wolfSSL: a small TLS library for embedded and server builds

What wolfSSL is for and who ends up using it

wolfSSL, formerly CyaSSL, is a TLS/SSL library written in ANSI C and aimed at embedded, RTOS and resource-constrained environments. The README says the choice usually comes down to size, speed and feature set, and gives typical footprint sizes of 20 to 100 kB. That number is the whole argument. On a device where the TLS stack has to fit alongside application code in a small flash budget, the size of the crypto and protocol layer is a design constraint, not a preference.

The same properties pull it into ordinary operating environments. The README notes royalty-free pricing and cross-platform support as reasons it is used outside embedded work. The library exposes an OpenSSL compatibility API, so an application already written against OpenSSL can be ported rather than rewritten. That combination, small and API-compatible, is why the project shows up both in firmware and in server-side builds.

Who it is not obviously for: teams that want the default behaviour of the system TLS they already have. wolfSSL makes different choices at the policy level, and those choices show up as connection failures if you have not loaded a trust store.

How the protocol layer, wolfCrypt and the build options fit together

wolfSSL is powered by the wolfCrypt cryptography library, which is where the primitives live. The TLS layer sits on top of it and the build system decides which parts get compiled. That is why configuration is done through defines and configure flags rather than a runtime config file: on a constrained target you want the unused code gone at compile time.

The README lists support for SSL 3.0, TLS 1.0 through 1.3, and DTLS 1.0, 1.2 and 1.3, along with progressive ciphers such as ChaCha20, Curve25519 and BLAKE2b/BLAKE2s, plus Post-Quantum TLS 1.3 groups. Since 3.6.6, SSLv3 is off by default. Static key cipher suites using PSK, RSA or ECDH without ephemeral key exchange are also off by default; the library enables ephemeral Diffie-Hellman and ECC suites instead, which provide perfect forward secrecy. If you need legacy static key suites you have to opt in with WOLFSSL_STATIC_DH, WOLFSSL_STATIC_RSA or WOLFSSL_STATIC_PSK, and the README is direct that doing so removes forward secrecy because the same long-term private key is reused across sessions.

One compile-time detail worth knowing before you disable things: when ssl.c is compiled, wolfSSL issues a compiler error if no cipher suites are available. Defining WOLFSSL_ALLOW_NO_SUITES removes that error, which is intended for builds that are not using TLS cipher suites at all.

The repository also carries build and compliance tooling that is not part of the runtime path. make sbom produces SPDX 2.3 and CycloneDX 1.6 JSON for Linux, Debian, RPM, Yocto and FIPS-Ready builds and validates against the SPDX spec with pyspdxtools, gating the build on it. For embedded, RTOS or IDE-based builds (Keil, IAR, STM32CubeIDE, ESP-IDF, Zephyr, plain CMake, custom Makefile) the README points at python3 scripts/gen-sbom, which needs a hand-edited user_settings.h and no autotools. make bomsh generates an OmniBOR artifact dependency graph, and make advisory emits one CSAF 2.0 document and one CycloneDX 1.6 VEX document per CVE into advisories/out/ from the records under advisories/. Neither SBOM path runs an NTIA-minimum-elements checker by default.

Installing wolfSSL and making a first connection

The README and repository layout describe the autotools path as ./configure followed by make, and the repository also ships CMakeLists.txt and CMakePresets.json for CMake-based projects. The commands below follow that documented flow; the configure step is where you decide which protocol versions and features are compiled in.

Start by generating the build system and configuring. Running autogen.sh is the documented way to produce configure from configure.ac in a git checkout.

./autogen.sh
./configure
make

After configure finishes it prints a summary of enabled features, and make compiles the library plus the examples. If you are cross-compiling for a target board, this is the point where a host triplet and toolchain would be supplied instead of the defaults; the README does not spell out a cross-compilation recipe, so check INSTALL for the flags your toolchain needs.

The repository contains an examples/ directory with client, server, echoclient, echoserver, benchmark, tls13 and other subdirectories, each with its own README. Those are the intended first stop for a working connection. A minimal client has to load a CA before connecting, because of the verification default described below.

If you are porting existing code, the OpenSSL compatibility API is the reason to try wolfSSL before rewriting. One naming difference to expect: when the library is built with --enable-opensslextra or with the NO_OLD_SHA_NAMES macro, the enum names SHA, SHA256, SHA384 and SHA512 are no longer available and are mapped to the OpenSSL single-call hash API. Use WC_SHA, WC_SHA256, WC_SHA384 and WC_SHA512 as the enum names in that configuration.

The certificate verification default that breaks first connections

This is the single most common surprise. wolfSSL takes a different approach to certificate verification than OpenSSL. The default client policy is to verify the server, so if you do not load CAs, the connection fails. The README states the failure surfaces as a connect error and gives the signer error code as -188.

If you want the OpenSSL behaviour, where SSL_connect succeeds even when server verification fails, you call wolfSSL_CTX_set_verify with WOLFSSL_VERIFY_NONE before wolfSSL_new():

wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_NONE, NULL);

The README explicitly says this is not recommended, and it is right to say so: it reduces security by accepting a server the library could not authenticate. The practical reading is that wolfSSL fails closed by default and OpenSSL fails open, so a port that "worked" under OpenSSL may need a trust store loaded before it works here. That is a feature, but it is a migration cost, and it is the kind of cost that shows up as a bug report rather than a compile error.

Hardware key isolation and hardware-derived keys

Two features in the README are aimed at devices where keys must not sit in ordinary RAM. The first is CryptoCB AES key import. When WOLF_CRYPTO_CB_AES_SETKEY is defined, wolfSSL invokes a CryptoCB callback during AES key setup, and the callback's return value selects the mode. If the callback returns 0, the key is imported to a secure element or HSM, is not copied into wolfSSL RAM, GCM tables are not generated, and all later AES operations route through CryptoCB. If it returns CRYPTOCB_UNAVAILABLE, the secure element does not support key import, software AES is used, and the key is copied to devKey so CryptoCB can still accelerate encrypt and decrypt. The README frames this as enabling TLS 1.3 traffic key protection where symmetric keys must never exist in main RAM. It is enabled with CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE".

The second is deriving device-unique keys from hardware entropy, configured with --enable-puf and a strength of small, balanced, strong or strongest, which selects 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. That last clause is the part that matters: without the health test, a stuck SRAM cell would produce the same key on every device. An example lives in the wolfssl-examples repository under puf.

Licence, FIPS and the cost of staying current

The repository's default licence is GPL-3.0, and the README describes the pricing as royalty-free, which is the phrasing that pulls people in. Those two statements are not in conflict, but they are not the same promise either. The README directs readers to LICENSING in the repository and to the wolfCrypt FIPS FAQ at wolfssl.com/license/fips for details, and a commercial licence is the path for products that cannot ship under GPL-3.0. This is a reading-the-file question, not a legal opinion: LICENSING is the authoritative document, and it is short enough to read before you write code.

FIPS is a separate axis. Two versions of wolfCrypt have been FIPS 140-2 validated (Certificate #2425 and #3389) and FIPS 140-3 validated (Certificate #4718). Validation attaches to a specific validated module and configuration, not to the library in general, so the sbom tooling distinguishes FIPS-Ready builds from ordinary ones. If your product needs a validated module, confirm which configuration the certificate covers before assuming the default build qualifies.

Upgrade cost is real but bounded. The releases listed for 2026 are v5.9.0-stable in March, v5.9.1-stable in April and v5.9.2-stable in June, and the project description points at 5.9.1 for CVE fixes. The repository carries advisories/ records, a SECURITY-POLICY.md and a SECURITY-REPORT-TEMPLATE.md, and make advisory turns those records into CSAF 2.0 and CycloneDX 1.6 VEX documents. That is a more automated advisory trail than most C libraries of this age provide, and it is the mechanism to use when deciding whether a given CVE affects your build. The last push to the repository was on 2026-09-23.

When wolfSSL is the wrong tool, and what to use instead

wolfSSL is the wrong choice when the environment already has a maintained system TLS and nothing forces you to replace it. If you are writing a desktop application that links against the platform's OpenSSL or Schannel, adding a second TLS implementation means a second set of CVE feeds, a second build configuration and a second verification policy to reason about. The size argument that justifies wolfSSL on a Cortex-M part does not apply on a server where the library is a shared object.

It is also the wrong choice if you need FIPS validation and cannot wait for a configuration to be covered, or if you need a permissive default licence and cannot take GPL-3.0 or buy a commercial licence. Those are hard boundaries, not tuning problems.

The obvious alternative is OpenSSL, and the difference is not just size. OpenSSL's client verification is permissive by default, which is why a port to wolfSSL fails with a signer error until CAs are loaded. OpenSSL also has a much larger API surface, so code that uses parts of it beyond the compatibility layer wolfSSL implements will need work. The README claims wolfSSL is up to 20 times smaller than OpenSSL and cites user benchmarking and feedback reports as showing better performance; those are the project's own claims, not independent measurements, and the benchmark example under examples/benchmark is the way to produce numbers for your own target rather than trusting either figure. mbedTLS is the other common embedded option; the README does not compare against it, so the honest position is that both target constrained devices and the choice comes down to API shape, feature coverage and licence terms you can verify in each project's own documentation.

Editorial conclusion

Adopt wolfSSL when you need TLS 1.3 or DTLS 1.3 in a build where OpenSSL's size or licence does not fit, and you can accept the GPL-3.0 default or buy a commercial licence. Do not adopt it if you expect OpenSSL's permissive default behaviour on certificate verification, or if you need a FIPS 140-2 or 140-3 validated binary without going through the validation process. Before committing, run ./configure && make on your actual target and check the reported footprint, then read LICENSING and the wolfCrypt FIPS FAQ to see which licence path applies to your product.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wolfSSL/wolfssl on GitHub