移植 corePKCS11 库

公有密钥加密标准 #11 定义了一个独立于平台的 API，可用于管理和使用加密令牌。PKCS 11 是指它定义的标准和 API。PKCS #11 加密 API 用于提取密钥存储、加密对象的 get/set 属性以及会话语义。该标准在操纵常见加密对象时应用广泛。它的功能允许应用程序软件使用、创建、修改和删除加密对象，而无需将这些对象暴露在应用程序的内存中。

FreeRTOS 库和参考集成使用 PCKS #11 接口标准的子集，重点是涉及非对称密钥、随机数生成和哈希的操作。下表列出了使用案例和需要支持的 PKCS #11 API。

使用案例
使用案例	必需的 PKCS #11 API 系列
全部	初始化、最终确定、打开/关闭会话、GetsLotList、登录
预置	GenerateKeyPair、CreateObject、DestroyObject、InitToken、GetTokenInfo
TLS	随机、签名、FindObject、GetAttributeValue
FreeRTOS+TCP	随机，摘要
OTA	验证、摘要、FindObject、GetAttributeValue

何时实现完整的 PKCS #11 模块

在通用闪存中存储私有密钥对于评估和快速原型设计场景非常方便。在生产场景中，为了减少数据窃取和设备复制的威胁，我们建议您使用专用加密硬件。加密硬件包含具有防止导出加密密钥功能的组件。为了支持这一点，您必须实现使用上表中定义的 FreeRTOS 库所需的 PKCS #11 子集。

何时使用 FreeRTOS corePKCS11

corePKCS11 库包含 PKCS #11 接口 (API) 的基于软件的实现，该接口使用 Mbed TLS 提供的加密功能。这是在没有专用加密硬件的情况下，为硬件的快速原型设计和评估场景提供的。在这种情况下，您只需要实现 corePKCS11 PAL 即可让基于 corePKCS11 软件的实现与您的硬件平台配合使用。

移植 corePKCS11

您必须有实现才能读取加密对象并将其写入非易失性存储器 (NVM)，例如板载闪存。加密对象必须存储在设备重新编程时未初始化且未擦除的 NVM 部分。corePKCS11 库的用户将使用凭证预置设备，然后使用可通过 corePKCS11 接口访问这些凭证的新应用程序重新编程设备。corePKCS11 PAL 移植必须提供一个位置来存储：

• 设备客户端证书

• 设备客户端私有密钥

• 设备客户端公有密钥

• 受信任的根 CA

• 代码验证公有密钥（或包含代码验证公有密钥的证书），用于安全引导加载程序和空中下载 (OTA) 更新

• 即时预置证书。

包含头文件并实现定义的 PAL API。

PAL API
函数	描述
PKCS11_PAL_Initialize	初始化 PAL 层。由 corePKCS11 库在其初始化序列开始时调用。
PKCS11_PAL_SaveObject	将数据写入非易失性存储。
PKCS11_PAL_FindObject	使用 PKCS #11 CKA_LABEL 来在非易失性存储中搜索相应的 PKCS #11 对象，并返回该对象的句柄（如果存在）。
PKCS11_PAL_GetObjectValue	检索对象的值，给定句柄。
PKCS11_PAL_GetObjectValueCleanup	PKCS11_PAL_GetObjectValue 调用的清除。可用于释放 PKCS11_PAL_GetObjectValue 调用中分配的内存。

测试

如果您使用 FreeRTOS corePKCS11 库或实现所需的 PKCS11 API 子集，则必须通过 FreeRTOS PKCS11 测试。这些测试用于验证 FreeRTOS 库所需的函数能否按预期执行。

本节还介绍了如何使用资格认证测试在本地运行 FreeRTOS PKCS11 测试。

先决条件

要设置 FreeRTOS PKCS11 测试，必须实现以下几点。

• PKCS11 API 支持的移植。

• FreeRTOS 资格认证测试平台功能的实现，其中包括：

  • FRTest_ThreadCreate

  • FRTest_ThreadTimedJoin

  • FRTest_MemoryAlloc

  • FRTest_MemoryFree

（参阅 GitHub 上有关 PKCS #11 的 FreeRTOS 库集成测试的 README.md 文件。）

移植测试

• 将 FreeRTOS-Libraries-Integration-Tests 作为子模块添加到您的项目中。只要可以构建子模块，就可以将其放在项目的任何目录中。

• 将 config_template/test_execution_config_template.h 和 config_template/test_param_config_template.h 复制到构建路径中的项目位置，然后将其重命名为test_execution_config.h和test_param_config.h。

• 将相关文件包含到构建系统中。如果使用 CMake，则可以使用 qualification_test.cmake 和 src/pkcs11_tests.cmake 来包含相关文件。

