As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Biblioteca de Secure Sockets **Importante** Essa biblioteca está hospedada no repositório Amazon-FreeRTOS, que está preterido. Recomendamos [começar aqui](freertos-getting-started-modular.md) ao criar um novo projeto. Se você já tem um projeto FreeRTOS existente baseado no repositório Amazon-FreeRTOS que está preterido, consulte o [Guia de migração do repositório Github do Amazon FreeRTOS](github-repo-migration.md). ## Visão geral do Use a biblioteca de [Secure Sockets](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/secure_sockets/index.html) do FreeRTOS para criar aplicações incorporadas que se comunicam de maneira segura. A biblioteca foi projetada para facilitar a integração de desenvolvedores de software de várias bases de programação de rede. A biblioteca de Secure Sockets do FreeRTOS se baseia na interface de soquetes Berkeley, com uma opção de comunicação segura adicional por protocolo TLS. Para obter informações sobre as diferenças entre a biblioteca de Secure Sockets do FreeRTOS e a interface de soquetes Berkeley, consulte `SOCKETS_SetSockOpt` na [Referência de API de Secure Sockets](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/secure_sockets/index.html). **nota** Atualmente, somente o cliente APIs, além de uma implementação [IP leve (LWIP](https://savannah.nongnu.org/projects/lwip/)) da API do `Bind` lado do servidor, são compatíveis com os Freertos Secure Sockets. ## Dependências e requisitos A biblioteca FreeRTOS Secure Sockets depende de TCP/IP uma pilha e de uma implementação de TLS. As portas para o FreeRTOS atendem a essas dependências em uma de três maneiras: + Uma implementação personalizada de ambos TCP/IP e do TLS + Uma implementação personalizada de TCP/IP, e a camada TLS do FreeRTOS com [mbedTLS](https://en.wikipedia.org/wiki/Mbed_TLS) + [FreeRTOS\$1TCP](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/index.html) e a camada TLS do FreeRTOS com [mbedTLS](https://en.wikipedia.org/wiki/Mbed_TLS) O diagrama de dependências abaixo mostra a implementação de referência inclusa com a biblioteca de Secure Sockets do FreeRTOS. Essa implementação de referência oferece suporte a TLS e TCP/IP por Ethernet e Wi-Fi com FreeRTOS\$1TCP e mbedTLS como dependências. Para obter mais informações sobre a camada TLS do FreeRTOS, consulte [Transport Layer Security](security-tls.md). ![\[Arquitetura da biblioteca de Secure Sockets com FreeRTOS+TCP, camada TLS e componentes TLS.\]](http://docs.aws.amazon.com/pt_br/freertos/latest/userguide/images/sockets-dependencies.png) ## Recursos Os recursos da biblioteca de Secure Sockets do FreeRTOS incluem: + Uma interface padrão baseada em soquetes Berkeley + Thread-safe APIs para enviar e receber dados + Easy-to-enable TLS ## Solução de problemas ### Códigos de erro Os códigos de erro que a biblioteca de Secure Sockets do FreeRTOS retorna são valores negativos. Para obter mais informações sobre cada código de erro, consulte Códigos de erro de Secure Sockets na [Referência da API de Secure Sockets](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/secure_sockets/index.html). **nota** Se a API de Secure Sockets do FreeRTOS retornar um código de erro, o [Biblioteca coreMQTT](coremqtt.md), que depende da biblioteca de Secure Sockets do FreeRTOS, retorna o código de erro `AWS_IOT_MQTT_SEND_ERROR`. ## Suporte ao desenvolvedor A biblioteca de Secure Sockets do FreeRTOS inclui duas macros auxiliares para manuseio de endereços IP: **`SOCKETS_inet_addr_quick`** Essa macro converte um endereço IP expresso por quatro octetos numéricos separados em um endereço IP expresso como um número de 32 bits em ordem de bytes de rede. **`SOCKETS_inet_ntoa`** Essa macro converte um endereço IP expresso como um número de 32 bits em ordem de bytes de rede em uma string com notação de ponto decimal. ## Restrições de uso Somente soquetes TCP são compatíveis com a biblioteca de Secure Sockets do FreeRTOS. Os soquetes UDP não são compatíveis. APIs Os servidores não são suportados pela biblioteca FreeRTOS Secure Sockets, exceto por uma implementação de [IP leve (LWIP)](https://savannah.nongnu.org/projects/lwip/) da API do lado do servidor. `Bind` O cliente APIs é suportado. ## Inicialização Para usar a biblioteca de Secure Sockets do FreeRTOS, é necessário inicializar a biblioteca e suas dependências. Para inicializar a biblioteca de Secure Sockets, use o seguinte código na aplicação: ``` BaseType_t xResult = pdPASS; xResult = SOCKETS_Init(); ``` As bibliotecas dependentes devem ser inicializadas separadamente. Por exemplo, se FreeRTOS\$1TCP for uma dependência, também é necessário invocar [https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/API/FreeRTOS_IPInit.html](https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/API/FreeRTOS_IPInit.html) na aplicação. ## Referência de API Para obter uma referência completa de API, consulte [Referência de API do Secure Sockets](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/secure_sockets/index.html). ## Exemplo de uso O código a seguir conecta um cliente a um 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 obter um exemplo completo, consulte [Demonstração do cliente Echo de Secure Sockets](secure-sockets-demo.md). ## Portabilidade Os FreeRTOS Secure Sockets dependem de TCP/IP uma pilha e de uma implementação de TLS. Dependendo da pilha, para transferir a biblioteca de Secure Sockets, será necessário transferir alguns dos seguintes: + A pilha [FreeRTOS\$1TCP](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/index.html) TCP/IP + A [PKCS11 biblioteca principal](security-pkcs.md) + A [Transport Layer Security](security-tls.md) Para obter mais informações sobre portabilidade, consulte [Portabilidade da biblioteca de Secure Sockets](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ss.html) no Guia de portabilidade do FreeRTOS.