0. Building on *nix from git repository

Run the autogen script to generate configure, then proceed to step 1.

Prerequisites: You'll need autoconf, automake and libtool installed.

$ ./autogen.sh

1. Building on *nix from a release

$ ./configure

$ make

$ make check # (optional, but highly recommended)

$ sudo make install

Note: Building with configure generates a wolfssl/options.h file that contains

all the generated build options. This file needs to be included in your application

before any other wolfSSL headers. Optionally your application can define

WOLFSSL_USE_OPTIONS_H to do this automatically.

Note: Building with configure also installs CMake package files under

$(libdir)/cmake/wolfssl to support find_package(wolfssl). You can disable this

with ./configure --disable-cmake-install.

2. Building on iOS

Use on the xcode project in IDE/iOS/wolfssl.xcodeproj

There is a README in IDE/iOS with more information

3. Building for Apple ARM64

When building for an Apple ARM64 platform, ensure the host CPU type is detected as "aarch64" during configure, if not, pass --host=aarch64-apple-darwin to configure.

4. Building on Windows

Use the Visual Studio Solution wolfssl64.sln

5. Building with IAR

Please see the README in IDE/IAR-EWARM for detailed instructions

6. Building with Keil

Please see the Keil Projects in IDE/MDK5-ARM/Projects

7. Building with Microchip tools

Please see the README in mplabx

8. Building with Freescale MQX

Please see the README in mqx

9. Building with Rowley CrossWorks for ARM

Use the CrossWorks project in IDE/ROWLEY-CROSSWORKS-ARM/wolfssl.hzp

There is a README.md in IDE/ROWLEY-CROSSWORKS-ARM with more information

10. Building with Arduino

Use the script IDE/ARDUINO/wolfssl-arduino.sh to reformat the wolfSSL

library for compatibility with the Arduino IDE. There is a README.md in

IDE/ARDUINO for detailed instructions.

11. Building for Android with Visual Studio 2017

Please see the README in IDE/VS-ARM.

Use the Visual Studio solution IDE/VS-ARM/wolfssl.sln.

12. Building for Yocto Project or OpenEmbedded

Please see the README in the "meta-wolfssl" repository. This repository

holds wolfSSL's Yocto and OpenEmbedded layer, which contains recipes

for wolfSSL, wolfSSH, wolfMQTT, wolfTPM, wolfCrypt examples, and OSS

project bbappend files.

https://github.com/wolfssl/meta-wolfssl

The wolfSSL recipe can also be found in the OpenEmbedded

"meta-openembedded/meta-networking/recipes-connectivity" layer:

https://github.com/openembedded/meta-openembedded

13. Porting to a new platform

Please see section 2.4 in the manual:

https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html#customizing-or-porting-wolfssl

14. Building with CMake

Note: Primary development uses automake (./configure). The support for CMake

is still under development.

For configuring wolfssl using CMake, we recommend downloading the CMake

GUI (https://cmake.org/download/). This tool allows you to see all of

wolfssl's configuration variables, set them, and view their descriptions.

Looking at the GUI or CMakeCache.txt (generated after running cmake once) is

the best way to find out what configuration options are available and what

they do. You can also invoke CMake from the GUI, which is described in the

Windows instructions below. For Unix-based systems, we describe the command

line work flow. Regardless of your chosen workflow, cmake will generate

a header options.h in the wolfssl directory that contains the options used

to configure the build.

Note: Building with configure generates a wolfssl/options.h file that contains

all the generated build options. This file needs to be included in your application

before any other wolfSSL headers. Optionally your application can define

WOLFSSL_USE_OPTIONS_H to do this automatically.

Unix-based Platforms

---

1) Navigate to the wolfssl root directory containing "CMakeLists.txt".

2) Create a directory called "build" and change into it. This is where

CMake will store build files.

3) Run `cmake ..` to generate the target build files (e.g. UNIX Makefiles).

To enable or disable features, set them using -D<option>=[yes/no]. For

example, to disable TLS 1.3 support, run cmake .. -DWOLFSSL_TLS13=no

(autoconf equivalent: ./configure --disable-tls13) To enable DSA, run

