Condividi tramite

Usare wolfSSL per connessioni TLS

  • Articolo

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

Il riferimento API wolfSSL fornisce una documentazione dettagliata dell'API wolfSSL, insieme a molti esempi. Azure Sphere supporta un sottoinsieme dell'API che garantisce la compatibilità binaria.

Requisiti per le applicazioni che utilizzano la libreria wolfSSL

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

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

Consulta la documentazione wolfSSL per determinare quali file di intestazione richiede l'applicazione.

Configurazione della build

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

  1. Impostare il TARGET_API_SET in CMakePresets.json su 6 o superiore.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. Aggiungi 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)

Caratteristiche supportate

Azure Sphere SDK supporta client-side wolfSSL TLS utilizzando un certificato client fornito da Microsoft o un certificato o a tua scelta. Azure Sphere SDK supporta wolfSSL TLS sul lato server usando solo un certificato di tua scelta. Gli scenari non supportati significativi includono:

  • Solo le connessioni TLS 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ò utilizzare il supporto integrato wolfSSL TLS o utilizzare e collegare in un'altra implementazione libreria wolfSSL. Tuttavia, l'uso misto del supporto incorporato 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 in genere devono usare una combinazione delle tecniche per creare e comunicare tramite queste connessioni.

Nota

Per la sicurezza avanzata, le applicazioni devono usare wolfSSL_CTX_set_verify() per convalidare l'host. Vedi la documentazione wolfSSL per ulteriori informazioni.

Inizializzare wolfSSL per 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 per l'uso con la connessione TLS. È possibile includere il certificato nel pacchetto di immagini dell'applicazione, come descritto in Aggiungere certificati CA al pacchetto immagine.

L'esempio seguente mostra come un'app può usare Storage_GetAbsolutePathInImagePackage per ottenere il percorso a un certificato client che fa parte del pacchetto di immagini dell'applicazione e quindi chiamare wolfSSL_CTX_load_verify_locations per caricare il certificato in wolfSSL. Tieni presente 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 implica la creazione di un oggetto SSL, l'associazione con un descrittore del socket e quindi la creazione della connessione, come in questo esempio:

    // 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 disponibile all'indirizzo HTTP/1.1: Request (w3.org) fornisce una buona panoramica di questa struttura. Tuttavia, si noti che questo documento è stato sostituito e si possono trovare ulteriori dettagli sulla struttura di richiesta nella sua sostituzione 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);

Inizializza 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 utilizzando il server TLS wolfSSL

Accettare le 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;
    }

Pulitura

Al termine dell'uso della connessione, l'applicazione 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 sulla piattaforma Azure Sphere, vedi WolfSSL_HighLevelApp.