Skip to content

Commit c36df93

Browse files
cconloncconlon
authored
Merge pull request #90 from TakayukiMatsuo/engine
2 parents 01e706e + 861a367 commit c36df93

15 files changed

+711
-1
lines changed

‎wolfEngine/Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,11 @@ SOURCES = chapter01.md \
1515
chapter10.md \
1616
chapter11.md
1717

18-
PDF = wolfEngine-Manual.pdf
18+
ifeq ($(DOC_LANG),JA)
19+
PDF = wolfEngine-Manual-jp.pdf
20+
else
21+
PDF = wolfEngine-Manual.pdf
22+
endif
1923

2024
.PHONY: html-prep
2125
html-prep:

‎wolfEngine/mkdocs-ja.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
site_name: wolfEngine マニュアル
2+
site_url: https://wolfssl.com/
3+
docs_dir: build/html/
4+
site_dir: html/
5+
copyright: Copyright © 2022 wolfSSL Inc.
6+
nav:
7+
- "1. イントロダクション": index.md
8+
- "2. OpenSSL版との互換性": chapter02.md
9+
- "3. wolfEngineのビルド": chapter03.md
10+
- "4. FIPS 140-2 のサポート": chapter04.md
11+
- "5. Engine コントロールコマンド": chapter05.md
12+
- "6. ロギング": chapter06.md
13+
- "7. 移植性": chapter07.md
14+
- "8. wolfEngineのロード": chapter08.md
15+
- "9. wolfEngineの設計": chapter09.md
16+
- "10. オープンソース統合に関する注意事項": chapter10.md
17+
- "11. サポートとOpenSSLバージョン追加": chapter11.md
18+
theme:
19+
name: null
20+
custom_dir: ../mkdocs-material/material
21+
language: en
22+
palette:
23+
primary: indigo
24+
accent: indigo
25+
font:
26+
text: roboto
27+
code: roboto mono
28+
icon: "logo.png"
29+
logo: logo.png
30+
favicon: logo.png
31+
feature:
32+
tabs: true
33+
extra_css: [skin.css]
34+
use_directory_urls: false

‎wolfEngine/src-ja/chapter01.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# イントロダクション
2+
3+
wolfCrypt エンジン (wolfEngine) は、wolfCrypt および wolfCrypt FIPS 暗号化ライブラリを OpenSSLエンジンフレームワークに適合させるためのライブラリです。 wolfEngine は、共有または静的ライブラリとして OpenSSL エンジンの実装を提供し、現在 OpenSSL を使用しているアプリケーションが FIPS および非 FIPS ユースケースで wolfCrypt 暗号化ライブラリを活用できるようにします。
4+
5+
wolfEngine は、wolfSSL (libwolfssl) と OpenSSL にリンクする個別のスタンドアロン ライブラリとして構成されています。 wolfEngine は、wolfCrypt ネイティブ API を内部的にラップする **OpenSSL エンジンの実装** を実装および公開します。 wolfEngine の概要図と、それがアプリケーションおよび OpenSSL とどのように関連しているかを下の図 1 に示します。
6+
7+
8+
wolfEngine の設計とアーキテクチャの詳細については、[wolfEngine の設計](chapter09.md) の章を参照してください。
9+
10+
11+
12+
13+
![wolfEngine Overview](png/wolfengine_overview.png)
14+
15+
wolfEngine は、デフォルトで **libwolfengine** と呼ばれる共有ライブラリとしてコンパイルされます。これは、アプリケーションまたはコンフィギュレーションファイルを介して OpenSSL によって実行時に動的に登録できます。 wolfEngine は、アプリケーションが静的ビルドでコンパイルされたときにエンジンをロードするためのエントリ ポイントも提供します。
16+

‎wolfEngine/src-ja/chapter02.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# OpenSSL版との互換性
2+
3+
wolfEngine は、以下のバージョンの OpenSSL に対してテストされています。 wolfEngine は他のバージョンでも動作する可能性がありますが、変更や調整が必要になる場合があります：
4+
5+
- OpenSSL 1.0.2h
6+
- OpenSSL 1.1.1b
7+
8+
wolfEngine に他の OpenSSL バージョンのサポート追加を希望される場合は、[[email protected]](mailto:[email protected]) にご連絡ください。
9+

