wolfSSL Embedded SSL/TLS Library

The wolfSSL embedded SSL library (formerly CyaSSL) is a lightweight SSL/TLS library written in ANSI C and targeted for embedded, RTOS, and resource-constrained environments - primarily because of its small size, speed, and feature set. It is commonly used in standard operating environments as well because of its royalty-free pricing and excellent cross platform support. wolfSSL supports industry standards up to the current TLS 1.3 and DTLS 1.3, is up to 20 times smaller than OpenSSL, and offers progressive ciphers such as ChaCha20, Curve25519, BLAKE2b/BLAKE2s and Post-Quantum TLS 1.3 groups. User benchmarking and feedback reports dramatically better performance when using wolfSSL over OpenSSL.

wolfSSL is powered by the wolfCrypt cryptography library. Two versions of wolfCrypt have been FIPS 140-2 validated (Certificate #2425 and certificate #3389). FIPS 140-3 validated (Certificate #4718). For additional information, visit the wolfCrypt FIPS FAQ or contact fips@wolfssl.com.

wolfCrypt also includes support for deriving device-unique keys from hardware entropy (--enable-puf[=small|balanced|strong|strongest], selecting the BCH error-correction strength). Each raw SRAM readout is health tested before use, so a degenerate readout - all zero, all ones, a repeating block, or an implausible bit bias - cannot silently produce a device-independent key. An example exists at SRAM PUF.

Why Choose wolfSSL?

There are many reasons to choose wolfSSL as your embedded, desktop, mobile, or enterprise SSL/TLS solution. Some of the top reasons include size (typical footprint sizes range from 20-100 kB), support for the newest standards (SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, DTLS 1.0, DTLS 1.2, and DTLS 1.3), current and progressive cipher support (including stream ciphers), multi-platform, royalty free, and an OpenSSL compatibility API to ease porting into existing applications which have previously used the OpenSSL package. For a complete feature list, see Chapter 4 of the wolfSSL manual.

SBOM / CRA Compliance

wolfSSL provides a Software Bill of Materials (SBOM) for EU Cyber Resilience Act (CRA) compliance via two entry points:

• python3 scripts/gen-sbom … for embedded / RTOS / IDE-based builds (Keil, IAR, STM32CubeIDE, ESP-IDF, Zephyr, plain CMake, custom Makefile) configured through a hand-edited user_settings.h. No autotools required.
• make sbom for Linux server / Debian / RPM / Yocto / FIPS-Ready builds that already use ./configure && make.

Both produce SPDX 2.3 + CycloneDX 1.6 JSON intended to satisfy the NTIA minimum elements. The make sbom path additionally runs SPDX-spec validation via pyspdxtools and gates the build on it; the standalone path validates only on demand (see doc/SBOM.md § 1.3). Neither path runs an NTIA-minimum-elements checker by default. See doc/SBOM.md for per-toolchain recipes and the full flag reference.

OmniBOR / Bomsh

wolfSSL supports generating an OmniBOR artifact dependency graph via make bomsh, providing cryptographic traceability from the installed library back to every source file that produced it. See doc/SBOM.md for details.

Security advisories (CSAF / VEX)

wolfSSL can generate machine-readable security advisories via make advisory (requires python3), emitting one CSAF 2.0 document and one CycloneDX 1.6 VEX document per CVE into advisories/out/ (*.csaf.json and *.cdx.json) from the git-tracked records under advisories/. See section 21 of INSTALL for details.

Notes, Please Read

Note 1

wolfSSL as of 3.6.6 no longer enables SSLv3 by default. By default, wolfSSL disables static key cipher suites that use PSK, RSA, or ECDH without ephemeral key exchange. Instead, wolfSSL enables cipher suites that provide perfect forward secrecy (PFS) using ephemeral Diffie-Hellman (DH) or Elliptic Curve (ECC) key exchange, both of which are enabled by default.

If you need to support legacy systems that require static key cipher suites, you can enable them using one or more of these defines:

• WOLFSSL_STATIC_DH
• WOLFSSL_STATIC_RSA
• WOLFSSL_STATIC_PSK

Important: Static key cipher suites reduce security by eliminating perfect forward secrecy. These cipher suites reuse the same long-term private key for all session key exchanges. In contrast, PFS-enabled cipher suites (the wolfSSL default) generate a new ephemeral key for each session, ensuring that compromising a long-term key cannot decrypt past sessions.

When compiling ssl.c, wolfSSL will now issue a compiler error if no cipher suites are available. You can remove this error by defining WOLFSSL_ALLOW_NO_SUITES in the event that you desire that, i.e., you're not using TLS cipher suites.

AES CryptoCB Key Import Support

wolfSSL supports hardware-accelerated AES operations via CryptoCB.

When WOLF_CRYPTO_CB_AES_SETKEY is defined, wolfSSL invokes a CryptoCB callback during AES key setup. The callback behavior determines the mode:

If callback returns 0 (success) and leaves aes->rounds at 0: - Key is imported to Secure Element/HSM - Key is NOT copied to wolfSSL RAM (true key isolation) - GCM tables are NOT generated (full hardware offload) - All subsequent AES operations route through CryptoCB; in default builds a mode the callback declines returns MISSING_KEY, as does streaming AES-GCM

A callback that sets aes->rounds must also build a software key schedule, since wolfSSL then treats the key as a software key as well. It does so by calling wc_AesSetKey() on the same object with aes->devId set to a devId no device is registered under, then restoring it. INVALID_DEVID only works without WOLF_CRYPTO_CB_FIND, whose find callback can map it back to the device. This request carries no key direction, so only a WOLF_CRYPTO_CB_SETKEY callback, which is given one, can build it.

If callback returns CRYPTOCB_UNAVAILABLE: - SE doesn't support key import - Normal software AES path is used - Key is copied to devKey for CryptoCB encrypt/decrypt acceleration - The callback must first release any key it holds for this object and set aes->devCtx to NULL, since wolfSSL does not clear it

This feature enables TLS 1.3 traffic key protection on embedded platforms where symmetric keys must never exist in main RAM.

Enable with: CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE"

Note 2

wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, no signer error to confirm failure (-188).

If you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling:

wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_NONE, NULL);

