Merge pull request #228 from tamasan238/pr216

[JA] wolfProvider - general documentation update

Author: kojo1

wolfProvider/mkdocs-ja.yml

@@ -2,7 +2,7 @@ site_name: wolfProvider マニュアル
 site_url: https://wolfssl.com/
 docs_dir: build/html/
 site_dir: html/
-copyright: Copyright © 2024 wolfSSL Inc.
+copyright: Copyright © 2025 wolfSSL Inc.
 nav:
     - "1. イントロダクション": index.md
     - "2. OpenSSLとの互換性": chapter02.md

wolfProvider/src-ja/chapter01.md

@@ -10,9 +10,9 @@ wolfProviderの概要図、そしてアプリケーションやOpenSSLとどの
 
 wolfProviderの設計とアーキテクチャの詳細については、[wolfProviderの設計](chapter09.md) の章をご覧ください。
 
-![wolfProvider Overview](../png/wolfProvider_overview.png)
+![wolfProvider Overview](wolfProvider_overview.png)
 
-wolfProviderは、**libwolfprovider** という名前の共有ライブラリとしてコンパイルされます。
+wolfProviderは、**libwolfprov** という名前の共有ライブラリとしてコンパイルされます。
 これは、アプリケーションまたはコンフィギュレーションファイルを介してOpenSSLによって実行時に動的に登録できます。
 wolfProviderは、アプリケーションが静的ビルドでコンパイルされたときにエンジンをロードするためのエントリポイントも提供します。
 

wolfProvider/src-ja/chapter02.md

@@ -3,7 +3,7 @@
 wolfProviderは、以下のバージョンのOpenSSLを使用してテストを実行しています。
 これ以外のバージョンでは、変更や調整が必要になる場合があります。
 
-- OpenSSL 1.0.2h
-- OpenSSL 1.1.1b
+- OpenSSL 3.0.0
+- OpenSSL 3.5.0
 
 他のOpenSSLバージョンのサポート追加を希望される場合は、[[email protected]](mailto:[email protected]) にご連絡ください。

wolfProvider/src-ja/chapter03.md

