通用密钥库装备开发引导
概述
功能简介
OpenHarmony通用密钥库体系（英文全称：OpenHarmony Universal KeyStore，以下简称HUKS）是OpenHarmony提供的体系级的密钥管理体系服务，提供密钥的全生命周期管理能力，包括密钥天生、密钥存储、密钥使用、密钥烧毁等功能，以及对存储在HUKS中的密钥提供合法性证明。在HUKS的分层架构中，处于最底层的HUKS核心层（HUKS Core)承载着密钥管理核心功能，一般运行在装备硬件安全环境中（比如TEE、安全芯片等）。由于不同厂商硬件安全环境不同，HUKS核心层的实现方式也不尽相同，为了保证服务层及应用层架构和接口的一致性，HUKS核心层界说了一套HDI接口（硬件装备统一接口），以保证HUKS服务层调用HUKS核心层的兼容。本文基于HUKS HDI接口，提供HUKS核心层功能的开发引导。
HUKS核心层需要支持以下功能：
- 天生密钥
- 外部导入密钥
- 密钥利用（加密解密、署名验签、密钥派生、密钥协商、消息认证码等）
- 密钥访问控制
- 密钥证明
- 芯片平台公钥导出
基本概念
- HUKS Core
HUKS核心组件，承载HUKS的核心功能，包括密钥的暗码学运算、明文密钥的加解密、密钥访问控制等。一般运行在装备的安全环境中（如TEE、安全芯片等，不同的厂商有所不同），保证密钥明文不出HUKS Core。
- 密钥会话
应用通过指定密钥别名，给当前利用的密钥建立一个会话，HUKS为每个会话天生一个全局唯一的句柄值来索引该会话。它的作用是缓存密钥使用期间的信息，包括利用数据、密钥信息、访问控制属性等。密钥利用一般需要经过建立会话、传入数据和参数、竣事会话（中止会话） 三个阶段。
- 可信执行环境（Trusted Execution Environment）
通过分别软件和硬件资源的方法构建一个安全地区，使得安全地区内部的程序和数据得到保护。这种分别会分隔出两个执行环境——可信执行环境和平凡执行环境。每个执行环境有独立的内部数据通路和计算所需存储空间，保证可信执行环境里的信息不会向外泄露。平凡执行环境的应用不能访问可信执行环境的资源，可信执行环境中的应用在没有授权的情况下也无法相互访问。
实现原理
HUKS接纳分层架构，包含应用层、服务层、核心层（范畴层），此中应用层重要对应用提供接口，服务层处理应用的密钥管理请求，进行密钥的密文管理、身份校验、密钥会话管理等，核心层提供密钥天生、密钥利用、密钥访问控制和密钥证明等核心功能。
图1 HUKS分层架构图
约束与限定
- 密钥不出安全环境
HUKS的核心特点是密钥全生命周期明文不出HUKS Core，在有硬件条件的装备上，如有TEE（Trusted Execution Environment)或安全芯片的装备，HUKS Core运行在硬件安全环境中。即使REE（Rich Execution Environment）环境被攻破，也能确保密钥明文也不会泄露。因此，HUKS直通式HDI API全部函数接口密钥材料数据只能是密文格式。
- 体系级安全加密存储
必须基于装备根密钥加密业务密钥，在有条件的装备上，叠加用户口令加密保护密钥。
- 严格的访问控制
只有合法的业务才有权访问密钥，同时支持用户身份认证访问控制以支持业务的高安敏感场景下安全访问密钥的诉求。
- 密钥的合法性证明
业务提供硬件厂商级别的密钥的合法性证明，证明密钥没有被篡改，并确实存在于有硬件保护的HUKS Core中，以及拥有准确的密钥属性。
- 密钥材料格式
导入/导出密钥时（包括密钥对、公钥、私钥），密钥材料的数据格式必须满意HUKS要求的格式。
- 证书链格式
AttestKey返回的证书链应该按照业务证书、装备证书、CA证书和根证书的顺序组装，在每项证书之前还需要加上证书的长度。证书链组装完成后添加整个证书链的长度组装成Blob格式。证书的具体格式如要自己实现应与服务器侧解析的格式相对应。
- KeyBlob格式 接口返回的密钥必须按照密钥存储态组装成KeyBlob，哪些接口需要遵循该限定请见[接口阐明]。
开发引导
场景先容
HUKS Core作为向应用提供密钥库能力的基础，包括密钥管理及密钥的暗码学利用等功能。假如想要使用自己的实现更换HUKS Core，需要实现以下接口。
接口阐明
表1 接口功能先容
接口名 功能先容 约束与限定 对应的js接口 [ModuleInit()] HUKS Core的初始化。 无 无 [ModuleDestroy()] HUKS Core的烧毁。 无 无 [GenerateKey()] 根据暗码算法参数，天生密钥，并返回密文材料。 出参要遵循KeyBlob格式 generateKey(keyAlias: string, options: HuksOptions) [ImportKey()] 导入明文密钥，并返回密文材料。 出参要遵循KeyBlob格式 importKey(keyAlias: string, options: HuksOptions) [ImportWrappedKey()] 导入加密密钥，并返回密文材料。 出参要遵循KeyBlob格式 importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) [ExportPublicKey()] 导出密钥对中的公钥。 无 exportKey(keyAlias: string, options: HuksOptions) [Init()] 初始化密钥会话的接口，返回密钥会话句柄和令牌（可选）。 无 init(keyAlias: string, options: HuksOptions) [Update()] 追加密钥利用数据。 署名验签时入参是原始数据 update(handle: number, token?: Uint8Array, options: HuksOptions) [Finish()] 竣事密钥会话 署名验签时入参是署名后数据 finish(handle: number, options: HuksOptions) [Abort()] 取消密钥会话 无 abort(handle: number, options: HuksOptions) [CheckKeyValidity()] 校验密钥材料（密文）的完整性 无 无 [AttestKey()] 获取密钥证书。 出参要遵循密钥证书链格式 attestKey(keyAlias: string, options: HuksOptions) [ExportChipsetPlatformPublicKey()] 导出芯片平台级密钥对的公钥。 出参为ECC P256的x y轴值裸数据，各32字节 无 [UpgradeKey()] 升级密钥文件。 无 无 [GenerateRandom()] 天生安全随机数 无 无 [Encrypt()] 加密 无 无 [Decrypt()] 解密 无 无 [Sign()] 署名 无 无 [Verify()] 验签 无 无 [AgreeKey()] 密钥协商 无 无 [DeriveKey()] 密钥派生 无 无 [Mac()] 消息认证码 无 无 <hr> ModuleInit
接口形貌
HUKS Core的初始化，一般用于初始化全局变量，比如全局线程锁，算法库，用于访问控制的AuthToken Key和根密钥。
接口原型
- int32_t ModuleInit(struct IHuks *self);
- struct IHuks *self
- HUKS HDI函数指针结构体指针
-
- HKS_SUCCESS：乐成，值为0，下同
- 其他：失败，值为负数，下同
<hr> ModuleDestroy
接口形貌
HUKS Core的烧毁，一般用于开释全局变量，包括锁，烧毁内存中的AuthToken Key和根密钥等。
接口原型
- int32_t ModuleDestroy(struct IHuks *self);
- struct IHuks *self
- HUKS HDI函数指针结构体指针
-
<hr> GenerateKey
接口形貌
根据密钥属性paramSet天生密钥。
接口原型
- int32_t GenerateKey(struct IHuks *self, const struct HuksBlob *keyAlias, const struct HuksParamSet *paramSet,
- const struct HuksBlob *keyIn, struct HuksBlob *encKeyOut);
- struct IHuks *self
- HUKS HDI函数指针结构体指针
-
- const struct HuksBlob *keyAlias 将要天生的密钥的别名，要求： 1. keyAlias != null
|
