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:
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.
- 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 info@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 Removing Features
The following defines can be used to remove features from wolfSSL. This can be helpful if you are trying to reduce the overall library footprint size. In addition to defining a NO_<feature-name> define, you can also remove the respective source file as well from the build (but not the header file).
NO_WOLFSSL_CLIENT removes calls specific to the client and is for a server-only builds. You should only use this if you want to remove a few calls for the sake of size.
NO_WOLFSSL_SERVER likewise removes calls specific to the server side.
NO_DES3 removes the use of DES3 encryptions. DES3 is built-in by default because some older servers still use it and it’s required by SSL 3.0.
NO_DH and NO_AES are the same as the two above, they are widely used.
NO_DSA removes DSA since it’s being phased out of popular use.
NO_ERROR_STRINGS disables error strings. Error strings are located in src/internal.c for wolfSSL or wolfcrypt/src/asn.c for wolfCrypt.
NO_HMAC removes HMAC from the build.
NO_MD4 removes MD4 from the build, MD4 is broken and shouldn’t be used.
NO_MD5 removes MD5 from the build.
NO_SHA256 removes SHA-256 from the build.
NO_PSK turns off the use of the pre-shared key extension. It is built-in by default.
NO_PWDBASED disables password-based key derivation functions such as PBKDF1, PBKDF2, and PBKDF from PKCS #12.
NO_RC4 removes the use of the ARC4 stream cipher from the build. ARC4 is built-in by default because it is still popular and widely used.
NO_RABBIT and NO_HC128 remove stream cipher extensions from the build.
NO_SESSION_CACHE can be defined when a session cache is not needed. This should reduce memory use by nearly 3 kB.
NO_TLS turns off TLS. We don’t recommend turning off TLS.
SMALL_SESSION_CACHE can be defined to limit the size of the SSL session cache used by wolfSSL. This will reduce the default session cache from 33 sessions to 6 sessions and save approximately 2.5 kB.
WC_NO_RSA_OAEP removes code for OAEP padding.
2.4.2 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.
HAVE_CAMELLIA enables Camellia support.
HAVE_CHACHA enables ChaCha20 support.
HAVE_POLY1305 enables Poly1305 support.
HAVE_CRL enables Certificate Revocation List (CRL) support.
HAVE_CRL_IO enables blocking inline HTTP request on the CRL URL. It will load the CRL into the WOLFSSL_CTX and apply it to all WOLFSSL objects created from it.
HAVE_ECC enables Elliptical Curve Cryptography (ECC) support.
HAVE_LIBZ is an extension that can allow for compression of data over the connection. It normally shouldn’t be used, see the note below under configure notes libz.
HAVE_OCSP enables Online Certificate Status Protocol (OCSP) support.
OPENSSL_EXTRA builds even more OpenSSL compatibility into the library, and enables the wolfSSL OpenSSL compatibility layer to ease porting wolfSSL into existing applications which had been designed to work with OpenSSL. It is off by default.
TEST_IPV6 turns on testing of IPv6 in the test applications. wolfSSL proper is IP neutral, but the testing applications use IPv4 by default.
HAVE_CSHARP turns on configuration options needed for C# wrapper.
HAVE_CURVE25519 turns on the use of curve25519 algorithm.
HAVE_ED25519 turns on use of the ed25519 algorithm.
CURVED25519_SMALL defines CURVE25519_SMALL and ED25519_SMALL.
CURVE25519_SMALL use small memory option for curve25519. This uses less memory, but is slower.
ED25519_SMALL use small memory option for ed25519. This uses less memory, but is slower.
WOLFSSL_DH_CONST turns off use of floating point values when performing Diffie Hellman operations and uses tables for XPOW() and XLOG(). Removes dependency on external math library.
WOLFSSL_TRUST_PEER_CERT turns on the use of trusted peer certificates. This allows for loading in a peer certificate to match with a connection rather than using a CA. When turned on if a trusted peer certificate is matched than the peer cert chain is not loaded and the peer is considered verified. Using CAs is preferred.
WOLFSSL_STATIC_MEMORY turns on the use of static memory buffers and functions. This allows for using static memory instead of dynamic.
WOLFSSL_SESSION_EXPORT turns on the use of DTLS session export and import. This allows for serializing and sending/recieving the current state of a DTLS session.
WOLFSSL_ARMASM turns on the use of ARMv8 hardware acceleration.
2.4.3 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);
2.4.4 Reducing Memory Usage
TFM_TIMING_RESISTANT can be defined when using fast math (USE_FAST_MATH) on systems with a small stack size. This will get rid of the large static arrays.
WOLFSSL_SMALL_STACK can be used for devices which have a small stack size. This increases the use of dynamic memory in wolfcrypt/src/integer.c, but can lead to slower performance.
RSA_LOW_MEM when defined CRT is not used which saves on some memory but slows down RSA operations. It is off by default.
2.4.5 Increasing Performance
WOLFSSL_AESNI enables use of AES accelerated operations which are built into some Intel chipsets. When using this define, the aes_asm.c file must be added to the wolfSSL build sources.
USE_FAST_MATH switches the big integer library to a faster one that uses assembly if possible. fastmath will speed up public key operations like RSA, DH, and DSA. The big integer library is generally the most portable and generally easiest to get going with, but the negatives to the normal big integer library are that it is slower and it uses a lot of dynamic memory. Because the stack memory usage can be larger when using fastmath, we recommend defining TFM_TIMING_RESISTANT as well when using this option.
2.4.6 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 for Micrium’s µC/OS (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.
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 |
|
–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-armasm |
Disabled |
Use of ARMv8 hardware acceleration. Sets mcpu or mfpu based on 64vs32 bit system. Does not overwrite mcpu or mfpu setting passed with CPPFLAGS. |
|
–enable-aesni |
Disabled |
Enable wolfSSL Intel AES-NI support |
|
–enable-intelasm |
Disabled |
Enable all Intel ASM speedups |
|
–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-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 |
|
–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-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-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). |
2.5.1 Build Option Notes
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.
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 info@wolfssl.com.