Usare wolfSSL per connessioni TLS

Articolo
09/27/2024

Importante

Questa è la documentazione di Azure Sphere (legacy). Azure Sphere (legacy) viene ritirato il 27 settembre 2027 e gli utenti devono eseguire la migrazione ad Azure Sphere (integrato) entro questo periodo. Usare il selettore di versione posizionato sopra il sommario per visualizzare la documentazione di Azure Sphere (integrata).

Azure Sphere SDK include un subset della libreria wolfSSL per transport layer security (TLS), che le applicazioni di alto livello possono usare per creare connessioni TLS sicure.

Le informazioni di riferimento sull'API wolfSSL forniscono una documentazione completa dell'API wolfSSL, insieme a molti esempi. Azure Sphere supporta un subset dell'API che garantisce la compatibilità binaria.

Requisiti per le applicazioni che usano la libreria wolfSSL

Le applicazioni che usano la libreria wolfSSL devono includere i file di intestazione e la configurazione di compilazione necessari.

L'API TLS wolfSSL non richiede funzionalità nel manifesto dell'applicazione. Tuttavia, se l'applicazione si connette a un endpoint Internet, il manifesto dell'applicazione deve includere informazioni sulla connessione. Per altre informazioni sull'abilitazione della connettività, vedere Connettersi ai servizi Web.

File di intestazione

Le applicazioni che usano l'API wolfSSL devono includere il ssl.h file di intestazione e possono richiedere uno o più file di intestazione aggiuntivi, a seconda delle funzionalità wolfSSL in 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>

Vedere la documentazione di wolfSSL per determinare i file di intestazione richiesti dall'applicazione.

Configurazione della build

Per compilare un'applicazione con il supporto dell'API TLS wolfSSL, modificare i file CMakePresets.json e CMakeLists.txt per specificare il set di API di destinazione e collegare rispettivamente la libreria wolfSSL.

Impostare il TARGET_API_SET in CMakePresets.json su 6 o versione successiva.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Aggiungere wolfssl all'elenco di target_link_libraries in CMakeLists.txt per collegare la libreria wolfSSL al progetto:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Funzionalità supportate

Azure Sphere SDK supporta TLS sul lato client wolfSSL usando un certificato client fornito da Microsoft o un certificato o una scelta. Azure Sphere SDK supporta TLS lato server wolfSSL usando solo un certificato di propria scelta. Gli scenari non supportati rilevanti includono:

Solo le connessioni TLS sul lato client wolfSSL sono supportate con il certificato client fornito da Microsoft. Le connessioni TLS lato server non possono usare il certificato client fornito da Microsoft.
Un'applicazione può usare il supporto TLS wolfSSL predefinito oppure usare e collegare in un'altra implementazione della libreria wolfSSL. Tuttavia, l'uso misto del supporto predefinito con un'altra libreria wolfSSL non è supportato.

Usare wolfSSL in Azure Sphere

Le applicazioni Azure Sphere di alto livello possono usare wolfSSL per creare e comunicare tramite una connessione TLS. Le applicazioni devono in genere usare una combinazione delle tecniche per creare e comunicare tramite queste connessioni.

Nota

Per una maggiore sicurezza, le applicazioni devono usare wolfSSL_CTX_set_verify() per convalidare l'host. Per altre informazioni, vedere la documentazione di wolfSSL.

Inizializzare wolfSSL per le connessioni TLS client

Per creare una connessione TLS con wolfSSL, l'applicazione deve prima inizializzare la libreria e il contesto SSL (CTX), come nel frammento di codice seguente:

    // 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;
    }

Caricare il certificato

Dopo l'inizializzazione di wolfSSL, può caricare un certificato da usare con la connessione TLS. È possibile includere il certificato nel pacchetto immagine dell'applicazione, come descritto in Aggiungere certificati CA al pacchetto immagine.

L'esempio seguente illustra come un'app può usare Storage_GetAbsolutePathInImagePackage per ottenere il percorso di un certificato client che fa parte del pacchetto immagine dell'applicazione e quindi chiamare wolfSSL_CTX_load_verify_locations per caricare il certificato in wolfSSL. Si noti che l'app deve includere il storage.h file di intestazione per usare 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;
    }

Creare una connessione lato client

Dopo aver caricato il certificato, l'app può stabilire la connessione TLS. Questo passaggio comporta la creazione di un oggetto SSL, l'associazione a un descrittore socket e la creazione della connessione, come nell'esempio seguente:

    // 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;
    }

Leggere e scrivere dati dalla connessione

Per scrivere e leggere dati dalla connessione, l'applicazione può usare rispettivamente wolfSSL_write e wolfSSL_read, come illustrato nell'esempio seguente. In questo esempio, la scrittura nel server contiene una richiesta HTTP/1.1 standard per recuperare il contenuto della pagina. La documentazione in HTTP/1.1: Richiesta (w3.org) offre una panoramica di questa struttura. Si noti tuttavia che questo documento è stato sostituito ed è possibile trovare altri dettagli sulla struttura delle richieste nella sua sostituzione RFC 9110: Semantica 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);

Inizializzare wolfSSL per le connessioni lato server

Per creare un server TLS con wolfSSL, l'applicazione deve prima inizializzare la libreria e il contesto SSL (CTX), come nel frammento di codice seguente:

// 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;
    }

Accettare connessioni in ingresso usando il server TLS wolfSSL

Accettare connessioni in ingresso da un client al server Azure Sphere.

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

Pulizia

Quando l'applicazione viene eseguita usando la connessione, dovrebbe liberare le risorse correlate.

    free(certificatePath);

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

Esempio

Per un esempio della funzionalità WolfSSL nella piattaforma Azure Sphere, vedere WolfSSL_HighLevelApp.

Condividi tramite