Použití wolfSSL pro připojení TLS

Článek
09/27/2024

Důležité

Toto je dokumentace k Azure Sphere (starší verze). Azure Sphere (starší verze) se vyřazuje 27. září 2027 a uživatelé musí do této doby migrovat do Azure Sphere (integrované). K zobrazení dokumentace k Azure Sphere (integrované) použijte selektor verzí umístěný nad obsahem.

Sada Azure Sphere SDK obsahuje podmnožinu knihovny wolfSSL pro protokol TLS (Transport Layer Security), kterou můžou aplikace vysoké úrovně použít k vytváření zabezpečených připojení TLS.

Referenční informace k rozhraní API wolfSSL poskytují důkladnou dokumentaci k rozhraní WOLFSSL API spolu s mnoha příklady. Azure Sphere podporuje podmnožinu rozhraní API , která zajišťuje binární kompatibilitu.

Požadavky pro aplikace, které používají knihovnu wolfSSL

Aplikace, které používají knihovnu wolfSSL, musí obsahovat potřebné soubory hlaviček a konfiguraci sestavení.

Rozhraní API protokolu TLS wolfSSL nevyžaduje funkce v manifestu aplikace. Pokud se ale aplikace připojí k internetovému koncovému bodu, musí manifest aplikace obsahovat informace o připojení. Další podrobnosti o povolení připojení najdete v tématu Připojení k webovým službám .

Soubory hlaviček

Aplikace, které používají rozhraní WOLFSSL API, musí obsahovat ssl.h soubor hlaviček a v závislosti na funkcích wolfSSL, které používají, můžou vyžadovat jeden nebo více dalších souborů hlaviček:

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

Informace o tom, které soubory hlaviček vaše aplikace vyžaduje, najdete v dokumentaci k wolfSSL.

Konfigurace sestavení

Pokud chcete vytvořit aplikaci s podporou rozhraní TLS API wolfSSL, upravte soubory CMakePresets.json a CMakeLists.txt, abyste určili cílovou sadu rozhraní API a propojili knihovnu wolfSSL.

Nastavte TARGET_API_SET v CMakePresets.json na 6 nebo vyšší.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Přidejte wolfssl do seznamu target_link_libraries v CMakeLists.txt propojte knihovnu wolfSSL s projektem:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Podporované funkce

Sada Azure Sphere SDK podporuje protokol TLS wolfSSL na straně klienta pomocí klientského certifikátu poskytnutého Microsoftem nebo certifikátu nebo vašeho výběru. Sada Azure Sphere SDK podporuje protokol WOLFSSL TLS na straně serveru pouze pomocí libovolného certifikátu. Mezi nepodporované scénáře patří:

S klientským certifikátem poskytovaným Microsoftem se podporují pouze připojení TLS na straně klienta wolfSSL. Připojení TLS na straně serveru nemůžou používat klientský certifikát od Microsoftu.
Aplikace může buď použít integrovanou podporu protokolu WOLFSSL TLS, nebo použít a propojit v jiné implementaci knihovny wolfSSL. Smíšené použití integrované podpory s jinou knihovnou wolfSSL se však nepodporuje.

Použití wolfSSL v Azure Sphere

Aplikace Azure Sphere vysoké úrovně můžou pomocí wolfSSL vytvářet a komunikovat přes připojení TLS. Aplikace obvykle musí používat kombinaci technik k vytváření a komunikaci přes tato připojení.

Poznámka:

Pro lepší zabezpečení by aplikace měly k ověření hostitele použít wolfSSL_CTX_set_verify( ). Další informace najdete v dokumentaci k wolfSSL.

Inicializace wolfSSL pro připojení TLS klienta

Pokud chcete vytvořit připojení TLS s wolfSSL, musí aplikace nejprve inicializovat knihovnu a kontext SSL (CTX), jako v následujícím fragmentu kódu:

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

Načtení certifikátu

Po inicializaci wolfSSL může načíst certifikát pro použití s připojením TLS. Certifikát můžete zahrnout do balíčku image aplikace, jak je popsáno v části Přidání certifikátů certifikační autority do balíčku image.

Následující příklad ukazuje, jak může aplikace použít Storage_GetAbsolutePathInImagePackage k získání cesty k klientskému certifikátu, který je součástí balíčku image aplikace, a voláním wolfSSL_CTX_load_verify_locations načíst certifikát do wolfSSL. Aplikace musí obsahovat hlavičkový storage.h soubor, který se má použít 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;
    }

Vytvoření připojení na straně klienta

Po načtení certifikátu může aplikace navázat připojení TLS. Tento krok zahrnuje vytvoření objektu SSL, jeho přidružení k popisovači soketu a následné vytvoření připojení, jak je znázorněno v tomto příkladu:

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

Čtení a zápis dat z připojení

K zápisu a čtení dat z připojení může aplikace používat wolfSSL_write a wolfSSL_read, jak ukazuje následující příklad. V tomto příkladu obsahuje zápis na server standardní požadavek HTTP/1.1 pro načtení obsahu stránky. Dokumentace na adrese HTTP/1.1: Požadavek (w3.org) poskytuje dobrý přehled této struktury. Všimněte si však, že tento dokument byl nahrazen a můžete najít další podrobnosti o struktuře požadavků v jeho náhradní RFC 9110: sémantika 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);

Inicializace wolfSSL pro připojení na straně serveru

Pokud chcete vytvořit server TLS s wolfSSL, musí aplikace nejprve inicializovat knihovnu a kontext SSL (CTX), jako v následujícím fragmentu kódu:

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

Přijetí příchozích připojení pomocí serveru WOLFSSL TLS

Přijímat příchozí připojení z klienta k serveru Azure Sphere

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

Vyčištění

Po dokončení připojení by aplikace měla uvolnit související prostředky.

    free(certificatePath);

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

Vzorek

Ukázku funkcí WolfSSL na platformě Azure Sphere najdete v tématu WolfSSL_HighLevelApp.

Sdílet prostřednictvím