Używanie wolfSSL dla połączeń TLS

Artykuł
09/27/2024

Ważne

Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).

Zestaw SDK usługi Azure Sphere zawiera podzbiór biblioteki wolfSSL na potrzeby zabezpieczeń warstwy transportu (TLS), której aplikacje wysokiego poziomu mogą używać do tworzenia bezpiecznych połączeń TLS.

Dokumentacja 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 internetowym punktem końcowym, manifest aplikacji musi zawierać informacje o połączeniu. Aby uzyskać więcej informacji na temat włączania łączności, zobacz Łączenie z usługami internetowymi.

Pliki nagłówkowe

Aplikacje korzystające z interfejsu API wolfSSL muszą zawierać plik nagłówka ssl.h 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 określić, których plików nagłówka wymaga aplikacja.

Konfiguracja kompilacji

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

Ustaw TARGET_API_SET w CMakePresets.json na 6 lub większą.
```
"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)
```

Obsługiwane funkcje

Zestaw SDK usługi Azure Sphere obsługuje protokół TLS po stronie klienta przy użyciu certyfikatu klienta lub certyfikatu lub wybranego certyfikatu klienta firmy Microsoft. Zestaw SDK usługi Azure Sphere obsługuje protokół TLS TLS po stronie serwera przy użyciu tylko wybranego certyfikatu. Istotne nieobsługiwane scenariusze obejmują:

Tylko połączenia TLS po stronie klienta wolfSSL są obsługiwane za pomocą certyfikatu klienta dostarczonego przez firmę Microsoft. Połączenia TLS po stronie serwera nie mogą używać certyfikatu klienta dostarczonego przez firmę Microsoft.
Aplikacja może użyć wbudowanej obsługi protokołu TLS wolfSSL lub użyć linku i linku w innej implementacji biblioteki wolfSSL. Jednak mieszane użycie wbudowanej obsługi z inną biblioteką wolfSSL nie jest obsługiwane.

Korzystanie z wolfSSL w usłudze Azure Sphere

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

Uwaga

W przypadku zwiększonych zabezpieczeń aplikacje powinny używać wolfSSL_CTX_set_verify() do sprawdzania poprawności hosta. Aby uzyskać więcej informacji, zobacz dokumentację wolfSSL.

Inicjowanie wolfSSL dla połączeń TLS klienta

Aby utworzyć połączenie TLS z wolfSSL, najpierw aplikacja musi zainicjować bibliotekę i kontekst SSL (CTX), jak w poniższym fragmencie 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życia z połączeniem TLS. Certyfikat można dołączyć do pakietu obrazów aplikacji zgodnie z opisem w temacie Dodawanie certyfikatów urzędu certyfikacji do pakietu obrazów.

W poniższym przykładzie pokazano, jak aplikacja może użyć Storage_GetAbsolutePathInImagePackage , aby uzyskać ścieżkę do certyfikatu klienta będącego częścią pakietu obrazu aplikacji, a następnie wywołać 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 obejmuje utworzenie obiektu SSL, skojarzenie go z deskryptorem gniazda, a następnie utworzenie 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 zapisywać i odczytywać 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 protokołu HTTP/1.1: Żądanie (w3.org) zawiera dobre omówienie tej struktury. Należy jednak pamiętać, że ten dokument został zastąpiony i można znaleźć więcej szczegółów na temat struktury żądań w zastąpieniu RFC 9110: Semantyka 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 fragmencie 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

Zaakceptuj połączenia przychodzące od klienta do serwera usługi Azure Sphere.

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

Czyszczenie

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

    free(certificatePath);

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

Przykład

Aby zapoznać się z przykładem funkcji WolfSSL na platformie Azure Sphere, zobacz WolfSSL_HighLevelApp.

Udostępnij za pośrednictwem