Použití wolfSSL pro připojení TLS

Článek
04/03/2024

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í wolfSSL API poskytují podrobnou 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 na aplikace, které používají knihovnu wolfSSL

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

Rozhraní WOLFSSL TLS API nevyžaduje funkce v manifestu aplikace. Pokud se ale aplikace připojí ke koncovému bodu internetu, manifest aplikace musí 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 mohou vyžadovat jeden nebo více dalších souborů hlaviček v závislosti na funkcích wolfSSL, které se používají:

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

Projděte si dokumentaci k wolfSSL a zjistěte, které soubory hlaviček vaše aplikace vyžaduje.

Konfigurace sestavení

Pokud chcete vytvořit aplikaci s podporou rozhraní WOLFSSL TLS API, upravte soubory CMakePresets.json a CMakeLists.txt tak, aby určily cílovou sadu rozhraní API a propojily 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, certifikátu nebo vašeho výběru. Sada Azure Sphere SDK podporuje protokol TLS wolfSSL na straně serveru pouze s použitím certifikátu podle vašeho výběru. Mezi nepodporované scénáře patří:

Certifikát klienta od Microsoftu podporuje pouze připojení TLS na straně klienta wolfSSL. Připojení TLS na straně serveru nemůžou používat klientský certifikát poskytnutý Microsoftem.
Aplikace může buď použít integrovanou podporu protokolu TLS wolfSSL, 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 používat wolfSSL k vytváření a komunikaci přes připojení TLS. Aplikace obvykle musí používat kombinaci technik k vytvoření a komunikaci přes tato připojení.

Poznámka

V případě zvýšeného zabezpečení by aplikace měly k ověření hostitele používat wolfSSL_CTX_set_verify( ). Další informace najdete v dokumentaci k wolfSSL .

Inicializace wolfSSL pro klientská připojení TLS

Pokud chcete vytvořit připojení TLS pomocí 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 bitové kopie aplikace, jak je popsáno v tématu Přidání certifikátů CA do balíčku imagí.

Následující příklad ukazuje, jak může aplikace použít Storage_GetAbsolutePathInImagePackage k získání cesty ke klientskému certifikátu, který je součástí balíčku image aplikace, a pak voláním wolfSSL_CTX_load_verify_locations načíst certifikát do wolfSSL. Upozorňujeme, že aplikace musí obsahovat storage.h soubor záhlaví, aby bylo možné používat 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í, jako 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žít 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 na načtení obsahu stránky. Dobrý přehled o této struktuře najdete v dokumentaci HTTP/1.1: Request (w3.org). Upozorňujeme však, že tento dokument byl nahrazen a další podrobnosti o struktuře požadavků najdete v jeho náhradním dokumentu 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říjem příchozích připojení pomocí serveru wolfSSL TLS

Přijměte 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í aplikace pomocí připojení by se měly uvolnit související prostředky.

    free(certificatePath);

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

Ukázka

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