@@ -8,23 +8,7 @@ autoconfを使用している場合、これは`./configure`に`--enable-debug`
 ./configure --enable-debug
 ```
 
-autoconf/configureを使用しない場合は、wolfProviderライブラリをコンパイルする際に `WOLFPROVIDER_DEBUG` を定義します。
-
-## デバッグログの有効化/無効化
-
-デバッグサポートを有効化してコンパイルを行った後、以下に示すwolfProviderコントロールコマンドを使用して実行時にデバッグを有効にする必要があります。
-"0" を指定すると、ログ出力が無効になります。
-`PROVIDER_ctrl_cmd()` APIを使用してログ出力を有効にする例を以下に示します。
-
-```
-int ret = 0;
-ret = PROVIDER_ctrl_cmd(e, “enable_debug”, 1, NULL, NULL, 0);
-if (ret != 1) {
-    printf(“Failed to enable debug logging\n”);
-}
-```
-
-wolfProviderがデバッグサポート無効の状態でコンパイルされた場合、`PROVIDER_ctrl_cmd()`で`enable_debug`を設定しようとすると失敗(0)が返されます。
+autoconf/configureを使用しない場合は、wolfProviderライブラリをコンパイルする際に `WOLFPROV_DEBUG` を定義します。
 
 ## ログ出力レベルの制御
 
@@ -70,9 +54,10 @@ wolfProviderでは、コンポーネントごとにログを出力できます
 | WP_LOG_CIPHER | 暗号化コンポーネント(AES, 3DES) | 0x0008 |
 | WP_LOG_PK     | 公開鍵コンポーネント (RSA, ECC) | 0x0010 |
 | WP_LOG_KE     | 鍵合意コンポーネント (DH, ECDH) | 0x0020 |
-| WP_LOG_PROVIDER | エンジン特有 | 0x0040 |
-| WP_LOG_COMPONENTS_ALL | 全コンポーネント | WP_LOG_RNG | WP_LOG_DIGEST | WP_LOG_MAC | WP_LOG_CIPHER | WP_LOG_PK | WP_LOG_KE | WP_LOG_PROVIDER |
-| WP_LOG_COMPONENTS_DEFAULT | デフォルトコンポーネント (all). | WP_LOG_COMPONENTS_ALL |
+| WP_LOG_KDF    | パスワードベースの鍵導出コンポーネント | 0x0040 |
+| WP_LOG_PROVIDER | すべてのプロバイダー固有ログを有効化 | 0x0080 |
+| WP_LOG_COMPONENTS_ALL | すべてのコンポーネントログを有効化 | WP_LOG_RNG | WP_LOG_DIGEST | WP_LOG_MAC | WP_LOG_CIPHER | WP_LOG_PK | WP_LOG_KE | WP_LOG_PROVIDER |
+| WP_LOG_COMPONENTS_DEFAULT | デフォルト構成 (すべてのログを有効化) | WP_LOG_COMPONENTS_ALL |
 
 デフォルトでは、すべてのコンポーネントを対象としてログを出力します(`WP_LOG_COMPONENTS_DEFAULT`)。
 
@@ -120,7 +105,7 @@ const char* const logMessage)
     fprintf(stderr, “wolfProvider log message: %d\n”, logMessage);
 }
 
-int **main** (void)
+int main (void)
 {
     int ret;
     PROVIDER* e;

wolfProvider/src-ja/chapter05.md

@@ -1,57 +1,45 @@
 # wolfProviderのロード
 
-## OpenSSLをエンジンを利用できるように構成
+## OpenSSLをエンジンプロバイダーを利用できるように構成
 
-アプリケーションがOpenSSLエンジンを使用および使用する方法については、OpenSSLのドキュメントをご参照ください。
+アプリケーションがOpenSSLプロバイダーを使用するための手順については、OpenSSLドキュメントをご参照ください。
 
-- [OpenSSL 1.0.2](https://www.openssl.org/docs/man1.0.2/man3/provider.html)
-- [OpenSSL 1.1.1](https://www.openssl.org/docs/man1.1.1/man3/PROVIDER_add.html)
-
-アプリケーションがエンジンを使用するための方法はいくつかあります。
-最も単純なものとして、OpenSSLにバンドルされているすべてのPROVIDER実装をロードして登録し、アプリケーションで次のコードを呼び出す方法があります。
- (上記のOpenSSLドキュメントから引用しています)
-```
-/* For OpenSSL 1.0.2, need to make the “dynamic” PROVIDER available */
-PROVIDER_load_dynamic();
-
-/* Load all bundled PROVIDERs into memory and make them visible */
-PROVIDER_load_builtin_providers();
-
-/* Register all of them for every algorithm they collectively implement */
-PROVIDER_register_all_complete();
-```
+- [OpenSSL 3.0](https://www.openssl.org/docs/man3.0/man7/provider.html)
+- [OpenSSL 3.5](https://www.openssl.org/docs/man3.5/man7/provider.html)
 
 アプリケーションがOpenSSL設定ファイルを使用するように設定されている場合、
 追加のプロバイダー設定ステップをそこで行うことができます。
 OpenSSLを構成する方法については、OpenSSLドキュメントをご覧ください。
 
-- [OpenSSL 1.0.2 ドキュメント](https://www.openssl.org/docs/man1.0.2/man3/OPENSSL_config.html)
-- [OpenSSL 1.1.1 ドキュメント](https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_config.html)
+- [OpenSSL 3.0](https://www.openssl.org/docs/man3.0/man5/config.html)
+- [OpenSSL 3.5](https://www.openssl.org/docs/man3.5/man5/config.html)
 
 アプリケーションはデフォルトのOpenSSL構成ファイル (`openssl.cnf`)や、
 `OPENSSL_CONF`環境変数によって設定された構成の `[openssl_conf]` セクションを呼び出して、読み取り、使用できます。
 
-```
-OPENSSL_config(NULL);
-```
-
-OpenSSLコンフィギュレーションファイルを使用する代わりに、アプリケーションは`PROVIDER_*` APIを使用して明示的に wolfProviderの初期化やアルゴリズムの登録を行うこともできます。 
+OpenSSLコンフィギュレーションファイルを使用する代わりに、アプリケーションは`OSSL_PROVIDER_*` APIを使用して明示的に wolfProviderの初期化やアルゴリズムの登録を行うこともできます。 
 一例として、wolfProviderの初期化とすべてのアルゴリズムの登録を行う場合を以下に示します。
 
 ```