cmake .. -DWOLFSSL_DSA=yes (autoconf equivalent: ./configure

--enable-dsa). Again, you can find a list of these options and their

descriptions either using the CMake GUI or by looking at CMakeCache.txt.

5) The build directory should now contain the generated build files. Build

with `cmake --build .`. Under the hood, this runs the target build tool

(by default, make). You can also invoke the target build tool directly

(e.g. make).

To build with debugging use: `cmake .. -DCMAKE_BUILD_TYPE=Debug`.

In the simplest form:

# create a root directory for wolfssl repo

git clone https://github.com/wolfSSL/wolfssl.git

cd wolfssl

# From the root of the wolfSSL repo:

mkdir -p out

pushd out

cmake ..

cmake --build .

# View the available ciphers with:

./examples/client/client -e

popd

ARIA Cipher Suite.

The ARIA cipher needs a 3rd party source binary, typically called

`MagicCrypto.tar.gz`.

The MagicCrypto files can be either copied to the local `wolfssl` directory,

or an environment variable `ARIA_DIR` can be set to point to the location.

Simply having the environment variable or local `MagicCrypto` directory

will not automatically enable the ARIA Ciphers.

To enable ARIA Ciphers in wolfSSL for `CMake`:

# From the root of the wolfSSL repo:

# set to your path

export ARIA_DIR=~/workspace/MagicCrypto

mkdir -p out

pushd out

cmake .. -DWOLFSSL_ARIA=yes

cmake --build .

# View the available ciphers with:

./examples/client/client -e

popd

Windows (Visual Studio)

---

1) Go to this page, download the appropriate Windows installer, and install

to get the CMake GUI: https://cmake.org/download/ Native CMake support in

Visual Studio 16 2019 (and possibly older versions) has proven buggy. We

recommend using the CMake GUI in concert with Visual Studio, as described

in these steps.

2) Open CMake.

3) Where is the source code: <root directory of wolfssl containing

CMakeLists.txt>

4) Where to build the binaries: <build directory, e.g. wolfssl/build>

5) Hit Configure. CMake runs the code in CMakeLists.txt and builds up an

internal representation of the project.

6) Hit Generate. CMake generates the build files. For Windows, this will

be Visual Studio project (.vcxproj) and solution (.sln) files.

7) Open Visual Studio and select "Open a project or solution".

8) Navigate to the build directory and select wolfssl.sln to load the

project.

Windows (command line)

---

1) Open Command Prompt

2) Run the Visual Studio batch to setup command line variables, e.g. C:\Program Files (x86)\Microsoft Visual

Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat

3) Follow steps in "Unix-based Platforms" above.

15. Building Post-Quantum Support for TLS 1.3

$ cd wolfssl

$ ./autogen.sh (Only necessary if downloaded from github)

$ ./configure --enable-kyber --enable-dilithium

$ make all

Execute the following to see the options for KEM groups near

the end of the output of these commands:

$ ./examples/server/server -?

$ ./examples/client/client -?

For a quick start, you can run the client and server like this:

$ ./examples/server/server -v 4 --pqc SecP521r1MLKEM1024

$ ./examples/client/client -v 4 --pqc SecP521r1MLKEM1024

Look for the following line in the output of the server and client:

```

Using Post-Quantum KEM: SecP521r1MLKEM1024

```

For authentication, you can generate a certificate chain using the Open

Quantum Safe project's OQS Provider with your system's OpenSSL application.

Instructions are maintained in our OSP repo here:

https://github.com/wolfSSL/osp/tree/master/oqs/README.md

For your convenience, there are also pre-generated ML-DSA certificates and

keys.

Please find instructions on how to generate the keys and certificates

in the `README.md` file.

Copy the certificates and keys into the certs directory of wolfssl. Now you

can run the server and client like this:

$ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \

-A certs/mldsa87_root_cert.pem \

-c certs/mldsa44_entity_cert.pem \

-k certs/mldsa44_entity_key.pem \

--pqc SecP521r1MLKEM1024

$ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \

-A certs/mldsa44_root_cert.pem \

-c certs/mldsa87_entity_cert.pem \

