Android Q 10.1 KeyMaster源码分析(二)

写在之前

这两篇文章是我2021年3月初看KeyMaster的笔记，本来打算等分析完KeyMaster和KeyStore以后再一起做成一系列贴出来，后来KeyStore的分析中断了，这一系列的文章就变得遥遥无期。今天群里聊天时有个朋友问到文章的事，我觉得可能多少还有些价值，做了一些脱敏后发出来，希望对你阅读KeyMaster代码有些帮助，尤其阅读代码的方法，如何从0开始查找，分析代码。

相关文章：
Android Q 10.1 KeyMaster源码分析(一) - KeyMaster相关目录和文件
Android Q 10.1 KeyMaster源码分析(二) - 各家方案的实现

本文主要分析有哪些模块，分析完才发现KeyMaster本身的代码比较底层，一般主要关注接口就好，所以本篇文章最重要的就是关于KeyMaster结构的图了，一眼就可以看到 KeyMaster 从 0~4的各个版本之间的差别，其中的灰色是已经移除的接口。

1. 文档

关于keymaster的文档主要有两个:

Android官方文档
- https://source.android.com/security/keystore
- https://source.android.com/security/keystore/implementer-ref
Android本地HIDL接口定义文件中的注释
- hardware/interfaces/keymaster/4.0/IKeymasterDevice.hal

2. keymaster结构对比

keymaster 0~4的功能结构对比:

keymaster 0: hardware/libhardware/include/hardware/keymaster0.h
keymaster 1: hardware/libhardware/include/hardware/keymaster1.h
keymaster 2: hardware/libhardware/include/hardware/keymaster2.h
keymaster 3: hardware/interfaces/keymaster/3.0/IKeymasterDevice.hal
keymaster 4: hardware/interfaces/keymaster/4.0/IKeymasterDevice.hal

图示颜色说明：

灰色是已经移除的接口，可见早起KeyMaster0, KeyMaster1中的多个接口已经被移除了
蓝色的部分是从KeyMaster 1~4 各代之间统一的接口，
绿色是KeyMaster3 开始新增接口，
橙色是KeyMaster4新增接口，
紫色是KeyMaster3有，但是KeyMaster4不再保留的接口。

3. `system\keymaster`下的模块

根据文件system/keymaster/Android.bp, 这下面的代码主要分4个部分:

libkeymaster_messages

与AndroidKeymaster implementation通信

  "android_keymaster/android_keymaster_messages.cpp","android_keymaster/android_keymaster_utils.cpp","android_keymaster/authorization_set.cpp","android_keymaster/keymaster_tags.cpp","android_keymaster/logger.cpp","android_keymaster/serializable.cpp","android_keymaster/keymaster_stl.cpp",

libkeymaster_portable

包含了keymaster除具体的实现环境KeymasterContext之外，所需要实现的一切功能

"android_keymaster/android_keymaster.cpp",
"android_keymaster/android_keymaster_messages.cpp",
"android_keymaster/android_keymaster_utils.cpp",
"android_keymaster/authorization_set.cpp",
"android_keymaster/keymaster_enforcement.cpp",
"android_keymaster/keymaster_stl.cpp",
"android_keymaster/keymaster_tags.cpp",
"android_keymaster/logger.cpp",
"android_keymaster/operation.cpp",
"android_keymaster/operation_table.cpp",
"android_keymaster/serializable.cpp",
"key_blob_utils/auth_encrypted_key_blob.cpp",
"key_blob_utils/integrity_assured_key_blob.cpp",
"key_blob_utils/ocb.c",
"key_blob_utils/ocb_utils.cpp",
"key_blob_utils/software_keyblobs.cpp",
"km_openssl/aes_key.cpp",
"km_openssl/aes_operation.cpp",
"km_openssl/asymmetric_key.cpp",
"km_openssl/asymmetric_key_factory.cpp",
"km_openssl/attestation_record.cpp",
"km_openssl/attestation_utils.cpp",
"km_openssl/block_cipher_operation.cpp",
"km_openssl/ckdf.cpp",
"km_openssl/ec_key.cpp",
"km_openssl/ec_key_factory.cpp",
"km_openssl/ecdsa_operation.cpp",
"km_openssl/ecies_kem.cpp",
"km_openssl/hkdf.cpp",
"km_openssl/hmac.cpp",
"km_openssl/hmac_key.cpp",
"km_openssl/hmac_operation.cpp",
"km_openssl/iso18033kdf.cpp",
"km_openssl/kdf.cpp",
"km_openssl/nist_curve_key_exchange.cpp",
"km_openssl/openssl_err.cpp",
"km_openssl/openssl_utils.cpp",
"km_openssl/rsa_key.cpp",
"km_openssl/rsa_key_factory.cpp",
"km_openssl/rsa_operation.cpp",
"km_openssl/software_random_source.cpp",
"km_openssl/symmetric_key.cpp",
"km_openssl/triple_des_key.cpp",
"km_openssl/triple_des_operation.cpp",
"km_openssl/wrapped_key.cpp",

