源代码：

https://android.googlesource.com/trusty/app/keymaster/

 git clone https://android.googlesource.com/trusty/app/keymaster

 https://wenku.baidu.com/view/34433fa1be1e650e53ea9927.html

 

KeyStore API: 
test 检测密钥是否可用 
get 按名称查找密钥并返回 
insert 保存一个密钥，如果有同名的覆盖 
del 删除给定名称的密钥 
exist 检测给定名称的密钥是否存在 
saw 列出当前所能访问的密钥 
reset 清空密钥保存区 
password 修改KeyStore的密码 
lock 锁定KeyStore 
unlock 解锁KeyStore 

zero 检测KeyStore中是否为空

UpgradeKey

为了使密钥升级到系统映像的新操作系统版本和补丁程序级别，Android 7.1 向 HAL 添加了 upgradeKey 方法：

Keymaster 3

    upgradeKey(vec keyBlobToUpgrade, vec upgradeParams)

        generates(ErrorCode error, vec upgradedKeyBlob);

Keymaster 2

keymaster_error_t (*upgrade_key)(const struct keymaster2_device* dev,

    const keymaster_key_blob_t* key_to_upgrade,

    const keymaster_key_param_set_t* upgrade_params,

    keymaster_key_blob_t* upgraded_key);

·        dev 是设备结构

·        keyBlobToUpgrade 是需要进行升级的密钥

·        upgradeParams 是升级密钥所需的参数。这将包括 Tag::APPLICATION_ID 和Tag::APPLICATION_DATA，

如果在密钥生成期间提供了这两个参数，则它们是解密密钥 Blob 所必需的参数。

·        upgradedKeyBlob 是输出参数，用于返回新的密钥 Blob。

注意：Keymaster 3 移除了 Keymaster 2 方法 configure。之前通过 configure 提供给 Keymaster HAL

的信息已在系统属性文件中提供，制造商实现会在启动期间读取这些文件。

 

要实现版本绑定，Keymaster TA需要以一种方式安全接收当前的操作系统版本和补丁程序级别（版本信息），

并确保所接收的信息与运行系统的相关信息严格匹配。

为了确保将版本信息安全传递到 TA，启动映像标头中添加了 os_version field。启动映像构建脚本会自动

填充此字段。原始设备制造商 (OEM) 和Keymaster TA 实现人员需要相互协作来修改设备引导加载程序，

以便从启动映像中提取版本信息，并在非安全系统启动之前将其传递到 TA。这样可确保攻击者无法干扰

向 TA 提供版本信息。

此外，您还需要确保系统映像与启动映像具有相同的版本信息。为此，Keymaster HAL 中添加了 configure 方法：

keymaster_error_t (*configure)(const struct keymaster2_device* dev,

        const keymaster_key_param_set_t* params);

params 参数包含 Tag::OS_VERSION 和 Tag::OS_PATCHLEVEL。Keymaster2 客户端会在打开 HAL 之后、调用任何其

他方法之前调用此方法。如果在调用 configure 之前调用了任何其他方法，TA 会返回 ErrorCode::KEYMASTER_NOT_CONFIGURED。

在设备启动后首次调用 configure 时，该方法应该验证所提供的版本信息是否与引导加载程序提供的版本

信息一致。如果版本信息不一致，则 configure 会返回 ErrorCode::INVALID_ARGUMENT，所有其他 

Keymaster 方法会继续返回 ErrorCode::KEYMASTER_NOT_CONFIGURED。如果信息一致，configure 会返

回 ErrorCode::OK，其他 Keymaster 方法开始正常运行。

对 configure 的后续调用与首次调用返回的值相同，而且不会更改 Keymaster 的状态。请注意，此过程会要

求所有 OTA 同时更新系统映像和启动映像；为了使版本信息保持同步，不能单独更新这两种映像。

由于将调用 configure 的系统的内容需要经过验证，攻击者可利用这一短暂的窗口期机会来破坏系统映像，

并强制其提供与启动映像一致的版本信息，但这并不是系统的真实版本信息。不过，对启动映像的

验证、对系统映像内容的 dm-verity 验证以及在系统启动早期调用 configure 这三项相结合，会让攻击者很难

利用这个机会

客户端绑定

客户端绑定（即将密钥与特定客户端应用相关联）是通过一个可选客户端 ID 和一些可选