-k certs/mldsa87_entity_key.pem \

--pqc SecP521r1MLKEM1024

Congratulations! You have just achieved a fully quantum-safe TLS 1.3

connection!

The following NIST Competition winning algorithms are supported by the

native wolfSSL implementation:

- ML-KEM (FIPS 203, CRYSTALS-KYBER) (key encapsulation mechanism)

- ML-DSA (FIPS 204, CRYSTALS-Dilithium) (signature scheme)

- SLH-DSA (FIPS 205, SPHINCS+) (signature scheme)

- Falcon (signature scheme) - experimental, not yet standardized

Falcon is provided by the native wolfSSL implementation; liboqs is no

longer required or supported. Falcon has not been standardized by NIST yet,

and its wolfCrypt API name is experimental and subject to change, so enable

it with --enable-falcon --enable-experimental (CMake: -DWOLFSSL_FALCON=yes

-DWOLFSSL_EXPERIMENTAL=yes).

The following NIST Competition Round 3 finalist algorithms were supported,

but have been removed after 5.3.3

- SABER (KEM)

- NTRU (KEM)

Links to more information about all of these algorithms can be found here:

https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions

NOTE: The quantum-safe algorithms that we have implemented are standardized

by NIST and our implementations follow these standards. At the

protocol layer, OIDs and codepoints have been proposed in various

standards organizations but are not yet ratified. OIDs and codepoints

are temporary and expected to change in the future. You should have no

expectation of backwards compatibility at the protocol layer.

16. Building with vcpkg

# Building wolfssl - Using vcpkg

