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

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

  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 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:

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

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

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

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.

WOLFSSL_DEBUG_TLS enables additional debugging print outs during a TLS connection

HAVE_BLAKE2 enables Blake2s algorithm support

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.

HAVE_QSH Turns on support for cipher suites resistant to Shor's algorithm. QSH stands for “Quantum Safe Handshake.

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)

WOLFSSL_STATIC_PSK Static ciphers are highly discouraged see WOLFSSL_STATIC_RSA

WOLFSSL_STATIC_DH Static ciphers are highly discouraged see WOLFSSL_STATIC_RSA

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

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.

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

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.

ECC_SHAMIR uses variation of ECC math that is slightly faster, but doubles heap usage.

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

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

WOLFSSL_SMALL_CERT_VERIFY verify the certificate signature without using DecodedCert. Doubles up on some code but allows smaller peak heap memory usage. Cannot be used with WOLFSSL_NONBLOCK_OCSP.

GCM_SMALL option to reduce AES GCM code size by calculating at runtime instead of using tables. Possible options are: GCM_SMALL, GCM_WORD32 or GCM_TABLE.

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.

USE_SLOW_SHA reduces code size by not unrolling loops, which reduces performance for SHA.

USE_SLOW_SHA256 reduces code size by not unrolling loops, which reduces performance for SHA. About 2k smaller and about 25% slower.

USE_SLOW_SHA512 reduces code size by not unrolling loops, which reduces performance for SHA. Over twice as small, but 50% slower.

ECC_USER_CURVES allow user to choose ECC curve sizes that are enabled. Only the 256-bit curve is enabled by default. To enable others use HAVE_ECC192, HAVE_ECC224, etc....

WOLFSSL_SP_SMALL if using SP math this will use smaller versions of the code.

WOLFSSL_SP_MATH enable only SP math to reduce code size. Eliminates big integer math code such as normal (integer.c) or fast (tfm.c). Restricts key sizes and curves to only ones supported by SP.

2.4.7 Increasing Performance

USE_INTEL_SPEEDUP enables use of Intel’s AVX/AVX2 instructions for accelerating AES, ChaCha20, Poly1305, SHA256, SHA512, ED25519 and Curve25519.

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

HAVE_INTEL_RDSEED enable Intel’s RDSEED for DRBG seed source.

HAVE_INTEL_RDRAND enable Intel’s RDRAND instruction for wolfSSL’s random source.

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.

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:

  • sp_c32.c
  • sp_c64.c
  • sp_arm32.c
  • sp_arm64.c
  • sp_armthumb.c
  • sp_cortexm.c
  • sp_int.c
  • sp_x86_64.c
  • sp_x86_64_asm.S

WOLFSSL_SP enable Single Precision math support. 

WOLFSSL_SP_ASM enable assembly speedups for Single Precision

WOLFSSL_HAVE_SP_RSA Single Precision RSA for 1024, 2048 and 3096 bit.

WOLFSSL_HAVE_SP_DH Single Precision DH for 1024, 2048 and 3096 bit.

WOLFSSL_HAVE_SP_ECC Single Precision ECC for SECP256R1.

WOLFSSL_ASYNC_CRYPT Adds support for Asynchronous Crypto**

** Limited Software support, works best with Intel® QuickAssist Technology (Intel® QAT)

 and Cavium Nitrox V Processors

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

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

WOLFSSL_CRYPTOCELL  can be defined to enable using ARM CRYPTOCELL.

WOLFSSL_SIFIVE_RISC_V  can be defined to enable using RISC-V SiFive/HiFive port.

WOLFSSL_MDK_ARM Adds support for MDK ARM

WOLFSSL_MDK5 Adds support for MDK5 ARM

2.4.9 OS Specific Defines

USE_WINDOWS_API  specify use of windows library APIs’ as opposed to Unix/Linux APIs’

WIN32_LEAN_AND_MEAN adds support for the Microsoft win32 lean and mean build.

FREERTOS_TCP adds support for the FREERTOS TCP stack

WOLFSSL_SAFERTOS adds support for SafeRTOS

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-debug

Disabled

Enable wolfSSL debugging support

--enable-distro

Disabled

Enable wolfSSL distro build

--enable-singlethreaded

Disabled

Enable single threaded mode, no multi thread protections

--enable-dtls

Disabled

Enable wolfSSL DTLS support

--enable-rng

Enabled

Enable compiling and using RNG

--enable-sctp

Disabled

Enable wolfSSL DTLS-SCTP support

--enable-openssh

Disabled