-PROVIDER* e = NULL;
-
-e = PROVIDER_by_id(“wolfprovider”);
-if (e == NULL) {
-    printf(“Failed to find wolfProvider\n”);
-    /* error */
-}
-PROVIDER_set_default(e, PROVIDER_METHOD_ALL);
-
-/* アプリケーションの実装 */
-
-PROVIDER_finish(e);
-PROVIDER_cleanup();
+    OSSL_PROVIDER *prov = NULL;
+    const char *build = NULL;
+    OSSL_PARAM request[] = {
+        { "buildinfo", OSSL_PARAM_UTF8_PTR, &build, 0, 0 },
+        { NULL, 0, NULL, 0, 0 }
+    };
+
+    if ((prov = OSSL_PROVIDER_load(NULL, "libwolfprov")) != NULL
+        && OSSL_PROVIDER_get_params(prov, request))
+        printf("Provider 'libwolfprov' buildinfo: %s\n", build);
+    else
+        ERR_print_errors_fp(stderr);
+
+    if (OSSL_PROVIDER_self_test(prov) == 0)
+        printf("Provider selftest failed\n");
+    else
+        printf("Provider selftest passed\n");
+
+    OSSL_PROVIDER_unload(prov);
 ```
 
 ## OpenSSLコンフィギュレーションファイルによるwolfProviderのロード
@@ -60,28 +48,18 @@ OpenSSLを使用するアプリケーションがコンフィギュレーショ
 wolfProviderはOpenSSLコンフィギュレーションファイルからロードできます。 
 
 wolfProviderライブラリをコンフィギュレーションファイルに追加する方法の例を以下に示します。
-`[wolfssl_section]`は、必要に応じてエンジン制御コマンド(`enable_debug`)を設定するように変更できます。
 
 ```
 openssl_conf = openssl_init
 
 [openssl_init]
-providers = provider_section
-
-[provider_section]
-wolfSSL = wolfssl_section
-
-[wolfssl_section]
-# If using OpenSSL <= 1.0.2, change provider_id to wolfprovider
-(drop the "lib").
-provider_id = libwolfprovider
-# dynamic_path = .libs/libwolfprovider.so
-init = 1
-# Use wolfProvider as the default for all algorithms it provides.
-default_algorithms = ALL
-# Only enable when debugging application - produces large
-amounts of output.
-# enable_debug = 1
+providers = provider_sect
+
+[provider_sect]
+libwolfprov = libwolfprov_sect
+
+[libwolfprov_sect]
+activate = 1
 ```
 
 ## wolfProvider静的エントリポイント
@@ -91,5 +69,5 @@ wolfProviderをロードできます。
 
 ```
 #include <wolfprovider/wp_wolfprovider.h>
