![](https://s5-media.51cto.com/ost/pc/static/noavatar.gif)
HarmonyOS Developer 通用密钥库开发指导
密钥访问控制
HUKS提供了全面完善的密钥访问控制能力,确保存储在HUKS中的密钥被合法正确的访问。
首先,业务只能访问属于自己的密钥,即只能访问通过HUKS生成或导入的密钥。
其次,支持密钥的用户身份认证访问控制,对于高安敏感的业务密钥,需要在使用密钥的时候,再次要求用户即时的验证锁屏密码或生物特征,验证通过后,才能使用业务密钥。
除此之外,HUKS还支持严格限制密钥的使用用途,如支持只允许AES密钥进行加密解密,只允许RSA密钥进行签名验签。
用户身份认证访问控制
生成或导入密钥时,可以指定密钥必须经过用户身份认证后才能使用。您可以指定用于解锁设备锁屏的凭据(指纹、人脸)的子集进行身份认证。在生成/导入密钥后,即使应用进程被攻击也不会导致未经用户授权的密钥访问,一般用于高敏感且高级别安全保护的场景,比如免密登录、免密支付、自动填充密码保护场景。
除用户身份认证外,应用还须将密钥的授权访问类型(即失效条件)设置为以下两种类型之一:
- 清除锁屏密码后密钥永久无效。设置此模式的前提是当前用户已经设置了锁屏密码,在生成/导入密钥后,一旦清除了锁屏密码,此类密钥将永久失效。注意,修改密码不会导致失效情况发生。此模式适合那些需要锁屏密码授权访问或用户强相关的数据保护的场景。
- 用户新录入生物特征后永久无效。此模式需要当前用户至少录入了一个生物特征(如指纹)才能生效,在生成/导入密钥后,一旦录入新的生物特征,这些密钥将永久失效。注意,仅删除生物特征不会导致失效情况发生。如果您不希望新录入的生物特征后,用户还可以授权访问原有数据(密钥保护的数据),那么可以使用此模式,如免密登录,免密支付等场景。
此外,为了保证密钥使用时用户认证结果的有效性(不可重放),HUKS支持挑战值校验:在身份认证前,需要从HUKS获取挑战值(调用huks.initSession()返回的HuksSessionHandle中)传给用户身份认证方法(userIAM_userAuth.getAuthInstance),然后在密钥操作时校验认证令牌的挑战值。
开发流程
设置了二次用户身份认证的密钥,需要先初始化密钥会话并获取挑战值,然后将HUKS生成的挑战值传至用户身份认证方法进行用户身份认证,认证通过后获取一个认证令牌,将认证令牌传至HUKS进行密钥操作。
接口说明
- 生成或导入密钥时,在密钥属性集中需指定三个参数:用户认证类型HuksUserAuthType、授权访问类型HuksAuthAccessType、挑战值类型HuksChallengeType。
表3用户认证类型:两种类型的子集
名称 | 值 | 说明 |
HUKS_USER_AUTH_TYPE_FINGERPRINT | 0x0001 | 用户认证类型为指纹,允许和人脸同时设置 |
HUKS_USER_AUTH_TYPE_FACE | 0x0002 | 用户认证类型为人脸 ,允许和指纹同时设置 |
表4 安全访问类型:二选一
名称 | 值 | 说明 |
HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | 1 | 清除锁屏密码后密钥无法访问。 |
HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | 2 | 新录入生物特征后密钥无法访问,用户认证类型须包含生物认证类型。 |
表5 挑战值类型:三选一
名称 | 值 | 说明 |
HUKS_CHALLENGE_TYPE_NORMAL | 0 | 普通类型,每次密钥的使用需要独立的一次用户认证 |
HUKS_CHALLENGE_TYPE_CUSTOM | 1 | 自定义类型,支持和多个密钥共享一次用户认证 |
HUKS_CHALLENGE_TYPE_NONE | 2 | 无挑战值类型,用户认证时不需要挑战值 |
注意
当指定挑战值类型为HUKS_CHALLENGE_TYPE_NONE 时,不需要传递挑战值,但是存在新的限制:在用户身份认证后,一段时间内允许访问该密钥,超时后不能访问,需要重新认证才能访问。因此应用需要额外指定超时时间HUKS_TAG_AUTH_TIMEOUT属性(最大60秒)。
- 使用密钥时,先初始化密钥会话,然后根据密钥生成/导入阶段指定的挑战值类型属性是否需要获取挑战值,或组装新的挑战值。
- 表6使用密钥的接口介绍
接口名 | 描述 |
initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksSessionHandle>) : void | 初始化密钥会话,获取挑战值 |
updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void | 分段操作数据,传递认证令牌 |
finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void | 结束密钥会话,传递认证令牌 |
开发步骤
- 生成密钥并指定指纹访问控制和相关属性
- 初始化密钥会话获取挑战值并发起指纹认证获取认证令牌
- 传入认证令牌进行数据操作
常见问题
- Cannot find name 'huks'.
不能找到huks,使用了接口函数但没导入security.huks.d.ts,添加import huks from '@ohos.security.huks';即可。 - Property 'finishSession' does not exist on type 'typeof huks'. Did you mean 'finish'?
不能在huks库中找到finishSession,finishSession是API9版本的,请更新SDK版本或替换新版本的security.huks.d.ts文件。
通用密钥库密码算法规格
支持的算法类型及参数组合
导入\生成密钥规格
算法 | API级别 | 支持的密钥长度 |
AES | 8+ | 128、192、256 |
RSA | 8+ | 2048、3072、4096 |
HMAC | 8+ | 8-4096(含),必须是8的倍数 |
ECC | 8+ | 256、384、521 |
ED25519 | 8+ | 256 |
X25519 | 8+ | 256 |
SM2 | 9+ | 256 |
SM3 | 9+ | 256 |
SM4 | 9+ | 128 |
加密解密
算法 | API级别 | 备注 |
AES/CBC/NoPadding AES/CTR/NoPadding AES/GCM/NoPadding AES/CBC/PKCS7 | 8+ | 1. CBC\ECB\CTR模式IV参数必选 2. GCM模式下Nonce、AAD、AEAD参数必选 |
RSA/ECB/NoPadding RSA/ECB/PKCS1_V1_5 RSA/ECB/OAEP | 8+ | - |
SM4/CTR/NoPadding SM4/CBC/NoPadding | 9+ | - |
签名验签
算法 | API级别 | 备注 |
RSA/SHA256/PKCS1_V1_5 RSA/SHA384/PKCS1_V1_5 RSA/SHA512/PKCS1_V1_5 RSA/SHA256/PSS RSA/SHA384/PSS | 8+ | - |
ECC/SHA256 ECC/SHA384 ECC/SHA512 | 8+ | - |
ED25519 | 8+ | - |
SM2/SM3 | 9+ | - |
密钥协商
算法 | API级别 | 备注 |
ECDH | 8+ | 协商密钥类型为ECC类型密钥 |
X25519 | 8+ | - |
密钥派生
算法 | API级别 | 派生密钥及长度 | 备注 |
HKDF/SHA256 HKDF/SHA384 HKDF/SHA512 | 8+ | 算法:AES、HMAC、SM4 长度:256、384、512 | 派生出的密钥可以存储到HUKS或者直接返回明文 |
PBKDF2/SHA256 PBKDF2/SHA384 PBKDF2/SHA512 | 8+ | 算法:AES、HMAC、SM4 长度:256、384、512 | 派生出的密钥可以存储到HUKS或者直接返回明文 |
密钥材料格式
针对不同密码算法的密钥对、公钥、私钥,HUKS定义了一套密钥材料格式。
密钥对材料
密钥对材料 = 密钥对材料Header + 密钥对材料原文
以RSA密钥为例,应用需要申请一个Uint8Array,按照RSA密钥对材料内存格式,将各个变量赋值到对应的位置:
图4 RSA密钥材料内存结构
其中,密钥算法的值取自枚举类HuksKeyAlg。
- RSA密钥对材料格式:
密钥算法 | 密钥大小 | 模数n长度Ln | 公钥指数e长度Le | 私钥指数d长度Ld | n | e | d |
4字节 | 4字节 | 4字节 | 4字节 | 4字节 | Ln字节 | Le字节 | Ld字节 |
- ECC密钥对材料格式:
密钥算法 | 密钥大小 | 坐标x长度Lx | 坐标y长度Ly | 坐标z长度Lz | x | y | z |
4字节 | 4字节 | 4字节 | 4字节 | 4字节 | Lx字节 | Ly字节 | Lz字节 |
- DSA密钥对材料格式:
密钥算法 | 密钥大小 | 私钥x长度Lx | 公钥y长度Ly | 素数p长度Lp | 素因子q长度Lq | g长度Lg | x | y | p | q | g |
4字节 | 4字节 | 4字节 | 4字节 | 4字节 | 4字节 | 4字节 | Lx字节 | Ly字节 | Lp字节 | Lq字节 | Lg字节 |
- DH密钥对材料格式:
密钥算法 | 密钥大小 | 公钥pk长度Lpk | 私钥sk长度Lsk | 保留字段 | pk | sk |
4字节 | 4字节 | 4字节 | 4字节 | 4字节 | Lpk字节 | Lsk字节 |
- Curve25519密钥对材料格式:
密钥算法 | 密钥大小 | 公钥pk长度Lpk | 私钥sk长度Lsk | 保留字段 | pk | sk |
4字节 | 4字节 | 4字节 | 4字节 | 4字节 | Lpk字节 | Lsk字节 |
公钥材料
在公钥导出/导入时,密钥材料采用标准的X.509规范的DER格式封装。
如下是一个DER编码的ECC公钥:
私钥材料
复用密钥对的材料格式,私钥材料的封装是把密钥对材料Header中的公钥部分的长度字段置0,同时密钥对材料原文部分拼接私钥材料即可。
私钥材料 = 密钥对材料Header + 私钥材料原文
以RSA私钥材料为例:
![](https://s5-media.51cto.com/ost/pc/static/noavatar.gif)