diff --git a/zh-cn/device-dev/subsystems/figures/HUKS-architecture.png b/zh-cn/device-dev/subsystems/figures/HUKS-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..850fefe34024d7027545235ae9d7643c0632ed5c Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/HUKS-architecture.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md b/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md index 606c7df8fa0bcce378ca4e234d4df3b622f7e665..419d372c21be943264e5038fbc2ca5bda5c24037 100644 --- a/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md @@ -1,63 +1,81 @@ -# OpenHarmony通用密钥库开发指导 +# 通用密钥库设备开发指导 ## 概述 ### 功能简介 -HUKS(OpenHarmony Universal KeyStore)提供系统级的密钥管理能力,实现密钥全生命周期(生成、存储、使用、销毁)的管理和安全使用,满足生态应用和上层业务的诉求。其中,密钥的安全存储和安全使用环境是密钥安全最重要的约束,如对明文密钥的存储和使用不能出现在非安全环境中,需要保证在安全环境中使用(比如TEE,安全芯片等);本文档介绍了开发者在OpenHarmony HUKS架构的基础上适配安全存储和安全使用环境的步骤,以及如何去验证适配是否正确,以保证API接口的兼容。 +OpenHarmony通用密钥库系统(英文全称:Open**H**armony **U**niversal **K**ey**S**tore,以下简称HUKS)是OpenHarmony提供的系统级的密钥管理系统服务,提供密钥的全生命周期管理能力,包括密钥生成、密钥存储、密钥使用、密钥销毁等功能,以及对存储在HUKS中的密钥提供合法性证明。在HUKS的分层架构中,处于最底层的HUKS核心层(HUKS Core)承载着密钥管理核心功能,一般运行在设备硬件安全环境中(比如TEE、安全芯片等)。由于不同厂商硬件安全环境不同,HUKS核心层的实现方式也不尽相同,为了保证服务层及应用层架构和接口的一致性,HUKS核心层定义了一套HDI接口(硬件设备统一接口),以保证HUKS服务层调用HUKS核心层的兼容。本文基于HUKS HDI接口,提供HUKS核心层功能的开发指导。 -HUKS支持密钥全生命周期管理,包括以下特性: +HUKS核心层需要支持以下功能: -1. 密钥生成/导入 +1. 生成密钥 -2. 密钥存储 +2. 外部导入密钥 -3. 密钥使用(加解密、签名验签、密钥派生、密钥协商、哈希、密钥访问控制等) +3. 密钥操作(加密解密、签名验签、密钥派生、密钥协商、消息认证码等) -4. 密钥销毁 +4. 密钥访问控制 + +5. 密钥证明 + +6. 芯片平台公钥导出 ### 基本概念 -- 服务层(HUKS Service) +- **HUKS Core** + + HUKS核心组件,承载HUKS的核心功能,包括密钥的密码学运算、明文密钥的加解密、密钥访问控制等。一般运行在设备的安全环境中(如TEE、安全芯片等,不同的厂商有所不同),保证密钥明文不出HUKS Core。 - 承载密钥管理功能的一个独立的OpenHarmony Service附属于huks_service进程,HUKS Service并不直接处理密钥运算,依赖HUKS Core为上层提供服务。 + +- **密钥会话** -- 核心层(HUKS CORE) + 应用通过指定密钥别名,给当前操作的密钥建立一个会话,HUKS为每个会话生成一个全局唯一的句柄值来索引该会话。它的作用是缓存密钥使用期间的信息,包括操作数据、密钥信息、访问控制属性等。密钥操作一般需要经过**建立会话、传入数据和参数、结束会话(中止会话)** 三个阶段。 - 提供密钥管理服务的核心功能模块,需要保证该模块处于安全环境中且密钥全生命周期明文不出HUKS Core模块。 -- 可信执行环境(Trusted Execution Environment) +- **可信执行环境(Trusted Execution Environment)** 通过划分软件和硬件资源的方法构建一个安全区域,使得安全区域内部的程序和数据得到保护。这种划分会分隔出两个执行环境——可信执行环境和普通执行环境。每个执行环境有独立的内部数据通路和计算所需存储空间,保证可信执行环境里的信息不会向外泄露。普通执行环境的应用不能访问可信执行环境的资源,可信执行环境中的应用在没有授权的情况下也无法相互访问。 -- 三段式(Init-Update-Finish) - Init:初始化密钥操作数据。 +## 实现原理 + +HUKS采用分层架构,包含应用层、服务层、核心层(领域层),其中应用层主要对应用提供接口,服务层处理应用的密钥管理请求,进行密钥的密文管理、身份校验、密钥会话管理等,核心层提供密钥生成、密钥操作、密钥访问控制和密钥证明等核心功能。 + +**图1** HUKS分层架构图 + +![huks_architect](./figures/HUKS-architecture.png) - Update:分段操作数据并返回结果,或追加数据。 +## 约束与限制 - Finish:结束分段操作或追加数据,返回结果。 + - **密钥不出安全环境** -### 实现原理 + HUKS的核心特点是密钥全生命周期明文不出HUKS Core,在有硬件条件的设备上,如有TEE(Trusted Execution Environment)或安全芯片的设备,HUKS Core运行在硬件安全环境中。即使REE(Rich Execution Environment)环境被攻破,也能确保密钥明文也不会泄露。因此,HUKS直通式HDI API所有函数接口密钥材料数据只能是密文格式。 -以密钥的生成为例介绍HUKS Service与HUKS Core的通信过程,其他密钥操作类似: -上层应用通过密钥管理SDK调用到HUKS Service,HUKS Service再调用HUKS Core,HUKS Core会调用密钥管理模块生成密钥。之后HUKS Core使用基于RootKey派生的加密密钥对生成的密钥加密再传给Service侧,Service侧再以文件形式存储加密后的密钥。 +- **系统级安全加密存储** -![HUKS密钥生成流程图](figures/HUKS-GenerateKey1.png) + 必须基于设备根密钥加密业务密钥,在有条件的设备上,叠加用户口令加密保护密钥。 -### 约束与限制 +- **严格的访问控制** -* HUKS的实现需要在可信执行环境中实现,保证密钥管理和操作的可信可靠。 + 只有合法的业务才有权访问密钥,同时支持用户身份认证访问控制以支持业务的高安敏感场景下安全访问密钥的诉求。 +- **密钥的合法性证明** -* HuksHdiAttestKey返回的证书链应该按照业务证书、设备证书、CA证书和根证书的顺序组装,在每项证书之前还需要加上证书的长度。证书链组装完成后添加整个证书链的长度组装成Blob格式。证书的具体格式如要自己实现应与服务器侧解析的格式相对应。 + 业务提供硬件厂商级别的密钥的合法性证明,证明密钥没有被篡改,并确实存在于有硬件保护的HUKS Core中,以及拥有正确的密钥属性。 -![CertChain格式图](figures/HUKS-CertChain.png) +- **密钥材料格式** + + 导入/导出密钥时(包括密钥对、公钥、私钥),密钥材料的数据格式必须满足HUKS要求的格式,具体各个密码算法密钥材料见[密钥材料格式](../../application-dev/security/huks-appendix.md#密钥材料格式)。 -* 接口返回的密钥必须按照密钥存储态组装成KeyBlob,哪些接口需要遵循该限制请见[接口说明](#接口说明)。 +- **证书链格式** - KeyBlob存储密钥的同时存储它的属性,结构见下图。构造KeyBlob的示例请参见[hks_keyblob.c/HksBuildKeyBlob](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_keyblob.c)。 + AttestKey返回的证书链应该按照业务证书、设备证书、CA证书和根证书的顺序组装,在每项证书之前还需要加上证书的长度。证书链组装完成后添加整个证书链的长度组装成Blob格式。证书的具体格式如要自己实现应与服务器侧解析的格式相对应。 -![KeyBlob格式图](figures/HUKS-KeyBlob.png) + ![CertChain格式图](figures/HUKS-CertChain.png) + +- **KeyBlob格式** + 接口返回的密钥必须按照密钥存储态组装成KeyBlob,哪些接口需要遵循该限制请见[接口说明](#接口说明)。 + + ![KeyBlob格式图](figures/HUKS-KeyBlob.png) ## 开发指导 @@ -71,31 +89,47 @@ HUKS Core作为向应用提供密钥库能力的基础,包括密钥管理及 | 接口名 | 功能介绍 | 约束与限制 | 对应的js接口 | | ------------------------------------------------------------ | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------ | -| [HuksHdiModuleInit()](#hukshdimoduleinit) | HUKS Core的初始化。 | 无 | 无 | -| [HuksHdiRefresh()](#hukshdirefresh) | 刷新根密钥。 | 无 | 无 | -| [HuksHdiGenerateKey()](#hukshdigeneratekey) | 生成密钥。 | 出参要遵循KeyBlob格式 |generateKey(keyAlias: string, options: HuksOptions)| -| [HuksHdiImportKey()](#hukshdiimportkey) | 导入明文密钥。 | 出参要遵循KeyBlob格式 | importKey(keyAlias: string, options: HuksOptions)| -| [HuksHdiImportWrappedKey()](#hukshdiimportwrappedkey) |导入加密密钥。 | 出参要遵循KeyBlob格式 | importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions)| -| [HuksHdiExportPublicKey()](#hukshdiexportpublickey) | 导出公钥。 |无 | exportKey(keyAlias: string, options: HuksOptions) | -| [HuksHdiInit()](#hukshdiinit) | 三段式中的Init接口。 |无 | init(keyAlias: string, options: HuksOptions) | -| [HuksHdiUpdate()](#hukshdiupdate) | 三段式中的Update接口。 |签名验签时入参是原始数据 | update(handle: number, token?: Uint8Array, options: HuksOptions) | -| [HuksHdiFinish()](#hukshdifinish) | 三段式中的Finish接口。 |签名验签时入参是签名后数据 | finish(handle: number, options: HuksOptions) | -| [HuksHdiAbort()](#hukshdiabort) | 终止三段式。 |无 | abort(handle: number, options: HuksOptions) | -| [HuksHdiGetKeyProperties()](#hukshdigetkeyproperties) | 获取密钥属性。 |无 | getKeyProperties(keyAlias: string, options: HuksOptions)| -| [HuksHdiAttestKey()](#hukshdiattestkey) | 获取密钥证书。 |出参要遵循certChain格式 | attestKey(keyAlias: string, options: HuksOptions)| -| [HuksHdiExportChipsetPlatformPublicKey()](#hukshdiexportchipsetplatformpublickey) | 导出芯片平台级密钥对的公钥。 | 出参为ECC P256的x y轴值裸数据,各32字节 | 无 | -| [HuksHdiUpgradeKey()](#hukshdiupgradekey) | 升级密钥文件。 | 无 | 无 | +| [ModuleInit()](#moduleinit) | HUKS Core的初始化。 | 无 | 无 | +| [ModuleDestroy()](#moduledestroy) | HUKS Core的销毁。 | 无 | 无 |无 | 无 | +| [GenerateKey()](#generatekey) | 根据密码算法参数,生成密钥,并返回密文材料。 | 出参要遵循KeyBlob格式 |generateKey(keyAlias: string, options: HuksOptions)| +| [ImportKey()](#importkey) | 导入明文密钥,并返回密文材料。 | 出参要遵循KeyBlob格式 | importKey(keyAlias: string, options: HuksOptions)| +| [ImportWrappedKey()](#importwrappedkey) |导入加密密钥,并返回密文材料。 | 出参要遵循KeyBlob格式 | importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions)| +| [ExportPublicKey()](#exportpublickey) | 导出密钥对中的公钥。 |无 | exportKey(keyAlias: string, options: HuksOptions) | +| [Init()](#init) | 初始化密钥会话的接口,返回密钥会话句柄和令牌(可选)。 |无 | init(keyAlias: string, options: HuksOptions) | +| [Update()](#update) | 追加密钥操作数据。 |签名验签时入参是原始数据 | update(handle: number, token?: Uint8Array, options: HuksOptions) | +| [Finish()](#finish) | 结束密钥会话 |签名验签时入参是签名后数据 | finish(handle: number, options: HuksOptions) | +| [Abort()](#abort) | 取消密钥会话 |无 | abort(handle: number, options: HuksOptions) | +| [CheckKeyValidity()](#checkkeyvalidity) | 校验密钥材料(密文)的完整性 |无 | 无 | +| [AttestKey()](#attestkey) | 获取密钥证书。 |出参要遵循密钥证书链格式 | attestKey(keyAlias: string, options: HuksOptions)| +| [ExportChipsetPlatformPublicKey()](#exportchipsetplatformpublickey) | 导出芯片平台级密钥对的公钥。 | 出参为ECC P256的x y轴值裸数据,各32字节 | 无 | +| [UpgradeKey()](#upgradekey) | 升级密钥文件。 | 无 | 无 | +| [GenerateRandom()](#generaterandom) | 生成安全随机数 | 无 | 无 | +| [Encrypt()](#encrypt) | 加密 | 无 | 无 | +| [Decrypt()](#decrypt) | 解密 | 无 | 无 | +| [Sign()](#sign) | 签名 | 无 | 无 | +| [Verify()](#verify) | 验签 | 无 | 无 | +| [AgreeKey()](#agreekey) | 密钥协商 | 无 | 无 | +| [DeriveKey()](#derivekey) | 密钥派生 | 无 | 无 | +| [Mac()](#mac) | 消息认证码 | 无 | 无 | - - - -#### HuksHdiModuleInit +#### ModuleInit **接口描述** -HUKS Core的初始化,包括锁,加密算法库,authtoken key和根密钥。 +HUKS Core的初始化,一般用于初始化全局变量,比如全局线程锁,算法库,用于访问控制的AuthToken Key和根密钥。 **接口原型** -
int32_t HuksHdiModuleInit();
+int32_t ModuleInit(struct IHuks *self);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
int32_t HuksHdiRefresh();
+int32_t ModuleDestroy(struct IHuks *self);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
int32_t HuksHdiGenerateKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet, const struct HksBlob *keyIn, struct HksBlob *keyOut);
+int32_t GenerateKey(struct IHuks *self, const struct HuksBlob *keyAlias, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *keyIn, struct HuksBlob *encKeyOut);
- const struct HksBlob *keyAlias + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *keyAlias 将要生成的密钥的别名,要求: 1. keyAlias != null 2. keyAlias -> data != null - 3. keyAlias -> size != 0 + 3. keyAlias -> dataLen != 0
- const struct HksParamSet *paramSet + const struct HuksParamSet *paramSet 要生成密钥的参数
- const struct HksBlob *keyIn - 在agree key时使用 + const struct HuksBlob *keyIn + 可选,通过密钥协商或密钥派生生成密钥时,传原密钥材料
- struct HksBlob *keyOut - 出参,将paramset和生成的密钥存放在这里 + struct HuksBlob *encKeyOut + 出参,密钥密文材料,将密钥属性paramset和生成的密钥密文存放在这里,格式参考KeyBlob
int32_t HuksHdiImportKey(const struct HksBlob *keyAlias, const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+int32_t ImportKey(struct IHuks *self, const struct HuksBlob *keyAlias, const struct HuksBlob *key,
+ const struct HuksParamSet *paramSet, struct HuksBlob *encKeyOut);
- const struct HksBlob *msg - 将要导入的密钥的别名,要求: + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *keyAlias + 待导入的密钥的别名,要求: 1. keyAlias != null 2. keyAlias -> data != null - 3. keyAlias -> size != 0 + 3. keyAlias -> dataLen != 0
- const struct HksBlob *key - 要导入的密钥,要求: + const struct HuksBlob *key + 待导入的密钥明文材料,密钥材料格式见密钥材料格式,要求: 1. key != null 2. key -> data != null - 3. key -> size != 0 -
- const struct HksParamSet *paramSet - 导入密钥的参数 + 3. key -> dataLen != 0
- struct HksBlob *keyOut - 出参,将paramset和生成的密钥存放在这里 + const struct HuksParamSet *paramSet + 待导入密钥的参数
+ struct HuksBlob *encKeyOut + 出参,密钥密文材料,将密钥属性paramset和生成的密钥密文存放在这里,格式参考KeyBlob
int32_t HuksHdiImportWrappedKey(const struct HksBlob *keyAlias, const struct HksBlob *wrappingUsedkey, const struct HksBlob *wrappedKeyData, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+int32_t ImportWrappedKey(struct IHuks *self, const struct HuksBlob *wrappingKeyAlias,
+ const struct HuksBlob *wrappingEncKey, const struct HuksBlob *wrappedKeyData, const struct HuksParamSet *paramSet,
+ struct HuksBlob *encKeyOut);
- const struct HksBlob *KeyAlias - 将要导入的密钥的别名,要求: - 1. keyAlias != null - 2. keyAlias -> data != null - 3. keyAlias -> size != 0 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *wrappingKeyAlias + 用于做加密导入的密钥的别名(非导入密钥本身的别名),要求: + 1. wrappingKeyAlias != null + 2. wrappingKeyAlias -> data != null + 3. wrappingKeyAlias -> dataLen != 0
- const struct HksBlob *key + const struct HuksBlob *wrappingEncKey 要导入的密钥数据被加密时使用的密钥,要求: - 1. wrappingUsedkey != null - 2. wrappingUsedkey -> data != null - 3. wrappingUsedkey -> size != 0 + 1. wrappingEncKey != null + 2. wrappingEncKey -> data != null + 3. wrappingEncKey -> dataLen != 0
- const struct HksBlob *wrappedKeyData - 要导入的密钥的加密数据,要求: + const struct HuksBlob *wrappedKeyData + 要导入的密钥的密钥材料数据,格式参考加密导入材料格式,要求: 1. wrappedKeyData != null 2. wrappedKeyData -> data != null - 3. wrappedKeyData -> size != 0 + 3. wrappedKeyData -> dataLen != 0
- const struct HksParamSet *paramSet - 导入密钥的参数 + const struct HuksParamSet *paramSet + 待导入密钥的密钥属性
- struct HksBlob *keyOut - 出参,将paramset和生成的密钥存放在这里 + struct HuksBlob *encKeyOut + 导入密钥的密文材料,参考KeyBlob格式
int32_t HuksHdiExportPublicKey(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+int32_t ExportPublicKey(struct IHuks *self, const struct HuksBlob *encKey,
+ const struct HuksParamSet *paramSet, struct HuksBlob *keyOut);
- const struct HksBlob *key - 与要导出的公钥对应的私钥,要求: - 1. key != null - 2. key -> data != null - 3. key -> size != 0 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *encKey + 与要导出的公钥的密钥对材料,要求: + 1. encKey != null + 2. encKey -> data != null + 3. encKey -> dataLen != 0
- const struct HksParamSet *paramSet - 空参数 + const struct HuksParamSet *paramSet + 导出公钥的所需要的参数,默认为空
- struct HksBlob *keyOut + struct HuksBlob *keyOut 出参,存放导出的公钥
int32_t HuksHdiInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle, struct HksBlob *token);
+int32_t Init(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ struct HuksBlob *handle, struct HuksBlob *token);
- const struct HksBlob *key - Init操作的密钥,要求: - 1. key != null - 2. key -> data != null - 3. key -> size != 0 + struct IHuks *self + HUKS HDI函数指针结构体指针
- const struct HksParamSet *paramSet - Init操作的参数 + const struct HuksBlob *encKey + 待操作密钥的密文材料,要求: + 1. encKey != null + 2. encKey -> data != null + 3. encKey -> dataLen != 0
- struct HksBlob *handle - 三段式的句柄 + const struct HuksParamSet *paramSet + 初始化密钥会话的参数
- struct HksBlob *token - 存放安全访问控制的challenge + struct HuksBlob *handle + 出参,密钥会话的句柄,作为Update、Finish和Abort的入参,用于索引密钥会话 +
+ struct HuksBlob *token + 出参,存放密钥访问控制的认证令牌(按需)
int32_t HuksHdiUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);
+int32_t Update(struct IHuks *self, const struct HuksBlob *handle, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *inData, struct HuksBlob *outData);
- const struct HksBlob *handle - 三段式的句柄 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *handle + 密钥会话的句柄
- const struct HksParamSet *paramSet - Update操作的参数 + const struct HuksParamSet *paramSet + 追加操作的参数
- const struct HksBlob *inData - Update操作的输入 + const struct HuksBlob *inData + 追加操作的输入
- struct HksBlob *outData - Update操作的结果 + struct HuksBlob *outData + 追加操作的结果
int32_t HuksHdiFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);
+int32_t Finish(struct IHuks *self, const struct HuksBlob *handle, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *inData, struct HuksBlob *outData);
- const struct HksBlob *handle - 三段式的句柄 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *handle + 密钥会话的句柄
- const struct HksParamSet *paramSet - Finish操作的参数 + const struct HuksParamSet *paramSet + 最后一段操作的参数
- const struct HksBlob *inData - Finish操作的输入 + const struct HuksBlob *inData + 最后一段操作的输入
- struct HksBlob *outData - Finish操作的结果 + struct HuksBlob *outData + 密钥操作的结果
int32_t HuksHdiAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet);
+int32_t Abort(struct IHuks *self, const struct HuksBlob *handle, const struct HuksParamSet *paramSet);
- const struct HksBlob *handle - 三段式的句柄 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *handle + 密钥会话的句柄
- const struct HksParamSet *paramSet + const struct HuksParamSet *paramSet Abort操作的参数
int32_t HuksHdiGetKeyProperties(const struct HksParamSet *paramSet, const struct HksBlob *key);
+int32_t CheckKeyValidity(struct IHuks *self, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *encKey);
- const struct HksParamSet *paramSet - 空对象 + struct IHuks *self + HUKS HDI函数指针结构体指针
- const struct HksBlob *key - 要获取属性的密钥 + const struct HuksParamSet *paramSet + 用于校验密钥完整性接口的参数,默认传空 +
+ const struct HuksBlob *encKey + 待校验密钥完整性的密钥材料
int32_t (*HuksHdiAttestKey)(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *certChain);
+int32_t AttestKey(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ struct HuksBlob *certChain);
- const struct HksBlob *key - 要获取证书的密钥 + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *encKey + 要获取证书的密钥对材料密文
- const struct HksParamSet *paramSet - 获取证书操作的参数 + const struct HuksParamSet *paramSet + 获取密钥证书操作的参数,如challenge等
- struct HksBlob *certChain - 出参,存放证书 + struct HuksBlob *certChain + 出参,存放证书链,格式参考上述证书链格式
int32_t (*HuksHdiExportChipsetPlatformPublicKey)(const struct HksBlob *salt, enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey);
+int32_t ExportChipsetPlatformPublicKey(struct IHuks *self, const struct HuksBlob *salt,
+ enum HuksChipsetPlatformDecryptScene scene, struct HuksBlob *publicKey);
- const struct HksBlob *salt + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *salt 用来派生芯片平台密钥对时的派生因子
- enum HksChipsetPlatformDecryptScene scene + enum HuksChipsetPlatformDecryptScene scene 业务预期进行芯片平台解密的场景
- struct HksBlob *publicKey + struct HuksBlob *publicKey 出参为ECC P256的x y轴值裸数据,各32字节
int32_t (*HuksHdiUpgradeKey)(const struct HksBlob *oldKey, const struct HksParamSet *paramSet, struct HksBlob *newKey);
+int32_t UpgradeKey(struct IHuks *self, const struct HuksBlob *encOldKey, const struct HuksParamSet *paramSet,
+ struct HuksBlob *encNewKey);
- const struct HksBlob *oldKey + struct IHuks *self + HUKS HDI函数指针结构体指针 +
+ const struct HuksBlob *encOldKey 待升级的密钥文件数据
- const struct HksParamSet *paramSet + const struct HuksParamSet *paramSet 升级密钥文件数据的参数
- struct HksBlob *newKey + struct HuksBlob *newKey 出参,升级后的密钥文件数据
int32_t GenerateRandom(struct IHuks *self, const struct HuksParamSet *paramSet, struct HuksBlob *random);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksParamSet *paramSet + 待生成安全随机数的参数,如长度 +
+ struct HuksBlob *random + 出参,随机数 +
int32_t Sign(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, struct HuksBlob *signature);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksBlob *encKey + 用于签名的密钥对材料(密文) +
+ const struct HuksParamSet *paramSet + 用于签名的参数,如摘要模式 +
+ const struct HuksBlob *srcData + 用于签名的数据 +
+ struct HuksBlob *signature + 出参,数据签名 +
int32_t Verify(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, const struct HuksBlob *signature);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksBlob *encKey + 用于验签的密钥对材料(密文) +
+ const struct HuksParamSet *paramSet + 用于验签的参数,如摘要模式 +
+ const struct HuksBlob *srcData + 待验签的数据 +
+ const struct HuksBlob *signature + 用于验签的签名 +
int32_t Encrypt(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *plainText, struct HuksBlob *cipherText);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksBlob *encKey + 用于加密的密钥材料(密文) +
+ const struct HuksParamSet *paramSet + 用于加密的密钥参数,如密钥工作模式、填充模式等 +
+ const struct HuksBlob *plainText + 待加密的数据明文 +
+ const struct HuksBlob *cipherText + 加密后的数据密文 +
int32_t Decrypt(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *cipherText, struct HuksBlob *plainText);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksBlob *encKey + 用于解密的密钥材料(密文) +
+ const struct HuksParamSet *paramSet + 用于解密的密钥参数,如密钥工作模式、填充模式等 +
+ const struct HuksBlob *cipherText + 待解密的数据密文 +
+ const struct HuksBlob *plainText + 解密后的数据明文 +
int32_t AgreeKey(struct IHuks *self, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *encPrivateKey, const struct HuksBlob *peerPublicKey, struct HuksBlob *agreedKey);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksParamSet *paramSet + 用于协商的参数,如协商密钥的长度 +
+ const struct HuksBlob *encPrivateKey + 用于协商的密钥对材料(密文) +
+ const struct HuksBlob *peerPublicKey + 用于协商密钥对公钥(明文) +
+ struct HuksBlob *agreedKey + 出参,协商出的密钥明文 +
int32_t DeriveKey(struct IHuks *self, const struct HuksParamSet *paramSet, const struct HuksBlob *encKdfKey,
+ struct HuksBlob *derivedKey);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksParamSet *paramSet + 用于密钥派生的参数,如派生密钥的长度 +
+ const struct HuksBlob *encKdfKey + 用于派生的密钥材料(密文) +
+ struct HuksBlob *derivedKey + 出参,派生出的密钥(明文) +
int32_t Mac(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, struct HuksBlob *mac);
+
++ struct IHuks *self + HUKS HDI函数指针结构体指针 ++
+ const struct HuksBlob *encKey + 用于生成消息认证码的密钥材料(密文) +
+ const struct HuksParamSet *paramSet + 用于生成消息认证码的参数 +
+ const struct HuksBlob *srcData + 消息数据 +
+ struct HuksBlob *mac + 出参,消息认证码 +