TLS 接続に wolfSSL を使用する
重要
これは Azure Sphere (レガシ) のドキュメントです。 Azure Sphere (レガシ) は 2027 年 9 月 27 日に 再提供されておりユーザーは現時点で Azure Sphere (統合) に移行する必要があります。 TOC の上にある Version セレクターを使用して、Azure Sphere (統合) のドキュメントを表示します。
Azure Sphere SDK には、トランスポート層セキュリティ (TLS) 用の wolfSSL ライブラリのサブセットが含まれています。このライブラリは、高度なアプリケーションがセキュリティで保護された TLS 接続を作成するために使用できます。
wolfSSL API リファレンスでは、wolfSSL API の詳細なドキュメントと、多くの例が提供されています。 Azure Sphere では、バイナリの互換性を確保する API の subset がサポートされています。
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 ライブラリをそれぞれリンクします。
CMakePresets.jsonのTARGET_API_SETを 6 以上に設定します。
"AZURE_SPHERE_TARGET_API_SET": "6"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 接続を介して作成および通信できます。 通常、アプリケーションでは、これらの接続を作成して通信するために、手法の組み合わせを使用する必要があります。
Note
セキュリティを強化するには、アプリケーションで 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を参照してください。