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

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

移植代码库

CorepKCS11 库包含基于软件的 PKCS #11 接口 (API) 模拟实现,该接口使用 mbed TLS 提供的加密功能。在通用闪存中存储私有密钥对于评估和快速原型设计场景非常方便。在生产场景中,为了减少数据窃取和设备重复的威胁,我们建议您使用专用加密硬件。加密硬件包含具有防止导出加密密钥功能的组件。

要将专用加密硬件用于 FreeRTOS,请移植适用于的硬件的 PKCS #11 API。一般来说,安全加密处理器(如受信任的平台模块 (TPM)、硬件安全模块 (HSM)、安全元素或任何其他类型的安全硬件飞地)的供应商都会随硬件分发 PKCS #11 实现。您可以将库添加到 CMake 和 IDE 项目中,编译它并运行 PKCS #11 测试套件。

本节介绍了如何使用 FreeRTOS CorepKCS11 库作为您自己的 PKCS #11 API 端口的基础。只实现了 PKCS #11 标准的一个子集,重点是涉及非对称键、随机数生成和散列的操作。PKCS #11 API 调用由 TLS 帮助程序接口生成,目的是为了在期间执行 TLS 客户端身份验证。SOCKETS_Connect。PKCS #11 API 调用也可以由一次性开发人员预置工作流程生成,以将用于身份验证的 TLS 客户端证书和私有密钥导入到Amazon IoTMQTT 代理。以上两个使用案例(预配置和 TLS 客户端身份验证)都只需要实施 PKCS #11 接口标准的一小部分。

有关 FreeRTOS 库的信息,请参阅FreeRTOS 图书馆中的FreeRTOS 用户指南

Prerequisites

要移植 CorepkCS11 库,需要以下内容:

  • 一个 IDE 项目或 CMakeLists.txt 列表文件,其中包含供应商提供的驱动程序,而这些驱动程序适用于敏感数据。

    有关设置测试项目的信息,请参阅为移植设置 FreeRTOS 源代码

  • FreeRTOS 内核的经验证配置。

    有关为您的平台配置 FreeRTOS 内核的信息,请参阅配置 FreeRTOS 内核移植

Porting

移植 CorepkCS11 库

  1. 移植由 CorepkCS11 实施的 PKCS #11 API 函数。

    PKCS #11 API 依赖于加密基元的实施,如 SHA256 哈希和椭圆曲线数字签名算法 (ECDSA) 签名。

    PKCS #11 的 FreeRTOS 实施使用在 mbedTLS 库中实施的加密基元。FreeRTOS 包括一个用于 mbedTLS 的端口。如果您的目标硬件将加密分载到单独的模块,或者如果您想要使用软件实施 mbedTLS 以外的加密基元,则需要修改现有 PKCS #11 实施。

  2. 针对设备特定的证书和密钥存储移植 CorepkCS11 平台抽象层 (PAL)。

    如果您决定使用 FreeRTOS 实施 PKCS #11,只需进行少量的自定义即可在非易失性存储 (NVM) 中读取和写入加密对象,例如板载内存。

    加密对象应存储在设备重新编程时未初始化且未擦除的 NVM 部分。CorepkCS11 库的用户应能够预置设备凭证,然后使用能够通过 CorepkCS11 接口访问这些凭证的新应用程序重新编程备。

    COREPKCS11 PAL 移植必须提供一个位置来存储:

    • 设备客户端证书。

    • 设备客户端私有密钥。

    • 设备客户端公有密钥。

    • 受信任的根 CA。

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

    • 即时预置证书。

    freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 包含 PAL 函数的空定义。您必须至少为此表中列出的函数提供移植:

    函数 描述
    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 调用中分配的内存。
  3. 为您的移植增加对加密随机熵源的支持:

    • 如果您的移植为底层加密和 TLS 支持使用 mbedTLS 库,并且您的设备有真随机数生成器 (TRNG),请执行以下操作:

      1. 实施mbedtl _ 硬件投票 ()函数为 mbedTLS 用于生成加密随机位流的确定性随机位生成器 (DRBG) 注入种子。mbedtls_hardware_poll() 函数位于 freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 中。

    • 如果您的移植为底层加密和 TLS 支持使用 mbedTLS 库,但您的设备没有 TRNG,请执行以下操作:

      1. 创建 freertos/libraries/3rdparty/mbedtls/include/mbedtls/config.h 的副本,然后在该副本中取消注释 MBEDTLS_ENTROPY_NV_SEED 并注释掉 MBEDTLS_ENTROPY_HARDWARE_ALT

        将修改的 config.h 版本保存到 freertos/vendors/vendor/boards/board/aws_tests/config_files/config.h 中。请勿覆盖原始文件。

      2. 实施函数 mbedtls_nv_seed_poll()nv_seed_read_func()nv_seed_write_func()

        有关实施这些函数的信息,请参阅 mbedtls/include/mbedtls/entropy_poll.h 中的注释以及 mbedtls/include/mbedtls/config.h mbedTLS 标头文件。

    重要

    必须在制造时向设备提供具有 NIST 批准的熵源的种子文件。

    注意

    如果您对 FreeRTOS 资格认证计划感兴趣,请参阅我们对RNG

    有关 NIST 批准的 DRBG 和熵源的更多信息,请参阅以下 NIST 出版物:

