Używanie wolfSSL do połączeń TLS

Artykuł
08/09/2023

Zestaw SDK Azure Sphere zawiera podzbiór biblioteki wolfSSL na potrzeby zabezpieczeń warstwy transportu (TLS), która umożliwia aplikacjom wysokiego poziomu tworzenie bezpiecznych połączeń TLS.

Odwołanie do interfejsu API wolfSSL zawiera szczegółową dokumentację interfejsu API wolfSSL wraz z wieloma przykładami. Usługa Azure Sphere obsługuje podzestaw interfejsu API , który zapewnia zgodność binarną.

Wymagania dotyczące aplikacji korzystających z biblioteki wolfSSL

Aplikacje korzystające z biblioteki wolfSSL muszą zawierać niezbędne pliki nagłówków i konfigurację kompilacji.

Interfejs API TLS wolfSSL nie wymaga możliwości w manifeście aplikacji. Jeśli jednak aplikacja łączy się z punktem końcowym internetu, manifest aplikacji musi zawierać informacje o połączeniu. Aby uzyskać więcej szczegółowych informacji na temat włączania łączności, zobacz Łączenie się z usługami sieci Web .

Pliki nagłówków

Aplikacje korzystające z interfejsu API wolfSSL muszą zawierać ssl.h plik nagłówka i mogą wymagać co najmniej jednego dodatkowego pliku nagłówka, w zależności od używanych funkcji wolfSSL:

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

Zapoznaj się z dokumentacją wolfSSL, aby ustalić, których plików nagłówków wymaga aplikacja.

Konfiguracja kompilacji

Aby utworzyć aplikację z obsługą interfejsu API TLS wolfSSL, edytuj pliki CMakePresets.json i CMakeLists.txt, aby określić docelowy zestaw interfejsów API i połączyć odpowiednio bibliotekę wolfSSL.

Ustaw TARGET_API_SET w CMakePresets.json na 6 lub więcej.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Dodaj wolfssl do listy target_link_libraries w CMakeLists.txt, aby połączyć bibliotekę wolfSSL z projektem:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Funkcje obsługiwane

Pakiet SDK Azure Sphere obsługuje protokół TLS wolfSSL po stronie klienta przy użyciu certyfikatu klienta lub certyfikatu dostarczonego przez firmę Microsoft albo wybranego przez Ciebie certyfikatu. Klawiatura SDK Azure Sphere obsługuje protokół TLS wolfSSL po stronie serwera, używając tylko wybranego certyfikatu. Istotne nieobsługiane scenariusze obejmują:

Certyfikat klienta firmy Microsoft obsługuje tylko połączenia TLS po stronie klienta wolfSSL. Połączenia TLS po stronie serwera nie mogą używać certyfikatu klienta dostarczonego przez firmę Microsoft.
Aplikacja może używać wbudowanej obsługi protokołu TLS wolfSSL lub używać i łączyć się w innej implementacji biblioteki wolfSSL. Jednak mieszane użycie wbudowanej obsługi z inną biblioteką wolfSSL nie jest obsługiwane.

Korzystanie z usługi wolfSSL w usłudze Azure Sphere

Aplikacje Azure Sphere wysokiego poziomu mogą używać wolfSSL do tworzenia i komunikowania się za pośrednictwem połączenia TLS. Aplikacje zwykle muszą używać kombinacji technik, aby tworzyć i komunikować się za pośrednictwem tych połączeń.

Uwaga

Aby zwiększyć bezpieczeństwo, aplikacje powinny sprawdzać poprawność hosta za pomocą wolfSSL_CTX_set_verify( ). Więcej informacji można znaleźć w dokumentacji wolfSSL .

Inicjowanie wolfSSL dla połączeń klienckich TLS

Aby utworzyć połączenie TLS z wolfSSL, aplikacja musi najpierw zainicjować bibliotekę i kontekst SSL (CTX), jak w poniższym wstawce kodu:

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

Załaduj certyfikat

Po zainicjowaniu wolfSSL może załadować certyfikat do użytku z połączeniem TLS. Certyfikat można dołączyć do pakietu obrazów aplikacji zgodnie z opisem w artykule Dodawanie certyfikatów urzędu certyfikacji do pakietu obrazów.

W poniższym przykładzie pokazano, jak aplikacja może używać Storage_GetAbsolutePathInImagePackage , aby uzyskać ścieżkę do certyfikatu klienta, który jest częścią pakietu obrazów aplikacji, a następnie wywołaj wolfSSL_CTX_load_verify_locations , aby załadować certyfikat do wolfSSL. Należy pamiętać, że aplikacja musi zawierać plik nagłówka storage.h , aby używać 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;
    }

Tworzenie połączenia po stronie klienta

Po załadowaniu certyfikatu aplikacja może ustanowić połączenie TLS. Ten krok polega na utworzeniu obiektu SSL, skojarzeniu go z deskryptorem gniazda, a następnie utworzeniu połączenia, jak w tym przykładzie:

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

Odczytywanie i zapisywanie danych z połączenia

Aby zapisać i odczytać dane z połączenia, aplikacja może używać odpowiednio wolfSSL_write i wolfSSL_read, jak pokazano w poniższym przykładzie. W tym przykładzie zapis na serwerze zawiera standardowe żądanie HTTP/1.1 w celu pobrania zawartości strony. Dokumentacja pod adresem HTTP/1.1: Żądanie (w3.org) zawiera dobry przegląd tej struktury. Jednak należy pamiętać, że ten dokument został zastąpiony i można znaleźć więcej szczegółów na temat struktury żądań w jego wymiany RFC 9110: Semantics 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);

Inicjowanie wolfSSL dla połączeń po stronie serwera

Aby utworzyć serwer TLS z wolfSSL, aplikacja musi najpierw zainicjować bibliotekę i kontekst SSL (CTX), jak w poniższym wstawce kodu:

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

Akceptowanie połączeń przychodzących przy użyciu serwera TLS wolfSSL

Akceptowanie połączeń przychodzących z klienta do serwera Azure Sphere.

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

Oczyszczania

Po zakończeniu korzystania z połączenia aplikacja powinna zwolnić pokrewne zasoby.

    free(certificatePath);

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

Przykładowe

Aby uzyskać próbkę funkcji WolfSSL na platformie Azure Sphere, zobacz WolfSSL_HighLevelApp.

Udostępnij za pośrednictwem