before calling wolfSSL_new();. Though it's not recommended.

Note 3

The enum values SHA, SHA256, SHA384, SHA512 are no longer available when wolfSSL is built with --enable-opensslextra (OPENSSL_EXTRA) or with the macro NO_OLD_SHA_NAMES. These names get mapped to the OpenSSL API for a single call hash function. Instead the name WC_SHA, WC_SHA256, WC_SHA384 and WC_SHA512 should be used for the enum name.

wolfSSL Release 5.9.4 (Sep 25, 2026)

Release 5.9.4 has been developed according to wolfSSL's development and QA process (see link below) and successfully passed the quality criteria. https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance

NOTE: * liboqs is no longer used for any algorithm: Falcon now has a native wolfCrypt implementation, and the liboqs dependency and its configure and CMake options have been removed (see PQC below). * Certificates carrying trailing bytes after the DER structure are now rejected unless WOLFSSL_NO_ASN_STRICT is defined; only the certificate itself is copied into WOLFSSL_X509. * ABI: struct OcspRequest (exported as OCSP_REQUEST) loses its trailing ssl pointer; consumers that embed the struct must be rebuilt. * Under FIPS: HMAC-MD5 is rejected, AES-GCM encryption with an IV shorter than 12 bytes returns FIPS_BAD_VALUE_E (override with WC_FIPS_AESGCM_ALLOW_SHORT_NONCES), the CMAC minimum tag is 64 bits, and RSA-PSS salts longer than the hash are refused (FIPS 186-5). --enable-wolfclu no longer enables MD5, Ed25519 or ASN relaxation on FIPS builds.

PR stands for Pull Request, and PR references a GitHub pull request number where the code change was added.

Vulnerabilities

• [High] CVE-2026-93302 MatchTrustedPeer ignores the public key used, leading to forged CA clones passing verification. Affected builds are any that enable the macro WOLFSSL_TRUST_PEER_CERT and load CA certificates with wolfSSL_CTX_trust_peer_cert() or wolfSSL_trust_peer_cert(). The peer must know the certificates being loaded to either of those APIs to take advantage of the issue. When OPENSSL_COMPATIBLE_DEFAULTS is also defined this widens the affected API to include all CA certificate loading. Both macros are defined when using autoconf builds such as (nginx, haproxy, stunnel, wpas, apache httpd, hitch, bind, rsyslog, ffmpeg, all, distro). When the certificate is listed as a trusted peer certificate the issue previously allowed for a malicious (D)TLS server to bypass authentication once knowing which CA’s the client would accept. This also affects mutual authentication cases where the client knows which CA’s the server has loaded. If building with any of these configurations and using (D)TLS where the loaded CA’s could be known and authentication of the peer is desired, users should either: update to the latest wolfSSL version, apply the fix patch, or use the configure flag --disable-openssl-compatible-defaults and not load CA’s with wolfSSL_CTX_trust_peer_cert() or wolfSSL_trust_peer_cert() to mitigate the issue. The affected certificate verification path with (D)TLS is in wolfSSL versions 5.3.0 to 5.9.2. Found via the Anthropic OSS program. Fixed in commit https://github.com/wolfSSL/wolfssl/commit/22bcd51d553eaac1de37bee91fdac80cc47961e1

• [High] CVE-2026-89102 In wolfSSL versions 5.7.2 through 5.9.2 there is a client-side implementation flaw in RFC 6961, multiple OCSP response stapling, which can lead to certificate forgery. When a wolfSSL client enables OCSP stapling with the HAVE_CERTIFICATE_STATUS_REQUEST_V2 feature and calls wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, options), the client accepts any certificate in the peer's chain as a certificate authority without verifying that the certificate is actually autho