• 实现 UNITY_OUTPUT_CHAR，这样，测试输出日志就不会与设备日志交错。

• 集成 MbedTLS，用于验证 cryptoki 的操作结果。

• 从应用程序调用 RunQualificationTest()。

配置测试

PKCS11 测试套件必须根据 PKCS11 实现进行配置。下表在 test_param_config.h 头文件中列出了 PKCS11 测试所需的配置。

PKSC11 测试配置
配置	描述
PKCS11_TEST_RSA_KEY_SUPPORT	该移植支持 RSA 密钥功能。
PKCS11_TEST_EC_KEY_SUPPORT	该移植支持 EC 密钥功能。
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	移植支持导入私有密钥。如果已启用支持密钥功能，则将在测试中验证 RSA 和 EC 密钥导入。
PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT	移植支持生成密钥对。如果已启用支持密钥功能，则将在测试中验证 EC 密钥对生成。
PKCS11_TEST_PREPROVISIONED_SUPPORT	移植具有预置凭证。PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS、PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS 和 PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS 是证书的示例。
PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS	测试中使用的私有密钥的标签。
PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS	测试中使用的公有密钥的标签。
PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS	测试中使用的证书的标签。
PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	该移植支持 JITP 的存储。将其设置为 1 可启用 JITP codeverify 测试。
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	JITP codeverify 测试中使用的代码验证密钥的标签。
PKCS11_TEST_LABEL_JITP_CERTIFICATION	JITP codeverify 测试中使用的 JITP 证书的标签。
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	JITP codeverify 测试中使用的根证书的标签。

FreeRTOS 库和参考集成必须支持至少一种密钥功能配置，例如 RSA 或 Elliptic 曲线密钥，以及 PKCS11 API 支持的一种密钥预置机制。该测试必须启用以下配置：

• 至少启用以下密钥功能配置之一：

  • PKCS11_TEST_RSA_KEY_SUPPORT

  • PKCS11_TEST_EC_KEY_SUPPORT

• 至少启用以下密钥预置配置之一：

  • PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT

  • PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT

  • PKCS11_TEST_PREPROVISIONED_SUPPORT

预先配置的设备凭证测试必须在以下条件下运行：

• 必须启用 PKCS11_TEST_PREPROVISIONED_SUPPORT 并禁用其他配置机制。

• 只有一个密钥功能（PKCS11_TEST_RSA_KEY_SUPPORT 或 PKCS11_TEST_EC_KEY_SUPPORT）处于启用状态。

• 根据您的密钥功能设置预先配置的密钥标签，包括 PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS、PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS 和 PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS。在运行测试之前，这些凭证必须存在。

如果实现支持预先配置的凭证和其他配置机制，则测试可能需要使用不同的配置运行多次。

注意

如果启用 PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT 或 PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT，则会在测试期间销毁带有标签 PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS、PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS 和 PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS 的对象。

运行测试

本节介绍如何通过资格认证测试在本地测试 PKCS11 接口。或者，您也可以使用 IDT 自动执行。有关详细信息，请参阅《FreeRTOS 用户指南》中 适用于 FreeRTOS 的 AWS IoT Device Tester。

以下说明介绍了如何运行测试：

• 打开 test_execution_config.h 并将 CORE_PKCS11_TEST_ENABLED 定义为 1。

• 构建应用程序并将其刷写到您的设备上，以便运行。测试结果会输出到串行端口。

下面是输出测试结果的一个示例。

TEST(Full_PKCS11_StartFinish, PKCS11_StartFinish_FirstTest) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_GetFunctionList) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_InitializeFinalize) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_GetSlotList) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_OpenSessionCloseSession) PASS
TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities) PASS
TEST(Full_PKCS11_NoObject, PKCS11_Digest) PASS
TEST(Full_PKCS11_NoObject, PKCS11_Digest_ErrorConditions) PASS
TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandom) PASS
TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandomMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_CreateObject) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObject) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValue) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_Sign) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObjectMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValueMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_DestroyObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GenerateKeyPair) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_CreateObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_FindObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValue) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_Sign) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_Verify) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_FindObjectMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValueMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_SignVerifyMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_DestroyObject) PASS

-----------------------
27 Tests 0 Failures 0 Ignored
OK
    

当所有测试均已通过后，测试完成。

注意

要正式对设备进行 FreeRTOS 资格认证，您必须使用 AWS IoT Device Tester 验证设备的移植源代码。按照《FreeRTOS 用户指南》中使用适用于 FreeRTOS 的 AWS IoT Device Tester中的说明为移植验证设置 AWS IoT Device Tester。要测试特定库的移植，必须在 AWS IoT Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。