鸿蒙开发：Universal Keystore Kit 密钥管理服务 密钥使用介绍及通用流程

密钥使用介绍及通用流程

为了实现对数据机密性、完整性等保护，可使用生成/导入的密钥，对数据进行密钥操作，比如：

• [加密解密]
• [签名验签]
• [密钥协商]
• [密钥派生]
• 开发前请熟悉鸿蒙开发指导文档 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

本章节提供了以上常用密钥操作的示例，这部分示例均没有设置二次身份访问控制，如设置了密钥访问控制请参考[密钥访问控制]用法。

加密/解密介绍及算法规格

在HUKS中已经有密钥，需要对一段数据加密或是解密，均可以使用HUKS完成加密/解密操作。

支持的算法

以下为密钥加密/解密支持的规格说明。

面向OpenHarmony的厂商适配密钥管理服务规格分为必选规格和可选规格。必选规格为所有厂商均支持的算法规格。而对于可选规格，厂商将基于实际情况决定是否实现，如需使用，请查阅具体厂商提供的说明，确保规格支持再使用。

建议开发者使用必选规格开发应用，可保证全平台兼容。

算法/分组模式/填充模式	备注	API级别	是否必选规格
AES/ECB/NoPadding AES/ECB/PKCS7	-	8+	否
AES/CBC/NoPadding AES/CBC/PKCS7 AES/CTR/NoPadding	IV参数必选	8+	是
AES/GCM/NoPadding	加密：Nonce参数必选 解密：Nonce、AEAD参数必选	8+	是
RSA/ECB/NoPadding RSA/ECB/PKCS1_V1_5 RSA/ECB/OAEP	OAEP填充模式支持的摘要算法：SHA256/SHA384/SHA512	8+	是
SM4/ECB/NoPadding SM4/ECB/PKCS7 SM4/CBC/PKCS7	CBC模式下 IV 参数必选, ECB模式不推荐使用	9+	否
SM4/CTR/NoPadding SM4/CBC/NoPadding SM4/CFB/NoPadding	IV 参数必选	12+	是
SM4/OFB/NoPadding	Nonce 参数必选	12+	是
SM2/-/NoPadding	摘要算法SM3	11+	是

签名/验签介绍及算法规格

为实现数据完整性保护和防抵赖，可使用生成/导入的密钥，对数据进行签名验签操作。

支持的算法

以下为密钥签名/验签支持的规格说明。

面向OpenHarmony的厂商适配密钥管理服务规格分为必选规格和可选规格。必选规格为所有厂商均支持的算法规格。而对于可选规格，厂商将基于实际情况决定是否实现，如需使用，请查阅具体厂商提供的说明，确保规格支持再使用。

建议开发者使用必选规格开发应用，可保证全平台兼容。

算法/摘要算法/填充模式	备注	API级别	是否必选规格
RSA/MD5/PKCS1_V1_5 RSA/SHA1/PKCS1_V1_5 RSA/SHA224/PKCS1_V1_5 RSA/SHA224/PSS	-	8+	否
RSA/SHA256/PKCS1_V1_5 RSA/SHA384/PKCS1_V1_5 RSA/SHA512/PKCS1_V1_5 RSA/SHA256/PSS RSA/SHA384/PSS RSA/SHA512/PSS	-	8+	是
RSA/NoDigest/PKCS1_V1_5	NoDigest需要指定TAG HuksKeyDigest.HUKS_DIGEST_NONE	9+	否
DSA/SHA1 DSA/SHA224 DSA/SHA256 DSA/SHA384 DSA/SHA512	-	8+	否
DSA/NoDigest	NoDigest需要指定TAG HuksKeyDigest.HUKS_DIGEST_NONE	9+	否
ECC/SHA1 ECC/SHA224	-	8+	否
ECC/SHA256 ECC/SHA384 ECC/SHA512	-	8+	是
ECC/NoDigest	NoDigest需要指定TAG HuksKeyDigest.HUKS_DIGEST_NONE	9+	否
ED25519/NoDigest	NoDigest需要指定TAG HuksKeyDigest.HUKS_DIGEST_NONE	8+	是
SM2/SM3	-	9+	是

密钥协商介绍及算法规格

为了避免恶意第三方获取到保密信息，密钥本身是不可以直接在设备间传输的。一般情况下，会采取密钥协商的方式，安全地在双方（或多方）间共享密钥。密钥协商只会传输密钥的公钥部分，私钥仍存留在设备内，以保护数据的安全性和机密性。

两台设备间进行密钥协商，双方各准备一个非对称密钥，并互换非对称密钥的公钥，以对端公钥与己端私钥协商出一个密钥，该密钥在两台设备相同。

支持的算法

以下为密钥协商支持的规格说明。

面向OpenHarmony的厂商适配密钥管理服务规格分为必选规格和可选规格。必选规格为所有厂商均支持的算法规格。而对于可选规格，厂商将基于实际情况决定是否实现，如需使用，请查阅具体厂商提供的说明，确保规格支持再使用。

建议开发者使用必选规格开发应用，可保证全平台兼容。

算法	备注	API级别	是否必选规格
ECDH	协商密钥类型为ECC类型密钥	8+	是
DH	-	8+	是
X25519	-	8+	是

密钥派生介绍及算法规格

在密码学中，密钥派生函数（Key derivation function，KDF）使用伪随机函数从诸如主密码或密码的秘密值中派生出一个或多个密钥。

支持的算法

以下为密钥派生支持的规格说明。

面向OpenHarmony的厂商适配密钥管理服务规格分为必选规格和可选规格。必选规格为所有厂商均支持的算法规格。而对于可选规格，厂商将基于实际情况决定是否实现，如需使用，请查阅具体厂商提供的说明，确保规格支持再使用。

建议开发者使用必选规格开发应用，可保证全平台兼容。

派生密钥是业务基于三段式得到密钥会话结果，业务可决定派生密钥是否由HUKS管理（即密钥不出TEE）亦或是业务独立管理。

算法/摘要	派生密钥的算法/长度	派生结果密钥可用算法/长度	API级别	是否必选规格
HKDF/SHA256	AES/192-256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是
HKDF/SHA384	AES/256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是
HKDF/SHA512	AES/256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是
PBKDF2/SHA256	AES/192-256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是
PBKDF2/SHA384	AES/256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是
PBKDF2/SHA512	AES/256	AES/128/192/256 HMAC/8-1024 SM4/128	8+	是HarmonyOS与OpenHarmony鸿蒙文档籽料：mau123789是v直接拿

通用开发流程

HUKS基于密钥会话来操作数据，使用密钥时基于以下流程：

1. （必选）初始化密钥会话[huks.initSession()]。 传入密钥别名和密钥操作参数，初始化一个密钥会话并获取会话句柄。其中密钥操作参数中必须包含对应密码算法所必须的参数，包括密码算法、密钥大小、密钥目的、工作模式、填充模式、散列模式、IV、Nonce、AAD等。
2. （可选）分段操作数据[huks.updateSession()]。 当使用的数据过大（超过100K）或是部分密码算法有要求时，需要对数据进行分段操作。否则可跳过此步骤。
3. （必选）结束密钥会话[huks.finishSession()]。 操作最后一段数据并结束密钥会话。

以上任一阶段中发生错误或不需要此次密钥操作数据，均需要取消会话[huks.abortSession()]，终止密钥的使用。

审核编辑 黄宇