移植 corepKCS11 库 - FreeRTOS
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

移植 corepKCS11 库

公钥加密标准 #11 定义了独立于平台的 API 来管理和使用加密令牌。PKCS 1指标准及其定义的 API。PKCS #11 加密 API 提取密钥存储、加密对象的获取/设置属性以及会话语义。它被广泛用于操纵常见的加密对象。它的功能允许应用程序软件使用、创建、修改和删除加密对象,而不会将这些对象暴露在应用程序的内存中。

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

使用案例
使用案例 必需的 PKCS #11 API 系列
全部 初始化、敲定、打开/关闭会话、getSlotList、登录
预置 GenerateKeyPair、CreateObject、销毁对象、initToken、getTokenInfo
TLS 随机、签名、查找对象、GetAttributeValue
FreeRTOS+TCP 摘要随机
OTA 验证、摘要、查找对象、GetAttributeValue

什么时候实施完整的 PKCS #11 模块

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

何时使用 FreeRTOS corepKCS11

CorepKCS11 库包含一个基于软件的 PKCS #11 接口 (API) 实现,该接口使用Mbed TLS. 这是针对硬件没有专用加密硬件的快速原型设计和评估场景提供的。在这种情况下,您只需要实施 corepKCS11 PAL 即可使基于软件的 CorepkCS11 实施与您的硬件平台配合使用。

移植 corepKCS11

您必须实施加密对象读取和写入加密对象到非易失性存储 (NVM),例如板载内存。加密对象必须存储在设备重新编程时未初始化且未擦除的 NVM 部分。CorepkCS11 库的用户将预置设备凭证,然后使用能够通过 CorepKCS11 接口访问这些凭证的新应用程序重新编程备。CorepkCS11 PAL 端口必须提供存储位置:

  • 设备客户端证书

  • 设备客户端私有密钥

  • 设备客户端公有密钥

  • 受信任的根 CA

  • 代码验证公有密钥(或包含代码验证公有密钥的证书),用于安全引导加载程序和 over-the-air (OTA) 更新

  • 即时预置证书

Include头文件并实施定义的 PAL API。

PAL API
函数 描述
PKCS11_pal_ 初始化

初始化 PAL 层。由 CorepkCS11 库在其初始化序列开始时调用。

PKCS11_pal_Save 对象

将数据写入非易失性存储。

PKCS11_pal_findObject

使用 PKCS #11 CKA_LABEL 来在非易失性存储中搜索相应的 PKCS #11 对象,并返回该对象的句柄(如果存在)。

PKCS11_pal_GET 对象值

检索对象的值,给定句柄。

PKCS11_pal_Get ObjectValue 清理

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

移植测试

  • AddFreertoS-图书馆-集成-测试作为项目的子模块。只要能构建子模块,就可以放置在项目的任何目录中。

  • Copyconfig_template/test_execution_config_template.hconfig_template/test_param_config_template.h转到构建路径中的项目位置,然后将其重命名为test_execution_config.htest_param_config.h.

  • 在生成系统中包含相关文件。使用 时CMakequalification_test.cmakesrc/pkcs11_tests.cmake可以用来包含相关文件。

  • 实现UNITY_OUTPUT_CHAR以便测试输出日志和设备日志不会交错。

  • 集成 mbedTLS,验证 cryptoki 操作结果。

  • CallRunQualificationTest()来自应用程序。

配置测试

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

PKSC11 测试配置
配置 描述
PKCS11_TEST_RSA_KEY_支持

移植支持 RSA 关键功能。

PKCS11_TEST_EC_KEY_支持

移植支持 EC 关键功能。

PKCS11_TEST_IMPORT _PRIVATE_KEY_支持

移植支持导入私钥。如果启用了支持关键功能,则在测试中验证 RSA 和 EC 密钥导入。

PKCS11_TEST_GENATE_KEYAIR_ 支持

移植支持生成密钥对。如果启用了支持关键功能,则在测试中验证 EC 密钥对生成。

PKCS11_TEST_预配置_支持

移植具有预先配置的凭据。PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLSPKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSPKCS11_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_证书_FOR_TLS

测试中使用的证书的标签。

PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_支持

移植支持 JITP 的存储。将其设置为 1 可启用 JITPcodeverify测试组件。

PKCS11_TEST_LABEL_CODE_CODE_验证_KEY

JITP 中使用的代码验证密钥的标签codeverify测试组件。

PKCS11_TEST_LABEL_JITP_ 证书

JITP 中使用的 JITP 证书的标签codeverify测试组件。

PKCS11_TEST_LABEL_ROOT_证书

JITP 中使用的根证书的标签codeverify测试组件。

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

  • 至少以下关键功能配置之一:

    • PKCS11_TEST_RSA_KEY_支持

    • PKCS11_TEST_EC_KEY_支持

  • 至少以下关键预置配置之一:

    • PKCS11_TEST_IMPORT _PRIVATE_KEY_支持

    • PKCS11_TEST_GENATE_KEYAIR_ 支持

    • PKCS11_TEST_预配置_支持

预配置的设备凭据测试必须在以下条件下运行:

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

  • 要么只有一个关键功能PKCS11_TEST_RSA_KEY_SUPPORT要么PKCS11_TEST_EC_KEY_SUPPORT已启用。

  • 根据您的关键功能设置预先配置的密钥标签,包括PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLSPKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS. 运行测试之前必须存在这些凭据。

如果实施支持预置备的凭据和其他配置机制,则测试可能需要使用不同的配置运行多次。

注意

带有标签的对象PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLSPKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS在测试过程中被销毁PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT要么PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT已启用。

运行测试

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

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

  • 打开test_execution_config.h然后定义CORE_PKCS11_TEST_ 已启用到 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 资格认证设备的移植源代码,您必须使用Amazon IoT Device Tester. 按照中的说明进行操作使用Amazon IoT Device Tester对于 FreeRTOS在 FreeRTOS 用户指南中进行设置Amazon IoT Device Tester用于端口验证。要测试特定库的移植,必须在device.json中的文件Amazon IoT Device Tester configsfolder。