Verwenden von WolfSSL für TLS-Verbindungen

Artikel
09/27/2024

Wichtig

Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.

Das Azure Sphere SDK enthält eine Teilmenge der wolfSSL-Bibliothek für transport layer security (TLS), mit der Anwendungen auf hoher Ebene sichere TLS-Verbindungen erstellen können.

Die WolfSSL-API-Referenz enthält eine gründliche Dokumentation der wolfSSL-API zusammen mit vielen Beispielen. Azure Sphere unterstützt eine Teilmenge der API , die die binäre Kompatibilität gewährleistet.

Anforderungen für Anwendungen, die die wolfSSL-Bibliothek verwenden

Anwendungen, die die wolfSSL-Bibliothek verwenden, müssen die erforderlichen Headerdateien und buildkonfigurationen enthalten.

Die wolfSSL TLS-API erfordert keine Funktionen im Anwendungsmanifest. Wenn die Anwendung jedoch eine Verbindung mit einem Internetendpunkt herstellt, muss das Anwendungsmanifest Informationen zur Verbindung enthalten. Weitere Informationen zum Aktivieren der Konnektivität finden Sie unter Herstellen einer Verbindung mit Webdiensten .

Headerdateien

Anwendungen, die die wolfSSL-API verwenden, müssen die ssl.h Headerdatei enthalten und erfordern je nach den verwendeten wolfSSL-Features möglicherweise eine oder mehrere zusätzliche Headerdateien:

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

In der WolfSSL-Dokumentation können Sie ermitteln, welche Headerdateien Ihre Anwendung benötigt.

Buildkonfiguration

Um eine Anwendung mit wolfSSL TLS-API-Unterstützung zu erstellen, bearbeiten Sie die CMakePresets.json- und CMakeLists.txt-Dateien, um den Ziel-API-Satz anzugeben und die wolfSSL-Bibliothek zu verknüpfen.

Legen Sie die TARGET_API_SET in CMakePresets.json auf 6 oder höher fest.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Fügen Sie wolfssl der Liste der target_link_libraries in CMakeLists.txt hinzu, um die wolfSSL-Bibliothek mit dem Projekt zu verknüpfen:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Unterstützte Funktionen

Das Azure Sphere SDK unterstützt clientseitige WolfSSL TLS mithilfe eines von Microsoft bereitgestellten Clientzertifikats oder eines Zertifikats oder Ihrer Wahl. Das Azure Sphere SDK unterstützt serverseitige WolfSSL TLS nur mit einem Zertifikat Ihrer Wahl. Zu den wichtigsten nicht unterstützten Szenarien gehören:

Nur wolfSSL clientseitige TLS-Verbindungen werden mit dem von Microsoft bereitgestellten Clientzertifikat unterstützt. Serverseitige TLS-Verbindungen können das von Microsoft bereitgestellte Clientzertifikat nicht verwenden.
Eine Anwendung kann entweder die integrierte WolfSSL TLS-Unterstützung oder die Verwendung und Verknüpfung in einer anderen wolfSSL-Bibliotheksimplementierung verwenden. Die gemischte Verwendung der integrierten Unterstützung mit einer anderen WolfSSL-Bibliothek wird jedoch nicht unterstützt.

Verwenden von wolfSSL in Azure Sphere

High-Level Azure Sphere-Anwendungen können wolfSSL verwenden, um eine TLS-Verbindung zu erstellen und zu kommunizieren. Anwendungen müssen in der Regel eine Kombination der Techniken verwenden, um diese Verbindungen zu erstellen und zu kommunizieren.

Hinweis

Für erhöhte Sicherheit sollten Anwendungen wolfSSL_CTX_set_verify() verwenden, um den Host zu überprüfen. Weitere Informationen finden Sie in der WolfSSL-Dokumentation .

Initialisieren von wolfSSL für Client-TLS-Verbindungen

Um eine TLS-Verbindung mit wolfSSL zu erstellen, muss die Anwendung zuerst die Bibliothek und den SSL-Kontext (CTX) initialisieren, wie im folgenden Codeausschnitt gezeigt:

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

Laden des Zertifikats

Nachdem wolfSSL initialisiert wurde, kann es ein Zertifikat für die Verwendung mit der TLS-Verbindung laden. Sie können das Zertifikat in das Anwendungsimagepaket einschließen, wie unter Hinzufügen von Zertifizierungsstellenzertifikaten zum Imagepaket beschrieben.

Das folgende Beispiel zeigt, wie eine App Storage_GetAbsolutePathInImagePackage verwenden kann, um den Pfad zu einem Clientzertifikat abzurufen, das Teil des Anwendungsbildpakets ist, und rufen Sie dann wolfSSL_CTX_load_verify_locations auf, um das Zertifikat in wolfSSL zu laden. Beachten Sie, dass die App die storage.h Headerdatei enthalten muss, um Storage_GetAbsolutePathInImagePackage zu verwenden.

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

Erstellen einer clientseitigen Verbindung

Nach dem Laden des Zertifikats kann die App die TLS-Verbindung herstellen. In diesem Schritt wird ein SSL-Objekt erstellt, ein Socketdeskriptor zugeordnet und dann die Verbindung erstellt, wie im folgenden Beispiel gezeigt:

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

Lesen und Schreiben von Daten aus der Verbindung

Zum Schreiben und Lesen von Daten aus der Verbindung kann die Anwendung wolfSSL_write bzw. wolfSSL_read verwenden, wie im folgenden Beispiel gezeigt. In diesem Beispiel enthält der Schreibzugriff auf den Server eine standardmäßige HTTP/1.1-Anforderung, um den Inhalt der Seite abzurufen. Die Dokumentation unter HTTP/1.1: Request (w3.org) bietet eine gute Übersicht über diese Struktur. Beachten Sie jedoch, dass dieses Dokument abgelöst wurde und Sie weitere Details zur Anforderungsstruktur in seiner Ersetzung RFC 9110 finden: 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);

Initialisieren von wolfSSL für serverseitige Verbindungen

Um einen TLS-Server mit wolfSSL zu erstellen, muss die Anwendung zuerst die Bibliothek und den SSL-Kontext (CTX) initialisieren, wie im folgenden Codeausschnitt gezeigt:

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

Eingehende Verbindungen mit wolfSSL TLS-Server annehmen

Akzeptieren Sie eingehende Verbindungen von einem Client zum Azure Sphere-Server.

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

Bereinigung

Wenn die Anwendung mit der Verbindung fertig ist, sollte sie die zugehörigen Ressourcen freigeben.

    free(certificatePath);

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

Beispiel

Ein Beispiel für die WolfSSL-Funktionalität auf der Azure Sphere-Plattform finden Sie unter WolfSSL_HighLevelApp.

Freigeben über