Dela via

Använda wolfSSL för TLS-anslutningar

  • Artikel

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

Azure Sphere SDK innehåller en delmängd av wolfSSL-biblioteket för transportnivåsäkerhet (TLS), som högnivåprogram kan använda för att skapa säkra TLS-anslutningar.

WolfSSL API-referensen innehåller omfattande dokumentation om wolfSSL-API:et, tillsammans med många exempel. Azure Sphere stöder en delmängd av API :et som säkerställer binär kompatibilitet.

Krav för program som använder wolfSSL-biblioteket

Program som använder wolfSSL-biblioteket måste innehålla nödvändiga huvudfiler och byggkonfiguration.

WolfSSL TLS API kräver inte funktioner i programmanifestet. Men om programmet ansluter till en Internetslutpunkt måste programmanifestet innehålla information om anslutningen. Mer information om hur du aktiverar anslutning finns i Ansluta till webbtjänster .

Rubrikfiler

Program som använder wolfSSL-API:et ssl.h måste innehålla huvudfilen och kan kräva en eller flera ytterligare huvudfiler, beroende på vilka wolfSSL-funktioner som används:

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

Se wolfSSL-dokumentationen för att avgöra vilka huvudfiler som programmet kräver.

Skapa konfiguration

Om du vill skapa ett program med stöd för wolfSSL TLS API redigerar du filerna CMakePresets.json och CMakeLists.txt för att ange mål-API-uppsättningen och länka wolfSSL-biblioteket.

  1. Ange TARGET_API_SET i CMakePresets.json till 6 eller högre.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. Lägg till wolfssl i listan över target_link_libraries i CMakeLists.txt för att länka wolfSSL-biblioteket till projektet:

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

Funktioner som stöds

Azure Sphere SDK stöder wolfSSL TLS på klientsidan med hjälp av ett Microsoft-tillhandahållet klientcertifikat eller ett certifikat eller ditt val. Azure Sphere SDK stöder wolfSSL TLS på serversidan med endast ett valfritt certifikat. Några viktiga scenarier som inte stöds är:

  • Endast wolfSSL-TLS-anslutningar på klientsidan stöds med det Microsoft-tillhandahållna klientcertifikatet. TLS-anslutningar på serversidan kan inte använda det Microsoft-tillhandahållna klientcertifikatet.

  • Ett program kan antingen använda det inbyggda wolfSSL TLS-stödet eller använda och länka i en annan wolfSSL-biblioteksimplementering. Dock stöds inte blandad användning av det inbyggda stödet med ett annat wolfSSL-bibliotek.

Använda wolfSSL i Azure Sphere

Azure Sphere-program på hög nivå kan använda wolfSSL för att skapa och kommunicera via en TLS-anslutning. Program måste vanligtvis använda en kombination av teknikerna för att skapa och kommunicera över dessa anslutningar.

Kommentar

För förbättrad säkerhet bör program använda wolfSSL_CTX_set_verify() för att verifiera värden. Mer information finns i wolfSSL-dokumentationen .

Initiera wolfSSL för klient-TLS-anslutningar

För att skapa en TLS-anslutning med wolfSSL måste programmet först initiera biblioteket och SSL-kontexten (CTX), som i följande kodfragment:

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

Läs in certifikatet

När wolfSSL har initierats kan det läsa in ett certifikat för användning med TLS-anslutningen. Du kan inkludera certifikatet i programavbildningspaketet enligt beskrivningen i Lägg till CA-certifikat i avbildningspaketet.

I följande exempel visas hur en app kan använda Storage_GetAbsolutePathInImagePackage för att hämta sökvägen till ett klientcertifikat som ingår i programavbildningspaketet och sedan anropa wolfSSL_CTX_load_verify_locations för att läsa in certifikatet till wolfSSL. Observera att appen måste innehålla storage.h huvudfilen för att kunna använda 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;
    }

Skapa en anslutning på klientsidan

När certifikatet har lästs in kan appen upprätta TLS-anslutningen. Det här steget omfattar att skapa ett SSL-objekt, associera det med en socketbeskrivning och sedan skapa anslutningen, som i det här exemplet:

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

Läsa och skriva data från anslutningen

För att skriva och läsa data från anslutningen kan programmet använda wolfSSL_write respektive wolfSSL_read, vilket visas i följande exempel. I det här exemplet innehåller skrivningen till servern en HTTP/1.1-standardbegäran för att hämta innehållet på sidan. Dokumentationen på HTTP/1.1: Request (w3.org) ger en bra översikt över den här strukturen. Observera dock att det här dokumentet har ersatts och du hittar mer information om begärandestrukturen i dess ersättnings-RFC 9110: HTTP-semantik (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);

Initiera wolfSSL för anslutningar på serversidan

Om du vill skapa en TLS-server med wolfSSL måste programmet först initiera biblioteket och SSL-kontexten (CTX), som i följande kodfragment:

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

Acceptera inkommande anslutningar med hjälp av wolfSSL TLS-servern

Acceptera inkommande anslutningar från en klient till Azure Sphere-servern.

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

Rensa

När programmet är klart med anslutningen bör det frigöra de relaterade resurserna.

    free(certificatePath);

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

Exempel

Ett exempel på WolfSSL-funktionerna på Azure Sphere-plattformen finns i WolfSSL_HighLevelApp.