diff --git a/wolfSentry/Makefile b/wolfSentry/Makefile index 9af06421..379f56ae 100644 --- a/wolfSentry/Makefile +++ b/wolfSentry/Makefile @@ -1,15 +1,11 @@ -include ../common/common.am .DEFAULT_GOAL := all -all: pdf html +all: pre-build pdf html - -ifeq ($(DOC_LANG),JA) -SOURCES = chapter01.md \ - chapter02.md \ - chapter04.md -else -SOURCES = README.md freertos-lwip-app.md json_configuration.md ChangeLog.md -endif +SOURCES = README.md \ + freertos-lwip-app.md \ + json_configuration.md \ + ChangeLog.md PDF = wolfSentry-Manual.pdf @@ -26,3 +22,9 @@ html-prep: .PHONY: pdf-prep pdf-prep: + +.PHONY: pre-build +pre-build: +ifeq ($(DOC_LANG),JA) + cp src/ChangeLog.md src-ja/ +endif diff --git a/wolfSentry/mkdocs-ja.yml b/wolfSentry/mkdocs-ja.yml index a33b679a..04eadc3c 100644 --- a/wolfSentry/mkdocs-ja.yml +++ b/wolfSentry/mkdocs-ja.yml @@ -2,11 +2,12 @@ site_name: wolfSentry Manual site_url: https://wolfssl.com/ docs_dir: build/html/ site_dir: html/ -copyright: Copyright © 2022 wolfSSL Inc. +copyright: Copyright © 2025 wolfSSL Inc. nav: - "1. はじめに": index.md - - "2. wolfSentryのビルド": chapter02.md - - "3. wolfSentry の使用例": chapter04.md + - "2. FreeRTOS/lwIPアプリケーション用のビルドと初期化": freertos-lwip-app.md + - "3. JSONドキュメントを使用した設定": json_configuration.md + - "4. リリース履歴と変更ログ": ChangeLog.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfSentry/src-ja/README.md b/wolfSentry/src-ja/README.md new file mode 100644 index 00000000..d145e8c0 --- /dev/null +++ b/wolfSentry/src-ja/README.md @@ -0,0 +1,176 @@ +# wolfSentry -- wolfSSL組み込みファイアウォール/IDPS + +## 説明 + +wolfSentryは、wolfSSL組み込みIDPS（侵入検知・防止システム）です。 +つまり、wolfSentryは組み込みファイアウォールエンジン（静的および完全動的の両方）であり、インターフェース、アドレスファミリー、プロトコル、ポート、その他のトラフィックパラメータによって修飾された既知のホスト/ネットブロックのプレフィックスベースおよびワイルドカード対応検索機能を提供します。 +さらに、wolfSentryは動的に設定可能なロジックハブとして使用でき、ユーザー定義のイベントをユーザー定義のアクションと任意に関連付け、接続属性によってコンテキスト化します。 +これにより、クライアント/サーバーの関係を詳細に追跡し、期待されるパターンに一致するトラフィックを自由に通過させる一方で、悪意の込められたトラフィックを効率的に拒否できます。 + +wolfSentryは、ソースツリーの`lwip/`サブディレクトリ内のパッチセットを通じてlwIPスタックと完全に統合されています。 +また、インバウンドおよびアウトバウンド接続のアプリケーションレベルフィルタリングのため、wolfSSLライブラリとも統合されています。 + +wolfSentryエンジンは、API経由でプログラム的に、またはエンジンに提供されるJSONのテキスト入力ファイルから、あるいはJSONフラグメントで動的かつ段階的に、またはこれらの方法の任意の組み合わせで動的に設定できます。 +再設定はトランザクションセマンティクスによって保護され、スレッド化されたターゲット上の高度な内部ロックにより、アトミックなポリシー移行でシームレスなサービス可用性を保証します。 +またコールバックを用いることで、MQTT、syslog、DDSメッセージバスなどを通じた、トランスポートプロトコルに依存しないリモートログ記録が可能です。 + +wolfSentryはリソース制約のある、ベアメタル/RTOS環境で適切に機能するよう設計されました。 +指定された最大メモリフットプリント内に留まり、決定論的スループットを維持するアルゴリズムを持っています。 +これにより、FreeRTOS、Nucleus、NUTTX、Zephyr、VxWorks、Green Hills Integrityなどの組み込みターゲット、およびARMやその他の一般的な組み込みCPUおよびMCU上で完全なファイアウォールとIDPS機能を実現できます。 +動的ファイアウォール機能を持つwolfSentryを実行するのに必要なリソースは非常に小さく、コードフットプリントに64k、揮発性状態フットプリントに32kです。 +アプリケーションと関連ライブラリが有する、既存のロジックと状態を完全に活用できます。 + + +## ドキュメント + +完全なAPIリファレンスマニュアルのHTML版は、wolfSentryソースツリーのトップから`make doc-html`で生成できます。 +事前に`doxygen`のインストールが必要です。 + +なおAPIリファレンスマニュアルのPDF版は事前生成されており、ソース配布物の`doc/`サブディレクトリに`doc/wolfSentry_refman.pdf`として含まれています。 +最新版は常に[GitHub](https://raw.githubusercontent.com/wolfSSL/wolfsentry/master/doc/wolfSentry_refman.pdf)で入手可能です。 +まもなく、日本語版もご提供できる予定です。 + + +## 依存関係 + +デフォルトビルドでは、wolfSentryはPOSIXランタイム、特にヒープアロケータ、clock_gettime、stdio、セマフォ、pthreads、文字列APIに依存しています。 +しかし、これらの依存関係は様々なビルド時オプションで回避できます。 +例えば次のコマンドでは、基本的な文字列関数のいくつかと`inet_ntop()`ライブラリ関数（POSIX.1-2001から、lwIPでも実装されています）のみに依存する`libwolfsentry.a`をビルドします。 + +`make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN"` + +その後、アロケータと時間のコールバックを`wolfsentry_init()`に提供される`struct wolfsentry_host_platform_interface`に設定する必要があります。 + +wolfSentry `Makefile`は、現代的な（v4.0+）Gnu `make`に依存しています。 +ライブラリ自体はユーザー設定マクロファイルを作成し、`WOLFSENTRY_USER_SETTINGS_FILE`マクロでコンパイラにそのパスを渡すことで、`make`外の別のプロジェクト/フレームワーク内でビルドできます。 + + +## ビルド + +wolfSentryは移植性を意識して設計しており、非POSIX・C89ターゲットでも動作します。 +例えば、すべての依存関係はFreeRTOS/newlib-nano/lwIPランタイムで充足します。 +wolfSentryのビルド時に問題がある場合は[サポートフォーラム]()を通じてサポートを求めるか、[support@wolfssl.com](mailto:support@wolfssl.com)へ直接ご連絡ください。 + +現在のwolfSentryリリースは[wolfSSLウェブサイト](https://www.wolfssl.jp/download)からZIPファイルとしてダウンロードできます。 +[リリース履歴を閲覧](https://github.com/wolfSSL/wolfsentry/tags)したり、最新のプレリリース更新のために[wolfSentry Gitリポジトリ](https://github.com/wolfSSL/wolfsentry)をクローンしたりすることもできます。 + +`make`では、環境に応じたフラグを渡すことでビルドパラメータを制御できます。 +ビルド時に使用したフラグは、ビルドツリーの`wolfsentry/wolfsentry_options.h`に保存します。 + +なお`make`を使用しない場合は、設定を含むファイルへのパスにCマクロ`WOLFSENTRY_USER_SETTINGS_FILE`を定義する必要があります。 +wolfSentryをビルドするときとアプリケーションをビルドするときの両方で必要ですので、お気をつけください。 + +wolfSentryがサポートしているオプション一覧を以下に示します。 +bool値のフラグ（`LWIP`、`NO_STDIO`、`NO_JSON`など）はデフォルトで未定義であり、定義することで有効化されます。 +マクロは`EXTRA_CFLAGS`オプションを使用するか、`USER_SETTINGS_FILE`に配置することで有効化できます。 +マクロのより詳細なドキュメントは、リファレンスマニュアルの「起動/設定/シャットダウンサブシステム」節をご覧ください。 + +| `make`オプション | マクロオプション | 説明 | +| ------------ | ----------------- | -------- | +| `SHELL` | | `bash`への明示的/代替パスを提供 | +| `AWK` | | Gnu `awk`への明示的/代替パスを提供 | +| `V` | | 詳細な`make`出力
例：`make V=1 -j test` | +| `USER_MAKE_CONF` | | メインMakefileの先頭に含めるユーザー定義make節
例：`make -j USER_MAKE_CONF=Makefile.settings` | +| `EXTRA_CFLAGS` | | コンパイラに逐語的に渡される追加引数 | +| `EXTRA_LDFLAGS` | | リンカに逐語的に渡される追加引数 | +| `SRC_TOP` | | ソースコードのトップレベルディレクトリ（デフォルト`pwd -P`） | +| `BUILD_TOP` | | 代替場所（ソースツリーの外部またはサブディレクトリ）でアーティファクトを使用してビルド
例：`make BUILD_TOP=./build -j test`| +| `DEBUG` | | 使用するコンパイラデバッグフラグ（デフォルト`-ggdb`） | +| `OPTIM` | | 使用するオプティマイザフラグ（デフォルト`-O3`） | +| `HOST` | | クロスコンパイル用のターゲットホストタプル（デフォルト未設定、つまりネイティブターゲティング） | +| `RUNTIME` | | ターゲットランタイムエコシステム -- デフォルト未設定、`FreeRTOS-lwIP`と`Linux-lwIP`が認識されます | +| `C_WARNFLAGS` | | 使用する警告フラグ（一般的に適用可能なデフォルトをオーバーライド） | +| `STATIC` | | 静的リンクされた単体テストをビルド | +| `STRIPPED` | | バイナリからデバッグシンボルを取り除く | +| `FUNCTION_SECTIONS` | | 未使用のオブジェクトコード（関数粒度）を削除して総サイズを最小化 | +| `BUILD_DYNAMIC` | | 動的リンクされたライブラリをビルド | +| `VERY_QUIET` | | ビルド中のすべての非エラー出力を抑制 | +| `TAR` | | `make dist`用のGNU tarバイナリへのパス、macOSでは`gtar`に設定すべき | +| `VERSION` | | `make dist`用にパッケージするバージョン | +| `LWIP` | `WOLFSENTRY_LWIP` | 真偽値 -- lwIP用の適切なビルド設定を有効化 | +| `NO_STDIO_STREAMS` | `WOLFSENTRY_NO_STDIO_STREAMS` | `stdio`ストリームI/Oに依存する機能を省略するよう定義 | +| | `WOLFSENTRY_NO_STDIO_H` | `stdio.h`のインクルードを抑制するよう定義 | +| `NO_ADDR_BITMASK_MATCHING` | `WOLFSENTRY_NO_ADDR_BITMASK_MATCHING` | アドレスのビットマスクマッチングサポートを省略し、プレフィックスマッチングのみをサポートするよう定義 | +| `NO_IPV6` | `WOLFSENTRY_NO_IPV6` | IPv6アドレスファミリーのサポートを省略するよう定義 | +| `NO_JSON` | `WOLFSENTRY_NO_JSON` | JSON設定サポートを省略するよう定義 | +| `NO_JSON_DOM` | `WOLFSENTRY_NO_JSON_DOM` | JSON DOM APIを省略するよう定義 | +| `CALL_TRACE` | `WOLFSENTRY_DEBUG_CALL_TRACE` | ランタイムコールスタックログ記録を有効化するよう定義（非常に詳細） | +| `USER_SETTINGS_FILE` | `WOLFSENTRY_USER_SETTINGS_FILE` | 自動生成された`wolfsentry_settings.h`を置き換える代替設定ファイル | +| `SINGLETHREADED` | `WOLFSENTRY_SINGLETHREADED` | スレッドセーフティロジックを省略し、スレッドセーフティ関数とマクロをno-opマクロに置き換えるよう定義 | +| | `WOLFSENTRY_NO_PROTOCOL_NAMES` | 定義されている場合、エラーコードとソースコードファイルを人間が読める形式でレンダリングするAPIを省略。数値的にレンダリングされます。 | +| | `WOLFSENTRY_NO_GETPROTOBY` | プロトコルとサービスの名前による検索とレンダリングを無効にするよう定義 | +| | `WOLFSENTRY_NO_ERROR_STRINGS` | 定義されている場合、エラーコードとソースコードファイルを人間が読める形式でレンダリングするAPIを省略。数値的にレンダリングされます。 | +| | `WOLFSENTRY_NO_MALLOC_BUILTINS` | 定義されている場合、組み込みヒープアロケータプリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_allocator`内のすべての関数の実装が含まれている必要があります。 | +| | `WOLFSENTRY_HAVE_NONGNU_ATOMICS` | gnu様式のアトミック組み込み関数が利用できない場合に定義。組み込み関数用の`WOLFSENTRY_ATOMIC_*()`マクロ定義を`WOLFSENTRY_USER_SETTINGS_FILE`で提供する必要があります（`wolfsentry_util.h`を参照）。 | +| | `WOLFSENTRY_NO_CLOCK_BUILTIN` | 定義されている場合、組み込み時間プリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_timecbs`内のすべての関数の実装が含まれている必要があります。 | +| | `WOLFSENTRY_NO_SEM_BUILTIN` | 定義されている場合、組み込みセマフォプリミティブを省略します；wolfSentry APIに提供される`wolfsentry_host_platform_interface`には、`struct wolfsentry_semcbs`内のすべての関数の実装が含まれている必要があります。 | +| | `WOLFSENTRY_USE_NONPOSIX_SEMAPHORES` | POSIXセマフォAPIが利用できない場合に定義。`wolfsentry_util.c`に非POSIX組み込み実装が存在しない場合は、#WOLFSENTRY_NO_SEM_BUILTINを設定する必要があり、wolfSentry APIに提供される`wolfsentry_host_platform_interface`の`wolfsentry_semcbs`スロットに完全なセマフォ実装（shimセット）を含める必要があります。 | +| | `WOLFSENTRY_SEMAPHORE_INCLUDE` | セマフォAPIを宣言するヘッダーファイルのパスに定義 | +| | `WOLFSENTRY_USE_NONPOSIX_THREADS` | POSIXスレッドAPIが利用できない場合に定義。`WOLFSENTRY_THREAD_INCLUDE`、`WOLFSENTRY_THREAD_ID_T`、`WOLFSENTRY_THREAD_GET_ID_HANDLER`を定義する必要があります。 | +| | `WOLFSENTRY_THREAD_INCLUDE` | スレッディングAPIを宣言するヘッダーファイルのパスに定義 | +| | `WOLFSENTRY_THREAD_ID_T` | POSIX `pthread_t`に類似した適切な型に定義 | +| | `WOLFSENTRY_THREAD_GET_ID_HANDLER` | POSIX `pthread_self`に類似した、`WOLFSENTRY_THREAD_ID_T`型の値を返すvoid関数の名前に定義 | +| | `FREERTOS` | FreeRTOS用にビルド | + +### ビルドとセルフテストのコマンド例 + +Linux上で`libwolfsentry.a`をビルドしてテスト + +`make -j test` + +詳細ビルド + +`make V=1 -j test` + +代替場所（ソースツリーの外部またはサブディレクトリ）でアーティファクトを使用してビルド + +`make BUILD_TOP=./build -j test` + +代替ビルド場所から非標準の宛先にインストール + +`make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install` + +`libwolfsentry.a`をビルドして様々な設定でテスト + +`make -j check` + +マルチスレッドサポートなしで`libwolfsentry.a`をビルドしてテスト + +`make -j SINGLETHREADED=1 test` + +他の利用可能なmakeフラグは`STATIC=1`、`STRIPPED=1`、`NO_JSON=1`、`NO_JSON_DOM=1`であり、`DEBUG`、`OPTIM`、`C_WARNFLAGS`のデフォルト値もオーバーライドできます。 + + +デフォルトをオーバーライドするためにユーザー提供のmakefileプリアンブルでビルド + +`make -j USER_MAKE_CONF=Makefile.settings` + +`Makefile.settings`は`OPTIM := -Os`のような単純な設定や、追加のルールと依存関係メカニズムを含む詳細なmakefileコードを含むことができます。 + + +最小構成でビルド + +`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"` + +ユーザー設定でビルドしてテスト + +`make -j USER_SETTINGS_FILE=user_settings.h test` + +FreeRTOSとlwIPソースツリーが図示のように配置されていると仮定して、ARM32上のFreeRTOS用にビルド + +`make -j HOST=arm-none-eabi RUNTIME=FreeRTOS-lwIP FREERTOS_TOP=../third/FreeRTOSv202212.00 LWIP_TOP=../third/lwip EXTRA_CFLAGS=-mcpu=cortex-m7` + + +## プロジェクト例 + +`wolfsentry/examples/`サブディレクトリに、一連のサンプルポートとアプリケーションを配置しています。 +具体的には、Linux D-Bus機能と統合した、TLS対応組み込みWebサーバーを実装するデモポップアップ通知システムなどがあります。 + +APIの使用法に関するより包括的な例は`tests/unittests.c`、特に`test_static_routes()`、`test_dynamic_rules()`、`test_json()`、`tests/test-config*.json`のJSON設定ファイルにあります。 + +[wolfSSLリポジトリ](https://github.com/wolfSSL/wolfssl)では、`WOLFSSL_WOLFSENTRY_HOOKS`で保護された`wolfssl/test.h`内のコードをご参照ください。 +これには`wolfsentry_store_endpoints()`、`wolfSentry_NetworkFilterCallback()`、`wolfsentry_setup()`、`tcp_connect_with_wolfSentry()`が含まれます。 +また、`WOLFSSL_WOLFSENTRY_HOOKS`で保護された`examples/server/server.c`と`examples/client/client.c`内のコードもお役に立つかもしれません。 + +wolfSSL統合でビルドするには`--enable-wolfsentry`でwolfSSLを設定し、wolfSentryが非標準の場所にインストールされている場合は`--with-wolfsentry=/インストールパス`を使用してください。 +wolfSSLテストクライアント/サーバーは、`--wolfsentry-config `を使用して、コマンドラインからユーザー提供のwolfSentry JSON設定をロードできます。 diff --git a/wolfSentry/src-ja/freertos-lwip-app.md b/wolfSentry/src-ja/freertos-lwip-app.md new file mode 100644 index 00000000..d31c997f --- /dev/null +++ b/wolfSentry/src-ja/freertos-lwip-app.md @@ -0,0 +1,262 @@ +# FreeRTOS/lwIPアプリケーション用のwolfSentryの構築と初期化 + +FreeRTOSでlwIPとnewlib-nanoを使用するwolfSentryライブラリの構築は、トップレベルの`Makefile`によって直接サポートされています。 +例えば、ARM Cortex M7の場合、`libwolfsentry.a`は以下のようにビルドできます。 + +```sh +make HOST=arm-none-eabi EXTRA_CFLAGS='-mcpu=cortex-m7' RUNTIME=FreeRTOS-lwIP FREERTOS_TOP="$FREERTOS_TOP" LWIP_TOP="$LWIP_TOP" +``` + +`FREERTOS_TOP`は、その直下に`FreeRTOS/Source`があるFreeRTOSディストリビューションのトップへのパスです。 +同様に`LWIP_TOP`は、その直下に`src`があるlwIPディストリビューションのトップへのパスです。 + +以下のコードフラグメントをFreeRTOSアプリケーションに追加して、動的にロードされるポリシー（JSON）でwolfSentryを有効化できます。 +実証されているコードパターンの多くはオプションです。 +必要不可欠な呼び出しは`wolfsentry_init()`、`wolfsentry_config_json_oneshot()`、`wolfsentry_install_lwip_filter_callbacks()`のみです。 +これらにはそれぞれ、ユーザーにより多くの制御を与えるAPIバリアントもあります。 + +```c +#define WOLFSENTRY_SOURCE_ID WOLFSENTRY_SOURCE_ID_USER_BASE +#define WOLFSENTRY_ERROR_ID_USER_APP_ERR0 (WOLFSENTRY_ERROR_ID_USER_BASE-1) + /* ユーザー定義エラーIDは WOLFSENTRY_ERROR_ID_USER_BASE（負の値）から開始してカウントダウンする */ + +#include +#include + +static struct wolfsentry_context *wolfsentry_lwip_ctx = NULL; + +static const struct wolfsentry_eventconfig demo_config = { +#ifdef WOLFSENTRY_HAVE_DESIGNATED_INITIALIZERS + .route_private_data_size = 64, + .route_private_data_alignment = 0, /* デフォルトアライメント -- sizeof(void *) と同じ */ + .max_connection_count = 10, /* デフォルトでは、同じルートにマッチする + * 同時接続を10以下に制限する + */ + .derogatory_threshold_for_penaltybox = 4, /* 同じルートにマッチする軽蔑的イベントが4回発生したら、 + * そのルートをペナルティボックス状態に移行する + */ + .penaltybox_duration = 300, /* ルートをペナルティボックス状態で5分間保持する + * wolfsentry_init() に渡すときは秒単位で指定 + */ + .route_idle_time_for_purge = 0, /* 0で無効化 -- 自動パージは通常 + * デフォルト設定としてはあまり意味がない + */ + .flags = WOLFSENTRY_EVENTCONFIG_FLAG_COMMENDABLE_CLEARS_DEROGATORY, /* 称賛すべきイベントが + * ルートにマッチしたときに、そのルートの + * 軽蔑的カウントを自動的にクリアする + */ + .route_flags_to_add_on_insert = 0, + .route_flags_to_clear_on_insert = 0, + .action_res_filter_bits_set = 0, + .action_res_filter_bits_unset = 0, + .action_res_bits_to_add = 0, + .action_res_bits_to_clear = 0 +#else + 64, + 0, + 10, + 4, + 300, + 0, + WOLFSENTRY_EVENTCONFIG_FLAG_COMMENDABLE_CLEARS_DEROGATORY, + 0, + 0, + 0, + 0, + 0, + 0 +#endif + }; + +/* このルーチンは、lwIPへの直接呼び出しの前に、つまり + * lwip_init() や tcpip_init() の前に、アプリケーションによって一度呼び出される必要がある + */ +wolfsentry_errcode_t activate_wolfsentry_lwip(const char *json_config, int json_config_len) +{ + wolfsentry_errcode_t ret; + char err_buf[512]; /* wolfsentry_config_json_oneshot() からの + * 詳細なエラーメッセージ用バッファ + */ + + /* スタック上にスレッド状態構造体を割り当てる。 + * 最後のセミコロンはマクロ定義によって提供されるため、 + * シングルスレッドアプリケーションビルドでは何も展開されない + */ + WOLFSENTRY_THREAD_HEADER_DECLS + + if (wolfsentry_lwip_ctx != NULL) { + printf("activate_wolfsentry_lwip() called multiple times.\n"); + WOLFSENTRY_ERROR_RETURN(ALREADY); + } + +#ifdef WOLFSENTRY_ERROR_STRINGS + /* WOLFSENTRY_ERROR_FMT/WOLFSENTRY_ERROR_FMT_ARGS() 用の + * アプリソースコードファイル名のプリティプリントを有効化 + */ + ret = WOLFSENTRY_REGISTER_SOURCE(); + WOLFSENTRY_RERETURN_IF_ERROR(ret); + + /* アプリ固有のエラーコードのプリティプリントを有効化 */ + ret = WOLFSENTRY_REGISTER_ERROR(USER_APP_ERR0, "failure in application code"); + WOLFSENTRY_RERETURN_IF_ERROR(ret); +#endif + + /* スレッド状態構造体を初期化 -- これによりスレッドIDが設定される */ + WOLFSENTRY_THREAD_HEADER_INIT_CHECKED(WOLFSENTRY_THREAD_FLAG_NONE); + + /* メインのwolfSentry初期化ルーチンを呼び出す + * + * WOLFSENTRY_CONTEXT_ARGS_OUT() は、それを必要とするAPIに + * スレッド構造体ポインタを条件付きで渡すことを抽象化するマクロ。 + * これがシングルスレッドビルド（!defined(WOLFSENTRY_THREADSAFE)）の場合、 + * スレッド引数は完全に省略される。 + * + * WOLFSENTRY_CONTEXT_ARGS_OUT_EX() は、"wolfsentry" が渡すべき + * 正しい引数でない場合に、呼び出し元が最初の引数を明示的に指定できる変種。 + * ここでは、ホストプラットフォームインターフェース（"hpi"）用にnullポインタを + * 渡すために使用される。 + */ + ret = wolfsentry_init( + wolfsentry_build_settings, + WOLFSENTRY_CONTEXT_ARGS_OUT_EX(NULL /* hpi */), + &demo_config, + &wolfsentry_lwip_ctx); + if (ret < 0) { + printf("wolfsentry_init() failed: " WOLFSENTRY_ERROR_FMT "\n", + WOLFSENTRY_ERROR_FMT_ARGS(ret)); + goto out; + } + + /* ユーザー定義アクションがあれば、ここに挿入する */ + ret = wolfsentry_action_insert( + WOLFSENTRY_CONTEXT_ARGS_OUT_EX(wolfsentry_lwip_ctx), + "my-action", + WOLFSENTRY_LENGTH_NULL_TERMINATED, + WOLFSENTRY_ACTION_FLAG_NONE, + my_action_handler, + NULL, + NULL); + if (ret < 0) { + printf("wolfsentry_action_insert() failed: " WOLFSENTRY_ERROR_FMT "\n", + WOLFSENTRY_ERROR_FMT_ARGS(ret)); + goto out; + } + + if (json_config) { + if (json_config_len < 0) + json_config_len = (int)strlen(json_config); + + /* ポリシーの初期読み込みを実行 */ + ret = wolfsentry_config_json_oneshot( + WOLFSENTRY_CONTEXT_ARGS_OUT_EX(wolfsentry_lwip_ctx), + (unsigned char *)json_config, + (size_t)json_config_len, + WOLFSENTRY_CONFIG_LOAD_FLAG_NONE, + err_buf, + sizeof err_buf); + if (ret < 0) { + printf("wolfsentry_config_json_oneshot() failed: %s\n", err_buf); + goto out; + } + } /* そうでなければ、アプリケーションがプログラム的にポリシーを設定するか、 + * 自身で wolfsentry_config_json_oneshot() または関連APIを呼び出す必要がある。 + */ + + /* lwIPコールバックをインストール。この呼び出しが成功を返すと、 + * 以下に示すマスク引数によってフィルタリング対象として指定された + * すべてのlwIPトラフィックが、上記で読み込まれたポリシーに従って + * フィルタリング（またはその他の補完的処理）の対象となる。 + * + * 特定のプロトコルがLWIPから除外されている場合、そのマスク引数は + * ここで0として渡さなければならない。そうしないと、 + * IMPLEMENTATION_MISSING エラーが発生する。 + * + * コールバックのインストールでは、wolfsentry_shutdown() によって + * 自動的に呼び出されるクリーンアップルーチンも登録される。 + */ + +#define LWIP_ALL_EVENTS ( \ + (1U << FILT_BINDING) | \ + (1U << FILT_DISSOCIATE) | \ + (1U << FILT_LISTENING) | \ + (1U << FILT_STOP_LISTENING) | \ + (1U << FILT_CONNECTING) | \ + (1U << FILT_ACCEPTING) | \ + (1U << FILT_CLOSED) | \ + (1U << FILT_REMOTE_RESET) | \ + (1U << FILT_RECEIVING) | \ + (1U << FILT_SENDING) | \ + (1U << FILT_ADDR_UNREACHABLE) | \ + (1U << FILT_PORT_UNREACHABLE) | \ + (1U << FILT_INBOUND_ERR) | \ + (1U << FILT_OUTBOUND_ERR)) + + ret = wolfsentry_install_lwip_filter_callbacks( + WOLFSENTRY_CONTEXT_ARGS_OUT_EX(wolfsentry_lwip_ctx), + +#if LWIP_ARP || LWIP_ETHERNET + LWIP_ALL_EVENTS, /* ethernet_mask */ +#else + 0, +#endif +#if LWIP_IPV4 || LWIP_IPV6 + LWIP_ALL_EVENTS, /* ip_mask */ +#else + 0, +#endif +#if LWIP_ICMP || LWIP_ICMP6 + LWIP_ALL_EVENTS, /* icmp_mask */ +#else + 0, +#endif +#if LWIP_TCP + LWIP_ALL_EVENTS, /* tcp_mask */ +#else + 0, +#endif +#if LWIP_UDP + LWIP_ALL_EVENTS /* udp_mask */ +#else + 0 +#endif + ); + if (ret < 0) { + printf("wolfsentry_install_lwip_filter_callbacks: " + WOLFSENTRY_ERROR_FMT "\n", WOLFSENTRY_ERROR_FMT_ARGS(ret)); + } + +out: + if (ret < 0) { + /* 初期化が失敗した場合のクリーンアップ */ + wolfsentry_errcode_t shutdown_ret = + wolfsentry_shutdown(WOLFSENTRY_CONTEXT_ARGS_OUT_EX(&wolfsentry_lwip_ctx)); + if (shutdown_ret < 0) + printf("wolfsentry_shutdown: " + WOLFSENTRY_ERROR_FMT "\n", WOLFSENTRY_ERROR_FMT_ARGS(shutdown_ret)); + } + + WOLFSENTRY_THREAD_TAILER_CHECKED(WOLFSENTRY_THREAD_FLAG_NONE); + + WOLFSENTRY_ERROR_RERETURN(ret); +} + +/* lwIPへの最終呼び出し後に、アプリケーションによって一度呼び出される */ +wolfsentry_errcode_t shutdown_wolfsentry_lwip(void) +{ + wolfsentry_errcode_t ret; + if (wolfsentry_lwip_ctx == NULL) { + printf("shutdown_wolfsentry_lwip() called before successful activation.\n"); + return -1; + } + + /* シャットダウン成功後、wolfsentry_lwip_ctx は初期化前と同様に再びnullポインタになる + */ + ret = wolfsentry_shutdown(WOLFSENTRY_CONTEXT_ARGS_OUT_EX4(&wolfsentry_lwip_ctx, NULL)); + if (ret < 0) { + printf("wolfsentry_shutdown: " + WOLFSENTRY_ERROR_FMT "\n", WOLFSENTRY_ERROR_FMT_ARGS(ret)); + } + + return ret; +} +``` diff --git a/wolfSentry/src-ja/json_configuration.md b/wolfSentry/src-ja/json_configuration.md new file mode 100644 index 00000000..019ad8dd --- /dev/null +++ b/wolfSentry/src-ja/json_configuration.md @@ -0,0 +1,571 @@ +# JSONドキュメントを使用したwolfSentryの設定 + +wolfSentryのほとんどの機能は、ライブラリにJSONドキュメントを提供することで設定、および動的に再設定することができます。 +この機能を使用するには、アプリケーションのwolfSentry初期化に以下を追加してください。 + +``` +#include +``` + +初期化とアプリケーション提供のコールバック（ある場合）のインストール後、設定を読み込むために以下のAPIのうち1つを呼び出す必要があります。 + +* `wolfsentry_config_json_oneshot()` +* `wolfsentry_config_json_oneshot_ex()`、JSON解析の細かい制御のための追加の`json_config`引数付き（`wolfsentry/centijson_sax.h`の`struct JSON_CONFIG`を参照） +* ストリーミングAPI： + * `wolfsentry_config_json_init()` または `wolfsentry_config_json_init_ex()` + * `wolfsentry_config_json_feed()` + * `wolfsentry_config_json_fini()` + +引数の詳細については、`wolfsentry/wolfsentry_json.h`をご参照ください。 + + +## JSON基本事項 + +wolfSentryの設定には、[RFC 8259](https://tex2e.github.io/rfc-translater/html/rfc8259.html)で定義された標準JSON構文を使用します。 +ただし[RFC 7493](https://tex2e.github.io/rfc-translater/html/rfc7493.html)による制限を受け、さらに以下に示す追加の要件があります。 +特にJSONドキュメント内の特定のセクションは、出現順序が制限されています。 + +* `"wolfsentry-config-version"`は最初に現れ、各イベント定義は、`"aux-parent-event"`、`"parent-event"`、`"default-event"`句を通じてそれを参照するイベント、ルート、デフォルトポリシーの定義より前に現れる必要があります。 + +* イベント定義内では、`"label"`、`"priority"`、および`"config"`要素は他のすべての要素より前に現れる必要があります。 + +これらの順序制約は、設定の高効率SAXスタイル（逐次増分）読み込みを可能にするために必要です。 + +すべてのワイルドカードフラグはルート上で暗黙的に設定され、設定内で明示的な割り当てがあるフィールドに対してはクリアされます。 +例えば、ルートが特定の`"family"`を指定する場合、`WOLFSENTRY_ROUTE_FLAG_SA_FAMILY_WILDCARD`は暗黙的にクリアされます。 +したがって、ルート定義内でワイルドカードフラグを明示的に設定またはクリアする必要はありません。 + +特定の要素バリアントは、ビルド設定により利用できない場合があることに注意してください。 + +* `address_family_name`: `defined(WOLFSENTRY_PROTOCOL_NAMES)`の場合に利用可能 +* `route_protocol_name`: `!defined(WOLFSENTRY_NO_GETPROTOBY)`の場合に利用可能 +* `address_port_name`: `!defined(WOLFSENTRY_NO_GETPROTOBY)`の場合に利用可能 +* `json_value_clause`: `defined(WOLFSENTRY_HAVE_JSON_DOM)`の場合に利用可能 + +呼び出し側が提供するイベントおよびアクションラベルは、`WOLFSENTRY_BUILTIN_LABEL_PREFIX`（デフォルトでは`"%"`）で始まってはいけません。 +これらが組み込み用に予約されているためです。 + +`"config-update"`により、デフォルト設定を更新することができます。 +wolfSentryは最初に`wolfsentry_init()`の`config`引数によって設定されるため（これは`NULL`で渡すことができ、組み込みデフォルトを意味します）、これは「更新」と呼ばれます。 +時間（`wolfsentry_eventconfig.penaltybox_duration`と`wolfsentry_eventconfig.route_idle_time_for_purge`）は、メンバーの`wolfsentry_time_t`型に関係なく、秒単位で`wolfsentry_init()`に渡される必要があることに注意してください。 + +## JSON読み込みフラグ + +`wolfsentry_config_json_init()`と`wolfsentry_config_json_oneshot()`への`flags`引数は、ビット単位ORで構築され、以下のようにJSONの処理方法を変更します。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_NONE` -- フラグではなく、すべてゼロで、デフォルト動作を意味します。 + wolfSentryコアはロックされ、現在の設定はフラッシュされ、新しい設定が増分的に読み込まれます。 + 読み込み中のエラーは、wolfSentryを未定義状態に残し、その後のフラッシュと成功する読み込みで回復できます。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_NO_FLUSH` -- 設定の初期フラッシュを抑制し、増分読み込みを可能にします。 + 読み込み中のエラーは、wolfSentryを未定義状態に残し、`WOLFSENTRY_CONFIG_LOAD_FLAG_DRY_RUN`または`WOLFSENTRY_CONFIG_LOAD_FLAG_LOAD_THEN_COMMIT`も提供されていない限り、その後のフラッシュと成功する読み込みでのみ回復できます。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_DRY_RUN` -- 一時設定に読み込み、戻る前に割り当て解除します。 + 実行中の設定は変更されません。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_LOAD_THEN_COMMIT` -- 新しく割り当てられた設定に読み込み、読み込みが正常に完了した場合にのみインストールします。 + エラー時、実行中の設定は変更されません。 + 成功時、古い設定は割り当て解除されます。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_NO_ROUTES_OR_EVENTS` -- 提供されたJSON内の`"routes"`および`"events"`セクションの読み込みを抑制します。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_FLUSH_ONLY_ROUTES` -- 読み込みプロセスの開始時、ルートを除くすべての現在の設定を保持し、ルートはフラッシュされます。 + これは、動的に追加されたルートの保存/復元のために`wolfsentry_route_table_dump_json_*()`と組み合わせて使用すると便利です。 + +* `WOLFSENTRY_CONFIG_LOAD_FLAG_JSON_DOM_DUPKEY_ABORT` -- ユーザー定義JSON値の処理時、重複キーで読み込みを中断します。 +* `WOLFSENTRY_CONFIG_LOAD_FLAG_JSON_DOM_DUPKEY_USEFIRST` -- ユーザー定義JSON値の処理時、オブジェクト内の任意のキーについて、最初に遭遇した出現を使用します。 +* `WOLFSENTRY_CONFIG_LOAD_FLAG_JSON_DOM_DUPKEY_USELAST` -- ユーザー定義JSON値の処理時、オブジェクト内の任意のキーについて、最後に遭遇した出現を使用します。 +* `WOLFSENTRY_CONFIG_LOAD_FLAG_JSON_DOM_MAINTAINDICTORDER` -- ユーザー定義JSON値の処理時、順序情報を保存し、その後の`wolfsentry_kv_render_value()`または`json_dom_dump(..., JSON_DOM_DUMP_PREFERDICTORDER)`への呼び出しが、辞書的にソートされるのではなく、提供された順序でオブジェクトをレンダリングするようにします。 + +`WOLFSENTRY_CONFIG_LOAD_FLAG_JSON_DOM_*`フラグはデフォルト設定の場合のように、ビルドで`WOLFSENTRY_HAVE_JSON_DOM`が定義されている場合にのみ許可されることにご注意ください。 + +## JSON構文の概要 + +以下は、利用可能なすべての設定ノードを示すJSON「lint」疑似ドキュメントです。 +この後に示すABNF定義を参照する値指定子を含んでいます。 +許可される値についても後に示しています。 + +``` +{ + "wolfsentry-config-version" : 1, + "config-update" : { + "max-connection-count" : uint32, + "penalty-box-duration" : duration, + "route-idle-time-for-purge" : duration, + "derog-thresh-for-penalty-boxing" : uint16, + "derog-thresh-ignore-commendable" : boolean, + "commendable-clears-derogatory" : boolean, + "route-flags-to-add-on-insert" : route_flag_list, + "route-flags-to-clear-on-insert" : route_flag_list, + "action-res-filter-bits-set" : action_res_flag_list, + "action-res-filter-bits-unset" : action_res_flag_list, + "action-res-bits-to-add" : action_res_flag_list, + "action-res-bits-to-clear" : action_res_flag_list, + "max-purgeable-routes" : uint32, + "max-purgeable-idle-time" : duration + }, + "events" : [ + { "label" : label, + "priority" : uint16, + "config" : { + "max-connection-count" : uint32, + "penalty-box-duration" : duration, + "route-idle-time-for-purge" : duration, + "derog-thresh-for-penalty-boxing" : uint16, + "derog-thresh-ignore-commendable" : boolean, + "commendable-clears-derogatory" : boolean, + "route-flags-to-add-on-insert" : route_flag_list, + "route-flags-to-clear-on-insert" : route_flag_list, + "action-res-filter-bits-set" : action_res_flag_list, + "action-res-filter-bits-unset" : action_res_flag_list, + "action-res-bits-to-add" : action_res_flag_list, + "action-res-bits-to-clear" : action_res_flag_list + }, + "aux-parent-event" : label, + "post-actions" : action_list, + "insert-actions" : action_list, + "match-actions" : action_list, + "update-actions" : action_list, + "delete-actions" : action_list, + "decision-actions" : action_list + } + ], + "default-policies" : { + "default-policy" : default_policy_value, + "default-event" ":" label + }, + "routes" : [ + { + "parent-event" : label, + "af-wild" : boolean, + "raddr-wild" : boolean, + "rport-wild" : boolean, + "laddr-wild" : boolean, + "lport-wild" : boolean, + "riface-wild" : boolean, + "liface-wild" : boolean, + "tcplike-port-numbers" : boolean, + "direction-in" : boolean, + "direction-out" : boolean, + "penalty-boxed" : boolean, + "green-listed" : boolean, + "dont-count-hits" : boolean, + "dont-count-current-connections" : boolean, + "port-reset" : boolean, + + "family" : address_family, + "protocol" : route_protocol, + "remote" : { + "interface" : uint8, + "address" : route_address, + "prefix-bits" : uint16, + "bitmask" : route_address, + "port" : endpoint_port + }, + "local" : { + "interface" : uint8, + "address" : route_address, + "prefix-bits" : uint16, + "bitmask" : route_address, + "port" : endpoint_port + } + } + ], + "user-values" : { + label : null, + label : true, + label : false, + label : number_sint64, + label : number_float, + label : string, + label : { "uint" : number_uint64 }, + label : { "sint" : number_sint64 }, + label : { "float" : number_float }, + label : { "string" : string_value }, + label : { "base64" : base64_value }, + label : { "json" : json_value } + } +} +``` + +## 要素の概要 + +`wolfsentry-config-version` -- 最初に現れ、値は `1` でなければならない。 + +`config-update` -- デフォルトおよびグローバルパラメータを設定する。 + デフォルトパラメータは、親イベントを持たないルート、独自の設定を持たない親イベントを持つルートに適用される。 + +* `max-connection-count` -- ゼロ以外の場合、同時接続制限で、これを超える追加の接続要求は拒否される。 + +* `penalty-box-duration` -- ゼロ以外の場合、ルートが自動解除される前にペナルティボックス状態に留まる期間。 + +* `derog-thresh-for-penalty-boxing` -- ゼロ以外の場合、累積された否定的カウント（`WOLFSENTRY_ACTION_RES_DEROGATORY` インシデントから）がルートを自動的にペナルティボックス化する閾値。 + +* `derog-thresh-ignore-commendable` -- trueの場合、自動ペナルティボックス化をチェックする際に、`WOLFSENTRY_ACTION_RES_COMMENDABLE` からのカウントは否定的カウントから減算されない。 + +* `commendable-clears-derogatory` -- trueの場合、`WOLFSENTRY_ACTION_RES_COMMENDABLE` からの各カウントは否定的カウントをゼロにする。 + +* `max-purgeable-routes` -- ルートテーブルで許可する短命ルートの数のグローバル制限で、これを超えると最も最近にマッチしていない短命ルートが早期に強制削除される。 + イベントの `config` 句では許可されない。 + +* `max-purgeable-idle-time` -- 短命ルートのグローバル絶対最大アイドル時間で、ゼロ以外の `wolfsentry_route_metadata_exports.connection_count` を持つ古い（期限切れ）短命ルートのパージを制御する。 + デフォルトは制限なし。 + イベントの `config` 句では許可されない。 + +* `route-idle-time-for-purge` -- ゼロ以外の場合、ルートの最新のディスパッチマッチ後にガベージコレクションされるまでの時間。 + 主にイベントの `config` 句で有用（下記の `events` を参照）。 + +* `route-flags-to-add-on-insert` -- 挿入時に新しいルートに設定するルートフラグのリスト。 + 主にイベントの `config` 句で有用（下記の `events` を参照）。 + +* `route-flags-to-clear-on-insert` -- 挿入時に新しいルートでクリアするルートフラグのリスト。 + 主にイベントの `config` 句で有用（下記の `events` を参照）。 + +* `action-res-filter-bits-set` -- 参照ルートがマッチするためにルックアップ時（ディスパッチ）に設定されている必要がある `action_res` フラグのリスト。 + 主にイベントの `config` 句で有用（下記の `events` を参照）。 + +* `action-res-filter-bits-unset` -- 参照ルートがマッチするためにルックアップ時（ディスパッチ）にクリアされている必要がある `action_res` フラグのリスト。 + 主にイベントの `config` 句で有用（下記の `events` を参照）。 + +* `action-res-bits-to-add` -- マッチ時に設定される `action_res` フラグのリスト。 + +* `action-res-bits-to-clear` -- マッチ時にクリアされる `action_res` フラグのリスト。 + + +`events` -- それぞれの定義を持つイベントのリスト。 + このセクションは複数回現れることができるが、任意の特定のイベント定義は、それを参照する定義よりも前に現れなければならない。 + +各イベントは以下の要素で構成され、`label` を除いてすべてオプションである。 +`label`、`priority`、`config` は他の要素より前に現れなければならない。 + +* `label` -- イベントが識別される名前。 + 許可される値については、下記のABNF文法の `label` の定義を参照。 + +* `priority` -- このイベントを `parent-event` として持つルートの優先度（下記の `routes` を参照）。 + 数値が低いほど優先度が高い。 + +* `config` -- この `parent-event` を持つルートに関連付ける設定。 + 上記の `config-update` と同様。 + +* `aux-parent-event` -- アクションハンドラーが使用するイベント参照、例えば組み込みの `"%track-peer-v1"` は `aux-parent-event` を新しいルートの `parent-event` としてルートを作成する。 + +* `post-actions` -- このイベントが `event_label` を介して `wolfsentry_route_event_dispatch()` などのディスパッチルーチンに渡されたときに実行するアクションのリスト。 + +* `insert-actions` -- このイベントを `parent-event` としてルートが挿入されたときに実行するアクションのリスト。 + +* `match-actions` -- ルートがディスパッチルーチンによってマッチし、そのルートがこのイベントを `parent-event` として持つときに実行するアクションのリスト。 + +* `update-actions` -- ルートがペナルティボックス状態の変更などのステータス更新を持ち、このイベントを `parent-event` として持つときに実行するアクションのリスト。 + +* `delete-actions` -- ルートが削除され、このイベントを `parent-event` として持つときに実行するアクションのリスト。 + +* `decision-actions` -- ディスパッチ最終決定（`action_results` の最終値）が決定され、マッチしたルートがこのイベントを `parent-event` として持つときに実行するアクションのリスト。 + +`default-policies` -- `wolfsentry_route_event_dispatch()` などの、ディスパッチルーチンのグローバルフォールスルーデフォルトポリシー。 + +* `default-policy` -- デフォルトで設定する単純な `action_result` フラグ、**accept**、**reject**、**reset** のいずれか。 + `reset`は関連する場合にTCPリセットとICMP到達不能応答パケットの生成を引き起こす。 + +* `default-event` -- ディスパッチルーチンがnull `event_label` で呼び出されたときに使用するイベント。 + +`routes` -- それぞれの定義を持つルートのリスト。 + このセクションは複数回現れることができる。 + +各ルートは以下の要素で構成され、すべてオプションである。 + +* `parent-event` -- ルートのダイナミクスを決定する属性を持つイベント。 + +* `family` -- マッチするアドレスファミリ。 + 許可される値については、下記のABNF文法の `address_family` の定義を参照。 + +* `protocol` -- マッチするプロトコル。 + 許可される値については、下記のABNF文法の `route_protocol` の定義を参照。 + +* `remote` -- トラフィックのリモートエンドポイントでマッチする属性。 + * `interface` -- 呼び出し元またはIPスタック統合によって選択され一貫して使用される任意の整数としてのネットワークインターフェースID。 + * `address` -- 慣用的な形式のネットワークアドレス。 + IPv4、IPv6、およびMACアドレスはすべてのオクテットを列挙しなければならない。 + 許可される値については、下記のABNF文法の `route_address` の定義を参照。 + * `prefix-bits` -- トラフィックがマッチしなければならない `address` のビット数（`bitmask` と相互排他的）。 + * `bitmask` -- ルート `address` とマッチする前にトラフィックアドレスに適用されるビットマスク（`prefix-bits` と相互排他的）。 + * `port` -- トラフィックがマッチしなければならないポート番号。 + +* `local` -- トラフィックのローカルエンドポイントでマッチする属性。 + `remote` と同じノードが利用可能。 +* `direction-in` -- trueの場合、インバウンドトラフィックをマッチ。 +* `direction-out` -- trueの場合、アウトバウンドトラフィックをマッチ。 +* `penalty-boxed` -- trueの場合、ルートにマッチするトラフィックはペナルティボックス化される（拒否またはリセット）。 +* `green-listed` -- trueの場合、ルートにマッチするトラフィックは受け入れられる。 +* `dont-count-hits` -- trueの場合、統計的記録管理を抑制する（ダイナミクスには影響しない）。 +* `dont-count-current-connections` -- trueの場合、同時接続の追跡を抑制し、`max-connection-count` がこのルートにマッチするトラフィックに影響しないようにする。 +* `port-reset` -- trueの場合、このルートがマッチしたときに `action_results` で `WOLFSENTRY_ACTION_RES_PORT_RESET` フラグを設定し、IPスタック統合が有効化されている場合（例：`wolfsentry_install_lwip_filter_callbacks()`）にTCPリセットまたはICMP到達不能応答パケットを生成させる。 + +`user-values` -- 任意の使用のためにアプリケーションコードで利用可能な完全にユーザー定義のデータの1つ以上のセクション。 + 各キーは下記のABNF文法で定義されるラベルである。 + 値は以下のいずれかになる。 + +* `null` +* `true` +* `false` +* 整数値、暗黙的に符号付き64ビット整数 +* 浮動小数点数、下記のABNF文法の `number_float` で定義される +* 標準のJSONエスケープを許可する引用符付き文字列 +* 下記のABNF文法で値が定義される、いくつかの明示的に型付けされた構造のいずれか + * `{ "uint" : number_uint64 }` + * `{ "sint" : number_sint64 }` + * `{ "float" : number_float }` + * `{ "string" : string_value }` + * `{ "base64" : base64_value }` + * `{ "json" : json_value }` + + +## 形式的ABNF文法 + +以下は設定構文と許可される値の形式的ABNF定義です。 + +この定義は、[RFC 5234](https://tex2e.github.io/rfc-translater/html/rfc5234)および[RFC 7405](https://tex2e.github.io/rfc-translater/html/rfc7405)で規定されるABNF構文を使用します。 +しかし、以下の例外があります。 + +* [RFC 8259](https://tex2e.github.io/rfc-translater/html/rfc8259.html)で提供されるように、空白は無視されます。 + +* `-` 演算子が追加され、引用符付きリテラル文字列またはリテラル文字のグループを受け入れ、対象テキストから省略された文字（ここでは、末尾のコンマ区切り文字）を提供し、演算子の引数で概念的に拡張された対象テキストでその時点まで含有グループのすべての概念的マッチング操作を実行します。 + +定義で使用される長さ制限は、wolfsentry_settings.h のデフォルト値を想定し、ラベルに32オクテット（`WOLFSENTRY_MAX_LABEL_BYTES`）、ユーザー定義値に16384オクテット（`WOLFSENTRY_KV_MAX_VALUE_BYTES`）です。 +これらの値は、ビルド時にユーザー提供の値でオーバーライドできます。 + +``` +"{" + DQUOTE %s"wolfsentry-config-version" DQUOTE ":" uint32 + [ "," DQUOTE %s"config-update" DQUOTE ":" top_config_list "," ] + *("," DQUOTE %s"events" ":" "[" + event *("," event) + "]") + [ "," DQUOTE %s"default-policies" DQUOTE ":" "{" + default_policy_item *("," default_policy_item) + "}" ] + *("," DQUOTE %s"routes" DQUOTE ":" "[" + route *("," route) + "]") + *("," DQUOTE %s"user-values" DQUOTE ":" "{" + user_item *("," user_item) + "}") +"}" + +event = "{" label_clause + [ "," priority_clause ] + [ "," event_config_clause ] + [ "," aux_parent_event_clause ] + *("," action_list_clause) "}" + +default_policy_item = + (DQUOTE %s"default-policy" DQUOTE ":" default_policy_value) / + (DQUOTE %s"default-event" DQUOTE ":" label) + +default_policy_value = (%s"accept" / %s"reject" / %s"reset") + +label_clause = DQUOTE %s"label" DQUOTE ":" label + +priority_clause = DQUOTE %s"priority" DQUOTE ":" uint16 + +event_config_clause = DQUOTE %s"config" DQUOTE ":" event_config_list + +aux_parent_event_clause = DQUOTE %s"aux-parent-event" DQUOTE ":" label + +action_list_clause = DQUOTE (%s"post-actions" / %s"insert-actions" / %s"match-actions" + / %s"update-actions" / %s"delete-actions" / %s"decision-actions") DQUOTE + ":" action_list + +action_list = "[" label *("," label) "]" + +event_config_list = "{" event_config_item *("," event_config_item) "}" + +top_config_list = "{" top_config_item *("," top_config_item) "}" + +top_config_item = event_config_item / max_purgeable_routes_clause / max_purgeable_idle_time_clause + +event_config_item = + (DQUOTE %s"max-connection-count" DQUOTE ":" uint32) / + (DQUOTE %s"penalty-box-duration" DQUOTE ":" duration) / + (DQUOTE %s"route-idle-time-for-purge" DQUOTE ":" duration) / + (DQUOTE %s"derog-thresh-for-penalty-boxing" DQUOTE ":" uint16 / + (DQUOTE %s"derog-thresh-ignore-commendable" DQUOTE ":" boolean / + (DQUOTE %s"commendable-clears-derogatory" DQUOTE ":" boolean / + (DQUOTE (%s"route-flags-to-add-on-insert" / %s"route-flags-to-clear-on-insert") DQUOTE ":" route_flag_list) / + (DQUOTE (%s"action-res-filter-bits-set" / %s"action-res-filter-bits-unset" / %s"action-res-bits-to-add" / %s"action-res-bits-to-clear") DQUOTE ":" action_res_flag_list) + +duration = number_sint64 / (DQUOTE number_sint64 [ %s"d" / %s"h" / %s"m" / %s"s" ] DQUOTE) + +max_purgeable_routes_clause = DQUOTE %s"max-purgeable-routes" DQUOTE ":" uint32 + +max_purgeable_idle_time_clause = DQUOTE %s"max-purgeable-idle-time" DQUOTE ":" duration + +route_flag_list = "[" route_flag *("," route_flag) "]" + +action_res_flag_list = "[" action_res_flag *("," action_res_flag) "]" + +route = "{" + [ parent_event_clause "," ] + *(route_flag_clause ",") + [ family_clause "," + [ route_protocol_clause "," ] + ] + [ route_remote_endpoint_clause "," ] + [ route_local_endpoint_clause "," ] + -"," +"}" + +parent_event_clause = DQUOTE %s"parent-event" DQUOTE ":" label +route_flag_clause = route_flag ":" boolean +family_clause = DQUOTE %s"family" DQUOTE ":" address_family +route_protocol_clause = DQUOTE %s"protocol" DQUOTE ":" route_protocol + +route_remote_endpoint_clause = DQUOTE %s"remote" DQUOTE ":" route_endpoint +route_local_endpoint_clause = DQUOTE %s"local" DQUOTE ":" route_endpoint + +route_endpoint = "{" + [ route_interface_clause "," ] + [ route_address_clause "," + [ (route_address_prefix_bits_clause / route_address_bitmask_clause) "," ] + ] + [ route_port_clause "," ] + -"," +"}" + +route_interface_clause = DQUOTE %s"interface" DQUOTE ":" uint8 + +route_address_clause = DQUOTE %s"address" DQUOTE ":" route_address + +route_address_bitmask_clause = DQUOTE %s"bitmask" DQUOTE ":" route_address + +route_address = DQUOTE (route_address_ipv4 / route_address_ipv6 / route_address_mac / route_address_user) DQUOTE + +route_address_ipv4 = uint8 3*3("." uint8) + +route_address_ipv6 = < IPv6address from RFC 5954 section 4.1 > + +route_address_mac = 1*2HEXDIG ( 5*5(":" 1*2HEXDIG) / 7*7(":" 1*2HEXDIG) ) + +route_address_user = < an address in a form recognized by a parser + installed with `wolfsentry_addr_family_handler_install()` + > + +address_family = uint16 / address_family_name + +address_family_name = DQUOTE ( "inet" / "inet6" / "link" / < a value recognized by wolfsentry_addr_family_pton() > ) DQUOTE + +route_address_prefix_bits_clause = DQUOTE %s"prefix-bits" DQUOTE ":" uint16 + +route_protocol = uint16 / route_protocol_name + +route_protocol_name = DQUOTE < a value recognized by getprotobyname_r(), requiring address family inet or inet6 > + +route_port_clause = DQUOTE %s"port" DQUOTE ":" endpoint_port + +endpoint_port = uint16 / endpoint_port_name + +endpoint_port_name = DQUOTE < a value recognized by getservbyname_r() for the previously designated protocol > DQUOTE + +route_flag = DQUOTE ( + %s"af-wild" / + %s"raddr-wild" / + %s"rport-wild" / + %s"laddr-wild" / + %s"lport-wild" / + %s"riface-wild" / + %s"liface-wild" / + %s"tcplike-port-numbers" / + %s"direction-in" / + %s"direction-out" / + %s"penalty-boxed" / + %s"green-listed" / + %s"dont-count-hits" / + %s"dont-count-current-connections" / + %s"port-reset" +) DQUOTE + +action_res_flag = DQUOTE ( + %s"none" / + %s"accept" / + %s"reject" / + %s"connect" / + %s"disconnect" / + %s"derogatory" / + %s"commendable" / + %s"stop" / + %s"deallocated" / + %s"inserted" / + %s"error" / + %s"fallthrough" / + %s"update" / + %s"port-reset" / + %s"sending" / + %s"received" / + %s"binding" / + %s"listening" / + %s"stopped-listening" / + %s"connecting-out" / + %s"closed" / + %s"unreachable" / + %s"sock-error" / + %s"user+0" / + %s"user+1" / + %s"user+2" / + %s"user+3" / + %s"user+4" / + %s"user+5" / + %s"user+6" / + %s"user+7" +) DQUOTE + +user_item = label ":" ( null / true / false / number_sint64_decimal / number_float / string / strongly_typed_user_item ) + +strongly_typed_user_item = + ( "{" DQUOTE %s"uint" DQUOTE ":" number_uint64 "}" ) / + ( "{" DQUOTE %s"sint" DQUOTE ":" number_sint64 "}" ) / + ( "{" DQUOTE %s"float" DQUOTE ":" number_float "}" ) / + ( "{" DQUOTE %s"string" DQUOTE ":" string_value "}" ) / + ( "{" DQUOTE %s"base64" DQUOTE ":" base64_value "}" ) / + json_value_clause + +json_value_clause = "{" DQUOTE %s"json" DQUOTE ":" json_value "}" + +null = %s"null" + +true = %s"true" + +false = %s"false" + +boolean = true / false + +number_uint64 = < decimal number in the range 0...18446744073709551615 > / + ( DQUOTE < hexadecimal number in the range 0x0...0xffffffffffffffff > DQUOTE ) / + ( DQUOTE < octal number in the range 00...01777777777777777777777 > DQUOTE ) + +number_sint64_decimal = < decimal number in the range -9223372036854775808...9223372036854775807 > + +number_sint64 = number_sint64_decimal / + ( DQUOTE < hexadecimal number in the range -0x8000000000000000...0x7fffffffffffffff > DQUOTE ) / + ( DQUOTE < octal number in the range -01000000000000000000000...0777777777777777777777 > DQUOTE ) + +number_float = < floating point value in a form and range recognized by the linked strtod() implementation > + +string_value = DQUOTE < any RFC 8259 JSON-valid string that decodes to at most 16384 octets > DQUOTE + +base64_value = DQUOTE < any valid RFC 4648 base64 encoding that decodes to at most 16384 octets > DQUOTE + +json_value = < any valid, complete and balanced RFC 8259 JSON expression, with + keys limited to WOLFSENTRY_MAX_LABEL_BYTES (default 32 bytes), + overall input length limited to WOLFSENTRY_JSON_VALUE_MAX_BYTES + if set (default unset), and overall depth limited to + WOLFSENTRY_MAX_JSON_NESTING (default 16) including the 4 parent + levels + > + +label = DQUOTE < any RFC 8259 JSON-valid string that decodes to at at least 1 and at most 32 octets > DQUOTE + +uint32 = < decimal integral number in the range 0...4294967295 > + +uint16 = < decimal integral number in the range 0...65535 > + +uint8 = < decimal integral number in the range 0...255 > +```