Enable OpenSSH compatibility build

--enable-opensslextra

Disabled

Enable extra OpenSSL API compatibility, increases the size

Requires

--enable-maxstrength

Disabled

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

--enable-harden

Enabled

Enable Hardened build, Enables Timing Resistance and Blinding

--enable-ipv6

Disabled

Enable testing of IPv6, wolfSSL proper is IP neutral

--enable-bump

Disabled

Enable SSL Bump build

--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-bigcache

Disabled

Enable a big session cache

--enable-hugecache

Disabled

Enable a huge session cache

--enable-smallcache

Disabled

Enable small session cache

--enable-savesession

Disabled

Enable persistent session cache

--enable-savecert

Disabled

Enable persistent cert cache

--enable-atomicuser

Disabled

Enable Atomic User Record Layer

--enable-pkcallbacks

Disabled

Enable Public Key Callbacks

--enable-sniffer

Disabled

Enable wolfSSL sniffer support

--enable-aesgcm

Enabled

Enable AES-GCM support

--enable-aesccm

Disabled

Enable AES-CCM support

--enable-aescbc

Enabled

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

--enable-aescfb

Disabled

Turns on AES-CFB mode support

--enable-aesctr

Disabled

Enable wolfSSL AES-CTR support

--enable-aesni

Disabled

Enable wolfSSL Intel AES-NI support

--enable-intelasm

Disabled

Enable ASM speedups for Intel and AMD processors

--enable-camellia

Disabled

Enable Camellia support

--enable-md2

Disabled

Enable MD2 support

--enable-nullcipher

Disabled

Enable wolfSSL NULL cipher support (no encryption)

--enable-ripemd

Disabled

Enable wolfSSL RIPEMD-160 support

--enable-blake2

Disabled

Enable wolfSSL BLAKE2 support

--enable-blake2s

Disabled

Enable wolfSSL BLAKE2s 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-sessioncerts

Disabled

Enable session cert storing

--enable-keygen

Disabled

Enable key generation

--enable-certgen

Disabled

Enable cert generation

--enable-certreq

Disabled

Enable cert request generation

--enable-sep

Disabled

Enable SEP extensions

--enable-hkdf

Disabled

Enable HKDF (HMAC-KDF)

--enable-x963kdf

Disabled

Enable X9.63 KDF support

--enable-dsa

Disabled

Enable Digital Signature Algorithm (DSA)

--enable-eccshamir

Enabled on x86_64

Enable ECC Shamir

--enable-ecc

Enabled on x86_64

Enable ECC

--enable-ecccustcurves

Disabled

Enable ECC custom curves (=all to enable all curve types)

--enable-compkey

Disabled

Enable compressed keys support

--enable-curve25519

Disabled

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

--enable-ed25519

Disabled

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

--enable-fpecc

Disabled

Enable Fixed Point cache ECC

--enable-eccencrypt

Disabled

Enable ECC encrypt

--enable-psk

Disabled

Enable PSK (Pre Shared Keys)

--enable-errorstrings

Enabled

Enable error strings table

--enable-oldtls

Enabled

Enable old TLS version < 1.2

--enable-sslv3

Disabled

Enable SSL version 3.0

--enable-stacksize

Disabled

Enable stack size info on examples

--enable-memory

Enabled

Enable memory callbacks

--enable-rsa

Enabled

Enable RSA

--enable-rsapss

Disabled

Enable RSA-PSS

--enable-dh

Enabled

Enable DH

--enable-anon

Disabled

Enable Anonymous

--enable-asn

Enabled

Enable ASN

--enable-aes

Enabled

Enable AES

--enable-coding

Enabled

Enable Coding base 16/64

--enable-base64encode

Enabled on x86_64

Enable Base64 encoding

--enable-des3

Enabled

Enable DES3

--enable-idea

Disabled

Enable IDEA Cipher

--enable-arc4

Disabled

Enable ARC4

--enable-md5

Enabled

Enable MD5

--enable-sha

Enabled

Enable SHA

--enable-webserver

Disabled

Enable Web Server

--enable-hc128

Disabled

Enable streaming cipher HC-128

--enable-rabbit

Disabled

Enable streaming cipher RABBIT

--enable-fips

Disabled

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

--enable-sha224

Enabled on x86_64

Enable wolfSSL SHA-224 support

--enable-poly1305

Enabled

Enable wolfSSL POLY1305 support

--enable-chacha

Enabled

Enable CHACHA

--enable-hashdrbg

Enabled

Enable Hash DRBG support

--enable-filesystem

