Usar wolfSSL para conexões TLS

O SDK do Azure Sphere inclui um subconjunto da biblioteca wolfSSL para TLS (Transport Layer Security), que aplicativos de alto nível podem usar para criar conexões TLS seguras.

A referência da API wolfSSL fornece documentação completa da API wolfSSL, juntamente com muitos exemplos. O Azure Sphere dá suporte a um subconjunto da API que garante a compatibilidade binária.

Requisitos para aplicativos que usam a biblioteca wolfSSL

Os aplicativos que usam a biblioteca wolfSSL devem incluir os arquivos de cabeçalho necessários e a configuração de compilação.

A API TLS wolfSSL não requer recursos no manifesto do aplicativo. No entanto, se o aplicativo se conectar a um ponto de extremidade da Internet, o manifesto do aplicativo deverá incluir informações sobre a conexão. Consulte Conectar-se a serviços Web para obter mais detalhes sobre como ativar a conectividade.

Arquivos de cabeçalho

Os aplicativos que usam a API wolfSSL devem incluir o arquivo de ssl.h cabeçalho e podem exigir um ou mais arquivos de cabeçalho adicionais, dependendo dos recursos wolfSSL em uso:

#include <wolfssl/wolfcrypt/ecc.h>
#include <wolfssl/wolfcrypt/error-crypt.h>
#include <wolfssl/wolfcrypt/random.h>
#include <wolfssl/wolfcrypt/types.h>
#include <wolfssl/ssl.h>

Consulte a documentação do wolfSSL para determinar quais arquivos de cabeçalho seu aplicativo exige.

Configuração de compilação

Para criar um aplicativo com suporte à API TLS wolfSSL, edite os arquivos CMakePresets.json e CMakeLists.txt para especificar o conjunto de APIs de destino e vincular a biblioteca wolfSSL, respectivamente.

1. Defina o TARGET_API_SET em CMakePresets.json para 6 ou superior.

   "AZURE_SPHERE_TARGET_API_SET": "6"
   

2. Adicione wolfssl à lista de target_link_libraries em CMakeLists.txt para vincular a biblioteca wolfSSL ao projeto:

   target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
   

Recursos com suporte

O SDK do Azure Sphere dá suporte ao TLS wolfSSL do lado do cliente usando um certificado de cliente fornecido pela Microsoft ou um certificado de sua escolha. O SDK do Azure Sphere dá suporte ao TLS wolfSSL do lado do servidor usando apenas um certificado de sua escolha. Cenários sem suporte notáveis incluem:

• Somente conexões TLS do lado do cliente wolfSSL são suportadas com o certificado de cliente fornecido pela Microsoft. As conexões TLS do lado do servidor não podem usar o certificado de cliente fornecido pela Microsoft.

• Um aplicativo pode usar o suporte interno ao TLS wolfSSL ou usar e vincular outra implementação da biblioteca wolfSSL. No entanto, o uso misto do suporte integrado com outra biblioteca wolfSSL não é suportado.

Usar wolfSSL no Azure Sphere

Os aplicativos de alto nível do Azure Sphere podem usar wolfSSL para criar e se comunicar por meio de uma conexão TLS. Os aplicativos normalmente devem usar uma combinação das técnicas para criar e se comunicar por meio dessas conexões.

Inicialize wolfSSL para conexões TLS do cliente

Para criar uma conexão TLS com wolfSSL, o aplicativo primeiro deve inicializar a biblioteca e o contexto SSL (CTX), como no seguinte trecho de código:

    // Configure the wolfSSL library

    if (wolfSSL_Init() != WOLFSSL_SUCCESS) {
        Log_Debug("Error initializing wolfSSL library.\n");
        goto cleanupLabel;
    }

    // Configure wolfSSL CTX functionality

    WOLFSSL_METHOD *wolfSslMethod = wolfTLSv1_3_client_method();
    if (wolfSslMethod == NULL) {
        Log_Debug("Unable to allocate TLS v1.3 method.\n");
        goto cleanupLabel;
    }

    WOLFSSL_CTX *wolfSslCtx = wolfSSL_CTX_new(wolfSslMethod);
    if (wolfSslCtx == NULL) {
        Log_Debug("Unable get create SSL context.\n");
        goto cleanupLabel;
    }

Carregar o certificado

Depois que o wolfSSL é inicializado, ele pode carregar um certificado para uso com a conexão TLS. Você pode incluir o certificado no pacote de imagens do aplicativo, conforme descrito em Adicionar certificados de autoridade de certificação ao pacote de imagens.