You can download and install wolfssl using the [vcpkg](https://github.com/Microsoft/vcpkg):

git clone https://github.com/Microsoft/vcpkg.git

cd vcpkg

./bootstrap-vcpkg.sh

OR for Windows

bootstrap-vcpkg.bat

./vcpkg integrate install

./vcpkg install wolfssl

The wolfssl port in vcpkg is kept up to date by wolfSSL.

We also have vcpkg ports for wolftpm, wolfmqtt and curl.

17. Building for Debian, Ubuntu, Linux Mint, and derivatives

To generate a .deb package, configure wolfSSL with the desired

configuration. Then run `make deb` to generate a Debian package

with the current configuration. To build the package inside a

Docker container, use `make deb-docker`. In both cases the

resulting packages are placed in the root directory of the

project.

18. Building for RHEL, Fedora, CentOS, SUSE, and openSUSE

To generate a .rpm package, configure wolfSSL with the desired

configuration. Then run `make rpm` to generate a .rpm package

with the current configuration. To build the package inside a

Docker container, use `make rpm-docker`. In both cases the

resulting packages are placed in the root directory of the

project.

19. Generating an SBOM (Software Bill of Materials)

wolfSSL can generate a Software Bill of Materials for EU Cyber Resilience

Act (CRA) compliance. Two entry points are supported, depending on how

you build wolfSSL.

--- 19a. Embedded / RTOS / IDE-based builds (no autotools) ----------

For customers building wolfSSL from a hand-edited user_settings.h with

their own Makefile, Keil MDK, IAR EWARM, STM32CubeIDE, ESP-IDF,

Zephyr, or plain CMake, invoke scripts/gen-sbom directly. No

./configure, no autotools.

Prerequisites:

- python3

- pcpp (pip install pcpp) # required for --user-settings

- spdx-tools (pip install spdx-tools) # optional; for SPDX validation

Usage:

$ python3 wolfssl/scripts/gen-sbom \

--name wolfssl --version 5.9.1 \

--license-file wolfssl/LICENSING \

--user-settings wolfssl/wolfssl/wolfcrypt/settings.h \

--user-settings-include wolfssl \

--user-settings-include path/to/your/user_settings_dir \

--user-settings-define WOLFSSL_USER_SETTINGS \

--srcs wolfssl/wolfcrypt/src/aes.c [...your wolfssl source list] \

--cdx-out wolfssl-5.9.1.cdx.json \

--spdx-out wolfssl-5.9.1.spdx.json

The component checksum is a deterministic OmniBOR-compatible Merkle

hash over the source files you compile into your firmware, so you do

not need to synthesize a separate libwolfssl.a just for SBOM purposes.

See doc/SBOM.md section 1 for per-toolchain recipes (Keil, IAR,

STM32CubeIDE, ESP-IDF, Zephyr, CMake) and the full flag reference.

--- 19b. Linux / autotools builds ----------------------------------

For Debian, RPM, Yocto, FIPS-Ready, and other builds that already use

./configure && make:

Prerequisites:

- python3 (detected automatically by configure)

- pyspdxtools (pip install spdx-tools)

Usage:

$ ./configure

$ make

$ make sbom

This produces three files in the build directory:

wolfssl-<version>.cdx.json CycloneDX 1.6 JSON

wolfssl-<version>.spdx.json SPDX 2.3 JSON

wolfssl-<version>.spdx SPDX 2.3 tag-value (validated by pyspdxtools)

The SPDX JSON is validated by pyspdxtools before the tag-value file is

written; make sbom fails if validation fails.

`make sbom` is a thin convenience wrapper around the same

scripts/gen-sbom Python entry point that section 19a uses, with all

paths resolved automatically from the autotools build tree.

To install the SBOM files to $(datadir)/doc/wolfssl/:

$ make install-sbom

To remove installed SBOM files:

$ make uninstall-sbom

The generated files are removed by make clean.

For details on the SBOM contents and CRA context, see doc/SBOM.md.

20. Generating OmniBOR build artifact graph (Bomsh)

wolfSSL supports generating an OmniBOR artifact dependency graph using

the Bomsh project (https://github.com/omnibor/bomsh). OmniBOR provides

cryptographic traceability from every binary artifact back to the exact

source files that produced it.

Prerequisites:

- bomtrace3 (build from https://github.com/omnibor/bomsh)

- bomsh_create_bom.py (from the bomsh scripts/ directory, in PATH)

- bomsh_sbom.py (optional; from bomsh scripts/, for SPDX enrichment)

Both bomtrace3 and the Python scripts are detected by configure.

make bomsh fails with a clear error message if either required tool

is missing.

Usage:

$ ./configure

$ make

$ make bomsh

This performs a clean rebuild of wolfSSL under bomtrace3 tracing,

then produces an OmniBOR artifact graph in omnibor/ in the build

directory. If bomsh_sbom.py is available and a wolfssl-<ver>.spdx.json

exists (from 'make sbom'), it also produces an OmniBOR-enriched SPDX

document omnibor.wolfssl-<ver>.spdx.json.

To install:

$ make install-bomsh # installs omnibor/ to $(datadir)/doc/wolfssl/

$ make uninstall-bomsh # removes installed files

The generated files are removed by make clean.

See doc/SBOM.md for full details.

21. Generating security advisories (CSAF 2.0 + CycloneDX VEX)

wolfSSL can generate machine-readable security advisories from a

canonical, git-tracked single source of truth. Each CVE record

produces one CSAF 2.0 document and one CycloneDX 1.6 VEX document,

suitable for downstream vulnerability tooling and CRA reporting.

Prerequisites:

- python3 (detected automatically by configure)

Usage:

$ ./configure

$ make advisory

Inputs (tracked in git):

advisories/records/*.json one JSON record per CVE

advisories/vex-overlay.json shared VEX overlay metadata

Outputs (build artifacts, one pair per record):

advisories/out/*.csaf.json CSAF 2.0 JSON

advisories/out/*.cdx.json CycloneDX 1.6 VEX JSON

Output is reproducible: SOURCE_DATE_EPOCH is honored and defaults to

the last git commit timestamp when unset, exactly like make sbom.

`make advisory` is a thin wrapper around scripts/gen-advisory and is

byte-for-byte interchangeable with running that script by hand:

$ python3 scripts/gen-advisory \

--records-dir advisories/records \

--vex-overlay advisories/vex-overlay.json \

--out-dir advisories/out

To install the advisory files to $(datadir)/doc/wolfssl/advisories/:

$ make install-advisory

To remove installed advisory files:

$ make uninstall-advisory

The generated files are removed by make clean.