Skip to content

Update wolfProvider docs following v1.1.0 #231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update wolfProvider docs following v1.1.0 #231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions wolfProvider/src/chapter03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down
76 changes: 51 additions & 25 deletions wolfProvider/src/chapter05.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <wolfprovider/wp_logging.h>

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 &#124; WP_LOG_DIGEST &#124; WP_LOG_MAC &#124; WP_LOG_CIPHER &#124; WP_LOG_PK &#124; WP_LOG_KE &#124; WP_LOG_KDF &#124; 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 &#124; WP_LOG_COMP_DIGEST &#124; WP_LOG_COMP_MAC &#124; WP_LOG_COMP_CIPHER &#124; WP_LOG_COMP_PK &#124; WP_LOG_COMP_KE &#124; WP_LOG_COMP_KDF &#124; 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 <wolfprovider/wp_logging.h>

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**.
Expand Down