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

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

移植 PKCS #11 库

FreeRTOS 使用开放标准 PKCS #11“CryptoKi”API 作为加密操作的抽象层,包括:

  • 签名和验证。

  • X.509 证书的存储和枚举。

  • 加密密钥的存储和管理。

有关更多信息,请参阅 PKCS #11 加密令牌接口基本规范

在通用闪存中存储私有密钥对于评估和快速原型设计场景非常方便。在生产场景中,为了减少数据窃取和设备重复的威胁,我们建议您使用专用加密硬件。加密硬件包含具有防止导出加密密钥功能的组件。要将专用加密硬件用于 FreeRTOS,您需要移植 PKCS #11 API 到硬件。有关 FreeRTOS PKCS #11 库的更多信息,请参阅 FreeRTOS 用户指南中的 FreeRTOS PKCS #11 库

Prerequisites

要移植 PKCS #11 库,需要以下内容:

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

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

  • 一个 FreeRTOS 内核的经验证配置。

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

Porting

移植 PKCS #11 库

  1. 移植 PKCS #11 API 函数

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

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

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

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

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

    PKCS #11 PAL 移植必须提供一个位置来存储:

    • 设备客户端证书。

    • 设备客户端私有密钥。

    • 设备客户端公有密钥。

    • 受信任的根 CA。

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

    • 即时预置证书。

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

    Function Description
    PKCS11_PAL_Initialize 初始化 PAL 层。由 PKCS #11 库在其初始化序列开始时调用。
    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. 实现 mbedtls_hardware_poll() 函数,为 mbedTLS 用于生成加密随机位流的确定性随机位生成器 (DRBG) 添加种子。mbedtls_hardware_poll() 函数位于 /vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 中。

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

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

        将修改后的 config.h 版本保存到 /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.hmbedtls/include/mbedtls/config.h 标头文件中的注释。mbedTLS

    重要

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

    注意

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

    有关经 NIST 批准的 DRBGs 和纪元源的更多信息,请参阅以下 NIST 出版物:

Testing

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

设置 IDE 测试项目

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

重要

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

在 IDE 项目中设置 PKCS #11 库

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

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

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

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

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

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

配置 CMakeLists.txt 文件

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

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

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

请参阅下文以了解 PKCS #11 库的示例可移植层目标定义,该库使用基于 mbedTLS 的 PKCS #11 软件实施,并提供特定于端口的 PKCS #11 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. 如果已经移植了安全套接字库,请打开 /libraries/freertos_plus/standard/utils/src/iot_system_init.c,并在函数 SYSTEM_Init() 中取消注释对 SOCKETS_Init() 的调用。

  2. 打开 /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 资格认证,您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照《FreeRTOS 用户指南》中的将 AWS IoT Device Tester 用于 FreeRTOS 中的说明操作,设置 Device Tester 以进行移植验证。要测试特定库的移植,必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。

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