WOLFSSL MANUAL: CHAPTER 2

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:

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.

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

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.

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.

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.

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

Some defines that can modify the build are listed in the following sub-sections, 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.

Insert the "meta-wolfSSL" layer into the build's bblayers.confWithin the BBLAYERS section, add the path to the location where meta-wolfssl was cloned into. Example:BBLAYERS ?= "... \ /path/to/meta-wolfssl/ \ ..."

Build a wolfSSL product recipebitbake 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.

Edit local.confThe 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:

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 project file simplifies the process of building on STM32 devices, is free to download, and is createed by Atollic - a part of ST Microelectronics. To build the wolfSSL static library project file in TrueSTUDIO, it will require the user perform the following steps after opening TrueSTUDIO:

Import the project into the workspace (File > Import)

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 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_HMACremoves HMAC from the build.

NOTE: SSL/TLS depends on HMAC but if you are only using wolfCrypt IE build option "WOLFCRYPT_ONLY" then HMAC can be disabled in this case.

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

NO_MD5 removes MD5 from the build.

NO_SHA removes SHA-1 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_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.

NO_RSA removes support for the RSA algorithm.

WC_NO_RSA_OAEP removes code for OAEP padding.

NO_AES_CBC turns off AES-CBC algorithm support.

NO_DEV_URANDOM disables the use of "/dev/urandom"

WOLFSSL_NO_SIGALG disables the signature algorithms extension

NO_RESUME_SUITE_CHECK disables the check of cipher suite when resuming a TLS connection

NO_ASN Removes support for ASN formatted certificate processing.

NO_OLD_TLS Removes support for SSLv3, TLSv1.0 and TLSv 1.1

WOLFSSL_AEAD_ONLY Removes support for non-AEAD algorithms. AEAD stands for “authenticated encryption with associated data” which means these algorithms (such as AES-GCM) do not just encrypt and decrypt data, they also assure confidentiality and authenticity of that data.

2.4.4 Enabling Features Disabled by Default

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

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

WOLFSSL_KEY_GENturns 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.

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.

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.

USE_ECDSA_KEYSZ_HASH_ALGO will choose a hash algorithm that matches the ephemeral ECDHE key size or the next highest available. This workaround resolves issue with some peer's that do not properly support scenarios such as a P-256 key hashed with SHA512.

WOLFSSL_ALT_CERT_CHAIN allows CA's to be presented by peer, but not part of a valid chain. Default wolfSSL behavior is to require validation of all presented peer certificates. This also allows loading intermediate CA's as trusted and ignoring no signer failures for CA's up the chain to root. The alternate certificate chain mode only requires that the peer certificate validate to a trusted CA.

WOLFSSL_CUSTOM_CURVES allow non-standard curves. Includes the curve "a" variable in calculation. Additional curve types can be enabled using HAVE_ECC_SECPR2, HAVE_ECC_SECPR3, HAVE_ECC_BRAINPOOL and HAVE_ECC_KOBLITZ.

HAVE_COMP_KEY enables ECC compressed key support.

WOLFSSL_EXTRA_ALERTS enables additional alerts to be sent during a TLS connection. This feature is also enabled automatically when (--enable-opensslextra) is used.

HAVE_FALLBACK_SCSV enables Signaling Cipher Suite Value(SCSV) support on the server side. This handles the cipher suite 0x56 0x00 sent from a client to signal that no downgrade of TLS version should be allowed.

WOLFSSL_PSK_ONE_ID enables support for only one PSK ID with TLS 1.3.

SHA256_MANY_REGISTERS a SHA256 version that keeps all data in registers and partial unrolled.

WOLFCRYPT_HAVE_SRP Enables wolfcrypt secure remote password support

WOLFSSL_MAX_STRENGTH Enables the strongest security features only and disables any weak or deprecated features. Results in slower performance due to near constant time execution to protect against timing based side-channel attacks.

WOLFSSL_STATIC_RSA Static ciphers are strongly discouraged and should never be used if avoidable. However there are still legacy systems that ONLY support static cihper suites. To that end if you need to connect to a legacy peer only supporting static RSA cipher suites use this to enable support for static RSA in wolfSSL. (See also WOLFSSL_STATIC_PSK and WOLFSSL_STATIC_DH)

HAVE_NTRU Turns on support for NTRU cipher suites. NTRU offers a Quantum resistant Public Key solution. Read more about it on the WIKI page: https://en.wikipedia.org/wiki/NTRU

HAVE_NULL_CIPHER Turns on support for NULL ciphers. This option is highly discouraged from a security standpoint however some systems are too small to perform encrypt/decrypt operations and it is better to at least authenticate messages and peers to prevent message tampering than nothing at all!

HAVE_ANON Turns on support for anonymous cipher suites. (Never recommended, some valid use cases involving closed or private networks detached from the web)

2.4.5 Customizing or Porting wolfSSL

WOLFSSL_USER_SETTINGSif 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_IOallows 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.

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.

NO_PUBLIC_GCM_SET_IV use this if you have done your own custom hardware port and not provided a public implementation of wc_AesGcmSetIV()

NO_PUBLIC_CCM_SET_NONCE use this if you have done your own custom hardware port and not provided a public implementation of wc_AesGcmSetNonce()

NO_GCM_ENCRYPT_EXTRA use this if you have done your own custom hardware port and not provided an implementation of wc_AesGcmEncrypt_ex()

WOLFSSL_STM32[F1 | F2 | F4 | F7 | L4] use one of these defines when building for the appropriate STM32 device. Update wolfssl-root/wolfssl/wolfcrypt/settings.h section with regards to the wolfSSL porting guide (https://www.wolfssl.com/docs/porting-guide/) as appropriate.

WOLFSSL_STM32_CUBEMX when using the CubeMX tool to generate Hardware Abstraction Layer (HAL) API’s use this setting to add appropriate support in wolfSSL.

WOLFSSL_CUBEMX_USE_LL When using the CubeMX tool to generate APIs there are two options, HAL (Hardware Abstraction Layer) or Low Layer (LL). Use this define to control which headers are include in wolfssl-root/wolfssl/wolfcrypt/settings.h in the WOLFSSL_STM32[F1/F2/F4/F7/L4] section.

NO_STM32_CRYPTO For when an STM32 part does not offer hardware crypto support

NO_STM32_HASH For when an STM32 part does not offer hardware hash support

NO_STM32_RNG For when an STM32 part does not offer hardware RNG support

XTIME_MS Macro to map a function for use to get the time in milliseconds when using TLS 1.3. Example being

extern time_t m2mb_xtime_ms(time_t * timer);

#define XTIME_MS(tl) m2mb_xtime_ms((tl))

2.4.6 Reducing Memory or Code 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.

ALT_ECC_SIZE If using fast math and RSA/DH you can define this to reduce your ECC memory consumption. Instead of using stack for ECC points it will allocate from the heap.

2.4.7 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.asm (for Windows with at&t syntax) or aes_asm.S file is used to optimize via the Intel AES new instruction set (AESNI).

USE_FAST_MATHswitches 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.

FP_ECC enables ECC Fixed Point Cache, which speeds up repeated operations against same private key. Can also define number of entries and LUT bits using FP_ENTRIES and FP_LUT to reduce default static memory usage.

wolfSSL’s proprietary Single Precision math support

Use these to speed up public key operations for specific keys sizes and curves that are common. Make sure to include the correct code files such as:

2.4.8 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_TCPIPcan 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).

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

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.

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".

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.

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.

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.

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.

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

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.

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 constraiants 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).

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.

pkcs12 turns on code for doing PKCS12 operations.

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.

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:

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 facts@wolfssl.com.