libsoftkeymasterdevice

纯软件的keymaster HAL层实现

当硬件层不支持hardware keymaster时，keystore会转而使用这里的纯软件的keymaster

"android_keymaster/keymaster_configuration.cpp",
"legacy_support/ec_keymaster0_key.cpp",
"legacy_support/ec_keymaster1_key.cpp",
"legacy_support/ecdsa_keymaster1_operation.cpp",
"legacy_support/keymaster0_engine.cpp",
"legacy_support/keymaster1_engine.cpp",
"legacy_support/rsa_keymaster0_key.cpp",
"legacy_support/rsa_keymaster1_key.cpp",
"legacy_support/rsa_keymaster1_operation.cpp",
"legacy_support/keymaster1_legacy_support.cpp",
"contexts/soft_attestation_cert.cpp",
"contexts/soft_keymaster_context.cpp",
"contexts/pure_soft_keymaster_context.cpp",
"contexts/soft_keymaster_device.cpp",
"km_openssl/soft_keymaster_enforcement.cpp",
"contexts/soft_keymaster_logger.cpp",

libpuresoftkeymasterdevice

"android_keymaster/keymaster_configuration.cpp",
"contexts/soft_attestation_cert.cpp",
"contexts/pure_soft_keymaster_context.cpp",
"contexts/soft_keymaster_logger.cpp",
"km_openssl/soft_keymaster_enforcement.cpp",

libkeymaster3device

"legacy_support/keymaster_passthrough_key.cpp",
"legacy_support/keymaster_passthrough_engine.cpp",
"legacy_support/keymaster_passthrough_operation.cpp",
"contexts/keymaster1_passthrough_context.cpp",
"contexts/keymaster2_passthrough_context.cpp",
"ng/AndroidKeymaster3Device.cpp",
"android_keymaster/keymaster_configuration.cpp",
"legacy_support/ec_keymaster0_key.cpp",
"legacy_support/ec_keymaster1_key.cpp",
"legacy_support/ecdsa_keymaster1_operation.cpp",
"legacy_support/keymaster0_engine.cpp",
"legacy_support/keymaster1_engine.cpp",
"legacy_support/keymaster1_legacy_support.cpp",
"legacy_support/rsa_keymaster0_key.cpp",
"legacy_support/rsa_keymaster1_key.cpp",
"legacy_support/rsa_keymaster1_operation.cpp",

libkeymaster4

"legacy_support/keymaster_passthrough_key.cpp",
"legacy_support/keymaster_passthrough_engine.cpp",
"legacy_support/keymaster_passthrough_operation.cpp",
"ng/AndroidKeymaster4Device.cpp",
"android_keymaster/keymaster_configuration.cpp",

4. keymaster 4.0实现

针对手上的代码，尝试搜索