Testing

如果使用 IDE 构建测试项目,您需要在 IDE 项目中设置库移植。

设置 IDE 测试项目

如果使用 IDE 进行移植和测试,您需要先将一些源文件添加到 IDE 测试项目中,然后才能测试移植的代码。

重要

在以下步骤中,请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。

在 IDE 项目中设置 CorepkCS11 库

  1. 将源文件 freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 添加到 aws_tests IDE 项目中。

  2. freertos/libraries/abstractions/pkcs11 目录及其子目录中的所有文件添加到 aws_tests IDE 项目中。

  3. freertos/libraries/freertos_plus/standard/pkcs11 目录及其子目录中的所有文件添加到 aws_tests IDE 项目中。这些文件实施了通常分组的 PKCS #11 函数集的包装程序。

  4. 将源文件 freertos/libraries/freertos_plus/standard/crypto/src/iot_crypto.c 添加到 aws_tests IDE 项目中。此文件为 mbedTLS 实施 CRYPTO 抽象包装程序。

  5. freertos/libraries/3rdparty/mbedtls 及其子目录中的所有源文件和标头文件添加到 aws_tests IDE 项目中。

  6. Addfreertos/libraries/3rdparty/mbedtls/includefreertos/libraries/abstractions/pkcs11添加到编译器的包含路径中。

配置 CMakeLists.txt 文件

如果使用 CMake 构建测试项目,您需要在 CMake 列表文件中为库定义一个可移植层目标。

要在 CMakeLists.txt 中定义库的可移植层目标,请按照FreeRTOS 可移植层中的说明进行操作。

freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义,并对其进行修改以适合您的平台。

请参阅下文以了解 CorepkCS11 库的示例可移植层目标定义,它使用基于 mbedTLS 的 PKCS #11 软件实施,并提供移植特定的 COrepkCS11 PAL 文件。

# PKCS11 afr_mcu_port(pkcs11_implementation DEPENDS AFR::pkcs11_mbedtls) target_sources( AFR::pkcs11_implementation::mcu_port INTERFACE "${afr_ports_dir}/pkcs11/core_pkcs11_pal.c" )

设置本地测试环境

在 IDE 项目中设置库后,您需要配置一些其他文件以进行测试。

为 PKCS #11 测试配置源文件和标头文件

  1. 如果已经移植了安全套接字库,请打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c,并在函数 SYSTEM_Init() 中取消注释对 SOCKETS_Init() 的调用。

  2. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h,然后将 testrunnerFULL_PKCS11_ENABLED 宏设置为 1 以启用 PKCS #11 测试。

运行测试

执行 PKCS #11 测试

  1. 构建测试项目,然后将其刷写到您的设备以执行该项目。

  2. 在 UART 控制台中检查测试结果。

    ...

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

Validation

要正式对设备进行 FreeRTOS 资格认证,您需要使用Amazon IoTDevice Tester。按照中的说明进行操作使用Amazon IoT适用于的 FreeRTOS Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植,必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。

完成将 CorepkCS11 库移植到设备之后,您可以开始移植 TLS 库。有关说明,请参阅移植 TLS 库