Add Japanese support for wolfSSL-FIPS-Ready

Author: tamasan238

wolfSSL-FIPS-Ready/mkdocs-ja.yml

@@ -0,0 +1,27 @@
+site_name: FIPS Ready User Guide
+site_url: https://wolfssl.com/
+docs_dir: build/html/
+site_dir: html/
+copyright: Copyright © 2023 wolfSSL Inc.
+nav:
+    - "1. 非FIPS版との違い": index.md
+    - "2. wolfSSL FIPS Ready版のビルド手順": section02.md
+    - "3. FIPS 140-2 Ready版からの変更点": section03.md
+    - "4. wolfCrypt FIPS Ready API": section04.md
+theme:
+  name: null
+  custom_dir: ../mkdocs-material/material
+  language: en
+  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]
+use_directory_urls: false

wolfSSL-FIPS-Ready/src-ja/section01.md

@@ -0,0 +1,17 @@
+# wolfSSL FIPS Ready
+
+FIPS認証の取得が求められるプロジェクトには、wolfSSL FIPS Ready版が役立ちます。wolfSSLソースツリーに含まれるFIPS対応の暗号レイヤーを用いて、FIPS認証を取得する手間を低減できます。FIPS Ready版はFIPS版と同一の構成ですが、認証は取得していません。必要なタイミングでFIPS認証プロセスを実行する準備が整っています。FIPS Ready版にはFIPSコードが組み込まれており、FIPS 140-3に示されるデフォルト・エントリーポイントの実用例やConditional Algorithm Self-tests(CAST)を含んでいます。必要なタイミングで実行環境をテストし、wolfSSLの既存のFIPS 140-3認証に追加、または新たなFIPS140-3認証を申請することですべての手続きが完了します。
+
+FIPS Ready版はオープンソースと商用ライセンスのデュアルライセンスで提供しており、GPLv3ライセンス下で動作検証を行っていただけます。その後商用環境でご利用いただくには、商用ライセンス契約が必要です。
+
+FIPSは複雑なトピックです。このドキュメントをご覧いただいた後、ご質問がありましたら[email protected]までお問い合わせください。
+
+## 非FIPS版との違い
+
+wolfCrypt FIPS APIは、FIPS環境内に存在するすべてのアルゴリズム関数のラッパーを提供します。FIPS APIをご利用にならず、非FIPS版にも存在するAPIを用いてコードを記述いただくことも可能です。いずれの場合でも、コンパイル時に自動的にwolfCrypt FIPS APIに置換します。FIPS APIは、実際の関数を呼び出す前に内部ステータスのセルフテストを行います。そして各アルゴリズムの初回実行時にCASTが実行します。このようなタイミングでの実行を避けたい場合は、起動時に予め各テストを実行することも可能です。
+
+wolfCrypt FIPS 140-3 Ready版のコードには、メモリ内の実行可能ファイルの整合性を自動的にチェックする必須の電源投入時自己テスト (POST) が含まれています。これにはアルゴリズムのKnown Answere Tests (KAT) が含まれており、140-2 以降変更しておりません。 POST で使用しないものは、使用が条件付きになりました。実行可能ファイルは、FIPS環境内のコードがメモリ内で隣接するように設計しています。FIPSコードを使用するアプリケーションが起動するか、共有ライブラリがロードされると、ライブラリのデフォルトエントリーポイントを呼び出し、POSTを自動的に実行します。これには、コア内のメモリチェックとPOSTで使用するアルゴリズム(HMAC-SHA256)のためのKATの2つが含まれます。
+
+まずHMAC-SHA256のPOSTを実行し、次いでコア内メモリテストを実行します。メモリ内のコードはHMAC-SHA256でハッシュを取り、一致した場合のみテストを続行します。一致しなければFIPSモジュールはエラー状態となり、整合性が取れるまですべての呼び出しは成功しません。
+
+FIPS環境内の他のアルゴリズムは、初回使用時または開発者が指定したタイミングで既定のデータを用いてテストします。出力は事前に計算された回答と比較します。テスト値はすべてFIPS環境内に存在し、呼び出された際にチェックします。署名と検証などのいくつかのテストではランダム性を含むため、既知のデータを署名し既知のデータで検証します。鍵の生成も同様にテストします。

wolfSSL-FIPS-Ready/src-ja/section02.md

