Dela via

Använda wolfSSL för TLS-anslutningar

  • Artikel

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

Api-referensen wolfSSL ger grundlig dokumentation av wolfSSL API, tillsammans med många exempel. Azure Sphere har stöd för 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 de nödvändiga huvudfilerna och konfigurationen av bygget.

Api:t för wolfSSL 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 anslutningen finns i Ansluta till webbtjänster .

Sidhuvudfiler

Program som använder wolfSSL API måste innehålla ssl.h rubrikfilen 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 krävs i programmet.

Konfiguration av bygge

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

  1. Ställ in TARGET_API_SET i CMakePresets.json till 6 eller senare.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. Lägg wolfssl till 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 klientbaserade wolfSSL TLS med ett Microsoft-klientcertifikat eller ett certifikat eller ditt val. Azure Sphere SDK stöder serverbaserade wolfSSL TLS med endast ett certifikat som du väljer. Exempel på scenarier som inte stöds:

  • Endast wolfSSL-klientbaserade TLS-anslutningar stöds med microsoft-klientcertifikatet. TLS-anslutningar på serversidan kan inte använda det Klientcertifikat som tillhandahålls av Microsoft.

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

Använda wolfSSL i Azure Sphere

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

Observera

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 TLS-klientanslutningar

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

    // 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äsa in certifikatet

När wolfSSL har initierats kan det läsa in ett certifikat för användning med TLS-anslutningen. Du kan ta med certifikatet i programbildpaketet enligt beskrivningen i Lägga till certifikatutfärdarcertifikat 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 programbildpaketet 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 rubrikfilen 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 laddats 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

Om du vill skriva och läsa data från anslutningen kan programmet använda wolfSSL_write respektive wolfSSL_read som visas i följande exempel. I det här exemplet innehåller skrivning till servern en vanlig HTTP/1.1-begäran om att hämta innehållet på sidan. Dokumentationen på HTTP/1.1: Begäran (w3.org) ger en bra översikt över denna struktur. Observera dock att det här dokumentet har ersatts och du hittar mer information om begärandestrukturen i ersättnings-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);

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 kodavsnitt:

// 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 wolfSSL TLS-server

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

Rensning

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

    free(certificatePath);

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

Prov

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