WOLFSSL MANUAL: CHAPTER 2

Download wolfSSL Manual (PDF)

Chapter 2:  Building wolfSSL

wolfSSL was written with portability in mind and should generally be easy to build on most systems. If you have difficulty building wolfSSL, please don’t hesitate to seek support through our support forums (http://www.wolfssl.com/forums) or contact us directly at support@wolfssl.com.

This chapter explains how to build wolfSSL on Unix and Windows, and provides guidance for building wolfSSL in a non-standard environment.  You will find the “getting started” guide in Chapter 3 and an SSL tutorial in Chapter 11.

When using the autoconf / automake system to build wolfSSL, wolfSSL uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively.

2.1 Getting wolfSSL Source Code


The most recent version of wolfSSL can be downloaded from the wolfSSL website as a ZIP file:

http://wolfssl.com/wolfSSL/download/downloadForm.php

After downloading the ZIP file, unzip the file using the unzip“unzip” command.  To use native line endings, enable the “-a” modifier when using unzip.  From the unzip man page, the “-a” modifier functionality is described:

[...]  The -a option causes files identified by zip as text files (those with the ‘t’  label in  zipinfo  listings,  rather  than  ‘b’)  to  be automatically extracted  as  such,  converting   line   endings,   end-of-file characters  and  the  character  set  itself as necessary.  [...]

NOTE:  Beginning with the release of wolfSSL 2.0.0rc3, the directory structure of wolfSSL was changed as well as the standard install location.  These changes were made to make it easier for open source projects to integrate wolfSSL.  For more information on header and structure changes, please see Sections 9.1 and 9.3.

2.2 Building on *nix


When building wolfSSL on Linux, *BSD, OS X, Solaris, or other *nix-like systems, use the autoconf system. To build wolfSSL you only need to run two commands from the wolfSSL root directory:

 

./configure

make

 

You can append any number of build options to ./configure.  For a list of available build options, please see Section 2.5 or run:

./configure --help

from the command line to see a list of possible options to pass to the ./configure script.  To build wolfSSL, run:

make

To install wolfSSL run:

 

make install

 

You may need superuser privileges to install, in which case precede the command with sudo:

 

sudo make install

 

To test the build, run the testsuite program from the root wolfSSL directory:

./testsuite/testsuite.test

or use autoconf to run the testsuite as well as the standard wolfSSL API and crypto tests:

make test

Further details about expected output of the testsuite program can be found in Section 3.2.  If you want to build only the wolfSSL library and not the additional items (examples, testsuite, benchmark app, etc.), you can run the following command from the wolfSSL root directory:

make src/libwolfssl.la

2.3 Building on Windows


 

In addition to the instructions below, you can find instructions and tips for building wolfSSL with Visual Studio here.

VS 2008:  Solutions are included for Visual Studio 2008 in the root directory of the install.  For use with Visual Studio 2010 and later, the existing project files should be able to be converted during the import process.

 

Note:

If importing to a newer version of VS you will be asked:  “Do you want to overwrite the project and its imported property sheets?”  You can avoid the following by selecting “No”.  Otherwise if you select “Yes”, you will see warnings about EDITANDCONTINUE being ignored due to SAFESEH specification. You will need to right click on the testsuite, sslSniffer, server, echoserver, echoclient, and client individually and modify their Properties->Configuration Properties->Linker->Advanced (scroll all the way to the bottom in Advanced window).  Locate “Image Has Safe Exception Handlers” and click the drop down arrow on the far right. Change this to No (/SAFESEH:NO) for each of the aforementioned. The other option is to disable EDITANDCONTINUE which, we have found to be useful for debugging purposes and is therefore not recommended.

VS 2010:  You will need to download Service Pack 1 to build wolfSSL solution once it has been updated. If VS reports a linker error, clean and rebuild the project; the linker error should be taken care of.

VS 2013 (64 bit solution):  You will need to download Service Pack 4 to build wolfSSL solution once it has been updated. If VS reports a linker error, clean the project then Rebuild the project and the linker error should be taken care of.

To test each build, choose “Build All” from the Visual Studio menu and then run the testsuite program.  To edit build options in the Visual Studio project, select your desired project (wolfssl, echoclient, echoserver, etc.) and browse to the “Properties” panel.

Note:

After the wolfSSL v3.8.0 release the build preprocessor macros were moved to a centralized file located at ‘IDE/WIN/user_settings.h’. This file can also be found in the project. To add features such as ECC or ChaCha20/Poly1305 add #defines here such as HAVE_ECC or HAVE_CHACHA / HAVE_POLY1305.

Cygwin:  If using Cygwin, or other toolsets for Windows that provides *nix-like commands and functionality, please follow the instructions in section 2.2, above, for “Building on *nix”.  If building wolfSSL for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build wolfSSL.

2.4 Building in a non-standard environment


While not officially supported, we try to help users wishing to build wolfSSL in a non-standard environment, particularly with embedded and cross-compilation systems. Below are some notes on getting started with this.

 

  1. The source and header files need to remain in the same directory structure as they are in the wolfSSL download package.

  1. Some build systems will want to explicitly know where the wolfSSL header files are located, so you may need to specify that.  They are located in the <wolfssl_root>/wolfssl directory.  Typically, you can add the <wolfssl_root> directory to your include path to resolve header problems.

  1. wolfSSL defaults to a little endian system unless the configure process detects big endian.  Since users building in a non-standard environment aren't using the configure process, BIG_ENDIAN_ORDER will need to be defined if using a big endian system.

  1. wolfSSL benefits speed-wise from having a 64-bit type available. The configure process determines if long or long long is 64 bits and if so sets up a define. So if sizeof(long) is 8 bytes on your system, define SIZEOF_LONG 8. If it isn't but sizeof(long long) is 8 bytes, then define SIZEOF_LONG_LONG 8.

  1. Try to build the library, and let us know if you run into any problems. If you need help, contact us at info@wolfssl.com.

  1. Some defines that can modify the build are listed in the following subsections, below.  For more verbose descriptions of many options, please see section 2.5.1, “Build Option Notes”.

2.4.1 Building into Yocto Linux

wolfSSL also includes recipes for building wolfSSL on Yocto Linux and OpenEmbedded. These recipes are maintained within the meta-wolfSSL layer as a GitHub repository, here: https://github.com/wolfSSL/meta-wolfssl. Building wolfSSL on Yocto Linux will require Git and bitbake. The following steps list how to get some wolfSSL products (that recipes exist for) built on Yocto Linux.

  1. Cloning wolfSSL meta
    This can be done through a git-clone command of the following URL:
    https://github.com/wolfSSL/meta-wolfssl
  2. Insert the "meta-wolfSSL" layer into the build's bblayers.conf
    Within the BBLAYERS section, add the path to the location where meta-wolfssl was cloned into. Example:
            
    BBLAYERS ?= "... \
            /path/to/meta-wolfssl/ \
            ..."
  3. Build a wolfSSL product recipe
    bitbake can be used to build one of the three following wolfSSL product recipes:
    wolfssl, wolfssh, and wolfmqtt. Simply pass one of those recipes into the bitbake command (example: bitbake wolfssl). This allows the user to personally confirm compilation succeeds without issues.
  4. Edit local.conf
    The final step is to edit the build's local.conf file, which allows desired libraries to be included with the image being built. Edit the "IMAGE_INSTALL_append" line to include the name of the desired recipe(s). An example of this is shown below:
            
    IMAGE_INSTALL_apped = "wolfssl wolfssh wolfmqtt"

Once the image has been built, wolfSSL's default location (or related products from recipes) will be the "/usr/lib/" directory.

Additionally, wolfSSL can be customized when building into Yocto by using the enable and disable options listed in section 2.5. This requires creating a .bbappend file and placing it within the wolfSSL application/recipe layer. The contents of this file should include a line specifying content to concatenate onto the EXTRA_OECONF variable. An example of this is shown below to enable TLS 1.3 support through the TLS 1.3 enable option:

EXTRA_OECONF += "--enable-tls13"

Further documentation on building into Yocto can be found in the meta-wolfssl README, located here: https://github.com/wolfSSL/meta-wolfssl/blob/master/README.md

2.4.2 Building with Atollic TrueSTUDIO

Versions of wolfSSL following 3.15.5 include a TrueSTUDIO project file that is used to build wolfSSL on ARM M4-Cortex devices. The TrueSTUDIO IDE simplifies the process of building on STM32 devices, is free to download, and is created by Atollic - a part of STMicroelectronics. To build the wolfSSL static library project file in TrueSTUDIO, it will require the user perform the following steps after opening TrueSTUDIO:

  1. Import the project into the workspace (File > Import)
  2. Build the project (Project > Build project)

The build then includes the settings located inside of user_settings.h at build-time. The default content of the user_settings.h file is minimal, and does not contain many features. Users are able to modify this file and add or remove features with options listed in the remainder of this chapter.

2.4.3 Building with Renesas CS+

Versions of wolfSSL following 3.15.0 include Renesas CS+ project files that can be used to build wolfSSL inside of the Renesas CS+ IDE. The CS+ IDE is compatible with other Renesas hardware tools. The steps for building wolfSSL through CS+ are located in one of the wolfSSL READMEs, <wolfssl-root>/IDE/Renesas/CS+/Projects/README.

2.4.4 Removing Features

The following defines can be used to remove features from wolfSSL.  This can be helpful if you are trying to reduce the overall library footprint size.  In addition to defining a NO_<feature-name> define, you can also remove the respective source file as well from the build (but not the header file).

NO_WOLFSSL_CLIENT removes calls specific to the client and is for a server-only builds.  You should only use this if you want to remove a few calls for the sake of size.

 

NO_WOLFSSL_SERVER likewise removes calls specific to the server side.

NO_DES3 removes the use of DES3 encryptions. DES3 is built-in by default because some older servers still use it and it's required by SSL 3.0.

NO_DH and NO_AES are the same as the two above, they are widely used.

NO_DSA removes DSA since it's being phased out of popular use.

NO_ERROR_STRINGS disables error strings. Error strings are located in src/internal.c for wolfSSL or wolfcrypt/src/asn.c for wolfCrypt.

NO_HMAC removes HMAC from the build.

NO_MD4 removes MD4 from the build, MD4 is broken and shouldn't be used.

NO_MD5 removes MD5 from the build.

NO_SHA256 removes SHA-256 from the build.

NO_PSK turns off the use of the pre-shared key extension. It is built-in by default.

NO_PWDBASED disables password-based key derivation functions such as PBKDF1, PBKDF2, and PBKDF from PKCS #12.

NO_RC4 removes the use of the ARC4 stream cipher from the build. ARC4 is built-in by default because it is still popular and widely used.

 

NO_RABBIT and NO_HC128 remove stream cipher extensions from the build.

NO_SESSION_CACHE can be defined when a session cache is not needed.  This should reduce memory use by nearly 3 kB.

NO_TLS turns off TLS.  We don’t recommend turning off TLS.

SMALL_SESSION_CACHE can be defined to limit the size of the SSL session cache used by wolfSSL.  This will reduce the default session cache from 33 sessions to 6 sessions and save approximately 2.5 kB.

WC_NO_RSA_OAEP removes code for OAEP padding.

NO_AES_CBC turns off AES-CBC algorithm support.

NO_AES_128, NO_AES_192, and NO_AES_256 can be defined to determine the selection of key sizes at compile-time.

NO_DEV_URANDOM disables the use of "/dev/urandom"

WOLFSSL_IGNORE_FILE_WARN disables the use of build warnings when not building with autotools

2.4.5 Enabling Features Disabled by Default

WOLFSSL_CERT_GEN turns on wolfSSL’s certificate generation functionality.  See Chapter 7 for more information.

WOLFSSL_DER_LOAD allows loading DER-formatted CA certs into the wolfSSL context (WOLFSSL_CTX) using the function wolfSSL_CTX_der_load_verify_locations().

WOLFSSL_DTLS turns on the use of DTLS, or datagram TLS.  This isn't widely supported or used.

WOLFSSL_ENCRYPTED_KEYS turns on support for wolfSSL to use PEM encrypted keys using password callback without requiring "opensslextra".

WOLFSSL_KEY_GEN turns on wolfSSL’s RSA key generation functionality.  See Chapter 7 for more information.

WOLFSSL_RIPEMD enables RIPEMD-160 support.

WOLFSSL_SHA384 enables SHA-384 support.

WOLFSSL_SHA512 enables SHA-512 support.

DEBUG_WOLFSSL builds in the ability to debug. For more information regarding debugging wolfSSL, see Chapter 8.  

HAVE_AESCCM enables AES-CCM support.

HAVE_AESGCM enables AES-GCM support.

WOLFSSL_AES_XTS enables AES-XTS support.

HAVE_CAMELLIA enables Camellia support.

HAVE_CHACHA enables ChaCha20 support.

HAVE_POLY1305 enables Poly1305 support.

HAVE_CRL enables Certificate Revocation List (CRL) support.

HAVE_CRL_IO enables blocking inline HTTP request on the CRL URL. It will load the CRL into the WOLFSSL_CTX and apply it to all WOLFSSL objects created from it.

HAVE_ECC enables Elliptical Curve Cryptography (ECC) support.

HAVE_LIBZ is an extension that can allow for compression of data over the connection.  It normally shouldn't be used, see the note below under configure notes libz.

HAVE_OCSP enables Online Certificate Status Protocol (OCSP) support.

OPENSSL_EXTRA builds even more OpenSSL compatibility into the library, and enables the wolfSSL OpenSSL compatibility layer to ease porting wolfSSL into existing applications which had been designed to work with OpenSSL. It is off by default.

TEST_IPV6 turns on testing of IPv6 in the test applications.  wolfSSL proper is IP neutral, but the testing applications use IPv4 by default.

HAVE_CSHARP turns on configuration options needed for C# wrapper.

HAVE_CURVE25519 turns on the use of curve25519 algorithm.

HAVE_ED25519 turns on use of the ed25519 algorithm.

CURVED25519_SMALL defines CURVE25519_SMALL and ED25519_SMALL.

CURVE25519_SMALL use small memory option for curve25519. This uses less memory, but is slower.

ED25519_SMALL use small memory option for ed25519. This uses less memory, but is slower.

WOLFSSL_DH_CONST turns off use of floating point values when performing Diffie Hellman operations and uses tables for XPOW() and XLOG(). Removes dependency on external math library.

WOLFSSL_TRUST_PEER_CERT turns on the use of trusted peer certificates. This allows for loading in a peer certificate to match with a connection rather than using a CA. When turned on if a trusted peer certificate is matched than the peer cert chain is not loaded and the peer is considered verified. Using CAs is preferred.


WOLFSSL_STATIC_MEMORY turns on the use of static memory buffers and functions. This allows for using static memory instead of dynamic.

WOLFMEM_IO_SZ can be defined to specify the desired static IO buffer size.

WOLFSSL_SESSION_EXPORT turns on the use of DTLS session export and import. This allows for serializing and sending/receiving the current state of a DTLS session.

WOLFSSL_ARMASM turns on the use of ARMv8 hardware acceleration.

WC_RSA_NONBLOCK turns on fast math RSA non-blocking support for splitting RSA operations into smaller chunks of work. Feature is enabled by calling wc_RsaSetNonBlock and checking for FP_WOULDBLOCK return code.

WOLFSSL_RSA_VERIFY_ONLY turns on small build for RSA verify only use. Should be used with the macros WOLFSSL_RSA_PUBLIC_ONLY, WOLFSSL_RSA_VERIFY_INLINE, NO_SIG_WRAPPER, and WOLFCRYPT_ONLY.

WOLFSSL_RSA_PUBLIC_ONLY turns on small build for RSA public key only use. Should be used with the macro WOLFCRYPT_ONLY.

WOLFSSL_RSA_PUBLIC_ONLY turns on small build for RSA public key only use. Should be used with the macro WOLFCRYPT_ONLY.

WOLFSSL_SHA3 turns on build for SHA3 use. This is  support for SHA3 Keccak for the sizes SHA3-224, SHA3-256, SHA3-384 and SHA3-512. In addition WOLFSSL_SHA3_SMALL can be used to trade off performance for resource use.

2.4.6 Customizing or Porting wolfSSL

WOLFSSL_ALLOW_MAX_FRAGMENT_ADJUST if defined enables a feature which allows the maximum fragment size to be adjusted post-handshake.

WOLFSSL_MAX_SIGALGO provides the ability to override the maximum number of signature algorithms.

WOLFSSL_USER_SETTINGS if defined allows a user specific settings file to be used. The file must be named “user_settings.h” and exist in the include path. This is included prior to the standard “settings.h” file, so default settings can be overridden.

WOLFSSL_CALLBACKS is an extension that allows debugging callbacks through the use of signals in an environment without a debugger, it is off by default. It can also be used to set up a timer with blocking sockets. Please see Chapter 6 for more information.

WOLFSSL_USER_IO allows the user to remove automatic setting of the default I/O functions EmbedSend() and EmbedReceive(). Used for custom I/O abstraction layer (see Section 5.1 for more details).

 

NO_FILESYSTEM is used if stdio isn't available to load certificates and key files. This enables the use of buffer extensions to be used instead of the file ones.

NO_INLINE disables the automatic inlining of small, heavily used functions. Turning this on will slow down wolfSSL and actually make it bigger since these are small functions, usually much smaller than function call setup/return.  You’ll also need to add wolfcrypt/src/misc.c to the list of compiled files if you’re not using autoconf.

NO_DEV_RANDOM disables the use of the default /dev/random random number generator. If defined, the user needs to write an OS-specific GenerateSeed() function (found in “wolfcrypt/src/random.c”).

 

NO_MAIN_DRIVER is used in the normal build environment to determine whether a test application is called on its own or through the testsuite driver application.  You'll only need to use it with the test files: test.c, client.c, server.c, echoclient.c, echoserver.c, and testsuite.c

NO_WRITEV disables simulation of writev() semantics.

NO_MULTIBYTE_PRINT is used to compile out special characters that some embedded devices may have difficulty processing.

SINGLE_THREADED is a switch that turns off the use of mutexes. wolfSSL currently only uses one for the session cache.  If your use of wolfSSL is always single threaded you can turn this on.

USER_TICKS allows the user to define their own clock tick function if time(0) is not wanted. Custom function needs second accuracy, but doesn’t have to be correlated to Epoch.  See LowResTimer() function in “wolfssl_int.c”.

 

USER_TIME disables the use of time.h structures in the case that the user wants (or needs) to use their own. See “wolfcrypt/src/asn.c” for implementation details. The user will need to define and/or implement XTIME(), XGMTIME(), and XVALIDATE_DATE().

USE_CERT_BUFFERS_1024 enables 1024-bit test certificate and key buffers located in <wolfssl_root>/wolfssl/certs_test.h.  Helpful when testing on and porting to embedded systems with no filesystem.

USE_CERT_BUFFERS_2048 enables 2048-bit test certificate and key buffers located in <wolfssl_root>/wolfssl/certs_test.h.  Helpful when testing on and porting to embedded systems with no filesystem.

USE_WOLF_TIME_T defining this option enables the library to use an internal time struct value.

USE_WOLF_STRTOK can be defined to allow the library to use the wolfSSL implementation of the function strtok.

USE_ECDSA_KEYSZ_HASH_ALGO can be defined to limit the size of the signature and algorithm hash digests to the ephemeral key sizes.

CUSTOM_RAND_GENERATE_SEED allows user to define custom function equivalent to wc_GenerateSeed(byte* output, word32 sz).

CUSTOM_RAND_GENERATE_BLOCK allows user to define custom random number generation function.
Examples of use are as follows.

        ./configure --disable-hashdrbg 
        CFLAGS="-DCUSTOM_RAND_GENERATE_BLOCK= custom_rand_generate_block"

or

/* RNG */

/* #define HAVE_HASHDRBG */

extern int custom_rand_generate_block(unsigned char* output,

                                      unsigned int sz);

WOLFSSL_SSLKEYLOGFILE allows the user to inspect the Pre-Master-Secret and other information when capturing packets with Wireshark. This option requires that SHOW_SECRETS be defined as well. These options are both HIGHLY INSECURE, and under no circumstances should these options be used within production builds.

WC_MAX_SYM_KEY_SIZE defines the max size of symmetric keys in the wolfSSL library. If not defined by the user, wolfSSL will define this macro as one eighth of max AES key size (if AES is enabled).

WOLFSSL_BASE16 allows the user to enable base 16 encoding or decoding.

2.4.7 Reducing Memory Usage

TFM_TIMING_RESISTANT can be defined when using fast math (USE_FAST_MATH) on systems with a small stack size.  This will get rid of the large static arrays.

WOLFSSL_SMALL_STACK can be used for devices which have a small stack size.  This increases the use of dynamic memory in wolfcrypt/src/integer.c, but can lead to slower performance.

RSA_LOW_MEM when defined CRT is not used which saves on some memory but slows down RSA operations. It is off by default.

USE_SLOW_SHA, USE_SLOW_SHA256, USE_SlOW_SHA512 when defined these macros reduce memory and resource usage for their corresponding SHA algorithms, at the cost of speed.

WOLFSSL_SHA3_SMALL when SHA3 is enabled this macro will reduce build size.

2.4.8 Increasing Performance

WOLFSSL_AESNI enables use of AES accelerated operations which are built into some Intel and AMD chipsets.  When using this define, the aes_asm.c file must be added to the wolfSSL build sources.

USE_FAST_MATH switches the big integer library to a faster one that uses assembly if possible.  fastmath will speed up public key operations like RSA, DH, and DSA.  The big integer library is generally the most portable and generally easiest to get going with, but the negatives to the normal big integer library are that it is slower and it uses a lot of dynamic memory.  Because the stack memory usage can be larger when using fastmath, we recommend defining TFM_TIMING_RESISTANT as well when using this option.

2.4.9 Stack or Chip Specific Defines

wolfSSL can be built for a variety of platforms and TCP/IP stacks.  Most of the following defines are located in ./wolfssl/wolfcrypt/settings.h and are commented out by default.  Each can be uncommented to enable support for the specific chip or stack referenced below.

IPHONE can be defined if building for use with iOS.

THREADX can be defined when building for use with the ThreadX RTOS (www.rtos.com).

MICRIUM can be defined when building wolfSSL to enable support for Micrium’s µC/OS-III RTOS (www.micrium.com).

MBED can be defined when building for the mbed prototyping platform (www.mbed.org).

MICROCHIP_PIC32 can be defined when building for Microchip’s PIC32 platform (www.microchip.com).

MICROCHIP_TCPIP_V5 can be defined specifically version 5 of microchip tcp/ip stack.

MICROCHIP_TCPIP can be defined for microchip tcp/ip stack version 6 or later.

WOLFSSL_MICROCHIP_PIC32MZ can be defined for PIC32MZ hardware cryptography engine.

FREERTOS can be defined when building for FreeRTOS (www.freertos.org). If using LwIP, define WOLFSSL_LWIP as well.

FREERTOS_WINSIM can be defined when building for the FreeRTOS windows simulator (www.freertos.org).

EBSNET can be defined when using EBSnet products and RTIP.

WC_RNG_BLOCKING can be defined to enable block with sleep.

WOLFSSL_LWIP can be defined when using wolfSSL with the LwIP TCP/IP stack (http://savannah.nongnu.org/projects/lwip/).

WOLFSSL_GAME_BUILD can be defined when building wolfSSL for a game console.

WOLFSSL_LSR can be defined if building for LSR.

FREESCALE_MQX can be defined when building for Freescale MQX/RTCS/MFS (www.freescale.com).  This in turn defines FREESCALE_K70_RNGA to enable support for the Kinetis H/W Random Number Generator Accelerator

WOLFSSL_STM32F1 can be defined when building for STM32F1.

WOLFSSL_STM32F2 can be defined when building for STM32F2. This define also enables STM32F2 hardware crypto and hardware RNG support in wolfSSL. (http://www.st.com/internet/mcu/subclass/1520.jsp)

COMVERGE can be defined if using Comverge settings.

WOLFSSL_QL can be defined if using QL SEP settings.

WOLFSSL_EROAD can be defined building for EROAD.

WOLFSSL_IAR_ARM can be defined if build for IAR EWARM.

WOLFSSL_TIRTOS can be defined when building for TI-RTOS.

WOLFSSL_ROWLEY_ARM can be defined when building with Rowley CrossWorks.

WOLFSSL_NRF51 can be defined when porting to Nordic nRF51.

WOLFSSL_NRF51_AES can be defined to use built-in AES hardware for AES 128 ECB encrypt when porting to Nordic nRF51.

WOLFSSL_CONTIKI can be defined to enable support for the Contiki operating system.

WOLFSSL_APACHE_MYNEWT can be defined to enable the Apache Mynewt port layer.

ASIO_USE_WOLFSSL can be defined to make wolfSSL build as an ASIO-compatible version. ASIO then relies on the BOOST_ASIO_USE_WOLFSSL preprocessor define.

2.5 Build Options (./configure Options)


The following are options which may be appended to the ./configure script to customize how the wolfSSL library is built.

By default, wolfSSL only builds in shared mode, with static mode being disabled. This speeds up build times by a factor of two. Either mode can be explicitly disabled or enabled if desired.

Option

Default Value

Description

--enable-16bit

Disabled

Enable 16 bit support

--enable-32bit

Disabled

Enable 32 bit support

--enable-aes

Enabled

Enable AES

--enable-aescbc

Enabled

Used to with --disable-aescbc to compile out AES-CBC

--enable-aesccm

Disabled

Enable AES-CCM support

--enable-aescfb

Disabled

Turns on AES-CFB mode support

--enable-aesctr

Disabled

Enable wolfSSL AES-CTR support

--enable-aesgcm

Enabled

Enable AES-GCM support

--enable-aeskeywrap

Disabled

Enable AES key wrap support

--enable-aesni

Disabled

Enable wolfSSL Intel AES-NI support

--enable-afalg

Disabled

Enables use of Linux module AF_ALG for hardware acceleration. Additional Xilinx use with =xilinx, =xilinx-rsa, =xilinx-aes, =xilinx-sha3

--enable-all

Disabled

Enables all wolfSSL features, excluding SSL v3

--enable-alpn

Disabled

Enable Application Layer Protocol Negotiation (ALPN)

--enable-anon

Disabled

Enable Anonymous

--enable-arc4

Disabled

Enable ARC4

--enable-asio

Disabled

Enables ASIO

--enable-asm

Enabled

Enable options for assembly, enables all inline assembly.

--enable-asn

Enabled

Enable ASN

--enable-asynccrypt

Disabled

Enable Asynchronous Crypto

--enable-atomicuser

Disabled

Enable Atomic User Record Layer

--enable-base16

Disabled

Base 16 encoding/decoding

--enable-base64encode

Enabled on x86_64

Enable Base64 encoding

--enable-bigcache

Disabled

Enable a big session cache

--enable-blake2

Disabled

Enable wolfSSL BLAKE2 support

--enable-bump

Disabled

Enable SSL Bump build

--enable-camellia

Disabled

Enable Camellia support

--enable-certgen

Disabled

Enable cert generation

--enable-certreq

Disabled

Enable cert request generation

--enable-certservice

Disabled

Enable certificate service (Windows Servers)

--enable-chacha

Enabled

Enable CHACHA

--enable-coding

Enabled

Enable Coding base 16/64

--enable-compkey

Disabled

Enable compressed keys support

--enable-crl

Disabled

Enable CRL

--enable-crl-monitor

Disabled

Enable CRL Monitor

--enable-cryptocb

Disabled

Enable crypto callbacks

--enable-cryptonly

Disabled

Enable wolfCrypt Only build

--enable-crypttests

Enabled

Enable Crypt Bench/Test

--enable-curve25519

Disabled

Enable Curve25519 (or `--enable-curve25519=small` for CURVE25519_SMALL)

--enable-debug

Disabled

Enable wolfSSL debugging support

--enable-des3

Enabled

Enable DES3

--enable-devcrypto

Disabled

Enables use of Linux /dev/crypto for hardware acceleration

--enable-dh

Enabled

Enable DH

--enable-distro

Disabled

Enable wolfSSL distro build

--enable-dsa

Disabled

Enable Digital Signature Algorithm (DSA)

--enable-dtls

Disabled

Enable wolfSSL DTLS support

--enable-ecc

Enabled on x86_64

Enable ECC

--enable-ecccustcurves

Disabled

Enable ECC custom curves

--enable-eccencrypt

Disabled

Enable ECC encrypt

--enable-eccshamir

Enabled on x86_64

Enable ECC Shamir

--enable-ed25519

Disabled

Enable ED25519 (or `--enable-ed25519=small` for ED25519_SMALL)

--enable-enckeys

Disabled

Enable PEM encrypted private key support

--enable-errorstrings

Enabled

Enable error strings table

--enable-examples

Enabled

Enable examples

--enable-extended-master

Enabled

Enable Extended Master Secret

--enable-fast-rsa

Disabled

Enable RSA using Intel IPP

--enable-fasthugemath

Disabled

Enable fast math + huge code

--enable-fastmath

Enabled on x86_64

Enable fast math ops

--enable-filesystem

Enabled

Enable Filesystem support

--enable-fips

Disabled

Enable FIPS 140-2 (Must have license to implement.)

--enable-fpecc

Disabled

Enable Fixed Point cache ECC

--enable-harden

Enabled

Enable Hardened build, Enables Timing Resistance and Blinding

--enable-hashdrbg

Enabled

Enable Hash DRBG support

--enable-hc128

Disabled

Enable streaming cipher HC-128

--enable-hkdf

Disabled

Enable HKDF (HMAC-KDF)

--enable-hugecache

Disabled

Enable a huge session cache

--enable-idea

Disabled

Enable IDEA Cipher

--enable-inline

Enabled

Enable inline functions

--enable-intelasm

Disabled

Enable ASM speedups for Intel and AMD processors

--enable-iopool

Disabled

Enable I/O Pool example

--enable-ipv6

Disabled

Enable testing of IPv6, wolfSSL proper is IP neutral

--enable-jni

Disabled

Enable wolfSSL JNI

--enable-jobserver [=no/yes/#]

yes

Enable up to # make jobs

yes: enable one more than CPU count

--enable-keygen

Disabled

Enable key generation

--enable-leanpsk

Disabled

Enable Lean PSK build

--enable-leantls

Disabled

Implements a lean TLS 1.2 client only (no client auth), ECC256, AES128 and SHA256 w/o Shamir. Meant to be used by itself at the moment and not in conjunction with other build options.

--enable-lighty

Disabled

Enable lighttpd/lighty

--enable-lowresource

Disabled

Enable low resource usage options for memory/flash

--enable-maxfragment

Disabled

Enable Maximum Fragment Length

--enable-maxstrength

Disabled

Enable Max Strength build, allows TSLv1.2-AEAD-PFS ciphers only

--enable-mcapi

Disabled

Enable Microchip API

--enable-mcast

Disabled

Enable wolfSSL DTLS multicast support

--enable-md2

Disabled

Enable MD2 support

--enable-md4

Disabled

Enable MD4

--enable-md5

Enabled

Enable MD5

--enable-memory

Enabled

Enable memory callbacks

--enable-nginx

Disabled

Enable wolfSSL support for use with NGINX web servers

--enable-nullcipher

Disabled

Enable wolfSSL NULL cipher support (no encryption)

--enable-ocsp

Disabled

Enable Online Certificate Status Protocol (OCSP)

--enable-ocspstapling

Disabled

Enable OCSP Stapling

--enable-ocspstapling2

Disabled

Enable OCSP Stapling version 2

--enable-oldnames

Enabled

Enable backward-compatibility with old names

--enable-oldtls

Enabled

Enable old TLS version < 1.2

--enable-openssh

Disabled

Enable OpenSSH compatibility build

--enable-opensslall

Disabled

Enable all OpenSSL API and compatibility (large size increase)

--enable-opensslextra

Disabled

Enable some extra OpenSSL API compatibility (size increase)

--enable-optflags

Enabled

Enable default optimization CFLAGS for the compiler

--enable-pkcallbacks

Disabled

Enable Public Key Callbacks

--enable-pkcs11

Disabled

Enable PKCS#11 access

--enable-pkcs7

Disabled

Enable PKCS#7 support

--enable-poly1305

Enabled

Enable wolfSSL POLY1305 support

--enable-psk

Disabled

Enable PSK (Pre Shared Keys)

--enable-pwdbased

Disabled

Enable PWDBASED

--enable-rabbit

Disabled

Enable streaming cipher RABBIT

--enable-renegotiation-indication

Disabled

Enable Renegotiation Indication

--enable-ripemd

Disabled

Enable wolfSSL RIPEMD-160 support

--enable-rng

Enabled

Enable compiling and using RNG

--enable-rsa

Enabled

Enable RSA

--enable-rsapss

Disabled

Enable RSA-PSS

--enable-rsapub

Disabled

Enabled RSA public key only support (note requires --enable-cryptonly)

--enable-rsavfy

Disabled

Enables RSA verify only support (note requires --enable-cryptonly)

--enable-savecert

Disabled

Enable persistent cert cache

--enable-savesession

Disabled

Enable persistent session cache

--enable-scep

Disabled

Enable wolfSCEP (Simple Certificate Enrollment Protocol)

--enable-scrypt

Disabled

Enable SCRYPT

--enable-sctp

Disabled

Enable wolfSSL DTLS-SCTP support

--enable-secure-renegotiation

Disabled

Enable Secure Renegotiation

--enable-sep

Disabled

Enable SEP extensions

--enable-session-ticket

Disabled

Enable Session Ticket

--enable-sessioncerts

Disabled

Enable session cert storing

--enable-sessionexport

Disabled

Enable export and import of sessions

--enable-sha

Enabled

Enable SHA

--enable-sha224

Enabled on x86_64

Enable wolfSSL SHA-224 support

--enable-sha3

Disabled (except x86_64/ Aarch64)

Enables wolfSSL SHA3 support (=small for small build)

--enable-sha512

Enabled on x86_64

Enable wolfSSL SHA-512 support

--enable-shared[=PKGS]

Disabled

Building shared wolfSSL libraries [default = no]

--enable-singlethreaded

Disabled

Enable single threaded mode, no multi thread protections

--enable-smallcache

Disabled

Enable small session cache

--enable-smallstack

Disabled

Enable Small Stack Usage

--enable-sni

Disabled

Enable Server Name Indication (SNI)

--enable-sniffer

Disabled

Enable wolfSSL sniffer support

--enable-sp

Disabled

Enable single-precision math for RSA, DH, and ECC to improve performance.

--enable-sp-asm

Disabled

Enable single-precision assembly implementation

--enable-srp

Disabled

Enable Secure Remote Password

--enable-sslv3

Disabled

Enable SSL version 3.0

--enable-stacksize

Disabled

Enable stack size info on examples

--enable-static[=PKGS]

Disabled

Building static wolfSSL libraries [default=no]

--enable-staticmemory

Disabled

Enable static memory use

--enable-stunnel

Disabled

Enable stunnel

--enable-supportedcurves

Disabled

Enable Supported Elliptic Curves

--enable-testcert

Disabled

Enable Test Cert

--enable-tls13

Disabled

Enable TLS 1.3 support

--enable-tlsv12

Enabled

Enable TLS 1.2 support

--enable-tlsv10

Disabled

Enable TLS 1.0 support

--enable-tlsx

Disabled

Enable all TLS extensions

--enable-trackmemory

Disabled

Enable memory use information on wolfCrypt and wolfSSL cleanup

--enable-truncatedhmac

Disabled

Enable Truncated Keyed-hash MAC (HMAC)

--enable-valgrind

Disabled

Enable valgrind for unit tests

--enable-webclient

Disabled

Enable web client

--enable-webserver

Disabled

Enable Web Server

--enable-ssh

Disabled

Enable wolfSSH options

--enable-x963kdf

Disabled

Enable X9.63 KDF support

--enable-xilinx

Disabled

Enable wolfSSL support for Xilinx hardened encryption

--enable-xts

Disabled

Enables AES-XTS mode

--with-cavium=PATH

Disabled

Path to cavium/software directory.

--with-intelqa=PATH

Disabled

Path to Intel QuickAssist (QAT) driver directory.

--with-libz=PATH

Disabled

Optionally include libz for compression

--with-ntru=PATH

Disabled

Path to NTRU install (default /usr/)

--with-user-crypto=PATH

Disabled

Path to USER_CRYPTO install (default /usr/local).

2.5.1 Build Option Notes

tls13 - this build option can be combined with "--disable-tlsv12" and "--disable-oldtls" to produce a wolfSSL build that is only TLS 1.3.

debug - enabling debug support allows easier debugging by compiling with debug information and defining the constant DEBUG_WOLFSSL which outputs messages to stderr. To turn debug on at runtime, call wolfSSL_Debugging_ON(). To turn debug logging off at runtime, call wolfSSL_Debugging_OFF().  For more information, see Chapter 8.

singlethreaded - enabling single threaded mode turns off multi thread protection of the session cache. Only enable single threaded mode if you know your application is single threaded or your application is multithreaded and only one thread at a time will be accessing the library.

dtls - enabling DTLS support allows users of the library to also use the DTLS protocol in addition to TLS and SSL. For more information, see Chapter 4.

opensslextra - enabling OpenSSL Extra includes a larger set of OpenSSL compatibility functions. The basic build will enable enough functions for most TLS/SSL needs, but if you're porting an application that uses 10s or 100s of OpenSSL calls, enabling this will allow better support. The wolfSSL OpenSSL compatibility layer is under active development, so if there is a function missing which you need, please contact us and we'll try to help. For more information about the OpenSSL Compatibility Layer, please see Chapter 13.

 

ipv6 - enabling IPV6 changes the test applications to use IPv6 instead of IPv4. wolfSSL proper is IP neutral, either version can be used, but currently the test applications are IP dependent, IPv4 by default.

leanpsk - Very small build using PSK, and eliminating many features from the library. Approximate build size for wolfSSL on an embedded system with this enabled is 21kB.

fastmath - enabling fastmath will speed up public key operations like RSA, DH, and DSA.  By default, wolfSSL uses the normal big integer math library.  This is generally the most portable and generally easiest to get going with.  The negatives to the normal big integer library are that it is slower and it uses a lot of dynamic memory.  This option switches the big integer library to a faster one that uses assembly if possible.  Assembly inclusion is dependent on compiler and processor combinations. Some combinations will need additional configure flags and some may not be possible. Help with optimizing fastmath with new assembly routines is available on a consulting basis.

On ia32, for example, all of the registers need to be available so high optimization and omitting the frame pointer needs to be taken care of. wolfSSL will add "-O3 -fomit-frame-pointer" to GCC for non debug builds. If you're using a different compiler you may need to add these manually to CFLAGS during configure.

OS X will also need "-mdynamic-no-pic" added to CFLAGS. In addition, if you're building in shared mode for ia32 on OS X you'll need to pass options to LDFLAGS as well:

LDFLAGS="-Wl,-read_only_relocs,warning"

This gives warning for some symbols instead of errors.

fastmath also changes the way dynamic and stack memory is used. The normal math library uses dynamic memory for big integers. Fastmath uses fixed size buffers that hold 4096 bit integers by default, allowing for 2048 bit by 2048 bit multiplications. If you need 4096 bit by 4096 bit multiplications then change FP_MAX_BITS in wolfssl/wolfcrypt/tfm.h. As FP_MAX_BITS is increased, this will also increase the runtime stack usage since the buffers used in the public key operations will now be larger. A couple of functions in the library use several temporary big integers, meaning the stack can get relatively large. This should only come into play on embedded systems or in threaded environments where the stack size is set to a low value. If stack corruption occurs with fastmath during public key operations in those environments, increase the stack size to accommodate the stack usage.

If you are enabling fastmath without using the autoconf system, you’ll need to define USE_FAST_MATH and add tfm.c to the wolfSSL build instead of integer.c.

Since the stack memory can be large when using fastmath, we recommend defining TFM_TIMING_RESISTANT when using the fastmath library.  This will get rid of large static arrays.

fasthugemath - enabling fasthugemath includes support for the fastmath library and greatly increases the code size by unrolling loops for popular key sizes during public key operations. Try using the benchmark utility before and after using fasthugemath to see if the slight speedup is worth the increased code size.

bigcache - enabling the big session cache will increase the session cache from 33 sessions to 20,027 sessions. The default session cache size of 33 is adequate for TLS clients and embedded servers. The big session cache is suitable for servers that aren't under heavy load, basically allowing 200 new sessions per minute or so.

hugecache - enabling the huge session cache will increase the session cache size to 65,791 sessions. This option is for servers that are under heavy load, over 13,000 new sessions per minute are possible or over 200 new sessions per second.

smallcache - enabling the small session cache will cause wolfSSL to only store 6 sessions. This may be useful for embedded clients or systems where the default of nearly 3kB is too much RAM. This define uses less than 500 bytes of RAM.

savesession - enabling this option will allow an application to persist (save) and restore the wolfSSL session cache to/from memory buffers.

savecert - enabling this option will allow an application to persist (save) and restore the wolfSSL certificate cache to/from memory buffers.

atomicuser - enabling this option will turn on User Atomic Record Layer Processing callbacks. This will allow the application to register its own MAC/encrypt and decrypt/verify callbacks.

pkcallbacks - enabling this option will turn on Public Key callbacks, allowing the application to register its own ECC sign/verify and RSA sign/verify and encrypt/decrypt callbacks.

sniffer - enabling sniffer (SSL inspection) support will allow the collection of SSL traffic packets as well as the ability to decrypt those packets with the correct key file.

Currently the sniffer supports the following RSA ciphers

CBC ciphers:

  • AES-CBC
  • Camellia-CBC
  • 3DES-CBC

Stream ciphers:

  • RC4
  • Rabbit
  • HC-128

aesgcm - enabling AES-GCM will add these cipher suites to wolfSSL.  wolfSSL offers four different implementations of AES-GCM balancing speed versus memory consumption. If available, wolfSSL will use 64-bit or 32-bit math. For embedded applications, there is a speedy 8-bit version that uses RAM-based lookup tables (8KB per session) which is speed comparable to the 64-bit version and a slower 8-bit version that doesn't take up any additional RAM. The --enable-aesgcm configure option may be modified with the options "=word32", "=table", or "=small", i.e. "--enable-aesgcm=table".

aesccm - enabling AES-GCM will enable Counter with CBC-MAC Mode with 8‑byte authentication (CCM-8) for AES.

aesni - enabling AES-NI support will allow AES instructions to be called directly from the chip when using an AES-NI supported chip. This provides speed increases for AES functions.  See Chapter 4 for more details regarding AES-NI.

poly1305 - enabling this option will add Poly1305 support to wolfCrypt and wolfSSL.

camellia - enabling this option will add Camellia-CBC support to wolfCrypt and wolfSSL.

chacha - enabling this option will add ChaCha support to wolfCrypt and wolfSSL.

md2 - enabling this option adds support for the MD2 algorithm to wolfSSL. MD2 is disabled by default due to known security vulnerabilities.

ripemd - enabling this option adds support for the RIPEMD-160 algorithm to wolfSSL.

sha512 - enabling this option adds support for the SHA-512 hash algorithm. This algorithm needs the word64 type to be available, which is why it is disabled by default.  Some embedded system may not have this type available.

sessioncerts - enabling this option adds support for the peer’s certificate chain in the session cache through the wolfSSL_get_peer_chain(), wolfSSL_get_chain_count(), wolfSSL_get_chain_length(), wolfSSL_get_chain_cert(), wolfSSL_get_chain_cert_pem(), and wolfSSL_get_sessionID() functions.

keygen - enabling support for RSA key generation allows generating keys of varying lengths up to 4096 bits. wolfSSL provides both DER and PEM formatting.

certgen - enables support for self-signed X.509 v3 certificate generation.

certreq - enabling this option will add support for certificate request generation.

hc128 - Though we really like the speed of the HC-128 streaming cipher, it takes up some room in the cipher union for users who aren’t using it. To keep the default build small in as many aspects as we can, we’ve disabled this cipher by default.  In order to use this cipher or the corresponding cipher suite just turn it on, no other action is required.

rabbit - enabling this option adds support for the RABBIT stream cipher.

psk - Pre Shared Key support is off by default since it’s not commonly used. To enable this feature simply turn it on, no other action is required.

poly1305 - enabling this option adds support for Poly1305 to wolfcrypt and wolfSSL.

webserver - this turns on functions required over the standard build that will allow full functionality for building with the yaSSL Embedded Web Server.

noFilesystem - this makes it easier to disable filesystem use.  This option defines NO_FILESYSTEM.

inline - disabling this option disables function inlining in wolfSSL.  Function placeholders that are not linked against but, rather, the code block is inserted into the function call when function inlining is enabled.

ecc - enabling this option will build ECC support and cipher suites into wolfSSL.

ocsp - enabling this option adds OCSP (Online Certificate Status Protocol) support to wolfSSL. It is used to obtain the revocation status of x.509 certificates as described in RFC 6960.

crl - enabling this option adds CRL (Certificate Revocation List) support to wolfSSL.

crl-monitor - enabling this option adds the ability to have wolfSSL actively monitor a specific CRL (Certificate Revocation List) directory.

ntru - this turns on the ability for wolfSSL to use NTRU cipher suites. NTRU is now available under the GPLv2 from Security Innovation.  The NTRU bundle may be downloaded from the Security Innovation GitHub repository available at https://github.com/NTRUOpenSourceProject/ntru-crypto.

sni - enabling this option will turn on the TLS Server Name Indication (SNI) extension.

maxfragment - enabling this option will turn on the TLS Maximum Fragment Length extension.

truncatedhmac - enabling this option will turn on the TLS Truncated HMAC extension.

supportedcurves - enabling this option will turn on the TLS Supported ECC Curves extension.

tlsx - enabling this option will turn on all TLS extensions currently supported by wolfSSL.

valgrind - enabling this option will turn on valgrind when running the wolfSSL unit tests. This can be useful for catching problems early on in the development cycle.

testcert - when this option is enabled, it exposes part of the ASN certificate API that is usually not exposed.  This can be useful for testing purposes, as seen in the wolfCrypt test application (wolfcrypt/test/test.c).

examples - this option is enabled by default. When enabled, the wolfSSL example applications will be built (client, server, echoclient, echoserver).

gcc-hardening - enabling this option will add extra compiler security checks.

jobserver - enabling this option allows “make” on computers with multiple processors to build several files in parallel, which can significantly reduce build times.  Users have the ability to pass different arguments to this command (yes/no/#).  If “yes” is used, the configure script will tell make to use one more than the CPU count for the number of jobs. “no” obviously disables this feature.  Optionally, the user can pass in the number of jobs as well.

disable shared - disabling the shared library build will exclude a wolfSSL shared library from being built. By default only a shared library is built in order to save time and space.

disable static - disabling the static library build will exclude a wolfSSL static library from being built.  This options is enabled by default.  A static library can be built by using the --enable-static build option.

libz - enabling libz will allow compression support in wolfSSL from the libz library. Think twice about including this option and using it by calling wolfSSL_set_compression() . While compressing data before sending decreases the actual size of the messages being sent and received, the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks.

fast-rsa - enabling fast-rsa speeds up RSA operations by using IPP libraries. It has a larger memory consumption then the default RSA set by wolfSSL. If IPP libraries can not be found an error message will be displayed during configuration. The first location that autoconf will look is in the directory wolfssl_root/IPP the second is standard location for libraries on the machine such as /usr/lib/ on linux systems.

The libraries used for RSA operations are in the directory “wolfssl-X.X.X/IPP/” where X.X.X is the current wolfSSL version number. Building from the bundled libraries is dependent on the directory location and name of IPP so the file structure of the subdirectory IPP should not be changed.

When allocating memory the fast-rsa operations have a memory tag of DYNAMIC_TYPE_USER_CRYPTO. This allows for viewing the memory consumption of RSA operations during run time with the fast-rsa option.  

leantls - enabling produces a small footprint TLS client that supports TLS 1.2 client only (no client auth), ECC256, AES128 and SHA256 w/o Shamir. Meant to be used by itself at the moment and not in conjunction with other build options.

curve25519 - an elliptic curve offering 128 bits of security and to be used with ECDH key  agreement (see § 2.6 Cross Compiling).

renegotiation-indication - as described in RFC 5746, this specification prevents an SSL/TLS attack involving renegotiation splicing by tying the renegotiations to the TLS connection they are performed over.

scep - as defined by the Internet Engineering Task Force, Simple Certificate Enrollment Protocol is a PKI that leverages PKCS#7 and PKCS#10 over HTTP. CERT notes that SCEP does not strongly authenticate certificate requests.

dsa - NIST approved digital signature algorithm along with RSA and ECDSA as defined by FIPS 186-4 and are used to generate and verify digital signatures if used in conjunction with an approved hash function as defined by the Secure Hash Standard (FIPS 180-4).

curve25519 - enabling curve25519 option allows for the use of the curve25519 algorithm. The default curve25519 is set to use more memory but have a faster run time. To have the algorithm use less memory the option -”-enable-curve25519=small” can be used. Although using less memory there is a trade off in speed.

ed25519 - enabling ed25519 option allows for the use of the ed25519 algorithm. The default ed25519 is set to use more memory but have a faster run time. To have the algorithm use less memory the option ”--enable-ed25519=small” can be used. Like with curve25519 using this enable option less is a trade off between speed and memory. As ed25519 is one of the algorithms now included in the base specification for TLS 1.3, wolfSSL also provides support for using ed25519 with TLS 1.3 and TLS 1.2.

Intelasm - enabling the intelasm option for wolfSSL will utilize expanded capabilities of your processor that dramatically enhance AES performance. The instruction sets leveraged when configure option is enabled include AVX1, AVX2, BMI2, RDRAND, RDSEED, AESNI, and ADX. These were first introduced into Intel processors and AMD processors have started adopting them in recent years. When enabled, wolfSSL will check the processor and take advantage of the instruction sets your processor supports.

sp-asm can be used to enable single-precision performance improvements through assembly with ARM and 64-bit ARM architectures.

armasm  the default configure sets mcpu or mfpu based on 64 vs 32 bit system. It does not overwrite mcpu or mfpu setting passed in by use of CPPFLAGS. On some compilers -mstrict-align may be needed due to the m constraints and -mstrict-align is now also set by default unless a user passes in mcpu/mfpu flags with CPPFLAGS.

asio requires that the options "opensslextra" and "opensslall" be enabled when configuring wolfSSL. If these two options are not enabled, then the autoconf tool will automatically enable these options to enable ASIO when configuring wolfSSL.

devcrypto has the ability to receive arguments, being able to receive any combination of aes (all aes support), hash (all hash algorithms), and cbc (aes-cbc only). If no options are given, it will default to using all (aes, hash).

cryptodev allows wolfSSL users to utilize the Linux kernel's built in cryptographic drivers through encryption callbacks. Note that is feature is distinctly different from devcrypto, and since versions 4.0.0 has been deprecated in favor of the cryptocb option.

cryptocb allows users to utilize the Linux kernel's built in cryptographic drivers though encryption callbacks.

afalg is similar to devcrypto in that it leverages a Linux kernel module (AF_ALG) for offloading crypto operations. On some hardware the module has performance accelerations available through the Linux crypto drivers. In the case of Petalinux with Xilinx the flag --enable-afalg=xilinx can be used to tell wolfSSL to use the Xilinx interface for AF_ALG.

nginx is used to enable wolfSSL support for use with NGINX and NGINX web servers. This option can be combined with "tls13" or other configure options that specify TLS versions.

optflags can be disabled to turn off the default flags and settings that are defined in the settings.h file used by wolfSSL, allowing the user to define their own flags.

2.6 Cross Compiling


Many users on embedded platforms cross compile wolfSSL for their environment.  The easiest way to cross compile the library is to use the ./configure system.  It will generate a Makefile which can then be used to build wolfSSL. However, more recent versions (post 3.12.2) include an example Makefile for GCC-ARM architectures. This Makefile can be found in <wolfssl-root>/IDE/GCC-ARM/Makefile.

When cross compiling, you’ll need to specify the host to ./configure, such as:

./configure --host=arm-linux

You may also need to specify the compiler, linker, etc. that you want to use:

./configure --host=arm-linux CC=arm-linux-gcc AR=arm-linux-ar RANLIB=arm-linux

The C language standard can also be changed by either defining the macro WOLF_C99 in the user's settings file, or by defining it within CFLAGS when running the configure script.

There is a bug in the configure system which you might see when cross compiling and detecting user overriding malloc.  If you get an undefined reference  to ‘rpl_malloc’ and/or ‘rpl_realloc’, please add the following to your ./configure line:

ac_cv_func_malloc_0_nonnull=yes ac_cv_func_realloc_0_nonnull=yes

After correctly configuring wolfSSL for cross-compilation, you should be able to follow standard autoconf practices for building and installing the library:

make

sudo make install

If you have any additional tips or feedback about cross compiling wolfSSL, please let us know at info@wolfssl.com.

2.6.1 Example cross compile configure options for toolchain builds

Toolchain

Description

armebv7-eabihf-glibc

./configure --host=armeb-linux \

        CC=armeb-linux-gcc LD=armeb-linux-ld \

        AR=armeb-linux-ar \

        RANLIB=armeb-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

armv5-eabi-glibc

./configure --host=arm-linux \

        CC=arm-linux-gcc LD=arm-linux-ld \

        AR=arm-linux-ar \

        RANLIB=arm-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

armv6-eabihf-glibc

./configure --host=arm-linux \

        CC=arm-linux-gcc LD=arm-linux-ld \

        AR=arm-linux-ar \

        RANLIB=arm-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

armv7-eabihf-glibc

./configure --host=arm-linux \

        CC=arm-linux-gcc LD=arm-linux-ld \

        AR=arm-linux-ar \

        RANLIB=arm-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

armv7m-uclibc

./configure --enable-static --disable-shared \

        --host=arm-linux CC=arm-linux-gcc \

        LD=arm-linux-ld AR=arm-linux-ar \

        RANLIB=arm-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

arm-none-eabi-gcc

./configure --host=arm-none-eabi \                                                  

        CC=arm-none-eabi-gcc LD=arm-none-eabi-ld \                                     AR=arm-none-eabi-ar RANLIB=arm-none-eabi-ranlib \                              CFLAGS="-DNO_WOLFSSL_DIR \                                                     -DWOLFSSL_USER_IO -DNO_WRITEV \                                                -mcpu=cortex-m4 -mthumb -Os \                                                  -specs=rdimon.specs" CPPFLAGS="-I./"

mips32--glibc

./configure --host=mips-linux \

        CC=mips-linux-gcc LD=mips-linux-ld \

        AR=mips-linux-ar \

        RANLIB=mips-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

PowerPc64le-Power8-Glibc

./configure --host=powerpc64le-buildroot-linux-gnu \

        CC=powerpc64le-buildroot-linux-gnu-gcc \

        LD=powerpc64le-buildroot-linux-gnu-ld \

        AR=powerpc64le-buildroot-linux-gnu-ar \

        RANLIB=powerpc64le-buildroot-linux-gnu-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

x86-64-core-i7-glibc

./configure --host=x86_64-linux \

        CC=x86_64-linux-gcc LD=x86_64-linux-ld \

        AR=x86_64-linux-ar \

        RANLIB=x86_64-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

x86-64-core-i7-musl

./configure --host=x86_64-linux \

        CC=x86_64-linux-gcc LD=x86_64-linux-ld \

        AR=x86_64-linux-ar \

        RANLIB=x86_64-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"

x86-64-core-i7-uclibc

./configure --host=x86_64-linux \

        CC=x86_64-linux-gcc LD=x86_64-linux-ld \

        AR=x86_64-linux-ar \

        RANLIB=x86_64-linux-ranlib \

        CFLAGS="-DWOLFSSL_USER_IO -Os" \

        CPPFLAGS="-I./"