Biblioteca de sockets seguros - FreeRTOS
Descripción generalDependencias y requisitosCaracterísticasSolución de problemasDeveloper SupportRestricciones de usoInicializaciónReferencia de la APIEjemplo de usoPortabilidad

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Biblioteca de sockets seguros

importante

Esta biblioteca está alojada en el repositorio de Amazon-FreeRTOS, que está en desuso. Recomendamos empezar por aquí al crear un nuevo proyecto. Si ya tiene un proyecto FreeRTOS existente basado en el repositorio Amazon FreeRTOS, ahora obsoleto, consulte Guía de migración del repositorio Github de Amazon-FreeRTOS.

Descripción general

Puede utilizar la biblioteca de sockets seguros de FreeRTOS para crear aplicaciones integradas que se comunican de forma segura. La biblioteca se ha diseñado para facilitar la incorporación de desarrolladores de software de diversos antecedentes de programación de red.

La biblioteca de sockets seguros de FreeRTOS se basa en la interfaz de sockets de Berkeley, con una opción de comunicación segura adicional mediante el protocolo TLS. Para obtener más información acerca de las diferencias entre la biblioteca de sockets seguros de FreeRTOS y la interfaz de sockets de Berkeley, consulte SOCKETS_SetSockOpt en la Referencia de la API de sockets seguros.

nota

Actualmente, solo el cliente APIs, más una implementación IP ligera (LWiP) de la API del Bind lado del servidor, son compatibles con FreeRTOS Secure Sockets.

Dependencias y requisitos

La biblioteca de sockets seguros de FreeRTOS depende de una pila TCP/IP y de una implementación de TLS. Las portabilidades para FreeRTOS cumplen estas dependencias en una de las tres formas:

  • Una implementación personalizada de TCP/IP y TLS

  • Una implementación personalizada de TCP/IP y la capa TLS de FreeRTOS con mbedTLS

  • FreeRTOS+TCP y la capa TLS de FreeRTOS con mbedTLS

El diagrama de dependencias siguiente muestra la implementación de referencia incluida con la biblioteca de sockets seguros de FreeRTOS. Esta implementación de referencia admite TLS y TCP/IP a través de Ethernet y Wi-Fi con FreeRTOS+TCP y mbedTLS como dependencias. Para obtener más información acerca de la capa TLS de FreeRTOS, consulte Transport Layer Security.

Arquitectura de biblioteca de sockets seguros con componentes FreeRTOS+TCP, TLS Layer y TLS.

Características

Las características de la biblioteca de sockets seguros de FreeRTOS incluyen:

  • Una interfaz estándar basada en sockets Berkeley

  • Seguro para subprocesos para enviar y recibir datos APIs

  • Easy-to-enable TLS

Solución de problemas

Códigos de error

Los códigos de error que la biblioteca de sockets seguros de FreeRTOS devuelve son valores negativos. Para obtener más información acerca de cada código de error, consulte Códigos de error de sockets seguros en la Referencia de la API de sockets seguros.

nota

Si la API de sockets seguros de FreeRTOS devuelve un código de error, Biblioteca coreMQTT, que depende de la biblioteca de sockets seguros de FreeRTOS devuelve el código de error AWS_IOT_MQTT_SEND_ERROR.

Developer Support

La biblioteca de sockets seguros de FreeRTOS incluye dos macros auxiliares para gestionar las direcciones IP:

SOCKETS_inet_addr_quick

Esta macro convierte una dirección IP que se expresa como cuatro octetos numéricos independientes en una dirección IP que se expresa como un número de 32 bits en orden de bytes de red.

SOCKETS_inet_ntoa

Esta macro convierte una dirección IP que se expresa como un número de 32 bits en orden de bytes de red en una cadena en notación decimal con puntos.

Restricciones de uso

Solo se admiten sockets de TCP mediante la biblioteca de sockets seguros de FreeRTOS. No se admiten los sockets de UDP.

La biblioteca de sockets seguros APIs FreeRTOS no admite servidores, excepto para una implementación IP ligera (LWiP) de la API del lado del servidor. Bind Los clientes son compatibles. APIs

Inicialización

Para utilizar la biblioteca de sockets seguros de FreeRTOS, tiene que inicializar la biblioteca y sus dependencias. Para inicializar la biblioteca de sockets seguros, utilice el siguiente código en su aplicación:

BaseType_t xResult = pdPASS;
xResult = SOCKETS_Init();

Las bibliotecas dependientes deben inicializarse por separado. Por ejemplo, si FreeRTOS+TCP es una dependencia, necesita invocar también FreeRTOS_IPInit en su aplicación.

Referencia de la API

Para obtener una referencia completa de la API, consulte la Referencia de la API de sockets seguros.

Ejemplo de uso

Con el siguiente código se conecta un cliente a un servidor.

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

Para ver un ejemplo completo, consulte Demostración de cliente de echo de sockets seguros.

Portabilidad

Los sockets seguros de FreeRTOS dependen de una pila TCP/IP y de una implementación de TLS. En función de la pila, para realizar la portabilidad de la biblioteca de sockets seguros, es posible que tenga que trasladar algunos de los siguientes:

Para obtener más información sobre la portabilidad, consulte Portabilidad de la biblioteca de sockets seguros en la Guía de portabilidad de FreeRTOS.