wolfssl

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 [email protected].

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):

• 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

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

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.2 (Jun 23, 2026)

Release 5.9.2 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:

• The pre-standardization Dilithium API has been renamed to its FIPS 204 ML-DSA name; the legacy dilithium.h header and wc_dilithium_* names remain available through a temporary compatibility shim.
• The SLH-DSA Hash sign/verify APIs now require a caller-supplied pre-hashed digest rather than the raw message (see Enhancements below).
• liboqs integrations for ML-KEM, ML-DSA, and SLH-DSA (SPHINCS+) have been removed in favor of the native implementations; the deprecated liblms and libxmss integrations have also been removed.
• BREAKING (RFC 6960 4.2.2.2): OCSP responder authorization is now strictly enforced. Removes the non-compliant CheckOcspResponderChain() fallback, which authorized any OCSP responder cert issued by an ancestor of the target's issuer; RFC 6960 4.2.2.2 requires direct issuance by the CA identified in the request. Also removes the now-unused WOLFSSL_NO_OCSP_ISSUER_CHAIN_CHECK macro and the vp parameter from CheckOcspResponder().

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

Vulnerabilities

• [High] CVE-2026-11310 X.509 trust-chain bypass in the OpenSSL compatibility certificate verifier (wolfSSL_X509_verify_cert()).

  This affects only builds with --enable-opensslextra (OPENSSL_EXTRA) and whose application validates certificates by calling X509_verify_cert() (OpenSSL compatibility layer function) with caller-supplied untrusted intermediate certificates; for those users it is critical, otherwise the library is unaffected. In particular, native wolfSSL TLS/DTLS usage is not impacted.

  wolfSSL’s X509_verify_cert() temporarily loads each caller-supplied untrusted intermediate into the certificate manager but failed to drop them before the trusted-store check, so an untrusted intermediate could anchor the path itself. An attacker can present a chain that never reaches a configured trust anchor and have it accepted, resulting in acceptance of an attacker-controlled certificate.

  This is certificate verification independent of TLS (e.g. S/MIME/CMS, code/firmware signing, JWT/JWS x5c), is not specific to any key type or algorithm, and a single untrusted intermediate suffices. The default wolfSSL TLS handshake (WOLFSSL_VERIFY_PEER) is not affected; only TLS applications doing manual or deferred peer verification through this API are, which also requires --enable-sessioncerts. Affected: v5.8.4, v5.9.0 and v5.9.1 (introduced by commit 025dbc34); v5.8.2 and earlier are not. Thanks to Corban Villa, Sohee Kim and Austin Chu (UC Berkeley, Sky Lab). Fixed in PR 10674.

• [High] CVE-2026-11999 X.509 trust-chain bypass (path-depth exhaustion) in the OpenSSL compatibility certificate verifier (wolfSSL_X509_verify_cert()). This affects only builds with --enable-opensslextra whose application calls X509_verify_cert() with caller-supplied untrusted intermediates; for those users it is critical, otherwise the library is unaffected. Native wolfSSL TLS/DTLS usage is not impacted.

  X509_verify_cert() returned success based only on the last verified link rather than on reaching a trust anchor: when the supplied chain is deeper than the verifier's maximum path depth (default 100), path building runs out of depth while still walking untrusted intermediates and the chain is accepted even though it never reaches a configured trust anchor, allowing acceptance of an attacker-controlled certificate. The default TLS handshake (WOLFSSL_VERIFY_PEER) is not affected; only applications doing manual or deferred verification through this API are. Affected versions: v5.7.4 through v5.9.1, introduced in commit 17c9e92b7 (first released in v5.7.4); v5.7.2 and earlier are not affected. Thanks to Corban Villa, Sohee Kim and Austin Chu (UC Berkeley, Sky Lab). Fixed in PR 10674.

• [High] CVE-2026-6679 A heap buffer overflow could occur in the DTLS 1.3 ACK serialization path before the connecting peer is authenticated. The buffer overflow was due to an integer truncation when computing the length of the ACK record-number list, causing an undersized buffer to be allocated and then overrun. This affects builds using DTLS 1.3 and wolfSSL version 5.9.0 and earlier. A fix was added to the 5.9.1 release. Thanks to Nicholas Carlini from Anthropic for the report. Fixed in PR 10116.

• [High] CVE-2026-55958 Out-of-bounds write in the Renesas TSIP TLS 1.3 transcript buffer. In tsip_StoreMessage() the capacity check guarding the fixed message bag (MSGBAG_SIZE) sets an error code but fails to return, so execution falls through to an XMEMCPY that writes past the end of the buffer once the accumulated TLS 1.3 handshake transcript exceeds MSGBAG_SIZE (8 KB), corrupting adjacent heap state and potentially causing a remote denial of service crash. The bag is sized to hold a normal handshake, so this is reached only by an unusually large but valid certificate chain,