wolfSSL Manual

Chapter 2: Building wolfSSL



wolfSSL (formerly CyaSSL) 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 [email protected].


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 a 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/yaSSL/download/downloadForm.php


After downloading the ZIP file, unzip the file using the “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. (For example, Unix files use line feeds (LFs) for end-of-line (EOL) and have no end-of-file (EOF) marker; Apple Operating Systems use carriage returns (CRs) for EOLs; and most PC operating systems use CR+LF for EOLs and control-Z for EOF. In addition, IBM mainframes and the Michigan Terminal System use EBCDIC rather than the more common ASCII character set, and NT supports Unicode.)”


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:


./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 source 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 propery 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” click the drop down arrow on the far right and 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 the project then Rebuild the project and 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.


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. 1.The source and header files need to remain in the same directory structure as they are in the wolfSSL download package.


  1. 2.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. 3.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. 4.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. 5.Try to build the library, and let us know if you run into any problems. If you need help, contact us at [email protected].


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


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


  2. NO_WOLFSSL_SERVER likewise removes calls specific to the server side.


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


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


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


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


  7. NO_HMAC removes HMAC from the build.


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


  9. NO_MD5 removes MD5 from the build.


  10. NO_SHA256 removes SHA-256 from the build.


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


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


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


  14. NO_RABBIT and NO_HC128 remove stream cipher extensions from the build.


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


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


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



2.4.2 Enabling Features Disabled by Default


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


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


  3. WOLFSSL_DTLS turns on the use of DTLS, or datagram TLS.  This isn't widely supported or used so it is off by default.


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


  5. WOLFSSL_RIPEMD enables RIPEMD-160 support.


  6. WOLFSSL_SHA384 enables SHA-384 support.


  7. WOLFSSL_SHA512 enables SHA-512 support.


  8. DEBUG_WOLFSSL builds in the ability to debug. For more information regarding debugging wolfSSL, see Chapter 8.  It is off by default.


  9. HAVE_AESCCM enables AES-CCM support.


  10. HAVE_AESGCM enables AES-GCM support.


  11. HAVE_CAMELLIA enables Camellia support.


  12. HAVE_CHACHA enables ChaCha20 support.


  13. HAVE_POLY1305 enables Poly1305 support.


  14. HAVE_CRL enables Certificate Revocation List (CRL) support.


  15. HAVE_ECC enables Elliptical Curve Cryptography (ECC) support.


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


  17. HAVE_OCSP enables Online Certificate Status Protocol (OCSP) support.


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


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



2.4.3 Customizing or Porting wolfSSL


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


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


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


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


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


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


  7. NO_WRITEV disables simulation of writev() semantics.


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


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


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


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


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



2.4.4 Reducing Memory Usage


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


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



2.4.5 Increasing Performance


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


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


  1. IPHONE can be defined if building for use with iOS.


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


  3. MICRIUM can be defined when building for Micrium’s µC/OS (www.micrium.com).


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


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


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


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


  8. WOLFSSL_MICROCHIP_PIC32MZ can be defined for PIC32MZ hardware cryptography engine.


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


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


  11. EBSNET can be defined when using EBSnet products and RTIP.


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


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


  14. WOLFSSL_LSR can be define if building for LSR.


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


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


  17. COMVERGE can be defined if using Comverge settings.


  18. WOLFSSL_QL can be defined if using QL SEP settings.


  19. WOLFSSL_EROAD can be defined building for EROAD.


  20. WOLFSSL_IAR_ARM can be defined if build for IAR EWARM.


  21. WOLFSSL_TIRTOS can be defined when building for TI-RTOS.



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.

Docs -> wolfSSL Manual


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.


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


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


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


noInline - enabling this option disables function inlining in wolfSSL.


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.


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.



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 [email protected].


Questions? +1 (425) 245-8247