Secure-Sockets-Bibliothek

Wichtig

Diese Bibliothek wird im Amazon-FreeRTOS-Repository gehostet, das veraltet ist. Wir empfehlen Ihnen, hier zu beginnen, wenn Sie ein neues Projekt erstellen. Wenn Sie bereits über ein vorhandenes FreeRTOS-Projekt verfügen, das auf dem jetzt veralteten Amazon-FreeRTOS-Repository basiert, finden Sie weitere Informationen unter Leitfaden zur Migration des Amazon-FreerTOS Github-Repositorys.

Übersicht

Sie können die FreeRTOS Secure Sockets-Bibliothek verwenden, um eingebettete Anwendungen zu erstellen, die sicher kommunizieren. Die Bibliothek dient dem einfachen Einstieg von Softwareentwicklern mit unterschiedlichem Hintergrund im Bereich Netzwerkprogrammierung.

Die FreeRTOS Secure Sockets-Bibliothek basiert auf der Berkeley-Sockets-Schnittstelle mit einer zusätzlichen sicheren Kommunikationsoption durch das TLS-Protokoll. Informationen zu den Unterschieden zwischen der FreeRTOS Secure Sockets-Bibliothek und der Berkeley-Sockets-Schnittstelle finden Sie unter SOCKETS_SetSockOpt in der Secure Sockets-API-Referenz.

Anmerkung

Derzeit werden nur Client-APIs sowie eine leichte IP-Implementierung (lwIP) der serverseitigen Bind API für FreeRTOS Secure Sockets unterstützt.

Abhängigkeiten und Anforderungen

Die FreeRTOS Secure Sockets-Bibliothek hängt von einem TCP/IP-Stack und einer TLS-Implementierung ab. Ports für FreeRTOS erfüllen diese Abhängigkeiten auf eine von drei Arten:

• Eine benutzerdefinierte Implementierung von TCP/IP und TLS

• Eine benutzerdefinierte Implementierung von TCP/IP und der FreeRTOS-TLS-Ebene mit mbedTLS

• FreeRTOS +TCP und die FreeRTOS-TLS-Ebene mit mbedTLS

Das Abhängigkeitsdiagramm unten zeigt die Referenzimplementierung, die in der FreeRTOS Secure Sockets-Bibliothek enthalten ist. Diese Referenzimplementierung unterstützt TLS und TCP/IP über Ethernet und WLAN mit FreeRTOS+TCP- und mbedTLS als Abhängigkeiten. Weitere Informationen zur FreeRTOS-TLS-Ebene finden Sie unter Transport Layer Security.

Features

Zu den Features der FreeRTOS Secure Sockets-Bibliothek gehören:

• Eine Standard-, Berkeley-Sockets-basierte Schnittstelle

• Threadsichere APIs zum Senden und Empfangen von Daten

• Easy-to-enable -TLS

Fehlerbehebung

Fehlercodes

Die Fehlercodes, die die FreeRTOS Secure Sockets-Bibliothek zurückgibt, sind negative Werte. Weitere Informationen zu den einzelnen Fehlercodes finden Sie unter „Secure Sockets-Fehlercodes“ in der Secure Sockets API-Referenz.

Anmerkung

Wenn die FreeRTOS Secure Sockets-API einen Fehlercode zurückgibt, gibt die CoreMQTT-Bibliothek, die von der FreeRTOS Secure Sockets-Bibliothek abhängt, den Fehlercode zurückAWS_IOT_MQTT_SEND_ERROR.

Developer Support

Die Bibliothek FreeRTOS Secure Sockets enthält zwei Hilfsmakros für die Verarbeitung von IP-Adressen:

SOCKETS_inet_addr_quick

Dieses Makro wandelt eine IP-Adresse, die als vier separate numerische Oktette ausgedrückt wird, in eine IP-Adresse um, die als 32-Bit-Zahl in Netzwerk-Byte-Reihenfolge ausgedrückt wird.

SOCKETS_inet_ntoa

Dieses Makro wandelt eine IP-Adresse, die als 32-Bit-Zahl in Netzwerk-Byte-Reihenfolge ausgedrückt wird, in eine Zeichenkette in Dezimalpunkt-Notation um.

Nutzungsbeschränkungen

Nur TCP-Sockets werden von der FreeRTOS Secure Sockets-Bibliothek unterstützt. UDP-Sockets werden nicht unterstützt.

Server-APIs werden von der FreeRTOS Secure Sockets-Bibliothek nicht unterstützt, mit Ausnahme einer leichtgewichtigen IP-Implementierung (lwIP) der serverseitigen Bind API. Client-APIs werden unterstützt.

Initialisierung

Um die FreeRTOS Secure Sockets-Bibliothek verwenden zu können, müssen Sie die Bibliothek und ihre Abhängigkeiten initialisieren. Um die Secure-Sockets-Bibliothek zu initialisieren, verwenden Sie den folgenden Code in Ihrer Anwendung:

BaseType_t xResult = pdPASS;
xResult = SOCKETS_Init();

Abhängige Bibliotheken müssen separat initialisiert werden. Beispiel: Wenn FreeRTOS+TCP eine Abhängigkeit ist, müssen Sie auch FreeRTOS_IPInit in Ihrer Anwendung aufrufen.

API-Referenz

Eine vollständige API-Referenz finden Sie unter Secure Sockets API Reference.

Beispielverwendung

Der folgende Code verbindet einen Client mit einem Server.

#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 );
}

Ein vollständiges Beispiel finden Sie unter Secure Sockets Echo-Client-Demo.

Portierung

FreeRTOS Secure Sockets hängt von einem TCP/IP-Stack und einer TLS-Implementierung ab. Abhängig von Ihrem Stack müssen Sie für die Portierung der Secure-Sockets-Bibliothek möglicherweise einige der folgenden Portierungen vornehmen:

• Der FreeRTOS+TCP-TCP/IP-Stack

• Die Coerbibliothek PKS11

• Die Transport Layer Security

Weitere Informationen zur Portierung finden Sie unter Portieren der Secure Sockets Library im FreeRTOS-Portierungshandbuch.