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
padelsbach 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();

@aidangarske aidangarske Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 [High] New OpenSSL key generation example uses the wrong API argument · bug

The new example passes osslLibCtx directly to EVP_PKEY_keygen, but EVP_PKEY_keygen operates on an EVP_PKEY_CTX, not an OSSL_LIB_CTX. This PR introduces a non-compilable OpenSSL example in the section explaining provider-context bypasses.

Fix: Update the snippet to use an EVP_PKEY_CTX created from the library context, or make the example explicit pseudocode instead of a C API sequence.

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.

@aidangarske aidangarske Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 [Low] Typo in new replace-default documentation · style

The new paragraph contains belive, which is a typo in user-facing documentation.

Fix: Fix the typo before publishing the updated manual.


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

@aidangarske aidangarske Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 [Medium] Runtime API is now described as build-time component logging · convention

The PR retitles the existing wolfProv_SetLogComponents(int mask) guidance as build-time control, but the API shown is a runtime setter. That conflicts with the new following section about runtime environment variables and can mislead readers about when the setting takes effect.

Fix: Retitle this section to describe API-based component selection, or add a separate build-time section that documents actual compile-time controls.


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 |

@aidangarske aidangarske Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 [High] Component table defines an all-components enum with the wrong name · bug

The PR changes the component enum table to list WP_LOG_COMP_COMP_ALL, but the very next row uses WP_LOG_COMP_ALL as the default value. That leaves the documented all-components enum inconsistent and likely invalid for users copying the table.

Fix: Rename the table entry to the actual all-components enum and keep the default row consistent with it.

| 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.

@aidangarske aidangarske Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 [High] Runtime component examples use level-prefixed or undocumented component names · bug

The new runtime examples set WOLFPROV_LOG_COMPONENTS with WP_LOG_COMP_ED25519, which is not present in the section's claimed full component list, and with WP_LOG_LEVEL_RSA | WP_LOG_LEVEL_PROVIDER, which uses the log-level prefix for component selection. This makes the new environment-variable examples internally inconsistent and likely unusable.

Fix: Use only valid WP_LOG_COMP_* component names in WOLFPROV_LOG_COMPONENTS, and add any newly supported components such as ED25519/RSA to the table if they really exist.

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