Secure Sockets 程式庫 - FreeRTOS
概觀相依性和要求功能故障診斷開發人員支援使用限制初始化API 參考範例使用方式移植

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Secure Sockets 程式庫

重要

此程式庫託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從這裡開始。如果您已經有以現在已棄用 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 Amazon-FreeRTOS Github 儲存庫遷移指南。 FreeRTOS

概觀

您可以使用 FreeRTOS Secure Sockets 程式庫來建立可安全通訊的內嵌應用程式。此程式庫的設計旨在讓來自各種網路程式設計背景的軟體開發人員都能夠輕鬆上線。

FreeRTOS Secure Sockets 程式庫是以 Berkeley 通訊端介面為基礎，並具有 TLS 通訊協定的其他安全通訊選項。如需 FreeRTOS Secure Sockets 程式庫與 Berkeley 通訊端介面之間的差異資訊，請參閱 Secure Sockets API 參考SOCKETS_SetSockOpt中的 。

注意

目前，FreeRTOS Secure Sockets 僅支援用戶端 APIs，以及伺服器端 Bind API 的輕量型 IP (lwIP) 實作。

相依性和要求

FreeRTOS Secure Sockets 程式庫取決於 TCP/IP 堆疊和 TLS 實作。FreeRTOS 連接埠透過下列三種方式之一來滿足這些相依性：

  • 同時自訂實作 TCP/IP 及 TLS

  • TCP/IP 的自訂實作，以及具有 mbedTLS 的 FreeRTOS TLS 層

  • FreeRTOS+TCP 和 FreeRTOS TLS layer with mbedTLS

以下相依性圖表顯示 FreeRTOS Secure Sockets 程式庫隨附的參考實作。此參考實作支援透過乙太網路和 Wi-Fi 的 TLS 和 TCP/IP，搭配做為相依性的 FreeRTOS+TCP 和 mbedTLS。如需 FreeRTOS TLS layer 的詳細資訊，請參閱Transport Layer Security。

使用 FreeRTOS+TCP、TLS Layer 和 TLS 元件的安全通訊端程式庫架構。

功能

FreeRTOS Secure Sockets 程式庫功能包括：

  • 標準 Berkeley 通訊端型界面

  • 用於傳送和接收資料的執行緒安全 API

  • 方便啟用 TLS

故障診斷

錯誤代碼

FreeRTOS Secure Sockets 程式庫傳回的錯誤碼是負值。如需每個錯誤碼的詳細資訊，請參閱 Secure Sockets API 參考中的 Secure Sockets 錯誤碼。

注意

如果 FreeRTOS Secure Sockets API 傳回錯誤碼，則coreMQTT 程式庫取決於 FreeRTOS Secure Sockets 程式庫的 會傳回錯誤碼 AWS_IOT_MQTT_SEND_ERROR。

開發人員支援

FreeRTOS Secure Sockets 程式庫包含兩個用於處理 IP 地址的協助程式巨集：

SOCKETS_inet_addr_quick

此巨集會依網路位元組順序將以四個單獨數字八位元表示的 IP 地址轉換為以 32 位元數字表示的 IP 地址。

SOCKETS_inet_ntoa

此巨集會依網路位元組順序將以 32 位元數字表示的 IP 地址轉換為以小數點表示法表示的字串。

使用限制

FreeRTOS Secure Sockets 程式庫僅支援 TCP 通訊端。不支援 UDP 通訊端。

FreeRTOS Secure Sockets 程式庫不支援伺服器 APIs，但伺服器端 Bind API 的輕量型 IP (lwIP) 實作除外。支援用戶端 APIs。

初始化

若要使用 FreeRTOS Secure Sockets 程式庫，您需要初始化程式庫及其相依性。若要初始化 Secure Sockets 程式庫，請在您的應用程式中使用下列程式碼：

BaseType_t xResult = pdPASS;
xResult = SOCKETS_Init();

必須個別初始化相依程式庫。例如，如果 FreeRTOS+TCP 是相依性，則您也需要在應用程式中呼叫 FreeRTOS_IPInit。

API 參考

如需完整的 API 參考，請參閱 Secure Sockets API 參考。

範例使用方式

以下程式碼會將用戶端連接到伺服器。

#include "aws_secure_sockets.h"

#define configSERVER_ADDR0                     127
#define configSERVER_ADDR1                     0
#define configSERVER_ADDR2                     0
#define configSERVER_ADDR3                     1
#define configCLIENT_PORT                      443

/* Rx and Tx timeouts are used to ensure the sockets do not wait too long for
 * missing data. */
