diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md index 3c249608..2a144eab 100644 --- a/wolfProvider/src/chapter03.md +++ b/wolfProvider/src/chapter03.md @@ -10,6 +10,7 @@ The general wolfProvider package is structured as follows: ``` certs/ (Test certificates and keys, used with unit tests) +debian/ (Scripts for building Debian packages) examples/ (Code examples) include/ wolfprovider/ (wolfProvider header files) @@ -48,6 +49,40 @@ For a full list of environment variables and script arguments do `./scripts/buil If desired, each component can be manually compiled using the following guide. +### Forcing use of wolfProvider via `--replace-default` +With stock OpenSSL, it's still possible to access the default provider delivered with OpenSSL, even with the proper configuration. For example, software may call into OpenSSL EVP functions with a specific provider context, similar to how the unit tests work: + +``` +osslLibCtx = OSSL_LIB_CTX_new(); +osslProv = OSSL_PROVIDER_load(osslLibCtx, "default"); +EVP_PKEY_keygen(osslLibCtx, &myKey); +``` + +For many use cases, this is not ideal because it allows calls to silently bypass wolfProvider and utilize OpenSSL cryptographic functions. + +As an alternative, the OpenSSL build created by this repo can optionally disable the stock provider from OpenSSL and replace it with wolfProvider. We belive this to be a more robust way of ensuring wolfProvider is the crypto backend. + +Use option `--replace-default` with `build-wolfprovider.sh` to enable this mode. + +To check if OpenSSL contains this functionality, look for the `wolfProvider-replace-default` string in the version output for both OpenSSL and the libssl3 library as shown: + +``` +$ openssl version +OpenSSL 3.0.17+wolfProvider-replace-default 29 Oct 2025 (Library: OpenSSL 3.0.17+wolfProvider-replace-default 29 Oct 2025) +``` + +Note that libwolfssl and libwolfprov are agnostic of the `--replace-default` flag. + +### Building Debian packages +*Note: wolfProvider supports Debian Bookworm only for the time being. Other versions of Debian and Ubuntu require minor porting.* + +wolfProvider supports building .deb files for installation on Debian systems. To build the packages, run: + +``` +scripts/build-wolfprovider.sh --debian --replace-default +``` + +Upon build success, the .deb files are placed in the parent directory. When installing, install all `../*.deb` files with `apt` or `dpkg` to get the default replacement functionality. Alternatively, when using a pre-installed version of OpenSSL, install just the libwolfssl and libwolfprov packages from the parent directory. ### Building OpenSSL diff --git a/wolfProvider/src/chapter05.md b/wolfProvider/src/chapter05.md index 25f709a1..521b8935 100644 --- a/wolfProvider/src/chapter05.md +++ b/wolfProvider/src/chapter05.md @@ -11,58 +11,84 @@ If not using Autoconf/configure, define `WOLFPROV_DEBUG` when compiling the wolf 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: -| 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 | +| Log Enum | Description | Log Enum Value | +| -------------- | --------------- |--------------------- | +| 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_DEFAULT | Default log level, all except verbose level | WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_ENTER | 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 | -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 includes `WP_LOG_LEVEL_ERROR`, `WP_LOG_LEVEL_ENTER`, `WP_LOG_LEVEL_LEAVE`, and `WP_LOG_LEVEL_INFO`. This includes all log levels except verbose logs (`WP_LOG_LEVEL_VERBOSE`). Log levels can be controlled using the `wolfProv_SetLogLevel(int mask)`. For example, to turn on only error and informative logs: ``` #include -ret = wolfProv_SetLogLevel(WP_LOG_ERROR | WP_LOG_INFO); +ret = wolfProv_SetLogLevel(WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_INFO); if (ret != 0) { printf(“Failed to set logging level\n”); } ``` -## Controlling Component Logging +## Controlling Component Logging at build time -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. The full list of components is defined in the wolfProvider_LogComponents enum 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 | Password Based Key Derivation Algorithms | 0x0040 | +| WP_LOG_COMP_PROVIDER | All provider specific logs | 0x0080 | +| WP_LOG_COMP_COMP_ALL | Log all components | WP_LOG_COMP_RNG | WP_LOG_COMP_DIGEST | WP_LOG_COMP_MAC | WP_LOG_COMP_CIPHER | WP_LOG_COMP_PK | WP_LOG_COMP_KE | WP_LOG_COMP_KDF | WP_LOG_COMP_PROVIDER | +| WP_LOG_COMP_DEFAULT | Default components logged (all). | WP_LOG_COMP_ALL | -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 -ret = wolfProv_SetLogComponents(WP_LOG_DIGEST | WP_LOG_CIPHER); +ret = wolfProv_SetLogComponents(WP_LOG_COMP_DIGEST | WP_LOG_COMP_CIPHER); if (ret != 0) { printf(“Failed to set log components\n”); } ``` + +## Controlling Component Logging at run time +wolfProvider allows runtime adjustments to the log settings through environment variables. `WOLFPROV_LOG_LEVEL` controls the log level, while `WOLFPROV_LOG_COMPONENTS` controls which components are logged. These values are expected to be strings in the format below. + +*Note that the environment variables can only control levels and components which have been enabled at build time.* + +``` +# Enable info logs only from the ED25519 block. +export WOLFPROV_LOG_LEVEL='WP_LOG_LEVEL_INFO' +export WOLFPROV_LOG_COMPONENTS='WP_LOG_COMP_ED25519' +``` + +``` +# Enable error and info logs only from the rsa and provider blocks. +export WOLFPROV_LOG_LEVEL='(WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_INFO)' +export WOLFPROV_LOG_COMPONENTS='(WP_LOG_LEVEL_RSA | WP_LOG_LEVEL_PROVIDER)' +``` + +``` +# Disable all wolfProvider logs +export WOLFPROV_LOG_LEVEL= +export WOLFPROV_LOG_COMPONENTS= +``` + +*Note that this functionality only applies to logs from wolfProvider, not logs from the wolfSSL library.* + ## Setting a Custom Logging Callback By default wolfProvider outputs debug log messages using **fprintf()** to **stderr**.