‎wolfEngine/src-ja/chapter03.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# wolfEngine のビルド
2+
3+
## wolfEngine のソースコードの取得
4+
5+
wolfEngine の最新バージョンは、wolfSSL Inc. から直接入手できます。詳細については、[[email protected]](mailto:[email protected]) までお問い合わせください。
6+
7+
8+
## wolfEngine パッケージ構成
9+
10+
一般的な wolfEngine パッケージは次のように構成されています:
11+
12+
```
13+
certs/ (ユニットテストで使用されるテスト用証明書、鍵)
14+
engine.conf 　(wolfEngineを使用する場合のOpenSSLコンフィギュレーションファイルサンプル）
15+
include/
16+
wolfengine/ (wolfEngineヘッダーファイル)
17+
openssl_patches/
18+
1.0.2h/tests/ (OpenSSL 1.0.2h テストアプリ用パッチ)
19+
1.1.1b/tests/ (OpenSSL 1.1.1b テストアプリ用パッチ)
20+
scripts/ (wolfEngine テストスクリプト)
21+
src/ (wolfEngine ソースファイル)
22+
test/ (wolfEngine テストファイル)
23+
user_settings.h (user_settings.hサンプル)
24+
```
25+
## OpenSSL のバージョンに関する注意事項
26+
27+
wolfEngine で使用されている OpenSSL のバージョンに応じて、次のようないくつかのアルゴリズム サポートの注意事項があります:
28+
29+
- SHA-3 はOpenSSL versions 1.1.1以降でサポートされます
30+
- EC_KEY_METHOD はOpenSSL versions 1.1.1以降でサポートされます
31+
32+
## *nix 上でのビルド
33+
34+
35+
### OpenSSLをビルド
36+
37+
OpenSSL のプリインストールされたバージョンを wolfEngine で使用することも (上記のアルゴリズムの警告を除いて)、または OpenSSL を再コンパイルして wolfEngine で使用することもできます。 *nix のようなプラットフォームで OpenSSL をコンパイルするための一般的な手順は、次のようになります。 完全で包括的な OpenSSL のビルド手順については、OpenSSL INSTALL ファイルとドキュメントを参照してください。
38+
39+
40+
```
41+
git clone https://github.com/openssl/openssl.git
42+
cd openssl
43+
./config no-fips -shared
44+
make
45+
sudo make install
46+
```
47+
48+
### wolfSSLをビルド
49+
50+
wolfEngine で wolfSSL の FIPS 検証済みバージョンを使用する場合は、特定の FIPS 検証済みソース バンドルとセキュリティ ポリシーで提供されるビルド手順に従ってください。 正しい「--enable-fips」設定オプションに加えて、wolfEngine は"**WOLFSSL_PUBLIC_MP**"が定義された状態で wolfSSL をコンパイルする必要があります。 たとえば、Linux で「wolfCrypt Linux FIPSv2」バンドルをビルドする場合:
51+
52+
```
53+
cd wolfssl-X.X.X-commercial-fips-linuxv
54+
./configure **--enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP”**
55+
make
56+
./wolfcrypt/test/testwolfcrypt
57+
#--< fips_test.c 内の verifyCore を hash output from testwolfcryptスクリプトが出力するハッシュ値に更新してください >--
58+
59+
make
60+
./wolfcrypt/test/testwolfcrypt
61+
62+
#--< 全アルゴリズムでパスするはずです>--
63+
64+
sudo make install
65+
```
66+
67+
wolfEngine で使用する非 FIPS wolfSSL をビルドするには:
68+
```
69+
cd wolfssl-X.X.X
70+
71+
./configure --enable-cmac --enable-keygen --enable-sha --enable-des --enable-aesctr --enable-aesccm --enable-x963kdf CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING -DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER"
72+
73+
make
74+
sudo make install
75+
```
76+
77+
GitHub から wolfSSL をクローンする場合、`./configure` を実行する前に `autogen.sh` スクリプトを実行する必要があります。 これにより、configure スクリプトが生成されます:
78+
79+
```
80+
./autogen.sh
81+
```
82+
83+
### wolfEngineをビルド
84+
85+
Linux またはその他の *nix ライクなシステムで wolfEngine をビルドする場合は、autoconf システムを使用してください。 wolfEngine を構成およびコンパイルするには、wolfEngine ルート ディレクトリから次の 2 つのコマンドを実行します：
86+
87+
88+
```
89+
./configure
90+
make
91+
```
92+
93+
GitHub から wolfEngine を取得してビルドする場合は、configure を実行する前に autogen.sh を実行します:
94+
```
95+
./autogen.sh
96+
```
97+
98+
任意の数のビルドオプションを ./configure に追加できます。 利用可能なビルド オプションのリストについては、以下の「ビルド オプション」セクションを参照するか、次のコマンドを実行して、./configure スクリプトに渡す利用可能なビルド オプションのリストを表示してください：
99+
100+
101+
```
102+
./configure --help
103+
```
104+
105+
"--with-openssl"オプションで変更しない限り、wolfEngine はシステムのデフォルトの OpenSSL ライブラリのインストールを使用します:
106+
107+
108+
```
109+
./configure --with-openssl=/usr/local/ssl
110+
```
111+
カスタム OpenSSL のインストール場所も、ライブラリ検索パスに追加する必要となる場合があります。Linux では、`LD_LIBRARY_PATH` が使用されます:
112+
113+
```
114+
export LD_LIBRARY_PATH=/usr/local/ssl:$LD_LIBRARY_PATH
115+
```
116+
117+
wolfEngine をビルドしてインストールするには、以下を実行します:
118+
119+
```
120+
make
121+
make install
122+
```
123+
124+
インストールにはスーパーユーザー権限が必要な場合があります。その場合は、コマンドの前に sudo を付けます:
125+
126+
```
127+
sudo make install
128+
```
129+
130+
ビルドをテストするには、ルート wolfEngine ディレクトリからビルトインテストを実行します:
131+
132+
```
133+
./test/unit.test
134+
```
135+
136+
または autoconf を使用してテストを実行します:
137+
138+
```
139+
make check
140+
```
141+
142+
`error while loading shared libraries: libssl.so.3` のようなエラーが発生した場合は、ライブラリが見つからなかった為です。上記のセクションで説明したように、`LD_LIBRARY_PATH` 環境変数を使用します：
143+
144+
145+
## WinCE上でのビルド
146+
147+
wolfEngine との完全な互換性のために、wolfCrypt の `user_settings.h` ファイルに以下の定義があることを確認してください:
148+
149+
150+
```
151+
#define WOLFSSL_CMAC
152+
#define WOLFSSL_KEY_GEN
153+
#undef NO_SHA
154+
#undef NO_DES
155+
#define WOLFSSL_AES_COUNTER
156+
#define HAVE_AESCCM
157+
#define HAVE_AES_ECB
158+
#define WOLFSSL_AES_DIRECT
159+
#define WC_RSA_NO_PADDING
160+
#define WOLFSSL_PUBLIC_MP
161+
#define ECC_MIN_KEY_SZ=192
162+
```
163+
164+
使用するアルゴリズムと機能に応じて、`user_settings.h` ファイルに wolfEngine フラグを追加します。 wolfEngine のディレクトリにある `user_settings.h` ファイルで、wolfEngine ユーザー設定フラグが参照できます。
165+
166+
Windows CE 用の wcecompat、wolfCrypt、および OpenSSL をビルドし、それらのパスを参照できるようにします。
167+
168+
wolfEngine ディレクトリでソースファイルを開き、OpenSSL、wolfCrypt、および `user_settings.h` パスを使用しているディレクトリに変更します。 INCLUDES セクションと TARGETLIBS セクションのパスを更新する必要があります。
169+
170+
Visual Studio で wolfEngine プロジェクトをロードします。 ベンチマークまたは単体テストを実行するかどうかに応じて、「bench.c」、または「unit.h」と「unit.c」のいずれかを含めます。
171+
172+
プロジェクトをビルドすると、wolfEngine.exe 実行可能ファイルが作成されます。 この実行可能ファイルを --help で実行すると、オプションの完全なリストが表示されます。 wolfEngine を静的エンジンとして使用するには、`--static` フラグを付けて実行する必要があります。
173+
174+
175+
## ビルドオプション (./configure に指定するオプション)
176+
177+
以下は、wolfEngine ライブラリの構築方法をカスタマイズする目的で `./configure` スクリプトに追加できるオプションです。
178+
179+
デフォルトでは、wolfEngine は共有ライブラリのみを構築し、静的ライブラリの構築は無効になっています。 これにより、ビルド時間が 2 倍速くなります。 どちらのモードも、必要に応じて明示的に無効または有効にすることができます。
180+
181+
182+
| オプション | デフォルト | 意味 |
183+
| :--------- | :---------------: | :-------------- |
184+
| --enable-static | **無効** | スタティックライブラリとしてビルド |
185+
| --enable-shared | 有効 | 共有ライブラリとしてビルド |
186+
| --enable-debug | **無効** | wolfEngineのデバッグ出力を有効にする |
187+
| --enable-coverage | **無効** | コードカバレッジレポートを作成する用ビルド |
188+
| --enable-usersettings | **無効** | user_settings.h を使用しMakefileの CFLAGSを使用しない |
189+
| --enable-dynamic-engine | 有効 | wolfEngine をダイナミックエンジンとしてロードする |
190+
| --enable-singlethreaded | **無効** | wolfEngineをシングルスレッド環境で使用する |
191+
| --enable-digest | 有効 | ダイジェストの生成にwc_Hash APIを使用する |
192+
| --enable-sha | 有効 | SHA-1 を有効にする|
193+
| --enable-sha224 | 有効 | SHA2-224 を有効にする|
194+
| --enable-sha256 | 有効 | SHA2-256 を有効にする|
195+
| --enable-sha384 | 有効 | SHA2-384 を有効にする|
196+
| --enable-sha512 | 有効 | SHA2-512 を有効にする|
197+
| --enable-sha3 | 有効 | SHA3 を有効にする|
198+
| --enable-sha3-224 | 有効 | SHA3-224 を有効にする|
199+
| --enable-sha3-256 | 有効 | SHA3-256 を有効にする|
200+
| --enable-sha3-384 | 有効 | SHA3-384 を有効にする|
201+
| --enable-sha3-512 | 有効 | SHA3-512 を有効にする|
202+
| --enable-cmac | 有効 | CMAC を有効にする|
203+
| --enable-hmac | 有効 | HMAC を有効にする|
204+
| --enable-des3cbc| 有効 | 3DES-CBC を有効にする|
205+
| --enable-aesecb | 有効 | AES-ECB を有効にする|
206+
| --enable-aescbc | 有効 | AES-CBC を有効にする|
207+
| --enable-aesctr | 有効 | AES-CTR を有効にする|
208+
| --enable-aesgcm | **無効** | AES-GCM を有効にする|
209+
| --enable-aesccm | **無効** | AES-CCM を有効にする|
210+
| --enable-rand | 有効 | RAND を有効にする|
211+
| --enable-rsa | 有効 | RSA を有効にする|
212+
| --enable-dh | 有効 | DH を有効にする|
213+
| --enable-evp-pkey | 有効 | EVP_PKEY APIs を有効にする|
214+
| --enable-ec-key | 有効 | ECC using EC_KEY を有効にする|
215+
| --enable-ecdsa | 有効 | ECDSA を有効にする|
216+
| --enable-ecdh | 有効 | ECDH を有効にする|
217+
| --enable-eckg | 有効 | EC Key Generation を有効にする|
218+
| --enable-p192 | 有効 | EC Curve P-192 を有効にする|
219+
| --enable-p224 | 有効 | EC Curve P-224 を有効にする|
220+
| --enable-p256 | 有効 | EC Curve P-256 を有効にする|
221+
| --enable-p384 | 有効 | EC Curve P-384 を有効にする|
222+
| --enable-p521 | 有効 | EC Curve P-521 を有効にする|
223+
| --with-openssl=DIR | | OpenSSLのインストール場所を指定。指定しない場合はシステムのデフォルトライブラリパスとインクルードパスが使われます。|
224+
225+
## ビルド用マクロ定義
226+
227+
wolfEngine は、ユーザーが wolfEngine の構築方法を設定できるようにするいくつかのプリプロセッサマクロを公開しています。 これらについては、次の表で説明します：
228+
229+
230+
| マクロ定義 | 意味 |
231+
| :---------------------------------------------- | :-------------- |
232+
| WOLFENGINE_DEBUG | デバッグ シンボル、最適化レベル、デバッグ ロギングを使用して wolfEngine をビルドします |
233+
| WE_NO_DYNAMIC_ENGINE | wolfEngineをダイナミックエンジンとしてビルドしない。ダイナミックエンジンとはOpenSSLが実行時に動的にロードするエンジンです。 |
234+
| WE_SINGLE_THREADED | wolfEngineをシングルスレッドモードでビルドする。このマクロ定義によりグローバルリソースの使用の排他用に内部的に使用するロック機構を取り除きます。|
235+
| WE_USE_HASH | ハッシュアルゴリズムを wc_Hash APIを使って有効にする |
236+
| WE_HAVE_SHA1 | SHA-1 を有効にする |
237+
| WE_HAVE_SHA224 | SHA-2 224を有効にする |
238+
| WE_HAVE_SHA256 | SHA-2 256を有効にする |
239+
| WE_HAVE_SHA384 | SHA-2 384を有効にする |
240+
| WE_HAVE_SHA512 | SHA-2 512を有効にする |
241+
| WE_SHA1_DIRECT | SHA-1 をwc_Sha APIを使って有効にする。WE_USE_HASHとはコンパチブルではない |
242+
| WE_SHA224_DIRECT | SHA-2 224 を wc_Sha224 APIを使って有効にする。WE_USE_HASHとはコンパチブルではない |
243+
| WE_SHA256_DIRECT | SHA-2 256 を wc_Sha256 APIを使って有効にする。WE_USE_HASHとはコンパチブルではない |
244+
| WE_HAVE_SHA3_224 | SHA-3 224を有効にする（OpenSSL 1.0.2では利用不可）|
245+
| WE_HAVE_SHA3_256 | SHA-3 256を有効にする（OpenSSL 1.0.2では利用不可）|
246+
| WE_HAVE_SHA3_384 | SHA-3 384を有効にする（OpenSSL 1.0.2では利用不可）|
247+
| WE_HAVE_SHA3_512 | SHA-3 512を有効にする（OpenSSL 1.0.2では利用不可）|
248+
| WE_HAVE_EVP_PKEY | EVP_PKEY APIを使用する機能を有効にする（RSA, DH等も含む） |
249+
| WE_HAVE_CMAC | CMAC を有効にする |
250+
| WE_HAVE_HMAC | HMAC を有効にする |
251+
| WE_HAVE_DES3CBC | DES3-CBC を有効にする |
252+
|WE_HAVE_AESECB | AES-ECB を有効にする |
253+
| WE_HAVE_AESCBC | AES-CBC を有効にする |
254+
| WE_HAVE_AESCTR | AES-countee modeを有効にする |
255+
| WE_HAVE_AESGCM | AES-GCM を有効にする |
256+
| WE_HAVE_AESCCM | AES-CCM を有効にする |
257+
| WE_HAVE_RANDOM | wolfCrypt の疑似乱数生成実装を有効にする |
258+
| WE_HAVE_RSA | RSA 操作 (すなわち 署名, 検証, 鍵生成等)を有効にする |
259+
| WE_HAVE_DH | Diffie-Hellman 操作 (すなわち 鍵生成, 共有シークレット計算等)を有効にする |
260+
| WE_HAVE_ECC | 楕円曲線暗号を有効にする |
261+
| WE_HAVE_EC_KEY | EC_KEY_METHODのサポートを有効にする（OpenSSL 1.0.2では利用不可） |
262+
| WE_HAVE_ECDSA | ECDSA を有効にする |
263+
| WE_HAVE_ECDH | EC Diffie-Hellman operationsを有効にする |
264+
| WE_HAVE_ECKEYGEN | EC key generationを有効にする |
265+
| WE_HAVE_EC_P192 | EC Curve P192を有効にする |
266+
| WE_HAVE_EC_P224 | EC Curve P224を有効にする |
267+
| WE_HAVE_EC_P256 | EC Curve P256を有効にする |
268+
| WE_HAVE_EC_P384 | EC Curve P384を有効にする |
269+
| WE_HAVE_EC_P512 | EC Curve P512を有効にする |
270+
| WE_HAVE_DIGEST | ダイジェストアルゴリズムをベンチマークとユニットテストのコードに含めてコンパイルする |
271+
| WOLFENGINE_USER_SETTINGS | ユーザーの指定した定義をuser_settings.hファイルから読み込む |
272+

