Partilhar via

Utilizar wolfSSL para ligações TLS

  • Artigo

O SDK do Azure Sphere inclui um subconjunto da biblioteca wolfSSL para transport layer security (TLS), que as aplicações de alto nível podem utilizar para criar ligações TLS seguras.

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

Requisitos para aplicações que utilizam a biblioteca wolfSSL

As aplicações que utilizam a biblioteca wolfSSL têm de incluir os ficheiros de cabeçalho necessários e a configuração da compilação.

A API wolfSSL TLS não requer capacidades no manifesto da aplicação. No entanto, se a aplicação se ligar a um ponto final da Internet, o manifesto da aplicação tem de incluir informações sobre a ligação. Veja Ligar aos serviços Web para obter mais detalhes sobre como ativar a conectividade.

Ficheiros de cabeçalho

As aplicações que utilizam a API wolfSSL têm de incluir o ssl.h ficheiro de cabeçalho e podem necessitar de um ou mais ficheiros de cabeçalho adicionais, consoante as funcionalidades wolfSSL em utilização:

#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>

Veja a documentação wolfSSL para determinar quais os ficheiros de cabeçalho necessários para a sua aplicação.

Configuração da compilação

Para criar uma aplicação com suporte para a API wolfSSL TLS, edite os ficheiros CMakePresets.json e CMakeLists.txt para especificar o conjunto de API de destino e ligar a biblioteca wolfSSL, respetivamente.

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

    "AZURE_SPHERE_TARGET_API_SET": "6"

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

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

Funcionalidades suportadas

O SDK do Azure Sphere suporta o wolfSSL TLS do lado do cliente através de um certificado de cliente fornecido pela Microsoft, um certificado ou a sua escolha. O SDK do Azure Sphere suporta o TLS wolfSSL do lado do servidor utilizando apenas um certificado à sua escolha. Cenários não suportados importantes incluem:

  • Apenas as ligações TLS do lado do cliente wolfSSL são suportadas com o certificado de cliente fornecido pela Microsoft. As ligações TLS do lado do servidor não podem utilizar o certificado de cliente fornecido pela Microsoft.

  • Uma aplicação pode utilizar o suporte incorporado wolfSSL TLS ou utilizar e ligar noutra implementação da biblioteca wolfSSL. No entanto, a utilização mista do suporte incorporado com outra biblioteca wolfSSL não é suportada.

Utilizar wolfSSL no Azure Sphere

As aplicações de alto nível do Azure Sphere podem utilizar wolfSSL para criar e comunicar através de uma ligação TLS. Normalmente, as aplicações têm de utilizar uma combinação das técnicas para criar e comunicar através destas ligações.

Nota

Para uma segurança melhorada, as aplicações devem utilizar wolfSSL_CTX_set_verify() para validar o anfitrião. Veja a documentação wolfSSL para obter mais informações.

Inicializar wolfSSL para ligações TLS cliente

Para criar uma ligação TLS com wolfSSL, a aplicação tem primeiro de inicializar a biblioteca e o contexto SSL (CTX), tal como no seguinte fragmento 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 de o wolfSSL ser inicializado, pode carregar um certificado para utilização com a ligação TLS. Pode incluir o certificado no pacote de imagem da aplicação, conforme descrito em Adicionar certificados de AC ao pacote de imagem.

O exemplo seguinte mostra como uma aplicação pode utilizar Storage_GetAbsolutePathInImagePackage para obter o caminho para um certificado de cliente que faz parte do pacote de imagem da aplicação e, em seguida, chamar wolfSSL_CTX_load_verify_locations para carregar o certificado para wolfSSL. Tenha em atenção que a aplicação tem de incluir o storage.h ficheiro de cabeçalho para utilizar 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 ligação do lado do cliente

Depois de carregar o certificado, a aplicação pode estabelecer a ligação TLS. Este passo envolve criar um objeto SSL, associá-lo a um descritor de socket e, em seguida, criar a ligaçã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 escrever dados a partir da ligação

Para escrever e ler dados da ligação, a aplicação pode utilizar wolfSSL_write e wolfSSL_read, respetivamente, como mostra o exemplo seguinte. Neste exemplo, a escrita no servidor contém um pedido HTTP/1.1 padrão para obter o conteúdo da página. A documentação em HTTP/1.1: Request (w3.org) fornece uma boa descrição geral desta estrutura. No entanto, tenha em atenção que este documento foi substituído e pode encontrar mais detalhes sobre a estrutura do pedido no respetivo RFC 9110 de substituição: Semântica HTTP (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);

Inicializar wolfSSL para ligações do lado do servidor

Para criar um servidor TLS com wolfSSL, a aplicação tem primeiro de inicializar a biblioteca e o contexto SSL (CTX), tal como no seguinte fragmento 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;
    }

Aceitar ligações recebidas com o servidor WolfSSL TLS

Aceite ligaçõ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 a aplicação terminar de utilizar a ligação, deve libertar os recursos relacionados.

    free(certificatePath);

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

Exemplo

Para obter uma amostra da funcionalidade WolfSSL na plataforma do Azure Sphere, veja WolfSSL_HighLevelApp.