From 9845989c1cd94447a10985911a70c8cc9c10e8a9 Mon Sep 17 00:00:00 2001 From: Aidan Garske Date: Fri, 28 Aug 2026 17:26:48 -0700 Subject: [PATCH 1/2] Correct and modernize the wolfProvider manual against current sources --- wolfProvider/header.txt | 2 +- wolfProvider/mkdocs.yml | 2 +- wolfProvider/src/chapter01.md | 4 +- wolfProvider/src/chapter02.md | 9 ++-- wolfProvider/src/chapter03.md | 67 +++++++++++-------------- wolfProvider/src/chapter04.md | 4 +- wolfProvider/src/chapter05.md | 93 +++++++++++++++++++++-------------- wolfProvider/src/chapter06.md | 16 +++++- wolfProvider/src/chapter07.md | 56 ++++++++++++++++----- wolfProvider/src/chapter08.md | 38 +++++++------- wolfProvider/src/chapter09.md | 55 +++++++++++---------- wolfProvider/src/chapter11.md | 50 ++++++++++++------- 12 files changed, 239 insertions(+), 157 deletions(-) diff --git a/wolfProvider/header.txt b/wolfProvider/header.txt index 3f70983a..5bb60605 100644 --- a/wolfProvider/header.txt +++ b/wolfProvider/header.txt @@ -8,7 +8,7 @@ header-includes: # Fancy page headers - \usepackage{fancyhdr} - \pagestyle{fancy} - - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.} + - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2026 wolfSSL Inc.} # Wrap long syntax highlighting code blocks - \usepackage{fvextra} - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}} diff --git a/wolfProvider/mkdocs.yml b/wolfProvider/mkdocs.yml index 5b217135..13e8e0b5 100644 --- a/wolfProvider/mkdocs.yml +++ b/wolfProvider/mkdocs.yml @@ -2,7 +2,7 @@ site_name: wolfProvider Manual site_url: https://wolfssl.com/ docs_dir: build/html/ site_dir: html/ -copyright: Copyright © 2024 wolfSSL Inc. +copyright: Copyright © 2026 wolfSSL Inc. nav: - "1. Introduction": index.md - "2. OpenSSL Version Compatability": chapter02.md diff --git a/wolfProvider/src/chapter01.md b/wolfProvider/src/chapter01.md index 641d2ba1..db87bfe7 100644 --- a/wolfProvider/src/chapter01.md +++ b/wolfProvider/src/chapter01.md @@ -4,9 +4,11 @@ The wolfCrypt Provider (wolfProvider) is an OpenSSL provider for the wolfCrypt a wolfProvider is structured as a separate standalone library which links against wolfSSL (libwolfssl) and OpenSSL. wolfProvider implements and exposes an **OpenSSL provider implementation** which wraps the wolfCrypt native API internally. A high-level diagram of wolfProvider and how it relates to applications and OpenSSL is displayed below in Figure 1. -For more details on the design and architecture of wolfProvider see the [wolfProvider Design](chapter09.md) chapter. +For more details on the design and architecture of wolfProvider see the [wolfProvider Design](chapter08.md) chapter. ![wolfProvider Overview](wolfProvider_overview.png) wolfProvider is compiled by default as a shared library called **libwolfprov** which can be dynamically registered at runtime by an application or OpenSSL through a config file. wolfProvider also provides an entry point for applications to load the provider when compiled in a static build. + +wolfProvider is cross-platform, running on Linux and other *nix-like systems, macOS, and Windows (including a Visual Studio 2022 build of `libwolfprov.dll`). It works with all release versions of OpenSSL 3.x, in both FIPS and non-FIPS configurations. See the [Portability](chapter06.md) chapter for the list of supported platforms. diff --git a/wolfProvider/src/chapter02.md b/wolfProvider/src/chapter02.md index 1ccf8355..183d3b2f 100644 --- a/wolfProvider/src/chapter02.md +++ b/wolfProvider/src/chapter02.md @@ -1,8 +1,11 @@ # OpenSSL Version Compatability -wolfProvider has been tested against the following versions of OpenSSL. wolfProvider may work with other versions, but may require some modification or adjustment: +wolfProvider supports all release versions of OpenSSL 3.x. It is continuously tested against a range of OpenSSL 3.x releases, from OpenSSL 3.0.6 through the latest 3.x release. Both FIPS and non-FIPS wolfProvider builds are tested. -- OpenSSL 3.0.0 -- OpenSSL 3.5.0 +Some features have a minimum OpenSSL requirement: + +- Post-Quantum algorithms (ML-KEM, ML-DSA) and LMS require OpenSSL 3.6 or later. + +OpenSSL 3.0.3 through 3.0.5 are not recommended due to an upstream ECX `EVP_PKEY_cmp` bug; use OpenSSL 3.0.6 or later on the 3.0.x series. If you are interested in having wolfSSL add support to wolfProvider for other OpenSSL versions, please contact wolfSSL at [facts@wolfssl.com](mailto:facts@wolfssl.com). diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md index 95bdef25..35ba2857 100644 --- a/wolfProvider/src/chapter03.md +++ b/wolfProvider/src/chapter03.md @@ -10,16 +10,16 @@ The general wolfProvider package is structured as follows: ``` certs/ (Test certificates and keys, used with unit tests) +docs/ (Integration and FIPS integration guides) examples/ (Code examples) include/ wolfprovider/ (wolfProvider header files) -IDE/ (Integration examples) +IDE/ (Integration examples, including the Windows Visual Studio solution) scripts/ (wolfProvider scripts for testing and building) src/ (wolfProvider source files) test/ (wolfProvider test files) provider.conf (Example OpenSSL config file using wolfProvider) provider-fips.conf (Example OpenSSL config file using wolfProvider FIPS) -user_settings.h (EXAMPLE user_settings.h) ``` ## Building on *nix The quickest method is to use the `scripts/build-wolfprovider.sh` script as follows: @@ -33,13 +33,13 @@ It will clone, configure, compile, and install OpenSSL and wolfSSL with a defaul Setting the various environment variables prior to calling the script: ``` -OPENSSL_TAG=openssl-3.2.0 WOLFSSL_TAG=v5.7.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh +OPENSSL_TAG=openssl-3.5.4 WOLFSSL_TAG=v5.9.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh ``` Specifying arguments for the script to parse: ``` -./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.2.0 --wolfssl-ver=v5.7.2-stable --debug +./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.5.4 --wolfssl-ver=v5.9.2-stable --debug ``` Of course, these methods can be combined to achieve the desired build combination as well. @@ -53,25 +53,29 @@ If desired, each component can be manually compiled using the following guide. A pre-installed version of OpenSSL may be used with wolfProvider, or OpenSSL can be recompiled for use with wolfProvider. General instructions for compiling OpenSSL on *nix-like platforms will be similar to the following. For complete and comprehensive OpenSSL build instructions, reference the OpenSSL INSTALL file and documentation. ``` +# Check out the latest patch release of a supported OpenSSL 3.x series. git clone https://github.com/openssl/openssl.git cd openssl -./config no-fips -shared +git checkout "$(git tag -l 'openssl-3.*' | grep -Ev 'alpha|beta' | sort -V | tail -1)" +./config no-fips shared make sudo make install ``` +Always build against the latest patch release of your chosen OpenSSL 3.x series (see the OpenSSL Version Compatibility chapter); older point releases may be missing security fixes. + ### Building wolfSSL -If using a FIPS-validated version of wolfSSL with wolfProvider, follow the build instructions provided with your specific FIPS validated source bundle and Security Policy. In addition to the correct “--enable-fips” configure option, wolfProvider will need wolfSSL to be compiled with “**WOLFSSL_PUBLIC_MP**” defined. For example, building the “wolfCrypt Linux FIPSv5” bundle on Linux: +If using a FIPS-validated version of wolfSSL with wolfProvider, follow the build instructions provided with your specific FIPS validated source bundle and Security Policy. In addition to the correct "--enable-fips" configure option, wolfProvider will need wolfSSL to be compiled with "**WOLFSSL_PUBLIC_MP**" defined. For example, building the "wolfCrypt Linux FIPSv5" bundle on Linux: ``` cd wolfssl-X.X.X-commercial-fips-linuxv5 -./configure --enable-fips=v5 CFLAGS=”-DWOLFSSL_PUBLIC_MP” +./configure --enable-fips=v5 CFLAGS="-DWOLFSSL_PUBLIC_MP" make ./wolfcrypt/test/testwolfcrypt -< modify fips_test.c using verifyCore hash output from testwolfcrypt > +# modify fips_test.c using the verifyCore hash output from testwolfcrypt make ./wolfcrypt/test/testwolfcrypt -< all algorithms should PASS > +# all algorithms should PASS sudo make install ``` @@ -91,6 +95,7 @@ Add `--enable-curve25519` to include support for X25519 Key Exchange. Add `--enable-curve448` to include support for X448 Key Exchange. Add `--enable-ed25519` to include support for Ed25519 signatures and certificates.. Add `--enable-ed448` to include support for Ed448 signature and certificates. +Add `--enable-sha3` and `--enable-shake256` to include SHA-3 and SHAKE-256 support. Add `--enable-pwdbased` to the configure command above if PKCS#12 is used in OpenSSL. @@ -98,14 +103,12 @@ Add to CPPFLAGS `-DHAVE_FFDHE_6144 -DHAVE_FFDHE_8192 -DFP_MAX_BITS=16384` to ena Add to `--enable-hmac-copy` if performing HMAC repeatedly with the same key to improve performance. (Available with wolfSSL 5.7.8+.) -Add `--enable-sp=yes,asm' '--enable-sp-math-all'` to use SP Integer maths. Replace `-DFP_MAX_BITS=16384` with -DSP_INT_BITS=8192` when used. +Add `--enable-sp=yes,asm --enable-sp-math-all` to use SP integer math. Replace `-DFP_MAX_BITS=16384` with `-DSP_INT_BITS=8192` when used. Remove `-DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER` and add `--enable-fips=v2` to the configure command above if building from a FIPS v2 bundle and not the git repository. Change `--enable-fips=v2` to `--enable-fips=ready` if using a FIPS Ready bundle. If '--with-eccminsz=192' is not supported by wolfSSL, add '-DECC_MIN_KEY_SZ=192' to the CPPFLAGS. -`` - If cloning wolfSSL from GitHub, you will need to run the `autogen.sh` script before running `./configure`. This will generate the configure script: ``` ./autogen.sh @@ -135,7 +138,7 @@ wolfProvider will use the system default OpenSSL library installation unless cha The custom OpenSSL installation location may also need to be added to your library search path. On Linux, `LD_LIBRARY_PATH` is used: ``` -export LD_LIBRARY_PATH=/usr/local/ssl:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=/usr/local/ssl/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ``` To build then install wolfProvider, run: @@ -161,32 +164,16 @@ make check If you get an error like `error while loading shared libraries: libssl.so.3` then the library cannot be found. Use the `LD_LIBRARY_PATH` environment variable as described in the section above. -## Building on WinCE - -For full wolfProvider compatibility, ensure you have the following flags in your `user_settings.h` file for wolfCrypt: -``` -#define WOLFSSL_CMAC -#define WOLFSSL_KEY_GEN -#undef NO_SHA -#undef NO_DES -#define WOLFSSL_AES_COUNTER -#define HAVE_AESCCM -#define HAVE_AES_ECB -#define WOLFSSL_AES_DIRECT -#define WC_RSA_NO_PADDING -#define WOLFSSL_PUBLIC_MP -#define ECC_MIN_KEY_SZ=192 -``` - -Add wolfProvider flags to your `user_settings.h` file depending on which algorithms and features you want to use. You can find a list of wolfProvider user settings flags in the `user_settings.h` file in wolfProvider’s directory. +## Building on Windows (Visual Studio) -Build wcecompat, wolfCrypt and OpenSSL for Windows CE, and keep track of their paths. +wolfProvider includes a Visual Studio 2022 solution at `IDE/WINVS/wolfprovider.sln` that builds **`libwolfprov.dll`**, an OpenSSL 3.x provider backed by wolfSSL. The DLL name matters: `-provider libwolfprov` resolves to `libwolfprov.dll`. There is no `configure` step on Windows; wolfSSL is configured through a `user_settings.h`. -In the wolfProvider directory, open the sources file and change the OpenSSL, wolfCrypt, and `user_settings.h` paths to the directories you are using. You will need to update the paths in the INCLUDES and TARGETLIBS sections. +Prerequisites: -Load the wolfProvider project in Visual Studio. Include either `bench.c`, or `unit.h` and `unit.c` depending on if you want to run the benchmark or unit tests. +* Visual Studio 2022 with the C++ toolset (v143) and MASM (`ml64.exe`). +* Perl (for example Strawberry Perl), NASM, and git, to build OpenSSL. NASM is a separate install from Perl. -Build the project, and you will end up with a wolfProvider.exe executable. You can run this executable with ` --help` to see a full list of options. You may need to run it with the `--static` flag to use wolfProvider as a static provider. +The solution provides four x64 configurations. `DLL Release` and `DLL Debug` build the shipped provider (`libwolfprov.dll`); `Static Release` and `Static Debug` build `unit-test.exe`, which links wolfProvider statically to run the unit tests. The shipped provider is the DLL; a statically linked wolfProvider is instead registered as an OpenSSL built-in provider via `OSSL_PROVIDER_add_builtin()` (see the Loading wolfProvider chapter). wolfProvider, wolfSSL, and OpenSSL are expected to sit side by side; the paths are set in `wolfprovider.props` and can be overridden on the command line (for example `/p:wolfCryptDir=D:\wolfssl`). Both non-FIPS and FIPS wolfSSL builds are supported. ## Build Options (./configure Options) @@ -212,7 +199,10 @@ By default, wolfProvider only builds a shared library, with building of a static | --enable-usersettings | **Disabled** | Use your own user_settings.h and do not add Makefile CFLAGS | | --enable-dynamic | **Enabled** | Enable loading wolfProvider as a dynamic provider | | --enable-singlethreaded | **Disabled** | Enable wolfProvider single threaded | -| --enable-pqc | **Disabled** | Enable ML-KEM, ML-DSA and SLH-DSA (FIPS 203/204/205) | +| --enable-debug-silent | **Disabled** | With `--enable-debug`, compile debug logging in but keep it silent until enabled at runtime via WOLFPROV_LOG_LEVEL / WOLFPROV_LOG_COMPONENTS (has no effect without `--enable-debug`) | +| --enable-replace-default | **Disabled** | Compile wolfProvider with `-DWOLFPROV_REPLACE_DEFAULT` for replace-default mode. Making wolfProvider the default provider also requires building OpenSSL with wolfProvider's `provider_predefined.c` replacement; use `scripts/build-wolfprovider.sh --replace-default` for the complete setup | +| --enable-seed-src | **Disabled** | Enable the SEED-SRC entropy source with /dev/urandom caching for fork-safe entropy | +| --enable-pqc | **Disabled** | Enable ML-KEM, ML-DSA and SLH-DSA (FIPS 203/204/205). Requires wolfSSL master/v5.9.2+ and OpenSSL 3.6+ | | --enable-mlkem | **Disabled** | Enable ML-KEM (FIPS 203) only | | --enable-mldsa | **Disabled** | Enable ML-DSA (FIPS 204) only | | --enable-slhdsa | **Disabled** | Enable SLH-DSA (FIPS 205) only | @@ -227,7 +217,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure | Define | Description | | :------------------------------- | :----------------------------- | -| WOLFPROVIDER_USER_SETTINGS | Read user-specified defines from user_settings.h. | +| WOLFPROVIDER_USER_SETTINGS | Define this (in your build flags or user_settings.h) to have wolfProvider read user-specified defines from user_settings.h. Some source files currently also check the shorter name `WOLFPROV_USER_SETTINGS`. The separate `--enable-usersettings` configure option tells the build not to add its own Makefile CFLAGS; it does not define this macro. | | WOLFPROV_DEBUG | Output debug information | | WP_CHECK_FORCE_FAIL | Force failure checking for testing purposes | | WP_ALLOW_NON_FIPS | Allow certain non-FIPS algorithms in FIPS mode | @@ -256,6 +246,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure | WP_HAVE_GMAC | GMAC (Galois/Counter Mode Authentication) support | | WP_HAVE_HKDF | HKDF (HMAC-based Key Derivation Function) support | | WP_HAVE_HMAC | HMAC (Hash-based Message Authentication Code) support | +| WP_HAVE_KBKDF | KBKDF (Key-Based Key Derivation Function) support | | WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support | | WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) verification support | | WP_HAVE_MD5 | MD5 hash algorithm support | @@ -265,6 +256,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure | WP_HAVE_PBE | Password-Based Encryption support | | WP_HAVE_RANDOM | Random number generation support | | WP_HAVE_RSA | RSA encryption and signature support | +| WP_HAVE_SEED_SRC | SEED-SRC entropy source support | | WP_HAVE_SHA1 | SHA1 hash algorithm support | | WP_HAVE_SHA224 | SHA224 hash algorithm support | | WP_HAVE_SHA256 | SHA256 hash algorithm support | @@ -278,6 +270,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure | WP_HAVE_SHA512_224 | SHA512/224 hash algorithm support | | WP_HAVE_SHA512_256 | SHA512/256 hash algorithm support | | WP_HAVE_SHAKE_256 | SHAKE256 extendable output function support | +| WP_HAVE_SSHKDF | SSHKDF (SSH Key Derivation Function) support | | WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) post-quantum signature support | | WP_HAVE_TLS1_PRF | TLS1 Pseudo-Random Function support | | WP_HAVE_X25519 | X25519 elliptic curve support | diff --git a/wolfProvider/src/chapter04.md b/wolfProvider/src/chapter04.md index 99513ece..8937da3d 100644 --- a/wolfProvider/src/chapter04.md +++ b/wolfProvider/src/chapter04.md @@ -4,8 +4,10 @@ wolfProvider has been designed to work with FIPS 140-3 validated versions of wol Note that wolfCrypt FIPS libraries cannot be “switched” into non-FIPS mode. wolfCrypt FIPS and regular wolfCrypt are two separate source code packages. -When wolfProvider is compiled to use wolfCrypt FIPS, it will only include support and register provider callbacks for FIPS-validated algorithms, modes, and key sizes. If OpenSSL based applications call non-FIPS validated algorithms, execution may not enter wolfProvider and could be handled by the default OpenSSL provider or other registered provider providers, based on the OpenSSL configuration. +When wolfProvider is compiled to use wolfCrypt FIPS, it registers provider callbacks for the algorithms supplied by the wolfCrypt FIPS module. Applications targeting FIPS compliance must restrict their usage to the approved algorithms, modes, and key sizes listed in the module's Security Policy; some registered modes may fall outside the validated set and must not be relied on in a FIPS-compliant deployment. If OpenSSL based applications call non-FIPS validated algorithms, execution may not enter wolfProvider and could be handled by the default OpenSSL provider or other registered providers, based on the OpenSSL configuration. **NOTE** : If targeting FIPS compliance, and non-wolfCrypt FIPS algorithms are called from a different provider, those algorithms are outside the scope of both wolfProvider and wolfCrypt FIPS and may not be FIPS validated. +For broader FIPS coverage, wolfProvider is typically built in replace-default mode, which makes wolfProvider OpenSSL's default provider and reduces the risk of applications silently falling back to non-FIPS algorithms in the default provider. Enabling this requires both the `--enable-replace-default` build option and building OpenSSL with wolfProvider's provider replacement; `scripts/build-wolfprovider.sh --replace-default` performs both steps. It does not by itself guarantee system-wide FIPS compliance, as explicitly loaded providers and direct low-level calls remain outside its control. See the [Loading wolfProvider](chapter07.md) chapter for replace-default mode, and the wolfProvider FIPS Integration Guide (`docs/FIPS_INTEGRATION_GUIDE.md` in the wolfProvider package) for the FIPS baseline verification and production FIPS build workflow, including the supported wolfCrypt FIPS module generations (for example v5, v6, and v7) and FIPS Ready bundles. + For more information on using wolfCrypt FIPS (140-2 / 140-3), contact wolfSSL at facts@wolfssl.com. diff --git a/wolfProvider/src/chapter05.md b/wolfProvider/src/chapter05.md index 25f709a1..ede79147 100644 --- a/wolfProvider/src/chapter05.md +++ b/wolfProvider/src/chapter05.md @@ -9,65 +9,80 @@ If not using Autoconf/configure, define `WOLFPROV_DEBUG` when compiling the wolf ## Controlling Logging Levels -wolfProvider supports the following logging levels. These are defined in the “include/wolfprovider/wp_logging.h” header file as part of the wolfProvider_LogType enum: +wolfProvider supports the following logging levels. These are defined as preprocessor macros in the `include/wolfprovider/wp_logging.h` header file: -| Log Enum | Description | Log Enum Value | +| Log Enum | Description | Log Enum Value | | -------------- | --------------- |--------------------- | -| WP_LOG_ERROR | Logs errors | 0x0001 | -| WP_LOG_ENTER | Logs when entering functions | 0x0002 | -| WP_LOG_LEAVE | Logs when leaving functions | 0x0004 | -| WP_LOG_INFO | Logs informative messages | 0x0008 | -| WP_LOG_VERBOSE | Verbose logs, including encrypted/decrypted/digested data | 0x0010 | -| WP_LOG_LEVEL_DEFAULT | Default log level, all except verbose level | WP_LOG_ERROR | WP_LOG_ENTER | WP_LOG_LEAVE | WP_LOG_INFO | -WP_LOG_LEVEL_ALL | All log levels are enabled | WP_LOG_ERROR | WP_LOG_ENTER | WP_LOG_LEAVE | WP_LOG_INFO | WP_LOG_VERBOSE | +| WP_LOG_LEVEL_ERROR | Logs errors | 0x0001 | +| WP_LOG_LEVEL_ENTER | Logs when entering functions | 0x0002 | +| WP_LOG_LEVEL_LEAVE | Logs when leaving functions | 0x0004 | +| WP_LOG_LEVEL_INFO | Logs informative messages | 0x0008 | +| WP_LOG_LEVEL_VERBOSE | Verbose logs, including encrypted/decrypted/digested data | 0x0010 | +| WP_LOG_LEVEL_DEBUG | Logs debug-level detail, including wolfSSL return codes | 0x0020 | +| WP_LOG_LEVEL_TRACE | Logs trace-level ultra-detailed information | 0x0040 | +| WP_LOG_LEVEL_DEFAULT | Default log level | WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_LEAVE | WP_LOG_LEVEL_INFO | +| WP_LOG_LEVEL_ALL | All log levels are enabled | WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_ENTER | WP_LOG_LEVEL_LEAVE | WP_LOG_LEVEL_INFO | WP_LOG_LEVEL_VERBOSE | WP_LOG_LEVEL_DEBUG | WP_LOG_LEVEL_TRACE | -The default wolfProvider logging level includes `WP_LOG_ERROR`, `WP_LOG_ENTER`, `WP_LOG_LEAVE`, and `WP_LOG_INFO`. This includes all log levels except verbose logs (`WP_LOG_VERBOSE`). +The default wolfProvider logging level (`WP_LOG_LEVEL_DEFAULT`) includes `WP_LOG_LEVEL_ERROR`, `WP_LOG_LEVEL_LEAVE`, and `WP_LOG_LEVEL_INFO`. + +The levels and components that can be enabled at runtime are bounded by the compile-time filters `WOLFPROV_LOG_LEVEL_FILTER` and `WOLFPROV_LOG_COMPONENTS_FILTER` (defined in `wp_logging.h`, defaulting to `WP_LOG_LEVEL_DEFAULT` and `WP_LOG_COMP_DEFAULT`). A level or component excluded by these filters at build time cannot be turned on at runtime; to enable, for example, `WP_LOG_LEVEL_DEBUG` or `WP_LOG_LEVEL_VERBOSE`, widen `WOLFPROV_LOG_LEVEL_FILTER` at compile time. Log levels can be controlled using the `wolfProv_SetLogLevel(int mask)`. For example, to turn on only error and informative logs: ``` +#include #include -ret = wolfProv_SetLogLevel(WP_LOG_ERROR | WP_LOG_INFO); -if (ret != 0) { - printf(“Failed to set logging level\n”); +int main(void) +{ + int ret = wolfProv_SetLogLevel(WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_INFO); + if (ret != 0) { + printf("Failed to set logging level\n"); + } + return 0; } ``` ## Controlling Component Logging -wolfProvider allows logging on a per-component basis. Components are defined in the wolfProvider_LogComponents enum in `include/wolfprovider/wp_logging.h`: +wolfProvider allows logging on a per-component basis. Components are defined as preprocessor macros in `include/wolfprovider/wp_logging.h`: | Log Component Enum | Description | Component Enum Value | | ------------------------------ | --------------- | -------------------------------- | -| WP_LOG_RNG | Random number generation | 0x0001 | -| WP_LOG_DIGEST | Digests (SHA-1/2/3) | 0x0002 | -| WP_LOG_MAC | MAC functions (HMAC, CMAC) | 0x0004 | -| WP_LOG_CIPHER | Ciphers (AES, 3DES) | 0x0008 | -| WP_LOG_PK | Public Key Algorithms (RSA, ECC) | 0x0010 | -| WP_LOG_KE | Key Agreement Algorithms (DH, ECDH) | 0x0020 | -| WP_LOG_KDF | Password Based Key Derivation Algorithms | 0x0040 | -| WP_LOG_PROVIDER | All provider specific logs | 0x0080 | -| WP_LOG_COMPONENTS_ALL | Log all components | WP_LOG_RNG | WP_LOG_DIGEST | WP_LOG_MAC | WP_LOG_CIPHER | WP_LOG_PK | WP_LOG_KE | WP_LOG_KDF | WP_LOG_PROVIDER | -| WP_LOG_COMPONENTS_DEFAULT | Default components logged (all). | WP_LOG_COMPONENTS_ALL | +| WP_LOG_COMP_RNG | Random number generation | 0x0001 | +| WP_LOG_COMP_DIGEST | Digests (SHA-1/2/3) | 0x0002 | +| WP_LOG_COMP_MAC | MAC functions (HMAC, CMAC) | 0x0004 | +| WP_LOG_COMP_CIPHER | Ciphers (AES, 3DES) | 0x0008 | +| WP_LOG_COMP_PK | Public Key Algorithms (RSA, ECC) | 0x0010 | +| WP_LOG_COMP_KE | Key Agreement Algorithms (DH, ECDH) | 0x0020 | +| WP_LOG_COMP_KDF | Key Derivation Algorithms | 0x0040 | +| WP_LOG_COMP_PROVIDER | All provider specific logs | 0x0080 | +| WP_LOG_COMP_ALL | Log all components | all components below | +| WP_LOG_COMP_DEFAULT | Default components logged (all) | WP_LOG_COMP_ALL | +Finer-grained per-algorithm components are also available for targeted logging, including `WP_LOG_COMP_RSA`, `WP_LOG_COMP_ECC`, `WP_LOG_COMP_DH`, `WP_LOG_COMP_AES`, `WP_LOG_COMP_SHA`, `WP_LOG_COMP_HMAC`, `WP_LOG_COMP_HKDF`, `WP_LOG_COMP_SSHKDF`, `WP_LOG_COMP_PQC`, and others. See `wp_logging.h` for the full list. -The default wolfProvider logging configuration logs all components (`WP_LOG_COMPONENTS_DEFAULT`). +The default wolfProvider logging configuration logs all components (`WP_LOG_COMP_DEFAULT`). Components logged can be controlled using the `wolfProv_SetLogComponents(int mask)`. For example, to turn on logging only for the Digest and Cipher algorithms: ``` +#include #include -ret = wolfProv_SetLogComponents(WP_LOG_DIGEST | WP_LOG_CIPHER); -if (ret != 0) { - printf(“Failed to set log components\n”); +int main(void) +{ + int ret = wolfProv_SetLogComponents(WP_LOG_COMP_DIGEST | WP_LOG_COMP_CIPHER); + if (ret != 0) { + printf("Failed to set log components\n"); + } + return 0; } ``` ## Setting a Custom Logging Callback By default wolfProvider outputs debug log messages using **fprintf()** to **stderr**. -Applications that want to have more control over how or where log messages are output can write and register a custom logging callback with wolfProvider. The logging callback should match the prototype of wolfProvider_Logging_cb in `include/wolfprovider/wp_logging.h`: +Applications that want to have more control over how or where log messages are output can write and register a custom logging callback with wolfProvider. The logging callback should match the prototype of wolfProv_Logging_cb in `include/wolfprovider/wp_logging.h`: ``` /** * wolfProvider logging callback. @@ -75,28 +90,32 @@ Applications that want to have more control over how or where log messages are o * component - [IN] - Component that log message is coming from * logMessage - [IN] - Log message */ -typedef void (* wolfProvider_Logging_cb )(const int logLevel, +typedef void (* wolfProv_Logging_cb )(const int logLevel, const int component, const char *const logMessage); ``` The callback can then be registered with wolfProvider using the `wolfProv_SetLoggingCb(wolfProv_Logging_cb logf)`. For example: ``` -void customLogCallback (const int logLevel, const int component, -const char* const logMessage) +#include +#include + +void customLogCallback(const int logLevel, const int component, + const char* const logMessage) { (void)logLevel; (void)component; - fprintf(stderr, “wolfProvider log message: %d\n”, logMessage); + fprintf(stderr, "wolfProvider log message: %s\n", logMessage); } -int main (void) +int main(void) { int ret; -... - ret = wolfProv_SetLoggingCb((void(*)(void))my_Logging_cb); + + ret = wolfProv_SetLoggingCb(customLogCallback); if (ret != 0) { /* failed to set logging callback */ } -... + + return 0; } ``` diff --git a/wolfProvider/src/chapter06.md b/wolfProvider/src/chapter06.md index 109f8ee9..bfcddbb7 100644 --- a/wolfProvider/src/chapter06.md +++ b/wolfProvider/src/chapter06.md @@ -2,9 +2,23 @@ wolfProvider has been designed to leverage the portability of the associated wolfCrypt and OpenSSL libraries. +## Supported Platforms + +wolfProvider is cross-platform and builds on the major platforms supported by wolfSSL and OpenSSL, including: + +* Linux and other *nix-like systems, built with the autoconf system (see [Building wolfProvider](chapter03.md)) +* macOS +* Windows, using the Visual Studio 2022 solution that builds `libwolfprov.dll` (see [Building wolfProvider](chapter03.md)) +* Android, using the build scripts under `IDE/Android` +* Apple platforms, using the framework build scripts under `IDE/XCODE` + +Both FIPS and non-FIPS builds are supported on Linux, macOS, Windows, and Android (the Android build supports FIPS Ready via its `USE_FIPS` option). + ## Threading -wolfProvider is thread safe and uses mutex locking mechanisms from wolfCrypt (`wc_LockMutex()`, `wc_UnLockMutex()`) where necessary. wolfCrypt has mutex operations abstracted for supported platforms. +wolfProvider's cryptographic operations are thread safe and use mutex locking mechanisms from wolfCrypt (`wc_LockMutex()`, `wc_UnLockMutex()`) where necessary. wolfCrypt has mutex operations abstracted for supported platforms. + +The global configuration setters are an exception: the logging setters (`wolfProv_SetLogLevel()`, `wolfProv_SetLogComponents()`, `wolfProv_SetLoggingCb()`) and the FIPS-check state update process-global state without internal synchronization. Configure these once during initialization, before other threads use the provider. ## Dynamic Memory Usage diff --git a/wolfProvider/src/chapter07.md b/wolfProvider/src/chapter07.md index 3bbe0ae9..eae4e01e 100644 --- a/wolfProvider/src/chapter07.md +++ b/wolfProvider/src/chapter07.md @@ -21,19 +21,22 @@ Alternatively to using an OpenSSL config file, applications can explicitly initi { 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 + prov = OSSL_PROVIDER_load(NULL, "libwolfprov"); + if (prov != NULL) { + if (OSSL_PROVIDER_get_params(prov, request)) + printf("Provider 'libwolfprov' buildinfo: %s\n", build); + else + ERR_print_errors_fp(stderr); + OSSL_PROVIDER_unload(prov); + } + else { ERR_print_errors_fp(stderr); + } +``` - if (OSSL_PROVIDER_self_test(prov) == 0) - printf("Provider selftest failed\n"); - else - printf("Provider selftest passed\n"); +Loading a provider makes it available; it does not by itself force every operation to use it. To require wolfProvider for a given operation, fetch algorithms with a property query using wolfProvider's registered property `"provider=wolfprov"` (for a FIPS build, `"provider=wolfprov,fips=yes"`) via the `EVP_*_fetch()` APIs. Note that `libwolfprov` is the module name used to *load* the provider, while `provider=wolfprov` is the property used to *select* its algorithms. - OSSL_PROVIDER_unload(prov); -``` +wolfProvider does not currently implement a provider self-test dispatch (`OSSL_FUNC_PROVIDER_SELF_TEST`). `OSSL_PROVIDER_self_test()` on the loaded provider therefore does not run a wolfProvider self-test and should not be relied on as one. ## Loading wolfProvider from an OpenSSL Configuration File @@ -54,8 +57,35 @@ activate = 1 ## wolfProvider Static Entrypoint -When wolfProvider is used as a static library, applications can call the following entry point to load wolfProvider: +When wolfProvider is built as a static library, it is loaded as an OpenSSL built-in provider rather than as a dynamically loaded module. The application links against static wolfProvider (and its wolfSSL and OpenSSL dependencies), registers wolfProvider's entry point with `OSSL_PROVIDER_add_builtin()`, and then loads it by name: ``` -#include -wolfssl_provider_init(const OSSL_CORE_HANDLE* handle, const OSSL_DISPATCH* in, const OSSL_DISPATCH** out, void** provCtx); +#include +#include + +int load_wolfprovider(void) +{ + OSSL_PROVIDER *prov; + + if (OSSL_PROVIDER_add_builtin(NULL, "libwolfprov", + wolfssl_provider_init) != 1) { + return -1; + } + prov = OSSL_PROVIDER_load(NULL, "libwolfprov"); + if (prov == NULL) { + return -1; + } + /* use prov, then call OSSL_PROVIDER_unload(prov) when finished */ + return 0; +} ``` +The entry point `wolfssl_provider_init()` is declared in `wolfprovider/wp_wolfprov.h`; it is passed to `OSSL_PROVIDER_add_builtin()` and is not called directly by the application. + +## Replace-Default Mode + +wolfProvider can be built to *replace* OpenSSL's default provider rather than loading alongside it. In replace-default mode, OpenSSL requests for the built-in `default` and `fips` providers resolve to wolfProvider (the `libwolfprov` module), so applications use wolfSSL cryptography with no code or configuration changes. (The `legacy` provider is redirected only in static-legacy builds.) OpenSSL's `base` provider, which offers encoders, decoders, and related non-cryptographic services, still loads normally. + +Enabling replace-default has two parts. The `--enable-replace-default` configure option (or defining `-DWOLFPROV_REPLACE_DEFAULT` in `CFLAGS`, useful for Yocto-style builds) builds wolfProvider's replacement default provider; it does not by itself patch or rebuild OpenSSL. Making wolfProvider the default also requires building OpenSSL with wolfProvider's `provider_predefined.c` replacement, so that OpenSSL's built-in `default`/`fips` entries load wolfProvider. The `scripts/build-wolfprovider.sh --replace-default` path performs both steps; see the wolfProvider Integration Guide (`docs/INTEGRATION_GUIDE.md`) for the authoritative procedure. + +In replace-default mode no `OPENSSL_CONF` or `OPENSSL_MODULES` configuration is required, since wolfProvider is already the default provider. The `scripts/env-setup` helper detects this mode automatically and skips setting those variables. + +Replace-default mode is useful for FIPS deployments: it removes the OpenSSL default-provider fallback path, reducing the risk that an application inadvertently uses non-FIPS algorithms. It does not by itself guarantee system-wide FIPS compliance, as explicitly loaded providers and direct low-level calls remain outside its control. See the FIPS 140-3 Support chapter and the wolfProvider FIPS Integration Guide for details. diff --git a/wolfProvider/src/chapter08.md b/wolfProvider/src/chapter08.md index 990edad8..e25b5d10 100644 --- a/wolfProvider/src/chapter08.md +++ b/wolfProvider/src/chapter08.md @@ -4,8 +4,8 @@ wolfProvider is composed of the following source files, all located under the "s | Source File | Description | | --------------- | ---------------- | -| wp_wolfprov.c | Contains library entry points. Calls OpenSSL IMPLEMENT_DYNAMIC_BIND_FN for dynamic loading of the library using the OpenSSL provider framework. Also includes static entry points when compiled and used as a static library. | -| wp_internal.c | Includes wolfprovider_bind() function, which handles registration of provider algorithm callbacks. Also includes other wolfprovider internal functionality. | +| wp_wolfprov.c | Contains the library entry points `OSSL_provider_init()` and `wolfssl_provider_init()`, the provider dispatch table, provider parameter handling, and the `OSSL_ALGORITHM` arrays that register wolfProvider's algorithm implementations with OpenSSL. Also serves as the static entry point when compiled and used as a static library. | +| wp_internal.c | wolfProvider internal helpers, including entropy/RNG and CAST self-test mutex setup, provider-context RNG access and locking utilities, and decoder-skip logic. | | wp_logging.c | wolfProvider logging framework and function implementations. | | wp_aes_aead.c | wolfProvider AES-AEAD (Authenticated Encryption with Associated Data) implementation. | | wp_aes_block.c | wolfProvider AES-ECB and AES-CBC implementation. | @@ -19,6 +19,7 @@ wolfProvider is composed of the following source files, all located under the "s | wp_dh_kmgmt.c | wolfProvider DH key management implementation. | | wp_digests.c | wolfProvider message digest implementations (SHA-1, SHA-2, SHA-3, ...). | | wp_drbg.c | wolfProvider DRBG (Deterministic Random Bit Generator) implementation. | +| wp_seed_src.c | wolfProvider SEED-SRC entropy source with /dev/urandom caching for fork-safe entropy. | | wp_ecc_kmgmt.c | wolfProvider ECC key management implementation. | | wp_ecdh_exch.c | wolfProvider ECDH key exchange implementation. | | wp_ecdsa_sig.c | wolfProvider ECDSA signature implementation. | @@ -38,10 +39,20 @@ wolfProvider is composed of the following source files, all located under the "s | wp_mac_sig.c | wolfProvider MAC signature implementation. | | wp_params.c | wolfProvider parameter handling implementation. | | wp_pbkdf2.c | wolfProvider PBKDF2 (Password-Based Key Derivation Function 2) implementation. | +| wp_sshkdf.c | wolfProvider SSHKDF (SSH Key Derivation Function) implementation. | | wp_rsa_asym.c | wolfProvider RSA asymmetric encryption implementation. | | wp_rsa_kem.c | wolfProvider RSA KEM (Key Encapsulation Mechanism) implementation. | | wp_rsa_kmgmt.c | wolfProvider RSA key management implementation. | | wp_rsa_sig.c | wolfProvider RSA signature implementation. | +| wp_mlkem_kmgmt.c | wolfProvider ML-KEM (FIPS 203) key management implementation. | +| wp_mlkem_kem.c | wolfProvider ML-KEM (FIPS 203) key encapsulation implementation. | +| wp_mlx_kmgmt.c | wolfProvider hybrid ML-KEM plus ECDH key management implementation. | +| wp_mlx_kem.c | wolfProvider hybrid ML-KEM plus ECDH key encapsulation implementation. | +| wp_mldsa_kmgmt.c | wolfProvider ML-DSA (FIPS 204) key management implementation. | +| wp_mldsa_sig.c | wolfProvider ML-DSA (FIPS 204) signature implementation. | +| wp_slhdsa_kmgmt.c | wolfProvider SLH-DSA (FIPS 205) key management implementation. | +| wp_slhdsa_sig.c | wolfProvider SLH-DSA (FIPS 205) signature implementation. | +| wp_lms.c | wolfProvider LMS (RFC 8554) verification implementation. | | wp_tls1_prf.c | wolfProvider TLS 1.0 PRF implementation. | | wp_tls_capa.c | wolfProvider TLS capabilities implementation. | @@ -76,15 +87,7 @@ The wolfProvider dispatch table contains several key functions that handle diffe ### wolfprov_teardown -The `wolfprov_teardown()` function is responsible for cleaning up wolfProvider when it is unloaded by OpenSSL. It performs the following cleanup tasks: - -- Frees allocated provider context and resources -- Cleans up any remaining algorithm implementations -- Removes registered callbacks and handlers -- Ensures proper memory deallocation to prevent memory leaks -- Resets any global state maintained by the provider - -This function is called automatically by OpenSSL when the provider is being unloaded, ensuring that all resources are properly released. +The `wolfprov_teardown()` function is called automatically by OpenSSL when the provider is unloaded. It frees the provider context (`wolfssl_prov_ctx_free()`) and calls `wolfCrypt_Cleanup()` to release wolfCrypt's resources. ### wolfprov_gettable_params @@ -108,19 +111,16 @@ The `wolfprov_get_params()` function retrieves specific parameter values from th - Provides access to provider configuration and state information - Supports both simple parameters and complex parameter structures -Common parameters that can be retrieved include provider version, supported algorithms, FIPS mode status, and other configuration details. +wolfProvider implements four provider parameters: the provider name (`OSSL_PROV_PARAM_NAME`), version (`OSSL_PROV_PARAM_VERSION`), build information (`OSSL_PROV_PARAM_BUILDINFO`), and running status (`OSSL_PROV_PARAM_STATUS`). ### wolfssl_prov_get_capabilities -The `wolfssl_prov_get_capabilities()` function reports the cryptographic capabilities of wolfProvider to OpenSSL. It provides capability information which: +The `wolfssl_prov_get_capabilities()` function reports wolfProvider's TLS-related capabilities to OpenSSL. It provides: -- Returns information about supported algorithms and operations -- Provides details about algorithm parameters and constraints -- Indicates FIPS compliance and validation status -- Reports performance characteristics and limitations -- Enables OpenSSL to make informed decisions about algorithm selection +- The supported TLS key-exchange groups (the `TLS-GROUP` capability), including classical and, when enabled, post-quantum and hybrid groups +- When ML-DSA is enabled, the supported TLS signature algorithms (the `TLS-SIGALG` capability) -The capabilities information helps OpenSSL determine when to use wolfProvider algorithms and how to configure them appropriately for different use cases. +The capabilities information helps OpenSSL negotiate the key-exchange groups and signature algorithms that wolfProvider supports during a TLS handshake. ### wolfprov_query diff --git a/wolfProvider/src/chapter09.md b/wolfProvider/src/chapter09.md index 225ffbde..ddab0202 100644 --- a/wolfProvider/src/chapter09.md +++ b/wolfProvider/src/chapter09.md @@ -9,57 +9,56 @@ wolfSSL has tested wolfProvider with numerous open source projects through autom The following Open Source Projects (OSPs) have been tested and verified to work with wolfProvider: ### Network and Web Technologies -* cURL - Command line tool for transferring data with URLs +* cURL - Command line tool and library for transferring data with URLs * gRPC - High-performance RPC framework -* libwebsockets - Lightweight C library for websockets +* libwebsockets - Lightweight C library for WebSockets * Nginx - High-performance HTTP server and reverse proxy +* Nginx (PQC) - Nginx built with post-quantum TLS key exchange groups * Qt5 Network - Qt networking module +* libnice - GLib ICE implementation for peer-to-peer and WebRTC +* iPerf - Network performance measurement tool ### Security and Authentication * OpenSSH - Secure shell implementation -* libssh2 - SSH2 library +* libssh2 - SSH2 client library * libfido2 - FIDO2 library for WebAuthn * OpenSC - Smart card tools and middleware * pam-pkcs11 - PAM module for PKCS#11 * OpenVPN - VPN solution -* Stunnel - SSL wrapper for network services +* Stunnel - SSL/TLS wrapper for network services +* hostap (wpa_supplicant / hostapd) - Wi-Fi authentication (EAP, WPA) +* Kerberos 5 (krb5) - Network authentication protocol +* libcryptsetup - LUKS disk encryption +* Git over SSH - Git transport over SSH ### System and Network Tools * systemd - System and service manager * tcpdump - Network packet analyzer * rsync - File synchronization utility * tnftp - Enhanced FTP client -* iperf - Network performance measurement tool -* IPMItool - IPMI management tool * PPP - Point-to-Point Protocol implementation +* Socat - Multipurpose relay for bidirectional data transfer +* librelp - Reliable Event Logging Protocol library +* Net-SNMP - Simple Network Management Protocol implementation ### Directory and Identity Services * OpenLDAP - Lightweight Directory Access Protocol * SSSD - System Security Services Daemon -* Net-SNMP - Network management protocol implementation +* BIND 9 - DNS server and resolver ### Cryptography and PKI -* cjose - C library for JWT -* libeac3 - Electronic Authentication Components -* libhashkit2 - Consistent hashing library -* liboauth2 - OAuth2 library +* cjose - C library for JOSE/JWT +* libeac3 - Extended Access Control library +* libhashkit2 - Consistent hashing library (libmemcached) +* liboauth2 - OAuth 2.0 library * libtss2 - TPM2 Software Stack * tpm2-tools - TPM2 tools * xmlsec - XML Security library * sscep - SCEP client implementation -### Development and Testing -* Asan - Address Sanitizer testing -* Codespell - Spell checker for source code -* Multi-Compiler - Multi-compiler testing - ### Remote Access and Display * x11vnc - VNC server for X11 -* python3-ntp - Python NTP library - -### Other Utilities -* Socat - Multipurpose relay for bidirectional data transfer -* Simple - Simple test applications +* python3-ntp - Python NTP implementation ## General Setup Most of these projects require similar setup steps: @@ -87,11 +86,15 @@ Further, wolfProvider gives some ability to determine if the library is actually If the project being used is included in the list of tested open source project's then the testing scripts can be referenced. These can be found in the [wolfssl/wolfProvider](https://github.com/wolfSSL/wolfProvider) repository on GitHub under .github/workflows/. ## Testing and Validation -All of the above referenced open source project's are continuously tested in the wolfProvider CI/CD pipeline with: +All of the above referenced open source projects are continuously tested in the wolfProvider CI/CD pipeline. Testing spans: + +* A range of OpenSSL 3.x releases (from 3.0.6 through the latest 3.x release) +* wolfSSL master plus multiple stable releases (for example v5.9.1 and v5.8.4) +* Both standard and replace-default provider modes +* FIPS and non-FIPS builds (FIPS additionally exercised by dedicated FIPS and FIPS-Ready GitHub Actions workflows) +* Force-failure testing (`WOLFPROV_FORCE_FAIL=1`) to confirm wolfProvider crypto is actually exercised +* Address and undefined-behavior sanitizers, static analysis, and post-quantum known-answer tests (KATs) -* OpenSSL version 3.5.0 -* wolfSSL with both master and stable releases -* Force failure testing to ensure proper error handling -* FIPS testing is also done through a Jenkins pipeline +wolfProvider currently maintains over 40 open source project integrations across more than 60 GitHub Actions workflows, split between a fast per-pull-request tier and a broader nightly tier. This comprehensive testing ensures that wolfProvider maintains compatibility with a wide range of open source projects and their various use cases. diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md index 267b00ae..54cbd703 100644 --- a/wolfProvider/src/chapter11.md +++ b/wolfProvider/src/chapter11.md @@ -29,11 +29,11 @@ pure and pre-hash signing, verification, context strings, and key encoding. SLH-DSA supports key generation, pure signing, verification, context strings, and key encoding. LMS supports public-key import and one-shot signature verification only. Private-key import, signing, and key generation are not -exposed because OpenSSL 3.6's provider ABI defines LMS as verification-only: it -advertises no signing, key-generation, or private-key import entry points for -wolfProvider to implement, even though wolfCrypt itself supports them. This -also avoids exposing stateful private-key operations through an interface that -cannot enforce LMS leaf-use (one-time signature) state. +exposed. This follows OpenSSL's LMS key-type contract, which is +verification-only, and is also a deliberate wolfProvider design choice: it +avoids exposing stateful LMS private-key operations through an interface that +cannot enforce LMS leaf-use (one-time signature) state, even though wolfCrypt +itself supports LMS signing and key generation. ## Provider Architecture @@ -132,10 +132,12 @@ for configuration and benchmark details. ## Building +Post-quantum algorithms require OpenSSL 3.6 or later. Set `OPENSSL_TAG` to the latest patched OpenSSL 3.6.x release (not 3.6.0, which has known vulnerabilities) so the build does not use an outdated default: + The build script can configure OpenSSL, wolfSSL, and wolfProvider together: ```sh -./scripts/build-wolfprovider.sh --enable-pqc +OPENSSL_TAG=openssl-3.6.2 ./scripts/build-wolfprovider.sh --enable-pqc ``` `--enable-pqc` enables ML-KEM, ML-DSA and SLH-DSA. LMS remains an independent @@ -152,13 +154,16 @@ For a manual build, configure wolfSSL with the matching algorithm options, then configure wolfProvider: ```sh -# Add the required options to the normal wolfSSL configuration. +# In the wolfSSL source directory, add the required options to the +# normal wolfSSL configuration. +cd /path/to/wolfssl ./configure --enable-mlkem --enable-mldsa --enable-slhdsa=yes,sha2 \ --enable-lms=verify-only,sha256-192,shake256 make sudo make install -# Configure wolfProvider against OpenSSL 3.6 or later. +# In the wolfProvider source directory, configure against OpenSSL 3.6 or later. +cd /path/to/wolfProvider ./configure --enable-pqc --enable-lms \ --with-openssl=/path/to/openssl \ --with-wolfssl=/path/to/wolfssl @@ -181,7 +186,7 @@ mode. It makes wolfProvider the OpenSSL default and prevents operations from silently falling back to OpenSSL's built-in provider: ```sh -./scripts/build-wolfprovider.sh --replace-default \ +OPENSSL_TAG=openssl-3.6.2 ./scripts/build-wolfprovider.sh --replace-default \ --enable-pqc --enable-lms ``` @@ -205,10 +210,11 @@ If wolfProvider was installed outside OpenSSL's module search path, also set export OPENSSL_MODULES=/path/to/wolfprovider/lib ``` -Run commands with the configuration active. This verifies the algorithms -advertised by the configured provider; it does not guarantee that unrelated -operations cannot be selected from OpenSSL's default provider in standard -provider mode: +Run commands with the configuration active. Because this configuration +activates only `libwolfprov`, OpenSSL does not implicitly activate its own +default provider, so operations that wolfProvider does not support will fail +rather than silently falling back, unless an application also activates the +default provider (or unless replace-default mode is used): ```sh OPENSSL_CONF=/path/to/wolfProvider/provider.conf \ @@ -228,10 +234,12 @@ families through the OpenSSL EVP API: - ML-DSA-65 key generation, signing, and verification - SLH-DSA-SHA2-128f key generation, signing, and verification -The example is built and run by `make check` when wolfProvider is configured -with any PQC family. Compile-time guards run only the enabled families, so the -same source also demonstrates ML-KEM-only, ML-DSA-only, and SLH-DSA-only -builds. After building, it can also be run directly from the wolfProvider root: +The example is built (as a `noinst_PROGRAMS` target, not an Automake test) +when wolfProvider is configured with any PQC family; wolfProvider's CI runs it +as a separate step rather than as part of `make check`. Compile-time guards run +only the enabled families, so the same source also demonstrates ML-KEM-only, +ML-DSA-only, and SLH-DSA-only builds. After building, it can be run directly +from the wolfProvider root: ```sh ./examples/pqc_openssl_example @@ -295,6 +303,14 @@ of a complete cryptographic module under FIPS 140-3, so using an open source or FIPS-ready wolfSSL build does not by itself create a FIPS-validated application. +Validated FIPS and FIPS-Ready builds currently reject PQC (ML-KEM, ML-DSA, +SLH-DSA) and LMS: combining a FIPS or FIPS-Ready wolfSSL build with these +algorithms is not yet supported, pending the module-specific CAST integration. +Use PQC and LMS with non-FIPS wolfSSL builds only until that integration is +available. This restriction is enforced by `scripts/build-wolfprovider.sh`; a +hand-run `./configure` does not currently reject the combination, so use the +build script (or avoid the combination) for FIPS builds. + PQC has several independent test layers: - Unit and example tests cover key generation, import/export, encoding, From 46c4e838f2cdf00c5cbdb107bc66f2eb9215771e Mon Sep 17 00:00:00 2001 From: Aidan Garske Date: Fri, 28 Aug 2026 17:26:48 -0700 Subject: [PATCH 2/2] Add a first-pass Japanese translation of the wolfProvider manual updates --- wolfProvider/Makefile | 5 +- wolfProvider/mkdocs-ja.yml | 5 +- wolfProvider/src-ja/chapter01.md | 6 +- wolfProvider/src-ja/chapter02.md | 11 +- wolfProvider/src-ja/chapter03.md | 32 +++- wolfProvider/src-ja/chapter04.md | 8 +- wolfProvider/src-ja/chapter05.md | 12 +- wolfProvider/src-ja/chapter06.md | 12 ++ wolfProvider/src-ja/chapter07.md | 17 ++ wolfProvider/src-ja/chapter08.md | 11 ++ wolfProvider/src-ja/chapter09.md | 73 ++++---- wolfProvider/src-ja/chapter11.md | 281 +++++++++++++++++++++++++++++++ 12 files changed, 417 insertions(+), 56 deletions(-) create mode 100644 wolfProvider/src-ja/chapter11.md diff --git a/wolfProvider/Makefile b/wolfProvider/Makefile index 98c59b9e..0bc8ecf5 100644 --- a/wolfProvider/Makefile +++ b/wolfProvider/Makefile @@ -12,14 +12,13 @@ SOURCES = chapter01.md \ chapter07.md \ chapter08.md \ chapter09.md \ - chapter10.md + chapter10.md \ + chapter11.md ifeq ($(DOC_LANG),JA) PDF = wolfProvider-Manual-jp.pdf else PDF = wolfProvider-Manual.pdf - # chapter11 (Post-Quantum) is English-only until it is translated. - SOURCES += chapter11.md endif .PHONY: html-prep diff --git a/wolfProvider/mkdocs-ja.yml b/wolfProvider/mkdocs-ja.yml index 98dcfeef..6e65b19f 100644 --- a/wolfProvider/mkdocs-ja.yml +++ b/wolfProvider/mkdocs-ja.yml @@ -2,18 +2,19 @@ site_name: wolfProvider マニュアル site_url: https://wolfssl.com/ docs_dir: build/html/ site_dir: html/ -copyright: Copyright © 2025 wolfSSL Inc. +copyright: Copyright © 2026 wolfSSL Inc. nav: - "1. イントロダクション": index.md - "2. OpenSSLとの互換性": chapter02.md - "3. wolfProviderのビルド": chapter03.md - - "4. FIPS 140-2のサポート": chapter04.md + - "4. FIPS 140-3のサポート": chapter04.md - "5. ログ出力": chapter05.md - "6. 移植性": chapter06.md - "7. wolfProviderのロード": chapter07.md - "8. wolfProviderの設計": chapter08.md - "9. その他のオープンソースソフトウェアとの統合に関する注意事項": chapter09.md - "10. サポートとOpenSSLバージョン追加": chapter10.md + - "11. ポスト量子暗号": chapter11.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfProvider/src-ja/chapter01.md b/wolfProvider/src-ja/chapter01.md index 127248f2..d5b5450c 100644 --- a/wolfProvider/src-ja/chapter01.md +++ b/wolfProvider/src-ja/chapter01.md @@ -8,7 +8,7 @@ wolfProviderは、wolfSSL(libwolfssl)とOpenSSLにリンクする個別のスタ wolfProviderは、wolfCryptネイティブAPIを内部的にラップするOpenSSLエンジンです。 wolfProviderの概要図、そしてアプリケーションやOpenSSLとどのように関連しているかを下の図1に示します。 -wolfProviderの設計とアーキテクチャの詳細については、[wolfProviderの設計](chapter09.md) の章をご覧ください。 +wolfProviderの設計とアーキテクチャの詳細については、[wolfProviderの設計](chapter08.md) の章をご覧ください。 ![wolfProvider Overview](wolfProvider_overview.png) @@ -16,3 +16,7 @@ wolfProviderは、**libwolfprov** という名前の共有ライブラリとし これは、アプリケーションまたはコンフィギュレーションファイルを介してOpenSSLによって実行時に動的に登録できます。 wolfProviderは、アプリケーションが静的ビルドでコンパイルされたときにエンジンをロードするためのエントリポイントも提供します。 +wolfProviderはクロスプラットフォームであり、Linuxおよびその他の*nix系システム、macOS、Windows(Visual Studio 2022による`libwolfprov.dll`のビルドを含む)で動作します。 +OpenSSL 3.xのすべてのリリースバージョンに対応しており、FIPSおよび非FIPSの両方の構成で使用できます。 +サポートされているプラットフォームの一覧については、[移植性](chapter06.md)の章をご覧ください。 + diff --git a/wolfProvider/src-ja/chapter02.md b/wolfProvider/src-ja/chapter02.md index 8924a01c..ccf0b28e 100644 --- a/wolfProvider/src-ja/chapter02.md +++ b/wolfProvider/src-ja/chapter02.md @@ -1,9 +1,12 @@ # OpenSSLとの互換性 -wolfProviderは、以下のバージョンのOpenSSLを使用してテストを実行しています。 -これ以外のバージョンでは、変更や調整が必要になる場合があります。 +wolfProviderは、OpenSSL 3.xのすべてのリリースバージョンをサポートしています。 +OpenSSL 3.0.6から最新の3.xリリースまでの幅広いバージョンに対して、FIPSビルドおよび非FIPSビルドの両方で継続的にテストを行っています。 -- OpenSSL 3.0.0 -- OpenSSL 3.5.0 +一部の機能には、OpenSSLの最小バージョン要件があります。 + +- ポスト量子アルゴリズム（ML-KEM、ML-DSA）およびLMSを使用するには、OpenSSL 3.6以降が必要です。 + +OpenSSL 3.0.3から3.0.5については、上流のECX `EVP_PKEY_cmp` に関する不具合があるため推奨していません。3.0.xシリーズをご利用の場合は、OpenSSL 3.0.6以降をご使用ください。 他のOpenSSLバージョンのサポート追加を希望される場合は、[info@wolfssl.jp](mailto:info@wolfssl.jp) にご連絡ください。 diff --git a/wolfProvider/src-ja/chapter03.md b/wolfProvider/src-ja/chapter03.md index 3d058f54..ba43ba2e 100644 --- a/wolfProvider/src-ja/chapter03.md +++ b/wolfProvider/src-ja/chapter03.md @@ -12,6 +12,7 @@ wolfProviderパッケージは、以下のように構成しています。 ``` certs/ (ユニットテストで使用されるテスト用証明書、鍵) +docs/ (インテグレーションガイドおよびFIPSインテグレーションガイド) examples/ (実装例) include/ wolfprovider/ (wolfProviderヘッダーファイル) @@ -39,13 +40,13 @@ user_settings.h (user_settings.hサンプル) スクリプトを呼び出す前に、各種環境変数を設定する方法: ``` -OPENSSL_TAG=openssl-3.2.0 WOLFSSL_TAG=v5.7.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh +OPENSSL_TAG=openssl-3.5.0 WOLFSSL_TAG=v5.9.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh ``` スクリプトの引数として指定する方法： ``` -./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.2.0 --wolfssl-ver=v5.7.2-stable --debug +./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.5.0 --wolfssl-ver=v5.9.2-stable --debug ``` これらの方法を組み合わせて、目的のビルドの組み合わせを実現することもできます。 @@ -236,6 +237,25 @@ Visual StudioでwolfProviderプロジェクトをロードします。 この実行可能ファイルに`--help`の引数をつけて実行すると、オプションの一覧を表示できます。 wolfProviderを静的エンジンとして使用するには`--static`を付けて実行する必要があります。 +## Windows上でのビルド (Visual Studio) + +wolfProviderには、`IDE/WINVS/wolfprovider.sln` にVisual Studio 2022ソリューションが含まれており、wolfSSLをバックエンドとするOpenSSL 3.xプロバイダーである **`libwolfprov.dll`** をビルドします。 +DLL名は重要です。`-provider libwolfprov` は `libwolfprov.dll` に解決されます。 +Windows上では`configure`ステップはなく、wolfSSLは`user_settings.h`を介して構成します。 + +前提条件: + +* C++ツールセット (v143) およびMASM (`ml64.exe`) を含むVisual Studio 2022 +* OpenSSLをビルドするためのPerl、NASM、git（Strawberry PerlにはNASMが含まれています） + +このソリューションは4つのx64構成を提供します。 +`DLL Release` と `DLL Debug` は、実際に配布されるプロバイダー (`libwolfprov.dll`) をビルドします。 +`Static Release` と `Static Debug` は、単体テストを実行するための `unit-test.exe` をビルドします +（OpenSSLは`LoadLibraryA`でプロバイダーをロードしてから`OSSL_provider_init`を探すため、静的ライブラリはプロバイダーとして動作できません）。 +wolfProvider、wolfSSL、OpenSSLは同じ階層に並べて配置されていることを前提としています。 +パスは`wolfprovider.props`で設定されており、コマンドラインから上書きできます（例: `/p:wolfCryptDir=D:\wolfssl`）。 +非FIPS版・FIPS版いずれのwolfSSLビルドもサポートしています。 + ## ビルドオプション (./configure に指定するオプション) ライブラリの構築方法をカスタマイズするために`./configure`スクリプトに追加できるオプションを以下に示します。 @@ -261,7 +281,10 @@ wolfProviderを静的エンジンとして使用するには`--static`を付け | --enable-usersettings | **無効** | user_settings.h を使用し、MakefileのCFLAGSを使用しない | | --enable-dynamic | 有効 | wolfProviderをダイナミックプロバイダーとしてロードできるようにする | | --enable-singlethreaded | **無効** | wolfProviderをシングルスレッド環境で使用する | -| --enable-pqc | **無効** | ポスト量子アルゴリズム (ML-KEM、ML-DSA、SLH-DSA) をすべて有効にする | +| --enable-debug-silent | **無効** | デバッグログをコンパイルには含めるが、実行時に WOLFPROV_LOG_LEVEL / WOLFPROV_LOG_COMPONENTS で有効化するまで出力を抑制する | +| --enable-replace-default | **無効** | wolfProviderがOpenSSLのデフォルトプロバイダーとなるよう、置き換え用デフォルトプロバイダーをビルドする (CFLAGSに -DWOLFPROV_REPLACE_DEFAULT を指定することでも有効化可能) | +| --enable-seed-src | **無効** | フォークセーフなエントロピーのために、/dev/urandom キャッシュを使用する SEED-SRC エントロピーソースを有効にする | +| --enable-pqc | **無効** | ML-KEM、ML-DSA、SLH-DSA (FIPS 203/204/205) を有効にする。wolfSSL master/v5.9.2以降およびOpenSSL 3.6以降が必要 | | --enable-mlkem | **無効** | ML-KEM (FIPS 203) のみを有効にする | | --enable-mldsa | **無効** | ML-DSA (FIPS 204) のみを有効にする | | --enable-slhdsa | **無効** | SLH-DSA (FIPS 205) のみを有効にする | @@ -306,6 +329,7 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる | WP_HAVE_GMAC | GMAC (ガロア/カウンターモード認証) を有効化 | | WP_HAVE_HKDF | HKDF (HMACベースの鍵導出関数) を有効化 | | WP_HAVE_HMAC | HMAC (ハッシュベースのメッセージ認証コード) を有効化 | +| WP_HAVE_KBKDF | KBKDF (鍵ベースの鍵導出関数) を有効化 | | WP_HAVE_KRB5KDF | Kerberos 5 鍵導出関数を有効化 | | WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) 検証を有効化 | | WP_HAVE_MD5 | MD5 ハッシュアルゴリズムを有効化 | @@ -315,6 +339,7 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる | WP_HAVE_PBE | パスワードベースの暗号化を有効化 | | WP_HAVE_RANDOM | 乱数生成を有効化 | | WP_HAVE_RSA | RSA 暗号化と署名を有効化 | +| WP_HAVE_SEED | SEED-SRC エントロピーソースを有効化 | | WP_HAVE_SHA1 | SHA1 ハッシュアルゴリズムを有効化 | | WP_HAVE_SHA224 | SHA224 ハッシュアルゴリズムを有効化 | | WP_HAVE_SHA256 | SHA256 ハッシュアルゴリズムを有効化 | @@ -328,6 +353,7 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる | WP_HAVE_SHA512_224 | SHA512/224 ハッシュアルゴリズムを有効化 | | WP_HAVE_SHA512_256 | SHA512/256 ハッシュアルゴリズムを有効化 | | WP_HAVE_SHAKE_256 | SHAKE256 拡張出力関数を有効化 | +| WP_HAVE_SSHKDF | SSHKDF (SSH 鍵導出関数) を有効化 | | WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) ポスト量子署名を有効化 | | WP_HAVE_TLS1_PRF | TLS1 擬似乱数関数を有効化 | | WP_HAVE_X25519 | X25519 楕円曲線を有効化 | diff --git a/wolfProvider/src-ja/chapter04.md b/wolfProvider/src-ja/chapter04.md index 0cfd4353..127e3d83 100644 --- a/wolfProvider/src-ja/chapter04.md +++ b/wolfProvider/src-ja/chapter04.md @@ -1,6 +1,6 @@ -# FIPS 140-2のサポート +# FIPS 140-3のサポート -wolfProviderは、FIPSで検証されたバージョンのwolfCryptに対して適切にコンパイルされた場合にのみ、FIPS140-2に対応した動作を行うよう設計しています。 +wolfProviderは、FIPSで検証されたバージョンのwolfCryptに対して適切にコンパイルされた場合にのみ、FIPS140-3に対応した動作を行うよう設計しています。 この使用シナリオには、wolfSSL Inc. から入手した、適切にライセンスされ、検証されたバージョンのwolfCryptが必要です。 wolfCrypt FIPSライブラリは、非FIPSモードに「切り替える」ことができません。 @@ -15,4 +15,8 @@ OpenSSL構成に基づいて、デフォルトのOpenSSLエンジンまたは他 それらのアルゴリズムはwolfProviderおよびFIPS版wolfCryptのスコープに含みません。 FIPS認証取得に際し、問題となる可能性があります。 +完全なFIPS適合を実現するには、wolfProviderは通常、置き換え用デフォルトモード(`--enable-replace-default`)でビルドされます。 +これにより、wolfProviderがOpenSSLのデフォルトプロバイダーとなり、アプリケーションが誤って非FIPSアルゴリズムにフォールバックすることを防ぎます。 +置き換え用デフォルトモードについては[wolfProviderのロード](chapter07.md)の章を、FIPSベースライン検証や本番FIPSビルドのワークフロー(wolfCrypt FIPSモジュールの世代(例: v5、v6、v7)やFIPS Readyバンドルを含む)についてはwolfProvider FIPSインテグレーションガイド(wolfProviderパッケージ内の`docs/FIPS_INTEGRATION_GUIDE.md`)をご参照ください。 + FIPS版wolfCrypt(140-2/140-3)の使用に関する詳細については、wolfSSL(info@wolfssl.jp)までお問い合わせください。 \ No newline at end of file diff --git a/wolfProvider/src-ja/chapter05.md b/wolfProvider/src-ja/chapter05.md index 04792669..418938ce 100644 --- a/wolfProvider/src-ja/chapter05.md +++ b/wolfProvider/src-ja/chapter05.md @@ -37,7 +37,7 @@ wolfProviderは以下のログ出力レベルをサポートします。 ret = PROVIDER_ctrl_cmd(e, “log_level”, WP_LOG_ERROR | WP_LOG_INFO, NULL, NULL, 0); if (ret != 1) { - printf(“Failed to set logging level\n”); + printf("Failed to set logging level\n"); } ``` @@ -71,7 +71,7 @@ wolfProviderでは、コンポーネントごとにログを出力できます ret = PROVIDER_ctrl_cmd(e, “log_components”, WP_LOG_DIGEST | WP_LOG_CIPHER, NULL, NULL, 0); if (ret != 1) { - printf(“Failed to set log components\n”); + printf("Failed to set log components\n"); } ``` @@ -80,7 +80,7 @@ if (ret != 1) { デフォルトでは、wolfProviderは **fprintf()** を使用してデバッグログメッセージを **stderr** に出力します。 ログメッセージの出力方法や出力場所を変更したい場合は、カスタムログ出力コールバック関数を記述してwolfProviderに登録します。 -その際、`include/wolfprovider/wp_logging.h`に示す`wolfProvider_Logging_cb`のプロトタイプ宣言と一致させる必要があります。 +その際、`include/wolfprovider/wp_logging.h`に示す`wolfProv_Logging_cb`のプロトタイプ宣言と一致させる必要があります。 ``` /** @@ -89,7 +89,7 @@ if (ret != 1) { * component - [IN] - Component that log message is coming from * logMessage - [IN] - Log message */ -typedef void (*wolfProvider_Logging_cb)(const int logLevel, const int component, const char *const logMessage); +typedef void (*wolfProv_Logging_cb)(const int logLevel, const int component, const char *const logMessage); ``` その後、"**set_logging_cb**"エンジン制御コマンドを使用して、コールバック関数をwolfProviderに登録できます。 @@ -102,7 +102,7 @@ const char* const logMessage) { (void)logLevel; (void)component; - fprintf(stderr, “wolfProvider log message: %d\n”, logMessage); + fprintf(stderr, "wolfProvider log message: %s\n", logMessage); } int main (void) @@ -110,7 +110,7 @@ int main (void) int ret; PROVIDER* e; ... - ret = PROVIDER_ctrl_cmd(e, “set_logging_cb”, 0, NULL, (void(*)(void))my_Logging_cb, 0); + ret = PROVIDER_ctrl_cmd(e, “set_logging_cb”, 0, NULL, (void(*)(void))customLogCallback, 0); if (ret != 1) { /* failed to set logging callback */ } diff --git a/wolfProvider/src-ja/chapter06.md b/wolfProvider/src-ja/chapter06.md index 78d05884..9e8d3f91 100644 --- a/wolfProvider/src-ja/chapter06.md +++ b/wolfProvider/src-ja/chapter06.md @@ -2,6 +2,18 @@ wolfProviderは、関連するwolfCryptおよびOpenSSLライブラリの移植性を活用するように設計しています。 +## 対応プラットフォーム + +wolfProviderはクロスプラットフォームであり、wolfSSLおよびOpenSSLがサポートする主要なプラットフォーム上でビルドできます。 +対応プラットフォームは以下の通りです。 + +* Linuxおよびその他の*nix系システム。autoconfシステムを使用してビルドします([wolfProviderのビルド](chapter03.md)を参照) +* macOS +* Windows。`libwolfprov.dll`をビルドするVisual Studio 2022ソリューションを使用します([wolfProviderのビルド](chapter03.md)を参照) +* Windows CE + +これらのプラットフォームでは、FIPSビルドと非FIPSビルドの両方をサポートしています。 + ## スレッド対応 wolfProviderはスレッドセーフであり、必要に応じてwolfCryptのミューテックスロックメカニズム`wc_LockMutex()`、`wc_UnLockMutex()`を使用します。 diff --git a/wolfProvider/src-ja/chapter07.md b/wolfProvider/src-ja/chapter07.md index 7e23f56b..1bbc7b41 100644 --- a/wolfProvider/src-ja/chapter07.md +++ b/wolfProvider/src-ja/chapter07.md @@ -71,3 +71,20 @@ wolfProviderをロードできます。 #include wolfssl_provider_init(const OSSL_CORE_HANDLE* handle, const OSSL_DISPATCH* in, const OSSL_DISPATCH** out, void** provCtx); ``` + +## 置き換え用デフォルトモード + +wolfProviderは、OpenSSLのデフォルトプロバイダーと並行してロードされるのではなく、それを*置き換える*形でビルドすることができます。 +置き換え用デフォルトモードでは、`default`、`fips`、`wolfProvider` のいずれのプロバイダーへのOpenSSL側の要求もすべてwolfProviderに解決されるため、 +アプリケーションはコードや構成を変更することなくwolfSSLの暗号処理を使用でき、OpenSSLネイティブの暗号処理へのフォールバックも発生しません。 + +ビルド時には、configureオプション `--enable-replace-default`、`scripts/build-wolfprovider.sh` の引数 `--replace-default`、 +または `CFLAGS` に `-DWOLFPROV_REPLACE_DEFAULT` を定義することで有効化できます(Yocto系のビルドで有用です)。 +このモード向けにOpenSSLをビルドすると、OpenSSLの `crypto/provider_predefined.c` が置き換えられ、デフォルトプロバイダーがwolfProviderによってバックエンドされるようになります。 + +置き換え用デフォルトモードでは、wolfProviderがすでにデフォルトプロバイダーとなっているため、`OPENSSL_CONF` や `OPENSSL_MODULES` の構成は不要です。 +`scripts/env-setup` ヘルパーはこのモードを自動的に検出し、これらの環境変数の設定をスキップします。 + +置き換え用デフォルトモードは、FIPS環境への展開において推奨されます。 +FIPS認証はシステム全体に適用されるため、このモデルによってアプリケーションが誤って非FIPSのデフォルトプロバイダーを使用してしまうことがなくなります。 +詳細については、FIPS 140-3のサポートの章およびwolfProvider FIPSインテグレーションガイドをご参照ください。 diff --git a/wolfProvider/src-ja/chapter08.md b/wolfProvider/src-ja/chapter08.md index 01e44c65..8ea32252 100644 --- a/wolfProvider/src-ja/chapter08.md +++ b/wolfProvider/src-ja/chapter08.md @@ -19,6 +19,7 @@ wolfProviderは次のソースファイルで構成され、すべてwolfProvide | wp_dh_kmgmt.c | wolfProvider DH 鍵管理実装 | | wp_digests.c | wolfProvider メッセージ ダイジェスト実装 (SHA-1、SHA-2、SHA-3、...)| | wp_drbg.c | wolfProvider DRBG (決定論的乱数ビット ジェネレーター) 実装| +| wp_seed_src.c | フォークセーフなエントロピーのための /dev/urandom キャッシュを用いた wolfProvider SEED-SRC エントロピーソース実装| | wp_ecc_kmgmt.c | wolfProvider ECC キー管理実装| | wp_ecdh_exch.c | wolfProvider ECDH キー交換実装| | wp_ecdsa_sig.c | wolfProvider ECDSA 署名実装| @@ -38,10 +39,20 @@ wolfProviderは次のソースファイルで構成され、すべてwolfProvide | wp_mac_sig.c | wolfProvider MAC 署名実装| | wp_params.c | wolfProvider パラメータ処理実装| | wp_pbkdf2.c | wolfProvider PBKDF2 (パスワードベースのキー導出関数 2) 実装| +| wp_sshkdf.c | wolfProvider SSHKDF (SSH 鍵導出関数) 実装| | 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_mlkem_kmgmt.c | wolfProvider ML-KEM (FIPS 203) キー管理実装| +| wp_mlkem_kem.c | wolfProvider ML-KEM (FIPS 203) 鍵カプセル化実装| +| wp_mlx_kmgmt.c | wolfProvider ハイブリッド ML-KEM + ECDH キー管理実装| +| wp_mlx_kem.c | wolfProvider ハイブリッド ML-KEM + ECDH 鍵カプセル化実装| +| wp_mldsa_kmgmt.c | wolfProvider ML-DSA (FIPS 204) キー管理実装| +| wp_mldsa_sig.c | wolfProvider ML-DSA (FIPS 204) 署名実装| +| wp_slhdsa_kmgmt.c | wolfProvider SLH-DSA (FIPS 205) キー管理実装| +| wp_slhdsa_sig.c | wolfProvider SLH-DSA (FIPS 205) 署名実装| +| wp_lms.c | wolfProvider LMS (RFC 8554) 検証実装| | wp_tls1_prf.c | wolfProvider TLS 1.0 PRF 実装| | wp_tls_capa.c | wolfProvider TLS 機能の実装 | diff --git a/wolfProvider/src-ja/chapter09.md b/wolfProvider/src-ja/chapter09.md index 50587892..4e43fcf9 100644 --- a/wolfProvider/src-ja/chapter09.md +++ b/wolfProvider/src-ja/chapter09.md @@ -1,32 +1,39 @@ # その他のオープンソースソフトウェアとの統合に関する注意事項 wolfProviderは、OpenSSLプロバイダの一般的なフレームワークとアーキテクチャに準拠しています。 -そのため、OpenSSLを使用するアプリケーションからOpenSSL構成ファイルやAPI呼び出しを介して、wolfProviderを利用できます。 +そのため、OpenSSL構成ファイルやAPI呼び出しを介してプロバイダーを正しくロード・初期化するあらゆるOpenSSL利用アプリケーションから、wolfProviderを利用できます。 -wolfSSLは、自動化されたCI/CDワークフローを用いていくつかのオープンソースプロジェクトでwolfProviderをテストしています。 -この章には、wolfProviderとのインテグレーションに関する注意事項とヒントを示します。 +wolfSSLは、自動化されたCI/CDワークフローを用いて数多くのオープンソースプロジェクトでwolfProviderをテストしています。 +この章には、テスト済みのプロジェクトとのインテグレーションに関する注意事項とヒントを示します。 ## テスト済みのオープンソースプロジェクト -以下のオープンソースプロジェクトは、wolfProviderを用いて動作することをテスト済みです。 +以下のオープンソースプロジェクト (OSP) は、wolfProviderを用いて動作することをテスト済みです。 ### ネットワーク / Webテクノロジー -* cURL - URLによるデータ転送用コマンドラインツール +* cURL - URLによるデータ転送用コマンドラインツールおよびライブラリ * gRPC - 高性能RPCフレームワーク -* libwebsockets - Websocket用軽量Cライブラリ +* libwebsockets - WebSocket用軽量Cライブラリ * Nginx - 高性能HTTPサーバーおよびリバースプロキシ +* Nginx (PQC) - ポスト量子TLS鍵交換グループを組み込んだNginx * Qt5 Network - Qtネットワークモジュール +* libnice - ピアツーピアおよびWebRTC向けGLib ICE実装 +* iPerf - ネットワークパフォーマンス測定ツール ### セキュリティ / 認証 * OpenSSH - セキュアシェル実装 -* libssh2 - SSH2ライブラリ -* libfido2 - WebAuthn用FIDO2 ライブラリ +* libssh2 - SSH2クライアントライブラリ +* libfido2 - WebAuthn用FIDO2ライブラリ * OpenSC - スマートカードツールおよびミドルウェア -* pam-pkcs11 - PKCS#11用PAM モジュール +* pam-pkcs11 - PKCS#11用PAMモジュール * OpenVPN - VPNソリューション -* Stunnel - ネットワークサービス用SSLラッパー +* Stunnel - ネットワークサービス用SSL/TLSラッパー +* hostap (wpa_supplicant / hostapd) - Wi-Fi認証 (EAP、WPA) +* Kerberos 5 (krb5) - ネットワーク認証プロトコル +* libcryptsetup - LUKSディスク暗号化 +* Git over SSH - SSH経由のGitトランスポート ### システム / ネットワークツール @@ -34,42 +41,32 @@ wolfSSLは、自動化されたCI/CDワークフローを用いていくつか * tcpdump - ネットワークパケットアナライザー * rsync - ファイル同期ユーティリティ * tnftp - 拡張FTPクライアント -* iperf - ネットワークパフォーマンス測定ツール -* IPMItool - IPMI管理ツール -* PPP - ポイント to ポイントプロトコル実装 +* PPP - Point-to-Point Protocol実装 +* Socat - 双方向データ転送用の多目的リレー +* librelp - 信頼性の高いイベントログプロトコルライブラリ +* Net-SNMP - Simple Network Management Protocol実装 ### ディレクトリ / IDサービス * OpenLDAP - 軽量ディレクトリアクセスプロトコル * SSSD - システムセキュリティサービスデーモン -* Net-SNMP - ネットワーク管理プロトコル実装 +* BIND 9 - DNSサーバーおよびリゾルバ ### 暗号 / PKI -* cjose - JWT用Cライブラリ -* libeac3 - 電子認証コンポーネント -* libhashkit2 - コンシステントハッシュライブラリ -* liboauth2 - OAuth2ライブラリ +* cjose - JOSE/JWT用Cライブラリ +* libeac3 - 拡張アクセス制御ライブラリ +* libhashkit2 - コンシステントハッシュライブラリ (libmemcached) +* liboauth2 - OAuth 2.0ライブラリ * libtss2 - TPM2ソフトウェアスタック * tpm2-tools - TPM2ツール * xmlsec - XMLセキュリティライブラリ * sscep - SCEPクライアント実装 -### 開発 / テスト - -* Asan - アドレスサニタイザーテスト -* Codespell - ソースコード用スペルチェッカー -* Multi-Compiler - マルチコンパイラテスト - ### リモートアクセス / リモートディスプレイ * x11vnc - X11用VNCサーバー -* python3-ntp - Python NTPライブラリ - -### その他のユーティリティ - -* Socat - 双方向データ転送用の多目的リレー -* Simple - シンプルなテストアプリケーション +* python3-ntp - Python NTP実装 ## 一般的な設定 @@ -106,11 +103,17 @@ export CPPFLAGS="-I/path/to/openssl/install/include" ## テストと検証 -上記のすべてのオープンソースプロジェクトは、wolfProvider CI/CDパイプラインで以下のものを使用して継続的にテストしています。 +上記のすべてのオープンソースプロジェクトは、wolfProvider CI/CDパイプラインで継続的にテストされています。 +テストの範囲は以下の通りです。 + +* OpenSSL 3.xの幅広いリリース (3.0.6から最新の3.xリリースまで) +* wolfSSL masterおよび複数の安定版リリース (例: v5.9.1、v5.8.4) +* 標準モードおよび置き換え用デフォルトプロバイダーモードの両方 +* FIPSビルドおよび非FIPSビルド (FIPSはJenkinsパイプラインによる追加検証も実施) +* wolfProviderの暗号処理が実際に実行されていることを確認するための障害テスト (`WOLFPROV_FORCE_FAIL=1`) +* アドレスサニタイザーおよび未定義動作サニタイザー、静的解析、ポスト量子既知解テスト (KAT) -* OpenSSL v3.5.0 -* wolfSSLのマスターリリース / 安定リリース -* 適切なエラー処理を保証するための障害テスト -* FIPSテストもJenkinsパイプラインを通じて実施しています +wolfProviderは現在、60を超えるGitHub Actionsワークフローにわたって40を超えるオープンソースプロジェクトのインテグレーションを維持しており、 +高速なプルリクエスト単位のティアと、より広範な夜間ティアに分かれています。 この包括的なテストにより、wolfProvider は幅広いオープンソースプロジェクトとその様々なユースケースとの互換性を維持しています。 diff --git a/wolfProvider/src-ja/chapter11.md b/wolfProvider/src-ja/chapter11.md new file mode 100644 index 00000000..1cdc82eb --- /dev/null +++ b/wolfProvider/src-ja/chapter11.md @@ -0,0 +1,281 @@ +# ポスト量子暗号 + +wolfProviderは、OpenSSL 3のEVPインターフェースを通じてNISTのポスト量子標準をサポートします。 +PQCサポートはオプトイン方式であるため、これらのアルゴリズムを必要としないアプリケーションには影響しません。 + +## 要件 + +- wolfSSL v5.9.2-stable以降 +- OpenSSL 3.6以降 +- 必要なPQCアルゴリズムが有効化されたwolfSSLビルド + +パッケージ化されたDebianビルドは、システムのOpenSSLがOpenSSL 3.6より古いため、現在PQCを利用できません。 + +## サポートされるアルゴリズム + +| アルゴリズム | 標準 | サポートされるパラメータセット | +| :-------- | :------- | :----------------------- | +| ML-KEM | FIPS 203 | ML-KEM-512, ML-KEM-768, ML-KEM-1024 | +| ML-DSA | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 | +| SLH-DSA with SHA-2 | FIPS 205 | SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f | +| SLH-DSA with SHAKE | FIPS 205 | SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f | +| LMS | RFC 8554 / NIST SP 800-208 | LMSおよびLMOTSの公開鍵検証 | + +ML-KEMは、鍵生成、カプセル化、デカプセル化、raw鍵のインポート/エクスポート、公開鍵/秘密鍵のエンコードをサポートします。 +ML-DSAは、鍵生成、pure署名およびpre-hash署名、検証、コンテキスト文字列、鍵エンコードをサポートします。 +SLH-DSAは、鍵生成、pure署名、検証、コンテキスト文字列、鍵エンコードをサポートします。 +LMSは、公開鍵のインポートとワンショットの署名検証のみをサポートします。 +秘密鍵のインポート、署名、鍵生成は公開されていません。これは、OpenSSL 3.6のプロバイダーABIがLMSを検証専用として定義しているためです。 +すなわち、wolfCrypt自体はこれらの機能をサポートしているものの、wolfProviderが実装すべき署名、鍵生成、秘密鍵インポート用のエントリポイントは提供されません。 +これにより、LMSの葉ノード使用(ワンタイム署名)状態を強制できないインターフェース経由でステートフルな秘密鍵操作を公開してしまうことも回避しています。 + +## プロバイダーアーキテクチャ + +アプリケーションは、標準的なOpenSSL 3のEVPインターフェースを使用します。 +wolfProviderは、各パラメータセットに対するOpenSSL鍵管理実装、ML-KEM用のKEM実装、ML-DSAおよびSLH-DSA用の署名実装を登録します。 +プロバイダーはこれらの操作を対応するwolfCrypt APIに変換し、wolfCryptの鍵オブジェクトをOpenSSLの`EVP_PKEY`内部に保持します。 + +| ファミリー | OpenSSLインターフェース | 主な操作 | +| :----- | :----------------- | :-------------- | +| ML-KEM | `EVP_PKEY`, `EVP_PKEY_CTX`, KEM | 鍵生成、カプセル化、デカプセル化、鍵のインポート/エクスポート | +| ML-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | 鍵生成、pure署名/pre-hash署名と検証、鍵のインポート/エクスポート | +| SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | 鍵生成、pure署名と検証、鍵のインポート/エクスポート | +| LMS | `EVP_PKEY`, `EVP_MD_CTX`, signature | 公開鍵のインポート/エクスポートおよびワンショット検証 | + +ML-KEM、ML-DSA、SLH-DSAの鍵は、raw形式の公開鍵/秘密鍵パラメータに加え、DERおよびPEMエンコードをサポートします。 +公開鍵にはSubjectPublicKeyInfoを、秘密鍵にはPKCS#8を使用します。暗号化されたPKCS#8秘密鍵の出力もサポートしています。 +署名実装は、X.509証明書および証明書要求の操作に必要なアルゴリズム識別子を公開します。 +一方、LMSはOpenSSLのraw XDR公開鍵表現を使用し、秘密鍵は公開しません。 + +OpenSSLのLMSプロバイダー契約は、一般的な複数レベルのHSS階層ではなく、単一のLMSツリーを表します。 +そのためraw形式の公開鍵と署名には、4バイトのHSSレベル数フィールドが含まれません。 +wolfProviderは、wolfCryptを呼び出す際にのみ必要な単一レベルのHSSラッパーを追加し、OpenSSLとの境界で再びそれを取り除くことで、アプリケーションに対してOpenSSL互換のバイト列を維持します。 + +## サイズとセキュリティカテゴリ + +ML-KEMは常に32バイトの共有秘密を生成します。 + +| パラメータセット | NISTカテゴリ | 公開鍵 | 秘密鍵 | 暗号文 | +| :------------ | :------------ | ---------: | ----------: | ---------: | +| ML-KEM-512 | 1 | 800 bytes | 1,632 bytes | 768 bytes | +| ML-KEM-768 | 3 | 1,184 bytes | 2,400 bytes | 1,088 bytes | +| ML-KEM-1024 | 5 | 1,568 bytes | 3,168 bytes | 1,568 bytes | + +ML-DSAの署名と鍵は、パラメータセットごとに固定サイズを持ちます。 + +| パラメータセット | NISTカテゴリ | 公開鍵 | 秘密鍵 | 署名 | +| :------------ | :------------ | ---------: | ----------: | --------: | +| ML-DSA-44 | 2 | 1,312 bytes | 2,560 bytes | 2,420 bytes | +| ML-DSA-65 | 3 | 1,952 bytes | 4,032 bytes | 3,309 bytes | +| ML-DSA-87 | 5 | 2,592 bytes | 4,896 bytes | 4,627 bytes | + +SLH-DSAでは、同じレベルのSHA-2パラメータセットとSHAKEパラメータセットのサイズは同じです。 +`s`バリアントは署名サイズの縮小を重視し、`f`バリアントは署名速度を重視します。 + +| パラメータセット | NISTカテゴリ | 公開鍵 | 秘密鍵 | 署名 | +| :------------- | :------------ | ---------: | ----------: | --------: | +| 128s | 1 | 32 bytes | 64 bytes | 7,856 bytes | +| 128f | 1 | 32 bytes | 64 bytes | 17,088 bytes | +| 192s | 3 | 48 bytes | 96 bytes | 16,224 bytes | +| 192f | 3 | 48 bytes | 96 bytes | 35,664 bytes | +| 256s | 5 | 64 bytes | 128 bytes | 29,792 bytes | +| 256f | 5 | 64 bytes | 128 bytes | 49,856 bytes | + +## 署名および鍵生成パラメータ + +ML-DSAおよびSLH-DSAは、OpenSSLの署名コンテキスト文字列パラメータを受け付けます(FIPS 204およびFIPS 205で定められた最大255バイトの制限があります)。 +いずれもOpenSSLの署名パラメータを通じて、決定論的署名とランダム化署名の両方をサポートします。 +ML-DSAはさらに、HashML-DSAのpre-hash署名と外部表現値の入力をサポートします。 + +鍵生成の実装は、OpenSSLのML-KEM、ML-DSA、SLH-DSA用シードパラメータを受け付けます。 +これらの決定論的パスは、既知解テストおよびACVPテストで使用されます。 +通常のアプリケーションによる鍵生成やランダム化署名では、wolfCryptの乱数生成器が使用されます。 + +OpenSSLは、アプリケーションに対してワンショットおよびストリーミングのdigest-signエントリポイントを提供します。 +wolfProviderはHashML-DSAの入力を逐次的にハッシュ化します。 +pure ML-DSAおよびSLH-DSAでは完全なメッセージが必要となるため、SLH-DSAはストリーミング入力をバッファリングし、64 MiBのメッセージサイズ制限を課しています。 + +## プラットフォーム最適化 + +wolfProviderはネイティブのwolfCrypt実装を呼び出すため、プロバイダー専用の高速化レイヤーを別途必要とせず、wolfSSLビルドで選択された最適化コードの恩恵をそのまま受けられます。 +利用可能なwolfCryptのPQC高速化には、x86-64向けのベクトル化実装や、ARM32、AArch64、ARMv7-M、ARMv7E-M向けのアセンブリパスが含まれます。 +最適化されたSHA-2、SHA-3、SHAKE演算も、ML-KEM、ML-DSA、SLH-DSA、および構成されたLMSパラメータファミリーで使用されるハッシュ処理を高速化します。 + +実際に選択される実装パスは、コンパイラ、プロセッサ、wolfSSLの構成に依存します。 +アプリケーションは、対象システム上でwolfCryptベンチマークを実行し、どの実装が選択されたかを確認し、該当するパラメータセットを測定することが推奨されます。 +構成方法とベンチマークの詳細については、wolfSSLの[PQCドキュメント](https://www.wolfssl.com/documentation/manuals/wolfssl/appendix09.html) +および[ML-KEM高速化の概要](https://www.wolfssl.com/accelerated-kyber-ml-kem/)をご参照ください。 + +## ビルド + +ビルドスクリプトを使用すると、OpenSSL、wolfSSL、wolfProviderをまとめて構成できます。 + +```sh +./scripts/build-wolfprovider.sh --enable-pqc +``` + +`--enable-pqc` はML-KEM、ML-DSA、SLH-DSAを有効にします。LMSは独立したオプションのままであり、各ファミリーを個別に選択することもできます。 + +```sh +./scripts/build-wolfprovider.sh --enable-mlkem +./scripts/build-wolfprovider.sh --enable-mldsa +./scripts/build-wolfprovider.sh --enable-slhdsa +./scripts/build-wolfprovider.sh --enable-lms +``` + +手動でビルドする場合は、対応するアルゴリズムオプションを指定してwolfSSLを構成した後、wolfProviderを構成します。 + +```sh +# Add the required options to the normal wolfSSL configuration. +./configure --enable-mlkem --enable-mldsa --enable-slhdsa=yes,sha2 \ + --enable-lms=verify-only,sha256-192,shake256 +make +sudo make install + +# Configure wolfProvider against OpenSSL 3.6 or later. +./configure --enable-pqc --enable-lms \ + --with-openssl=/path/to/openssl \ + --with-wolfssl=/path/to/wolfssl +make +sudo make install +``` + +wolfSSLでアルゴリズムが有効になっていても、wolfProviderに`--enable-pqc`または個別のPQCオプションを渡さない限り、PQCコードはコンパイルされません。 + +wolfProviderはLMSの検証のみを行うため、`--enable-lms=verify-only,sha256-192,shake256` を指定してwolfSSLをビルドし、 +LMSの署名と鍵生成をコンパイルして未使用のままにするのではなく、ビルドから完全に除外してください。 +`build-wolfprovider.sh --enable-lms` のフローでは、すでにこのようにwolfSSLが構成されます。 + +## wolfProviderの使用 + +本番環境での展開には、置き換え用デフォルトモードの構成を推奨します。 +これにより、wolfProviderがOpenSSLのデフォルトとなり、操作が気付かないうちにOpenSSL組み込みのプロバイダーにフォールバックすることを防ぎます。 + +```sh +./scripts/build-wolfprovider.sh --replace-default \ + --enable-pqc --enable-lms +``` + +アプリケーションは、wolfProviderを通常のプロバイダーとしてロードすることもできます。 +このモードは相互運用性や移行に役立ちますが、すべての操作がwolfProviderで処理されることを保証するものではありません。 +wolfProviderが特定の操作を実装していない場合や、構成が適用されていない場合、OpenSSLはデフォルトプロバイダーを選択することがあります。 + +wolfProviderをロードするには、リポジトリのプロバイダー構成ファイルを使用します。 +この構成ファイルは`libwolfprov`を有効化します。`OPENSSL_CONF`をそのファイルに向けて設定してください。 + +```sh +export OPENSSL_CONF=/path/to/wolfProvider/provider.conf +``` + +wolfProviderがOpenSSLのモジュール検索パス外にインストールされている場合は、`libwolfprov.so`を含むディレクトリに`OPENSSL_MODULES`を設定してください。 + +```sh +export OPENSSL_MODULES=/path/to/wolfprovider/lib +``` + +構成を有効にした状態でコマンドを実行します。 +これにより、構成されたプロバイダーが通知するアルゴリズムを確認できますが、標準プロバイダーモードにおいて、 +関係のない操作がOpenSSLのデフォルトプロバイダーから選択されないことを保証するものではありません。 + +```sh +OPENSSL_CONF=/path/to/wolfProvider/provider.conf \ + openssl list -kem-algorithms +OPENSSL_CONF=/path/to/wolfProvider/provider.conf \ + openssl list -signature-algorithms +``` + +## OpenSSL EVPの使用例 + +メンテナンスされている +[`examples/pqc_openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c) +プログラムは、OpenSSLのEVP APIを通じて、NISTのFIPS 203からFIPS 205までの3つのアルゴリズムファミリーを実演します。 + +- ML-KEM-768の鍵生成、カプセル化、デカプセル化 +- ML-DSA-65の鍵生成、署名、検証 +- SLH-DSA-SHA2-128fの鍵生成、署名、検証 + +この例は、wolfProviderがいずれかのPQCファミリーで構成されている場合、`make check` によってビルドおよび実行されます。 +コンパイル時のガードにより有効化されたファミリーのみが実行されるため、同じソースコードでML-KEMのみ、ML-DSAのみ、SLH-DSAのみのビルドも実演できます。 +ビルド後は、wolfProviderのルートディレクトリから直接実行することもできます。 + +```sh +./examples/pqc_openssl_example +``` + +LMSはこの例には含まれていません。OpenSSLは検証機能のみを公開しており、実用的な例を作成するには固定の公開鍵と署名が必要となるためです。 +代わりに、このリポジトリではOpenSSLの320件の固定検証ベクターと、プロバイダー向けの単体テストによってLMSを検証しています。 + +## ビルドマクロ + +configureオプションは、それぞれ対応するリクエストマクロを追加します。 + +| configureオプション | wolfProviderリクエストマクロ | wolfSSL機能マクロ | +| :--------------- | :------------------------- | :----------------------- | +| `--enable-mlkem` | `WOLFPROV_HAVE_MLKEM` | `WOLFSSL_HAVE_MLKEM` | +| `--enable-mldsa` | `WOLFPROV_HAVE_MLDSA` | `WOLFSSL_HAVE_MLDSA` | +| `--enable-slhdsa` | `WOLFPROV_HAVE_SLHDSA` | `WOLFSSL_HAVE_SLHDSA` | +| `--enable-lms` | `WOLFPROV_HAVE_LMS` | `WOLFSSL_HAVE_LMS` | + +`--enable-pqc` はML-KEM、ML-DSA、SLH-DSAを有効にします。LMSは`--enable-lms`で個別に有効化します。 +configureがwolfSSLの機能を検証した後、wolfProviderは内部的に`WP_HAVE_MLKEM`、`WP_HAVE_MLDSA`、`WP_HAVE_SLHDSA`、`WP_HAVE_LMS`を使用して、 +利用可能な実装をコンパイルおよび登録します。 + +## TLS 1.3 + +wolfProviderは、以下のML-KEM TLSグループを通知します。 + +- MLKEM512 +- MLKEM768 +- MLKEM1024 +- X25519MLKEM768 +- SecP256r1MLKEM768 +- SecP384r1MLKEM1024 + +また、`mldsa44`、`mldsa65`、`mldsa87` のTLS 1.3署名方式も通知します。SLH-DSAはEVP経由でサポートされていますが、TLS署名方式としては通知されません。 + +## 検証 + +wolfCrypt Post Quantum v7.0.0実装は、[証明書A8437](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/details?validation=41047)のもとでNIST CAVPアルゴリズム検証を取得しています。 +この証明書は、LMS署名検証、ML-KEMの鍵生成・カプセル化・デカプセル化、ML-DSAの鍵生成・署名生成・署名検証、SLH-DSAの鍵生成・署名生成・署名検証を対象としています。 +また、NISTの記録で特定されている、前提となるSHA、SHAKE、HMAC、DRBGの各実装も対象に含まれます。 + +この検証は、特定されたwolfCryptのバージョンおよび動作環境に適用されます。 +検証済みの展開が必要な場合、wolfProviderアプリケーションは対応する検証済みのwolfCrypt配布物を使用し、そのセキュリティポリシーに従う必要があります。 + +CAVPはアルゴリズム実装を検証するものです。FIPS 140-3に基づく完全な暗号モジュールの検証とは別物であるため、 +オープンソース版やFIPS Ready版のwolfSSLビルドを使用するだけでは、FIPS検証済みアプリケーションにはなりません。 + +PQCには、複数の独立したテスト層があります。 + +- 単体テストおよびサンプルテストは、鍵生成、インポート/エクスポート、エンコード、カプセル化、デカプセル化、署名、検証、不正な入力、 + および該当する場合はX.509操作をカバーします。LMSの単体テストは特に、raw形式の公開鍵のインポート/エクスポート、XDRデコード、 + selectionの処理、不正な入力、およびサポート対象外のステートフルな操作の拒否をカバーします。 +- OpenSSL EVPの既知解テストは、ML-KEM、ML-DSA、SLH-DSA、LMSの各ベクターファイルをwolfProviderに対して実行します。 + LMSベクターには320件の検証ケースが含まれます。 +- PQC相互運用性テストは、wolfProviderとOpenSSLのデフォルトプロバイダー、および直接のwolfSSL APIを比較します。 + また、ML-KEMおよびハイブリッドTLSグループ、ML-DSA証明書認証のテストも行います。 +- nginx OSPワークフローは、ML-DSA認証を用いたML-KEMおよびハイブリッドTLS 1.3鍵交換をテストします。 +- 固定バージョンのlibacvp (Cisco v2.3.1) OSPワークフローは、`--enable-pqc` を指定してwolfProviderをビルドし、 + `APP_PQC_HANDLER` グループを実行した後、その完全な単体テストスイートを実行します。 + これにより、置き換え用デフォルトモードと非置き換えモードの両方で、ML-KEMおよびML-DSA用のOpenSSL ACVPハンドラーを検証します。 + +バージョン、nginx、libacvpの各マトリクスは、wolfSSL masterおよび最新の対象安定版リリースをカバーします。 +OSPテストは、置き換え用デフォルトモードと非置き換えモードの両方で、通常時と強制障害時のケースを実行します。 +PQCのKATおよびバージョンカバレッジはプルリクエストごとに実行され、より長時間を要するOSPインテグレーションワークフローはラベルによって選択され、夜間に実行されます。 +KATマトリクスには、組み合わせたPQC構成に加えて、LMS単体の行も含まれます。 + +## 関連ドキュメント + +現在の展開モデルおよび完全なビルド手順については、 +[wolfProvider README](https://github.com/wolfSSL/wolfProvider/blob/master/README.md) +および[wolfProviderインテグレーションガイド](https://github.com/wolfSSL/wolfProvider/blob/master/docs/INTEGRATION_GUIDE.md)をご参照ください。 +インテグレーションガイドでは、置き換え用デフォルトビルド、プロバイダー構成、テスト、トラブルシューティングについて説明しています。 +検証済みの展開については、置き換え用デフォルトの要件とセキュリティポリシーに関する考慮事項を説明する +[FIPSインテグレーションガイド](https://github.com/wolfSSL/wolfProvider/blob/master/docs/FIPS_INTEGRATION_GUIDE.md)をご利用ください。 + +リポジトリ内の +[置き換え用デフォルトビルドワークフロー](https://github.com/wolfSSL/wolfProvider/blob/master/scripts/build-wolfprovider.sh)、 +[プロバイダー構成](https://github.com/wolfSSL/wolfProvider/blob/master/provider.conf)、 +[PQC EVPの例](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c)、 +[PQC KATランナー](https://github.com/wolfSSL/wolfProvider/blob/master/scripts/test-pqc-kat.sh) +は実装とともにメンテナンスされており、サポートされているオプションと検証に関する最新の例を提供しています。