|
| 1 | +# wolfSentry -- wolfSSL組み込みファイアウォール/IDPS |
| 2 | + |
| 3 | +## 説明 |
| 4 | + |
| 5 | +wolfSentryは、wolfSSL組み込みIDPS（侵入検知・防止システム）です。 |
| 6 | +つまり、wolfSentryは組み込みファイアウォールエンジン（静的および完全動的の両方）であり、インターフェース、アドレスファミリー、プロトコル、ポート、その他のトラフィックパラメータによって修飾された既知のホスト/ネットブロックのプレフィックスベースおよびワイルドカード対応検索機能を提供します。 |
| 7 | +さらに、wolfSentryは動的に設定可能なロジックハブとして使用でき、ユーザー定義のイベントをユーザー定義のアクションと任意に関連付け、接続属性によってコンテキスト化します。 |
| 8 | +これにより、クライアント/サーバーの関係を詳細に追跡し、期待されるパターンに一致するトラフィックを自由に通過させる一方で、悪意の込められたトラフィックを効率的に拒否できます。 |
| 9 | + |
| 10 | +wolfSentryは、ソースツリーの`lwip/`サブディレクトリ内のパッチセットを通じてlwIPスタックと完全に統合されています。 |
| 11 | +また、インバウンドおよびアウトバウンド接続のアプリケーションレベルフィルタリングのため、wolfSSLライブラリとも統合されています。 |
| 12 | + |
| 13 | +wolfSentryエンジンは、API経由でプログラム的に、またはエンジンに提供されるJSONのテキスト入力ファイルから、あるいはJSONフラグメントで動的かつ段階的に、またはこれらの方法の任意の組み合わせで動的に設定できます。 |
| 14 | +再設定はトランザクションセマンティクスによって保護され、スレッド化されたターゲット上の高度な内部ロックにより、アトミックなポリシー移行でシームレスなサービス可用性を保証します。 |
| 15 | +またコールバックを用いることで、MQTT、syslog、DDSメッセージバスなどを通じた、トランスポートプロトコルに依存しないリモートログ記録が可能です。 |
| 16 | + |
| 17 | +wolfSentryはリソース制約のある、ベアメタル/RTOS環境で適切に機能するよう設計されました。 |
| 18 | +指定された最大メモリフットプリント内に留まり、決定論的スループットを維持するアルゴリズムを持っています。 |
| 19 | +これにより、FreeRTOS、Nucleus、NUTTX、Zephyr、VxWorks、Green Hills Integrityなどの組み込みターゲット、およびARMやその他の一般的な組み込みCPUおよびMCU上で完全なファイアウォールとIDPS機能を実現できます。 |
| 20 | +動的ファイアウォール機能を持つwolfSentryを実行するのに必要なリソースは非常に小さく、コードフットプリントに64k、揮発性状態フットプリントに32kです。 |
| 21 | +アプリケーションと関連ライブラリが有する、既存のロジックと状態を完全に活用できます。 |
| 22 | + |
| 23 | + |
| 24 | +## ドキュメント |
| 25 | + |
| 26 | +完全なAPIリファレンスマニュアルのHTML版は、wolfSentryソースツリーのトップから`make doc-html`で生成できます。 |
| 27 | +事前に`doxygen`のインストールが必要です。 |
| 28 | + |
| 29 | +なおAPIリファレンスマニュアルのPDF版は事前生成されており、ソース配布物の`doc/`サブディレクトリに`doc/wolfSentry_refman.pdf`として含まれています。 |
| 30 | +最新版は常に[GitHub](https://raw.githubusercontent.com/wolfSSL/wolfsentry/master/doc/wolfSentry_refman.pdf)で入手可能です。 |
| 31 | +まもなく、日本語版もご提供できる予定です。 |
| 32 | + |
| 33 | + |
| 34 | +## 依存関係 |
| 35 | + |
| 36 | +デフォルトビルドでは、wolfSentryはPOSIXランタイム、特にヒープアロケータ、clock_gettime、stdio、セマフォ、pthreads、文字列APIに依存しています。 |
| 37 | +しかし、これらの依存関係は様々なビルド時オプションで回避できます。 |
| 38 | +例えば次のコマンドでは、基本的な文字列関数のいくつかと`inet_ntop()`ライブラリ関数（POSIX.1-2001から、lwIPでも実装されています）のみに依存する`libwolfsentry.a`をビルドします。 |
| 39 | + |
| 40 | +`make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN"` |
| 41 | + |
| 42 | +その後、アロケータと時間のコールバックを`wolfsentry_init()`に提供される`struct wolfsentry_host_platform_interface`に設定する必要があります。 |
| 43 | + |
| 44 | +wolfSentry `Makefile`は、現代的な（v4.0+）Gnu `make`に依存しています。 |
| 45 | +ライブラリ自体はユーザー設定マクロファイルを作成し、`WOLFSENTRY_USER_SETTINGS_FILE`マクロでコンパイラにそのパスを渡すことで、`make`外の別のプロジェクト/フレームワーク内でビルドできます。 |
| 46 | + |
| 47 | + |
| 48 | +## ビルド |
| 49 | + |
| 50 | +wolfSentryは移植性を意識して設計しており、非POSIX・C89ターゲットでも動作します。 |
| 51 | +例えば、すべての依存関係はFreeRTOS/newlib-nano/lwIPランタイムで充足します。 |
| 52 | +wolfSentryのビルド時に問題がある場合は[サポートフォーラム](<https://www.wolfssl.com/forums>)を通じてサポートを求めるか、[support@wolfssl.com](mailto:support@wolfssl.com)へ直接ご連絡ください。 |
| 53 | + |
| 54 | +現在のwolfSentryリリースは[wolfSSLウェブサイト](https://www.wolfssl.jp/download)からZIPファイルとしてダウンロードできます。 |
| 55 | +[リリース履歴を閲覧](https://github.com/wolfSSL/wolfsentry/tags)したり、最新のプレリリース更新のために[wolfSentry Gitリポジトリ](https://github.com/wolfSSL/wolfsentry)をクローンしたりすることもできます。 |
| 56 | + |
| 57 | +`make`では、環境に応じたフラグを渡すことでビルドパラメータを制御できます。 |
| 58 | +ビルド時に使用したフラグは、ビルドツリーの`wolfsentry/wolfsentry_options.h`に保存します。 |
| 59 | + |
| 60 | +なお`make`を使用しない場合は、設定を含むファイルへのパスにCマクロ`WOLFSENTRY_USER_SETTINGS_FILE`を定義する必要があります。 |
| 61 | +wolfSentryをビルドするときとアプリケーションをビルドするときの両方で必要ですので、お気をつけください。 |
| 62 | + |
| 63 | +wolfSentryがサポートしているオプション一覧を以下に示します。 |
| 64 | +bool値のフラグ（`LWIP`、`NO_STDIO`、`NO_JSON`など）はデフォルトで未定義であり、定義することで有効化されます。 |
| 65 | +マクロは`EXTRA_CFLAGS`オプションを使用するか、`USER_SETTINGS_FILE`に配置することで有効化できます。 |
| 66 | +マクロのより詳細なドキュメントは、リファレンスマニュアルの「起動/設定/シャットダウンサブシステム」節をご覧ください。 |
| 67 | + |
| 68 | +| `make`オプション | マクロオプション | 説明 | |
| 69 | +| ------------ | ----------------- | -------- | |
| 70 | +| `SHELL` | | `bash`への明示的/代替パスを提供 | |
| 71 | +| `AWK` | | Gnu `awk`への明示的/代替パスを提供 | |
| 72 | +| `V` | | 詳細な`make`出力 <br> 例：`make V=1 -j test` | |
| 73 | +| `USER_MAKE_CONF` | | メインMakefileの先頭に含めるユーザー定義make節 <br> 例：`make -j USER_MAKE_CONF=Makefile.settings` | |
| 74 | +| `EXTRA_CFLAGS` | | コンパイラに逐語的に渡される追加引数 | |
| 75 | +| `EXTRA_LDFLAGS` | | リンカに逐語的に渡される追加引数 | |
| 76 | +| `SRC_TOP` | | ソースコードのトップレベルディレクトリ（デフォルト`pwd -P`） | |
| 77 | +| `BUILD_TOP` | | 代替場所（ソースツリーの外部またはサブディレクトリ）でアーティファクトを使用してビルド <br> 例：`make BUILD_TOP=./build -j test`| |
| 78 | +| `DEBUG` | | 使用するコンパイラデバッグフラグ（デフォルト`-ggdb`） | |
| 79 | +| `OPTIM` | | 使用するオプティマイザフラグ（デフォルト`-O3`） | |
| 80 | +| `HOST` | | クロスコンパイル用のターゲットホストタプル（デフォルト未設定、つまりネイティブターゲティング） | |
| 81 | +| `RUNTIME` | | ターゲットランタイムエコシステム -- デフォルト未設定、`FreeRTOS-lwIP`と`Linux-lwIP`が認識されます | |
| 82 | +| `C_WARNFLAGS` | | 使用する警告フラグ（一般的に適用可能なデフォルトをオーバーライド） | |
| 83 | +| `STATIC` | | 静的リンクされた単体テストをビルド | |
| 84 | +| `STRIPPED` | | バイナリからデバッグシンボルを取り除く | |
| 85 | +| `FUNCTION_SECTIONS` | | 未使用のオブジェクトコード（関数粒度）を削除して総サイズを最小化 | |
| 86 | +| `BUILD_DYNAMIC` | | 動的リンクされたライブラリをビルド | |
| 87 | +| `VERY_QUIET` | | ビルド中のすべての非エラー出力を抑制 | |
| 88 | +| `TAR` | | `make dist`用のGNU tarバイナリへのパス、macOSでは`gtar`に設定すべき | |
| 89 | +| `VERSION` | | `make dist`用にパッケージするバージョン | |
| 90 | +| `LWIP` | `WOLFSENTRY_LWIP` | 真偽値 -- lwIP用の適切なビルド設定を有効化 | |
| 91 | +| `NO_STDIO_STREAMS` | `WOLFSENTRY_NO_STDIO_STREAMS` | `stdio`ストリームI/Oに依存する機能を省略するよう定義 | |
| 92 | +| | `WOLFSENTRY_NO_STDIO_H` | `stdio.h`のインクルードを抑制するよう定義 | |
| 93 | +| `NO_ADDR_BITMASK_MATCHING` | `WOLFSENTRY_NO_ADDR_BITMASK_MATCHING` | アドレスのビットマスクマッチングサポートを省略し、プレフィックスマッチングのみをサポートするよう定義 | |
| 94 | +| `NO_IPV6` | `WOLFSENTRY_NO_IPV6` | IPv6アドレスファミリーのサポートを省略するよう定義 | |
| 95 | +| `NO_JSON` | `WOLFSENTRY_NO_JSON` | JSON設定サポートを省略するよう定義 | |
| 96 | +| `NO_JSON_DOM` | `WOLFSENTRY_NO_JSON_DOM` | JSON DOM APIを省略するよう定義 | |
| 97 | +| `CALL_TRACE` | `WOLFSENTRY_DEBUG_CALL_TRACE` | ランタイムコールスタックログ記録を有効化するよう定義（非常に詳細） | |
| 98 | +| `USER_SETTINGS_FILE` | `WOLFSENTRY_USER_SETTINGS_FILE` | 自動生成された`wolfsentry_settings.h`を置き換える代替設定ファイル | |
| 99 | +| `SINGLETHREADED` | `WOLFSENTRY_SINGLETHREADED` | スレッドセーフティロジックを省略し、スレッドセーフティ関数とマクロをno-opマクロに置き換えるよう定義 | |
| 100 | +| | `WOLFSENTRY_NO_PROTOCOL_NAMES` | 定義されている場合、エラーコードとソースコードファイルを人間が読める形式でレンダリングするAPIを省略。数値的にレンダリングされます。 | |
| 101 | +| | `WOLFSENTRY_NO_GETPROTOBY` | プロトコルとサービスの名前による検索とレンダリングを無効にするよう定義 | |
| 102 | +| | `WOLFSENTRY_NO_ERROR_STRINGS` | 定義されている場合、エラーコードとソースコードファイルを人間が読める形式でレンダリングするAPIを省略。数値的にレンダリングされます。 | |
| 103 | +| | `WOLFSENTRY_NO_MALLOC_BUILTINS` | 定義されている場合、組み込みヒープアロケータプリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_allocator`内のすべての関数の実装が含まれている必要があります。 | |
| 104 | +| | `WOLFSENTRY_HAVE_NONGNU_ATOMICS` | gnu様式のアトミック組み込み関数が利用できない場合に定義。組み込み関数用の`WOLFSENTRY_ATOMIC_*()`マクロ定義を`WOLFSENTRY_USER_SETTINGS_FILE`で提供する必要があります（`wolfsentry_util.h`を参照）。 | |
| 105 | +| | `WOLFSENTRY_NO_CLOCK_BUILTIN` | 定義されている場合、組み込み時間プリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_timecbs`内のすべての関数の実装が含まれている必要があります。 | |
| 106 | +| | `WOLFSENTRY_NO_SEM_BUILTIN` | 定義されている場合、組み込みセマフォプリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_semcbs`内のすべての関数の実装が含まれている必要があります。 | |
| 107 | +| | `WOLFSENTRY_USE_NONPOSIX_SEMAPHORES` | POSIXセマフォAPIが利用できない場合に定義。`wolfsentry_util.c`に非POSIX組み込み実装が存在しない場合は、#WOLFSENTRY_NO_SEM_BUILTINを設定する必要があり、wolfSentry APIに提供される`wolfsentry_host_platform_interface`の`wolfsentry_semcbs`スロットに完全なセマフォ実装（shimセット）を含める必要があります。 | |
| 108 | +| | `WOLFSENTRY_SEMAPHORE_INCLUDE` | セマフォAPIを宣言するヘッダーファイルのパスに定義 | |
| 109 | +| | `WOLFSENTRY_USE_NONPOSIX_THREADS` | POSIXスレッドAPIが利用できない場合に定義。`WOLFSENTRY_THREAD_INCLUDE`、`WOLFSENTRY_THREAD_ID_T`、`WOLFSENTRY_THREAD_GET_ID_HANDLER`を定義する必要があります。 | |
| 110 | +| | `WOLFSENTRY_THREAD_INCLUDE` | スレッディングAPIを宣言するヘッダーファイルのパスに定義 | |
| 111 | +| | `WOLFSENTRY_THREAD_ID_T` | POSIX `pthread_t`に類似した適切な型に定義 | |
| 112 | +| | `WOLFSENTRY_THREAD_GET_ID_HANDLER` | POSIX `pthread_self`に類似した、`WOLFSENTRY_THREAD_ID_T`型の値を返すvoid関数の名前に定義 | |
| 113 | +| | `FREERTOS` | FreeRTOS用にビルド | |
| 114 | + |
| 115 | +### ビルドとセルフテストのコマンド例 |
| 116 | + |
| 117 | +Linux上で`libwolfsentry.a`をビルドしてテスト |
| 118 | + |
| 119 | +`make -j test` |
| 120 | + |
| 121 | +詳細ビルド |
| 122 | + |
| 123 | +`make V=1 -j test` |
| 124 | + |
| 125 | +代替場所（ソースツリーの外部またはサブディレクトリ）でアーティファクトを使用してビルド |
| 126 | + |
| 127 | +`make BUILD_TOP=./build -j test` |
| 128 | + |
| 129 | +代替ビルド場所から非標準の宛先にインストール |
| 130 | + |
| 131 | +`make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install` |
| 132 | + |
| 133 | +`libwolfsentry.a`をビルドして様々な設定でテスト |
| 134 | + |
| 135 | +`make -j check` |
| 136 | + |
| 137 | +マルチスレッドサポートなしで`libwolfsentry.a`をビルドしてテスト |
| 138 | + |
| 139 | +`make -j SINGLETHREADED=1 test` |
| 140 | + |
| 141 | +他の利用可能なmakeフラグは`STATIC=1`、`STRIPPED=1`、`NO_JSON=1`、`NO_JSON_DOM=1`であり、`DEBUG`、`OPTIM`、`C_WARNFLAGS`のデフォルト値もオーバーライドできます。 |
| 142 | + |
| 143 | + |
| 144 | +デフォルトをオーバーライドするためにユーザー提供のmakefileプリアンブルでビルド |
| 145 | + |
| 146 | +`make -j USER_MAKE_CONF=Makefile.settings` |
| 147 | + |
| 148 | +`Makefile.settings`は`OPTIM := -Os`のような単純な設定や、追加のルールと依存関係メカニズムを含む詳細なmakefileコードを含むことができます。 |
| 149 | + |
| 150 | + |
| 151 | +最小構成でビルド |
| 152 | + |
| 153 | +`make -j SINGLETHREADED=1 NO_STDIO=1 DEBUG= OPTIM=-Os EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN -DWOLFSENTRY_NO_ERROR_STRINGS -Wno-error=inline -Wno-inline"` |
| 154 | + |
| 155 | +ユーザー設定でビルドしてテスト |
| 156 | + |
| 157 | +`make -j USER_SETTINGS_FILE=user_settings.h test` |
| 158 | + |
| 159 | +FreeRTOSとlwIPソースツリーが図示のように配置されていると仮定して、ARM32上のFreeRTOS用にビルド |
| 160 | + |
| 161 | +`make -j HOST=arm-none-eabi RUNTIME=FreeRTOS-lwIP FREERTOS_TOP=../third/FreeRTOSv202212.00 LWIP_TOP=../third/lwip EXTRA_CFLAGS=-mcpu=cortex-m7` |
| 162 | + |
| 163 | + |
| 164 | +## プロジェクト例 |
| 165 | + |
| 166 | +`wolfsentry/examples/`サブディレクトリに、一連のサンプルポートとアプリケーションを配置しています。 |
| 167 | +具体的には、Linux D-Bus機能と統合した、TLS対応組み込みWebサーバーを実装するデモポップアップ通知システムなどがあります。 |
| 168 | + |
| 169 | +APIの使用法に関するより包括的な例は`tests/unittests.c`、特に`test_static_routes()`、`test_dynamic_rules()`、`test_json()`、`tests/test-config*.json`のJSON設定ファイルにあります。 |
| 170 | + |
| 171 | +[wolfSSLリポジトリ](https://github.com/wolfSSL/wolfssl)では、`WOLFSSL_WOLFSENTRY_HOOKS`で保護された`wolfssl/test.h`内のコードをご参照ください。 |
| 172 | +これには`wolfsentry_store_endpoints()`、`wolfSentry_NetworkFilterCallback()`、`wolfsentry_setup()`、`tcp_connect_with_wolfSentry()`が含まれます。 |
| 173 | +また、`WOLFSSL_WOLFSENTRY_HOOKS`で保護された`examples/server/server.c`と`examples/client/client.c`内のコードもお役に立つかもしれません。 |
| 174 | + |
| 175 | +wolfSSL統合でビルドするには`--enable-wolfsentry`でwolfSSLを設定し、wolfSentryが非標準の場所にインストールされている場合は`--with-wolfsentry=/インストールパス`を使用してください。 |
| 176 | +wolfSSLテストクライアント/サーバーは、`--wolfsentry-config <file>`を使用して、コマンドラインからユーザー提供のwolfSentry JSON設定をロードできます。 |
0 commit comments