客户端数据（分别是 TAG::APPLICATION_ID 和 TAG::APPLICATION_DATA）实现的。Keystore 会将这些值视为不透明

Blob，仅用于确保密钥生成/导入期间存在的 Blob 在每次使用相应密钥时都存在，并且每个字节都完全相同。

客户端绑定数据不是由 Keymaster 返回的。调用程序必须知道这些数据，才能使用相应密钥。

此功能未提供给应用。

信任根绑定

Keystore 要求将密钥绑定到一个信任根。信任根是在启动期间提供给 Keymaster 安全硬件的一个位串

（最好由引导加载程序提供）。该位串会以加密形式绑定到由 Keymaster 管理的每个密钥。

信任根包含一个公钥，该公钥用于验证启动映像上的签名和设备的锁定状态。如果该公钥被更改了

（以允许使用不同的系统映像），或锁定状态发生了变化，之前的系统创建的受 Keymaster 保护的所有密钥

都无法再使用，除非之前的信任根已恢复并且通过相应密钥签名的系统已启动。这是为了确保由攻击者安装的

操作系统无法使用 Keymaster 密钥，从而提高由软件强制执行的密钥访问控制所发挥的作用。

用途

密钥有一组关联的用途，这些用途以一个或多个带有 TAG::PURPOSE 标记（用于定义可以如何使用相应密钥）的授权

条目表示。这些用途是：

·        KeyPurpose::ENCRYPT

·        KeyPurpose::DECRYPT

·        KeyPurpose::SIGN

·        KeyPurpose::VERIFY

任意密钥都可以具有这些用途任意组合。请注意，有些组合会带来安全问题。例如，如果某个 RSA 密钥可用于加

密和签名，那么能够诱使系统解密任意数据的攻击者就可以利用该密钥来生成签名。

导入和导出

Keymaster 仅支持以 X.509 格式导出公钥，并支持：

·        以未采用密码加密的 DER 编码 PKCS#8 格式导入公钥和私钥对

·        以原始字节形式导入对称密钥

为了确保导入的密钥可与安全生成的密钥区分开来，相应密钥授权列表中会包含 TAG::ORIGIN。例如，如果密

钥是在安全硬件中生成的，hw_enforced 密钥特性列表中将有值为KeyOrigin::GENERATED 的 TAG::ORIGIN；如果密钥

是导入到安全硬件中的，值将为KeyOrigin::IMPORTED。

用户身份验证

安全的 Keymaster实现不会实现用户身份验证，但会依赖于其他实现用户身份验证的可信应用。对于这些

应用实现的接口，请参阅 Gatekeeper 页面。

用户身份验证要求是通过两组标记指定的。第一组用于指明哪些用户可以使用相应密钥：

·        TAG::ALL_USERS 表示所有用户都可以使用相应密钥。如果该标记存在，则 TAG::USER_ID 和 TAG::USER_SECURE_ID 不存在。

·        TAG::USER_ID 有一个数字值，用于指定已获授权用户的 ID。请注意，此值是 Android 用户ID

（适用于多用户环境）而非应用 UID，且仅由非安全软件强制执行。如果该标记存在，则 TAG::ALL_USERS 不存在。

·        TAG::USER_SECURE_ID 有一个64 位数字值，用于指定安全用户 ID。要在安全身份验证令牌中提供该 ID，

才能获得使用相应密钥的授权。在重复使用此标记的情况下，只要在安全身份验证令牌中提供了此标记的任

何一个值，即可使用相应密钥。

第二组用于指明是否需要对用户进行身份验证以及何时进行验证。如果不存在以下任一标记，但

有 TAG::USER_SECURE_ID，则表示每次使用相应密钥时均需要经过身份验证。

·        NO_AUTHENTICATION_REQUIRED 表示无需进行任何用户身份验证，不过仍只有以通过TAG::USER_ID 指定的用

户身份运行的应用可以使用相应密钥。

·        TAG::AUTH_TIMEOUT 是一个数字值，用于指定用户身份验证需要多新（以秒数计）才能授权使用相应

密钥。此标记仅适用于私钥/密钥操作。公钥操作不需要进行身份验证。设备重新启动后超时将会失效；

设备重新启动后，所有密钥的状态均为“从未经过身份验证”。可以将超时设为一个较大的值，以指明每次

设备启动后只需进行一次身份验证（2^32 秒约为136 年；Android设备的重新启动时间间隔一般不会超过该值）