android-q-ab2/src-km$ grep -Rn CreateKeymasterDevice system hardware vendor/broadcom/ device/
system/keymaster/ng/include/AndroidKeymaster3Device.h:98:IKeymasterDevice* CreateKeymasterDevice();
system/keymaster/ng/include/AndroidKeymaster3Device.h:100:IKeymasterDevice* CreateKeymasterDevice(keymaster2_device_t* km2_device);
system/keymaster/ng/include/AndroidKeymaster3Device.h:101:IKeymasterDevice* CreateKeymasterDevice(keymaster1_device_t* km1_device);
system/keymaster/ng/include/AndroidKeymaster3Device.h:102:IKeymasterDevice* CreateKeymasterDevice(keymaster0_device_t* km0_device);
system/keymaster/ng/include/AndroidKeymaster4Device.h:106:IKeymasterDevice* CreateKeymasterDevice(SecurityLevel securityLevel);
system/keymaster/ng/AndroidKeymaster3Device.cpp:496:IKeymasterDevice* CreateKeymasterDevice() {
system/keymaster/ng/AndroidKeymaster3Device.cpp:499:IKeymasterDevice* CreateKeymasterDevice(keymaster2_device_t* km2_device) {
system/keymaster/ng/AndroidKeymaster3Device.cpp:505:IKeymasterDevice* CreateKeymasterDevice(keymaster1_device_t* km1_device) {
system/keymaster/ng/AndroidKeymaster3Device.cpp:510:IKeymasterDevice* CreateKeymasterDevice(keymaster0_device_t* km0_device) {
system/keymaster/ng/AndroidKeymaster4Device.cpp:563:IKeymasterDevice* CreateKeymasterDevice(SecurityLevel securityLevel) {
hardware/interfaces/keymaster/3.0/default/KeymasterDevice.cpp:74:        return ::keymaster::ng::CreateKeymasterDevice();
hardware/interfaces/keymaster/3.0/default/KeymasterDevice.cpp:82:        return ::keymaster::ng::CreateKeymasterDevice(dev);
hardware/interfaces/keymaster/3.0/default/KeymasterDevice.cpp:88:        return ::keymaster::ng::CreateKeymasterDevice(dev);
hardware/interfaces/keymaster/3.0/default/KeymasterDevice.cpp:94:        return ::keymaster::ng::CreateKeymasterDevice(dev);
hardware/interfaces/keymaster/3.0/default/KeymasterDevice.cpp:102:        return ::keymaster::ng::CreateKeymasterDevice();
hardware/interfaces/keymaster/4.0/default/service.cpp:28:    auto keymaster = ::keymaster::V4_0::ng::CreateKeymasterDevice(SecurityLevel::SOFTWARE);
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40.sage.cpp:1806:         auto swkm = ::keymaster::V4_0::ng::CreateKeymasterDevice(SecurityLevel::SOFTWARE);
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40.tee.cpp:1087:      auto swkm = ::keymaster::V4_0::ng::CreateKeymasterDevice(SecurityLevel::SOFTWARE);
device/generic/goldfish/keymaster/strongbox/service.cpp:29:    using ::keymaster::V4_0::ng::CreateKeymasterDevice;
device/generic/goldfish/keymaster/strongbox/service.cpp:35:    auto keymaster = CreateKeymasterDevice(SecurityLevel::TRUSTED_ENVIRONMENT);
device/generic/goldfish/keymaster/strongbox/service.cpp:41:    auto strongbox = CreateKeymasterDevice(SecurityLevel::STRONGBOX);
grep: device/ti/beagle_x15/hostcc/ar: No such file or directory
grep: device/ti/beagle_x15/hostcc/cc: No such file or directory
grep: device/ti/beagle_x15/hostcc/ld: No such file or directory
grep: device/ti/beagle_x15/hostcc/strings: No such file or directory
grep: device/ti/beagle_x15/hostcc/gcc: No such file or directory
grep: device/ti/beagle_x15/hostcc/g++: No such file or directory
grep: device/ti/beagle_x15/hostcc/ld.bfd: No such file or directory
android-q-ab2/src-km$ grep -Rn CreateBcmKm40 vendor/broadcom/
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40Tee.h:123:IKeymasterDevice* CreateBcmKm40();
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40.sage.cpp:3544:IKeymasterDevice* CreateBcmKm40() {
vendor/broadcom/bcm_platform/hals/keymaster/4.0/service.cpp:29:    auto keymaster = ::bcm::keymaster::V4_0::implementation::CreateBcmKm40();
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40.tee.cpp:1902:IKeymasterDevice* CreateBcmKm40() {
vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40Sage.h:150:IKeymasterDevice* CreateBcmKm40();

发现，在:

hardware/interfaces/keymaster/4.0/default/service.cpp
- 提供了一个基于AndroidKeymaster4Device的实现
vendor/broadcom/bcm_platform/hals/keymaster/4.0/service.cpp
- 提供了一个Broadcom平台的具体实现

在device, hardware, system和vendor下搜索hardware相关service脚本:

android-q-ab2/src-km$ find device/ hardware/ system/ vendor/broadcom/ -type f -iname android.hardware.keymaster*.rc
device/generic/goldfish/keymaster/strongbox/android.hardware.keymaster@4.0-strongbox-service.rc
hardware/interfaces/keymaster/3.0/default/android.hardware.keymaster@3.0-service.rc
hardware/interfaces/keymaster/4.0/default/android.hardware.keymaster@4.0-service.rc
system/core/trusty/keymaster/3.0/android.hardware.keymaster@3.0-service.trusty.rc
system/core/trusty/keymaster/4.0/android.hardware.keymaster@4.0-service.trusty.rc
vendor/broadcom/bcm_platform/hals/keymaster/4.0/android.hardware.keymaster@4.0-service.bcm.rc

4.1 Broadcom 私有实现

文件android.hardware.keymaster@4.0-service.bcm.rc是Broadcom实现的KeyMaster Service的启动脚本。

在实现代码中，实际上获取的KeyMaster是Broadcom私有代码CreateBcmKm40返回的一个对象BcmKm40。

# vendor/broadcom/bcm_platform/hals/keymaster/4.0/android.hardware.keymaster@4.0-service.bcm.rc# vendor/broadcom/bcm_platform/hals/keymaster/4.0/service.cpp
int main() {::android::hardware::configureRpcThreadpool(1, true /* willJoinThreadpool */);auto keymaster = ::bcm::keymaster::V4_0::implementation::CreateBcmKm40();if (keymaster == NULL) {LOG(FATAL) << "Could not create Bcm Keymaster 4.0";}auto status = keymaster->registerAsService();if (status != android::OK) {LOG(FATAL) << "Could not register service for Bcm Keymaster 4.0 (" << status << ")";}android::hardware::joinRpcThreadpool();return -1;  // Should never get here.
}# vendor/broadcom/bcm_platform/hals/keymaster/4.0/BcmKm40.sage.cpp
IKeymasterDevice* CreateBcmKm40() {return new BcmKm40();
}

4.2 Android 默认的基于软件的实现

文件android.hardware.keymaster@4.0-service.rc是 Android 默认实现的KeyMaster Service的启动脚本。

Android 默认提供了一个基于软件的KeyMaster实现，即创建服务时: CreateKeymasterDevice(SecurityLevel::SOFTWARE)，如果相应的硬件平台没有实现硬件的KeyMaster，则这里会回退使用Android的Software的Keymaster。

# hardware/interfaces/keymaster/4.0/default/android.hardware.keymaster@4.0-service.rc# hardware/interfaces/keymaster/4.0/default/service.cpp
int main() {::android::hardware::configureRpcThreadpool(1, true /* willJoinThreadpool */);auto keymaster = ::keymaster::V4_0::ng::CreateKeymasterDevice(SecurityLevel::SOFTWARE);auto status = keymaster->registerAsService();if (status != android::OK) {LOG(FATAL) << "Could not register service for Keymaster 4.0 (" << status << ")";}android::hardware::joinRpcThreadpool();return -1;  // Should never get here.
}# system/keymaster/ng/AndroidKeymaster4Device.cpp
IKeymasterDevice* CreateKeymasterDevice(SecurityLevel securityLevel) {return new AndroidKeymaster4Device(securityLevel);
}# system/keymaster/ng/AndroidKeymaster4Device.cpp/** AndroidKeymaster4Device::impl_ = new ::keymaster::AndroidKeymaster(KeymasterContext* context, size_t operation_table_size);*   impl_->context_ = new PureSoftKeymasterContext();*   impl_->operation_table_ = (new OperationTable(kOperationTableSize));* AndroidKeymaster4Device::securityLevel_ = securityLevel;*/
AndroidKeymaster4Device::AndroidKeymaster4Device(SecurityLevel securityLevel): impl_(new ::keymaster::AndroidKeymaster([]() -> auto {auto context = new PureSoftKeymasterContext();context->SetSystemVersion(GetOsVersion(), GetOsPatchlevel());return context;}(),kOperationTableSize)), securityLevel_(securityLevel) {}

4.3 Trusty 实现

文件android.hardware.keymaster@4.0-service.trusty.rc是 Trusty 实现的KeyMaster Service的启动脚本。

基于 Trusty TEE 的 KeyMaster实现，代码分析略。

# system/core/trusty/keymaster/4.0/android.hardware.keymaster@4.0-service.trusty.rc# system/core/trusty/keymaster/4.0/service.cpp
int main() {::android::hardware::configureRpcThreadpool(1, true);auto trustyKeymaster = new keymaster::TrustyKeymaster();int err = trustyKeymaster->Initialize();if (err != 0) {LOG(FATAL) << "Could not initialize TrustyKeymaster (" << err << ")";return -1;}auto keymaster = new ::keymaster::V4_0::TrustyKeymaster4Device(trustyKeymaster);auto status = keymaster->registerAsService();if (status != android::OK) {LOG(FATAL) << "Could not register service for Keymaster 4.0 (" << status << ")";return -1;}android::hardware::joinRpcThreadpool();return -1;  // Should never get here.
}# system/core/trusty/keymaster/TrustyKeymaster.cpp
int TrustyKeymaster::Initialize() {int err;err = trusty_keymaster_connect();if (err) {ALOGE("Failed to connect to trusty keymaster %d", err);return err;}ConfigureRequest req;req.os_version = GetOsVersion();req.os_patchlevel = GetOsPatchlevel();ConfigureResponse rsp;Configure(req, &rsp);if (rsp.error != KM_ERROR_OK) {ALOGE("Failed to configure keymaster %d", rsp.error);return -1;}return 0;
}TrustyKeymaster::TrustyKeymaster() {}# system/core/trusty/keymaster/4.0/TrustyKeymaster4Device.cpp
/** TrustyKeymaster4Device::impl_ = new keymaster::TrustyKeymaster()*/
TrustyKeymaster4Device::TrustyKeymaster4Device(TrustyKeymaster* impl) : impl_(impl) {}

4.4 Goldfish 实现

从代码中可以看到，Goldfish 有基于 StrongBox 和一般 KeyMaster 两种

StrongBox

# device/generic/goldfish/keymaster/strongbox/android.hardware.keymaster@4.0-strongbox-service.rc# device/generic/goldfish/keymaster/strongbox/service.cpp
int main() {::android::hardware::configureRpcThreadpool(1, true /* willJoinThreadpool */);using android::hardware::keymaster::V4_0::SecurityLevel;using ::keymaster::V4_0::ng::CreateKeymasterDevice;/** Create two software keymaster devices claiming different security levels for testing* purposes. They do not have the certificates of real TEE or Strongbox keymaster devices.*/auto keymaster = CreateKeymasterDevice(SecurityLevel::TRUSTED_ENVIRONMENT);auto status = keymaster->registerAsService("default");if (status != android::OK) {LOG(FATAL) << "Could not register default service for Keymaster 4.0 (" << status << ")";}auto strongbox = CreateKeymasterDevice(SecurityLevel::STRONGBOX);status = strongbox->registerAsService("strongbox");if (status != android::OK) {LOG(FATAL) << "Could not register strongbox service for Keymaster 4.0 (" << status << ")";}android::hardware::joinRpcThreadpool();return -1;  // Should never get here.
}# 以上代码基于不同的security level创建了两个keymaster设备keymaster和strongbox
# using ::keymaster::V4_0::ng::CreateKeymasterDevice;

Keymaster

#
# device/generic/goldfish/keymaster/trusty
#
# 模拟器使用的都是ranchu内核，android源码是在7.0的时候才开始提供的，路径是：prebuilts/qemu-kernel/x86/ranchu/kernel-qemu
# 编译可用的Android模拟器ranchu内核# device/generic/goldfish/keymaster/trusty/keymaster_module.cpp
struct keystore_module HAL_MODULE_INFO_SYM __attribute__((visibility("default"))) = {.common ={.tag = HARDWARE_MODULE_TAG,.module_api_version = KEYMASTER_MODULE_API_VERSION_2_0,.hal_api_version = HARDWARE_HAL_API_VERSION,.id = KEYSTORE_HARDWARE_MODULE_ID,.name = "Trusty Keymaster HAL",.author = "The Android Open Source Project",.methods = &keystore_module_methods,.dso = 0,.reserved = {},},
};/** Generic device handling*/
static int trusty_keymaster_open(const hw_module_t* module __unused, const char* name, hw_device_t** device) {if (strcmp(name, KEYSTORE_KEYMASTER) != 0) {return -EINVAL;}// Use softkeymaster in guest instead of connecting to host implementation of softkeymaster*device = reinterpret_cast<hw_device_t*>((new keymaster::SoftKeymasterDevice())->keymaster2_device());return 0;
}# system/keymaster/contexts/soft_keymaster_device.cpp
keymaster2_device_t* SoftKeymasterDevice::keymaster2_device() {return &km2_device_;
}

4.5 QualComm 私有实现

这个应该是 QualComm 基于老的 KeyMaster 接口的实现，还是原来的 HAL_MODULE 的形式，不适合最新的 KeyMaster，默认实现比较简单，公开的代码中没有最新的实现。

# hardware/qcom/keymaster/keymaster_qcom.cppstatic struct hw_module_methods_t keystore_module_methods = {.open = qcom_km_open,
};struct keystore_module HAL_MODULE_INFO_SYM
__attribute__ ((visibility ("default"))) = {.common = {.tag = HARDWARE_MODULE_TAG,.module_api_version = QCOM_KEYMASTER_API_VERSION,.hal_api_version = HARDWARE_HAL_API_VERSION,.id = KEYSTORE_HARDWARE_MODULE_ID,.name = "Keymaster QCOM HAL",.author = "The Android Open Source Project",.methods = &keystore_module_methods,.dso = 0,.reserved = {},},
};

5. 关于 KeyMaster 的注释文档

在 system/keymaster/include/keymaster/keymaster_context.h 提供了一些关于 keymaster 的注释，如果需要学习 KeyMaster，建议看下 Android 官方关于 KeyMaster 的文档。

Android 官方网站文档: https://source.android.google.cn/security/keystore?hl=zh-cn

# system/keymaster/include/keymaster/keymaster_context.h/*** KeymasterContext provides a singleton abstract interface that encapsulates various* environment-dependent elements of AndroidKeymaster.** AndroidKeymaster runs in multiple contexts.  Primarily:** - In a trusted execution environment (TEE) as a "secure hardware" implementation.  In this*   context keys are wrapped with an master key that never leaves the TEE, TEE-specific routines*   are used for random number generation, all AndroidKeymaster-enforced authorizations are*   considered hardware-enforced, and there's a bootloader-provided root of trust.** - In the non-secure world as a software-only implementation.  In this context keys are not*   encrypted (though they are integrity-checked) because there is no place to securely store a*   key, OpenSSL is used for random number generation, no AndroidKeymaster-enforced authorizations*   are considered hardware enforced and the root of trust is a static string.** - In the non-secure world as a hybrid implementation fronting a less-capable hardware*   implementation.  For example, a keymaster0 hardware implementation.  In this context keys are*   not encrypted by AndroidKeymaster, but some may be opaque blobs provided by the backing*   hardware, but blobs that lack the extended authorization lists of keymaster1.  In addition,*   keymaster0 lacks many features of keymaster1, including modes of operation related to the*   backing keymaster0 keys.  AndroidKeymaster must extend the blobs to add authorization lists,*   and must provide the missing operation mode implementations in software, which means that*   authorization lists are partially hardware-enforced (the bits that are enforced by the*   underlying keymaster0) and partially software-enforced (the rest). OpenSSL is used for number*   generation and the root of trust is a static string.** More contexts are possible.*/
class KeymasterContext {...
}

AndroidKeymaster运行在多个上下文context中
- TEE, secure hardware, 由TEE的一个master key包含keymaster key
- REE, software-only implementation
  - keys没有加密, OpenSSL用来生成随机数
- REE (hybrid implementation, a less-capable hardware implementation)