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

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

移植安全套接字库

您可以使用 FreeRTOS 安全套接字库来创建和配置 TCP 套接字、连接到 MQTT 代理以及发送和接收 TCP 数据。安全套接字库还封装 TLS 功能。创建 TLS 保护的套接字只需要标准 TCP 套接字。有关更多信息,请参阅 FreeRTOS 用户指南中的 FreeRTOS 安全套接字库

FreeRTOS 包含 FreeRTOS+TCP轻型 IP (lwIP) TCP/IP 堆栈的套接字实施,后者与 mbedTLS 结合使用。如果您使用的是 FreeRTOS+TCP或 lwIP TCP/IP堆栈,您无需移植安全套接字库。

注意

即使您不需要创建安全套接字库的移植,您的平台仍必须通过安全套接字库的资格认证测试。资格认证基于 AWS IoT Device Tester 的结果。

此外,您的 TLS 实现应支持 AWS IoT的 TLS 密码套件

如果您的平台将 TCP/IP 功能分载到单独的网络芯片,则需要将 FreeRTOS 安全套接字库移植到您的设备。

Prerequisites

要移植安全套接字库,您需要以下信息:

  • Wi-Fi 库的移植(仅当您使用 Wi-Fi 网络连接时需要)。

    有关移植 Wi-Fi 库的信息,请参阅移植 Wi-Fi 库

  • 移植 TCP/IP 堆栈。

    有关移植 TCP/IP 堆栈的信息,请参阅移植 TCP/IP 堆栈

  • Echo 服务器。

    FreeRTOS 在 /tools/echo_server 目录中包含一个使用 Go 编写的 Echo 服务器。有关更多信息,请参阅设置 Echo 服务器

Porting

如果您的平台将 TCP/IP 功能分载到单独的网络芯片,则需要实施在 /vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c 中具有存根的所有函数。

Testing

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

设置 IDE 测试项目

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

重要

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

在 IDE 项目中设置安全套接字库

  1. 如果您正在使用 FreeRTOS+TCPTCP/IP堆栈,添加 /libraries/abstractions/secure_sockets/freertos_plus_tcp/iot_secure_sockets.caws_tests IDE项目。

    如果您正在使用 lwIP TCP/IP堆栈,添加 /libraries/abstractions/secure_sockets/lwip/iot_secure_sockets.caws_tests IDE项目。

    如果使用您自己的 TCP/IP 端口,请将 /vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c 添加到 aws_tests IDE 项目中。

  2. secure_sockets/test/aws_test_tcp.c 添加到 aws_tests IDE 项目。

配置 CMakeLists.txt 文件

如果您正在使用 CMake 要构建测试项目,您需要为中的库定义一个便携式层目标 CMake 列表文件。

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

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

有关示例,请参阅以下安全套接字库的可移植层目标定义。

# Secure sockets afr_mcu_port(secure_sockets) # Link to AFR::secure_sockets_freertos_tcp if you want use default implementation based on # FreeRTOS-Plus-TCP. target_link_libraries( AFR::pkcs11::mcu_port INTERFACE AFR::secure_sockets_freertos_tcp ) # Or provide your own implementation. target_sources( AFR::secure_sockets::mcu_port INTERFACE "$path/iot_secure_sockets.c" )

设置本地测试环境

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

为安全套接字测试配置源文件和标头文件

  1. 打开 /libraries/freertos_plus/standard/utils/src/iot_system_init.c,并在函数 SYSTEM_Init() 中,确保注释掉调用 SOCKETS_Init() 的行。

  2. 启动 Echo 服务器。

    如果尚未将 TLS 库移植到您的平台,则只能使用不安全的 Echo 服务器 (/tools/echo_server/echo_server.go) 测试安全套接字移植。有关设置和运行不安全的 Echo 服务器的说明,请参阅设置 Echo 服务器

  3. aws_test_tcp.h 中,将 IP 地址设置为服务器的正确值。例如,如果您的服务器的 IP 地址是 192.168.2.6,请在 aws_test_tcp.h 中设置以下值:

    Value
    tcptestECHO_SERVER_ADDR0 192
    tcptestECHO_SERVER_ADDR1 168
    tcptestECHO_SERVER_ADDR2 2
    tcptestECHO_SERVER_ADDR3 6
  4. 打开 aws_test_tcp.h,将 tcptestSECURE_SERVER 宏设置为 0 以不使用 TLS 运行安全套接字测试。

  5. 打开 /vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner.config.h,然后将 testrunnerFULL_TCP_ENABLED 宏设置为 1 以启用套接字测试。

  6. 打开 /vendors/vendor/boards/board/aws_tests/application_code/main.c,然后删除 vApplicationIPNetworkEventHook ( void ) 定义中的 #if 0#endif 编译器指令以启用测试任务。

    注意

    此更改需要移植剩余的库。

重要

对于资格认证,您必须使用 TLS 通过安全套接字测试。移植 TLS 库之后,在启用 TLS 的情况下返回安全套接字测试,使用支持 TLS 的 Echo 服务器。

要移植 TLS 库,请参阅移植 TLS 库

在移植 TLS 库之后为安全套接字设置测试

  1. 启动安全的 Echo 服务器。

    有关信息,请参阅设置 Echo 服务器

  2. /tests/include/aws_test_tcp.h 中的 IP 地址和端口设置为适用于您的服务器的值。例如,如果您的服务器的 IP 地址为 192.168.2.6,并且服务器侦听 9000,请在 /tests/include/aws_test_tcp.h 中设置以下值:

    Value
    tcptestECHO_SERVER_TLS_ADDR0 192
    tcptestECHO_SERVER_TLS_ADDR1 168
    tcptestECHO_SERVER_TLS_ADDR2 2
    tcptestECHO_SERVER_TLS_ADDR3 6
    tcptestECHO_PORT_TLS 9000
  3. 打开 /tests/include/aws_test_tcp.h,然后将 tcptestSECURE_SERVER 宏设置为 1 以启用 TLS 测试。

  4. 下载受信任的根证书。有关接受的根证书和下载链接的信息,请参阅 AWS IoT 开发人员指南中的服务器身份验证。我们建议您使用 Amazon Trust Services 证书。

  5. 在浏览器窗口中,打开 /tools/certificate_configuration/PEMfileToCString.html

  6. PEM Certificate or Key (PEM 证书或密钥) 中,选择您下载的根 CA 文件。

  7. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到 aws_clientcredential_keys.h 中设置了格式的 PEM 字符串,然后复制证书字符串。

  8. 打开 aws_test_tcp.h,然后将设置了格式的证书字符串粘贴到 tcptestECHO_HOST_ROOT_CA 的定义中。

  9. 使用第二组 OpenSSL 命令 /tools/echo_server/readme-gencert.txt 生成由证书机构签名的客户端证书和私钥。证书和密钥使得自定义 Echo 服务器可以信任在 TLS 身份验证期间设备呈现的客户端证书。

  10. 使用 /tools/certificate_configuration/PEMfileToCString.html 格式工具设置证书和密钥格式。

  11. 在设备上构建和运行测试项目之前,打开 aws_clientcredential_keys.h,并将 PEM 格式的客户端证书和私有密钥复制到 keyCLIENT_CERTIFICATE_PEMkeyCLIENT_PRIVATE_KEY_PEM 的定义中。

运行测试

执行安全套接字测试

  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 库。有关说明,请参阅移植 PKCS #11 库