O exemplo a seguir mostra como um aplicativo pode usar o Storage_GetAbsolutePathInImagePackage para obter o caminho para um certificado de cliente que faz parte do pacote de imagem do aplicativo e, em seguida, chamá wolfSSL_CTX_load_verify_locations lo para carregar o certificado em wolfSSL. Observe que o aplicativo deve incluir o storage.h arquivo de cabeçalho para usar Storage_GetAbsolutePathInImagePackage.

   #include <applibs/storage.h>
   ...

    // Get the full path to the certificate file used to authenticate the HTTPS server identity.
    // The .pem file is the certificate that is used to verify the
    // server identity.

    certificatePath = Storage_GetAbsolutePathInImagePackage("certs/YourDesiredCert.pem");
    if (certificatePath == NULL) {
        Log_Debug("The certificate path could not be resolved: errno=%d (%s)\n", errno,
                  strerror(errno));
        goto cleanupLabel;
    }

    // Load the client certificate into wolfSSL
    if (wolfSSL_CTX_load_verify_locations(ctx, certificatePath, NULL) != WOLFSSL_SUCCESS) {
        Log_Debug("Error loading certificate.\n");
        goto cleanupLabel;
    }

Criar uma conexão do lado do cliente

Depois de carregar o certificado, o aplicativo pode estabelecer a conexão TLS. Esta etapa envolve a criação de um objeto SSL, associando-o a um descritor de soquete e, em seguida, criando a conexão, como neste exemplo:

    // Create the SSL object
    if ((ssl = wolfSSL_new(ctx)) == NULL) {
        Log_Debug("Error creating final SSL object.\n");
        goto cleanupLabel;
    }

    // Attach the socket file descriptor to wolfSSL
    if (wolfSSL_set_fd(ssl, sockfd) != WOLFSSL_SUCCESS) {
        Log_Debug("Error attaching socket fd to wolfSSL.\n");
        goto cleanupLabel;
    }

    // Call Connect for incoming connections
    if (wolfSSL_connect(ssl) != WOLFSSL_SUCCESS) {
        Log_Debug("Error establishing TLS connection to host.\n");
        goto cleanupLabel;
    }

Ler e gravar dados da conexão

Para gravar e ler dados da conexão, o aplicativo pode usar wolfSSL_write e wolfSSL_read, respectivamente, como mostra o exemplo a seguir. Neste exemplo, a gravação no servidor contém uma solicitação HTTP/1.1 padrão para recuperar o conteúdo da página. A documentação em HTTP/1.1: Request (w3.org) fornece uma boa visão geral dessa estrutura. No entanto, observe que este documento foi substituído e você pode encontrar mais detalhes sobre a estrutura de solicitação em sua substituição RFC 9110: HTTP Semantics (rfc-editor.org).

    sprintf(buffer, "GET / HTTP/1.1\r\nHost: example.com\r\nAccept: */*\r\n\r\n");
    ret = wolfSSL_write(ssl, buffer, (int)strlen(buffer));
    if (ret != strlen(buffer)) {
        Log_Debug("Error writing GET command to server.\n");
        goto cleanupLabel;
    }

    // Read the data back
    ret = wolfSSL_read(ssl, buffer, BUFFER_SIZE);
    if (ret == -1) {
        Log_Debug("Error reading from host.\n");
        goto cleanupLabel;
    }

    Log_Debug("Received %d bytes from host.\n", ret);
    Log_Debug("%s\n", buffer);

Inicialize wolfSSL para conexões do lado do servidor

Para criar um servidor TLS com wolfSSL, o aplicativo deve primeiro inicializar a biblioteca e o contexto SSL (CTX), como no seguinte trecho de código:

// Configure wolfSSL CTX functionality
    WOLFSSL_METHOD *wolfSslMethod = wolfTLSv1_3_server_method();
    if (wolfSslMethod) == NULL) {
        Log_Debug("Unable to allocate TLS v1.3 method\n");
        goto cleanupLabel;
    }

    WOLFSSL_CTX *wolfSslCtx = wolfSSL_CTX_new(wolfSslMethod);
    if (wolfSslCtx == NULL) {
        Log_Debug("Unable to create SSL context.\n");
        goto cleanupLabel;
    }

Aceite conexões de entrada usando o servidor TLS wolfSSL

Aceite conexões de entrada de um cliente para o servidor do Azure Sphere.

    // Call Accept for incoming connections
    if (wolfSSL_accept(ssl) != WOLFSSL_SUCCESS) {
        Log_Debug("Error establishing TLS connection to host.\n");
        goto cleanupLabel;
    }

Limpeza

Quando o aplicativo terminar de usar a conexão, ele deverá liberar os recursos relacionados.

    free(certificatePath);

    if (ssl) {
        wolfSSL_free(ssl);
    }
    if (ctx) {
        wolfSSL_CTX_free(ctx);
        wolfSSL_Cleanup();
    }

Amostra

Para obter um exemplo da funcionalidade WolfSSL na plataforma Azure Sphere, consulte WolfSSL_HighLevelApp.