From d188b1dbba534c0f2c9631fb6dd998d5f8a96363 Mon Sep 17 00:00:00 2001 From: Sebastian Carpenter Date: Fri, 25 Jul 2025 15:53:32 -0600 Subject: [PATCH] wolfProvider - general documentation update --- wolfProvider/Makefile | 2 + wolfProvider/src/chapter01.md | 2 +- wolfProvider/src/chapter02.md | 1 + wolfProvider/src/chapter03.md | 163 ++++++++++++++++++++------------- wolfProvider/src/chapter04.md | 3 +- wolfProvider/src/chapter05.md | 17 ++-- wolfProvider/src/chapter07.md | 2 +- wolfProvider/src/chapter08.md | 166 +++++++++++++++++++++++++--------- wolfProvider/src/chapter09.md | 112 +++++++++++++++++------ 9 files changed, 324 insertions(+), 144 deletions(-) diff --git a/wolfProvider/Makefile b/wolfProvider/Makefile index 37e2a3ee..0f47fc5b 100644 --- a/wolfProvider/Makefile +++ b/wolfProvider/Makefile @@ -22,6 +22,8 @@ endif .PHONY: html-prep html-prep: + $(Q)cp png/*.png build/html/ .PHONY: pdf-prep pdf-prep: + $(Q)cp png/*.png build/pdf/ diff --git a/wolfProvider/src/chapter01.md b/wolfProvider/src/chapter01.md index bf31fc21..641d2ba1 100644 --- a/wolfProvider/src/chapter01.md +++ b/wolfProvider/src/chapter01.md @@ -7,6 +7,6 @@ wolfProvider is structured as a separate standalone library which links against For more details on the design and architecture of wolfProvider see the [wolfProvider Design](chapter09.md) chapter. -![wolfProvider Overview](../png/wolfprovider_overview.png) +![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. diff --git a/wolfProvider/src/chapter02.md b/wolfProvider/src/chapter02.md index 187d5b15..1ccf8355 100644 --- a/wolfProvider/src/chapter02.md +++ b/wolfProvider/src/chapter02.md @@ -3,5 +3,6 @@ wolfProvider has been tested against the following versions of OpenSSL. wolfProvider may work with other versions, but may require some modification or adjustment: - OpenSSL 3.0.0 +- OpenSSL 3.5.0 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 69084122..3c249608 100644 --- a/wolfProvider/src/chapter03.md +++ b/wolfProvider/src/chapter03.md @@ -9,14 +9,17 @@ The most recent version of wolfProvider can be obtained directly from wolfSSL In The general wolfProvider package is structured as follows: ``` -certs/ (Test certificates and keys, used with unit tests) -provider.conf (Example OpenSSL config file using wolfProvider) +certs/ (Test certificates and keys, used with unit tests) +examples/ (Code examples) include/ - wolfprovider/ (wolfProvider header files) -scripts/ (wolfProvider test scripts) -src/ (wolfProvider source files) -test/ (wolfProvider test files) -user_settings.h (EXAMPLE user_settings.h) + wolfprovider/ (wolfProvider header files) +IDE/ (Integration examples) +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: @@ -25,13 +28,25 @@ The quickest method is to use the `scripts/build-wolfprovider.sh` script as foll ./scripts/build-wolfprovider.sh ``` -It will retrieve the dependencies and compile them as necessary. To use other than the default (such as different releases) you can set various environment variables prior to calling the script: +It will clone, configure, compile, and install OpenSSL and wolfSSL with a default set of options. Two methods are available to override these defaults: + +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 +``` + +Specifying arguments for the script to parse: ``` -OPENSSL_TAG=openssl-3.2.0 WOLFSSL_TAG=v5.7.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 ``` -Alternatively, you can manually compile each component using the following guide. +Of course, these methods can be combined to achieve the desired build combination as well. + +For a full list of environment variables and script arguments do `./scripts/build-wolfprovider.sh --help`. + +If desired, each component can be manually compiled using the following guide. ### Building OpenSSL @@ -47,20 +62,21 @@ sudo make install ### 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 FIPSv2” 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 FIPSv2” bundle on Linux: ``` cd wolfssl-X.X.X-commercial-fips-linuxv -./configure **--enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP”** +./configure --enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP” make ./wolfcrypt/test/testwolfcrypt -< modify fips_test.c using verifyCore hash output from testwolfcrypt -> +< modify fips_test.c using verifyCore hash output from testwolfcrypt > make ./wolfcrypt/test/testwolfcrypt < all algorithms should PASS > sudo make install ``` +If available, it may be easier to instead `make` then run the `./fips-hash.sh` utility and then `make` once again. This utility automates the process of updating fips_test.c with the testwolfcrypt hash output. + To build non-FIPS wolfSSL for use with wolfProvider: ``` cd wolfssl-X.X.X @@ -178,15 +194,25 @@ The following are options which may be appended to the `./configure` script to c By default, wolfProvider only builds a shared library, with building of a static library disabled. This speeds up build times by a factor of two. Either mode can be explicitly disabled or enabled if desired. -| Option | Default Value | Description | -| :--------- | :---------------: | :-------------- | -| --enable-static | **Disabled** | Build static libraries | -| --enable-shared | Enabled | Build shared libraries | -| --enable-debug | **Disabled** | Enable wolfProvider debugging support | -| --enable-coverage | **Disabled** | Build to generate code coverage stats | +| Option | Default Value | Description | +| :---------------- | :---------------: | :----------------------------- | +| --disable-option-checking | **Disabled** | | ignore unrecognized --enable/--with options | +| --enable-silent-rules | **Disabled** | less verbose build output (undo: "make V=1") | +| --disable-silent-rules | **Disabled** | verbose build output (undo: "make V=0") | +| --enable-static | **Disabled** | Build static libraries | +| --enable-pic[=PKGS] | **Use Both** | try to use only PIC/non-PIC objects | +| --enable-shared | **Enabled** | Build shared libraries | +| --enable-fast-install[=PKGS] | **Enabled** | optimize for fast installation | +| --enable-aix-soname=aix\|svr4\|both | **aix** | shared library versioning (aka "SONAME") variant to provide on AIX | +| --enable-dependency-tracking | **Disabled** | do not reject slow dependency extractors | +| --disable-dependency-tracking | **Disabled** | speeds up one-time build | +| --disable-libtool-lock | **Disabled** | avoid locking (might break parallel builds) | +| --enable-debug | **Disabled** | Enable wolfProvider debugging support | +| --enable-coverage | **Disabled** | Build to generate code coverage stats | | --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-dynamic | **Enabled** | Enable loading wolfProvider as a dynamic provider | | --enable-singlethreaded | **Disabled** | Enable wolfProvider single threaded | +| | | | | --with-openssl=DIR | | OpenSSL installation location to link against. If not set, use the system default library and include paths. | | --with-wolfssl=DIR | | wolfSSL installation location to link against. If not set, use the system default library and include paths. | @@ -194,46 +220,57 @@ By default, wolfProvider only builds a shared library, with building of a static wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below. -| Define | Description | -| :---------------------------------------------- | :-------------- | -| WOLFPROVIDER_DEBUG | Build wolfProvider with debug symbols, optimization level, and debug logging. | -| WP_NO_DYNAMIC_PROVIDER | Do not build wolfProvider with dynamic provider support. Dynamic providers are ones that can be loaded into OpenSSL at runtime. | -| WP_SINGLE_THREADED | Build wolfProvider in single-threaded mode. This removes the need for locking around global resources used internally. | -| WP_USE_HASH | Enable digest algorithms using the wc_Hash API. | -| WP_HAVE_SHA1 | Enable SHA-1 digest algorithm. | -| WP_HAVE_SHA224 | Enable SHA-2 digest algorithm with digest size 224. | -| WP_HAVE_SHA256 | Enable SHA-2 digest algorithm with digest size 256. | -| WP_HAVE_SHA384 | Enable SHA-2 digest algorithm with digest size 384. | -| WP_HAVE_SHA512| Enable SHA-2 digest algorithm with digest size 512. | -| WP_SHA1_DIRECT | Enable the SHA-1 digest algorithm using the wc_Sha API. Incompatible with WP_USE_HASH. | -| WP_SHA224_DIRECT | Enable the SHA-2 224 digest algorithm using the wc_Sha224 API. Incompatible with WP_USE_HASH. | -| WP_SHA256_DIRECT | Enable the SHA-2 256 digest algorithm using the wc_Sha256 API. Incompatible with WP_USE_HASH. | -| WP_HAVE_SHA3_224 | Enable SHA-3 digest algorithm with digest size 224. Not available in OpenSSL 1.0.2. | -| WP_HAVE_SHA3_256 | Enable SHA-3 digest algorithm with digest size 256. Not available in OpenSSL 1.0.2. | -| WP_HAVE_SHA3_384 | Enable SHA-3 digest algorithm with digest size 384. Not available in OpenSSL 1.0.2. | -| WP_HAVE_SHA3_512 | Enable SHA-3 digest algorithm with digest size 512. Not available in OpenSSL 1.0.2. | -| WP_HAVE_EVP_PKEY | Enable functionality that uses the EVP_PKEY API. This includes things like RSA, DH, etc. | -| WP_HAVE_CMAC | Enable CMAC algorithm. | -| WP_HAVE_HMAC | Enable HMAC algorithm. | -| WP_HAVE_DES3CBC | Enable DES3-CBC algorithm. | -| WP_HAVE_AESECB | Enable AES algorithm with ECB mode. | -| WP_HAVE_AESCBC | Enable AES algorithm with CBC mode. | -| WP_HAVE_AESCTR | Enable AES algorithm with countee mode. | -| WP_HAVE_AESGCM | Enable AES algorithm with GCM mode. | -| WP_HAVE_AESCCM |Enable AES algorithm with CCM mode. | -| WP_HAVE_RANDOM | Enable wolfCrypt random implementation. | -| WP_HAVE_RSA | Enable RSA operations (e.g. sign, verify, key generation, etc.). | -| WP_HAVE_DH | Enable Diffie-Hellman operations (e.g. key generation, shared secret computation, etc.). | -| WP_HAVE_ECC | Enable support for elliptic curve cryptography. | -| WP_HAVE_EC_KEY | Enable support for EC_KEY_METHOD. Not available in OpenSSL 1.0.2. | -| WP_HAVE_ECDSA | Enable ECDSA algorithm. | -| WP_HAVE_ECDH | Enable EC Diffie-Hellman operations. | -| WP_HAVE_ECKEYGEN | Enable EC key generation. | -| WP_HAVE_EC_P192 | Enable EC curve P192. | -| WP_HAVE_EC_P224 | Enable EC curve P224. | -| WP_HAVE_EC_P256 | Enable EC curve P256. | -| WP_HAVE_EC_P384 | Enable EC curve P384. | -| WP_HAVE_EC_P512 | Enable EC curve P512. | -| WP_HAVE_DIGEST | Compile code in benchmark program and unit tests for use with digest algorithms. | +| Define | Description | +| :------------------------------- | :----------------------------- | | WOLFPROVIDER_USER_SETTINGS | Read user-specified defines from user_settings.h. | - +| 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 | +| WP_HAVE_AESCCM | AES encryption in CCM (Counter with CBC-MAC) mode | +| WP_HAVE_AESCFB | AES encryption in CFB (Cipher Feedback) mode | +| WP_HAVE_AESCBC | AES encryption in CBC (Cipher Block Chaining) mode | +| WP_HAVE_AESCTR | AES encryption in CTR (Counter) mode | +| WP_HAVE_AESCTS | AES encryption in CTS (Ciphertext Stealing) mode | +| WP_HAVE_AESECB | AES encryption in ECB (Electronic Codebook) mode | +| WP_HAVE_AESGCM | AES encryption in GCM (Galois/Counter Mode) mode | +| WP_HAVE_CMAC | CMAC (Cipher-based Message Authentication Code) support | +| WP_HAVE_DES3CBC | Triple DES encryption in CBC mode | +| WP_HAVE_DH | Diffie-Hellman key exchange support | +| WP_HAVE_DIGEST | General digest/hash algorithm support | +| WP_HAVE_ECC | General Elliptic Curve Cryptography support | +| WP_HAVE_EC_P192 | P-192 elliptic curve support | +| WP_HAVE_EC_P224 | P-224 elliptic curve support | +| WP_HAVE_EC_P256 | P-256 elliptic curve support | +| WP_HAVE_EC_P384 | P-384 elliptic curve support | +| WP_HAVE_EC_P521 | P-521 elliptic curve support | +| WP_HAVE_ECDH | ECDH (Elliptic Curve Diffie-Hellman) key exchange support | +| WP_HAVE_ECDSA | ECDSA (Elliptic Curve Digital Signature Algorithm) support | +| WP_HAVE_ECKEYGEN | Elliptic curve key generation support | +| WP_HAVE_ED25519 | Ed25519 elliptic curve signature support | +| WP_HAVE_ED448 | Ed448 elliptic curve signature support | +| 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_KRB5KDF | Kerberos 5 Key Derivation Function support | +| WP_HAVE_MD5 | MD5 hash algorithm support | +| WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support | +| WP_HAVE_PBE | Password-Based Encryption support | +| WP_HAVE_RANDOM | Random number generation support | +| WP_HAVE_RSA | RSA encryption and signature support | +| WP_HAVE_SHA1 | SHA1 hash algorithm support | +| WP_HAVE_SHA224 | SHA224 hash algorithm support | +| WP_HAVE_SHA256 | SHA256 hash algorithm support | +| WP_HAVE_SHA384 | SHA384 hash algorithm support | +| WP_HAVE_SHA3 | SHA3 family hash algorithm support | +| WP_HAVE_SHA3_224 | SHA3-224 hash algorithm support | +| WP_HAVE_SHA3_256 | SHA3-256 hash algorithm support | +| WP_HAVE_SHA3_384 | SHA3-384 hash algorithm support | +| WP_HAVE_SHA3_512 | SHA3-512 hash algorithm support | +| WP_HAVE_SHA512 | SHA512 hash algorithm support | +| 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_TLS1_PRF | TLS1 Pseudo-Random Function support | +| WP_HAVE_X25519 | X25519 elliptic curve support | +| WP_HAVE_X448 | X448 elliptic curve support | +| WP_RSA_PSS_ENCODING | RSA-PSS (Probabilistic Signature Scheme) encoding support | diff --git a/wolfProvider/src/chapter04.md b/wolfProvider/src/chapter04.md index e71350af..99513ece 100644 --- a/wolfProvider/src/chapter04.md +++ b/wolfProvider/src/chapter04.md @@ -6,7 +6,6 @@ Note that wolfCrypt FIPS libraries cannot be “switched” into non-FIPS mode. 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. -**NOTE** : If targeting FIPS compliance,and non-wolfCrypt FIPS algorithms are called from a different provider, those algorithms are outside the scope of -wolfProvider and wolfCrypt FIPS and may not be FIPS validated. +**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 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 07f67695..25f709a1 100644 --- a/wolfProvider/src/chapter05.md +++ b/wolfProvider/src/chapter05.md @@ -5,7 +5,7 @@ wolfProvider supports output of log messages for informative and debug purposes. ./configure --enable-debug ``` -If not using Autoconf/configure, define `WOLFPROVIDER_DEBUG` when compiling the wolfProvider library. +If not using Autoconf/configure, define `WOLFPROV_DEBUG` when compiling the wolfProvider library. ## Controlling Logging Levels @@ -19,7 +19,7 @@ wolfProvider supports the following logging levels. These are defined in the “ | 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 WP_LOG_ERROR | All log levels are enabled | WP_LOG_ENTER | WP_LOG_LEAVE | WP_LOG_INFO | WP_LOG_VERBOSE | +WP_LOG_LEVEL_ALL | All log levels are enabled | WP_LOG_ERROR | WP_LOG_ENTER | WP_LOG_LEAVE | WP_LOG_INFO | WP_LOG_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`). @@ -46,14 +46,15 @@ wolfProvider allows logging on a per-component basis. Components are defined in | 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_PROVIDER | All provider specific logs | 0x0040 | -| 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_PROVIDER | +| 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 | The default wolfProvider logging configuration logs all components (`WP_LOG_COMPONENTS_DEFAULT`). -Components logged can be controlled using the `wolfProv_SetLogComponents(int mask)`. For example, to turn on only logging only for the Digest and Cipher algorithms: +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 @@ -74,13 +75,13 @@ 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 (* wolfProvider_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, +void customLogCallback (const int logLevel, const int component, const char* const logMessage) { (void)logLevel; @@ -88,7 +89,7 @@ const char* const logMessage) fprintf(stderr, “wolfProvider log message: %d\n”, logMessage); } -int **main** (void) +int main (void) { int ret; ... diff --git a/wolfProvider/src/chapter07.md b/wolfProvider/src/chapter07.md index 7e36c42f..3bbe0ae9 100644 --- a/wolfProvider/src/chapter07.md +++ b/wolfProvider/src/chapter07.md @@ -10,7 +10,7 @@ If the application is configured to read/use an OpenSSL config file, additional [OpenSSL 3.0](https://www.openssl.org/docs/man3.0/man5/config.html) -An application can read and consume the default OpenSSL config file (openssl.cnf) or config as set by OPENSSL\_CONF environment variable, and default [openssl\_conf] section. +An application can read and consume the default OpenSSL config file (openssl.cnf) or config as set by OPENSSL\_CONF environment variable and default [openssl\_conf] section. Alternatively to using an OpenSSL config file, applications can explicitly initialize and register wolfProvider using the desired OSSL\_PROVIDER_\* APIs. As one example, initializing wolfProvider and registering for all algorithms could be done using: ``` diff --git a/wolfProvider/src/chapter08.md b/wolfProvider/src/chapter08.md index f43b692d..990edad8 100644 --- a/wolfProvider/src/chapter08.md +++ b/wolfProvider/src/chapter08.md @@ -1,54 +1,136 @@ # wolfProvider Design -wolfProvider is composed of the following source files, all located under the “src” subdirectory of the wolfProvider package. +wolfProvider is composed of the following source files, all located under the "src" subdirectory of the wolfProvider package. | Source File | Description | | --------------- | ---------------- | -| wp_wolfprovider.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_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_logging.c | wolfProvider logging framework and function implementations. | -| wp_openssl_bc.c | wolfProvider OpenSSL binary compatibility abstraction layer, used for supporting wolfProvider across multiple OpenSSL versions. | +| wp_aes_aead.c | wolfProvider AES-AEAD (Authenticated Encryption with Associated Data) implementation. | | wp_aes_block.c | wolfProvider AES-ECB and AES-CBC implementation. | -| wp_aes_cbc_hmac.c | wolfProvider AES-CBC-HMAC implementation. | -| wp_aes_ccm.c | wolfProvider AES-CCM implementation. | -| wp_aes_ctr.c | wolfProvider AES-CTR implementation. | -| wp_aes_gcm.c | wolfProvider AES-GCM implementation. | -| wp_des3_cbc.c | wolfProvider 3DES-CBC implementation. | -| wp_dh.c | wolfProvider DH implementation. | -| wp_digest.c | wolfProvider message digest implementations (SHA-1, SHA-2, SHA-3). | -| wp_ecc.c | wolfProvider ECDSA and ECDH implementation. | -| wp_mac.c | wolfProvider HMAC and CMAC implementations. | -| wp_random.c | wolfProvider RAND implementation. | -| wp_rsa.c | wolfProvider RSA implementation. | -| wp_tls_prf.c | wolfProvider TLS 1.0 PRF implementation. | +| wp_aes_stream.c | wolfProvider AES stream cipher implementation. | +| wp_aes_wrap.c | wolfProvider AES key wrapping implementation. | +| wp_cmac.c | wolfProvider CMAC (Cipher-based Message Authentication Code) implementation. | +| wp_dec_epki2pki.c | wolfProvider encrypted private key to private key conversion implementation. | +| wp_dec_pem2der.c | wolfProvider PEM to DER format conversion implementation. | +| wp_des.c | wolfProvider DES implementation. | +| wp_dh_exch.c | wolfProvider DH key exchange implementation. | +| 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_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. | +| wp_ecx_exch.c | wolfProvider ECX key exchange implementation (X25519, X448, ...). | +| wp_ecx_kmgmt.c | wolfProvider ECX key management implementation. | +| wp_ecx_sig.c | wolfProvider ECX signature implementation (Ed25519, Ed448, ...). | +| wp_file_store.c | wolfProvider file storage implementation. | +| wp_fips.c | wolfProvider FIPS validation implementation. | +| wp_gmac.c | wolfProvider GMAC (Galois/Counter Mode) implementation. | +| wp_hkdf.c | wolfProvider HKDF (HMAC-based Key Derivation Function) implementation. | +| wp_hmac.c | wolfProvider HMAC implementation. | +| wp_kbkdf.c | wolfProvider KBKDF (Key-Based Key Derivation Function) implementation. | +| wp_kdf_exch.c | wolfProvider KDF key exchange implementation. | +| wp_kdf_kmgmt.c | wolfProvider KDF key management implementation. | +| wp_krb5kdf.c | wolfProvider Kerberos 5 KDF implementation. | +| wp_mac_kmgmt.c | wolfProvider MAC key management implementation. | +| 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_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_tls1_prf.c | wolfProvider TLS 1.0 PRF implementation. | +| wp_tls_capa.c | wolfProvider TLS capabilities implementation. | ## wolfProvider Entry Points -The main entry points into the wolfProvider library are either **wolfprovider_bind** () or **PROVIDER_load_wolfprovider** (). wolfprovider_bind() is called automatically by OpenSSL if wolfProvider has been loaded dynamically. PROVIDER_load_wolfprovider() is the entry point applications must call if wolfProvider has been built and used statically instead of dynamically. - -## wolfProvider Algorithm Callback Registration - -wolfProvider registers algorithm structures and callbacks with the OpenSSL provider framework for all supported components of wolfCrypt FIPS. This registration happens inside `wolfprovider_bind()` in `wp_internal.c`. `wolfprovider_bind()` receives an PROVIDER structure pointer -representing the wolfProvider provider. Individual algorithm/component callbacks or structures are then registered with that PROVIDER structure using the appropriate API from . - -These API calls include the following: -``` -PROVIDER_set_id(e, wolfprovider_id) -PROVIDER_set_name(e, wolfprovider_name) -PROVIDER_set_digests(e, wp_digests) -PROVIDER_set_ciphers(e, wp_ciphers) -PROVIDER_set_RAND(e, wp_random_method) -PROVIDER_set_RSA(e, wp_rsa()) -PROVIDER_set_DH(e, wp_dh_method) -PROVIDER_set_ECDSA(e, wp_ecdsa()) -PROVIDER_set_pkey_meths(e, wp_pkey) -PROVIDER_set_pkey_asn1_meths(e, wp_pkey_asn1) -PROVIDER_set_EC(e, wp_ec()) -PROVIDER_set_ECDH(e, wp_ecdh()) -PROVIDER_set_destroy_function(e, wolfprovider_destroy) -PROVIDER_set_cmd_defns(e, wolfprovider_cmd_defns) -PROVIDER_set_ctrl_function(e, wolfprovider_ctrl) -``` - -Each algorithm/component callback function or structure used in the above calls (ex: wp_digests, wp_ciphers, etc) are implemented in either `wp_internal.c` or in the respective algorithm source file. +The main entry points into the wolfProvider library are **OSSL_provider_init()** and **wolfssl_provider_init()**. + +**OSSL_provider_init()** is the standard OpenSSL provider entry point that is called automatically by OpenSSL when the provider is loaded dynamically. This function is defined in `wp_wolfprov.c` and serves as a wrapper that calls `wolfssl_provider_init()`. + +**wolfssl_provider_init()** is the core initialization function that: + +- Sets up the provider context +- Initializes the dispatch table with provider functions +- Handles FIPS mode configuration +- Sets up debugging if enabled +- Returns the provider's dispatch table containing function pointers for: + + * `wolfprov_teardown` - Provider cleanup + * `wolfprov_gettable_params` - Parameter table retrieval + * `wolfprov_get_params` - Parameter retrieval + * `wolfprov_query` - Operation querying + * `wolfssl_prov_get_capabilities` - Capability reporting + +The provider is loaded by OpenSSL when applications request wolfProvider algorithms, and the dispatch table allows OpenSSL to call the appropriate wolfProvider functions for cryptographic operations. + +## wolfProvider Dispatch Table Functions + +The wolfProvider dispatch table contains several key functions that handle different aspects of provider operation. Each function serves a specific purpose in the OpenSSL provider framework. + +**Note on OSSL Parameters (Referenced Later):** OSSL parameters are a standardized way for OpenSSL to exchange configuration data and capabilities information with providers. Parameters can represent simple values (integers, strings, booleans) or complex structures, and they enable applications to query provider capabilities, configure behavior, and retrieve status information. The parameter system provides a type-safe, extensible mechanism for provider-application communication. + +### 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. + +### wolfprov_gettable_params + +The `wolfprov_gettable_params()` function returns a table of parameter descriptors that define what parameters the provider supports. This function accomplishes the following tasks: + +- Defines the structure and types of parameters that can be retrieved +- Provides metadata about parameter names, types, and descriptions +- Enables OpenSSL to understand what parameters are available from the provider +- Supports parameter validation and type checking +- Allows applications to discover available provider parameters + +The returned table contains parameter definitions that applications can use to query provider capabilities and configuration options. + +### wolfprov_get_params + +The `wolfprov_get_params()` function retrieves specific parameter values from the provider. This function: + +- Accepts parameter requests from OpenSSL or applications +- Returns the current values of requested parameters +- Handles parameter type conversion and validation +- 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. + +### wolfssl_prov_get_capabilities + +The `wolfssl_prov_get_capabilities()` function reports the cryptographic capabilities of wolfProvider to OpenSSL. It provides capability information which: + +- 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 capabilities information helps OpenSSL determine when to use wolfProvider algorithms and how to configure them appropriately for different use cases. + +### wolfprov_query + +The `wolfprov_query()` function is the primary mechanism for algorithm discovery and registration in wolfProvider. It serves as the central routing mechanism that: + +- Handles requests from OpenSSL for specific algorithm implementations +- Returns the appropriate algorithm structure when a supported algorithm is requested +- Provides operation-specific dispatch tables for cryptographic operations +- Manages algorithm registration and lookup within the provider +- Supports both symmetric and asymmetric cryptographic operations +- Enables dynamic algorithm discovery based on OpenSSL's requirements + +When OpenSSL requests an algorithm (such as AES, RSA, SHA-256, etc.), `wolfprov_query()` determines if wolfProvider supports that algorithm and returns the corresponding implementation structure. This function acts as the central routing mechanism that connects OpenSSL's algorithm requests to the specific wolfProvider implementations found in the various source files (e.g., `wp_aes_block.c`, `wp_rsa_sig.c`, etc.). diff --git a/wolfProvider/src/chapter09.md b/wolfProvider/src/chapter09.md index 5ccfba0e..225ffbde 100644 --- a/wolfProvider/src/chapter09.md +++ b/wolfProvider/src/chapter09.md @@ -1,39 +1,97 @@ # Notes on Open Source Integration -wolfProvider conforms to the general OpenSSL provider framework and architecture. As such, it can be leveraged from any OpenSSL-consuming application that correctly loads and initializes providers and wolfProvider through OpenSSL configuration file or programmatically via PROVIDER API calls. +wolfProvider conforms to the general OpenSSL provider framework and architecture. As such, it can be leveraged from any OpenSSL-consuming application that correctly loads and initializes providers and wolfProvider through an OpenSSL configuration file or programmatically via API calls. -wolfSSL has tested wolfProvider with several open source projects. This chapter contains notes and tips on wolfProvider integration. This chapter is not comprehensive of all open source project support with wolfProvider, and will be expanded upon as wolfSSL or the community reports testing and using wolfProvider with additional open source projects. +wolfSSL has tested wolfProvider with numerous open source projects through automated CI/CD workflows. This chapter contains notes and tips on wolfProvider integration with the tested projects. -## cURL +## Tested Open Source Projects -cURL is already set up to leverage an OpenSSL config file. To leverage wolfProvider: +The following Open Source Projects (OSPs) have been tested and verified to work with wolfProvider: -1. Add wolfProvider provider information to your OpenSSL config file -2. If needed, set OPENSSL_CONF environment variable to point to your OpenSSL config file: -``` -$ export OPENSSL_CONF=/path/to/openssl.cnf -``` -3. Set OPENSSL_PROVIDERS environment variable to point to location of wolfProvider shared library file: -``` -$ export OPENSSL_PROVIDERS=/path/to/wolfprovider/library/dir -``` -## stunnel +### Network and Web Technologies +* cURL - Command line tool for transferring data with URLs +* gRPC - High-performance RPC framework +* libwebsockets - Lightweight C library for websockets +* Nginx - High-performance HTTP server and reverse proxy +* Qt5 Network - Qt networking module -stunnel has been tested with wolfProvider. Notes coming soon. +### Security and Authentication +* OpenSSH - Secure shell implementation +* libssh2 - SSH2 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 -## OpenSSH +### 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 -OpenSSH needs to be compiled with OpenSSL provider support using the `--with-ssl-provider` configure option. If needed, `--with-ssl-dir=DIR` can also be used to specify the installation location of the OpenSSL library being used: -``` -$ cd openssh -$ ./configure --prefix=/install/path --with-ssl-dir=/path/to/openssl/install ---with-ssl-provider -$ make -$ sudo make install -``` +### Directory and Identity Services +* OpenLDAP - Lightweight Directory Access Protocol +* SSSD - System Security Services Daemon +* Net-SNMP - Network management protocol implementation + +### Cryptography and PKI +* cjose - C library for JWT +* libeac3 - Electronic Authentication Components +* libhashkit2 - Consistent hashing library +* liboauth2 - OAuth2 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 -OpenSSH will also need an OpenSSL config file set up to leverage wolfProvider. If needed, the OPENSSL_CONF environment variable can be set to point to your config file. The OPENSSL_PROVIDERS environment variable may also need to be set to the location of the wolfProvider shared library: +### Other Utilities +* Socat - Multipurpose relay for bidirectional data transfer +* Simple - Simple test applications + +## General Setup +Most of these projects require similar setup steps: + +1. Clone from Github +2. Build with Autotools +3. Configure with OpenSSL +4. Make and Install +5. Use wolfProvider: + ``` + export OPENSSL_CONF=/path/to/provider.conf + export OPENSSL_MODULES=/path/to/wolfprov-install/lib + ``` + +After running make (or the equivalent build script) the configured version of OpenSSL can be checked by running `ldd /path/to/compiled/binary`. This will provide a list of which libraries are linked against. If the incorrect version is present then setting some combination of these four environment variables before rebuilding may help: ``` -$ export OPENSSL_CONF=/path/to/openssl.cnf -$ export OPENSSL_PROVIDERS=/path/to/wolfprovider/library/dir +export LD_LIBRARY_PATH="/path/to/wolfssl/install/lib:/path/to/openssl/install/lib64" +export PKG_CONFIG_PATH="/path/to/openssl/install/lib64/pkgconfig" +export LDFLAGS="-L/path/to/openssl/install/lib64" +export CPPFLAGS="-I/path/to/openssl/install/include" ``` + +Further, wolfProvider gives some ability to determine if the library is actually using wolfProvider. Just do `export WOLFPROV_FORCE_FAIL=1` or `WOLFPROV_FORCE_FAIL=1 /command/to/run` and if the command ends up using wolfProvider crypto it will fail. + +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: + +* 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 + +This comprehensive testing ensures that wolfProvider maintains compatibility with a wide range of open source projects and their various use cases.