static const TickType_t xReceiveTimeOut = pdMS_TO_TICKS( 2000 );
static const TickType_t xSendTimeOut = pdMS_TO_TICKS( 2000 );

/* PEM-encoded server certificate */
/* The certificate used below is one of the Amazon Root CAs.\
Change this to the certificate of your choice. */
static const char cTlsECHO_SERVER_CERTIFICATE_PEM[] =
"-----BEGIN CERTIFICATE-----\n"
"MIIBtjCCAVugAwIBAgITBmyf1XSXNmY/Owua2eiedgPySjAKBggqhkjOPQQDAjA5\n"
"MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6b24g\n"
"Um9vdCBDQSAzMB4XDTE1MDUyNjAwMDAwMFoXDTQwMDUyNjAwMDAwMFowOTELMAkG\n"
"A1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJvb3Qg\n"
"Q0EgMzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABCmXp8ZBf8ANm+gBG1bG8lKl\n"
"ui2yEujSLtf6ycXYqm0fc4E7O5hrOXwzpcVOho6AF2hiRVd9RFgdszflZwjrZt6j\n"
"QjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBSr\n"
"ttvXBp43rDCGB5Fwx5zEGbF4wDAKBggqhkjOPQQDAgNJADBGAiEA4IWSoxe3jfkr\n"
"BqWTrBqYaGFy+uGh0PsceGCmQ5nFuMQCIQCcAu/xlJyzlvnrxir4tiz+OpAUFteM\n"
"YyRIHN8wfdVoOw==\n"
"-----END CERTIFICATE-----\n";

static const uint32_t ulTlsECHO_SERVER_CERTIFICATE_LENGTH = sizeof( cTlsECHO_SERVER_CERTIFICATE_PEM );

void vConnectToServerWithSecureSocket( void )
{
    Socket_t xSocket;
    SocketsSockaddr_t xEchoServerAddress;
    BaseType_t xTransmitted, lStringLength;

    xEchoServerAddress.usPort = SOCKETS_htons( configCLIENT_PORT );
    xEchoServerAddress.ulAddress = SOCKETS_inet_addr_quick( configSERVER_ADDR0,
                                                            configSERVER_ADDR1,
                                                            configSERVER_ADDR2,
                                                            configSERVER_ADDR3 );
                                                            
    /* Create a TCP socket. */
    xSocket = SOCKETS_Socket( SOCKETS_AF_INET, SOCKETS_SOCK_STREAM, SOCKETS_IPPROTO_TCP );
    configASSERT( xSocket != SOCKETS_INVALID_SOCKET );
    
    /* Set a timeout so a missing reply does not cause the task to block indefinitely. */
    SOCKETS_SetSockOpt( xSocket, 0, SOCKETS_SO_RCVTIMEO, &xReceiveTimeOut, sizeof( xReceiveTimeOut ) );
    SOCKETS_SetSockOpt( xSocket, 0, SOCKETS_SO_SNDTIMEO, &xSendTimeOut, sizeof( xSendTimeOut ) );

    /* Set the socket to use TLS. */
    SOCKETS_SetSockOpt( xSocket, 0, SOCKETS_SO_REQUIRE_TLS, NULL, ( size_t ) 0 );
    SOCKETS_SetSockOpt( xSocket, 0, SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE, cTlsECHO_SERVER_CERTIFICATE_PEM, ulTlsECHO_SERVER_CERTIFICATE_LENGTH );

    if( SOCKETS_Connect( xSocket, &xEchoServerAddress, sizeof( xEchoServerAddress ) ) == 0 )
    {
        /* Send the string to the socket. */
        xTransmitted = SOCKETS_Send( xSocket,                         /* The socket receiving. */
                                     ( void * )"some message",        /* The data being sent. */
                                     12,                              /* The length of the data being sent. */
                                     0 );                             /* No flags. */

        if( xTransmitted < 0 )
        {
            /* Error while sending data */
            return;
        }

        SOCKETS_Shutdown( xSocket, SOCKETS_SHUT_RDWR );
    }
    else
    {
        //failed to connect to server
    }

    SOCKETS_Close( xSocket );
}

如需完整範例，請參閱 Secure Sockets echo 用戶端示範。

移植

FreeRTOS Secure Sockets 取決於 TCP/IP 堆疊和 TLS 實作。根據您的堆疊，若要移植 Secure Sockets 程式庫，您可能需要移植下列一些項目：

如需移植的詳細資訊，請參閱 FreeRTOS 移植指南中的移植 Secure Sockets Library。