針對 TLS 連線使用 wolfSSL

發行項
11/05/2024

重要

這是 Azure Sphere （舊版）檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式）檔。

Azure Sphere SDK 包含用於傳輸層安全性的 wolfSSL 連結庫子集（TLS），高階應用程式可用來建立安全的 TLS 連線。

wolfSSL API 參考提供 wolfSSL API 的完整檔，以及許多範例。 Azure Sphere 支援可確保二進位相容性的 API 子集。

使用 wolfSSL 連結庫之應用程式的需求

使用 wolfSSL 連結庫的應用程式必須包含必要的頭檔及建置組態。

wolfSSL TLS API 不需要應用程式指令清單中的功能。不過，如果應用程式連線到因特網端點，應用程式指令清單必須包含連線的相關信息。如需啟用連線的詳細資訊，請參閱連線至 Web 服務。

標頭檔

使用 wolfSSL API 的應用程式必須包含 ssl.h 頭檔，而且可能需要一或多個額外的頭檔，視使用的 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>

請參閱 wolfSSL 檔，以判斷應用程式所需的頭檔。

組建組態

若要建置具有 wolfSSL TLS API 支援的應用程式，請編輯CMakePresets.json和CMakeLists.txt檔案，以指定目標 API 集，以及分別連結 wolfSSL 連結庫。

將 CMakePresets.json 中的TARGET_API_SET設定為 6 或更新。
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
將新增 wolfssl 至 CMakeLists.txt 中的target_link_libraries清單，以將 wolfSSL 連結庫連結至專案：
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

支援的功能

Azure Sphere SDK 支援使用Microsoft提供的用戶端憑證或憑證或您選擇的用戶端 wolfSSL TLS。 Azure Sphere SDK 僅支援使用您選擇的憑證的伺服器端 wolfSSL TLS。值得注意的不支援案例包括：

Microsoft提供的客戶端憑證僅支援 wolfSSL 用戶端 TLS 連線。伺服器端 TLS 連線無法使用Microsoft提供的客戶端憑證。
應用程式可以使用內建的 wolfSSL TLS 支援，或是在另一個 wolfSSL 連結庫實作中使用和連結。不過，不支援將內建支援與另一個 wolfSSL 連結庫混合使用。

在 Azure Sphere 中使用 wolfSSL

高階 Azure Sphere 應用程式可以使用 wolfSSL，透過 TLS 連線來建立和通訊。應用程式通常必須使用這些技術的組合來建立和通訊這些連線。

注意

為了增強安全性，應用程式應該使用 wolfSSL_CTX_set_verify（） 來驗證主機。如需詳細資訊，請參閱 wolfSSL 檔。

初始化用戶端 TLS 連線的 wolfSSL

若要使用 wolfSSL 建立 TLS 連線，應用程式必須先初始化連結庫和 SSL 內容（CTX），如下列代碼段所示：

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

加載憑證

初始化 wolfSSL 之後，它可以載入憑證以搭配 TLS 連線使用。您可以在應用程式映像套件中包含憑證，如將 CA 憑證新增至映像套件中所述。

下列範例示範應用程式如何使用 Storage_GetAbsolutePathInImagePackage 來取得屬於應用程式映像套件一部分之用戶端憑證的路徑，然後呼叫 wolfSSL_CTX_load_verify_locations ，將憑證載入 wolfSSL。請注意，應用程式必須包含 storage.h 頭檔，才能使用 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;
    }

建立客戶端連線

載入憑證之後，應用程式可以建立 TLS 連線。此步驟牽涉到建立 SSL 物件、將它與套接字描述元建立關聯，然後建立連線，如下列範例所示：

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

從連線讀取和寫入數據

若要從聯機寫入和讀取數據，應用程式可以使用 wolfSSL_write 和 wolfSSL_read，如下列範例所示。在此範例中，寫入伺服器包含用來擷取頁面內容的標準 HTTP/1.1 要求。 HTTP/1.1 的檔：要求（w3.org）提供此結構的良好概觀。不過，請注意，這份檔已被取代，您可以在其取代 RFC 9110：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);

初始化伺服器端連線的 wolfSSL

若要使用 wolfSSL 建立 TLS 伺服器，應用程式必須先初始化連結庫和 SSL 內容（CTX），如下列代碼段所示：

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

使用 wolfSSL TLS 伺服器接受連入連線

接受從用戶端到 Azure Sphere 伺服器的連入連線。

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

清理

當應用程式使用連線完成時，應該釋放相關的資源。

    free(certificatePath);

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

範例

如需 Azure Sphere 平臺上的 WolfSSL 功能範例，請參閱 WolfSSL_HighLevelApp。

共用方式為