-PROVIDER_load_wolfprovider();
+wolfssl_provider_init(const OSSL_CORE_HANDLE* handle, const OSSL_DISPATCH* in, const OSSL_DISPATCH** out, void** provCtx);
 ```

wolfProvider/src-ja/chapter07.md

@@ -2,58 +2,76 @@
 
 wolfProviderは次のソースファイルで構成され、すべてwolfProviderパッケージの`src`サブディレクトリの下にあります。
 
-| ソースファイル | 詳細 |
-| ---- | ---------------- |
-| wp_wolfprovider.c | ライブラリエントリポイントが含まれます。 OpenSSLエンジンフレームワークを使用してライブラリを動的にロードするために、OpenSSL IMPLEMENT_DYNAMIC_BIND_FNを呼び出します。コンパイルして静的ライブラリとして使用する場合のスタティックエントリポイントも含みます。 |
-| wp_internal.c | エンジンアルゴリズムコールバックの登録を処理する`wolfprovider_bind()`関数が含まれています。他のwolfProviderの内部機能も含みます。 |
-| wp_logging.c | wolfProviderログ出力フレームワークと関数の実装 |
-| wp_openssl_bc.c | wolfProvider OpenSSLバイナリ互換抽象化レイヤーです。複数のOpenSSLバージョンでwolfProviderをサポートするために使用します。 |
-| wp_aes_block.c | wolfProvider AES-ECBおよびAES-CBC実装 |
-| wp_aes_cbc_hmac.c | wolfProvider AES-CBC-HMAC実装 |
-| wp_aes_ccm.c | wolfProvider AES-CCM実装 |
-| wp_aes_ctr.c | wolfProvider AES-CTR実装 |
-| wp_aes_gcm.c | wolfProvider AES-GCM実装 |
-| wp_des3_cbc.c | wolfProvider 3DES-CBCの実装 |
-| wp_dh.c | wolfProvider DHの実装 |
-| wp_digest.c | wolfProvider メッセージダイジェストの実装(SHA-1、SHA-2、SHA-3) |
-| wp_ecc.c | wolfProvider ECDSAおよびECDHの実装 |
-| wp_mac.c | wolfProvider HMACおよびCMACの実装 |
-| wp_random.c | wolfProvider RAND実装 |
-| wp_rsa.c | wolfProvider RSA実装 |
-| wp_tls_prf.c | wolfProvider TLS 1.0 PRF実装 |
+| ソースファイル | 説明 |
+| ------ | ---------------- |
+| wp_wolfprov.c | ライブラリのエントリポイントが含まれています。OpenSSL プロバイダフレームワークを使用してライブラリを動的にロードするために、OpenSSL IMPLEMENT_DYNAMIC_BIND_FN を呼び出します。コンパイルして静的ライブラリとして使用する場合は、静的エントリポイントも含みます。 |
+| wp_internal.c | プロバイダアルゴリズムのコールバックの登録を処理する wolfprovider_bind() 関数が含まれています。また、その他の wolfprovider 内部機能も含みます。 |
+| wp_logging.c | wolfProvider のロギングフレームワークと関数の実装 |
+| wp_aes_aead.c | wolfProvider AES-AEAD (Authenticated Encryption with Associated Data) の実装 |
+| wp_aes_block.c | wolfProvider AES-ECB および AES-CBC 実装 |
+| wp_aes_stream.c | wolfProvider AES ストリーム暗号実装 |
+| wp_aes_wrap.c | wolfProvider AES キーラッピング実装 |
+| wp_cmac.c | wolfProvider CMAC (暗号ベースメッセージ認証コード) 実装 |
+| wp_dec_epki2pki.c | wolfProvider 暗号化された秘密鍵から秘密鍵への変換実装 |
+| wp_dec_pem2der.c | wolfProvider PEM から DER 形式への変換実装 |
+| wp_des.c | wolfProvider DES 実装 |
+| wp_dh_exch.c | wolfProvider DH 鍵交換実装 |
+| wp_dh_kmgmt.c | wolfProvider DH 鍵管理実装 |
+| wp_digests.c | wolfProvider メッセージ ダイジェスト実装 (SHA-1、SHA-2、SHA-3、...)|
+| wp_drbg.c | wolfProvider DRBG (決定論的乱数ビット ジェネレーター) 実装|
+| wp_ecc_kmgmt.c | wolfProvider ECC キー管理実装|
+| wp_ecdh_exch.c | wolfProvider ECDH キー交換実装|
+| wp_ecdsa_sig.c | wolfProvider ECDSA 署名実装|
+| wp_ecx_exch.c | wolfProvider ECX キー交換実装 (X25519、X448、...)|
+| wp_ecx_kmgmt.c | wolfProvider ECX キー管理実装|
+| wp_ecx_sig.c | wolfProvider ECX 署名実装 (Ed25519、Ed448、...)|
+| wp_file_store.c | wolfProvider ファイルストレージ実装|
+| wp_fips.c | wolfProvider FIPS 検証実装|
+| wp_gmac.c | wolfProvider GMAC (Galois/Counter Mode) 実装|
+| wp_hkdf.c | wolfProvider HKDF (HMAC ベースの鍵導出関数) 実装|
+| wp_hmac.c | wolfProvider HMAC 実装|
+| wp_kbkdf.c | wolfProvider KBKDF (鍵ベースの鍵導出関数) 実装|
+| wp_kdf_exch.c | wolfProvider KDF 鍵交換実装|
+| wp_kdf_kmgmt.c | wolfProvider KDF 鍵管理実装|
+| wp_krb5kdf.c | wolfProvider Kerberos 5 KDF 実装|
+| wp_mac_kmgmt.c | wolfProvider MAC キー管理実装|
+| wp_mac_sig.c | wolfProvider MAC 署名実装|
+| wp_params.c | wolfProvider パラメータ処理実装|
+| wp_pbkdf2.c | wolfProvider PBKDF2 (パスワードベースのキー導出関数 2) 実装|
+| wp_rsa_asym.c | wolfProvider RSA 非対称暗号化実装|
+| wp_rsa_kem.c | wolfProvider RSA KEM (キーカプセル化メカニズム) 実装|
+| wp_rsa_kmgmt.c | wolfProvider RSA キー管理実装|
+| wp_rsa_sig.c | wolfProvider RSA 署名実装|
+| wp_tls1_prf.c | wolfProvider TLS 1.0 PRF 実装|
+| wp_tls_capa.c | wolfProvider TLS 機能の実装 |
 
 ## wolfProviderエントリーポイント
 
-wolfProviderライブラリへの主なエントリポイントは、**wolfprovider_bind** () または **PROVIDER_load_wolfprovider** () のいずれかです。
-wolfProviderが動的にロードされている場合、`wolfprovider_bind()`はOpenSSL によって自動的に呼び出されます。
-`PROVIDER_load_wolfprovider()` はwolfProvider静的に構築および使用されている場合に、アプリケーションが呼び出す必要があるエントリポイントです。
-
-## wolfProviderアルゴリズムコールバック登録
-
-wolfProviderは、FIPS版wolfCryptでサポートしているすべてのコンポーネントに対して、アルゴリズム構造体とコールバックを OpenSSLエンジンフレームワークに登録します。
-この登録は、`wp_internal.c` の `wolfprovider_bind()` 内で行われます。
-`wolfprovider_bind()`は、wolfProvider エンジンを表す`PROVIDER`構造体ポインタを受け取ります。
-次に、個々のアルゴリズム/コンポーネントのコールバックまたは構造体が、`<openssl/provider.h>`の適切なAPIを使用してその`PROVIDER`構造体に登録されます。
-
-これらのAPI呼び出しには、以下のものが含まれます。
-
-```
-PROVIDER_set_id(e, wolfprovider_id)
-PROVIDER_set_name(e, wolfprovider_name)
-PROVIDER_set_digests(e, wp_digests)
-PROVIDER_set_ciphers(e, wp_ciphers)
-PROVIDER_set_RAND(e, wp_random_method)
-PROVIDER_set_RSA(e, wp_rsa())
-PROVIDER_set_DH(e, wp_dh_method)
-PROVIDER_set_ECDSA(e, wp_ecdsa())
-PROVIDER_set_pkey_meths(e, wp_pkey)
-PROVIDER_set_pkey_asn1_meths(e, wp_pkey_asn1)
-PROVIDER_set_EC(e, wp_ec())
-PROVIDER_set_ECDH(e, wp_ecdh())
-PROVIDER_set_destroy_function(e, wolfprovider_destroy)
-PROVIDER_set_cmd_defns(e, wolfprovider_cmd_defns)
-PROVIDER_set_ctrl_function(e, wolfprovider_ctrl)
-```
-
-上記の呼び出しで使用される各アルゴリズム/コンポーネントのコールバック関数または構造体
-(例: wp_digests、wp_ciphers など) は、`wp_internal.c` またはそれぞれのアルゴリズムソースファイルに実装しています。
+wolfProvider ライブラリへの主要なエントリポイントは、**OSSL_provider_init()** と **wolfssl_provider_init()** です。
+
+**OSSL_provider_init()** は、プロバイダが動的にロードされた際に OpenSSL によって自動的に呼び出される標準のOpenSSLプロバイダエントリポイントです。
+この関数は `wp_wolfprov.c` で定義されており、`wolfssl_provider_init()` を呼び出すラッパーとして機能します。
+
+**wolfssl_provider_init()** は、以下の機能を実行するコア初期化関数です。
+
+- プロバイダーコンテキストをセットアップします。
+- プロバイダー関数でディスパッチテーブルを初期化します。
+- FIPS モード設定を処理します。
+- デバッグが有効になっている場合は、デバッグをセットアップします。
+- 以下の関数ポインタを含むプロバイダーのディスパッチテーブルを返します。
+
+* `wolfprov_teardown` - プロバイダーのクリーンアップ
+* `wolfprov_gettable_params` - パラメーターテーブルの取得
+* `wolfprov_get_params` - パラメーターの取得
+* `wolfprov_query` - 操作のクエリ
+* `wolfssl_prov_get_capabilities` - 機能レポート
+
+アプリケーションがwolfProviderアルゴリズムを要求すると、OpenSSLによってプロバイダーがロードされます。
+ディスパッチテーブルは、OpenSSLが暗号操作に適切なwolfProvider関数を呼び出すことを可能にします。
+
+## wolfProvider ディスパッチテーブル関数
+
+wolfProviderディスパッチテーブルには、プロバイダー操作のさまざまな側面を処理するいくつかの主要な関数が含まれています。
+各関数は、OpenSSLプロバイダフレームワークにおいて特定の目的を果たします。
+
+**OSSLパラメータに関する注意（後述）:** OSSLパラメータは、OpenSSLがプロバイダと設定データや機能情報を交換するための標準化された方法です。