CyaSSL User Manual September 11, 2014 Version 3.2.0 Table of Contents Chapter 1: Introduction Chapter 2: Building CyaSSL 2.1 Getting CyaSSL Source Code 2.2 Building on *nix 2.3 Building on Windows 2.4 Building in a Non-Standard Environment 2.5 Build Options (./configure Options) 2.6 Cross Compiling Chapter 3: Getting Started 3.1 General Description 3.2 Testsuite 3.3 Client Example 3.4 Server Example 3.5 EchoServer Example 3.6 EchoClient Example 3.7 Benchmark 3.8 Changing a Client Application to Use CyaSSL 3.9 Changing a Server Application to Use CyaSSL Chapter 4: Features 4.1 Features Overview 4.2 Protocol Support 4.3 Cipher Support 4.4 Hardware Accelerated Crypto 4.5 SSL Inspection 4.6 Compression 4.7 Pre-Shared Keys 4.8 Client Authentication 4.9 Server Name Indication (SNI) 4.10 Handshake Modifications 4.11 Truncated HMAC Chapter 5: Portability 5.1 Abstraction Layers Copyright 2014 wolfSSL Inc. All rights reserved. 1 5.2 Supported Operating Systems 5.3 Supported Chipmakers Chapter 6: Callbacks 6.1 Handshake Callback 6.2 Timeout Callback Chapter 7: Keys and Certificates 7.1 Supported Formats and Sizes 7.2 Certificate Loading 7.3 Certificate Chain Verification 7.4 Domain Name Check for Server Certificates 7.5 No File System and Using Certificates 7.6 Serial Number Retrieval 7.7 RSA Key Generation 7.8 Certificate Generation 7.9 Convert raw ECC key Chapter 8: Debugging 8.1 Debugging and Logging 8.2 Error Codes Chapter 9: Library Design 9.1 Library Headers 9.2 Startup and Exit 9.3 Structure Usage 9.4 Thread Safety 9.5 Input and Output Buffers 9.6 Secure Renegotiation Chapter 10: CTaoCrypt Usage Reference 10.1 Hash Functions 10.2 Keyed Hash Functions 10.3 Block Ciphers 10.4 Stream Ciphers 10.5 Public Key Cryptography Chapter 11: SSL Tutorial Chapter 12: Best Practices for Embedded Devices Chapter 13: OpenSSL Compatibility Chapter 14: Licensing Chapter 15: Support and Consulting Chapter 16: CyaSSL Updates Chapter 17: CyaSSL API Reference Copyright 2014 wolfSSL Inc. All rights reserved. 2 Appendix A: SSL/TLS Overview Appendix B: RFCs, Specifications, and Reference Appendix C: Error Codes Chapter 1: Introduction This manual is written as a technical guide to the CyaSSL embedded SSL library. It will explain how to build and get started with CyaSSL, provide an overview of build options, features, portability enhancements, support, and much more. Why Choose CyaSSL? There are many reasons to choose CyaSSL as your embedded SSL solution. Some of the top reasons include size (typical footprint sizes range from 20-100 kB), support for the newest standards (SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, DTLS 1.0, and DTLS 1.2), current and progressive cipher support (including stream ciphers), multi-platform, royalty free, and an OpenSSL compatibility API to ease porting into existing applications which have previously used the OpenSSL package. For a complete feature list, see Section 4.1. Copyright 2014 wolfSSL Inc. All rights reserved. 3 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.wolfssl.com/forums) or contact us directly at [email protected]. This chapter explains how to build CyaSSL on Unix and Windows, and provides guidance for building CyaSSL 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 CyaSSL, 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 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 CyaSSL 2.0.0rc3, the directory structure of CyaSSL was changed as well as the standard install location. These changes were Copyright 2014 wolfSSL Inc. All rights reserved. 4 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 autoconf system. To build CyaSSL 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 CyaSSL, run: make To install CyaSSL 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 CyaSSL source directory: ./testsuite/testsuite.test Or use autoconf to run the testsuite as well as the standard CyaSSL API and crypto tests: make test Copyright 2014 wolfSSL Inc. All rights reserved. 5 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 command from the CyaSSL root directory: make src/libcyassl.la 2.3 Building on Windows 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. 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 (cyassl, 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 CyaSSL for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build CyaSSL. 2.4 Building in a non-standard environment While not officially supported, we try to help users 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. The source and header files need to remain in the same directory structure as they are in the CyaSSL download package. 2. Some build systems will want to explicitly know where the CyaSSL header files are located, so you may need to specify that. They are located in the <cyassl_root>/cyassl directory. Typically, you can add the <cyassl_root> directory to your include path to resolve header problems. 3. CyaSSL defaults to a little endian system unless the configure process detects Copyright 2014 wolfSSL Inc. All rights reserved. 6 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. 4. 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. 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]. 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 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). 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. NO_CYASSL_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.