@@ -0,0 +1,118 @@
+# wolfSSL FIPS Ready版のビルド手順
+
+通常版と大きな差はありませんが、いくつかの追加手順が必要です。
+
+ここでは、LinuxまたはmacOS環境でwolfSSL FIPS Ready GPL v3版を利用し、システムに共有ライブラリとしてインストールする手順を示します。
+
+## ソースコードの解凍
+
+```
+$ tar xzvf wolfssl-5.6.4-gplv3-fips-ready.tar.gz
+$ cd wolfssl-5.6.0-gplv3-fips-ready 
+```
+
+ソースコードを解凍し、生成されたディレクトリに移動します。商用リリースを受け取った場合は、gplv3をcommercialに、.tar.gz を .7z に、tar xzvf を 7z x -p<password> に置き換えてください。
+
+## ビルドを構成 
+
+```
+$ ./configure --enable-fips=ready
+```
+
+このコマンドは、FIPS Ready版のwolfSSLを構築するようにMakefileを構成します。
+
+## ライブラリのビルド
+
+```
+$ make
+```
+
+これにより、すべてのソースがコンパイルされライブラリがリンクされます。 また、サンプルツールとテストツールも構築します。
+
+## コアメモリのハッシュを更新
+
+```
+$ ./fips-hash.sh
+
+$ make # Re-build once the hash has been updated
+```
+
+このステップでコア内メモリ テストのハッシュを計算し、更新する必要があります。 wolfCrypt テストは、fips-hash.sh スクリプトによって呼び出されたときに失敗するはずです。次のメッセージが出力されます。(ハッシュ値は一意であることにご注意ください)
+
+```
+in my Fips callback, ok = 0, err = -203
+
+message = In Core Integrity check FIPS error
+
+hash = 8D29242F610EAEA179605BB1A99974EBC72B0ECDB26B483B226A729F36FC82A2
+
+In core integrity hash check failure, copy above hash
+
+into verifyCore[] in fips_test.c and rebuild
+```
+
+ビルド時に他のオプションを追加するとハッシュ値が変化する可能性があるため、この手順を繰り返す必要があります。 またアプリケーションに変更を加えると、アプリケーションを再コンパイルしたときにメモリ内の FIPS 境界が移動する可能性があります。 アプリケーションのみが更新された場合のハッシュの変化は、モジュールが影響を受けていることを示すものではなく、メモリ内の所定の位置にシフトされたことを示します。 これは、静的ライブラリとして使用する場合に発生します。 共有ライブラリではこの問題は発生しません。
+
+4.1 提供している fips-hash.sh スクリプトを使用せずに上記を実行する場合は、ファイル wolfcrypt/src/fips_test.c を編集してハッシュを手動で更新するか、次のような設定を使用することができます。
+
+```
+$ ./configure --enable-fips=ready CFLAGS=”-DWOLFCRYPT_FIPS_CORE_HASH_VALUE=8D29242F610EAEA179605BB1A99974EBC72B0ECDB26B483B226A729F36FC82A2”
+```
+
+4.2 再びmakeを実行します。 
+
+## ビルドの検証
+
+```
+$ make check
+```
+
+Makefile 内のチェック ターゲットは、wolfSSLおよびwolfCryptで提供されるすべてのテストツールとスクリプトです。すべてが正常であれば、次の出力が表示されるはずです。
+
+```
+
+PASS: scripts/resume.test
+
+PASS: scripts/external.test
+
+PASS: scripts/google.test
+
+PASS: testsuite/testsuite.test
+
+PASS: scripts/openssl.test
+
+PASS: tests/unit.test
+
+=======================================================================
+
+Testsuite summary for wolfssl 4.0.0
+
+=======================================================================
+
+# TOTAL: 6
+
+# PASS:  6
+
+# SKIP:  0
+
+# XFAIL: 0
+
+# FAIL:  0
+
+# XPASS: 0
+
+# ERROR: 0
+
+=======================================================================
+
+```
+
+## ライブラリのインストール
+
+```
+$ make install
+```
+
+Makefile 内のinstallターゲットにより、すべてのヘッダーとライブラリがシステムにインストールされます。デフォルトでは /usr/local 配下にインストールします。
+
+これで、アプリケーションのビルド時にwolfSSL FIPS Ready版をご利用いただけます。

wolfSSL-FIPS-Ready/src-ja/section03.md

@@ -0,0 +1,33 @@
+# FIPS 140-2 Ready版からの変更点
+
+1. FIPSモードで実行する場合は、アプリケーションレベルで wc_SetSeed_Cb を呼び出す必要があります。
+
+  a.  +#ifdef WC_RNG_SEED_CB
+
+  b.  + wc_SetSeed_Cb(wc_GenerateSeed);
+
+  c.  +#endif
+
+2. 鍵アクセス管理
+
+  a.  wolfSSL(SSL/TLS)APIを呼び出す場合には、この項による影響はありません。しかしCrypt API(wc_XXX)を呼び出す場合には、次のステップをご参照ください。
+
+  b.  秘密鍵のロードまたは使用を伴う wolfCrypt (wc_XXX) API を直接呼び出す場合は、アプリケーション レベルで鍵へのアクセスを管理する必要があります。具体的には、秘密鍵のロードや使用前に、アプリケーションでPRIVATE_KEY_UNLOCK()を呼び出してロックを解除しなければなりません。使用後にはPRIVATE_KEY_LOCK()を呼び出して再度ロックする必要があります。
+
+     i.  PRIVATE_KEY_UNLOCK()とPRIVATE_KEY_LOCK()は、アプリケーションの起動時及びシャットダウン時にそれぞれ1回だけ呼び出すことも可能です。
+
+     ii.  秘密鍵のロードや使用の前後で都度これらを呼び出すことで、より厳密なアクセス管理を実現できます。
+
+     ** アプリケーション終了前に、必ずロックする必要があります。 - これはドキュメント要件であり、実行時にエラーや終了防止によって強制されるものではありません。 終了する前にキーを再ロックしないと、アプリケーションは「FIPS に準拠していない」ことになります。
+
+
+  c.  アプリケーションをwolfSSL FIPS版と非FIPS版の両方にリンクできるようにするには、次のように実装します。
+
+
+```
+#if !defined(PRIVATE_KEY_LOCK) && !defined(PRIVATE_KEY_UNLOCK)
+    #define PRIVATE_KEY_LOCK() do {} while (0)
+    #define PRIVATE_KEY_UNLOCK() do {} while (0)
+#endif
+```
+