wolfssl/INSTALL

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.