From 9845989c1cd94447a10985911a70c8cc9c10e8a9 Mon Sep 17 00:00:00 2001 From: Aidan Garske Date: Fri, 28 Aug 2026 17:26:48 -0700 Subject: [PATCH 1/3] 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/3] 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) +は実装とともにメンテナンスされており、サポートされているオプションと検証に関する最新の例を提供しています。 From f7803478592cc218f00a878df7ddcc4190d80cda Mon Sep 17 00:00:00 2001 From: Aidan Garske Date: Mon, 31 Aug 2026 08:26:32 -0700 Subject: [PATCH 3/3] Expand replace-default mode documentation and sync the Japanese chapter --- wolfProvider/src-ja/chapter07.md | 172 ++++++++++++++++++++++++++----- wolfProvider/src/chapter07.md | 167 +++++++++++++++++++++++++++++- 2 files changed, 311 insertions(+), 28 deletions(-) diff --git a/wolfProvider/src-ja/chapter07.md b/wolfProvider/src-ja/chapter07.md index 1bbc7b41..16b8d6ac 100644 --- a/wolfProvider/src-ja/chapter07.md +++ b/wolfProvider/src-ja/chapter07.md @@ -28,19 +28,25 @@ OpenSSLコンフィギュレーションファイルを使用する代わりに { 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"); +プロバイダーをロードすると利用可能にはなりますが、それだけですべての操作が必ずそのプロバイダーを使用するわけではありません。 +特定の操作でwolfProviderを必ず使用させるには、wolfProviderが登録するプロパティ `"provider=wolfprov"`(FIPSビルドの場合は `"provider=wolfprov,fips=yes"`)を用いたプロパティクエリで、`EVP_*_fetch()` APIを通じてアルゴリズムをフェッチします。 +なお、`libwolfprov` はプロバイダーを*ロード*するために使用するモジュール名であり、`provider=wolfprov` はそのアルゴリズムを*選択*するために使用するプロパティです。 - OSSL_PROVIDER_unload(prov); -``` +wolfProviderは現在、プロバイダーのセルフテストディスパッチ(`OSSL_FUNC_PROVIDER_SELF_TEST`)を実装していません。 +そのため、ロード済みプロバイダーに対する `OSSL_PROVIDER_self_test()` はwolfProviderのセルフテストを実行せず、セルフテストとして依拠すべきではありません。 ## OpenSSLコンフィギュレーションファイルによるwolfProviderのロード @@ -64,27 +70,145 @@ activate = 1 ## wolfProvider静的エントリポイント -wolfProviderを静的ライブラリとして使用する場合、アプリケーションは次のエントリポイントを呼び出して -wolfProviderをロードできます。 +wolfProviderを静的ライブラリとしてビルドした場合、動的にロードされるモジュールではなく、OpenSSLの組み込みプロバイダーとしてロードされます。 +アプリケーションは静的wolfProvider(およびそのwolfSSLとOpenSSLの依存関係)にリンクし、wolfProviderのエントリポイントを `OSSL_PROVIDER_add_builtin()` で登録したうえで、名前を指定してロードします。 ``` -#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; +} ``` +エントリポイント `wolfssl_provider_init()` は `wolfprovider/wp_wolfprov.h` で宣言されています。 +これは `OSSL_PROVIDER_add_builtin()` に渡すものであり、アプリケーションから直接呼び出すことはありません。 + ## 置き換え用デフォルトモード -wolfProviderは、OpenSSLのデフォルトプロバイダーと並行してロードされるのではなく、それを*置き換える*形でビルドすることができます。 -置き換え用デフォルトモードでは、`default`、`fips`、`wolfProvider` のいずれのプロバイダーへのOpenSSL側の要求もすべてwolfProviderに解決されるため、 -アプリケーションはコードや構成を変更することなくwolfSSLの暗号処理を使用でき、OpenSSLネイティブの暗号処理へのフォールバックも発生しません。 +上記の標準的なロードモデルでは、wolfProviderはOpenSSL自身のプロバイダーと*並行して*ロードされます。 +すなわち、アプリケーションは構成ファイル、`OSSL_PROVIDER_load()` / `OSSL_PROVIDER_add_builtin()` の呼び出し、あるいはプロパティクエリを通じて `libwolfprov` を有効化します。 +このときOpenSSLネイティブの `default`(FIPSビルドの場合は `fips`)プロバイダーは引き続き存在し、wolfProviderが処理しない操作はOpenSSL自身の暗号処理で応答され得ます。 + +置き換え用デフォルトモードはこの関係を変えます。 +wolfProviderはOpenSSLのデフォルトプロバイダーと並んでロードされるのではなく、それ自体が*デフォルトプロバイダーになります*。 +置き換え用デフォルトモードでは、OpenSSLの組み込み `default` または `fips` プロバイダーへの要求がwolfProvider(`libwolfprov` モジュール)に解決されます。 +そのため、変更を加えていないアプリケーションは、**コードの変更も、`openssl.cnf` も、環境変数の構成も一切なしに** wolfSSLの暗号処理を使用でき、置き換えられたプロバイダーについてはOpenSSLネイティブ実装へ戻る経路も存在しません。 + +### 仕組み + +置き換え用デフォルトモードは、OpenSSLのビルド前にOpenSSLのソースファイル `crypto/provider_predefined.c` を1つ置き換えることで実現します。 +このファイルは、組み込みプロバイダーの*名前*を、その名前でプロバイダーがロードされる際に使用する初期化関数へ対応付けるテーブル `ossl_predefined_providers[]` を定義しています。 +標準のOpenSSLでは `default` という名前は `ossl_default_provider_init`(OpenSSL自身の暗号処理)に対応付けられています。 +wolfProviderは、このテーブルを書き換えるドロップイン置換ファイル `patches/provider_predefined.c.replace-default` を同梱しており、`default` と `fips`(および静的レガシービルドでは `legacy`)の名前を、代わりに小さなローダー関数へ対応付けます。 + +```c +const OSSL_PROVIDER_INFO ossl_predefined_providers[] = { + { "fips", NULL, load_wolfprov_and_init, NULL, 0 }, + { "default", NULL, load_wolfprov_and_init, NULL, 1 }, +# ifdef STATIC_LEGACY + { "legacy", NULL, load_wolfprov_and_init, NULL, 0 }, +# endif + { "base", NULL, ossl_base_provider_init, NULL, 0 }, + { "null", NULL, ossl_null_provider_init, NULL, 0 }, + { NULL, NULL, NULL, NULL, 0 } +}; +``` + +`load_wolfprov_and_init()` はOpenSSLのDSOレイヤーを使用して `libwolfprov` を `dlopen` し、そのエントリポイント `wolfssl_provider_init` をバインドして、プロバイダーの初期化関数として呼び出します。 +これ以降、OpenSSLがデフォルトプロバイダーを遅延ロードするたびに――アプリケーションがプロバイダーを明示的に選択せずに初めて暗号処理を行った時点で自動的に行われます――wolfProviderがロードされます。 + +2つのエントリは意図的にそのまま残されています。 +OpenSSLの `base` プロバイダー(エンコーダー、デコーダー、`PEM`/`DER` シリアライズ、その他の非暗号サービス)と `null` プロバイダーは、wolfProviderがこれらの非暗号サービスを置き換えないため、元のOpenSSLの初期化関数を保持します。 + +またこの置換ファイルは、OpenSSL自体がFIPSモジュールとしてビルドされる場合にはコンパイルを拒否します。 + +```c +#ifdef FIPS_MODULE +#error "For wolfProvider replace default mode, do not build OpenSSL with FIPS" +#endif +``` + +これは意図的な設計です。置き換え用デフォルトモードでは、FIPSの振る舞いはOpenSSLの独立したFIPSモジュールではなく、wolfProviderの下層にあるwolfCryptから得られることを想定しています。 +このため `--replace-default` はOpenSSL側の `--enable-fips-baseline` パッチとは相互排他であり、`scripts/build-wolfprovider.sh` はこの組み合わせを拒否します。 + +このリダイレクトはOpenSSLのビルド内に完結するため、wolfProviderは実行時にも存在している必要があります。 +`load_wolfprov_and_init()` は `libwolfprov` を名前でロードするので、wolfProvider共有ライブラリは動的ローダーが見つけられる場所にインストールされていなければなりません。 +存在しない場合、パッチ適用済みのOpenSSLは `Could not load libwolfprov.so. Is the libwolfprov package installed?` と報告し、プロバイダーの初期化に失敗します。 +「構成が不要」であることは「依存関係が不要」を意味するわけではありません。 + +### 置き換え用デフォルトモードの有効化 + +置き換え用デフォルトの有効化には2つの部分があり、両方が必要です。 + +1. **wolfProviderを置き換え用デフォルト向けにビルドする。** `./configure` に `--enable-replace-default` を渡すか、`CFLAGS` に `-DWOLFPROV_REPLACE_DEFAULT` を定義します(フラグ経由でビルドを駆動するYocto系・システムパッケージ向けのビルドに便利です)。 +2. **`provider_predefined.c` 置換を適用してOpenSSLをビルドする。** これによりOpenSSLの組み込み `default`/`fips` の名前がwolfProviderをロードするようになります。 -ビルド時には、configureオプション `--enable-replace-default`、`scripts/build-wolfprovider.sh` の引数 `--replace-default`、 -または `CFLAGS` に `-DWOLFPROV_REPLACE_DEFAULT` を定義することで有効化できます(Yocto系のビルドで有用です)。 -このモード向けにOpenSSLをビルドすると、OpenSSLの `crypto/provider_predefined.c` が置き換えられ、デフォルトプロバイダーがwolfProviderによってバックエンドされるようになります。 +ビルドスクリプトは両方を1ステップで行います。 -置き換え用デフォルトモードでは、wolfProviderがすでにデフォルトプロバイダーとなっているため、`OPENSSL_CONF` や `OPENSSL_MODULES` の構成は不要です。 -`scripts/env-setup` ヘルパーはこのモードを自動的に検出し、これらの環境変数の設定をスキップします。 +```sh +./scripts/build-wolfprovider.sh --replace-default +``` + +手順1だけを行うと、置き換え用デフォルト対応のwolfProviderはビルドされますが、OpenSSLは依然として自身のデフォルトプロバイダーを使用するストックのままになります。 +手順2だけを行うと、ロードすべきwolfProviderが存在しないOpenSSLにパッチを当てることになります。 +2つが同期した状態を保つため、ビルドスクリプトを使用してください(あるいはインテグレーションガイドに従ってください)。 +パッケージ化やシステム全体への展開を含む、権威ある手順については、wolfProviderインテグレーションガイド(`docs/INTEGRATION_GUIDE.md`)をご参照ください。 + +置き換え用デフォルトモードでは、wolfProviderがすでにデフォルトプロバイダーであるため、`OPENSSL_CONF` や `OPENSSL_MODULES` の構成は不要です。 +`scripts/env-setup` ヘルパーはこのモードを検出し、これらの変数の設定をスキップします(標準モードでは `OPENSSL_CONF` を `provider.conf` に向けて `libwolfprov` を有効化します)。 + +### 置き換え用デフォルトモードを使用する理由 + +置き換え用デフォルトモードでビルドする主な理由は2つあります。 + +**1. wolfProviderが実際に暗号処理を行っていることを保証するため。** 標準的なロードモデルでは、いくつかの状況でOpenSSLが自身のデフォルトプロバイダーから要求を処理し得ます――アプリケーション(またはその依存関係)が `default` プロバイダーを明示的に要求した場合、wolfProviderが実装していないアルゴリズムの場合、あるいは構成ファイルが単に読み込まれていない場合です。 +これらの場合、OpenSSLはネイティブ実装へ気付かないうちにフォールバックし、その様子はアプリケーションの挙動からは見えません。 +置き換え用デフォルトモードはこのフォールバック経路を完全に取り除きます。`default`/`fips` の名前が*wolfProvider自体*であるため、フォールバックできるOpenSSLネイティブのプロバイダーが残らないからです。 +これにより、アプリケーション、ライブラリ、あるいはシステム全体が、見かけ上そう見えるだけでなく、実際にwolfCryptを介して暗号処理を行っていることを検証する決定的な手段となります。 +wolfProviderのCIは、まさにこの目的で、強制障害テスト(`WOLFPROV_FORCE_FAIL=1`)と組み合わせて使用しています。 + +**2. システム全体の置き換え。** 置き換え用デフォルトモードは、パッチ適用済みのlibcryptoにリンクする*すべての*OpenSSL利用者に対して、アプリケーションごとの構成もソース変更もなしに、wolfCryptを暗号バックエンドにします。 +これは、ディストリビューションやイメージ全体――例えばYoctoイメージや、`scripts/build-wolfprovider.sh --replace-default` が置換をシステムのOpenSSLパッケージへ転送するDebianパッケージビルド――の下層でwolfCryptに差し替えることが目的の場合に使用されるモデルです。 +結果として得られるシステム上のすべてのアプリケーションが、個別に再ビルドや再構成をされることなくwolfSSLの暗号処理を使用します。 -置き換え用デフォルトモードは、FIPS環境への展開において推奨されます。 -FIPS認証はシステム全体に適用されるため、このモデルによってアプリケーションが誤って非FIPSのデフォルトプロバイダーを使用してしまうことがなくなります。 +置き換え用デフォルトモードは、理由(1)と同じ理由から、FIPS展開でも推奨されるモデルです。 +OpenSSLのデフォルトプロバイダーへのフォールバック経路を取り除くことで、アプリケーションが誤ってOpenSSL自身のプロバイダーの非FIPSアルゴリズムを使用してしまうリスクを低減します。 +これ自体がシステム全体のFIPS適合を保証するわけではありません(明示的にロードされたサードパーティのプロバイダーや、低レベルの直接呼び出しは制御外のままです)が、最も一般的な意図しないフォールバック経路を塞ぎます。 詳細については、FIPS 140-3のサポートの章およびwolfProvider FIPSインテグレーションガイドをご参照ください。 + +### 置き換え用デフォルトモードが有効かどうかの確認 + +最も確実な確認方法はOpenSSLのプロバイダー一覧です。 +置き換え用デフォルトモードでは、組み込みの `default` プロバイダーが自身の名前として **wolfSSL Provider** を報告し、別個の `libwolfprov` エントリは存在しません。 + +```sh +$ openssl list -providers +Providers: + default + name: wolfSSL Provider + version: ... + status: active +``` + +標準モデルでは、同じコマンドはwolfProviderをOpenSSLの `default` とは別の `libwolfprov` プロバイダーとして表示します。 +wolfProviderのスクリプトでビルドされたOpenSSLは、バージョン文字列にビルドメタデータのサフィックスも付きます(`openssl version` は例えば `OpenSSL 3.x.y+wolfProvider-nonfips` と表示します)。ただしこのサフィックス自体は、wolfProviderによってビルドされたOpenSSLであることを示すものであり、置き換え用デフォルトモードそのものを示すわけではありません。 + +### 置き換え用デフォルトのテスト用ビルド + +`--replace-default` を必要とする別のオプション `--enable-replace-default-testing` が存在しますが、**これはwolfProvider自身の単体テスト専用であり、本番環境で使用してはなりません**。 +置き換え用デフォルトのOpenSSLは、比較対象となる本物のOpenSSLデフォルトプロバイダーをもはや公開しないため、このオプションは通常は内部的なOpenSSLシンボルをいくつかエクスポートし、単体テストが本物のOpenSSLプロバイダーを別名でロードしてwolfProviderの出力と照合できるようにします。 +これはテストハーネス用の補助であって展開モードではありません。有効化するとビルドスクリプトは目立つ「テスト専用」の警告を出力します。 diff --git a/wolfProvider/src/chapter07.md b/wolfProvider/src/chapter07.md index eae4e01e..b6033291 100644 --- a/wolfProvider/src/chapter07.md +++ b/wolfProvider/src/chapter07.md @@ -82,10 +82,169 @@ The entry point `wolfssl_provider_init()` is declared in `wolfprovider/wp_wolfpr ## 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. +In the standard loading models described above, wolfProvider is loaded *alongside* +OpenSSL's own providers: the application activates `libwolfprov` through a config +file, an `OSSL_PROVIDER_load()`/`OSSL_PROVIDER_add_builtin()` call, or a property +query. OpenSSL's native `default` (and, for a FIPS build, `fips`) provider remains +present, and any operation that wolfProvider does not service can still be answered +by OpenSSL's own crypto. + +Replace-default mode changes that relationship. Instead of loading beside OpenSSL's +default provider, wolfProvider *becomes* it. In replace-default mode, an OpenSSL +request for the built-in `default` or `fips` provider resolves to wolfProvider (the +`libwolfprov` module), so an unmodified application uses wolfSSL cryptography with +**no code, no `openssl.cnf`, and no environment configuration** — and with no path +back to OpenSSL's native implementations for the redirected providers. + +### How It Works + +Replace-default mode works by replacing one OpenSSL source file, +`crypto/provider_predefined.c`, before OpenSSL is built. That file defines +`ossl_predefined_providers[]`, the table OpenSSL consults to map a built-in provider +*name* to the initialization function used when that provider is loaded. In stock +OpenSSL the `default` name maps to `ossl_default_provider_init` (OpenSSL's own +crypto). wolfProvider ships a drop-in replacement, +`patches/provider_predefined.c.replace-default`, that rewrites the table so the +`default` and `fips` names (and `legacy`, in static-legacy builds) instead map to a +small loader function: + +```c +const OSSL_PROVIDER_INFO ossl_predefined_providers[] = { + { "fips", NULL, load_wolfprov_and_init, NULL, 0 }, + { "default", NULL, load_wolfprov_and_init, NULL, 1 }, +# ifdef STATIC_LEGACY + { "legacy", NULL, load_wolfprov_and_init, NULL, 0 }, +# endif + { "base", NULL, ossl_base_provider_init, NULL, 0 }, + { "null", NULL, ossl_null_provider_init, NULL, 0 }, + { NULL, NULL, NULL, NULL, 0 } +}; +``` + +`load_wolfprov_and_init()` uses OpenSSL's DSO layer to `dlopen` `libwolfprov`, bind +its `wolfssl_provider_init` entry point, and call it as the provider's init +function. From that point on, whenever OpenSSL lazily loads its default provider — +which it does automatically the first time an application performs any crypto +without having explicitly selected a provider — it loads wolfProvider instead. + +Two entries are deliberately left untouched. OpenSSL's `base` provider (encoders, +decoders, `PEM`/`DER` serialization, and other non-cryptographic services) and its +`null` provider keep their original OpenSSL initialization functions, because +wolfProvider does not replace those non-crypto services. + +The replacement also refuses to compile if OpenSSL itself is being built as a FIPS +module: + +```c +#ifdef FIPS_MODULE +#error "For wolfProvider replace default mode, do not build OpenSSL with FIPS" +#endif +``` + +This is intentional: in replace-default mode, FIPS behavior is expected to come from +wolfCrypt underneath wolfProvider, not from OpenSSL's separate FIPS module. For this +reason `--replace-default` is mutually exclusive with the OpenSSL-side +`--enable-fips-baseline` patch, and `scripts/build-wolfprovider.sh` rejects the +combination. -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. +Because the redirect lives entirely in the OpenSSL build, wolfProvider still needs +to be present at runtime: `load_wolfprov_and_init()` loads `libwolfprov` by name, so +the wolfProvider shared library must be installed where the dynamic loader can find +it. If it is missing, the patched OpenSSL reports +`Could not load libwolfprov.so. Is the libwolfprov package installed?` and provider +initialization fails. "No configuration" does not mean "no dependency." -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. +### Enabling Replace-Default Mode + +Enabling replace-default has two parts, and both must be present: + +1. **Build wolfProvider for replace-default.** Pass `--enable-replace-default` to + `./configure`, or define `-DWOLFPROV_REPLACE_DEFAULT` in `CFLAGS` (convenient for + Yocto-style/system-package builds that drive the build through flags). +2. **Build OpenSSL with the `provider_predefined.c` replacement**, so that OpenSSL's + built-in `default`/`fips` names load wolfProvider. + +The build script does both in one step: + +```sh +./scripts/build-wolfprovider.sh --replace-default +``` + +Doing only step 1 builds a replace-default-capable wolfProvider but leaves a stock +OpenSSL that still uses its own default provider; doing only step 2 patches an +OpenSSL that has no wolfProvider to load. Use the build script (or follow the +Integration Guide) so the two stay in sync. See the wolfProvider Integration Guide +(`docs/INTEGRATION_GUIDE.md`) for the authoritative, step-by-step procedure, +including packaging and whole-system deployment. + +In replace-default mode, no `OPENSSL_CONF` or `OPENSSL_MODULES` configuration is +required, because wolfProvider is already the default provider. The +`scripts/env-setup` helper detects this mode and skips setting those variables (in +standard mode it points `OPENSSL_CONF` at `provider.conf` to activate `libwolfprov`). + +### Why Use Replace-Default Mode + +There are two primary reasons to build in replace-default mode. + +**1. To prove that wolfProvider is actually the one doing the crypto.** In the +standard loading model, OpenSSL can still satisfy a request from its own default +provider in several situations — an application (or a dependency) that explicitly +asks for the `default` provider, an algorithm wolfProvider does not implement, or a +configuration file that is simply not picked up. In those cases OpenSSL silently +falls back to its native implementation, and nothing in the application's behavior +makes that visible. Replace-default mode removes the fallback path entirely: since +the `default`/`fips` names *are* wolfProvider, there is no OpenSSL-native provider +left to fall back to. This makes it the definitive way to verify that an +application, a library, or a whole system genuinely routes its cryptography through +wolfCrypt rather than only appearing to. wolfProvider's CI uses it together with +force-failure testing (`WOLFPROV_FORCE_FAIL=1`) for exactly this purpose. + +**2. Whole-system replacement.** Replace-default mode makes wolfCrypt the crypto +backend for *every* OpenSSL consumer linked against the patched libcrypto, with no +per-application configuration and no source changes to any of them. This is the +model used when the goal is to substitute wolfCrypt underneath an entire +distribution or image — for example a Yocto image, or a Debian package build where +`scripts/build-wolfprovider.sh --replace-default` forwards the replacement into the +system OpenSSL package. Every application on the resulting system uses wolfSSL +cryptography without being individually rebuilt or reconfigured. + +Replace-default mode is also the recommended model for FIPS deployments, for the +same reason as (1): removing the OpenSSL default-provider fallback path reduces the +risk that an application inadvertently uses a non-FIPS algorithm from OpenSSL's own +provider. It does not by itself guarantee system-wide FIPS compliance — explicitly +loaded third-party providers and direct low-level calls remain outside its control — +but it closes the most common accidental-fallback path. See the FIPS 140-3 Support +chapter and the wolfProvider FIPS Integration Guide for details. + +### Confirming Replace-Default Mode Is Active + +The most reliable check is the OpenSSL provider list. In replace-default mode the +built-in `default` provider reports **wolfSSL Provider** as its name, and there is no +separate `libwolfprov` entry: + +```sh +$ openssl list -providers +Providers: + default + name: wolfSSL Provider + version: ... + status: active +``` -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. +In the standard model the same command instead shows wolfProvider as a distinct +`libwolfprov` provider alongside OpenSSL's `default`. An OpenSSL built by the +wolfProvider scripts also carries a build-metadata suffix in its version string +(`openssl version` shows, for example, `OpenSSL 3.x.y+wolfProvider-nonfips`), though +that suffix alone marks a wolfProvider-produced OpenSSL, not specifically +replace-default mode. + +### Replace-Default Testing Builds + +A separate `--enable-replace-default-testing` option (which requires +`--replace-default`) exists **for wolfProvider's own unit tests only, and must not +be used in production**. Because a replace-default OpenSSL no longer exposes a +genuine OpenSSL default provider to compare against, this option exports a handful of +otherwise-internal OpenSSL symbols so the unit tests can load the real OpenSSL +provider under a separate name and check wolfProvider's output against it. It is a +test-harness aid, not a deployment mode; the build scripts print prominent +"testing only" warnings when it is enabled.