From 036970dad92fc0b6da8404ae43f3f96934421775 Mon Sep 17 00:00:00 2001 From: Koji Takeda Date: Thu, 29 Oct 2026 21:51:45 +0900 Subject: [PATCH] Add Japanese of MbedTLS-Migration --- MbedTLS-Migration/Makefile | 6 +- MbedTLS-Migration/mkdocs-ja.yml | 35 +++++++ MbedTLS-Migration/src-ja/chapter01.md | 43 ++++++++ MbedTLS-Migration/src-ja/chapter02.md | 50 +++++++++ MbedTLS-Migration/src-ja/chapter03.md | 145 ++++++++++++++++++++++++++ MbedTLS-Migration/src-ja/chapter04.md | 71 +++++++++++++ MbedTLS-Migration/src-ja/chapter05.md | 82 +++++++++++++++ MbedTLS-Migration/src-ja/chapter06.md | 70 +++++++++++++ MbedTLS-Migration/src-ja/chapter07.md | 34 ++++++ MbedTLS-Migration/src-ja/chapter08.md | 84 +++++++++++++++ MbedTLS-Migration/src-ja/chapter09.md | 35 +++++++ MbedTLS-Migration/src-ja/chapter10.md | 40 +++++++ 12 files changed, 694 insertions(+), 1 deletion(-) create mode 100644 MbedTLS-Migration/mkdocs-ja.yml create mode 100644 MbedTLS-Migration/src-ja/chapter01.md create mode 100644 MbedTLS-Migration/src-ja/chapter02.md create mode 100644 MbedTLS-Migration/src-ja/chapter03.md create mode 100644 MbedTLS-Migration/src-ja/chapter04.md create mode 100644 MbedTLS-Migration/src-ja/chapter05.md create mode 100644 MbedTLS-Migration/src-ja/chapter06.md create mode 100644 MbedTLS-Migration/src-ja/chapter07.md create mode 100644 MbedTLS-Migration/src-ja/chapter08.md create mode 100644 MbedTLS-Migration/src-ja/chapter09.md create mode 100644 MbedTLS-Migration/src-ja/chapter10.md diff --git a/MbedTLS-Migration/Makefile b/MbedTLS-Migration/Makefile index 3beca745..cdc48245 100644 --- a/MbedTLS-Migration/Makefile +++ b/MbedTLS-Migration/Makefile @@ -14,7 +14,11 @@ SOURCES = chapter01.md \ chapter09.md \ chapter10.md -PDF = MbedTLS-wolfSSL-Migration-Guide.pdf +ifeq ($(DOC_LANG),JA) + PDF = MbedTLS-wolfSSL-Migration-Guide-jp.pdf +else + PDF = MbedTLS-wolfSSL-Migration-Guide.pdf +endif .PHONY: html-prep html-prep: diff --git a/MbedTLS-Migration/mkdocs-ja.yml b/MbedTLS-Migration/mkdocs-ja.yml new file mode 100644 index 00000000..382c4332 --- /dev/null +++ b/MbedTLS-Migration/mkdocs-ja.yml @@ -0,0 +1,35 @@ +site_name: Mbed TLS 移行ガイド +site_url: https://wolfssl.com/ +docs_dir: build/html/ +site_dir: html/ +copyright: Copyright © 2026 wolfSSL Inc. +nav: + - "1. はじめに": index.md + - "2. 設計上の違い": chapter02.md + - "3. TLS クライアントの移植": chapter03.md + - "4. よくある落とし穴": chapter04.md + - "5. ハードウェアとプラットフォーム": chapter05.md + - "6. Mbed TLS にない機能": chapter06.md + - "7. はじめよう": chapter07.md + - "8. API 対応表": chapter08.md + - "9. 設定オプションの対応": chapter09.md + - "10. サポート": chapter10.md +theme: + name: null + custom_dir: ../mkdocs-material/material + language: ja + palette: + primary: indigo + accent: indigo + font: + text: Roboto + code: Roboto Mono + icon: "logo.png" + logo: logo.png + favicon: logo.png + feature: + tabs: true +extra_css: [skin.css] +extra: + generator: false +use_directory_urls: false diff --git a/MbedTLS-Migration/src-ja/chapter01.md b/MbedTLS-Migration/src-ja/chapter01.md new file mode 100644 index 00000000..df70922d --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter01.md @@ -0,0 +1,43 @@ +# はじめに + +本ガイドは、組み込み機器およびホスト上のアプリケーションを Mbed TLS から wolfSSL へ移行する開発者のためのものです。 +移行に関わる主な設計上の違い、TLS クライアントの比較コード、実際の移行で頻繁に見られる落とし穴、そして API と設定の完全な対応表を収録しています。 + +## 対象読者 + +本ガイドは、Mbed TLS 3.6 または 4.x をベースにした製品を保守しており、wolfSSL への移行を計画・検討している C 言語開発者およびアーキテクトを対象としています。 +現在お使いの製品で利用している Mbed TLS API についての知識を前提としています。 + +## 対象範囲 + +本ガイドは Mbed TLS 3.6 と 4.x の両方を対象とし、主に 4.x を基準として説明します。 +TLS 層の API（`mbedtls_ssl_*`）は、暗号層に比べると 3.6 から 4.x への変更がはるかに少ないため、本ガイドの大部分は両バージョンに当てはまります。 +両バージョンで異なる箇所については、本文中でその旨を明記しています。 + +本ガイドは TLS と DTLS を中心に扱います。 +Mbed TLS や PSA Crypto の関数を直接呼び出しているコードは、ネイティブの wolfCrypt `wc_*` API へ移行することも、wolfPSA を介して wolfCrypt 上で PSA Crypto API をそのまま使い続けることもできます（[Mbed TLS にない機能](chapter06.md)を参照）。 + +## Mbed TLS のサポート状況 + +2026年10月時点の状況は次のとおりです。 + +| ブランチ | 状況 | +| -------------------- | -------------------------------------------------------------------------------- | +| 2.28 LTS | サポート終了。最終リリースは 2.28.10（2025年3月）。 | +| 3.6 LTS | 2027年3月までメンテナンス。最新リリースは 3.6.7（2026年7月）。 | +| 4.0 | 最初の 4.x リリース（2025年10月）。暗号機能は TF-PSA-Crypto 1.0 として分離。 | +| 4.1 LTS | 2029年3月まで修正提供予定と発表。最新リリースは 4.1.1（2026年7月）。 | +| 4.2 | 現行のメインラインリリース（2026年7月）。TF-PSA-Crypto 1.2 を使用。 | + +2026年10月、Mbed TLS チームは、現在のメンテナが 2027年4月に TLS および X.509 ライブラリの開発から離れることを[発表](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/thread/YPIGCB7WN6GCHOGEGKOJXUYAP7OK527W/)しました。 +新たなメンテナが引き継がない限り、これらのライブラリのセキュリティ修正とリリースはその時点で終了し、4.1 LTS ブランチの TLS および X.509 部分も影響を受けます。 +なお、暗号層である TF-PSA-Crypto は引き続き活発にメンテナンスされます。 + +## 本ガイドの使い方 + +1. [設計上の違い](chapter02.md)を読み、変わる概念を把握します。 +2. [TLS クライアントの移植](chapter03.md)と [API 対応表](chapter08.md)を参照しながら、TLS の初期設定と I/O のコードを移植します。 +3. [設定オプションの対応](chapter09.md)をチェックリストとして使い、Mbed TLS の設定で使用している機能を有効にして wolfSSL をビルドします。 +4. 移植したコードを[よくある落とし穴](chapter04.md)と照らし合わせて確認します。 + 落とし穴の多くは、コンパイルは通るものの実行時に失敗するものです。 +5. [はじめよう](chapter07.md)の説明に従い、既存の Mbed TLS の通信相手とのテストを行います。 diff --git a/MbedTLS-Migration/src-ja/chapter02.md b/MbedTLS-Migration/src-ja/chapter02.md new file mode 100644 index 00000000..3377970f --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter02.md @@ -0,0 +1,50 @@ +# 設計上の違い + +本章では、Mbed TLS と wolfSSL の構造を比較し、以降の章で扱う移植作業の全体像を示します。 + +| 項目 | Mbed TLS | wolfSSL | +| ------------------ | ----------------------------------------- | ----------------------------------------- | +| コンテキストモデル | `mbedtls_ssl_config` と `mbedtls_ssl_context` | `WOLFSSL_CTX` と `WOLFSSL` | +| プロトコルとロール | `mbedtls_ssl_config_defaults()` の引数 | `wolfSSL_CTX_new()` に渡すメソッド | +| 暗号 API | レガシー API（3.6）または PSA（4.x） | ネイティブの wolfCrypt `wc_*` API、wolfPSA による PSA（オプション） | +| 乱数生成器（RNG） | アプリケーションが接続（3.6）、PSA 内部で管理（4.x） | セッションごとに内部で生成・シード | +| 設定 | `mbedtls_config.h`、`crypto_config.h` | `./configure`、CMake または `user_settings.h` | +| 戻り値 | 成功時 0、エラー時は負の値 | TLS 関数は `WOLFSSL_SUCCESS`（1）、`wc_*` 関数は 0 | +| トランスポート | `mbedtls_ssl_set_bio()` のコールバック | `wolfSSL_set_fd()` または I/O コールバック | +| ハードウェアオフロード | `_ALT`（3.6）または PSA ドライバ（4.x） | 暗号コールバックとツリー内のポート | +| ライセンス | Apache-2.0 または GPL-2.0-or-later | GPLv3 または商用ライセンス | + +## 設定用に 1 つ、接続ごとに 1 つのコンテキスト + +`mbedtls_ssl_config` は `WOLFSSL_CTX` に、`mbedtls_ssl_context` は `WOLFSSL` に置き換わります。 +エンドポイント、トランスポート、プリセットを `mbedtls_ssl_config_defaults()` に渡す代わりに、`wolfSSL_CTX_new()` にメソッドを渡します。 +`wolfTLS_client_method()` は双方がサポートする最も高い TLS バージョンをネゴシエートし、`wolfDTLSv1_3_client_method()` は DTLS 1.3 を選択します。 +`WOLFSSL_CTX` は一度だけ設定してスレッド間で共有し、接続ごとに `WOLFSSL` を 1 つ作成します。 + +## RNG の接続処理は不要 + +wolfSSL では、3.6 の CTR-DRBG の接続処理も、4.x の `psa_crypto_init()` の呼び出しも必要ありません。 +各 `WOLFSSL` は、プラットフォームのエントロピー源から自身の RNG をシードします。 +ベアメタル環境では、`CUSTOM_RAND_GENERATE_SEED` または `wc_GenerateSeed()` の移植によってエントロピー源を一度だけ提供します。 +これは `MBEDTLS_ENTROPY_HARDWARE_ALT` や `MBEDTLS_PSA_DRIVER_GET_ENTROPY` に相当するもので、wolfSSL はその上で Hash_DRBG を動作させます。 +wolfCrypt を直接呼び出す場合、乱数を必要とする関数は明示的に `WC_RNG*` を引数に取ります。 + +## メモリフットプリント + +Mbed TLS は、`MBEDTLS_SSL_IN_CONTENT_LEN` と `MBEDTLS_SSL_OUT_CONTENT_LEN` で縮小しない限り、デフォルトで接続ごとに 16 KB の入力バッファと 16 KB の出力バッファを確保します。 +wolfSSL は各レコードを実際のサイズで割り当て、処理が終わると解放するため、ピーク使用量は受信する最大のレコードに応じて決まります。 +ただし、双方が Max Fragment Length に合意しない限り、最大で 16 KB になる点は同じです。 +`malloc()` を持たないシステム向けには、`--enable-staticmemory` により、すべてのメモリ割り当てをアプリケーションが用意したプールから行えます。 + +wolfSSL のブログ記事 2 本で、両ライブラリを計測しています。 +[TLS 1.3 in 30.8 KB](https://www.wolfssl.com/tls-1-3-in-30-8-kb-wolfssl-vs-mbedtls/) では、Cortex-M33 上で wolfSSL のフラッシュ使用量が 5% から 44% 小さいという結果が得られました。 +また、[同一条件でのベンチマーク](https://www.wolfssl.com/wolfssl-vs-mbedtls-an-apples-to-apples-benchmark-across-intel-arm-cortex-a-and-cortex-m-and-risc-v-targets/)では、Intel、ARM、RISC-V 上で wolfCrypt の公開鍵演算が数倍高速であることが確認されています。 + +## ライセンス + +Mbed TLS は Apache-2.0 と GPL-2.0-or-later のデュアルライセンスです。 +Apache-2.0 では、著作権表示などの要件を満たすだけでクローズドソースのファームウェアを出荷できます。 +wolfSSL は GPLv3 と商用ライセンスのデュアルライセンスのため、クローズドソースのファームウェアの多くでは商用ライセンスが必要になります。 +GPLv3 で回避できるケースはほとんどありません。 +GPLv3 は、コンシューマ向け機器ではユーザーが改変したソフトウェアをインストールできることも求めますが、ロックダウンされたファームウェアでは通常それを許容できないためです。 +エンジニアリング作業を始める前にライセンスの問題を解決できるよう、早めに wolfSSL までご相談ください。 diff --git a/MbedTLS-Migration/src-ja/chapter03.md b/MbedTLS-Migration/src-ja/chapter03.md new file mode 100644 index 00000000..3c7c086b --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter03.md @@ -0,0 +1,145 @@ +# TLS クライアントの移植 + +以下の 2 つの関数は、どちらも接続済みのソケット上で、CA ファイルを使ってサーバーを検証し、ホスト名を確認し、リクエストを送信して応答を読み取ります。 +これらは Mbed TLS 4.1 と wolfSSL 5.9.4 でコンパイルし、それぞれ相手側ライブラリのテストサーバーに対して動作を確認しています。 + +## Mbed TLS 4.x + +```c +#include +#include +#include +#include + +int tls_get(int fd, const char* host, const char* caFile) +{ + int ret; + mbedtls_net_context net; + mbedtls_ssl_context ssl; + mbedtls_ssl_config conf; + mbedtls_x509_crt ca; + unsigned char buf[256]; + const char req[] = "GET / HTTP/1.0\r\n\r\n"; + + mbedtls_net_init(&net); + net.fd = fd; + mbedtls_ssl_init(&ssl); + mbedtls_ssl_config_init(&conf); + mbedtls_x509_crt_init(&ca); + + ret = (int)psa_crypto_init(); /* 4.x: 証明書のパースより前に呼ぶ */ + if (ret != PSA_SUCCESS) + goto out; + if ((ret = mbedtls_x509_crt_parse_file(&ca, caFile)) != 0) + goto out; + if ((ret = mbedtls_ssl_config_defaults(&conf, MBEDTLS_SSL_IS_CLIENT, + MBEDTLS_SSL_TRANSPORT_STREAM, MBEDTLS_SSL_PRESET_DEFAULT)) != 0) + goto out; + mbedtls_ssl_conf_ca_chain(&conf, &ca, NULL); + /* 3.6 のみ: mbedtls_ssl_conf_rng(&conf, mbedtls_ctr_drbg_random, &drbg); */ + + if ((ret = mbedtls_ssl_setup(&ssl, &conf)) != 0 || + (ret = mbedtls_ssl_set_hostname(&ssl, host)) != 0) + goto out; + mbedtls_ssl_set_bio(&ssl, &net, mbedtls_net_send, mbedtls_net_recv, NULL); + + while ((ret = mbedtls_ssl_handshake(&ssl)) != 0) { + if (ret != MBEDTLS_ERR_SSL_WANT_READ && + ret != MBEDTLS_ERR_SSL_WANT_WRITE) + goto out; + } + ret = mbedtls_ssl_write(&ssl, (const unsigned char*)req, sizeof(req) - 1); + if (ret <= 0) + goto out; + do { + ret = mbedtls_ssl_read(&ssl, buf, sizeof(buf) - 1); + } while (ret == MBEDTLS_ERR_SSL_WANT_READ || + ret == MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET); + if (ret > 0) + ret = 0; + mbedtls_ssl_close_notify(&ssl); + +out: + mbedtls_ssl_free(&ssl); + mbedtls_ssl_config_free(&conf); + mbedtls_x509_crt_free(&ca); + return ret; +} +``` + +## wolfSSL + +```c +#include +#include +#include + +int tls_get(int fd, const char* host, const char* caFile) +{ + int ret = -1; + WOLFSSL_CTX* ctx = NULL; + WOLFSSL* ssl = NULL; + char buf[256]; + const char req[] = "GET / HTTP/1.0\r\n\r\n"; + + ctx = wolfSSL_CTX_new(wolfTLS_client_method()); /* TLS 1.2 または 1.3 */ + if (ctx == NULL) + goto out; + if (wolfSSL_CTX_load_verify_locations(ctx, caFile, NULL) + != WOLFSSL_SUCCESS) + goto out; + wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_PEER, NULL); + + ssl = wolfSSL_new(ctx); + if (ssl == NULL) + goto out; + if (wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, host, + (unsigned short)strlen(host)) != WOLFSSL_SUCCESS || + wolfSSL_check_domain_name(ssl, host) != WOLFSSL_SUCCESS || + wolfSSL_set_fd(ssl, fd) != WOLFSSL_SUCCESS) + goto out; + + ret = wolfSSL_connect(ssl); + if (ret != WOLFSSL_SUCCESS) { + ret = wolfSSL_get_error(ssl, ret); + goto out; + } + ret = wolfSSL_write(ssl, req, (int)sizeof(req) - 1); + if (ret <= 0) { + ret = wolfSSL_get_error(ssl, ret); + goto out; + } + ret = wolfSSL_read(ssl, buf, (int)sizeof(buf) - 1); + if (ret <= 0) { + ret = wolfSSL_get_error(ssl, ret); + goto out; + } + ret = 0; + wolfSSL_shutdown(ssl); + +out: + wolfSSL_free(ssl); + wolfSSL_CTX_free(ctx); + return ret; +} +``` + +## 変更点 + +- RNG の設定と `psa_crypto_init()` は不要になります。 +- `wolfSSL_CTX_load_verify_locations()` は 1 回の呼び出しで CA のパースと登録を行います。 + また、`wolfSSL_CTX_set_verify()` によってピア検証を明示的に指定します（[よくある落とし穴](chapter04.md)の「ピア検証は有効であり、有効のままにすべき」を参照）。 +- ブロッキングソケットでは、`wolfSSL_connect()` がハンドシェイク全体を実行します。 + ノンブロッキングソケットでは、`wolfSSL_get_error()` が `WOLFSSL_ERROR_WANT_READ` または `WOLFSSL_ERROR_WANT_WRITE` を返す間、再度呼び出します。 +- `wolfSSL_UseSNI()` には SNI サポートが必要です。 + `./configure` は x86 および aarch64 ホストでのみ SNI をデフォルトで有効にします。 + 組み込みターゲットでは、`--enable-sni` を指定してビルドするか、`HAVE_SNI` を定義してください。 +- 読み取りループも不要になります。 + 4.0 以降の `mbedtls_ssl_read()` は、TLS 1.3 サーバーがチケットを送信するたびに `MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET` を返しますが、wolfSSL はチケットを内部で処理します。 + +失敗時、wolfSSL 版の関数は `wolfSSL_get_error()` のコードを返します。 +その中には、ピアが接続を閉じたときの `WOLFSSL_ERROR_ZERO_RETURN` のように正の値もあります。 +戻り値は `< 0` ではなく `!= 0` で判定してください。 + +`wolfSSL_Init()` は起動時に 1 回、`wolfSSL_Cleanup()` は終了時に 1 回だけ呼び出してください。 +`wolfSSL_Cleanup()` はセッションキャッシュも解放するため、接続ごとに呼び出さないでください。 diff --git a/MbedTLS-Migration/src-ja/chapter04.md b/MbedTLS-Migration/src-ja/chapter04.md new file mode 100644 index 00000000..af14f1ba --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter04.md @@ -0,0 +1,71 @@ +# よくある落とし穴 + +ここでは、Mbed TLS から移植する際に最もよく見られる問題を紹介します。 +その多くは、コンパイルは通るものの実行時に失敗するものです。 + +## ホスト名の検証には専用の呼び出しが必要 + +`mbedtls_ssl_set_hostname()` は SNI を送信し、さらにサーバー証明書をその名前と照合します。 +wolfSSL では、`wolfSSL_UseSNI()` は拡張を送信するだけで、名前の照合は `wolfSSL_check_domain_name()` で有効にします。 +そのため、[TLS クライアントの移植](chapter03.md)のサンプルのように両方を呼び出してください。 +2 つ目の呼び出しがないと、信頼された CA が発行した証明書であれば、どのホストに対しても受け入れてしまいます。 +これは Mbed TLS 3.6.3 以降では強制されているチェックです。 + +wolfSSL 5.9.2 以降、`wolfSSL_check_domain_name()` は完全修飾ドメイン名（FQDN）と `localhost` のみを受け付け、`gateway` のような単一ラベルの名前や IP アドレスに対しては `WOLFSSL_FAILURE` を返します。 +一方、`mbedtls_ssl_set_hostname()` は任意の名前を受け付けるため、完全修飾名を使用してください。 +IP アドレスの場合は `wolfSSL_check_ip_address()` を呼び出し、`--enable-ip-alt-name` を指定してビルドしてください。 +そうしないと、ハンドシェイクが `IPADDR_MISMATCH` で失敗します。 + +## 成功は 0 ではなく 1 + +`wolfSSL_*` の設定関数やハンドシェイク関数の多くは、成功時に `WOLFSSL_SUCCESS`（値は 1）を返します。 +`if (ret != 0)` のチェックのまま移植したコードは、すべての成功をエラーとして扱ってしまいます。 +さらに悪いことに、すべての失敗（`WOLFSSL_FAILURE` は 0）を成功として扱ってしまいます。 +wolfCrypt の `wc_*` 関数は、Mbed TLS と同じく成功時に 0 を返す規約に従います。 +`wolfSSL_read()` と `wolfSSL_write()` はバイト数を返し、失敗時は `wolfSSL_get_error(ssl, ret)` で原因を取得できます。 + +## ライブラリとアプリケーションは同じ定義でビルドする + +wolfSSL の多くの構造体は、有効にする機能によってサイズが変わります。 +そのため、ライブラリとアプリケーションで定義が一致しないと、コンパイルとリンクは成功しても実行時にメモリを破壊します。 +他のどの wolfSSL ヘッダーよりも先に `` をインクルードしてください。 +`user_settings.h` を使う場合は、ライブラリとアプリケーションの両方で `WOLFSSL_USER_SETTINGS` を定義し、同じファイルを共有してください。 + +## デフォルト設定が異なる + +デフォルトの `./configure` ビルドは最小限の構成です。 +Mbed TLS がデフォルトで有効にしている機能のいくつかは、wolfSSL では明示的なオプション指定が必要です。 +たとえば、組み込みターゲットでの SNI、Curve25519、ALPN、セッションチケット、DTLS、DTLS Connection ID、PSK、AES-CCM（CoAP や LwM2M の `_CCM_8` 暗号スイート用）、Max Fragment Length などです。 +関数が `NOT_COMPILED_IN` を返したり、関数自体が存在しない場合は、[設定オプションの対応](chapter09.md)で該当するオプションを確認してください。 + +## ピア検証は有効であり、有効のままにすべき + +デフォルトのビルドでは、wolfSSL クライアントは Mbed TLS と同様にサーバーを検証します。 +ただし、`--enable-all` や `--enable-nginx` のような OpenSSL 互換のデフォルトを持つビルドでは、`WOLFSSL_VERIFY_NONE` で開始します。 +そのため、すべてのクライアントで `wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_PEER, NULL)` を呼び出してください。 +CA が見つからない場合、ハンドシェイクは `ASN_NO_SIGNER_E`（-188）で失敗します。 +検証を無効にするのではなく、正しい CA を読み込んでください。 +サーバー側で `MBEDTLS_SSL_VERIFY_REQUIRED` と同じ動作にするには、`WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT` を追加します。 +`MBEDTLS_SSL_VERIFY_OPTIONAL` に相当する動作にするには、エラーを記録して 1 を返す検証コールバックを使用します。 + +## カスタム I/O コールバックの戻り値が異なる + +カスタムトランスポートのコールバックは、ほぼ 1 対 1 で移植できます。 +シグネチャは `int recv(WOLFSSL* ssl, char* buf, int sz, void* ctx)` で、送信側も同様です。 +Mbed TLS のコードの代わりに `WOLFSSL_CBIO_ERR_WANT_READ` または `WOLFSSL_CBIO_ERR_WANT_WRITE` を返し、ピアが接続を閉じた場合は `WOLFSSL_CBIO_ERR_CONN_CLOSE` を、DTLS でタイマーが満了した場合は `WOLFSSL_CBIO_ERR_TIMEOUT` を返してください。 +wolfSSL は Mbed TLS のコードを致命的エラーとして扱います。 + +## PEM と DER のバッファ + +Mbed TLS では、PEM バッファの長さに終端の NUL バイトを含める必要があります。 +wolfSSL の `*_buffer()` 関数もその長さを受け付けるため、既存のバッファはそのまま使えます。 +違いはフォーマットの指定方法です。 +Mbed TLS は内容から PEM か DER かを判別しますが、wolfSSL は引数として `WOLFSSL_FILETYPE_PEM` または `WOLFSSL_FILETYPE_ASN1` を受け取ります。 +DER のバッファを PEM として渡すと `ASN_NO_PEM_HEADER`（-162）で失敗します。 + +## 時計を持たないボードでの証明書の有効期間 + +`MBEDTLS_HAVE_TIME_DATE` なしでビルドした Mbed TLS は、有効期間のチェックを黙ってスキップします。 +wolfSSL は常にこのチェックを行うため、時計を持たないボードではハンドシェイクが `ASN_BEFORE_DATE_E` または `ASN_AFTER_DATE_E` で失敗します。 +`USER_TIME` または `TIME_OVERRIDES`（`XTIME()`）で時刻を提供するか、意図的にチェックを省略する場合は `NO_ASN_TIME` を定義してください。 +`NO_ASN_TIME` はセッションキャッシュとセッションチケットも無効にするため、セッション再開も使えなくなります。 diff --git a/MbedTLS-Migration/src-ja/chapter05.md b/MbedTLS-Migration/src-ja/chapter05.md new file mode 100644 index 00000000..f2bfb5e9 --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter05.md @@ -0,0 +1,82 @@ +# ハードウェアとプラットフォーム + +## ハードウェアアクセラレーション + +wolfSSL は `wolfcrypt/src/port/` に 30 を超えるハードウェアおよびプラットフォーム向けのポートを同梱しています（NXP、ST、Renesas、Microchip、Cypress PSoC 6、Silicon Labs、Espressif、Xilinx、Intel QuickAssist など）。 +さらに、Intel AES-NI/AVX、ARMv8、RISC-V 向けに手作業で最適化したアセンブリも含まれています。 +ドライバを作成する前に、お使いのデバイス向けのポートがこのディレクトリにないか確認してください。 + +## 暗号コールバック + +ツリー内にポートが存在しないハードウェアでは、暗号コールバックインターフェース（`--enable-cryptocb`）が実装すべき唯一のフックです。 +Mbed TLS の代替手段と比較すると次のようになります。 + +- 暗号の `_ALT` マクロ（3.6）は、コンパイル時にソフトウェア実装を置き換え、すべての呼び出し元に影響します。 + 4.x では廃止されています。 +- PSA ドライバ（4.x）は、いまだベータとされている仕様に従っています。 + ディスパッチ層の一部のみがコード生成され、残りは手作業で接続します。 +- wolfSSL の暗号コールバックは、実行時にデバイス ID の下で登録され、個々のオブジェクトまたは TLS コンテキスト全体がそのデバイス ID を選択して利用します。 + コールバックが `CRYPTOCB_UNAVAILABLE` を返すとソフトウェア処理にフォールバックします。 + このインターフェースはハッシュ、共通鍵暗号、MAC、RNG、従来型およびポスト量子の公開鍵アルゴリズムをカバーしているため、セキュアエレメントや HSM が ML-KEM や ML-DSA を引き受けることもできます。 + デバイスのみが保持する鍵による ML-KEM のデカプセル化には、wolfSSL 5.9.4 より後のリリースが必要です。 + +コンテキスト上のすべての TLS 接続で ECDSA 署名をオフロードする例は次のとおりです。 + +```c +#include +#include +#include + +#define MY_HW_DEVID 0x48570001 + +int my_hw_ecdsa_sign(const byte* hash, word32 hashSz, byte* sig, + word32* sigSz, ecc_key* key); + +static int myHwCallback(int devId, wc_CryptoInfo* info, void* ctx) +{ + (void)devId; + (void)ctx; + if (info->algo_type == WC_ALGO_TYPE_PK && + info->pk.type == WC_PK_TYPE_ECDSA_SIGN) { + return my_hw_ecdsa_sign(info->pk.eccsign.in, info->pk.eccsign.inlen, + info->pk.eccsign.out, info->pk.eccsign.outlen, + info->pk.eccsign.key); + } + return CRYPTOCB_UNAVAILABLE; /* それ以外はすべてソフトウェアで処理 */ +} + +int use_hw(WOLFSSL_CTX* ctx) +{ + if (wc_CryptoCb_RegisterDevice(MY_HW_DEVID, myHwCallback, NULL) != 0) + return -1; + return wolfSSL_CTX_SetDevId(ctx, MY_HW_DEVID) == WOLFSSL_SUCCESS ? 0 : -1; +} +``` + +`sig` には DER 形式の署名が格納されます。 +生の r と s は `wc_ecc_rs_raw_to_sig()` で変換してください。 +秘密鍵をセキュアエレメント内に保持したままにするには、同じデバイス ID を指定して `wolfSSL_CTX_use_PrivateKey_Id()` で読み込みます。 +wolfHSM、wolfTPM、PKCS#11 も同じ仕組みで動作しています。 +また、PK コールバック（`--enable-pkcallbacks`）は TLS レベルでの代替手段を提供します。 + +`use_hw()` は `wolfSSL_new()` より前に呼び出してください。 +各 `WOLFSSL` は、作成時にコンテキストのデバイス ID を引き継ぎます。 +すでに存在するセッションに対しては、`wolfSSL_SetDevId()` で設定します。 + +## Zephyr + +Zephyr の TLS ソケット（`SOL_TLS`）は Mbed TLS 上に構築されています。 +wolfSSL は [Zephyr モジュール](https://github.com/wolfSSL/wolfssl/tree/master/zephyr)を提供しており、[wolfSSL OSP リポジトリ](https://github.com/wolfSSL/osp/tree/master/zephyr)には、サポート対象の Zephyr リリースごとに TLS ソケットを wolfSSL に切り替えるパッチが用意されています。 +新しいリリースに移行する際は、パッチを再適用してください。 +Bluetooth など PSA Crypto API を使用するサブシステムは、[wolfPSA](https://github.com/wolfSSL/wolfPSA) を Zephyr の PSA Crypto プロバイダとして使うことで、変更なしに wolfCrypt 上で動作します。 + +## ESP-IDF + +wolfSSL は Espressif Component Registry のマネージドコンポーネントとして提供されています。 +ビルド手順とサンプルは、wolfSSL リポジトリの [IDE/Espressif](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif) にあります。 + +## その他のプラットフォーム + +wolfSSL の `IDE/` ディレクトリには 60 を超える IDE およびプラットフォーム向けのプロジェクトがあり、そのほかにも Arduino および PlatformIO 向けのパッケージや、Linux および BSD のカーネルモジュールが用意されています。 +configure を使わないビルドでは `user_settings.h` を使用します。 +テンプレートは `examples/configs/` にあります。 diff --git a/MbedTLS-Migration/src-ja/chapter06.md b/MbedTLS-Migration/src-ja/chapter06.md new file mode 100644 index 00000000..43ca6fa4 --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter06.md @@ -0,0 +1,70 @@ +# Mbed TLS にない機能 + +| 機能 | Mbed TLS 3.6 / 4.x | wolfSSL | +| ---------------------------------- | ------------------------------------ | ------------------------------ | +| TLS 1.3 | 対応 | 対応 | +| DTLS 1.3（RFC 9147） | 非対応（DTLS 1.2 のみ） | 対応 | +| DTLS Connection ID（RFC 9146） | 対応 | 対応（DTLS 1.2 および 1.3） | +| ML-KEM ハイブリッド鍵交換 | 非対応 | 対応（デフォルトで有効） | +| TLS 1.3 での ML-DSA、SLH-DSA 証明書 | 非対応 | 対応 | +| LMS、XMSS | LMS 検証、実験的な LMS 署名、XMSS 非対応 | 署名と検証に対応 | +| Ed25519、Ed448 | 非対応 | 対応 | +| QUIC | 非対応 | 対応 | +| Encrypted Client Hello | 非対応 | 対応 | +| OCSP ステープリング | 非対応 | 対応（v1 および v2） | +| TLS 1.3 ポストハンドシェイク認証 | 非対応 | 対応 | +| Raw Public Key（RFC 7250） | 非対応 | 対応 | +| FIPS 140-3 認証済み暗号 | 非対応 | 対応（別途認証を受けた wolfCrypt モジュールを使用） | +| ハードウェアオフロード | `_ALT` または PSA ドライバ | 暗号コールバックと 30 を超えるツリー内ポート | + +## DTLS 1.3 + +Mbed TLS は DTLS 1.2 のみをサポートしています。 +wolfSSL は DTLS 1.3（RFC 9147）を追加でサポートし、両バージョンで Connection ID も利用できます。 +これにより、CoAP、LwM2M、セルラー IoT などのデータグラムトランスポートに TLS 1.3 のハンドシェイクを導入できます。 +移行はメソッドの変更だけで済みます。 +`--enable-dtls13` を指定したビルドでは、`wolfDTLS_client_method()` はサーバーが対応していれば DTLS 1.3 をネゴシエートし、対応していなければ DTLS 1.2 にフォールバックします。 + +## ポスト量子暗号 + +Mbed TLS のロードマップでは ML-KEM は今後の課題とされており、ML-DSA のコードは開発ブランチ上の実験的な ML-DSA-87 ドライバのみです。 +wolfCrypt は NIST 標準の全アルゴリズムを、独自の実装と Intel および ARM 向けのアセンブリ最適化付きで提供しています。 + +- ML-KEM（FIPS 203）。TLS 1.3 では、単体の ML-KEM として、または X25519MLKEM768、SecP256r1MLKEM768、SecP384r1MLKEM1024 などのハイブリッドグループとして使用します。 +- ML-DSA（FIPS 204）。証明書、TLS 1.3 の認証、CMS、証明書生成に使用します。 + SLH-DSA（FIPS 205）は証明書と TLS 1.3 の認証に使用します。 +- ファームウェア署名向けのステートフルなハッシュベース署名 LMS/HSS および XMSS/XMSS^MT。 +- コンパクトな格子ベース署名を必要とするアプリケーション向けの Falcon（実験的機能: `--enable-falcon --enable-experimental`）。 + +ML-KEM とハイブリッドグループはデフォルトで有効です。 +ML-DSA と SLH-DSA には `--enable-mldsa` と `--enable-slhdsa` が必要です。 +[TLS クライアントの移植](chapter03.md)のサンプルクライアントは、PQC 固有のコードを含まないにもかかわらず、デフォルト設定の wolfSSL サーバーに対して SecP256r1MLKEM768 をネゴシエートします。 +`--enable-curve25519` を指定すると、優先グループは、現在ブラウザで採用されているハイブリッドである X25519MLKEM768 になります。 + +## FIPS 140-3 + +wolfCrypt は FIPS 140-3 認証を取得していますが、Mbed TLS は取得していません。 +お使いのプラットフォームに適した認証については、wolfSSL までお問い合わせください。 + +## PSA Crypto API を使い続ける + +[wolfPSA](https://github.com/wolfSSL/wolfPSA) は wolfCrypt 上に PSA Crypto API を実装しています。 +そのため、Mbed TLS 4.x 向けにすでに PSA へ移植したコードの大部分は、API を変更せずに wolfCrypt 上で動作します。 +ただし、PAKE 関数（およびそれに伴う EC J-PAKE）は実装されていません。 + +## wolfSSL 製品ファミリー + +wolfCrypt は、他の wolfSSL 製品の暗号コアでもあります。 +EST および SCEP による証明書登録のための [wolfCert](https://github.com/wolfSSL/wolfCert)、 +[wolfMQTT](https://github.com/wolfSSL/wolfMQTT)、 +[wolfSSH](https://github.com/wolfSSL/wolfssh)、 +[wolfTPM](https://github.com/wolfSSL/wolfTPM)、 +セキュアブートのための [wolfBoot](https://github.com/wolfSSL/wolfBoot)、 +[wolfHSM](https://github.com/wolfSSL/wolfHSM)、 +[wolfPKCS11](https://github.com/wolfSSL/wolfPKCS11)、 +[wolfPSA](https://github.com/wolfSSL/wolfPSA)、 +OpenSSL 3 向けの [wolfProvider](https://github.com/wolfSSL/wolfProvider)、 +[wolfIP](https://github.com/wolfSSL/wolfip)、 +[wolfSentry](https://github.com/wolfSSL/wolfsentry)、 +[wolfCOSE](https://github.com/wolfSSL/wolfCOSE) があります。 +また、Python、Rust、C#、Java（JSSE および JCE）、Ada 向けの言語バインディングがあり、[wolfSSL OSP リポジトリ](https://github.com/wolfSSL/osp)では curl、nginx、OpenSSH などのプロジェクトへの移植を提供しています。 diff --git a/MbedTLS-Migration/src-ja/chapter07.md b/MbedTLS-Migration/src-ja/chapter07.md new file mode 100644 index 00000000..7306efe0 --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter07.md @@ -0,0 +1,34 @@ +# はじめよう + +第1章の「本ガイドの使い方」の手順に従い、既存の Mbed TLS の通信相手とのテストを行ってください。 +移植が動作したら、新たに利用できるようになった機能を有効にしましょう。 +たとえば DTLS 1.3 や、お使いのハードウェア向けの暗号コールバックです。 +ML-KEM ハイブリッドグループはデフォルトで有効です。 +`user_settings.h` を使うビルドについては、[設定オプションの対応](chapter09.md)を参照してください。 + +## 相互接続性テスト + +wolfSSL の CI では、TLS、DTLS、DTLS Connection ID について Mbed TLS 3.6 との相互接続性テストを実施しています。 +本ガイドのサンプルは、Mbed TLS 4.1 に対してもテスト済みです。 + +ホスト上で手早くテストするには、wolfSSL のサンプルクライアントとサーバーを、Mbed TLS の `ssl_client2` および `ssl_server2` プログラムと組み合わせて使います。 + +```sh +# wolfSSL クライアントから Mbed TLS サーバーへ接続。-g で HTTP GET を送信 +./examples/client/client -h -p -A -g + +# Mbed TLS クライアント用の wolfSSL サーバー。-d でクライアント証明書の要求を省略 +./examples/server/server -p -d + +# 上記サーバーへ Mbed TLS クライアントから接続。wolfSSL のテスト CA を信頼する +ssl_client2 server_port= ca_file=/certs/ca-cert.pem server_name=example.com +``` + +Mbed TLS のテストデータに含まれる `test-ca.crt` は、`ssl_server2` が TLS 1.2 でデフォルトで使用する RSA 証明書の署名元です。 +TLS 1.3 では `ssl_server2` は ECDSA 証明書を提示しますが、その CA である `test-ca2.crt` には wolfSSL が拒否する NULL の署名パラメータが含まれています。 +そのため、代わりに `crt_file=server2-sha256.crt key_file=server2.key` を指定して起動してください。 +wolfSSL のサンプルプログラムを `-?` 付きで実行すると、オプションの一覧が表示されます。 + +## ソースコードとリリース + +wolfSSL のソースコードは [github.com/wolfSSL/wolfssl](https://github.com/wolfSSL/wolfssl) にあり、リリースアーカイブは [wolfssl.com/download](https://www.wolfssl.com/download/) から入手できます。 diff --git a/MbedTLS-Migration/src-ja/chapter08.md b/MbedTLS-Migration/src-ja/chapter08.md new file mode 100644 index 00000000..6627b661 --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter08.md @@ -0,0 +1,84 @@ +# API 対応表 + +備考欄に特に記載がない限り、Mbed TLS の名前は 3.6 と 4.x の両方に当てはまります。 +Mbed TLS の鍵交換のうち 2 つには、wolfSSL に相当するものがありません。 +1 つは OpenThread が Thread のコミッショニングに使用する EC J-PAKE 暗号スイート（`MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED`）、もう 1 つは 3.6 の RSA-PSK 暗号スイート（`MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED`）です。 + +## 初期化と終了処理 + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| `psa_crypto_init()` | `wolfSSL_Init()` | 4.x、および `MBEDTLS_USE_PSA_CRYPTO` を有効にした 3.6 では必須。`wolfSSL_CTX_new()` は必要に応じて `wolfSSL_Init()` を呼び出す | +| `mbedtls_ssl_config_init()` + `mbedtls_ssl_config_defaults()` | `wolfSSL_CTX_new(method)` | ロール、トランスポート、バージョンはメソッドで決まる | +| `mbedtls_ssl_conf_min_tls_version()` | `wolfSSL_CTX_SetMinVersion()` | または `wolfTLSv1_3_client_method()` などバージョン固有のメソッドを使用 | +| `mbedtls_ssl_conf_rng()` | 不要 | 3.6 のみ。4.x で削除 | +| `mbedtls_ssl_init()` + `mbedtls_ssl_setup()` | `wolfSSL_new(ctx)` | | +| `mbedtls_ssl_session_reset()` | `wolfSSL_clear()` | | +| `mbedtls_ssl_free()`、`mbedtls_ssl_config_free()` | `wolfSSL_free()`、`wolfSSL_CTX_free()` | | +| `mbedtls_psa_crypto_free()` | `wolfSSL_Cleanup()` | | + +## 証明書、鍵、検証 + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| `mbedtls_x509_crt_parse_file()` + `mbedtls_ssl_conf_ca_chain()` | `wolfSSL_CTX_load_verify_locations()` | | +| `mbedtls_x509_crt_parse()` + `mbedtls_ssl_conf_ca_chain()` | `wolfSSL_CTX_load_verify_buffer()` | Mbed TLS と同じバッファと長さを使用可能。フォーマットは明示的に指定する | +| `mbedtls_x509_crt_parse_file()` + `mbedtls_pk_parse_keyfile()` + `mbedtls_ssl_conf_own_cert()` | `wolfSSL_CTX_use_certificate_chain_file()` + `wolfSSL_CTX_use_PrivateKey_file()` | PEM のみ。DER 証明書には `WOLFSSL_FILETYPE_ASN1` を指定して `wolfSSL_CTX_use_certificate_file()` を使用。`mbedtls_pk_parse_keyfile()` は 3.6 では RNG の引数を取るが、4.x では取らない | +| 上記のバッファ版 | `wolfSSL_CTX_use_certificate_chain_buffer()` + `wolfSSL_CTX_use_PrivateKey_buffer()` | PEM のみ。DER には `WOLFSSL_FILETYPE_ASN1` を指定して `wolfSSL_CTX_use_certificate_buffer()` を使用 | +| `mbedtls_ssl_conf_authmode()` | `wolfSSL_CTX_set_verify()` | REQUIRED: `WOLFSSL_VERIFY_PEER`（サーバーではさらに `WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT`）。OPTIONAL: `WOLFSSL_VERIFY_PEER` と 1 を返すコールバック。NONE: `WOLFSSL_VERIFY_NONE` | +| `mbedtls_ssl_conf_verify()` | `wolfSSL_CTX_set_verify()` のコールバック引数 | 証明書チェーンは DER 形式で `store->certs[]` に渡される。`wc_InitDecodedCert()` + `wc_ParseCert()` でパースする。`store->current_cert` には `--enable-opensslextra` が必要。デフォルトでは、コールバックは検証に失敗した証明書に対してのみ呼ばれる。`WOLFSSL_ALWAYS_VERIFY_CB` を定義すると成功時にも、`WOLFSSL_VERIFY_CB_ALL_CERTS` を定義するとすべての中間証明書に対して呼ばれる。`--enable-opensslextra` は両方を定義する | +| `mbedtls_ssl_set_hostname()` | `wolfSSL_UseSNI()` + `wolfSSL_check_domain_name()` | IP アドレスには `wolfSSL_check_ip_address()`。[よくある落とし穴](chapter04.md)を参照 | +| `mbedtls_ssl_conf_sni()`（サーバー） | `wolfSSL_CTX_set_servername_callback()` + `wolfSSL_SNI_GetRequest()` | SNI が必要 | +| `mbedtls_ssl_conf_own_cert()` での不透明鍵またはセキュアエレメント内の鍵 | デバイス ID を指定した `wolfSSL_CTX_use_PrivateKey_Id()` / `wolfSSL_CTX_use_PrivateKey_Label()` | `--enable-cryptocb` または `--enable-pkcs11` が必要 | +| `mbedtls_ssl_get_verify_result()` | `wolfSSL_get_verify_result()` | `--enable-opensslextra` が必要。検証に失敗した場合はすでにハンドシェイクが失敗している | +| `mbedtls_ssl_get_peer_cert()` | `wolfSSL_get_peer_certificate()` | コピーを返すため、`wolfSSL_X509_free()` で解放する。`--enable-opensslextra` が必要。ない場合は `--enable-sessioncerts` を指定して `wolfSSL_get_peer_chain()` + `wolfSSL_get_chain_cert()` を使用 | + +## 接続と I/O + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| `mbedtls_net_connect()`、`mbedtls_net_bind()`、`mbedtls_net_accept()` | アプリケーションのソケットコード | wolfSSL にはソケットのヘルパー API はない | +| `mbedtls_net_send()` / `mbedtls_net_recv()` を指定した `mbedtls_ssl_set_bio()` | `wolfSSL_set_fd()` | | +| カスタムコールバックを指定した `mbedtls_ssl_set_bio()` | `wolfSSL_CTX_SetIOSend()` / `wolfSSL_CTX_SetIORecv()` + `wolfSSL_SetIOWriteCtx()` / `wolfSSL_SetIOReadCtx()` | セッション単位では `wolfSSL_SSLSetIOSend()` / `wolfSSL_SSLSetIORecv()` | +| `mbedtls_ssl_handshake()` | `wolfSSL_connect()` / `wolfSSL_accept()` | どちらのロールでも使える `wolfSSL_negotiate()` もある | +| `mbedtls_ssl_read()`、`mbedtls_ssl_write()` | `wolfSSL_read()`、`wolfSSL_write()` | | +| `mbedtls_ssl_get_bytes_avail()` | `wolfSSL_pending()` | | +| `mbedtls_ssl_close_notify()` | `wolfSSL_shutdown()` | | + +## エラーとデバッグ + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| 戻り値として直接返される `MBEDTLS_ERR_SSL_WANT_READ` / `_WANT_WRITE` | `wolfSSL_get_error()` が `WOLFSSL_ERROR_WANT_READ` / `_WANT_WRITE` を返す | | +| カスタム受信コールバックから返す `MBEDTLS_ERR_SSL_WANT_READ` | `WOLFSSL_CBIO_ERR_WANT_READ` | [よくある落とし穴](chapter04.md)を参照 | +| `MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY` | `WOLFSSL_ERROR_ZERO_RETURN` | | +| `MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET` | 不要 | チケットは内部で処理される | +| `mbedtls_strerror()` | `wolfSSL_ERR_error_string_n()`、`wc_GetErrorString()` | | +| `mbedtls_ssl_conf_dbg()` + `mbedtls_debug_set_threshold()` | `wolfSSL_SetLoggingCb()` + `wolfSSL_Debugging_ON()` | `--enable-debug` が必要 | + +## セッション、PSK、拡張 + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| `mbedtls_ssl_get_session()` | `wolfSSL_get1_session()` | `wolfSSL_SESSION_free()` で解放する。`wolfSSL_get_session()` が返すポインタは `WOLFSSL` とともに解放される | +| `mbedtls_ssl_set_session()` | `wolfSSL_set_session()` | | +| `mbedtls_ssl_cache_*` + `mbedtls_ssl_conf_session_cache()` | 組み込みのセッションキャッシュ | | +| `mbedtls_ssl_ticket_setup()` + `mbedtls_ssl_conf_session_tickets_cb()` | `--enable-session-ticket`、必要に応じて `wolfSSL_CTX_set_TicketEncCb()` | `mbedtls_ssl_ticket_setup()` は 4.x で引数が変更された | +| `mbedtls_ssl_conf_psk()` | `wolfSSL_CTX_set_psk_client_callback()` / `wolfSSL_CTX_set_psk_server_callback()` | TLS 1.3 用は名前に `_tls13_` が付く | +| `mbedtls_ssl_conf_alpn_protocols()` + `mbedtls_ssl_get_alpn_protocol()` | `wolfSSL_UseALPN()` + `wolfSSL_ALPN_GetProtocol()` | セッション単位。カンマ区切りの文字列と、`WOLFSSL_ALPN_FAILED_ON_MISMATCH` または `WOLFSSL_ALPN_CONTINUE_ON_MISMATCH` を受け取る。4.x では Mbed TLS のリストの型が `const char *const *` に変更された | +| `mbedtls_ssl_conf_ciphersuites()` | `wolfSSL_CTX_set_cipher_list()` | コロン区切りの文字列を受け取る | +| `mbedtls_ssl_conf_groups()` | `wolfSSL_CTX_set_groups()` または `wolfSSL_set_groups()` | ClientHello で送信する鍵共有を選ぶには `wolfSSL_UseKeyShare()` を追加する。`wolfSSL_UseKeyShare()` 単独では、HelloRetryRequest でネゴシエートされうるグループは制限されない | +| `mbedtls_ssl_conf_max_frag_len()` | `wolfSSL_UseMaxFragment()` | | + +## DTLS + +| Mbed TLS | wolfSSL | 備考 | +| ------------------------------------- | ------------------------------------- | -------------------------- | +| `mbedtls_ssl_config_defaults()` での `MBEDTLS_SSL_TRANSPORT_DATAGRAM` | `wolfDTLS_client_method()`、`wolfDTLSv1_3_client_method()` および対応するサーバー用メソッド | | +| `mbedtls_ssl_set_timer_cb()` | `wolfSSL_dtls_get_current_timeout()` + `wolfSSL_dtls_got_timeout()` | ノンブロッキングソケットまたはカスタム受信コールバックを使う場合のみ必要。カスタム受信コールバックの待ち時間は最大 `wolfSSL_dtls_get_current_timeout()` 秒とする | +| `mbedtls_ssl_conf_handshake_timeout()` | `wolfSSL_dtls_set_timeout_init()` + `wolfSSL_dtls_set_timeout_max()` | セッション単位。`wolfSSL_new()` の後に呼び出す。値はミリ秒ではなく秒単位で、init は max（デフォルト 64）を超えてはならない | +| `mbedtls_ssl_cookie_setup()` + `mbedtls_ssl_conf_dtls_cookies()` | 組み込み | | +| 共有の UDP ソケット 1 つでの Cookie 交換 | `wolfDTLS_accept_stateless()` | サーバー側 | +| `mbedtls_ssl_set_client_transport_id()` | `wolfSSL_dtls_set_peer()` | | +| `mbedtls_ssl_set_cid()` | `wolfSSL_dtls_cid_use()` + `wolfSSL_dtls_cid_set()` | `--enable-dtlscid` が必要 | +| `mbedtls_ssl_set_mtu()` | `wolfSSL_dtls_set_mtu()` | `--enable-dtls-mtu` が必要 | diff --git a/MbedTLS-Migration/src-ja/chapter09.md b/MbedTLS-Migration/src-ja/chapter09.md new file mode 100644 index 00000000..49a0c2ca --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter09.md @@ -0,0 +1,35 @@ +# 設定オプションの対応 + +| Mbed TLS のオプション | wolfSSL の configure オプション | `user_settings.h` のマクロ | +| -------------------------------------- | -------------------------------------- | ------------------------ | +| `MBEDTLS_SSL_PROTO_TLS1_3` | デフォルトで有効（`--enable-tls13`） | `WOLFSSL_TLS13` | +| `MBEDTLS_SSL_PROTO_DTLS` | `--enable-dtls`（DTLS 1.3 にはさらに `--enable-dtls13`） | `WOLFSSL_DTLS`、`WOLFSSL_DTLS13` | +| `MBEDTLS_SSL_DTLS_CONNECTION_ID` | `--enable-dtlscid` | `WOLFSSL_DTLS_CID` | +| `MBEDTLS_SSL_DTLS_SRTP` | `--enable-srtp` | `WOLFSSL_SRTP` | +| `MBEDTLS_SSL_SERVER_NAME_INDICATION` | `--enable-sni`（デフォルトで有効なのは x86 および aarch64 ホストのみ） | `HAVE_SNI` | +| `MBEDTLS_SSL_ALPN` | `--enable-alpn` | `HAVE_ALPN` | +| `MBEDTLS_SSL_SESSION_TICKETS` | `--enable-session-ticket`。wolfSSL 5.9.4 以前では、Mbed TLS の TLS 1.3 サーバーと通信するクライアントに `--enable-ticket-nonce-malloc` も必要 | `HAVE_SESSION_TICKET`、`WOLFSSL_TICKET_NONCE_MALLOC` | +| `MBEDTLS_SSL_EARLY_DATA` | `--enable-earlydata` と、`--enable-session-ticket` または `--enable-psk` | `WOLFSSL_EARLY_DATA` | +| `MBEDTLS_SSL_MAX_FRAGMENT_LENGTH` | `--enable-maxfragment` | `HAVE_MAX_FRAGMENT` | +| `MBEDTLS_SSL_RENEGOTIATION` | `--enable-secure-renegotiation`。アプリケーションが `mbedtls_ssl_conf_renegotiation()` で再ネゴシエーションを有効にしている場合のみ | `HAVE_SECURE_RENEGOTIATION` | +| `MBEDTLS_KEY_EXCHANGE_*PSK*` | `--enable-psk`（RSA-PSK 暗号スイートは非対応） | `NO_PSK` を定義しない | +| `MBEDTLS_KEY_EXCHANGE_RSA_ENABLED`（3.6） | `CFLAGS=-DWOLFSSL_STATIC_RSA`。静的 RSA には前方秘匿性がなく、4.x では廃止されている | `WOLFSSL_STATIC_RSA` | +| `MBEDTLS_CCM_C` / `PSA_WANT_ALG_CCM` | `--enable-aesccm` | `HAVE_AESCCM` | +| `PSA_WANT_ECC_MONTGOMERY_255` / `MBEDTLS_ECP_DP_CURVE25519_ENABLED` | `--enable-curve25519` | `HAVE_CURVE25519` | +| `MBEDTLS_LMS_C` | `--enable-lms` | `WOLFSSL_HAVE_LMS` | +| 相当するものなし（ML-KEM） | デフォルトで有効（`--enable-mlkem`）。単体の ML-KEM 鍵交換には `--enable-tls-mlkem-standalone` が必要 | `WOLFSSL_HAVE_MLKEM`（`WOLFSSL_SHA3`、`WOLFSSL_SHAKE128`、`WOLFSSL_SHAKE256` とともに）、および configure のデフォルトに合わせるための `WOLFSSL_PQC_HYBRIDS` と `WOLFSSL_TLS_NO_MLKEM_STANDALONE` | +| 実験的な ML-DSA-87（開発ブランチのみ） | `--enable-mldsa`、`--enable-slhdsa` | `WOLFSSL_HAVE_MLDSA`、`WOLFSSL_HAVE_SLHDSA`（`WOLFSSL_SHA3`、`WOLFSSL_SHAKE128`、`WOLFSSL_SHAKE256` とともに） | +| `MBEDTLS_MEMORY_BUFFER_ALLOC_C` | `--enable-staticmemory` | `WOLFSSL_STATIC_MEMORY` | +| `MBEDTLS_THREADING_C` | デフォルトで有効（無効にするには `--enable-singlethreaded`） | 無効にするには `SINGLE_THREADED` を定義 | +| `MBEDTLS_DEBUG_C` | `--enable-debug` | `DEBUG_WOLFSSL` | +| 暗号の `MBEDTLS_*_ALT`、PSA ドライバ | `--enable-cryptocb` | `WOLF_CRYPTO_CB` | + +この表のデフォルトは `./configure` と CMake に適用されます。 +`user_settings.h` を使うビルドでは、TLS 1.3、ML-KEM、ハイブリッドグループ、SNI などの機能は定義した場合にのみ有効になります。 +そのため、空のファイルからではなく、`examples/configs/user_settings_tls13.h`（または `user_settings_dtls13.h`、`user_settings_pq.h`）から始めてください。 +これらのテンプレートはいずれもハイブリッドグループを有効にしていません。 +`user_settings_pq.h` には `WOLFSSL_PQC_HYBRIDS` と `WOLFSSL_TLS_NO_MLKEM_STANDALONE` を追加してください。 +TLS 1.3 と DTLS 1.3 のテンプレートでは、さらに `WOLFSSL_HAVE_MLKEM`、`WOLFSSL_SHA3`、`WOLFSSL_SHAKE128`、`WOLFSSL_SHAKE256` が必要です。 +DTLS 1.3 のテンプレートには `HAVE_SNI` と `WOLFSSL_DTLS_CH_FRAG` も必要です。 +DTLS 1.3 サーバーは、フラグメント化された ClientHello を受け付けるために `wolfSSL_dtls13_allow_ch_frag()` も呼び出す必要があります。 +フラグメント化が許されるのは、Cookie を含む 2 回目の ClientHello のみです。 diff --git a/MbedTLS-Migration/src-ja/chapter10.md b/MbedTLS-Migration/src-ja/chapter10.md new file mode 100644 index 00000000..409f1e56 --- /dev/null +++ b/MbedTLS-Migration/src-ja/chapter10.md @@ -0,0 +1,40 @@ +# サポート + +wolfSSL は、Mbed TLS から移行するユーザー向けに複数のサポート窓口を用意しています。 + +## 商用サポート + +wolfSSL Inc. は、wolfSSL のエンジニアリングチームに直接相談できる商用サポートパッケージを提供しています。 +商用サポートでは次の内容に対応しています。 + +- 移行支援とコンサルティング +- FIPS 140-3 の導入に関するガイダンス +- カスタム機能の開発 +- プラットフォームへの移植と統合 + +商用サポートおよびライセンスに関するお問い合わせは、wolfSSL までご連絡ください。 + +- 電子メール（日本語）: [info@wolfssl.jp](mailto:info@wolfssl.jp) +- 電子メール（英語）: [facts@wolfssl.com](mailto:facts@wolfssl.com) +- Web: [https://www.wolfssl.jp/](https://www.wolfssl.jp/)、[https://www.wolfssl.com/contact/](https://www.wolfssl.com/contact/) + +wolfSSL では、ご購入前のサポートも無料で提供しています。 +ご質問や問題がありましたら、サポートチームまで直接お問い合わせください。 + +- 電子メール: [support@wolfssl.com](mailto:support@wolfssl.com)（日本語可） + +## コミュニティリソース + +- **wolfSSL GitHub** - [https://github.com/wolfSSL](https://github.com/wolfSSL) +- **wolfSSL フォーラム** - [https://www.wolfssl.com/forums/](https://www.wolfssl.com/forums/) + +## 関連ドキュメント + +- [wolfSSL マニュアル](https://www.wolfssl.com/documentation/manuals/jp/wolfssl/) +- [wolfSSL ポーティングガイド](https://www.wolfssl.com/documentation/manuals/wolfssl-porting-guide/)（英語） +- [wolfSSL チューニングガイド](https://www.wolfssl.com/documentation/manuals/wolfssl-tuning-guide/)（英語） +- [wolfSSL FIPS FAQ](https://www.wolfssl.com/documentation/manuals/wolfssl-fips-faq/)（英語） + +## 問題の報告 + +wolfSSL のバグや問題は、[wolfSSL GitHub リポジトリ](https://github.com/wolfSSL/wolfssl/issues)にご報告ください。