CyaSSL Manual

Chapter 2: Building CyaSSL



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


This chapter explains how to build CyaSSL on Unix and Windows, and provides guidance for building CyaSSL in a non-standard environment.  You can find a getting started guide in Chapter 3.


CyaSSL 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 CyaSSL Source Code



The most recent version of CyaSSL can be downloaded from the yaSSL website as a ZIP file from the Download page.


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 CyaSSL 2.0.0rc3, the directory structure of CyaSSL has changed as well as the standard install location.  These changes were made to make it easier for open source projects to integrate CyaSSL.  For more information on header and structure changes, please see sections 9.1 and 9.3.



2.2 Building on *nix



When building CyaSSL on Linux, *BSD, OS X, Solaris, or other *nix like systems, use the autconf system. To build CyaSSL you only need to run two commands:


./configure

make


To install CyaSSL run:


make install


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


sudo make install


To test the build, run the testsuite program from the root CyaSSL source directory.


./testsuite/testsuite


Or by using autoconf:


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 CyaSSL library and not the additional items (examples, testsuite, benchmark app, etc.), you can run the following from the CyaSSL root directory:


make src/libcyassl.la



2.3 Building on Windows



VS 2005 / VS 2008:  Solutions are included for Visual Studio 2005/2008 in the root directory of the install.


To test each build, choose “Build All” from the Visual Studio menu and then run the testsuite program.


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



2.4 Building in a non-standard environment



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


  1. 1.Place all of the .c files from src/ and ctaocrypt/src/ into the same directory.


  1. 2.Copy the cyassl/ include directory into the same directory as above.  This directory contains all .h files for CyaSSL and CTaoCrypt.


  1. 3.Even though all of the CyaSSL headers are now in the /cyassl sub-directory under the source directory, some build systems will still want to explicitly know where the header files are so you may need to specify that.


  1. 4.CyaSSL defaults to a little endian system unless the configure process detects big endian.  Since you aren't using the configure process, you'll need to define BIG_ENDIAN_ORDER if you are using a big endian system.


  1. 5.CyaSSL 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. 6.Try to build the library, and let us know if you run into any problems. If you need help, contact us at info@yassl.com.


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


  3. NO_CYASSL_SERVER likewise removes calls specific to the server side.


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


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


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


  11. NO_ERROR_STRINGS disables error strings. Error strings are located in src/internal.c for CyaSSL or ctaocrypt/src/asn.c for CTaoCrypt.


  13. NO_HMAC removes HMAC from the build.


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


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


  19. NO_PWDBASED disables password-based key derivation functions such as PBKDF1, PDKDF2, and PBKDF from PCKS#12.


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


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


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


  27. NO_TLS turns off TLS which isn't recommended.


  29. SMALL_SESSION_CACHE can be defined to limit the size of the SSL session cache used by CyaSSL.  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. CYASSL_CERT_GEN turns on CyaSSL’s certificate generation functionality.  See chapter 7 for more information.


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


  5. CYASSL_KEY_GEN turns on CyaSSL’s RSA key generation functionality.  See chapter 7 for more information.


  7. CYASSL_RIPEMD enables RIPEMD-160 support.


  9. CYASSL_SHA512 enables SHA-512 support.


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


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


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


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


2.4.3 Customizing or Porting CyaSSL


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


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


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


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


  9. 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 “ctaocrypt/src/random.c”).


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


  13. NO_WRITEV disables simulation of writev() semantics.


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


  17. 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 “cyassl_int.c”.


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


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.


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


2.4.5 Increasing Performance


  1. CYASSL_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 CyaSSL build sources.


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


2.4.6 Stack or Chip Specific Defines


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


  1. CYASSL_GAME_BUILD can be defined when building CyaSSL for a game console.


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


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


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


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


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


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


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



2.5 Build Options (./configure Options)



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


By default, CyaSSL 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 -> CyaSSL Manual

Home

Download

License

Blog

Community

Contact

About

Products

Docs

Support Forums

Previous Chapter

Download CyaSSL Manual (PDF)

Table of Contents


2.5.1 Build Option Notes


Debug - enabling debug support allows easier debugging by compiling with debug information and defining the constant DEBUG_CYASSL which outputs messages to stderr. To turn debug on at runtime, call CyaSSL_Debugging_ON(). To turn debug logging off at runtime, call CyaSSL_Debugging_OFF().


Small - enabling the small build option will create the smallest possible CyaSSL library. This will also remove features that may be desired like TLS, HMAC, SHA-256, error strings, or others. Only use this if the default build is too big and you don't mind losing features.  A full list of features which are disabled are TLS, HMAC, AES, 3DES, SHA-256, Error Strings, HC-128, RABBIT, PSK, DSA, and DH.


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 multi threaded and only one thread at a time will be accessing the library.


DTLS - enabling DTLS support allows users of the library to also run DTLS in addition to TLS and SSL. DTLS support is still experimental so please send us any comments, questions, or suggestions.


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 CyaSSL OpenSSL compatibility layer is under active development, so if there is a function missing that you need, then please contact us and we'll try to help.


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


fastmath - enabling fastmath will speed up public key operations like RSA, DH, and DSA.  This 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. CyaSSL 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 cyassl/ctaocrypt/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 CyaSSL 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 fasthughmath 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 1055 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.


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.


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.


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


certgen - enables support for self-signed x509 v3 certificate generation.


disable shared - disabling the shared library build will exclude a CyaSSL 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 CyaSSL 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 CyaSSL from the libz library. Think twice about including this option and using it by calling CyaSSL_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.


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.


HC-128 - Though we really like the speed of this 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.


NTRU - This turns on the ability for CyaSSL to use NTRU cipher suites. An NTRU license is required to build and use these. Without both the NTRU license and library the build will fail.


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.



2.6 Cross Compiling



Many users on embedded platforms cross compile CyaSSL 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 CyaSSL.


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 CyaSSL 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 CyaSSL, please let us know at info@yassl.com.


Next Chapter

 

Embedded SSL