TLS 接続に wolfSSL を使用する

  • [アーティクル]

Azure Sphere SDK には、トランスポート層セキュリティ (TLS) 用の wolfSSL ライブラリのサブセットが含まれています。このライブラリは、高レベルのアプリケーションがセキュリティで保護された TLS 接続を作成するために使用できます。

wolfSSL API リファレンスでは、wolfSSL API の詳細なドキュメントと、多くの例が提供されています。 Azure Sphere では、バイナリ互換性を確保する API のサブセット がサポートされています。

wolfSSL ライブラリを使用するアプリケーションの要件

wolfSSL ライブラリを使用するアプリケーションには、必要なヘッダー ファイルとビルド構成を含める必要があります。

wolfSSL TLS API には、アプリケーション マニフェストの機能は必要ありません。 ただし、アプリケーションがインターネット エンドポイントに接続する場合は、アプリケーション マニフェストに接続に関する情報を含める必要があります。 接続の有効化の詳細については、「 Web サービスに 接続する」を参照してください。

ヘッダー ファイル

wolfSSL API を使用するアプリケーションにはヘッダー ファイルが ssl.h 含まれている必要があり、使用されている wolfSSL 機能によっては、1 つ以上の追加ヘッダー ファイルが必要になる場合があります。

#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 ライブラリをそれぞれリンクします。

  1. CMakePresets.jsonのTARGET_API_SETを 6 以上に設定します。

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. CMakeLists.txt のtarget_link_librariesの一覧に追加 wolfssl して、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_GetAbsolutePathInImagePackageを使用するには、アプリに storage.h ヘッダー ファイルを含める必要があることに注意 してください。

   #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: Request (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」を参照してください。