Enabled

Enable Filesystem support

--enable-inline

Enabled

Enable inline functions

--enable-ocsp

Disabled

Enable Online Certificate Status Protocol (OCSP)

--enable-ocspstapling

Disabled

Enable OCSP Stapling

--enable-ocspstapling2

Disabled

Enable OCSP Stapling version 2

--enable-crl

Disabled

Enable CRL

--enable-crl-monitor

Disabled

Enable CRL Monitor

--enable-sni

Disabled

Enable Server Name Indication (SNI)

--enable-maxfragment

Disabled

Enable Maximum Fragment Length

--enable-alpn

Disabled

Enable Application Layer Protocol Negotiation (ALPN)

--enable-truncatedhmac

Disabled

Enable Truncated Keyed-hash MAC (HMAC)

--enable-renegotiation-indication

Disabled

Enable Renegotiation Indication

--enable-secure-renegotiation

Disabled

Enable Secure Renegotiation

--enable-supportedcurves

Disabled

Enable Supported Elliptic Curves

--enable-session-ticket

Disabled

Enable Session Ticket

--enable-extended-master

Enabled

Enable Extended Master Secret

--enable-tlsx

Disabled

Enable all TLS extensions

--enable-pkcs7

Disabled

Enable PKCS#7 support

--enable-pkcs11

Disabled

Enable PKCS#11 access

--enable-scep

Disabled

Enable wolfSCEP (Simple Certificate Enrollment Protocol)

--enable-srp

Disabled

Enable Secure Remote Password

--enable-smallstack

Disabled

Enable Small Stack Usage

--enable-valgrind

Disabled

Enable valgrind for unit tests

--enable-testcert

Disabled

Enable Test Cert

--enable-iopool

Disabled

Enable I/O Pool example

--enable-certservice

Disabled

Enable certificate service (Windows Servers)

--enable-jni

Disabled

Enable wolfSSL JNI

--enable-lighty

Disabled

Enable lighttpd/lighty

--enable-stunnel

Disabled

Enable stunnel

--enable-md4

Disabled

Enable MD4

--enable-pwdbased

Disabled

Enable PWDBASED

--enable-scrypt

Disabled

Enable SCRYPT

--enable-cryptonly

Disabled

Enable wolfCrypt Only build

--enable-fastmath

Enabled on x86_64

Enable fast math ops

--enable-fasthugemath

Disabled

Enable fast math + huge code

--enable-examples

Enabled

Enable examples

--enable-crypttests

Enabled

Enable Crypt Bench/Test

--enable-fast-rsa

Disabled

Enable RSA using Intel IPP

--enable-staticmemory

Disabled

Enable static memory use

--enable-mcapi

Disabled

Enable Microchip API

--enable-asynccrypt

Disabled

Enable Asynchronous Crypto

--enable-sessionexport

Disabled

Enable export and import of sessions

--enable-aeskeywrap

Disabled

Enable AES key wrap support

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

yes

Enable up to # make jobs

yes: enable one more than CPU count

--enable-shared[=PKGS]

Disabled

Building shared wolfSSL libraries [default = no]

--enable-static[=PKGS]

Disabled

Building static wolfSSL libraries [default=no]

--with-ntru=PATH

Disabled

Path to NTRU install (default /usr/)

--with-libz=PATH

Disabled

Optionally include libz for compression

--with-cavium=PATH

Disabled

Path to cavium/software directory.

--with-user-crypto=PATH

Disabled

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

--enable-rsavfy

Disabled

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

--enable-rsapub

Disabled

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

--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-tlsv12

Enabled

Enable TLS 1.2 support

--enable-tls13

Disabled

Enable TLS 1.3 support

--enable-all

Disabled

Enables all wolfSSL features, excluding SSL v3

--enable-xts

Disabled

Enables AES-XTS mode

--enable-asio

Disabled

Enables ASIO

--enable-afalg

Disabled

Enables use of Linux module AF_ALG for hardware accleration.

Additional Xilinx use with =xilinx, =xilinx-rsa, =xilinx-aes, =xilinx-sha3

--enable-devcrypto

Disabled

Enables use of Linux /dev/crypto for hardware acceleration

--enable-mcast

Disabled

Enable wolfSSL DTLS multicast support

--enable-pkcs12

Enabled

Enable PKCS12 code

--enable-fallback-scsv

Disabled

Enables Signaling Cipher Suite Value(SCSV)

--enable-psk-one-id

Disabled

Enables support for single PSK ID with TLS 1.3

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.

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:

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

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.

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