‎wolfEngine/src-ja/chapter04.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# FIPS 140-2 のサポート
2+
3+
wolfEngine は、FIPS で検証されたバージョンの wolfCrypt に対してコンパイルされた場合に、FIPS 140-2 で検証されたバージョンの wolfCrypt で動作するように設計されています。 この使用シナリオには、wolfSSL Inc. から入手した、適切にライセンスされ、検証されたバージョンの wolfCrypt が必要です。
4+
5+
wolfCrypt FIPS ライブラリは、非 FIPS モードに「切り替える」ことができないことに注意してください。 wolfCrypt FIPS と通常の wolfCrypt は、2 つの別個のソース コード パッケージです。
6+
7+
wolfEngine が wolfCrypt FIPS を使用するようにコンパイルされると、FIPS で検証されたアルゴリズム、モード、およびキー サイズのサポートおよび登録エンジン コールバックのみが含まれます。 OpenSSL ベースのアプリケーションが非 FIPS 検証済みアルゴリズムを呼び出す場合、実行は wolfEngine に入らず、OpenSSL 構成に基づいて、デフォルトの OpenSSL エンジンまたは他の登録済みエンジン プロバイダーによって処理される可能性があります。
8+
9+
**注** : FIPS 準拠を対象としており、wolfCrypt 以外の FIPS アルゴリズムが別のエンジンから呼び出される場合、それらのアルゴリズムは　wolfEngine および wolfCrypt FIPS であり、FIPS で検証されていない可能性があります。
10+
11+
wolfCrypt FIPS (140-2 / 140-3) の使用に関する詳細については、wolfSSL ([email protected]) までお問い合わせください。
12+
13+

0 commit comments

Comments
 (0)