Wolf SSL Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 605 [warning: Documents this large are best viewed by clicking the View PDF Link!]

wolfSSL User Manual

October, 2017

Version 3.12.2

Table of Contents

Chapter 1: Introduction

Chapter 2: Building wolfSSL

2.1 Getting wolfSSL 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

Chapter 4: Features

4.1 Features Overview

4.2 Protocol Support

4.3 Cipher Support

4.4 Hardware Accelerated Crypto

4.5 SSL Inspection (Sniffer)

4.6 Compression

4.7 Pre-Shared Keys

4.8 Client Authentication

4.9 Server Name Indication

4.10 Handshake Modifications

4.11 Truncated HMAC

4.12 User Crypto Module

4.13 Timing-Resistance in wolfSSL

Chapter 5: Portability

5.1 Abstraction Layers

5.2 Supported Operating Systems

5.3 Supported Chipmakers

5.4 C# Wrapper

Chapter 6: Callbacks

6.1 HandShake Callback

6.2 Timeout Callback

6.3 User Atomic Record Layer Processing

6.4 Public Key Callbacks

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

Chapter 10: wolfCrypt (formerly 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

11.1 Introduction

11.2 Quick Summary of SSL/TLS

11.3 Getting the Source Code

11.4 Base Example Modifications

11.5 Building and Installing wolfSSL

11.6 Initial Compilation

11.7 Libraries

11.8 Headers

11.9 Startup/Shutdown

11.10 WOLFSSL Object

11.11 Sending/Receiving Data

11.12 Signal Handling

11.13 Certificates

11.14 Conclusion

Chapter 12: Best Practices for Embedded Devices

12.1 Creating Private Keys

12.2 Digitally Signing and Authenticating with wolfSSL

Chapter 13: OpenSSL Compatibility

13.1 Compatibility with OpenSSL

13.2 Differences Between wolfSSL and OpenSSL

13.3 Supported OpenSSL Structures

13.4 Supported OpenSSL Functions

13.5 x509 Certificates

Chapter 14: Licensing

14.1 Open Source

14.2 Commercial Licensing

14.3 Support Packages

Chapter 15: Support and Consulting

15.1 How to Get Support

15.2 Consulting

Chapter 16: wolfSSL (formerly CyaSSL) Updates

16.1 Product Release Information

Chapter 17: wolfSSL (formerly CyaSSL) API Reference

17.1 Initialization / Shutdown

17.2 Certificates and Keys

17.3 Context and Session Setup

17.4 Callbacks

17.5 Error Handling and Debugging

17.6 OCSP and CRL

17.7 Informational

17.8 Connection, Session, and I/O

17.9 DTLS Specific

17.10 Memory Abstraction Layer

17.11 Certificate Manager

17.12 OpenSSL Compatibility Layer

17.13 TLS Extensions

Appendix A: SSL/TLS Overview

Chapter 1: Introduction

This manual is written as a technical guide to the wolfSSL (formerly CyaSSL)

embedded SSL/TLS library. It will explain how to build and get started with wolfSSL,

provide an overview of build options, features, portability enhancements, support, and

much more.

Why Choose wolfSSL?

There are many reasons to choose wolfSSL 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, TLS 1.3, 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.

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 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” 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 &'(&(!$&' 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 &'(&(!$&' program can be found in

Section 3.2. If you want to build only the wolfSSL library and not the additional items

(examples, testsuite, benchmark app, etc.), you can run the following command from

the wolfSSL root directory:

make src/libwolfssl.la

2.3 Building on Windows

In addition to the instructions below, you can find instructions and tips for building

wolfSSL with Visual Studio here.

VS 2008: Solutions are included for Visual Studio 2008 in the root directory of the

install. For use with Visual Studio 2010 and later, the existing project files should be

able to be converted during the import process.

Note:

If importing to a newer version of VS you will be asked: “Do you want to overwrite the

project and its imported property sheets?” You can avoid the following by selecting

“No”. Otherwise if you select “Yes”, you will see warnings about EDITANDCONTINUE

being ignored due to SAFESEH specification. You will need to right click on the

testsuite, sslSniffer, server, echoserver, echoclient, and client individually and modify

their Properties->Configuration Properties->Linker->Advanced (scroll all the way to the

bottom in Advanced window). Locate “Image Has Safe Exception Handlers” and click

the drop down arrow on the far right. Change this to No (/SAFESEH:NO) for each of the

aforementioned. The other option is to disable EDITANDCONTINUE which, we have

found to be useful for debugging purposes and is therefore not recommended.

VS 2010: You will need to download Service Pack 1 to build wolfSSL solution once it

has been updated. If VS reports a linker error, clean and rebuild the project; the linker

error should be taken care of.

VS 2013 (64 bit solution): You will need to download Service Pack 4 to build wolfSSL

solution once it has been updated. If VS reports a linker error, clean the project then

Rebuild the project and the linker error should be taken care of.

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

testsuite program. To edit build options in the Visual Studio project, select your desired

project (wolfssl, echoclient, echoserver, etc.) and browse to the “Properties” panel.

Note:

After the wolfSSL v3.8.0 release the build preprocessor macros were moved to a

centralized file located at ‘IDE/WIN/user_settings.h’. This file can also be found in the

project. To add features such as ECC or ChaCha20/Poly1305 add #defines here such

as HAVE_ECC or HAVE_CHACHA / HAVE_POLY1305.

Cygwin: If using Cygwin, or other toolsets for Windows that provides *nix-like

commands and functionality, please follow the instructions in section 2.2, above, for

“Building on *nix”. If building wolfSSL for Windows on a Windows development

machine, we recommend using the included Visual Studio project files to build wolfSSL.

2.4 Building in a non-standard environment

While not officially supported, we try to help users wishing to build wolfSSL in a non-

standard environment, particularly with embedded and cross-compilation systems.

Below are some notes on getting started with this.

1. The source and header files need to remain in the same directory structure as

they are in the wolfSSL download package.

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.

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.

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.

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

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

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"

/* 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

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

x86_64

Enable ECC Shamir

--enable-ecc

Enabled

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

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

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

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.

Chapter 3 : Getting Started

3.1 General Description

wolfSSL, formerly CyaSSL, is about 10 times smaller than yaSSL and up to 20 times

smaller than OpenSSL when using the compile options described in Chapter 2. User

benchmarking and feedback also reports dramatically better performance from wolfSSL

vs. OpenSSL in the vast majority of standard SSL operations.

For instructions on the build process please see Chapter 2.

3.2 Testsuite

The testsuite program is designed to test the ability of wolfSSL and its cryptography

library, wolfCrypt, to run on the system.

wolfSSL needs all examples and tests to be run from the wolfSSL home directory. This

is because it finds certs and keys from ./certs. To run testsuite, execute:

./testsuite/testsuite.test

make test (when using autoconf)

On *nix or Windows the examples and testsuite will check to see if the current directory

is the source directory and if so, attempt to change to the wolfSSL home directory. This

should work in most setup cases, if not, just use the first method above and specify the

full path.

On a successful run you should see output like this, with additional output for unit tests

and cipher suite tests:

MD5 test passed!

SHA test passed!

SHA-224 test passed!

SHA-256 test passed!

SHA-384 test passed!

SHA-512 test passed!

HMAC-MD5 test passed!

HMAC-SHA test passed!

HMAC-SHA224 test passed!

HMAC-SHA256 test passed!

HMAC-SHA384 test passed!

HMAC-SHA512 test passed!

GMAC test passed!

Chacha test passed!

POLY1305 test passed!

ChaCha20-Poly1305 AEAD test passed!

AES test passed!

AES-GCM test passed!

RANDOM test passed!

RSA test passed!

DH test passed!

ECC test passed!

SSL version is TLSv1.2

SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

SSL version is TLSv1.2

SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Client message: hello wolfssl!

Server response: I hear you fa shizzle!

sending server shutdown command: quit!

client sent quit command: shutting down!

ciphers = DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:ECDHE-

RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-

SHA256:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-

SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-

AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-

SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-

SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-CHACHA20-POLY1305:DHE-RSA-

CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305-OLD:ECDHE-ECDSA-CHACHA20-

POLY1305-OLD:DHE-RSA-CHACHA20-POLY1305-OLD

33bc1a4570f4f1abccd5c48aace529b01a42ab51293954a297796e90d20970f0 input

33bc1a4570f4f1abccd5c48aace529b01a42ab51293954a297796e90d20970f0

/tmp/output-7Iyhbo

All tests passed!

This indicates that everything is configured and built correctly. If any of the tests fail,

make sure the build system was set up correctly. Likely culprits include having the

wrong endianness or not properly setting the 64-bit type. If you've set anything to the

non-default settings try removing those, rebuilding wolfSSL, and then re-testing.

3.3 Client Example

You can use the client example found in examples/client to test wolfSSL against any

SSL server. To see a list of available command line runtime options, run the client with

the --help argument:

./examples/client/client --help

client 3.9.10 NOTE: All files relative to wolfSSL home dir

-? Help, print this usage

-h <host> Host to connect to, default 127.0.0.1

-p <num> Port to connect on, not 0, default 11111

-v <num> SSL version [0-3], SSLv3(0) - TLS1.2(3)), default 3

-V Prints valid ssl version numbers, SSLv3(0) - TLS1.2(3)

-l <str> Cipher suite list (: delimited)

-c <file> Certificate file, default ./certs/client-cert.pem

-k <file> Key file, default ./certs/client-key.pem

-A <file> Certificate Authority file, default ./certs/ca-cert.pem

-Z <num> Minimum DH key bits, default 1024

-b <num> Benchmark <num> connections and print stats

-B <num> Benchmark throughput using <num> bytes and print stats

-s Use pre Shared keys

-t Track wolfSSL memory use

-d Disable peer checks

-D Override Date Errors example

-e List Every cipher suite available,

-g Send server HTTP GET

-u Use UDP DTLS, add -v 2 for DTLSv1, -v 3 for DTLSv1.2 (default)

-m Match domain name in cert

-N Use Non-blocking sockets

-r Resume session

-w Wait for bidirectional shutdown

-M <prot> Use STARTTLS, using <prot> protocol (smtp)

-f Fewer packets/group messages

-x Disable client cert/key loading

-X Driven by eXternal test case

-n Disable Extended Master Secret

To test against example.com:443 try the following. This is using wolfSSL compiled with

the --enable-opensslextra --enable-supportedcurves build options:

./examples/client/client -h example.com -p 443 -d -g

peer's cert info:

issuer : /C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert SHA2 High

Assurance Server CA

subject: /C=US/ST=California/L=Los Angeles/O=Internet Corporation for

Assigned Names and Numbers/OU=Technology/CN=www.example.org

altname = www.example.net

altname = www.example.edu

altname = www.example.com

altname = example.org

altname = example.net

altname = example.edu

altname = example.com

altname = www.example.org

serial number:0e:64:c5:fb:c2:36:ad:e1:4b:17:2a:eb:41:c7:8c:b0

SSL version is TLSv1.2

SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Client Random :

83083A1D84404E66C86D7560A2C6ACEEEB0C35F94FDD5E07BC7507CD4E273B19

SSL connect ok, sending GET...

Server response: HTTP/1.0 200 OK

Accept-Ranges: bytes

Content-Type: text/html

Date: Tue, 20 D

ec 2016 22:52:00 GMT

Last-Modified: Tue, 20 Dec 2016 22:33:12 GMT

Server: ECS

(pae/378A)

Content-Length: 94

Connection: close

<html><head><title>edgecastcdn.net</title></head>

<body><h1>edgecastcdn.net</h1></body></html>

This tells the client to connect to (-h) example.com on the HTTPS port (-p) of 443 and

sends a generic (-g) GET request. The (-d) option tells the client not to verify the server.

The rest is the initial output from the server that fits into the read buffer.

If no command line arguments are given, then the client attempts to connect to the

localhost on the wolfSSL default port of 11111. It also loads the client certificate in case

the server wants to perform client authentication.

The client is able to benchmark a connection when using the “-b <num>” argument.

When used, the client attempts to connect to the specified server/port the argument

number of times and gives the average time in milliseconds that it took to perform

SSL_connect(). For example,

./examples/client/client -b 100

SSL_connect avg took: 0.653 milliseconds

If you'd like to change the default host from localhost, or the default port from 11111,

you can change these settings in /wolfssl/test.h. The variables wolfSSLIP and

wolfSSLPort control these settings. Re-build all of the examples including testsuite

when changing these settings otherwise the test programs won't be able to connect to

each other.

By default, the wolfSSL example client tries to connect to the specified server using TLS

1.2. The user is able to change the SSL/TLS version which the client uses by using the

“-v” command line option. The following values are available for this option:

-v 0 = SSL 3.0 (disabled by default)

-v 1 = TLS 1.0

-v 2 = TLS 1.1

-v 3 = TLS 1.2

A common error users see when using the example client is -155:

err = -155, ASN sig error, confirm failure

This is typically caused by the wolfSSL client not being able to verify the certificate of

the server it is connecting to. By default, the wolfSSL client loads the yaSSL test CA

certificate as a trusted root certificate. This test CA certificate will not be able to verify

an external server certificate which was signed by a different CA. As such, to solve this

problem, users either need to turn off verification of the peer (server), using the “-d”

option:

./examples/client/client -h myhost.com -p 443 -d

Or load the correct CA certificate into the wolfSSL client using the “-A” command line

option:

./examples/client/client -h myhost.com -p 443 -A serverCA.pem

3.4 Server Example

The server example demonstrates a simple SSL server that optionally performs client

authentication. Only one client connection is accepted and then the server quits. The

client example in normal mode (no command line arguments) will work just fine against

the example server, but if you specify command line arguments for the client example,

then a client certificate isn't loaded and the wolfSSL_connect() will fail (unless client cert

check is disabled using the “-d” option). The server will report an error "-245, peer

didn't send cert". Like the example client, the server can be used with several

command line arguments as well:

./examples/server/server --help

server 3.9.10 NOTE: All files relative to wolfSSL home dir

-? Help, print this usage

-p <num> Port to listen on, not 0, default 11111

-v <num> SSL version [0-3], SSLv3(0) - TLS1.2(3)), default 3

-l <str> Cipher suite list (: delimited)

-c <file> Certificate file, default ./certs/server-cert.pem

-k <file> Key file, default ./certs/server-key.pem

-A <file> Certificate Authority file, default ./certs/client-cert.pem

-R <file> Create Ready file for external monitor default none

-D <file> Diffie-Hellman Params file, default ./certs/dh2048.pem

-Z <num> Minimum DH key bits, default 1024

-d Disable client cert check

-b Bind to any interface instead of localhost only

-s Use pre Shared keys

-t Track wolfSSL memory use

-u Use UDP DTLS, add -v 2 for DTLSv1, -v 3 for DTLSv1.2 (default)

-f Fewer packets/group messages

-r Allow one client Resumption

-N Use Non-blocking sockets

-S <str> Use Host Name Indication

-w Wait for bidirectional shutdown

-i Loop indefinitely (allow repeated connections)

-e Echo data mode (return raw bytes received)

-B <num> Benchmark throughput using <num> bytes and print stats

3.5 EchoServer Example

The echoserver example sits in an endless loop waiting for an unlimited number of

client connections. Whatever the client sends the echoserver echoes back. Client

authentication isn't performed so the example client can be used against the echoserver

in all 3 modes. Four special commands aren't echoed back and instruct the echoserver

to take a different action.

1. "quit" If the echoserver receives the string "quit" it will shutdown.

2. "break" If the echoserver receives the string "break" it will stop the current

session but continue handling requests. This is particularly useful for DTLS

testing.

3. "printstats" If the echoserver receives the string "printstats" it will print out

statistics for the session cache.

4. "GET" If the echoserver receives the string "GET" it will handle it as an http get

and send back a simple page with the message "greeting from wolfSSL". This

allows testing of various TLS/SSL clients like Safari, IE, Firefox, gnutls, and the

like against the echoserver example.

The output of the echoserver is echoed to stdout unless NO_MAIN_DRIVER is

defined. You can redirect output through the shell or through the first command line

argument. To create a file named output.txt with the output from the echoserver run:

./examples/echoserver/echoserver output.txt

3.6 EchoClient Example

The echoclient example can be run in interactive mode or batch mode with files. To run

in interactive mode and write 3 strings "hello", "wolfssl", and "quit" results in:

./examples/echoclient/echoclient

hello

wolfssl

quit

sending server shutdown command: quit!

To use an input file, specify the filename on the command line as the first argument. To

echo the contents of the file input.txt issue:

./examples/echoclient/echoclient input.txt

If you want the result to be written out to a file, you can specify the output file name as

an additional command line argument. The following command will echo the contents of

file input.txt and write the result from the server to output.txt:

./examples/echoclient/echoclient input.txt output.txt

The testsuite program does just that, but hashes the input and output files to make sure

that the client and server were getting/sending the correct and expected results.

3.7 Benchmark

Many users are curious about how the wolfSSL embedded SSL library will perform on a

specific hardware device or in a specific environment. Because of the wide variety of

different platforms and compilers used today in embedded, enterprise, and cloud-based

environments, it is hard to give generic performance calculations across the board.

To help wolfSSL users and customers in determining SSL performance for wolfSSL /

wolfCrypt, a benchmark application is provided which is bundled with wolfSSL. wolfSSL

uses the wolfCrypt cryptography library for all crypto operations by default. Because the

underlying crypto is a very performance-critical aspect of SSL/TLS, our benchmark

application runs performance tests on wolfCrypt’s algorithms.

The benchmark utility located in wolfcrypt/benchmark

(./wolfcrypt/benchmark/benchmark) may be used to benchmark the cryptographic

functionality of wolfCrypt. Typical output may look like the following (in this output,

several optional algorithms/ciphers were enabled including HC-128, RABBIT, ECC,

SHA-256, SHA-512, AES-GCM, AES-CCM, and Camellia):

./wolfcrypt/benchmark/benchmark

RNG 50 megs took 0.516 seconds, 96.975 MB/s Cycles per byte = 22.57

AES enc 50 megs took 0.278 seconds, 179.737 MB/s Cycles per byte = 12.18

AES dec 50 megs took 0.260 seconds, 192.029 MB/s Cycles per byte = 11.40

AES-GCM 50 megs took 0.840 seconds, 59.552 MB/s Cycles per byte = 36.75

AES-CCM 50 megs took 0.534 seconds, 93.548 MB/s Cycles per byte = 23.39

Camellia 50 megs took 0.376 seconds, 132.928 MB/s Cycles per byte = 16.46

HC128 50 megs took 0.032 seconds, 1550.586 MB/s Cycles per byte = 1.41

RABBIT 50 megs took 0.109 seconds, 459.559 MB/s Cycles per byte = 4.76

CHACHA 50 megs took 0.144 seconds, 347.427 MB/s Cycles per byte = 6.30

CHA-POLY 50 megs took 0.190 seconds, 262.978 MB/s Cycles per byte = 8.32

IDEA 50 megs took 0.807 seconds, 61.982 MB/s Cycles per byte = 35.31

MD5 50 megs took 0.111 seconds, 452.121 MB/s Cycles per byte = 4.84

POLY1305 50 megs took 0.039 seconds, 1281.392 MB/s Cycles per byte = 1.71

SHA 50 megs took 0.118 seconds, 424.747 MB/s Cycles per byte = 5.15

SHA-224 50 megs took 0.242 seconds, 206.789 MB/s Cycles per byte = 10.58

SHA-256 50 megs took 0.243 seconds, 206.022 MB/s Cycles per byte = 10.62

SHA-384 50 megs took 0.172 seconds, 290.787 MB/s Cycles per byte = 7.53

SHA-512 50 megs took 0.175 seconds, 286.117 MB/s Cycles per byte = 7.65

scrypt 39.698 milliseconds, avg over 10 iterations

RSA 2048 public 0.358 milliseconds, avg over 100 iterations

RSA 2048 private 4.537 milliseconds, avg over 100 iterations

DH 2048 key generation 1.391 milliseconds, avg over 100 iterations

DH 2048 key agreement 1.422 milliseconds, avg over 100 iterations

ECC 256 key generation 0.885 milliseconds, avg over 100 iterations

EC-DHE key agreement 0.874 milliseconds, avg over 100 iterations

EC-DSA sign time 0.929 milliseconds, avg over 100 iterations

EC-DSA verify time 0.602 milliseconds, avg over 100 iterations

This is especially useful for comparing the public key speed before and after changing

the math library. You can test the results using the normal math library (./configure),

the fastmath library (./configure --enable-fastmath), and the fasthugemath library

(./configure --enable-fasthugemath).

For more details and benchmark results, please refer to the wolfSSL Benchmarks page:

https://wolfssl.com/wolfSSL/benchmarks-wolfssl.html

3.7.1 Relative Performance

Although the performance of individual ciphers and algorithms will depend on the host

platform, the following graph shows relative performance between wolfCrypt’s ciphers.

These tests were conducted on a Macbook Pro (OS X 10.6.8) running a 2.2 GHz Intel

Core i7.

If you want to use only a subset of ciphers, you can customize which specific cipher

suites and/or ciphers wolfSSL uses when making an SSL/TLS connection. For

example, to force 128-bit AES, add the following line after the call to wolfSSL_CTX_new

(SSL_CTX_new):

wolfSSL_CTX_set_cipher_list(ctx, “AES128-SHA”);

3.7.2 Benchmarking Notes

1. The processors native register size (32 vs 64-bit) can make a big difference

when doing 1000+ bit public key operations.

2. keygen (--enable-keygen) will allow you to also benchmark key generation

speeds when running the benchmark utility.

3. fastmath (--enable-fastmath) reduces dynamic memory usage and speeds up

public key operations. If you are having trouble building on 32-bit platform with

fastmath, disable shared libraries so that PIC isn’t hogging a register (also see

notes in the README)

./configure --enable-fastmath --disable-shared

make clean

make

*Note: doing a “make clean” is good practice with wolfSSL when switching

configure options.

4. By default, fastmath tries to use assembly optimizations if possible. If assembly

optimizations don’t work, you can still use fastmath without them by adding

TFM_NO_ASM to CFLAGS when building wolfSSL:

./configure --enable-fastmath C_EXTRA_FLAGS=”-DTFM_NO_ASM”

5. Using fasthugemath can try to push fastmath even more for users who are not

running on embedded platforms:

./configure --enable-fasthugemath

6. With the default wolfSSL build, we have tried to find a good balance between

memory usage and performance. If you are more concerned about one of the

two, please refer back to Chapter 2 for additional wolfSSL configuration options.

7. Bulk Transfers: wolfSSL by default uses 128 byte I/O buffers since about 80%

of SSL traffic falls within this size and to limit dynamic memory use. It can be

configured to use 16K buffers (the maximum SSL size) if bulk transfers are

required.

3.7.3 Benchmarking on Embedded Systems

There are several build options available to make building the benchmark application on

an embedded system easier. These include:

BENCH_EMBEDDED - enabling this define will switch the benchmark application from

using Megabytes to using Kilobytes, therefore reducing the memory usage. By default,

when using this define, ciphers and algorithms will be benchmarked with 25kB. Public

key algorithms will only be benchmarked over 1 iteration (as public key operations on

some embedded processors can be fairly slow). These can be adjusted in

benchmark.c by altering the variables “numBlocks” and “times” located inside the

BENCH_EMBEDDED define.

USE_CERT_BUFFERS_1024 - enabling this define will switch the benchmark

application from loading test keys and certificates from the file system and instead use

1024-bit key and certificate buffers located in <wolfssl_root>/wolfssl/certs_test.h. It is

useful to use this define when an embedded platform has no filesystem (used with

NO_FILESYSTEM) and a slow processor where 2048-bit public key operations may not

be reasonable.

USE_CERT_BUFFERS_2048 - enabling this define is similar to

USE_CERT_BUFFERS_1024 accept that 2048-bit key and certificate buffers are used

instead of 1024-bit ones. This define is useful when the processor is fast enough to do

2048-bit public key operations but when there is no filesystem available to load keys

and certificates from files.

3.8 Changing a Client Application to Use wolfSSL

This section will explain the basic steps needed to add wolfSSL to a client application,

using the wolfSSL native API. For a server explanation, please see Section 3.9. A

more complete walk-through with example code is located in the SSL Tutorial in

Chapter 11. If you want more information about the OpenSSL compatibility layer,

please see Chapter 13.

1. Include the wolfSSL header

#include <wolfssl/ssl.h>

2. Change all calls from read() (or recv()) to wolfSSL_read() so

result = read(fd, buffer, bytes);

becomes

result = wolfSSL_read(ssl, buffer, bytes);

3. Change all calls from write (or send) to wolfSSL_write() so

result = write(fd, buffer, bytes);

becomes

result = wolfSSL_write(ssl, buffer, bytes);

4. You can manually call wolfSSL_connect() but that's not even necessary; the first

call to wolfSSL_read() or wolfSSL_write() will initiate the wolfSSL_connect() if it

hasn't taken place yet.

5. Initialize wolfSSL and the WOLFSSL_CTX. You can use one WOLFSSL_CTX no

matter how many WOLFSSL objects you end up creating. Basically you'll just

need to load CA certificates to verify the server you are connecting to. Basic

initialization looks like:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

if ( (ctx = wolfSSL_CTX_new(wolfTLSv1_client_method())) == NULL)

{

fprintf(stderr, "wolfSSL_CTX_new error.\n");

exit(EXIT_FAILURE);

}

if (wolfSSL_CTX_load_verify_locations(ctx,"./ca-cert.pem",0) !=

SSL_SUCCESS) {

fprintf(stderr, "Error loading ./ca-cert.pem,"

" please check the file.\n");

exit(EXIT_FAILURE);

}

6. Create the WOLFSSL object after each TCP connect and associate the file

descriptor with the session:

/*after connecting to socket fd*/

WOLFSSL* ssl;

if ( (ssl = wolfSSL_new(ctx)) == NULL) {

fprintf(stderr, "wolfSSL_new error.\n");

exit(EXIT_FAILURE);

}

wolfSSL_set_fd(ssl, fd);

7. Error checking. Each wolfSSL_read() and wolfSSL_write() call will return the

number of bytes written upon success, 0 upon connection closure, and -1 for an

error, just like read() and write(). In the event of an error you can use two calls to

get more information about the error:

char errorString[80];

int err = wolfSSL_get_error(ssl, 0);

wolfSSL_ERR_error_string(err, errorString);

If you are using non-blocking sockets, you can test for errno

EAGAIN/EWOULDBLOCK or more correctly you can test the specific error code

returned by wolfSSL_get_error() for SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE.

8. Cleanup. After each WOLFSSL object is done being used you can free it up by

calling:

wolfSSL_free(ssl);

When you are completely done using SSL/TLS altogether you can free the

WOLFSSL_CTX object by calling:

wolfSSL_CTX_free(ctx);

wolfSSL_Cleanup();

For an example of a client application using wolfSSL, see the client example located in

the <wolfssl_root>/examples/client.c file.

3.9 Changing a Server Application to Use wolfSSL

This section will explain the basic steps needed to add wolfSSL to a server application

using the wolfSSL native API. For a client explanation, please see section 3.8. A more

complete walk-through, with example code, is located in the SSL Tutorial in Chapter 11.

1. Follow the instructions above for a client, except change the client method call in

step 5 to a server one, so

wolfSSL_CTX_new(wolfTLSv1ls_client_method())

becomes

wolfSSL_CTX_new(wolfTLSv1_server_method())

or even

wolfSSL_CTX_new(wolfSSLv23_server_method())

To allow SSLv3 and TLSv1+ clients to connect to the server.

2. Add the server's certificate and key file to the initialization in step 5 above:

if (wolfSSL_CTX_use_certificate_file(ctx,"./server-cert.pem",

SSL_FILETYPE_PEM) != SSL_SUCCESS) {

fprintf(stderr, "Error loading ./server-cert.pem,"

" please check the file.\n");

exit(EXIT_FAILURE);

}

if (wolfSSL_CTX_use_PrivateKey_file(ctx,"./server-key.pem",

SSL_FILETYPE_PEM) != SSL_SUCCESS) {

fprintf(stderr, "Error loading ./server-key.pem,"

" please check the file.\n");

exit(EXIT_FAILURE);

}

It is possible to load certificates and keys from buffers as well if there is no filesystem

available. In this case, see the wolfSSL_CTX_use_certificate_buffer() and

wolfSSL_CTX_use_PrivateKey_buffer() API documentation, linked here, for more

information.

For an example of a server application using wolfSSL, see the server example located

in the <wolfssl_root>/examples/server.c file.

Chapter 4: Features

wolfSSL (formerly CyaSSL) supports the C programming language as a primary

interface, but also supports several other host languages, including Java, PHP, Perl,

and Python (through a SWIG interface). If you have interest in hosting wolfSSL in

another programming language that is not currently supported, please contact us.

This chapter covers some of the features of wolfSSL in more depth, including Stream

Ciphers, AES-NI, IPv6 support, SSL Inspection (Sniffer) support, and more.

4.1 Features Overview

For an overview of wolfSSL features, please reference the wolfSSL product webpage:

https://wolfssl.com/wolfSSL/Products-wolfssl.html

4.2 Protocol Support

wolfSSL supports SSL 3.0, TLS (1.0, 1.1, 1.2, 1.3 (client side)), and DTLS (1.0 and

1.2). You can easily select a protocol to use by using one of the following functions (as

shown for either the client or server). wolfSSL does not support SSL 2.0, as it has been

insecure for several years. The client and server functions below change slightly when

using the OpenSSL compatibility layer. For the OpenSSL-compatible functions, please

see Chapter 13.

4.2.1 Server Functions

wolfDTLSv1_server_method(void); /*DTLS 1.0*/

wolfDTLSv1_2_server_method(void); /*DTLS 1.2*/

wolfSSLv3_server_method(void); /*SSL 3.0*/

wolfTLSv1_server_method(void); /*TLS 1.0*/

wolfTLSv1_1_server_method(void); /*TLS 1.1*/

wolfTLSv1_2_server_method(void); /*TLS 1.2*/

wolfSSLv23_server_method(void); /*Use highest possible version

from SSLv3 - TLS 1.2*/

wolfSSL supports robust server downgrade with the wolfSSLv23_server_method()

function. See section 4.2.3 for a details.

4.2.2 Client Functions

wolfDTLSv1_client_method(void); /* DTLS 1.0*/

wolfDTLSv1_2_client_method(void); /* DTLS 1.2*/

wolfSSLv3_client_method(void); /* SSL 3.0*/

wolfTLSv1_client_method(void); /* TLS 1.0*/

wolfTLSv1_1_client_method(void); /* TLS 1.1*/

wolfTLSv1_2_client_method(void); /* TLS 1.2*/

wolfSSLv23_client_method(void); /* Use highest possible version

from SSLv3 - TLS 1.2*/

wolfSSL supports robust client downgrade with the wolfSSLv23_client_method()

function. See section 4.2.3 for a details.

For details on how to use these functions, please see Chapter 3, “Getting Started.” For

a comparison between SSL 3.0, TLS 1.0, 1.1, 1.2, and DTLS, please see Appendix A.

4.2.3 Robust Client and Server Downgrade

Both wolfSSL clients and servers have robust version downgrade capability. If a

specific protocol version method is used on either side, then only that version will be

negotiated or an error will be returned. For example, a client that uses TLS 1.0 and

tries to connect to an SSL 3.0 only server, the connection will fail, likewise connecting to

a TLS 1.1 will fail as well.

To resolve this issue, a client that uses the wolfSSLv23_client_method() function will

use the highest protocol version supported by the server and downgrade to TLS 1.0 if

needed. In this case, the client will be able to connect to a server running TLS 1.0 - TLS

1.2. The only versions it can't connect to is SSL 2.0 which has been insecure for years,

and SSL 3.0 which has been disabled by default.

Similarly, a server using the wolfSSLv23_server_method() function can handle clients

supporting protocol versions from TLS 1.0 - TLS 1.2. A wolfSSL server can't accept a

connection from SSLv2 because no security is provided.

4.2.4 IPv6 Support

If you are an adopter of IPv6 and want to use an embedded SSL implementation then

you may have been wondering if wolfSSL supports IPv6. The answer is yes, we do

support wolfSSL running on top of IPv6.

wolfSSL was designed as IP neutral, and will work with both IPv4 and IPv6, but the

current test applications default to IPv4 (so as to apply to a broader range of systems).

To change the test applications to IPv6, use the --enable-ipv6 option while building

wolfSSL.

Further information on IPv6 can be found here:

http://en.wikipedia.org/wiki/IPv6.

4.2.5 DTLS

wolfSSL has support for DTLS (“Datagram” TLS) for both client and server. The current

supported version is DTLS 1.0.

The TLS protocol was designed to provide a secure transport channel across a reliable

medium (such as TCP). As application layer protocols began to be developed using

UDP transport (such as SIP and various electronic gaming protocols), a need arose for

a way to provide communications security for applications which are delay sensitive.

This need lead to the creation of the DTLS protocol.

Many people believe the difference between TLS and DTLS is the same as TLS vs.

UDP. This is incorrect. UDP has the benefit of having no handshake, no tear-down, and

no delay in the middle if something gets lost (compared with TCP). DTLS on the other

hand, has an extended SSL handshake and tear-down and must implement TCP-like

behavior for the handshake. In essence, DTLS reverses the benefits that are offered by

UDP in exchange for a secure connection.

DTLS can be enabled when building wolfSSL by using the --enable-dtls build option.

4.2.6 LwIP (Lightweight Internet Protocol)

wolfSSL supports the lightweight internet protocol implementation out of the box. To use

this protocol all you need to do is define WOLFSSL_LWIP or navigate to the settings.h

file and uncomment the line:

/*#define WOLFSSL_LWIP*/

The focus of lwIP is to reduce RAM usage while still providing a full TCP stack. That

focus makes lwIP great for use in embedded systems, an area where wolfSSL is an

ideal match for SSL/TLS needs.

4.3 Cipher Support

4.3.1 Cipher Suite Strength and Choosing Proper Key Sizes

To see what ciphers are currently being used you can call the method:

wolfSSL_get_ciphers()

This function will return the currently enabled cipher suites.

Cipher suites come in a variety of strengths. Because they are made up of several

different types of algorithms (authentication, encryption, and message authentication

code (MAC)), the strength of each varies with the chosen key sizes.

There can be many methods of grading the strength of a cipher suite - the specific

method used seems to vary between different projects and companies and can include

things such as symmetric and public key algorithm key sizes, type of algorithm,

performance, and known weaknesses.

NIST (National Institute of Standards and Technology) makes recommendations on

choosing an acceptable cipher suite by providing comparable algorithm strengths for

varying key sizes of each. The strength of a cryptographic algorithm depends on the

algorithm and the key size used. The NIST Special Publication, SP800-57, states that

two algorithms are considered to be of comparable strength as follows:

… two algorithms are considered to be of comparable strength for the

given key sizes (X and Y) if the amount of work needed to “break the

algorithms” or determine the keys (with the given key sizes) is

approximately the same using a given resource. The security strength of

an algorithm for a given key size is traditionally described in terms of the

amount of work it takes to try all keys for a symmetric algorithm with a key

size of “X” that has no shortcut attacks (i.e., the most efficient attack is to

try all possible keys).

The following two tables are based off of both Table 2 (pg. 64) and Table 4 (pg. 66)

from NIST SP800-57, and shows comparable security strength between algorithms as

well as a strength measurement (based off of NIST’s suggested algorithm security

lifetimes using bits of security).

Note: In the following table “L” is the size of the public key for finite field cryptography

(FFC), “N” is the size of the private key for FFC, “k” is considered the key size for

integer factorization cryptography (IFC), and “f” is considered the key size for elliptic

curve cryptography.

Bits of

Security

Symmetric Key

Algorithms

FFC Key Size

(DSA, DH, etc.)

IFC Key Size

(RSA, etc.)

ECC Key Size

(ECDSA, etc.)

2TDEA, etc.

L = 1024

N = 160

k = 1024

f = 160-223

128

AES-128, etc.

L = 3072

N = 256

k = 3072

f = 256-383

192

AES-192, etc.

L = 7680

N = 384

k = 7680

f = 384-511

256

AES-256, etc.

L = 15360

N = 512

k = 15360

f = 512+

(Table 2: Relative Bit and Key Strengths)

Bits of Security

Description

Security)good)through)2010

128

Security)good)through)2030

192

Long)Term)Protection

256

Secure)for)the)foreseeable)future

(Table 3: Bit Strength Descriptions)

Using this table as a guide, to begin to classify a cipher suite, we categorize it based on

the strength of the symmetric encryption algorithm. In doing this, a rough grade

classification can be devised to classify each cipher suite based on bits of security (only

taking into account symmetric key size):

LOW = bits of security smaller than 128 bits

MEDIUM = bits of security equal to 128 bits

HIGH = bits of security larger than 128 bits

Outside of the symmetric encryption algorithm strength, the strength of a cipher suite

will depend greatly on the key sizes of the key exchange and authentication algorithm

keys. The strength is only as good as the cipher suite’s weakest link.

Following the above grading methodology (and only basing it on symmetric encryption

algorithm strength), wolfSSL 2.0.0 currently supports a total of 0 LOW strength cipher

suites, 12 MEDIUM strength cipher suites, and 8 HIGH strength cipher suites – as listed

below. The following strength classification could change depending on the chosen key

sizes of the other algorithms involved. For a reference on hash function security

strength, see Table 3 (pg. 64) of NIST SP800-57.

In some cases, you will see ciphers referenced as “EXPORT” ciphers. These ciphers

originated from the time period in US history (as late as 1992) when it was illegal to

export software with strong encryption from the United States. Strong encryption was

classified as “Munitions” by the US Government (under the same category as Nuclear

Weapons, Tanks, and Ballistic Missiles). Because of this restriction, software being

exported included “weakened” ciphers (mostly in smaller key sizes). In the current day,

this restriction has been lifted, and as such, EXPORT ciphers are no longer a mandated

necessity.

4.3.2 Supported Cipher Suites

The following cipher suites are supported by wolfSSL. A cipher suite is a combination of

authentication, encryption, and message authentication code (MAC) algorithms which

are used during the TLS or SSL handshake to negotiate security settings for a

connection.

Each cipher suite defines a key exchange algorithm, a bulk encryption algorithm, and a

message authentication code algorithm (MAC). The key exchange algorithm (RSA,

DSS, DH, EDH) determines how the client and server will authenticate during the

handshake process. The bulk encryption algorithm (DES, 3DES, AES, ARC4,

RABBIT, HC-128), including block ciphers and stream ciphers, is used to encrypt the

message stream. The message authentication code (MAC) algorithm (MD2, MD5,

SHA-1, SHA-256, SHA-512, RIPEMD) is a hash function used to create the message

digest.

The table below matches up to the cipher suites (and categories) found in

<wolfssl_root>/wolfssl/internal.h (starting at about line 706). If you are looking for a

cipher suite which is not in the following list, please contact us to discuss getting it

added to wolfSSL.

wolfSSL Cipher Suites

(version 3.10.0)

TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA

TLS_DHE_RSA_WITH_AES_256_CBC_SHA

TLS_DHE_RSA_WITH_AES_128_CBC_SHA

TLS_DH_anon_WITH_AES_128_CBC_SHA

TLS_RSA_WITH_AES_256_CBC_SHA

TLS_RSA_WITH_AES_128_CBC_SHA

TLS_RSA_WITH_NULL_SHA

TLS_PSK_WITH_AES_256_CBC_SHA

TLS_PSK_WITH_AES_128_CBC_SHA256

TLS_PSK_WITH_AES_256_CBC_SHA384

TLS_PSK_WITH_AES_128_CBC_SHA

TLS_PSK_WITH_NULL_SHA256

TLS_PSK_WITH_NULL_SHA384

TLS_PSK_WITH_NULL_SHA

SSL_RSA_WITH_RC4_128_SHA

SSL_RSA_WITH_RC4_128_MD5

SSL_RSA_WITH_3DES_EDE_CBC_SHA

SSL_RSA_WITH_IDEA_CBC_SHA

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

TLS_ECDHE_RSA_WITH_RC4_128_SHA

TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

TLS_ECDHE_PSK_WITH_NULL_SHA256

TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256

TLS_ECDHE_ECDSA_WITH_NULL_SHA

ECC cipher

suites

TLS_ECDH_RSA_WITH_AES_256_CBC_SHA

TLS_ECDH_RSA_WITH_AES_128_CBC_SHA

TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA

TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

TLS_ECDH_RSA_WITH_RC4_128_SHA

TLS_ECDH_ECDSA_WITH_RC4_128_SHA

TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA

TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA

TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256

TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384

TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384

Static ECDH

cipher suites

TLS_RSA_WITH_HC_128_MD5

TLS_RSA_WITH_HC_128_SHA

TLS_RSA_WITH_RABBIT_SHA

wolfSSL

extension -

eSTREAM cipher

suites

TLS_RSA_WITH_AES_128_CBC_B2B256

TLS_RSA_WITH_AES_256_CBC_B2B256

TLS_RSA_WITH_HC_128_B2B256

Blake2b cipher

suites

TLS_QSH

wolfSSL

extension -

Quantum-Safe

Handshake

TLS_NTRU_RSA_WITH_RC4_128_SHA

TLS_NTRU_RSA_WITH_3DES_EDE_CBC_SHA

TLS_NTRU_RSA_WITH_AES_128_CBC_SHA

TLS_NTRU_RSA_WITH_AES_256_CBC_SHA

wolfSSL

extension - NTRU

cipher suites

TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

TLS_RSA_WITH_AES_256_CBC_SHA256

TLS_RSA_WITH_AES_128_CBC_SHA256

TLS_RSA_WITH_NULL_SHA256

TLS_DHE_PSK_WITH_AES_128_CBC_SHA256

TLS_DHE_PSK_WITH_NULL_SHA256

SHA-256 cipher

suites

TLS_DHE_PSK_WITH_AES_256_CBC_SHA384

TLS_DHE_PSK_WITH_NULL_SHA384

SHA-384 cipher

suites

TLS_RSA_WITH_AES_128_GCM_SHA256

TLS_RSA_WITH_AES_256_GCM_SHA384

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

TLS_PSK_WITH_AES_128_GCM_SHA256

TLS_PSK_WITH_AES_256_GCM_SHA384

TLS_DHE_PSK_WITH_AES_128_GCM_SHA256

TLS_DHE_PSK_WITH_AES_256_GCM_SHA384

AES-GCM cipher

suites

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256

TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384

ECC AES-GCM

cipher suites

TLS_RSA_WITH_AES_128_CCM_8

TLS_RSA_WITH_AES_256_CCM_8

TLS_ECDHE_ECDSA_WITH_AES_128_CCM

TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8

TLS_PSK_WITH_AES_128_CCM

TLS_PSK_WITH_AES_256_CCM

TLS_PSK_WITH_AES_128_CCM_8

TLS_PSK_WITH_AES_256_CCM_8

TLS_DHE_PSK_WITH_AES_128_CCM

AES-CCM cipher

suites

TLS_DHE_PSK_WITH_AES_256_CCM

TLS_RSA_WITH_CAMELLIA_128_CBC_SHA

TLS_RSA_WITH_CAMELLIA_256_CBC_SHA

TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256

TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256

TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA

TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA

TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256

TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256

Camellia cipher

suites

TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

TLS_PSK_WITH_CHACHA20_POLY1305_SHA256

TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256

TLS_ECDHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA25

TLS_ECDHE_ECDSA_WITH_CHACHA20_OLD_POLY1305_SH

A256

TLS_DHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA256

ChaCha cipher

suites

TLS_EMPTY_RENEGOTIATION_INFO_SCSV

Renegotiation

Indication

Extension Special

Suite

(Table 4: wolfSSL Cipher Suites)

4.3.3 AEAD Suites

wolfSSL supports AEAD suites, including AES-GCM, AES-CCM, and CHACHA-

POLY1305. The big difference between these AEAD suites and others is that they

authenticate the encrypted data. This helps with mitigating man in the middle attacks

that result in having data tampered with. AEAD suites use a combination of a block

cipher (or more recently also a stream cipher) algorithm combined with a tag produced

by a keyed hash algorithm. Combining these two algorithms is handled by the wolfSSL

encrypt and decrypt process which makes it easier for users. All that is needed for using

a specific AEAD suite is simply enabling the algorithms that are used in a supported

suite.

4.3.4 Block and Stream Ciphers

wolfSSL supports the AES, DES, 3DES, and Camellia block ciphers and the RC4,

RABBIT, HC-128 and CHACHA20 stream ciphers. AES, DES, 3DES, RC4 and

RABBIT are enabled by default. Camellia, HC-128, and ChaCha20 can be enabled

when building wolfSSL (with the --enable-hc128, --enable-camellia, and --enable-

chacha build options, respectively). The default mode of AES is CBC mode. To enable

GCM or CCM mode with AES, use the --enable-aesgcm and --enable-aesccm build

options. Please see the examples for usage and the wolfCrypt Usage Reference

(Chapter 10) for specific usage information.

SSL uses RC4 as the default stream cipher. It's a good one, though it's getting a little

old. wolfSSL has added two ciphers from the eStream project into the code base,

RABBIT and HC-128. RABBIT is nearly twice as fast as RC4 and HC-128 is about 5

times as fast! So if you've ever decided not to use SSL because of speed concerns,

using wolfSSL's stream ciphers should lessen or eliminate that performance doubt.

Recently wolfSSL also added ChaCha20. While RC4 performs about .11 times faster

than ChaCha, RC4 is generally considered less secure than ChaCha. ChaCha can put

up very nice times of it’s own with added security as a tradeoff.

To see a comparison of cipher performance, visit the wolfSSL Benchmark web page,

located here: http://wolfssl.com/yaSSL/benchmarks-wolfssl.html.

4.3.4.1 What’s the Difference?

A block cipher has to be encrypted in chunks that are the block size for the cipher. For

example, AES has block size of 16 bytes. So if you're encrypting a bunch of small, 2 or

3 byte chunks back and forth, over 80% of the data is useless padding, decreasing the

speed of the encryption/decryption process and needlessly wasting network bandwidth

to boot. Basically block ciphers are designed for large chunks of data, have block sizes

requiring padding, and use a fixed, unvarying transformation.

Stream ciphers work well for large or small chunks of data. They are suitable for smaller

data sizes because no block size is required. If speed is a concern, stream ciphers are

your answer, because they use a simpler transformation that typically involves an xor'd

keystream. So if you need to stream media, encrypt various data sizes including small

ones, or have a need for a fast cipher then stream ciphers are your best bet.

4.3.5 Hashing Functions

wolfSSL supports several different hashing functions, including MD2, MD4, MD5, SHA-

1, SHA-2 (SHA-224, SHA-256, SHA-384, SHA-512), SHA-3 (BLAKE2), and RIPEMD-

160. Detailed usage of these functions can be found in the wolfCrypt Usage Reference,

Section 10.1.

4.3.6 Public Key Options

wolfSSL supports the RSA, ECC, DSA/DSS, DH, and NTRU public key options, with

support for EDH (Ephemeral Diffie-Hellman) on the wolfSSL server. Detailed usage of

these functions can be found in the wolfCrypt Usage Reference, section 10.5.

wolfSSL has support for four cipher suites utilizing NTRU public key:

TLS_NTRU_RSA_WITH_3DES_EDE_CBC_SHA

TLS_NTRU_RSA_WITH_RC4_128_SHA

TLS_NTRU_RSA_WITH_AES_128_CBC_SHA

TLS_NTRU_RSA_WITH_AES_256_CBC_SHA

The strongest one, AES-256, is the default. If wolfSSL is enabled with NTRU and the

NTRU library is available, these cipher suites are built into the wolfSSL library. A

wolfSSL client will have these cipher suites available without any interaction needed by

the user. On the other hand, a wolfSSL server application will need to load an NTRU

private key and NTRU x509 certificate in order for those cipher suites to be available for

use.

The example servers, echoserver and server, both use the define HAVE_NTRU (which

is turned on by enabling NTRU) to specify whether or not to load NTRU keys and

certificates. The wolfSSL package comes with test keys and certificates in the /certs

directory. ntru-cert.pem is the certificate and ntru-key.raw is the private key blob.

The wolfSSL NTRU cipher suites are given the highest preference order when the

protocol picks a suite. Their exact preference order is the reverse of the above listed

suites, i.e., AES-256 will be picked first and 3DES last before moving onto the

“standard” cipher suites. Basically, if a user builds NTRU into wolfSSL and both sides of

the connection support NTRU then an NTRU cipher suite will be picked unless a user

on one side has explicitly excluded them by stating to only use different cipher suites.

Using NTRU over RSA can provide a 20 - 200X speed improvement. The improvement

increases as the size of keys increases, meaning a much larger speed benefit when

using large keys (8192-bit) versus smaller keys (1024-bit).

4.3.7 ECC Support

wolfSSL has support for Elliptic Curve Cryptography (ECC) including but not limited to:

ECDH-ECDSA, ECDHE-ECDSA, ECDH-RSA, ECDHE-PSK and ECDHE-RSA.

wolfSSL’s ECC implementation can be found in the

<wolfssl_root>/wolfssl/wolfcrypt/ecc.h header file and the

<wolfssl_root>/wolfcrypt/src/ecc.c source file.

Supported cipher suites are shown in the table above. ECC is disabled by default on

non x86_64 builds, but can be turned on when building wolfSSL with the HAVE_ECC

define or by using the autoconf system:

./configure --enable-ecc

make

make check

When “make check” runs, note the numerous cipher suites that wolfSSL checks (if

make check doesn’t produce a list of cipher suites run ./testsuite/testsuite.test on its

own). Any of these cipher suites can be tested individually, e.g., to try ECDH-ECDSA

with AES256-SHA, the example wolfSSL server can be started like this:

./examples/server/server -d -l ECDHE-ECDSA-AES256-SHA -c

./certs/server-ecc.pem -k ./certs/ecc-key.pem

(-d) disables client cert check while (-l) specifies the cipher suite list. (-c) is the

certificate to use and (-k) is the corresponding private key to use. To have the client

connect try:

./examples/client/client -A ./certs/server-ecc.pem

where (-A) is the CA certificate to use to verify the server.

4.3.8 PKCS Support

PKCS (Public Key Cryptography Standards) refers to a group of standards created and

published by RSA Security, Inc. wolfSSL has support for PKCS #5, PKCS #8, and

PBKD from PKCS #12.

4.3.8.1 PKCS #5, PBKDF1, PBKDF2, PKCS #12

PKCS #5 is a password based key derivation method which combines a password, a

salt, and an iteration count to generate a password-based key. wolfSSL supports both

PBKDF1 and PBKDF2 key derivation functions. A key derivation function produces a

derived key from a base key and other parameters (such as the salt and iteration count

as explained above). PBKDF1 applies a hash function (MD5, SHA1, etc) to derive keys,

where the derived key length is bounded by the length of the hash function output. With

PBKDF2, a pseudorandom function is applied (such as HMAC-SHA-1) to derive the

keys. In the case of PBKDF2, the derived key length is unbounded.

wolfSSL also supports the PBKDF function from PKCS #12 in addition to PBKDF1 and

PBKDF2. The function prototypes look like this:

int PBKDF2(byte* output, const byte* passwd, int pLen,

const byte* salt,int sLen, int iterations,

int kLen, int hashType);

int PKCS12_PBKDF(byte* output, const byte* passwd, int pLen,

const byte* salt, int sLen, int iterations,

int kLen, int hashType, int purpose);

output contains the derived key, passwd holds the user password of length pLen, salt

holds the salt input of length sLen, iterations is the number of iterations to perform,

kLen is the desired derived key length, and hashType is the hash to use (which can be

MD5, SHA1, or SHA2).

If you are using ./configure to build wolfssl, the way to enable this functionality is to

use the option --enable-pwdbased

A full example can be found in <wolfSSL Root>/wolfcrypt/test.c. More information can

be found on PKCS #5, PBKDF1, and PBKDF2 from the following specifications:

PKCS#5, PBKDF1, PBKDF2: http://tools.ietf.org/html/rfc2898

4.3.8.2 PKCS #8

PKCS #8 is designed as the Private-Key Information Syntax Standard, which is used to

store private key information - including a private key for some public-key algorithm and

set of attributes.

The PKCS #8 standard has two versions which describe the syntax to store both

encrypted private keys and non-encrypted keys. wolfSSL supports both unencrypted

and encrypted PKCS #8. Supported formats include PKCS #5 version 1 - version 2, and

PKCS#12. Types of encryption available include DES, 3DES, RC4, and AES.

PKCS#8: http://tools.ietf.org/html/rfc5208

4.3.9 Forcing the Use of a Specific Cipher

By default, wolfSSL will pick the “best” (highest security) cipher suite that both sides of

the connection can support. To force a specific cipher, such as 128 bit AES, add

something similar to:

wolfSSL_CTX_set_cipher_list(ctx, “AES128-SHA”);

after the call to wolfSSL_CTX_new(); so that you have:

ctx = wolfSSL_CTX_new(method);

wolfSSL_CTX_set_cipher_list(ctx, “AES128-SHA”);

4.3.10 Quantum-Safe Handshake Ciphersuite

wolfSSL has support for the cipher suite utilizing post quantum handshake cipher suite

such as with NTRU:

TLS_QSH

If wolfSSL is enabled with NTRU and the NTRU package is available, the TLS_QSH

cipher suite is built into the wolfSSL library. A wolfSSL client and server will have this

cipher suite available without any interaction needed by the user.

The wolfSSL quantum safe handshake ciphersuite is given the highest preference order

when the protocol picks a suite. Basically, if a user builds NTRU into wolfSSL and both

sides of the connection support NTRU then an NTRU cipher suite will be picked unless

a user on one side has explicitly excluded them by stating to only use different cipher

suites.

Users can adjust what crypto algorithms and if the client sends across public keys by

using the function examples

wolfSSL_UseClientQSHKeys(ssl, 1);

wolfSSL_UseSupportedQSH(ssl, WOLFSSL_NTRU_EESS439);

To test if a QSH connection was established after a client has connected the following

function example can be used.

wolfSSL_isQSH(ssl);

4.4 Hardware Accelerated Crypto

wolfSSL is able to take advantage of several hardware accelerated (or “assisted”)

crypto functionalities in various processors and chips. The following sections explain

which technologies wolfSSL supports out-of-the-box.

4.4.1 Intel AES-NI

AES is a key encryption standard used by governments worldwide, which wolfSSL has

always supported. Intel has released a new set of instructions that is a faster way to

implement AES. wolfSSL is the first SSL library to fully support the new instruction set

for production environments.

Essentially, Intel has added AES instructions at the chip level that perform the

computationally-intensive parts of the AES algorithm, boosting performance. For a list

of Intel’s chips that currently have support for AES-NI, you can look here:

http://ark.intel.com/search/advanced/?s=t&AESTech=true

We have added the functionality to wolfSSL to allow it to call the instructions directly

from the chip, instead of running the algorithm in software. This means that when you’re

running wolfSSL on a chipset that supports AES-NI, you can run your AES crypto 5-10

times faster!

If you are running on an AES-NI supported chipset, enable AES-NI with the --enable-

aesni build option. To build wolfSSL with AES-NI, GCC 4.4.3 or later is required to

make use of the assembly code.

References and further reading on AES-NI, ordered from general to specific, are listed

below. For information about performance gains with AES-NI, please see the third link

to the Intel Software Network page.

AES (Wikipedia)

http://en.wikipedia.org/wiki/Advanced_Encryption_Standard

AES-NI (Wikipedia)

http://en.wikipedia.org/wiki/AES_instruction_set

AES-NI (Intel Software

Network page)

http://software.intel.com/en-us/articles/intel-advanced-

encryption-standard-instructions-aes-ni/

4.4.2 STM32F2

wolfSSL is able to use the STM32F2 hardware-based cryptography and random

number generator through the STM32F2 Standard Peripheral Library.

For necessary defines, see the WOLFSSL_STM32F2 define in settings.h. The

WOLFSSL_STM32F2 define enables STM32F2 hardware crypto and RNG support by

default. The defines for enabling these individually are STM32F2_CRYPTO (for

hardware crypto support) and STM32F2_RNG (for hardware RNG support).

Documentation for the STM32F2 Standard Peripheral Library can be found in the

following document:

http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATUR

E/USER_MANUAL/DM00023896.pdf

4.4.3 Cavium NITROX

wolfSSL has support for Cavium NITROX

(http://www.cavium.com/processor_security.html). To enable Cavium NITROX support

when building wolfSSL use the following configure option:

./configure --with-cavium=/home/user/cavium/software

Where the “--with-cavium=” option is pointing to your licensed cavium/software

directory. Since Cavium doesn't build a library wolfSSL pulls in the cavium_common.o

file which gives a libtool warning about the portability of this. Also, if you're using the

github source tree you'll need to remove the -Wredundant-decls warning from the

generated Makefile because the cavium headers don't conform to this warning.

Currently wolfSSL supports Cavium RNG, AES, 3DES, RC4, HMAC, and RSA directly

at the crypto layer. Support at the SSL level is partial and currently just does AES,

3DES, and RC4. RSA and HMAC are slower until the Cavium calls can be utilized in

non-blocking mode. The example client turns on cavium support as does the crypto test

and benchmark. Please see the HAVE_CAVIUM define.

4.5 SSL Inspection (Sniffer)

Beginning with the wolfSSL 1.5.0 release, wolfSSL has included a build option allowing

it to be built with SSL Sniffer (SSL Inspection) functionality. This means that you can

collect SSL traffic packets and with the correct key file, are able to decrypt them as well.

The ability to “inspect” SSL traffic can be useful for several reasons, some of which

include:

● Analyzing Network Problems

● Detecting network misuse by internal and external users

● Monitoring network usage and data in motion

● Debugging client/server communications

To enable sniffer support, build wolfSSL with the --enable-sniffer option on *nix or use

the vcproj files on Windows. You will need to have pcap installed on *nix or WinPcap

on Windows. The main sniffer functions which can be found in sniffer.h are listed below

with a short description of each:

ssl_SetPrivateKey - Sets the private key for a specific server and port.

ssl_SetNamedPrivateKey - Sets the private key for a specific server, port and domain

name.

ssl_DecodePacket - Passes in a TCP/IP packet for decoding.

ssl_Trace - Enables / Disables debug tracing to the traceFile.

ssl_InitSniffer - Initialize the overall sniffer.

ssl_FreeSniffer - Free the overall sniffer.

ssl_EnableRecovery - Enables option to attempt to pick up decoding of SSL traffic in

the case of lost packets.

ssl_GetSessionStats - Obtains memory usage for the sniffer sessions.

To look at wolfSSL's sniffer support and see a complete example, please see the

"snifftest" app in the "sslSniffer/sslSnifferTest" folder from the wolfSSL download.

Keep in mind that because the encryption keys are setup in the SSL Handshake, the

handshake needs to be decoded by the sniffer in order for future application data to be

decoded. For example, if you are using "snifftest" with the wolfSSL example echoserver

and echoclient, the snifftest application must be started before the handshake begins

between the server and client.

The sniffer can only decode streams encrypted with the following algorithms: AES-CBC,

DES3-CBC, ARC4, HC-128, RABBIT, Camellia-CBC, and IDEA. If ECDHE or DHE key

agreement is used the stream cannot be sniffed; only RSA key-exchange is supported.

4.6 Compression

wolfSSL supports data compression with the zlib library. The ./configure build system

detects the presence of this library, but if you're building in some other way define the

constant HAVE_LIBZ and include the path to zlib.h for your includes.

Compression is off by default for a given cipher. To turn it on, use the function

wolfSSL_set_compression() before SSL connecting or accepting. Both the client and

server must have compression turned on in order for compression to be used.

Keep in mind that 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.

4.7 Pre-Shared Keys

wolfSSL has support for these ciphers with static pre-shared keys:

TLS_PSK_WITH_AES_256_CBC_SHA

TLS_PSK_WITH_AES_128_CBC_SHA256

TLS_PSK_WITH_AES_256_CBC_SHA384

TLS_PSK_WITH_AES_128_CBC_SHA

TLS_PSK_WITH_NULL_SHA256

TLS_PSK_WITH_NULL_SHA384

TLS_PSK_WITH_NULL_SHA

TLS_PSK_WITH_AES_128_GCM_SHA256

TLS_PSK_WITH_AES_256_GCM_SHA384

TLS_PSK_WITH_AES_128_CCM

TLS_PSK_WITH_AES_256_CCM

TLS_PSK_WITH_AES_128_CCM_8

TLS_PSK_WITH_AES_256_CCM_8

TLS_PSK_WITH_CHACHA20_POLY1305

These suites are built into wolfSSL with WOLFSSL_STATIC_PSK on, all PSK suites

can be turned off at build time with the constant NO_PSK. To only use these ciphers at

runtime use the function wolfSSL_CTX_set_cipher_list() with the desired ciphersuite.

wolfSSL has support for ephemeral key PSK suites:

ECDHE-PSK-AES128-CBC-SHA256

ECDHE-PSK-NULL-SHA256

ECDHE-PSK-CHACHA20-POLY1305

DHE-PSK-CHACHA20-POLY1305

DHE-PSK-AES256-GCM-SHA384

DHE-PSK-AES128-GCM-SHA256

DHE-PSK-AES256-CBC-SHA384

DHE-PSK-AES128-CBC-SHA256

On the client, use the function wolfSSL_CTX_set_psk_client_callback() to setup the

callback. The client example in <wolfSSL_Home>/examples/client/client.c gives

example usage for setting up the client identity and key, though the actual callback is

implemented in wolfssl/test.h.

On the server side two additional calls are required:

wolfSSL_CTX_set_psk_server_callback()

wolfSSL_CTX_use_psk_identity_hint()

The server stores its identity hint to help the client with the 2nd call, in our server

example that's "wolfssl server". An example server psk callback can also be found in

my_psk_server_cb() in wolfssl/test.h.

wolfSSL supports identities and hints up to 128 octets and pre-shared keys up to 64

octets.

4.8 Client Authentication

Client authentication is a feature which enables the server to authenticate clients by

requesting that the clients send a certificate to the server for authentication when they

connect. Client authentication requires an X.509 client certificate from a CA (or self-

signed if generated by you or someone other than a CA).

By default, wolfSSL validates all certificates that it receives - this includes both client

and server. To set up client authentication, the server must load the list of trusted CA

certificates to be used to verify the client certificate against:

wolfSSL_CTX_load_verify_locations(ctx, caCert, 0);

To turn on client verification and control its behavior, the wolfSSL_CTX_set_verify()

function is used. In the following example, SSL_VERIFY_PEER turns on a certificate

request from the server to the client. SSL_VERIFY_FAIL_IF_NO_PEER_CERT

instructs the server to fail if the client does not present a certificate to validate on the

server side. Other options to wolfSSL_CTX_set_verify() include SSL_VERIFY_NONE

and SSL_VERIFY_CLIENT_ONCE.

wolfSSL_CTX_set_verify(ctx,SSL_VERIFY_PEER | ((usePskPlus)?

SSL_VERIFY_FAIL_EXCEPT_PSK :

SSL_VERIFY_FAIL_IF_NO_PEER_CERT),0);

An example of client authentication can be found in the example server (server.c)

included in the wolfSSL download (/examples/server/server.c).

4.9 Server Name Indication

SNI is useful when a server hosts multiple ‘virtual’ servers at a single underlying

network address. It may be desirable for clients to provide the name of the server which

it is contacting. To enable SNI with wolfSSL you can simply do:

./configure --enable-sni

Using SNI on the client side requires an additional function call, which should be one of

the following functions:

wolfSSL_CTX_UseSNI()

wolfSSL_UseSNI()

wolfSSL_CTX_UseSNI() is most recommended when the client contacts the same

server multiple times. Setting the SNI extension at the context level will enable the SNI

usage in all SSL objects created from that same context from the moment of the call

forward.

wolfSSL_UseSNI() will enable SNI usage for one SSL object only, so it is recommended

to use this function when the server name changes between sessions.

On the server side one of the same function calls is required. Since the wolfSSL server

doesn't host multiple 'virtual' servers, the SNI usage is useful when the termination of

the connection is desired in the case of SNI mismatch. In this scenario,

wolfSSL_CTX_UseSNI() will be more efficient, as the server will set it only once per

context creating all subsequent SSL objects with SNI from that same context.

4.10 Handshake Modifications

4.10.1 Grouping Handshake Messages

wolfSSL has the ability to group handshake messages if the user desires. This can be

done at the context level with:

wolfSSL_CTX_set_group_messages(ctx);

or at the SSL object level with:

wolfSSL_set_group_messages(ssl);

4.11 Truncated HMAC

Currently defined TLS cipher suites use the HMAC to authenticate record-layer

communications. In TLS, the entire output of the hash function is used as the MAC tag.

However, it may be desirable in constrained environments to save bandwidth by

truncating the output of the hash function to 80 bits when forming MAC tags. To enable

the usage of Truncated HMAC at wolfSSL you can simply do:

./configure --enable-truncatedhmac

Using Truncated HMAC on the client side requires an additional function call, which

should be one of the following functions:

wolfSSL_CTX_UseTruncatedHMAC();

wolfSSL_UseTruncatedHMAC();

wolfSSL_CTX_UseTruncatedHMAC() is most recommended when the client would

like to enable Truncated HMAC for all sessions. Setting the Truncated HMAC extension

at context level will enable it in all SSL objects created from that same context from the

moment of the call forward.

wolfSSL_UseTruncatedHMAC() will enable it for one SSL object only, so it's

recommended to use this function when there is no need for Truncated HMAC on all

sessions.

On the server side no call is required. The server will automatically attend to the client's

request for Truncated HMAC.

All TLS extensions can also be enabled with:

./configure --enable-tlsx

4.12 User Crypto Module

User Crypto Module allows for a user to plug in custom crypto that they want used

during supported operations (Currently RSA operations are supported). An example of a

module is located in the directory root_wolfssl/wolfcrypt/user-crypto/ using IPP libraries.

Examples of the configure option when building wolfSSL to use a crypto module is as

follows :

./configure --with-user-crypto

./configure --with-user-crypto=/dir/to

When creating a user crypto module that performs RSA operations, it is mandatory that

there is a header file for RSA called user_rsa.h. For all user crypto operations it is

mandatory that the users library be called libusercrypto. These are the names that

wolfSSL autoconf tools will be looking for when linking and using a user crypto module.

In the example provided with wolfSSL, the header file user_rsa.h can be found in the

directory wolfcrypt/user-crypto/include/ and the library once created is located in the

directory wolfcrypt/user-crypto/lib/ . For a list of required API look at the header file

provided.

To build the example, after having installed IPP libraries, the following commands from

the root wolfSSL directory should be ran.

cd wolfcrypt/user-crypto/

./autogen.sh

./configure

make

sudo make install

The included example in wolfSSL requires the use of IPP, which will need to be installed

before the project can be built. Though even if not having IPP libraries to build the

example it is intended to provide users with an example of file name choice and API

interface. Once having made and installed both the library libusercrypto and header

files, making wolfSSL use the crypto module does not require any extra steps. Simply

using the configure flag --with-user-crypto will map all function calls from the typical

wolfSSL crypto to the user crypto module.

Memory allocations, if using wolfSSL’s XMALLOC, should be tagged with

DYNAMIC_TYPE_USER_CRYPTO. Allowing for analyzing memory allocations used by

the module.

User crypto modules cannot be used in conjunction with the wolfSSL configure options

fast-rsa and/or fips. Fips requires that specific, certified code be used and fast-rsa

makes use of the example user crypto module to perform RSA operations.

4.13 Timing-Resistance in wolfSSL

wolfSSL provides the function “ConstantCompare” which guarantees constant time

when doing comparison operations that could potentially leak timing information. This

API is used at both the TLS and crypto level in wolfSSL to deter against timing based,

side-channel attacks.

The wolfSSL ECC implementation has the define ECC_TIMING_RESISTANT to enable

timing-resistance in the ECC algorithm. Similarly the define TFM_TIMING_RESISTANT

is provided in the fast math libraries for RSA algorithm timing-resistance. The function

exptmod uses the timing resistant Montgomery ladder.

See Also:

wolfSSL_Cleanup

wolfSSL_library_init

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_library_init(void)

Description:

This function is called internally in wolfSSL_CTX_new().

This function is a wrapper around wolfSSL_Init() and exists for OpenSSL compatibility

(SSL_library_init) when wolfSSL has been compiled with OpenSSL compatibility layer.

wolfSSL_Init() is the more typically-used wolfSSL initialization function.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FATAL_ERROR is returned upon failure.

Parameters:

This function takes no parameters.

Example:

int ret = 0;

ret = wolfSSL_library_init();

if (ret != SSL_SUCCESS) {

/*failed to initialize wolfSSL*/

}

...

See Also:

wolfSSL_Init

wolfSSL_Cleanup

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_Cleanup(void);

Description:

Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it

will free any resources used by the library.

Return Values:

SSL_SUCCESS return no errors.

BAD_MUTEX_E a mutex error return.

Parameters:

There are no parameters for this function.

Example:

wolfSSL_Cleanup();

See Also:

wolfSSL_Init

wolfSSL_shutdown

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_shutdown(WOLFSSL* ssl);

Description:

This function shuts down an active SSL/TLS connection using the SSL session, ssl.

This function will try to send a “close notify” alert to the peer.

The calling application can choose to wait for the peer to send its “close notify” alert in

response or just go ahead and shut down the underlying connection after directly calling

wolfSSL_shutdown (to save resources). Either option is allowed by the TLS

specification. If the underlying connection will be used again in the future, the complete

two-directional shutdown procedure must be performed to keep synchronization intact

between the peers.

wolfSSL_shutdown() works with both blocking and non-blocking I/O. When the

underlying I/O is non-blocking, wolfSSL_shutdown() will return an error if the underlying

I/O could not satisfy the needs of wolfSSL_shutdown() to continue. In this case, a call

to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to

wolfSSL_shutdown() when the underlying I/O is ready.

Return Values:

SSL_SUCCESS - will be returned upon success.

SSL_SHUTDOWN_NOT_DONE - will be returned when shutdown has not finished, and

the function should be called again.

SSL_FATAL_ERROR - will be returned upon failure. Call wolfSSL_get_error() for a

more specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret = 0;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_shutdown(ssl);

if (ret != 0) {

/*failed to shut down SSL connection*/

}

See Also:

wolfSSL_free

wolfSSL_CTX_free

wolfSSL_get_shutdown

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_shutdown(WOLFSSL* ssl);

Description:

This function checks the shutdown conditions in closeNotify or connReset or sentNotify

members of the Options structure. The Options structure is within the WOLFSSL

structure.

Return Values:

1 - SSL_SENT_SHUTDOWN is returned.

2 - SSL_RECEIVED_SHUTDOWN is returned.

Parameters:

ssl - a constant pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

…

int ret;

ret = wolfSSL_get_shutdown(ssl);

if(ret == 1){

/*SSL_SENT_SHUTDOWN */

} else if(ret == 2){

/*SSL_RECEIVED_SHUTDOWN */

} else {

/*Fatal error.*/

}

See Also:

wolfSSL_SESSION_free

wolfSSL_is_init_finished

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_is_init_finished(WOLFSSL* ssl);

Description:

This function checks to see if the connection is established.

Return Values:

0 - returned if the connection is not established, i.e. the WOLFSSL struct is NULL or the

handshake is not done.

1 - returned if the handshake is done.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_is_init_finished(ssl)){

/*Handshake is done and connection is established*/

}

See Also:

wolfSSL_set_accept_state

wolfSSL_get_keys

wolfSSL_set_shutdown

wolfSSL_ALPN_GetPeerProtocol

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char** list, word16* listSz);

Description:

This function copies the alpn_client_list data from the SSL object to the buffer.

Return Values:

SSL_SUCCESS - returned if the function executed without error. The alpn_client_list

member of the SSL object has been copied to the list parameter.

BAD_FUNC_ARG - returned if the list or listSz parameter is NULL.

BUFFER_ERROR - returned if there will be a problem with the list buffer (either it’s

NULL or the size is 0).

MEMORY_ERROR - returned if there was a problem dynamically allocating memory.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

list - a pointer to the buffer. The data from the SSL object will be copied into it.

listSz - the buffer size.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

#ifdef HAVE_ALPN

char* list = NULL;

word16 listSz = 0;

…

err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz);

if(err == SSL_SUCCESS){

/*List of protocols names sent by client */

}

See Also:

wolfSSL_UseALPN

wolfSSL_SetMinVersion

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetMinVersion(WOLFSSL* ssl, int version);

Description:

This function sets the minimum downgrade version allowed. Applicable only when the

connection allows downgrade using (wolfSSLv23_client_method or

wolfSSLv23_server_method).

Return Values:

SSL_SUCCESS - returned if this function and its subroutine executes without error.

BAD_FUNC_ARG - returned if the SSL object is NULL. In the subroutine this error is

thrown if there is not a good version match.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

version - an integer representation of the version to be set as the minimum:

WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or

WOLFSSL_TLSV1_2 = 3.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int version = /*version id (see internal.h enum Misc)*/

…

if(version != SSL_SUCCESS){

/*The minimum version failed to set properly */

} else {

/*You have successfully set the min version */

}

See Also:

SetMinVersionHelper

wolfSSL_CTX_SetMinVersion

wolfSSL_MakeTlsMasterSecret

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_MakeTlsMasterSecret(byte* ms, word32 msLen, const byte* pms,

word32 pmsLen, const byte* cr, const byte* sr, int tls1_2, int hash_type);

Description:

This function copies the values of cr and sr then passes through to PRF (pseudo

random function) and returns that value.

Return Values:

This function returns 0 on success.

BUFFER_E - returned if there will be an error with the size of the buffer.

MEMORY_E - returned if a subroutine failed to allocate dynamic memory.

Parameters:

ms - the master secret held in the Arrays structure.

msLen - the length of the master secret.

pms - the pre-master secret held in the Arrays structure.

pmsLen - the length of the pre-master secret.

cr - the client random.

sr - the server random.

tls1_2 - signifies that the version is at least tls version 1.2.

hash_type - signifies the hash type.

Example:

WOLFSSL* ssl; /*Initialize*/

/*called in MakeTlsMasterSecret and retrieves the necessary information as

follows:*/

int MakeTlsMasterSecret(WOLFSSL* ssl){

int ret;

ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret,

SECRET_LEN,

ssl->arrays->preMasterSecret, ssl->arrays-

>preMasterSz,

ssl->arrays->clientRandom, ssl->arrays->serverRandom,

IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);

…

return ret;

}

See Also:

PRF

doPRF

p_hash

MakeTlsMasterSecret

wolfSSL_SetServerID

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetServerID(WOLFSSL* ssl, const byte* id, int len, int newSession);

Description:

This function associates the client session with the server id. If the newSession flag is

on, an existing session won’t be reused.

Return Values:

SSL_SUCCESS - returned if the function executed without an error.

BAD_FUNC_ARG - returned if the WOLFSSL struct or id parameter is NULL or if len is

not greater than zero.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

id - a constant byte pointer that will be copied to the serverID member of the

WOLFSSL_SESSION structure.

len - an int type representing the length of the session id parameter.

newSession - an int type representing the flag to denote whether to reuse a session or

not.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

const byte id[MAX_SIZE]; /*or dynamically create space*/

int len = 0; /*initialize length*/

int newSession = 0; /*flag to allow*/

…

int ret = wolfSSL_SetServerID(ssl, id, len, newSession);

if(ret){

/*The Id was successfully set*/

}

See Also:

GetSessionClient

wolfSSL_ALPN_GetProtocol

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char** protocol_name, word16* size);

Description:

This function gets the protocol name set by the server.

Return Values:

SSL_SUCCESS - returned on successful execution where no errors were thrown.

SSL_FATAL_ERROR - returned if the extension was not found or if there was no

protocol match with peer. There will also be an error thrown if there is more than one

protocol name accepted.

SSL_ALPN_NOT_FOUND - returned signifying that no protocol match with peer was

found.

BAD_FUNC_ARG - returned if there was a NULL argument passed into the function.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

protocol_name - a pointer to a char that represents the protocol name and will be held

in the ALPN structure.

size - a word16 type that represents the size of the protocol_name.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

...

int err;

char* protocol_name = NULL;

Word16 protocol_nameSz = 0;

err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz);

if(err == SSL_SUCCESS){

/*Sent ALPN protocol*/

}

See Also:

TLSX_ALPN_GetRequest

TLSX_Find

17.2 Certificates and Keys

The functions in this section have to do with loading certificates and keys into wolfSSL.

wolfSSL_CTX_load_verify_buffer

Synopsis:

int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,

long sz, int format);

Description:

This function loads a CA certificate buffer into the WOLFSSL Context. It behaves like

the non-buffered version, only differing in its ability to be called with a buffer as input

instead of a file. The buffer is provided by the in argument of size sz. format specifies

the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More

than one CA certificate may be loaded per buffer as long as the format is in PEM.

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

in - pointer to the CA certificate buffer

sz - size of the input CA certificate buffer, in.

format - format of the buffer certificate, either SSL_FILETYPE_ASN1 or

SSL_FILETYPE_PEM.

Example:

int ret = 0;

int sz = 0;

WOLFSSL_CTX* ctx;

byte certBuff[...];

...

ret = wolfSSL_CTX_load_verify_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*error loading CA certs from buffer*/

}

...

See Also:

wolfSSL_CTX_load_verify_locations

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_CTX_load_verify_locations

Synopsis:

int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file,

const char* path);

Description:

This function loads PEM-formatted CA certificate files into the SSL context

(WOLFSSL_CTX). These certificates will be treated as trusted root certificates and

used to verify certs received from peers during the SSL handshake.

The root certificate file, provided by the file argument, may be a single certificate or a

file containing multiple certificates. If multiple CA certs are included in the same file,

wolfSSL will load them in the same order they are presented in the file. The path

argument is a pointer to the name of a directory that contains certificates of trusted root

CAs. If the value of file is not NULL, path may be specified as NULL if not needed. If

path is specified and NO_WOLFSSL_DIR was not defined when building the library,

wolfSSL will load all CA certificates located in the given directory. This function will

attempt to load all files in the directory and locate any files with the PEM header “-----

BEGIN CERTIFICATE-----”.

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FAILURE will be returned if ctx is NULL, or if both file and path are NULL.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

BAD_PATH_ERROR will be returned if opendir() fails when trying to open path.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

file - pointer to name of the file containing PEM-formatted CA certificates

path - pointer to the name of a directory to load PEM-formatted certificates from.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_load_verify_locations(ctx, “./ca-cert.pem”, 0);

if (ret != SSL_SUCCESS) {

/*error loading CA certs*/

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_file

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_file

wolfSSL_use_certificate_file

wolfSSL_use_PrivateKey_file

wolfSSL_use_certificate_chain_file

wolfSSL_CTX_use_PrivateKey_buffer

Synopsis:

int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX* ctx, const unsigned char*

in, long sz, int format);

Description:

This function loads a private key buffer into the SSL Context. It behaves like the non-

buffered version, only differing in its ability to be called with a buffer as input instead of a

file. The buffer is provided by the in argument of size sz. format specifies the format

type of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the

examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

NO_PASSWORD will be returned if the key file is encrypted but no password is

provided.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

in - the input buffer containing the private key to be loaded.

sz - the size of the input buffer.

format - the format of the private key located in the input buffer (in). Possible values

are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example:

int ret = 0;

int sz = 0;

WOLFSSL_CTX* ctx;

byte keyBuff[...];

...

ret = wolfSSL_CTX_use_PrivateKey_buffer(ctx, keyBuff, sz, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*error loading private key from buffer*/

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_CTX_use_PrivateKey_file

Synopsis:

int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX* ctx, const char* file,

int format);

Description:

This function loads a private key file into the SSL context (WOLFSSL_CTX). The file is

provided by the file argument. The format argument specifies the format type of the file

- SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper

usage.

Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be

returned. If the function call fails, possible causes might include:

- The file is in the wrong format, or the wrong format has been given using the “format”

argument

- The file doesn’t exist, can’t be read, or is corrupted

- An out of memory condition occurs

- Base16 decoding fails on the file

- The key file is encrypted but no password is provided

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_use_PrivateKey_file(ctx, “./server-key.pem”,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*error loading key file*/

}

...

See Also:

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_use_PrivateKey_file

wolfSSL_use_PrivateKey_buffer

wolfSSL_get_privateKey

Synopsis:

WOLFSSL_EVP_PKEY *wolfSSL_get_privatekey(const WOLFSSL *ssl)

Description:

This function gets a pointer to a private-key of the X.509 certificate in the SSL.

Return Values:

If successful the call will return EVP_PKEY of the SSL, otherwise NULL will be returned

when No private key is loaded and getting a private key failed.

Example:

WOLFSSL* ssl;

WOLFSSL_EVP_PKEY* evp_key;

...

evp_key = wolfSSL_get_privatekey(ssl);

...

See Also:

wolfSSL_CTX_new

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_new

wolfSSL_EVP_PKEY_free

wolfSSL_free

wolfSSL_CTX_free

wolfSSL_CTX_use_certificate_buffer

Synopsis:

int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,

long sz, int format);

Description:

This function loads a certificate buffer into the WOLFSSL Context. It behaves like the

non-buffered version, only differing in its ability to be called with a buffer as input instead

of a file. The buffer is provided by the in argument of size sz. format specifies the

format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see

the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

in - the input buffer containing the certificate to be loaded.

sz - the size of the input buffer.

format - the format of the certificate located in the input buffer (in). Possible values are

SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example:

int ret = 0;

int sz = 0;

WOLFSSL_CTX* ctx;

byte certBuff[...];

...

ret = wolfSSL_CTX_use_certificate_buffer(ctx, certBuff, sz,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*error loading certificate from buffer*/

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_CTX_use_certificate_chain_buffer

Synopsis:

int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX* ctx,

const unsigned char* in, long sz);

Description:

This function loads a certificate chain buffer into the WOLFSSL Context. It behaves like

the non-buffered version, only differing in its ability to be called with a buffer as input

instead of a file. The buffer is provided by the in argument of size sz. The buffer must

be in PEM format and start with the subject’s certificate, ending with the root certificate.

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

in - the input buffer containing the PEM-formatted certificate chain to be loaded.

sz - the size of the input buffer.

Example:

int ret = 0;

int sz = 0;

WOLFSSL_CTX* ctx;

byte certChainBuff[...];

...

ret = wolfSSL_CTX_use_certificate_chain_buffer(ctx, certChainBuff, sz);

if (ret != SSL_SUCCESS) {

/*error loading certificate chain from buffer*/

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_CTX_use_certificate_chain_file

Synopsis:

int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX* ctx, const char* file);

Description:

This function loads a chain of certificates into the SSL context (WOLFSSL_CTX). The

file containing the certificate chain is provided by the file argument, and must contain

PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH

(default = 9, defined in internal.h) certificates, plus the subject cert.

Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be

returned. If the function call fails, possible causes might include:

- The file is in the wrong format, or the wrong format has been given using the “format”

argument

- file doesn’t exist, can’t be read, or is corrupted

- an out of memory condition occurs

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()

file - a pointer to the name of the file containing the chain of certificates to be loaded

into the wolfSSL SSL context. Certificates must be in PEM format.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_use_certificate_chain_file(ctx, “./cert-chain.pem”);

if (ret != SSL_SUCCESS) {

/*error loading cert file*/

}

...

See Also:

wolfSSL_CTX_use_certificate_file

wolfSSL_CTX_use_certificate_buffer

wolfSSL_use_certificate_file

wolfSSL_use_certificate_buffer

wolfSSL_CTX_use_certificate_file

Synopsis:

int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX* ctx, const char* file, int format);

Description:

This function loads a certificate file into the SSL context (WOLFSSL_CTX). The file is

provided by the file argument. The format argument specifies the format type of the

file, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples

for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be

returned. If the function call fails, possible causes might include:

- The file is in the wrong format, or the wrong format has been given using the “format”

argument

- file doesn’t exist, can’t be read, or is corrupted

- an out of memory condition occurs

- Base16 decoding fails on the file

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()

file - a pointer to the name of the file containing the certificate to be loaded into the

wolfSSL SSL context.

format - format of the certificates pointed to by file. Possible options are

SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_use_certificate_file(ctx, “./client-cert.pem”,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*error loading cert file*/

}

...

See Also:

wolfSSL_CTX_use_certificate_buffer

wolfSSL_use_certificate_file

wolfSSL_use_certificate_buffer

wolfSSL_SetTmpDH

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetTmpDH(WOLFSSL* ssl, unsigned char* p, int pSz, unsigned char* g,

int gSz);

Description:

Server Diffie-Hellman Ephemeral parameters setting. This function sets up the group

parameters to be used if the server negotiates a cipher suite that uses DHE.

Return Values:

If successful the call will return SSL_SUCCESS.

MEMORY_ERROR will be returned if a memory error was encountered.

SIDE_ERROR will be returned if this function is called on an SSL client instead of an

SSL server.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

p - Diffie-Hellman prime number parameter.

pSz - size of p.

g - Diffie-Hellman “generator” parameter.

gSz - size of g.

Example:

WOLFSSL* ssl;

static unsigned char p[] = {...};

static unsigned char g[] = {...};

...

wolfSSL_SetTmpDH(ssl, p, sizeof(p), g, sizeof(g));

See Also:

SSL_accept

wolfSSL_use_PrivateKey

Synopsis:

#include <wolfssl/ssl.h>

SSL_use_PrivateKey ->

int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey);

Description:

This is used to set the private key for the WOLFSSL structure.

Return Values:

SSL_SUCCESS: On successful setting argument.

SSL_FAILURE: If an NULL ssl passed in.

All error cases will be negative values.

Parameters:

ssl - WOLFSSL structure to set argument in.

pkey - private key to use.

Example:

WOLFSSL* ssl;

WOLFSSL_EVP_PKEY* pkey;

int ret;

// create ssl object and set up private key

ret = wolfSSL_use_PrivateKey(ssl, pkey);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free, wolfSSL_use_PrivateKey

wolfSSL_use_PrivateKey_ASN1

Synopsis:

#include <wolfssl/ssl.h>

SSL_use_PrivateKey_ASN1 ->

int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl, unsigned char* der, long

derSz);

Description:

This is used to set the private key for the WOLFSSL structure. A DER formatted key

buffer is expected

Return Values:

SSL_SUCCESS: On successful setting parsing and setting the private key.

SSL_FAILURE: If an NULL ssl passed in.

All error cases will be negative values.

Parameters:

pri - type of private key.

ssl - WOLFSSL structure to set argument in.

der -buffer holding DER key.

derSz - size of der buffer.

Example:

WOLFSSL* ssl;

unsigned char* pkey;

long pkeySz;

int ret;

// create ssl object and set up private key

ret = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free, wolfSSL_use_PrivateKey

wolfSSL_use_RSAPrivateKey_ASN1

Synopsis:

#include <wolfssl/ssl.h>

SSL_use_RSAPrivateKey_ASN1 ->

int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der, long

derSz);

Description:

This is used to set the private key for the WOLFSSL structure. A DER formatted RSA

key buffer is expected

Return Values:

SSL_SUCCESS: On successful setting parsing and setting the private key.

SSL_FAILURE: If an NULL ssl passed in.

All error cases will be negative values.

Parameters:

ssl - WOLFSSL structure to set argument in.

der -buffer holding DER key.

derSz - size of der buffer.

Example:

WOLFSSL* ssl;

unsigned char* pkey;

long pkeySz;

int ret;

// create ssl object and set up RSA private key

ret = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free, wolfSSL_use_PrivateKey

wolfSSL_use_PrivateKey_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_use_PrivateKey_buffer(WOLFSSL* ssl, const unsigned char* in,

long sz, int format);

Description:

This function loads a private key buffer into the WOLFSSL object. It behaves like the

non-buffered version, only differing in its ability to be called with a buffer as input instead

of a file. The buffer is provided by the in argument of size sz. format specifies the

format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see

the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

NO_PASSWORD will be returned if the key file is encrypted but no password is

provided.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

in - buffer containing private key to load.

sz - size of the private key located in buffer.

format - format of the private key to be loaded. Possible values are

SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example:

int buffSz;

int ret;

byte keyBuff[...];

WOLFSSL* ssl = 0;

...

ret = wolfSSL_use_PrivateKey_buffer(ssl, keyBuff, buffSz, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*failed to load private key from buffer*/

}

See Also:

wolfSSL_use_PrivateKey

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_use_certificate_buffer(WOLFSSL* ssl, const unsigned char* in,

long sz, int format);

Description:

This function loads a certificate buffer into the WOLFSSL object. It behaves like the

non-buffered version, only differing in its ability to be called with a buffer as input instead

of a file. The buffer is provided by the in argument of size sz. format specifies the

format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see

the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

in - buffer containing certificate to load.

sz - size of the certificate located in buffer.

format - format of the certificate to be loaded. Possible values are

SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example:

int buffSz;

int ret;

byte certBuff[...];

WOLFSSL* ssl = 0;

...

ret = wolfSSL_use_certificate_buffer(ssl, certBuff, buffSz,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/*failed to load certificate from buffer*/

}

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_use_certificate_chain_buffer(WOLFSSL* ssl, const unsigned char* in,

long sz);

Description:

This function loads a certificate chain buffer into the WOLFSSL object. It behaves like

the non-buffered version, only differing in its ability to be called with a buffer as input

instead of a file. The buffer is provided by the in argument of size sz. The buffer must

be in PEM format and start with the subject’s certificate, ending with the root certificate.

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

in - buffer containing certificate to load.

sz - size of the certificate located in buffer.

Example:

int buffSz;

int ret;

byte certChainBuff[...];

WOLFSSL* ssl = 0;

...

ret = wolfSSL_use_certificate_chain_buffer(ssl, certChainBuff, buffSz);

if (ret != SSL_SUCCESS) {

/*failed to load certificate chain from buffer*/

}

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_CTX_der_load_verify_locations

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX* ctx, const char* file,

int format);

Description:

This function is similar to wolfSSL_CTX_load_verify_locations, but allows the loading of

DER-formatted CA files into the SSL context (WOLFSSL_CTX). It may still be used to

load PEM-formatted CA files as well. These certificates will be treated as trusted root

certificates and used to verify certs received from peers during the SSL handshake.

The root certificate file, provided by the file argument, may be a single certificate or a

file containing multiple certificates. If multiple CA certs are included in the same file,

wolfSSL will load them in the same order they are presented in the file. The format

argument specifies the format which the certificates are in either, SSL_FILETYPE_PEM

or SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations, this

function does not allow the loading of CA certificates from a given directory path.

Note that this function is only available when the wolfSSL library was compiled with

WOLFSSL_DER_LOAD defined.

Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be

returned upon failure.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()

file - a pointer to the name of the file containing the CA certificates to be loaded into the

wolfSSL SSL context, with format as specified by format.

format - the encoding type of the certificates specified by file. Possible values include

SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_der_load_verify_locations(ctx, “./ca-cert.der”,

SSL_FILETYPE_ASN1);

if (ret != SSL_SUCCESS) {

/*error loading CA certs*/

}

...

See Also:

wolfSSL_CTX_load_verify_locations

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_NTRUPrivateKey_file

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_use_NTRUPrivateKey_file(WOLFSSL_CTX* ctx, const char* file);

Description:

This function loads an NTRU private key file into the WOLFSSL Context. It behaves

like the normal version, only differing in its ability to accept an NTRU raw key file. This

function is needed since the format of the file is different than the normal key file (buffer)

functions. Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

NO_PASSWORD will be returned if the key file is encrypted but no password is

provided.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()

file - a pointer to the name of the file containing the NTRU private key to be loaded into

the wolfSSL SSL context.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_use_NTRUPrivateKey_file(ctx, “./ntru-key.raw”);

if (ret != SSL_SUCCESS) {

/*error loading NTRU private key*/

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_KeepArrays

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_KeepArrays(WOLFSSL* ssl);

Description:

Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. Calling

this function before the handshake begins will prevent wolfSSL from freeing temporary

arrays. Temporary arrays may be needed for things such as wolfSSL_get_keys() or

PSK hints.

When the user is done with temporary arrays, either wolfSSL_FreeArrays() may be

called to free the resources immediately, or alternatively the resources will be freed

when the associated SSL object is freed.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl;

...

wolfSSL_KeepArrays(ssl);

See Also:

wolfSSL_FreeArrays

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_FreeArrays(WOLFSSL* ssl);

Description:

Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. If

wolfSSL_KeepArrays() has been called before the handshake, wolfSSL will not free

temporary arrays. This function explicitly frees temporary arrays and should be called

when the user is done with temporary arrays and does not want to wait for the SSL

object to be freed to free these resources.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl;

...

wolfSSL_FreeArrays(ssl);

See Also:

wolfSSL_KeepArrays

wolfSSL_UnloadCertsKeys

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UnloadCertsKeys(WOLFSSL* ssl);

Description:

This function unloads any certificates or keys that SSL owns.

Return Values:

SSL_SUCCESS - returned if the function executed successfully.

BAD_FUNC_ARG - returned if the WOLFSSL object is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

…

int unloadKeys = wolfSSL_UnloadCertsKeys(ssl);

if(unloadKeys != SSL_SUCCESS){

/*Failure case. */

}

See Also:

wolfSSL_CTX_UnloadCAs

wolfSSL_CTX_get_cert_cache_memsize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX* ctx);

Description:

Returns the size the certificate cache save buffer needs to be.

Return Values:

If the funciton is successful an INTEGER value is returned representing the memory

size.

BAD_FUNC_ARG is returned if the WOLFSSL_CTX struct is NULL.

BAD_MUTEX_E - returned if there was a mutex lock error.

Parameters:

ctx - a pointer to a wolfSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol*/);

…

int certCacheSize = wolfSSL_CTX_get_cert_cache_memsize(ctx);

if(certCacheSize != BAD_FUNC_ARG || certCacheSize != BAD_MUTEX_E){

/*Successfully retrieved the memory size. */

}

See Also:

CM_GetCertCacheMemSize

wolfSSL_X509_get_signature_type

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_X509_get_signature_type(WOLFSSL_X509* x509);

Description:

This function returns the value stored in the sigOID member of the WOLFSSL_X509

structure.

Return Values:

0 - returned if the WOLFSSL_X509 structure is NULL.

An Integer value is returned which was retrieved from the x509 object.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

…

int x509SigType = wolfSSL_X509_get_signature_type(x509);

if(x509SigType != EXPECTED){

/*Deal with an unexpected value*/

}

See Also:

wolfSSL_X509_get_signature

wolfSSL_X509_version

wolfSSL_X509_get_der

wolfSSL_X509_get_serial_number

wolfSSL_X509_notBefore

wolfSSL_X509_notAfter

wolfSSL_X509_free

wolfSSL_X509_get_next_altname

Synopsis:

#include <wolfssl/ssl.h>

char* wolfSSL_X509_get_next_altname(WOLFSSL_X509* cert);

Description:

This function returns the next, if any, altname from the peer certificate.

Return Values:

NULL if there is not a next altname.

cert->altNamesNext->name from the WOLFSSL_X509 structure that is a string value

from the altName list is returned if it exists.

Parameters:

cert - a pointer to the wolfSSL_X509 structure.

Example:

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

…

int x509NextAltName = wolfSSL_X509_get_next_altname(x509);

if(x509NextAltName == NULL){

/*There isn’t another alt name*/

}

See Also:

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_subjectCN

Synopsis:

#include <wolfssl/ssl.h>

char* wolfSSL_X509_get_subjectCN(WOLFSSL_X509* x509);

Description:

Returns the common name of the subject from the certificate.

Return Values:

NULL - returned if the x509 structure is null

A string representation of the subject’s common name is returned if the function

executes successfully.

Parameters:

x509 - a pointer to a WOLFSSL_X509 structure containing certificate information.

Example:

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

…

int x509Cn = wolfSSL_X509_get_subjectCN(x509);

if(x509Cn == NULL){

/*Deal with NULL case*/

} else {

/*x509Cn contains the common name*/

}

See Also:

wolfSSL_X509_Name_get_entry

wolfSSL_X509_get_next_altname

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_der

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_X509_get_der(WOLFSSL_X509* x509, int* outSz);

Description:

This function gets the DER encoded certificate in the WOLFSSL_X509 struct.

Return Values:

This function returns the DerBuffer structure’s buffer member, which is of type byte.

NULL - returned if the x509 or outSz parameter is NULL.

Parameters:

x509 - a pointer to a WOLFSSL_X509 structure containing certificate information.

outSz - length of the derBuffer member of the WOLFSSL_X509 struct.

Example:

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

int* outSz; /*initialize*/

…

byte* x509Der = wolfSSL_X509_get_der(x509, outSz);

if(x509Der == NULL){

/*Failure case one of the parameters was NULL */

}

See Also:

wolfSSL_X509_version

wolfSSL_X509_Name_get_entry

wolfSSL_X509_get_next_altname

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_hw_type

Synopsis:

#include <wolfssl/ssl.h>

byte* wolfSSL_X509_get_hw_type(WOLFSSL_X509* x509, byte* in, int* inOutSz);

Description:

The function copies the hwType member of the WOLFSSL_X509 structure to the

buffer.

Return Values:

The function returns a byte type of the data previously held in the hwType member of

the WOLFSSL_X509 structure.

NULL - returned if inOutSz is NULL.

Parameters:

x509 - a pointer to a WOLFSSL_X509 structure containing certificate information.

in - pointer to type byte that represents the buffer.

inOutSz - pointer to type int that represents the size of the buffer.

Example:

WOLFSSL_X509* x509; /*X509 certificate*/

byte* in; /*initialize the buffer*/

int* inOutSz; /*holds the size of the buffer*/

...

byte* hwType = wolfSSL_X509_get_hw_type(x509, in, inOutSz);

if(hwType == NULL){

/*Failure case function returned NULL. */

}

See Also:

wolfSSL_X509_get_hw_serial_number

wolfSSL_X509_get_device_type

wolfSSL_X509_d2i_fp

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509* wolfSSL_X509_d2i_fp(WOLFSSL_X509** x509, XFILE file);

Description:

If NO_STDIO_FILESYSTEM is defined this function will allocate heap memory, initialize

a WOLFSSL_X509 structure and return a pointer to it.

Return Values:

WOLFSSL_X509 structure pointer is returned if the function executes successfully.

NULL - if the call to XFTELL macro returns a negative value.

Parameters:

x509 - a pointer to a WOLFSSL_X509 pointer.

file - a defined type that is a pointer to a FILE.

Example:

WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

WOLFSSL_X509** x509 = x509a;

XFILE file; (mapped to struct fs_file*)

...

WOLFSSL_X509* newX509 = wolfSSL_X509_d2i_fp(x509, file);

if(newX509 == NULL){

/*The function returned NULL */

}

See Also:

wolfSSL_X509_d2i

XFTELL

XREWIND

XFSEEK

wolfSSL_SetCertCbCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetCertCbCtx(WOLFSSL* ssl, void* ctx);

Description:

This function stores user CTX object information for verify callback.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

ctx - a void pointer that is set to WOLFSSL structure’s verifyCbCtx member’s value.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

(void*)ctx;

…

if(ssl != NULL){

wolfSSL_SetCertCbCtx(ssl, ctx);

} else {

/*Error case, the SSL is not initialized properly. */

}

See Also:

wolfSSL_CTX_save_cert_cache

wolfSSL_CTX_restore_cert_cache

wolfSSL_CTX_set_verify

wolfSSL_CertPemToDer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertPemToDer(const unsigned char* pem, int pemSz,

Unsigned char* buff, int buffSz, int type);

Description:

This function converts a PEM formatted certificate to DER format. Calls OpenSSL

function PemToDer.

Return Values:

Returns the bytes written to the buffer.

Parameters:

pem - pointer PEM formatted certificate.

pemSz - size of the certificate.

buff - buffer to be copied to DER format.

buffSz - size of the buffer.

type - Certificate file type found in asn_public.h enum CertType.

Example:

const unsigned char* pem;

int pemSz;

unsigned char buff[BUFSIZE];

int buffSz = sizeof(buff)/sizeof(char);

int type;

...

if(wolfSSL_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) {

/*There were bytes written to buffer*/

}

See Also:

PemToDer (OpenSSL)

wolfSSL_X509_notAfter

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_X509_notAfter(wolfSSL_X509* x509);

Description:

This function checks to see if x509 is NULL and if it’s not, it returns the notAfter member

of the x509 struct.

Return Values:

The function returns a constant byte pointer to the notAfter member of the x509 struct.

NULL - returned if the x509 object is NULL.

Parameters:

x509 - a pointer to the WOLFSSL_X509 struct.

Example:

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509) ;

...

byte* notAfter = wolfSSL_X509_notAfter(x509);

if(notAfter == NULL){

/*Failure case, the x509 object is null. */

}

See Also:

wolfssl/openssl/ssl.h

cyassl/ssl.h

wolfSSL_get_peer_certificate

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl);

Description:

This function gets the peer’s certificate.

Return Values:

Returns a pointer to the peerCert member of the WOLFSSL_X509 structure if it exists.

0 - returned if the peer certificate issuer size is not defined.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

WOLFSSL_X509* peerCert = wolfSSL_get_peer_certificate(ssl);

if(peerCert){

/*You have a pointer peerCert to the peer certification*/

}

See Also:

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_cert_chain

Synopsis:

#include <wolfssl/ssl.h>

STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFSSL* ssl);

Description:

This function gets the peer’s certificate chain.

Return Values:

Returns a pointer to the peer’s Certificate stack.

NULL - returned if no peer certificate.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

wolfSSL_connect(ssl);

STACK_OF(WOLFSSL_X509)* chain = wolfSSL_get_peer_cert_chain(ssl);

ifchain){

/*You have a pointer to the peer certificate chain*/

}

See Also:

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_isCA

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_X509_get_isCA(WOLFSSL_X509* x509);

Description:

Checks the isCa member of the WOLFSSL_X509 structure and returns the value.

Return Values:

The value in the isCA member of the WOLFSSL_X509 structure is returned.

0 - returned if there is not a valid x509 structure passed in.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl;

…

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

if(wolfSSL_X509_get_isCA(ssl)){

/*This is the CA*/

}else {

/*Failure case*/

}

See Also:

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_isCA

wolfSSL_CTX_save_cert_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX* ctx, const char* fname);

Description:

This function writes the cert cache from memory to file.

Return Values:

SSL_SUCCESS - if CM_SaveCertCache exits normally.

BAD_FUNC_ARG - is returned if either of the arguments are NULL.

SSL_BAD_FILE - if the cert cache save file could not be opened.

BAD_MUTEX_E - if the lock mutex failed.

MEMORY_E - the allocation of memory failed.

FWRITE_ERROR - Certificate cache file write failed.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, holding the certificate information.

fname - the cert cache buffer.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol def*/);

const char* fname;

...

if(wolfSSL_CTX_save_cert_cache(ctx, fname)){

/*file was written. */

}

See Also:

CM_SaveCertCache

DoMemSaveCertCache

wolfSSL_CTX_restore_cert_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX* ctx,

const char* fname) ;

Description:

This function persistes certificate cache from a file.

Return Values:

SSL_SUCCESS - returned if the function, CM_RestoreCertCache, executes normally.

SSL_BAD_FILE - returned if XFOPEN returns XBADFILE. The file is corrupted.

MEMORY_E - returned if the allocated memory for the temp buffer fails.

BAD_FUNC_ARG - returned if fname or ctx have a NULL value.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, holding the certificate information.

fname - the cert cache buffer.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

const char* fname = /*path to file*/;

...

if(wolfSSL_CTX_restore_cert_cache(ctx, fname)){

/*check to see if the execution was successful */

}

See Also:

CM_RestoreCertCache

XFOPEN

wolfSSL_get_chain_X509

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509*

wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN* chain, int idx);

Description:

This function gets the peer’s wolfSSL_X509_certificate at index (idx) from the chain of

certificates.

Return Values:

The function returns a pointer to a WOLFSSL_X509 structure.

Parameters:

chain - a pointer to the WOLFSSL_X509_CHAIN used for no dynamic memory

SESSION_CACHE.

idx - the index of the WOLFSSL_X509 certificate.

Example:

WOLFSSL_X509_CHAIN* chain = &session->chain;

int idx = /*set idx*/;

…

WOLFSSL_X509_CHAIN ptr;

prt = wolfSSL_get_chain_X509(chain, idx);

if(ptr != NULL){

/*ptr contains the cert at the index specified*/

} else {

/*ptr is NULL*/

}

See Also:

InitDecodedCert

ParseCertRelative

CopyDecodedToX509

wolfSSL_wolfSSL_X509_notBefore

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509);

Description:

The function checks to see if x509 is NULL and if it’s not, it returns the notBefore

member of the x509 struct.

Return Values:

This function returns a constant byte pointer to the x509’s member notAfter.

NULL - the function returns NULL if the x509 structure is NULL.

Parameters:

x509 - a pointer to the WOLFSSL_X509 struct.

Example:

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509) ;

…

byte* notAfter = wolfSSL_X509_notAfter(x509);

if(notAfter == NULL){

/*The x509 object was NULL */

}

See Also:

wolfSSL_X509_notAfter

wolfSSL_X509_get_signature

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_X509_get_signature(WOLFSSL_X509* x509,

unsigned char* buf, int bufSz);

Description:

Gets the X509 signature and stores it in the buffer.

Return Values:

SSL_SUCCESS - returned if the function successfully executes. The signature is

loaded into the buffer.

SSL_FATAL_ERRROR - returns if the x509 struct or the bufSz member is NULL. There

is also a check for the length member of the sig structure (sig is a member of x509).

Parameters:

x509 - pointer to a WOLFSSL_X509 structure..

buf - a char pointer to the buffer.

bufSz - an integer pointer to the size of the buffer.

Example:

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

unsigned char* buf; /*Initialize*/

int* bufSz = sizeof(buf)/sizeof(unsigned char);

...

if(wolfSSL_X509_get_signature(x509, buf, bufSz) != SSL_SUCCESS){

/*The function did not execute successfully. */

} else{

/*The buffer was written to correctly. */

}

See Also:

wolfSSL_X509_get_serial_number

wolfSSL_X509_get_signature_type

wolfSSL_X509_get_device_type

Synopsis:

#include <wolfssl/ssl.h>

byte* wolfSSL_X509_get_device_type(WOLFSSL_X509* x509, byte* in,

int* inOutSz);

Description:

This function copies the device type from the x509 structure to the buffer.

Return Values:

Returns a byte pointer holding the device type from the x509 structure.

NULL - returned if the buffer size is NULL.

Parameters:

x509 - pointer to a WOLFSSL_X509 structure, created with WOLFSSL_X509_new().

in - a pointer to a byte type that will hold the device type (the buffer).

inOutSz - the minimum of either the parameter inOutSz or the deviceTypeSz member

of the x509 structure.

Example:

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,

DYNAMIC_TYPE_X509);

byte* in;

int* inOutSz;

...

byte* deviceType = wolfSSL_X509_get_device_type(x509, in, inOutSz);

if(!deviceType){

/*Failure case, NULL was returned. */

}

See Also:

wolfSSL_X509_get_hw_type

wolfSSL_X509_get_hw_serial_number

wolfSSL_X509_d2i

wolfSSL_CTX_memsave_cert_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX* ctx, void* mem,

int sz, int* used);

Description:

This function persists the certificate cache to memory.

Return Values:

SSL_SUCCESS - returned on successful execution of the function. No errors were

thrown.

BAD_MUTEX_E - mutex error where the WOLFSSL_CERT_MANAGER member

caLock was not 0 (zero).

BAD_FUNC_ARG - returned if ctx, mem, or used is NULL or if sz is less than or equal

to 0 (zero).

BUFFER_E - output buffer mem was too small.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

mem - a void pointer to the destination (output buffer).

sz - the size of the output buffer.

used - a pointer to size of the cert cache header.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol*/);

void* mem; /*initialize */

int sz; /*sizeof mem*/

int* used; /*cert cache header*/

...

if(wolfSSL_CTX_memsave_cert_cache(ctx, mem, sz, used) != SSL_SUCCESS){

/*The function returned with an error*/

}

See Also:

DoMemSaveCertCache

GetCertCacheMemSize

CM_MemRestoreCertCache

CM_GetCertCacheMemSize

wolfSSL_KeyPemToDer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_KeyPemToDer(const unsigned char* pem, int pemSz,

unsigned char* buff, int buffSz, const char* pass);

Description:

Converts a key in PEM format to DER format.

Return Values:

The function returns the number of bytes written to the buffer on successful execution.

< 0 returned indicating an error.

Parameters:

pem - a pointer to the PEM encoded certificate.

pemSz - the size of the PEM buffer (pem).

buff - a pointer to the copy of the buffer member of the DerBuffer struct.

buffSz - size of the buffer space allocated in the DerBuffer struct.

pass - password passed into the function.

Example:

byte* loadBuf; /*Initialize */

long fileSz = 0;

byte* bufSz; /*Initialize */

static int LoadKeyFile(byte** keyBuf, word32* keyBufSz, const char* keyFile,

int typeKey, const char* pasword);

…

bufSz = wolfSSL_KeyPemToDer(loadBuf, (int)fileSz, saveBuf,

(int)fileSz, password);

if(saveBufSz > 0){

/*Bytes were written to the buffer. */

}

See Also:

PemToDer

wolfssl_decrypt_buffer_key

wolfSSL_X509_load_certificate_file

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509* wolfSSL_X509_load_certificate_file(const char* fname,

int format);

Description:

The function loads the x509 certificate into memory.

Return Values:

A successful execution returns pointer to a WOLFSSL_X509 structure.

NULL - returned if the certificate was not able to be written.

Parameters:

fname - the certificate file to be loaded.

format - the format of the certificate.

Example:

#define cliCert “certs/client-cert.pem”

…

X509* x509;

…

x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM);

AssertNotNull(x509);

See Also:

InitDecodedCert

PemToDer

wolfSSL_get_certificate

AssertNotNull

wolfSSL_X509_get_issuer_name

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509_NAME* wolfSSL_X509_get_issuer_name(WOLFSSL_X509* cert);

Description:

This function returns the name of the certificate issuer.

Return Values:

A pointer to the WOLFSSL_X509 struct’s issuer member is returned.

NULL - if the cert passed in is NULL.

Parameters:

cert - a pointer to a WOLFSSL_X509 structure.

Example:

WOLFSSL_X509* x509;

WOLFSSL_X509_NAME issuer;

...

issuer = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);

if(!issuer){

/*NULL was returned*/

} else {

/*issuer hods the name of the certificate issuer. */

}

See Also:

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_certificate

wolfSSL_X509_NAME_oneline

Synopsis:

#include <wolfssl/ssl.h>

char* wolfSSL_X509_NAME_oneline(WOLFSSL_X509* name, char* in, int sz);

Description:

This function copies the name of the x509 into a buffer.

Return Values:

A char pointer to the buffer with the WOLFSSL_X509_NAME structures name

member’s data is returned if the function executed normally.

Parameters:

name - a pointer to a WOLFSSL_X509 structure.

in - a buffer to hold the name copied from the WOLFSSL_X509_NAME structure.

sz - the maximum size of the buffer.

Example:

WOLFSSL_X509 x509; /*Initialize */

char* name;

...

name = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);

if(name <= 0){

/*There’s nothing in the buffer. */

}

See Also:

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_certificate

wolfSSL_X509_version

wolfSSL_X509_get_hw_serial_number

Synopsis:

#include <wolfssl/ssl.h>

byte* wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509 x509, byte* in,

int* inOutSz);

Description:

This function returns the hwSerialNum member of the x509 object.

Return Values:

The function returns a byte pointer to the in buffer that will contain the serial number

loaded from the x509 object.

Parameters:

x509 - pointer to a WOLFSSL_X509 structure containing certificate information.

in - a pointer to the buffer that will be copied to.

inOutSz - a pointer to the size of the buffer.

Example:

char* serial;

byte* in; /*Initialize*/

int* inOutSz; /*Initialize to max size of buffer*/

WOLFSSL_X509 x509;

...

serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz);

if(serial == NULL || serial <= 0){

/*Failure case */

}

See Also:

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_certificate

wolfSSL_X509_version

wolfSSL_X509_get_subject_name

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509_NAME* wolfSSL_X509_get_subject_name(WOLFSSL_X509* cert);

Description:

This function returns the subject member of the WOLFSSL_X509 structure.

Return Values:

A pointer to the WOLFSSL_X509_NAME structure. The pointer may be NULL if the

WOLFSSL_X509 struct is NULL or if the subject member of the structure is NULL.

Parameters:

cert - a pointer to a WOLFSSL_X509 structure.

Example:

WOLFSSL_X509* cert; /* Will be initialized */

WOLFSSL_X509_NAME name;

…

name = wolfSSL_X509_get_subject_name(cert);

if(name == NULL){

/*Deal with the NULL case */

}

See Also:

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_certificate

wolfSSL_X509_version

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_X509_version(WOLFSSL_X509* x509);

Description:

This function retrieves the version of the X509 certificate.

Return Values:

0 - returned if the x509 structure is NULL.

The version stored in the x509 structure will be returned.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_X509* x509; /*Initialize */

int version;

...

version = wolfSSL_X509_version(x509);

if(!version){

/*The function returned 0, failure case. */

}

See Also:

wolfSSL_X509_get_subject_name

wolfSSL_X509_get_issuer_name

wolfSSL_X509_get_isCA

wolfSSL_get_peer_certificate

wolfSSL_DeriveTlsKeys

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_DeriveTlsKeys(byte* key_data, word32 keyLen, const byte* ms,

word32 msLen, const byte* sr, const byte* cr,

int tls1_2, int hash_type);

Description:

An external facing wrapper to derive TLS Keys.

Return Values:

0 - returned on success.

BUFFER_E - returned if the sum of labLen and seedLen (computes total size) exceeds

the maximum size.

MEMORY_E - returned if the allocation of memory failed.

Parameters:

key_data - a byte pointer that is allocateded in DeriveTlsKeys and passed through to

PRF to hold the final hash.

keyLen - a word32 type that is derived in DeriveTlsKeys from the WOLFSSL structure’s

specs member.

ms - a constant pointer type holding the master secret held in the arrays structure

within the WOLFSSL structure.

msLen - a word32 type that holds the length of the master secret in an enumerated

define, SECRET_LEN.

sr - a constant byte pointer to the serverRandom member of the arrays structure within

the WOLFSSL structure.

cr - a constant byte pointer to the clientRandom member of the arrays structure within

the WOLFSSL structure.

tls1_2 - an integer type returned from IsAtLeastTLSv1_2().

hash_type - an integer type held in the WOLFSSL structure.

Example:

int DeriveTlsKeys(WOLFSSL* ssl){

int ret;

…

ret = wolfSSL_DeriveTlsKeys(key_data, length, ssl->arrays->masterSecret,

SECRET_LEN, ssl->arrays->clientRandom,

IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);

…

}

See Also:

PRF

doPRF

DeriveTlsKeys

IsAtLeastTLSv1_2

wolfSSL_get_psk_identity

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_get_psk_identity(const WOLFSSL* ssl);

Description:

The function returns a constant pointer to the client_identity member of the Arrays

structure.

Return Values:

The string value of the client_identity member of the Arrays structure.

NULL - if the WOLFSSL structure is NULL or if the Arrays member of the WOLFSSL

structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

const char* pskID;

...

pskID = wolfSSL_get_psk_identity(ssl);

if(pskID == NULL){

/*There is not a value in pskID*/

}

See Also:

wolfSSL_get_psk_identity_hint

wolfSSL_use_psk_identity_hint

wolfSSL_SetMinEccKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetMinEccKey_Sz(WOLFSSL* ssl, short keySz);

Description:

Sets the value of the minEccKeySz member of the options structure. The options

struct is a member of the WOLFSSL structure and is accessed through the ssl

parameter.

Return Values:

SSL_SUCCESS - if the function successfully set the minEccKeySz member of the

options structure.

BAD_FUNC_ARG - if the WOLFSSL_CTX structure is NULL or if the key size (keySz)

is less than 0 (zero) or not divisible by 8.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

keySz - value used to set the minimum ECC key size. Sets value in the options

structure.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx); /*New session */

short keySz = /*min key size allowable*/;

...

if(wolfSSL_SetMinEccKey_Sz(ssl, keySz) != SSL_SUCCESS){

/*Failure case. */

}

See Also:

wolfSSL_CTX_SetMinEccKey_Sz

wolfSSL_CTX_SetMinRsaKey_Sz

wolfSSL_SetMinRsaKey_Sz

wolfSSL_UseClientQSHKeys

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseClientQSHKeys(WOLFSSL* ssl, unsigned char flag);

Description:

If the flag is 1 keys will be sent in hello. If flag is 0 then the keys will not be sent during

hello.

Return Values:

0 - on success.

BAD_FUNC_ARG - if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

flag - an unsigned char input to determine if the keys will be sent during hello.

Example:

WOLFSSL* ssl;

unsigned char flag = 1; /*send keys*/

...

if(!wolfSSL_UseClientQSHKeys(ssl, flag)){

/*The keys will be sent during hello. */

}

See Also:

wolfSSL_UseALPN

wolfSSL_UseSupportedQSH

wolfSSL_isQSH

wolfSSL_CTX_SetMinDhKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX* ctx, word16 keySz);

Description:

This function sets the minimum size of the Diffie Hellman key size by accessing the

minDhKeySz member in the WOLFSSL_CTX structure.

Return Values:

SSL_SUCCESS - returned if the function completes successfully.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX struct is NULL or if the keySz is

greater than 16,000 or not divisible by 8.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

keySz - a word16 type used to set the minimum DH key size. The WOLFSSL_CTX

struct holds this information in the minDhKeySz member.

Example:

public static int CTX_SetMinDhKey_Sz(IntPtr ctx, short minDhKey){

…

return wolfSSL_CTX_SetMinDhKey_Sz(local_ctx, minDhKey);

See Also:

wolfSSL_SetMinDhKey_Sz

CTX_SetMinDhKey_Sz

wolfSSL_GetDhKey_Sz

wolfSSL_CTX_SetTMpDH_file

wolfSSL_CTX_SetTmpDH_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX* ctx, const unsigned char* buf,

long sz, int format);

Description:

A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper

Return Values:

0 - returned for a successful execution.

BAD_FUNC_ARG - returned if the ctx or buf parameters are NULL.

MEMORY_E - if there is a memory allocation error.

SSL_BAD_FILETYPE - returned if format is not correct.

Parameters:

ctx - a pointer to a WOLFSSL structure, created using wolfSSL_CTX_new().

buf - a pointer to a constant unsigned char type that is allocated as the buffer and

passed through to wolfSSL_SetTmpDH_buffer_wrapper.

sz - a long integer type that is derived from the fname parameter in

wolfSSL_SetTmpDH_file_wrapper().

format - an integer type passed through from wolfSSL_SetTmpDH_file_wrapper().

Example:

static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,

Const char* fname, int format);

#ifdef WOLFSSL_SMALL_STACK

byte staticBuffer[1]; /*force heap usage*/

#else

byte* staticBuffer; /*Initialize */

long sz = 0;

…

if(ssl){

ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);

} else {

ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format);

}

See Also:

wolfSSL_SetTmpDH_buffer_wrapper

wolfSSL_SetTMpDH_buffer

wolfSSL_SetTmpDH_file_wrapper

wolfSSL_CTX_SetTmpDH_file

wolfSSL_GetIVSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetIVSize(WOLFSSL* ssl);

Description:

Returns the iv_size member of the specs structure held in the WOLFSSL struct.

Return Values:

Returns the value held in ssl->specs.iv_size.

BAD_FUNC_ARG - returned if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int ivSize;

...

ivSize = wolfSSL_GetIVSize(ssl);

if(ivSize > 0){

/*ivSize holds the specs.iv_size value. */

}

See Also:

wolfSSL_GetKeySize

wolfSSL_GetClientWriteIV

wolfSSL_GetServerWriteIV

wolfSSL_GetDhKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetDhKey_Sz(WOLFSSL* ssl);

Description:

Returns the value of dhKeySz that is a member of the options structure. This value

represents the Diffie-Hellman key size in bytes.

Return Values:

Returns the value held in ssl->options.dhKeySz which is an integer value.

BAD_FUNC_ARG - returns if the WOLFSSL struct is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int dhKeySz;

...

dhKeySz = wolfSSL_GetDhKey_Sz(ssl);

if(dhKeySz == BAD_FUNC_ARG || dhKeySz <= 0){

/*Failure case */

} else {

/*dhKeySz holds the size of the key. */

}

See Also:

wolfSSL_SetMinDhKey_sz

wolfSSL_CTX_SetMinDhKey_Sz

wolfSSL_CTX_SetTmpDH

wolfSSL_SetTmpDH

wolfSSL_CTX_SetTmpDH_file

wolfSSL_SetTmpDH_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetTmpDH_buffer(WOLFSSL* ssl, const unsigned char* buf,

long sz, int format);

Description:

The function calls the wolfSSL_SetTMpDH_buffer_wrapper, which is a wrapper for

Diffie-Hellman parameters.

Return Values:

SSL_SUCCESS - on successful execution.

SSL_BAD_FILETYPE - if the file type is not PEM and is not ASN.1. It will also be

returned if the wc_DhParamsLoad does not return normally.

SSL_NO_PEM_HEADER - returns from PemToDer if there is not a PEM header.

SSL_BAD_FILE - returned if there is a file error in PemToDer.

SSL_FATAL_ERROR - returned from PemToDer if there was a copy error.

MEMORY_E - if there was a memory allocation error.

BAD_FUNC_ARG - returned if the WOLFSSL struct is NULL or if there was otherwise a

NULL argument passed to a subroutine.

DH_KEY_SIZE_E - is returned if their is a key size error in wolfSSL_SetTmpDH() or in

wolfSSL_CTX_SetTmpDH().

SIDE_ERROR - returned if it is not the server side in wolfSSL_SetTmpDH.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - allocated buffer passed in from wolfSSL_SetTMpDH_file_wrapper.

sz - a long int that holds the size of the file (fname within

wolfSSL_SetTmpDH_file_wrapper).

format - an integer type passed through from wolfSSL_SetTmpDH_file_wrapper() that

is a representation of the certificate format.

Example:

Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,

Const char* fname, int format);

long sz = 0;

byte* myBuffer = staticBuffer[FILE_BUFFER_SIZE];

…

if(ssl)

ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);

See Also:

wolfSSL_SetTmpDH_buffer_wrapper

wc_DhParamsLoad

wolfSSL_SetTmpDH

PemToDer

wolfSSL_CTX_SetTmpDH

wolfSSL_CTX_SetTmpDH_file

wolfSSL_CTX_SetMinRsaKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX* ctx, short keySz);

Description:

Sets the minimum RSA key size in both the WOLFSSL_CTX structure and the

WOLFSSL_CERT_MANAGER structure.

Return Values:

SSL_SUCCESS - returned on successful execution of the function.

BAD_FUNC_ARG - returned if the ctx structure is NULL or the keySz is less than zero

or not divisible by 8.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

keySz - a short integer type stored in minRsaKeySz in the ctx structure and the cm

structure converted to bytes.

Example:

WOLFSSL_CTX* ctx = SSL_CTX_new(method);

(void)minDhKeyBits;

ourCert = myoptarg;

…

minDhKeyBits = atoi(myoptarg);

…

if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){

…

See Also:

wolfSSL_SetMinRsaKey_Sz

wolfSSL_CTX_SetTmpDH_file

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX* ctx, const char* fname, int format);

Description:

The function calls wolfSSL_SetTmpDH_file_wrapper to set the server Diffie-Hellman

parameters.

Return Values:

SSL_SUCCESS - returned if the wolfSSL_SetTmpDH_file_wrapper or any of its

subroutines return successfully.

MEMORY_E - returned if an allocation of dynamic memory fails in a subroutine.

BAD_FUNC_ARG - returned if the ctx or fname parameters are NULL or if a

subroutine is passed a NULL argument.

SSL_BAD_FILE - returned if the certificate file is unable to open or if the a set of

checks on the file fail from wolfSSL_SetTmpDH_file_wrapper.

SSL_BAD_FILETYPE - returned if teh format is not PEM or ASN.1 from

wolfSSL_SetTmpDH_buffer_wrapper().

DH_KEY_SIZE_E - returned from wolfSSL_SetTmpDH() if the ctx minDhKeySz

member exceeds maximum size allowed for DH.

SIDE_ERROR - returned in wolfSSL_SetTmpDH() if the side is not the server end.

SSL_NO_PEM_HEADER - returned from PemToDer if there is no PEM header.

SSL_FATAL_ERROR - returned from PemToDer if there is a memory copy failure.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

fname - a constant character pointer to a certificate file.

format - an integer type passed through from wolfSSL_SetTmpDH_file_wrapper() that

is a representation of the certificate format.

Example:

#define dhParam “certs/dh2048.pem”

#DEFINE aSSERTiNTne(x, y) AssertInt(x, y, !=, ==)

WOLFSSL_CTX* ctx;

…

AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method()))

…

AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam,

SSL_FILETYPE_PEM));

See Also:

wolfSSL_SetTmpDH_buffer_wrapper

wolfSSL_SetTmpDH

wolfSSL_CTX_SetTmpDH

wolfSSL_SetTmpDH_buffer

wolfSSL_CTX_SetTmpDH_buffer

wolfSSL_SetTmpDH_file_wrapper

AllocDer

PemToDer

wolfSSL_get_psk_identity_hint

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_get_psk_identity_hint(const WOLFSSL* ssl);

Description:

This function returns the psk identity hint.

Return Values:

const char pointer - the value that was stored in the arrays member of the WOLFSSL

structure is returned.

NULL - returned if the WOLFSSL or Arrays structures are NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

char* idHint;

...

idHint = wolfSSL_get_psk_identity_hint(ssl);

if(idHint){

/*The hint was retrieved*/

return idHint;

} else {

/*Hint wasn’t successfully retrieved */

}

See Also:

wolfSSL_get_psk_identity

wolfSSL_SetMinRsaKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetMinRsaKey_Sz(WOLFSSL* ssl, short keySz);

Description:

Sets the minimum allowable key size in bytes for RSA located in the WOLFSSL

structure.

Return Values:

SSL_SUCCESS - the minimum was set successfully.

BAD_FUNC_ARG - returned if the ssl structure is NULL or if the ksySz is less than zero

or not divisible by 8.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

keySz - a short integer value representing the the minimum key in bits.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

short keySz;

…

int isSet = wolfSSL_SetMinRsaKey_Sz(ssl, keySz);

if(isSet != SSL_SUCCESS){

/*Failed to set. */

}

See Also:

wolfSSL_CTX_SetMinRsaKey_Sz

wolfSSL_SetMinDhKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetMinDhKey_Sz(WOLFSSL* ssl, word16 keySz);

Description:

Sets the minimum size for a Diffie-Hellman key in the WOLFSSL structure in bytes.

Return Values:

SSL_SUCCESS - the minimum size was successfully set.

BAD_FUNC_ARG - the WOLFSSL structure was NULL or the keySz parameter was

greater than the allowable size or not divisible by 8.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

keySz - a word16 type representing the bit size of the minimum DH key.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

word16 keySz;

...

if(wolfSSL_SetMinDhKey(ssl, keySz) != SSL_SUCCESS){

/*Failed to set. */

}

See Also:

wolfSSL_GetDhKey_Sz

wolfSSL_CTX_set_tmp_dh

Synopsis:

#include <wolfssl/ssl.h>

long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX* ctx, WOLFSSL_DH* dh);

Description:

Initializes the WOLFSSL_CTX structure’s dh member with the Diffie-Hellman

parameters.

Return Values:

SSL_SUCCESS - returned if the function executed successfully.

BAD_FUNC_ARG - returned if the ctx or dh structures are NULL.

SSL_FATAL_ERROR - returned if there was an error setting a structure value.

MEMORY_E - returned if their was a failure to allocate memory.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

dh - a pointer to a WOLFSSL_DH structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL_DH* dh;

…

return wolfSSL_CTX_set_tmp_dh(ctx, dh);

See Also:

wolfSSL_BN_bn2bin

wolfSSL_CTX_use_psk_identity_hint

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX* ctx, const char* hint);

Description:

This function stores the hint argument in the server_hint member of the

WOLFSSL_CTX structure.

Return Values:

SSL_SUCCESS - returned for successful execution of the function.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

hint - a constant char pointer that will be copied to the WOLFSSL_CTX structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

const char* hint;

int ret;

…

ret = wolfSSL_CTX_use_psk_identity_hint(ctx, hint);

if(ret == SSL_SUCCESS){

/* Function was successful. */

return ret;

} else {

/*Failure case. */

}

See Also:

wolfSSL_use_psk_identity_hint

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_use_psk_identity_hint(WOLFSSL* ssl, const char* hint);

Description:

This function stores the hint argument in the server_hint member of the Arrays

structure within the WOLFSSL structure.

Return Values:

SSL_SUCCESS - returned if the hint was successfully stored in the WOLFSSL

structure.

SSL_FAILURE - returned if the WOLFSSL or Arrays structures are NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

hint - a constant character pointer that holds the hint to be saved in memory.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

const char* hint; /*pass in valid hint*/

...

if(wolfSSL_use_psk_identity_hint(ssl, hint) != SSL_SUCCESS){

/*Handle failure case. */

}

See Also:

wolfSSL_CTX_use_psk_identity_hint

wolfSSL_make_eap_keys

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_make_eap_keys(WOLFSSL* ssl, void* msk, unsigned int len,

const char* label);

Description:

This function is used by EAP_TLS and EAP-TTLS to derive keying material from the

master secret.

Return Values:

BUFFER_E - returned if the actual size of the buffer exceeds the maximum size

allowable.

MEMORY_E - returned if there is an error with memory allocation.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

msk - a void pointer variable that will hold the result of the p_hash function.

len - an unsigned integer that represents the length of the msk variable.

label - a constant char pointer that is copied from in PRF() .

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);;

void* msk;

unsigned int len;

const char* label;

…

return wolfSSL_make_eap_keys(ssl, msk, len, label);

See Also:

PRF

doPRF

p_hash

wc_HmacFinal

wc_HmacUpdate

wolfSSL_CTX_SetMinEccKey_Sz

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX* ctx, short keySz);

Description:

Sets the minimum size in bytes for the ECC key in the WOLF_CTX structure and the

WOLFSSL_CERT_MANAGER structure.

Return Values:

SSL_SUCCESS - returned for a successful execution and the minEccKeySz member is

set.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX struct is NULL or if the keySz is

negative or not divisible by 8.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

keySz - a short integer type that represents the minimum ECC key size in bits.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

short keySz; /*minimum key size*/

…

if(wolfSSL_CTX_SetMinEccKey(ctx, keySz) != SSL_SUCCESS){

/*Failed to set min key size */

}

See Also:

wolfSSL_SetMinEccKey_Sz

wolfSSL_SetTmpDH_file

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetTmpDH_file(WOLFSSL* ssl, const char* fname, int format);

Description:

This function calls wolfSSL_SetTmpDH_file_wrapper to set server Diffie-Hellman

parameters.

Return Values:

SSL_SUCCESS - returned on successful completion of this function and its

subroutines.

MEMORY_E - returned if a memory allocation failed in this function or a subroutine.

SIDE_ERROR - if the side member of the Options structure found in the WOLFSSL

struct is not the server side.

SSL_BAD_FILETYPE - returns if the certificate fails a set of checks.

BAD_FUNC_ARG - returns if an argument value is NULL that is not permitted such as,

the WOLFSSL structure.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

fname - a constant char pointer holding the certificate.

format - an integer type that holds the format of the certification.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

const char* dhParam;

…

AssertIntNE(SSL_SUCCESS, wolfSSL_SetTmpDH_file(ssl, dhParam,

SSL_FILETYPE_PEM));

See Also:

wolfSSL_CTX_SetTmpDH_file

wolfSSL_SetTmpDH_file_wrapper

wolfSSL_SetTmpDH_buffer

wolfSSL_CTX_SetTmpDH_buffer

wolfSSL_SetTmpDH_buffer_wrapper

wolfSSL_SetTmpDH

wolfSSL_CTX_SetTmpDH

wolfSSL_PubKeyPemToDer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_PubKeyPemToDer(const unsigned char* pem, int pemSz,

unsigned char* buff, int buffSz);

Description:

Converts the PEM format to DER format.

Return Values:

An int type representing the bytes written to buffer.

< 0 - returned for an error.

BAD_FUNC_ARG - returned if the DER length is incorrect or if the pem buff, or buffSz

arguments are NULL.

Parameters:

pem - the PEM certificate.

pemSz - the size of the PEM certificate.

buff - the buffer that will be written to from the DerBuffer.

buffSz - the size of the buffer.

Example:

unsigned char* pem = “/*pem file*/”;

int pemSz = sizeof(pem)/sizeof(char);

unsigned char* buff; /*The buffer*/

int buffSz; /*Initialize*/

...

if(wolfSSL_PubKeyPemToDer(pem, pemSz, buff, buffSz)!= SSL_SUCCESS){

/*Conversion was not successful */

}

See Also:

wolfSSL_PubKeyPemToDer

wolfSSL_PemPubKeyToDer

PemToDer

wolfSSL_CTX_SetTmpDH

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX* ctx, const unsigned char* p, int pSz,

Const unsigned char* g, int gSz);

Description:

Sets the parameters for the server CTX Diffie-Hellman.

Return Values:

SSL_SUCCESS - returned if the function and all subroutines return without error.

BAD_FUNC_ARG - returned if the CTX, p or g parameters are NULL.

DH_KEY_SIZE_E - returned if the minDhKeySz member of the WOLFSSL_CTX struct

is not the correct size.

MEMORY_E - returned if the allocation of memory failed in this function or a subroutine.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

p - a constant unsigned char pointer loaded into the buffer member of the serverDH_P

struct.

pSz - an int type representing the size of p, initialized to MAX_DH_SIZE.

g - a constant unsigned char pointer loaded into the buffer member of the serverDH_G

struct.

gSz - an int type representing the size of g, initialized ot MAX_DH_SIZE.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol def*/);

byte* p; /*Initialize / Allocate size*/

byte* g; /*Initialize / Allocate size*/

word32 pSz = (word32)sizeof(p)/sizeof(byte);

word32 gSz = (word32)sizeof(g)/sizeof(byte);

…

int ret = wolfSSL_CTX_SetTmpDH(ctx, p, pSz, g, gSz);

if(ret != SSL_SUCCESS){

/*Failure case*/

}

See Also:

wolfSSL_SetTmpDH

wc_DhParamsLoad

wolfSSL_d2i_X509_bio

Synopsis:

#include <wolfssl/ssl.h>

d2i_X509_bio ->

WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509**

x509);

Description:

This function get the DER buffer from bio and converts it to a WOLFSSL_X509

structure.

Return Values:

Returns NULL on failure and a new WOLFSSL_X509 structure pointer on success.

Parameters:

bio - pointer to the WOLFSSL_BIO structure that has the DER certificate buffer.

x509 - pointer that get set to new WOLFSSL_X509 structure created.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_X509* x509;

// load DER into bio

x509 = wolfSSL_d2i_X509_bio(bio, NULL);

wolfSSL_d2i_X509_bio(bio, &x509);

// use x509 returned (check for NULL)

See Also:

wolfSSL_PEM_read_bio_DSAparams

Synopsis:

#include <wolfssl/ssl.h>

PEM_read_bio_DSAparams ->

WOLFSSL_DSA* wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO* bio,

WOLFSSL_DSA** x, pem_password_cb* cb, void* u);

Description:

This function get the DSA parameters from a PEM buffer in bio.

Return Values:

On successfully parsing the PEM buffer a WOLFSSL_DSA structure is created and

returned. If failing to parse the PEM buffer NULL is returned.

Parameters:

bio - pointer to the WOLFSSL_BIO structure for getting PEM memory pointer.

x - pointer to be set to new WOLFSSL_DSA structure.

cb - password callback function.

u - null terminated password string.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_DSA* dsa;

// setup bio

dsa = wolfSSL_PEM_read_bio_DSAparams(bio, NULL, NULL, NULL);

// check dsa is not NULL and then use dsa

See Also:

wolfSSL_PEM_read_bio_X509_AUX

Synopsis:

#include <wolfssl/ssl.h>

PEM_read_bio_X509_AUX->

WOLFSSL_X509* wolfSSL_PEM_read_bio_X509_AUX(WOLFSSL_BIO* bp,

WOLFSSL_X509** x, pem_password_cb* cb, void* u);

Description:

This function behaves the same as wolfSSL_PEM_read_bio_X509. AUX signifies

containing extra information such as trusted/rejected use cases and friendly name for

human readability.

Return Values:

On successfully parsing the PEM buffer a WOLFSSL_X509 structure is returned. If

unsuccessful NULL is returned.

Parameters:

bp - WOLFSSL_BIO structure to get PEM buffer from.

x - if setting WOLFSSL_X509 by function side effect.

cb - password callback.

u - NULL terminated user password.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_X509* x509;

// setup bio

X509 = wolfSSL_PEM_read_bio_X509_AUX(bio, NULL, NULL, NULL);

//check x509 is not null and then use it

See Also:

wolfSSL_PEM_read_bio_X509

wolfSSL_PEM_write_bio_PrivateKey

Synopsis:

#include <wolfssl/ssl.h>

PEM_write_bio_PrivateKey ->

int wolfSSL_PEM_write_bio_PrivateKey(WOLFSSL_BIO* bio, WOLFSSL_EVP_PKEY*

key, const WOLFSSL_EVP_CIPHER* cipher, unsigned char* passwd, int len,

pem_password_cb* cb, void* arg);

Description:

This function writes a key into a WOLFSSL_BIO structure in PEM format.

Return Values:

On successfully creating the PEM buffer SSL_SUCCESS is returned. If unsuccessful

SSL_FAILURE is returned.

Parameters:

bio - WOLFSSL_BIO structure to get PEM buffer from.

key - key to convert to PEM format.

cipher- EVP cipher structure.

passwd - password.

len - length of password.

cb - password callback.

arg - optional argument.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_EVP_PKEY* key;

int ret;

// create bio and setup key

ret = wolfSSL_PEM_write_bio_PrivateKey(bio, key, NULL, NULL, 0, NULL, NULL);

//check ret value

See Also:

wolfSSL_PEM_read_bio_X509_AUX

wolfSSL_X509_digest

Synopsis:

#include <wolfssl/ssl.h>

X509_digest ->

int wolfSSL_X509_digest( const WOLFSSL_X509* x509, const WOLFSSL_EVP_MD*

digest, unsigned char* buf, unsigned int* len)

Description:

This function returns the hash of the DER certificate.

Return Values:

SSL_SUCCESS: On successfully creating a hash.

SSL_FAILURE: Returned on bad input or unsuccessful hash.

Parameters:

x509 - certificate to get the hash of.

digest - the hash algorithm to use.

buf - buffer to hold hash.

len - length of buffer.

Example:

WOLFSSL_X509* x509;

unsigned char buffer[64];

unsigned int bufferSz;

int ret;

ret = wolfSSL_X509_digest(x509, wolfSSL_EVP_sha256(), buffer, &bufferSz);

//check ret value

See Also:

wolfSSL_X509_get_ext_d2i

Synopsis:

#include <wolfssl/ssl.h>

X509_get_ext_d2i ->

void*wolfSSL_X509_get_ext_d2i( const WOLFSSL_X509* x509, int nid, int* c, int* idx)

Description:

This function looks for and returns the extension matching the passed in NID value.

Return Values:

NULL: If extension is not found or error is encountered.

If successful a STACK_OF(WOLFSSL_ASN1_OBJECT) pointer is returned.

Parameters:

x509 - certificate to get parse through for extension.

nid - extension OID to be found.

c - if not NULL is set to -2 for multiple extensions found -1 if not found, 0 if found and

not critical and 1 if found and critical.

idx - if NULL return first extension matched otherwise if not stored in x509 start at idx.

Example:

const WOLFSSL_X509* x509;

int c;

int idx = 0;

STACK_OF(WOLFSSL_ASN1_OBJECT)* sk;

sk = wolfSSL_X509_get_ext_d2i(x509, NID_basic_constraints, &c, &idx);

//check sk for NULL and then use it. sk needs freed after done.

See Also:

wolfSSL_sk_ASN1_OBJECT_free

wolfSSL_X509_NAME_get_text_by_NID

Synopsis:

#include <wolfssl/ssl.h>

X509_NAME_get_text_by_NID ->

int wolfSSL_X509_NAME_get_text_by_NID(WOLFSSL_X509_NAME* name, int nid,

char* buf, int len);

Description:

This function gets the text related to the passed in NID value.

Return Values:

Returns the size of text buffer.

Parameters:

name - WOLFSSL_X509_NAME to search for text.

nid - NID to search for.

buf - buffer to hold text when found.

len - length of buffer.

Example:

WOLFSSL_X509_NAME* name;

char buffer[100];

int bufferSz;

int ret;

// get WOLFSSL_X509_NAME

ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName, buffer,

bufferSz);

//check ret value

See Also:

wolfSSL_X509_STORE_add_cert

Synopsis:

#include <wolfssl/ssl.h>

X509_STORE_add_cert ->

int wolfSSL_X509_STORE_add_cert(WOLFSSL_X509_STORE* str, WOLFSSL_X509*

x509);

Description:

This function adds a certificate to the WOLFSSL_X509_STRE structure.

Return Values:

SSL_SUCCESS: If certificate is added successfully.

SSL_FATAL_ERROR: If certificate is not added successfully.

Parameters:

str - certificate store to add the certificate to.

x509 - certificate to add.

Example:

WOLFSSL_X509_STORE* str;

WOLFSSL_X509* x509;

int ret;

ret = wolfSSL_X509_STORE_add_cert(str, x509);

//check ret value

See Also:

wolfSSL_X509_free

wolfSSL_X509_STORE_CTX_get_chain

Synopsis:

#include <wolfssl/ssl.h>

X509_STORE_CTX_get_chain ->

int wolfSSL_X509_STORE_CTX_get_chain(WOLFSSL_X509_STORE_CTX* ctx);

Description:

This function is a getter function for chain variable in WOLFSSL_X509_STORE_CTX

structure. Currently chain is not populated.

Return Values:

If successful returns WOLFSSL_STACK (same as STACK_OF(WOLFSSL_X509))

pointer otherwise NULL.

Parameters:

ctx - certificate store ctx to get parse chain from.

Example:

WOLFSSL_STACK* sk;

WOLFSSL_X509_STORE_CTX* ctx;

sk = wolfSSL_X509_STORE_CTX_get_chain(ctx);

//check sk for NULL and then use it. sk needs freed after done.

See Also:

wolfSSL_sk_X509_free

wolfSSL_X509_STORE_set_flags

Synopsis:

#include <wolfssl/ssl.h>

X509_STORE_set_flags ->

int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* str, unsigned long

flag);

Description:

This function takes in a flag to change the behavior of the WOLFSSL_X509_STORE

structure passed in. An example of a flag used is WOLFSSL_CRL_CHECK.

Return Values:

SSL_SUCCESS: If no errors were encountered when setting the flag.

If unsuccessful a negative error value is returned.

Parameters:

str - certificate store to set flag in.

flag - flag for behavior.

Example:

WOLFSSL_X509_STORE* str;

int ret;

// create and set up str

ret = wolfSSL_X509_STORE_set_flags(str, WOLFSSL_CRL_CHECKALL);

If (ret != SSL_SUCCESS) {

//check ret value and handle error case

}

See Also:

wolfSSL_X509_STORE_new, wolfSSL_X509_STORE_free

wolfSSL_X509_STORE_CTX_set_flags

Synopsis:

#include <wolfssl/ssl.h>

X509_STORE_CTX_set_flags ->

void wolfSSL_X509_STORE_CTX_set_flags(WOLFSSL_X509_STORE_CTX* ctx,

unsigned long flags)

Description:

This function takes in a flag to change the behavior of the

WOLFSSL_X509_STORE_CTX. structure passed in.

Return Values:

None

Parameters:

ctx - certificate store CTX to set flag in.

flag - flag for behavior.

Example:

WOLFSSL_X509_STORE_CTX* ctx;

// create and set up ctx and flag

wolfSSL_X509_STORE_CTX, set_flags(ctx, flag);

See Also:

wolfSSL_X509_STORE_CTX_new, wolfSSL_X509_STORE_CTX_free

wolfSSL_DES_set_key

Synopsis:

#include <wolfssl/openssl/des.h>

DES_set_key ->

int wolfSSL_DES_set_key(WOLFSSL_const_DES_cblock* myDes,

WOLFSSL_DES_key_schedule* key);

Description:

This function sets the key schedule. If the macro WOLFSSL_CHECK_DESKEY is

defined then acts like wolfSSL_DES_set_key_checked if not then acts like

wolfSSL_DES_set_key_unchecked.

Return Values:

If WOLFSSL_CHECK_DESKEY set then -1 if parity error, -2 for weak/null key, and 0 for

success.

If macro WOLFSSL_CHECK_DESKEY is not defined then always returns 0.

Parameters:

myDes - DES key

key - key to set from myDes.

Example:

WOLFSSL_const_DES_cblock* myDes;

WOLFSSL_DES_key_schedule* key;

int ret;

// load DES key

ret = wolfSSL_DES_set_key(myDes, key);

// check ret value

See Also:

wolfSSL_DES_set_key_checked, wolfSSL_DES_set_key_unchecked

wolfSSL_DSA_dup_DH

Synopsis:

#include <wolfssl/ssl.h>

DSA_dup_DH ->

WOLFSSL_DH* wolfSSL_DSA_dup_DH(const WOLFSSL_DSA* dsa);

Description:

This function duplicates the parameters in dsa to a newly created WOLFSSL_DH

structure.

Return Values:

If duplicated returns WOLFSSL_DH structure if function failed NULL is returned.

Parameters:

dsa - WOLFSSL_DSA structure to duplicate.

Example:

WOLFSSL_DH* dh;

WOLFSSL_DSA* dsa;

// set up dsa

dh = wolfSSL_DSA_dup_DH(dsa);

// check dh is not null

See Also:

17.3 Context and Session Setup

The functions in this section have to do with creating and setting up SSL/TLS context

objects (WOLFSSL_CTX) and SSL/TLS session objects (WOLFSSL).

wolfSSLv3_client_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD *wolfSSLv3_client_method(void);

Description:

The wolfSSLv3_client_method() function is used to indicate that the application is a

client and will only support the SSL 3.0 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Parameters:

This function has no parameters.

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfSSLv3_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfTLSv1_client_method

wolfTLSv1_1_client_method

wolfTLSv1_2_client_method

wolfDTLSv1_client_method

wolfSSLv23_client_method

wolfSSL_CTX_new

wolfSSLv3_server_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD *wolfSSLv3_server_method(void);

Description:

The wolfSSLv3_server_method() function is used to indicate that the application is a

server and will only support the SSL 3.0 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Parameters:

This function has no parameters.

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfSSLv3_server_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfTLSv1_server_method

wolfTLSv1_1_server_method

wolfTLSv1_2_server_method

wolfDTLSv1_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new

wolfSSLv23_client_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD *wolfSSLv23_client_method(void);

Description:

The wolfSSLv23_client_method() function is used to indicate that the application is a

client and will support the highest protocol version supported by the server between

SSL 3.0 - TLS 1.2. This function allocates memory for and initializes a new

WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with

wolfSSL_CTX_new().

Both wolfSSL clients and servers have robust version downgrade capability. If a

specific protocol version method is used on either side, then only that version will be

negotiated or an error will be returned. For example, a client that uses TLSv1 and tries

to connect to a SSLv3 only server will fail, likewise connecting to a TLSv1.1 will fail as

well.

To resolve this issue, a client that uses the wolfSSLv23_client_method() function will

use the highest protocol version supported by the server and downgrade to SSLv3 if

needed. In this case, the client will be able to connect to a server running SSLv3 -

TLSv1.2.

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Parameters:

This function has no parameters.

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfSSLv23_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_client_method

wolfTLSv1_client_method

wolfTLSv1_1_client_method

wolfTLSv1_2_client_method

wolfDTLSv1_client_method

wolfSSL_CTX_new

wolfSSLv23_server_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD *wolfSSLv23_server_method(void);

Description:

The wolfSSLv23_server_method() function is used to indicate that the application is a

server and will support clients connecting with protocol version from SSL 3.0 - TLS 1.2.

This function allocates memory for and initializes a new WOLFSSL_METHOD structure

to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Parameters:

This function has no parameters.

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfSSLv23_server_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_server_method

wolfTLSv1_server_method

wolfTLSv1_1_server_method

wolfTLSv1_2_server_method

wolfDTLSv1_server_method

wolfSSL_CTX_new

wolfTLSv1_client_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_client_method(void);

Description:

The wolfTLSv1_client_method() function is used to indicate that the application is a

client and will only support the TLS 1.0 protocol. This function allocates memory for and

initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS

context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_client_method

wolfTLSv1_1_client_method

wolfTLSv1_2_client_method

wolfDTLSv1_client_method

wolfSSLv23_client_method

wolfSSL_CTX_new

wolfTLSv1_server_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_server_method(void);

Description:

The wolfTLSv1_server_method() function is used to indicate that the application is a

server and will only support the TLS 1.0 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_server_method();

if (method == NULL) {

/*nable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_server_method

wolfTLSv1_1_server_method

wolfTLSv1_2_server_method

wolfDTLSv1_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new

wolfTLSv1_1_client_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_1_client_method(void);

Description:

The wolfTLSv1_1_client_method() function is used to indicate that the application is a

client and will only support the TLS 1.0 protocol. This function allocates memory for and

initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS

context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_1_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_client_method

wolfTLSv1_client_method

wolfTLSv1_2_client_method

wolfDTLSv1_client_method

wolfSSLv23_client_method

wolfSSL_CTX_new

wolfTLSv1_1_server_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_1_server_method(void);

Description:

The wolfTLSv1_1_server_method() function is used to indicate that the application is a

server and will only support the TLS 1.1 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_1_server_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_server_method

wolfTLSv1_server_method

wolfTLSv1_2_server_method

wolfDTLSv1_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new

wolfTLSv1_2_client_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_2_client_method(void);

Description:

The wolfTLSv1_2_client_method() function is used to indicate that the application is a

client and will only support the TLS 1.2 protocol. This function allocates memory for and

initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS

context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_2_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_client_method

wolfTLSv1_client_method

wolfTLSv1_1_client_method

wolfDTLSv1_client_method

wolfSSLv23_client_method

wolfSSL_CTX_new

wolfTLSv1_2_server_method

Synopsis:

WOLFSSL_METHOD *wolfTLSv1_2_server_method(void);

Description:

The wolfTLSv1_2_server_method() function is used to indicate that the application is a

server and will only support the TLS 1.2 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfTLSv1_2_server_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_server_method

wolfTLSv1_server_method

wolfTLSv1_1_server_method

wolfDTLSv1_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new

wolfSSLv3_server_method_ex; wolfSSLv3_client_method_ex;

wolfTLSv1_server_method_ex; wolfTLSv1_client_method_ex;

wolfTLSv1_1_server_method_ex; wolfTLSv1_1_client_method_ex;

wolfTLSv1_2_server_method_ex; wolfTLSv1_2_client_method_ex;

wolfSSLv23_server_method_ex; wolfSSLv23_client_method_ex;

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap)

Description:

These functions have the same behavior as their counterparts (functions with not having

_ex) except that they do not create WOLFSSL_METHOD* using dynamic memory. The

functions will use the heap hint passed in to create a new WOLFSSL_METHOD struct.

Return Values:

A value of WOLFSSL_METHOD pointer if success.

NULL is returned in error cases.

Parameters:

heap - a pointer to a heap hint for creating WOLFSSL_METHOD struct.

Example:

WOLFSSL_CTX* ctx;

int ret;

...

ctx = NULL:

ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex,

memory, memorySz, 0, MAX_CONCURRENT_HANDSHAKES);

if (ret != SSL_SUCCESS) {

// handle error case

}

...

See Also:

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_CTX_free

wolfDTLSv1_client_method

Synopsis:

WOLFSSL_METHOD *wolfDTLSv1_client_method(void);

Description:

The wolfDTLSv1_client_method() function is used to indicate that the application is a

client and will only support the DTLS 1.0 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfDTLSv1_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_client_method

wolfTLSv1_client_method

wolfTLSv1_1_client_method

wolfTLSv1_2_client_method

wolfSSLv23_client_method

wolfSSL_CTX_new

wolfDTLSv1_server_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD *wolfDTLSv1_server_method(void);

Description:

The wolfDTLSv1_server_method() function is used to indicate that the application is a

server and will only support the DTLS 1.0 protocol. This function allocates memory for

and initializes a new WOLFSSL_METHOD structure to be used when creating the

SSL/TLS context with wolfSSL_CTX_new().

Return Values:

If successful, the call will return a pointer to the newly created WOLFSSL_METHOD

structure.

If memory allocation fails when calling XMALLOC, the failure value of the underlying

malloc() implementation will be returned (typically NULL with errno will be set to

ENOMEM).

Example:

WOLFSSL_METHOD* method;

WOLFSSL_CTX* ctx;

method = wolfDTLSv1_server_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

...

See Also:

wolfSSLv3_server_method

wolfTLSv1_server_method

wolfTLSv1_1_server_method

wolfTLSv1_2_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new

wolfSSL_new

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL* wolfSSL_new(WOLFSSL_CTX* ctx);

Description:

This function creates a new SSL session, taking an already created SSL context as

input.

Return Values:

If successful the call will return a pointer to the newly-created WOLFSSL structure.

Upon failure, NULL will be returned.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

Example:

WOLFSSL* ssl = NULL;

WOLFSSL_CTX* ctx = 0;

ctx = wolfSSL_CTX_new(method);

if (ctx == NULL) {

/*context creation failed*/

}

ssl = wolfSSL_new(ctx);

if (ssl == NULL) {

/*SSL object creation failed*/

}

See Also:

wolfSSL_CTX_new

wolfSSL_free

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_free(WOLFSSL* ssl);

Description:

This function frees an allocated WOLFSSL object.

Return Values:

No return values are used for this function.

Parameters:

ssl - pointer to the SSL object, created with wolfSSL_new().

Example:

WOLFSSL* ssl = 0;

...

wolfSSL_free(ssl);

See Also:

wolfSSL_CTX_new

wolfSSL_new

wolfSSL_CTX_free

wolfSSL_ASN1_INTEGER_to_BN

Synopsis:

#include <wolfssl/ssl.h>

ASN1_INTEGER_to_BN ->

WOLFSSL_BIGNUM* wolfSSL_ASN1_INTEGER_to_BN(const

WOLFSSL_ASN1_INTEGER* ai, WOLFSSL_BIGNUM* bn);

Description:

This function is used to copy a WOLFSSL_ASN1_INTEGER value to a

WOLFSSL_BIGNUM structure.

Return Values:

On successfully copying the WOLFSSL_ASN1_INTEGER value a WOLFSSL_BIGNUM

pointer is returned.

If a failure occured NULL is returned.

Parameters:

ai - WOLFSSL_ASN1_INTEGER structure to copy from.

bn - if wanting to copy into an already existing WOLFSSL_BIGNUM struct then pass in

a pointer to it. Optionally this can be NULL and a new WOLFSSL_BIGNUM structure

will be created.

Example:

WOLFSSL_ASN1_INTEGER* ai;

WOLFSSL_BIGNUM* bn;

// create ai

bn = wolfSSL_ASN1_INTEGER_to_BN(ai, NULL);

// or if having already created bn and wanting to reuse structure

// wolfSSL_ASN1_INTEGER_to_BN(ai, bn);

// check bn is or return value is not NULL

See Also:

wolfSSL_ASN1_INTEGER_get

Synopsis:

#include <wolfssl/ssl.h>

#include <l/wolfssl/openssl/asn1.h>

ASN1_INTEGER_get ->

long wolfSSL_ASN1_INTEGER_get(const WOLFSSL_ASN1_INTEGER* i)

Description:

This functions convert ASN1_INTEGER structure to the value.

Return Values:

ASN1_INTEGER_get() returns the value of i but it returns 0 if a is NULL and -1 on error.

Parameters:

i - WOLFSSL_ASN1_INTEGER structure

Example:

WOLFSSL_ASN1_INTEGER* i;

long a;

// create ai

a = wolfSSL_ASN1_INTEGER_get(ai);

// check a is or return value is not NULL

wolfSSL_BN_mod_exp

Synopsis:

#include <wolfssl/openssl/bn.h>

BN_mod_exp ->

int wolfSSL_BN_mod_exp(WOLFSSL_BIGNUM* r, const WOLFSSL_BIGNUM* a,

const WOLFSSL_BIGNUM* p, const WOLFSSL_BIGNUM* m, WOLFSSL_BN_CTX*

ctx);

Description:

This function performs the following math “r = (a^p) % m”.

Return Values:

SSL_SUCCESS: On successfully performing math operation.

SSL_FAILURE: If an error case was encountered.

Parameters:

r - structure to hold result.

a - value to be raised by a power.

p - power to raise a by.

m - modulus to use.

ctx -currently not used with wolfSSL can be NULL.

Example:

WOLFSSL_BIGNUM r,a,p,m;

int ret;

// set big number values

ret = wolfSSL_BN_mod_exp(r, a, p, m, NULL);

// check ret value

See Also:

wolfSSL_BN_new, wolfSSL_BN_free

wolfSSL_BN_mod_mul

Synopsis:

#include <wolfssl/openssl/bn.h>

BN_mod_mul ->

nt wolfSSL_BN_mod_mul(WOLFSSL_BIGNUM *r, const WOLFSSL_BIGNUM *a,

const WOLFSSL_BIGNUM *b, const WOLFSSL_BIGNUM *m,

WOLFSSL_BN_CTX *ctx)

Description:

This function performs the following math “"r=(a*b) mod m”.

Return Values:

SSL_SUCCESS: On successfully performing math operation.

SSL_FAILURE: If an error case was encountered.

Parameters:

r - structure to hold result.

a - value to be multiplied

b - value to multiply

m - modulus to use

ctx -currently not used with wolfSSL can be NULL.

Example:

WOLFSSL_BIGNUM r,a,b, m;

int ret;

// set big number values

ret = wolfSSL_BN_mod_mul(r, a, b, m, NULL);

// check ret value

See Also:

wolfSSL_BN_new, wolfSSL_BN_free

wolfSSL_check_private_key

Synopsis:

#include <wolfssl/ssl.h>

SSL_check_private_key ->

int wolfSSL_check_private_key(const WOLFSSL* ssl);

Description:

This function checks that the private key is a match with the certificate being used.

Return Values:

SSL_SUCCESS: On successfully match.

SSL_FAILURE: If an error case was encountered.

All error cases other than SSL_FAILURE are negative values.

Parameters:

ssl - WOLFSSL structure to check.

Example:

WOLFSSL* ssl;

int ret;

// create and set up ssl

ret = wolfSSL_check_private_key(ssl);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_get_client_random

Synopsis:

#include <wolfssl/ssl.h>

SSL_get_client_random ->

size_t wolfSSL_get_client_random(const WOLFSSL* ssl, unsigned char* out, size_t

outSz);

Description:

This is used to get the random data sent by the client during the handshake.

Return Values:

On successfully getting data returns a value greater than 0. If no random data buffer or

an error state returns 0. If outSz passed in is 0 then the maximum buffer size needed is

returned.

Parameters:

ssl - WOLFSSL structure to get clients random data buffer from.

out -buffer to hold random data.

outSz -size of out buffer passed in. (if 0 function will return max buffer size needed)

Example:

WOLFSSL ssl;

unsigned char* buffer;

size_t bufferSz;

size_t ret;

bufferSz = wolfSSL_get_client_random(ssl, NULL, 0);

buffer = malloc(bufferSz);

ret = wolfSSL_get_client_random(ssl, buffer, bufferSz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_get_server_random

Synopsis:

#include <wolfssl/ssl.h>

SSL_get_server_random ->

size_t wolfSSL_get_server_random(const WOLFSSL* ssl, unsigned char* out, size_t

outSz);

Description:

This is used to get the random data sent by the server during the handshake.

Return Values:

On successfully getting data returns a value greater than 0. If no random data buffer or

an error state returns 0. If outSz passed in is 0 then the maximum buffer size needed is

returned.

Parameters:

ssl - WOLFSSL structure to get clients random data buffer from.

out -buffer to hold random data.

outSz -size of out buffer passed in. (if 0 function will return max buffer size needed)

Example:

WOLFSSL ssl;

unsigned char* buffer;

size_t bufferSz;

size_t ret;

bufferSz = wolfSSL_get_server_random(ssl, NULL, 0);

buffer = malloc(bufferSz);

ret = wolfSSL_get_server_random(ssl, buffer, bufferSz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_SESSION_get_master_key

Synopsis:

#include <wolfssl/ssl.h>

SSL_SESSION_get_master_key ->

int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses, unsigned

char* out, int outSz);

Description:

This is used to get the master key after completing a handshake.

Return Values:

On successfully getting data returns a value greater than 0. If no data or an error state

is hit then the function returns 0. If the outSz passed in is 0 then the maximum buffer

size needed is returned.

Parameters:

ses - WOLFSSL_SESSION structure to get master secret buffer from.

out -buffer to hold data.

outSz -size of out buffer passed in. (if 0 function will return max buffer size needed)

Example:

WOLFSSL_SESSION ssl;

unsigned char* buffer;

size_t bufferSz;

size_t ret;

// complete handshake and get session structure

bufferSz = wolfSSL_SESSION_get_master_secret(ses, NULL, 0);

buffer = malloc(bufferSz);

ret = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_SESSION_get_master_key_length

Synopsis:

#include <wolfssl/ssl.h>

SSL_SESSION_get_master_key_length ->

int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses);

Description:

This is used to get the master secret key length.

Return Values:

Returns master secret key size.

Parameters:

ses - WOLFSSL_SESSION structure to get master secret buffer from.

Example:

WOLFSSL_SESSION ssl;

unsigned char* buffer;

size_t bufferSz;

size_t ret;

// complete handshake and get session structure

bufferSz = wolfSSL_SESSION_get_master_secret_length(ses);

buffer = malloc(bufferSz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_get_options

Synopsis:

#include <wolfssl/ssl.h>

SSL_get_options ->

unsigned long wolfSSL_get_options(const WOLFSSL* ssl);

Description:

This function returns the current options mask.

Return Values:

Returns the mask value stored in ssl.

Parameters:

ssl - WOLFSSL structure to get options mask from.

Example:

WOLFSSL* ssl;

unsigned long mask;

mask = wolfSSL_get_options(ssl);

// check mask

See Also:

wolfSSL_new, wolfSSL_free, wolfSSL_set_options

wolfSSL_set_options

Synopsis:

#include <wolfssl/ssl.h>

SSL_set_options ->

unsigned long wolfSSL_get_options(const WOLFSSL* ssl, unsigned long op);

Description:

This function sets the options mask in the ssl.

Some valid options are:

SSL_OP_ALL

SSL_OP_COOKIE_EXCHANGE

SSL_OP_NO_SSLv2

SSL_OP_NO_SSLv3

SSL_OP_NO_TLSv1

SSL_OP_NO_TLSv1_1

SSL_OP_NO_TLSv1_2

SSL_OP_NO_COMPRESSION

Return Values:

Returns the updated options mask value stored in ssl.

Parameters:

ssl - WOLFSSL structure to set options mask.

Example:

WOLFSSL* ssl;

unsigned long mask;

mask = SSL_OP_NO_TLSv1

mask = wolfSSL_set_options(ssl, mask);

// check mask

See Also:

wolfSSL_new, wolfSSL_free, wolfSSL_get_options

wolfSSL_set_msg_callback

Synopsis:

#include <wolfssl/ssl.h>

SSL_set_msg_callback ->

int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb);

Description:

This function sets a callback in the ssl. The callback is to observe handshake

messages. NULL value of cb resets the callback.

Callback function prototype:

typedef void (*SSL_Msg_Cb)(int write_p, int version, int content_type,

const void *buf, size_t len, WOLFSSL *ssl, void *arg);

Return Values:

SSL_SUCCESS: On success.

SSL_FAILURE: If an NULL ssl passed in.

Parameters:

ssl - WOLFSSL structure to set callback argument.

Example:

static cb(int write_p, int version, int content_type,

const void *buf, size_t len, WOLFSSL *ssl, void *arg)

{ … }

WOLFSSL* ssl;

ret = wolfSSL_set_msg_callback(ssl, cb);

// check ret

See Also:

wolfSSL_set_msg_callback_arg

Synopsis:

#include <wolfssl/ssl.h>

SSL_set_msg_callback_arg ->

void wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void *arg);

Description:

This function sets associated callback context value in the ssl. The value is handed over

to the callback argument.

266

Return Values:

None

Parameters:

ssl - WOLFSSL structure to set callback argument.

Example:

static cb(int write_p, int version, int content_type,

const void *buf, size_t len, WOLFSSL *ssl, void *arg)

{ … }

WOLFSSL* ssl;

ret = wolfSSL_set_msg_callback(ssl, cb);

// check ret

wolfSSL_set_msg_callback(ssl, arg);

See Also:

wolfSSL_set_msg_callback

wolfSSL_get_verify_result

Synopsis:

#include <wolfssl/ssl.h>

SSL_get_verify_result ->

long wolfSSL_get_verify_result(const WOLFSSL* ssl);

Description:

This is used to get the results after trying to verify the peer's certificate.

267

Return Values:

X509_V_OK: On successful verification.

SSL_FAILURE: If an NULL ssl passed in.

Parameters:

ssl - WOLFSSL structure to get verification results from.

Example:

WOLFSSL* ssl;

long ret;

// attempt/complete handshake

ret = wolfSSL_get_verify_result(ssl);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_get1_session

Synopsis:

#include <wolfssl/ssl.h>

SSL_get1_session ->

WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl)

Description:

This function returns the WOLFSSL_SESSION from the WOLFSSL structure.

Return Values:

WOLFSSL_SESSION: On success return session pointer.

NULL: on failure returns NULL.

268

Parameters:

ssl - WOLFSSL structure to get session from.

Example:

WOLFSSL* ssl;

WOLFSSL_SESSION* ses;

// attempt/complete handshake

ses = wolfSSL_get1_session(ssl);

// check ses information

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_set_tlsext_debug_arg

Synopsis:

#include <wolfssl/ssl.h>

SSL_set_tlsext_debug_arg ->

long wolfSSL_set_tlsext_debug_arg(WOLFSSL* ssl, void* arg);

Description:

This is used to set the debug argument passed around.

Return Values:

SSL_SUCCESS: On successful setting argument.

SSL_FAILURE: If an NULL ssl passed in.

Parameters:

ssl - WOLFSSL structure to set argument in.

arg - argument to use.

Example:

269

WOLFSSL* ssl;

void* args;

int ret;

// create ssl object

ret = wolfSSL_set_tlsext_debug_arg(ssl, args);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_set_tmp_dh

Synopsis:

#include <wolfssl/ssl.h>

SSL_set_tmp_dh ->

long wolfSSL_set_tmp_dh(WOLFSSL* ssl, WOLFSSL_DH* dh);

Description:

This function sets the temporary DH to use during the handshake.

Return Values:

SSL_SUCCESS: On successful setting DH.

SSL_FAILURE, MEMORY_E, SSL_FATAL_ERROR, BAD_FUNC_ARG: in error

cases

Parameters:

ssl - WOLFSSL structure to set temporary DH.

dh - DH to use.

Example:

WOLFSSL* ssl;

WOLFSSL_DH* dh;

int ret;

270

// create ssl object

ret = wolfSSL_set_tmp_dh(ssl, dh);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_state

Synopsis:

#include <wolfssl/ssl.h>

SSL_state ->

int wolfSSL_state(WOLFSSL* ssl);

Description:

This is used to get the internal error state of the WOLFSSL structure.

Return Values:

Returns ssl error state or BAD_FUNC_ARG if ssl is NULL.

Parameters:

ssl - WOLFSSL structure to get state from.

Example:

WOLFSSL* ssl;

int ret;

// create ssl object

ret = wolfSSL_state(ssl);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

271

wolfSSL_use_certificate

Synopsis:

#include <wolfssl/ssl.h>

SSL_use_certificate ->

int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509);

Description:

This is used to set the certificate for WOLFSSL structure to use during a handshake.

Return Values:

SSL_SUCCESS: On successful setting argument.

SSL_FAILURE: If a NULL argument passed in.

Parameters:

ssl - WOLFSSL structure to set certificate in.

x509 - certificate to use.

Example:

WOLFSSL* ssl;

WOLFSSL_X509* x509

int ret;

// create ssl object and x509

ret = wolfSSL_use_certificate(ssl, x509);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_use_certificate_ASN1

Synopsis:

#include <wolfssl/ssl.h>

272

SSL_use_certificate_ASN1 ->

int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der, int derSz);

Description:

This is used to set the certificate for WOLFSSL structure to use during a handshake. A

DER formatted buffer is expected.

Return Values:

SSL_SUCCESS: On successful setting argument.

SSL_FAILURE: If a NULL argument passed in.

Parameters:

ssl - WOLFSSL structure to set certificate in.

der - DER certificate to use.

derSz - size of the DER buffer passed in.

Example:

WOLFSSL* ssl;

unsigned char* der;

int derSz;

int ret;

// create ssl object and set DER variables

ret = wolfSSL_use_certificate_ASN1(ssl, der, derSz);

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSLv23_method

Synopsis:

#include <wolfssl/ssl.h>

273

SSLv23_method ->

WOLFSSL_METHOD* wolfSSLv23_method(void);

Description:

This function returns a WOLFSSL_METHOD similar to wolfSSLv23_client_method

except that it is not determined which side yet (server/client).

Return Values:

WOLFSSL_METHOD*: On successful creation returns a WOLFSSL_METHOD pointer.

NULL: NULL if memory allocation error or failure to create method.

Parameters:

None

Example:

WOLFSSL* ctx;

ctx = wolfSSL_CTX_new(wolfSSLv23_method());

// check ret value

See Also:

wolfSSL_new, wolfSSL_free

wolfSSL_CTX_new

Synopsis:

WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD* method);

Description:

This function creates a new SSL context, taking a desired SSL/TLS protocol method for

input.

Return Values:

If successful the call will return a pointer to the newly-created WOLFSSL_CTX. Upon

failure, NULL will be returned.

274

Parameters:

method - pointer to the desired WOLFSSL_METHOD to use for the SSL context. This

is created using one of the wolfSSLvXX_XXXX_method() functions to specify

SSL/TLS/DTLS protocol level.

Example:

WOLFSSL_CTX* ctx = 0;

WOLFSSL_METHOD* method = 0;

method = wolfSSLv3_client_method();

if (method == NULL) {

/*unable to get method*/

}

ctx = wolfSSL_CTX_new(method);

if (ctx == NULL) {

/*context creation failed*/

}

See Also:

wolfSSL_new

wolfSSL_CTX_free

Synopsis:

void wolfSSL_CTX_free(WOLFSSL_CTX* ctx);

Description:

This function frees an allocated WOLFSSL_CTX object. This function decrements the

CTX reference count and only frees the context when the reference count has reached

Return Values:

No return values are used for this function.

Parameters:

275

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = 0;

...

wolfSSL_CTX_free(ctx);

See Also:

wolfSSL_CTX_new

wolfSSL_new

wolfSSL_free

wolfSSL_CTX_clear_options

Synopsis:

long wolfSSL_CTX_clear_options(WOLFSSL_CTX* ctx, long opt);

Description:

This function resets option bits of WOLFSSL_CTX object.

Return Values:

New option bits

Parameters:

ctx - pointer to the SSL context.

Example:

WOLFSSL_CTX* ctx = 0;

...

wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);

See Also:

wolfSSL_CTX_new

wolfSSL_new

wolfSSL_free

276

wolfSSL_CTX_add_extra_chain_cert

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_add_extra_chain_cert ->

long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX* ctx, WOLFSSL_X509*

x509);

Description:

This function adds the certificate to the internal chain being built in the WOLFSSL_CTX

structure.

Return Values:

SSL_SUCCESS: after successfully adding the certificate.

SSL_FAILURE: if failing to add the certificate to the chain.

Parameters:

ctx - WOLFSSL_CTX structure to add certificate to.

x509 - certificate to add to the chain.

Example:

WOLFSSL_CTX* ctx;

WOLFSSL_X509* x509;

int ret;

// create ctx

ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509);

// check ret value

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free

277

wolfSSL_CTX_get_cert_store

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_get_cert_store ->

WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx);

Description:

This is a getter function for the WOLFSSL_X509_STORE structure in ctx.

Return Values:

WOLFSSL_X509_STORE*: On successfully getting the pointer.

NULL: Returned if NULL arguments are passed in.

Parameters:

ctx - pointer to the WOLFSSL_CTX structure for getting cert store pointer.

Example:

WOLFSSL_CTX ctx;

WOLFSSL_X509_STORE* st;

// setup ctx

st = wolfSSL_CTX_get_cert_store(ctx);

//use st

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free, wolfSSL_CTX_set_cert_store

wolfSSL_CTX_set_cert_store

Synopsis:

#include <wolfssl/ssl.h>

278

SSL_CTX_set_cert_store ->

void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx, WOLFSSL_X509_STORE*

str);

Description:

This is a setter function for the WOLFSSL_X509_STORE structure in ctx.

Return Values:

None

Parameters:

ctx - pointer to the WOLFSSL_CTX structure for setting cert store pointer.

str - pointer to the WOLFSSL_X509_STORE to set in ctx.

Example:

WOLFSSL_CTX ctx;

WOLFSSL_X509_STORE* st;

// setup ctx and st

st = wolfSSL_CTX_set_cert_store(ctx, st);

//use st

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free, wolfSSL_CTX_get_cert_store

wolfSSL_CTX_get_default_passwd_cb

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_get_default_passwd_cb ->

int wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX* ctx)

279

Description:

This is a getter function for the password callback set in ctx.

Return Values:

On success returns the callback function.

NULL: If ctx is NULL then NULL is returned.

Parameters:

ctx - WOLFSSL_CTX structure to get call back from.

Example:

WOLFSSL_CTX* ctx;

Pem_password_cb cb;

// setup ctx

cb = wolfSSL_CTX_get_default_passwd_cb(ctx);

//use cb

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free

wolfSSL_CTX_get_default_passwd_cb_userdata

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_get_default_passwd_cb_userdata ->

void* wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX* ctx)

Description:

This is a getter function for the password callback user data set in ctx.

Return Values:

On success returns the user data pointer.

280

NULL: If ctx is NULL then NULL is returned.

Parameters:

ctx - WOLFSSL_CTX structure to get user data from.

Example:

WOLFSSL_CTX* ctx;

void* data;

// setup ctx

data = wolfSSL_CTX_get_default_passwd_cb(ctx);

//use data

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free

wolfSSL_CTX_get_read_ahead

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_get_read_ahead ->

int wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX* ctx);

Description:

This function returns the get read ahead flag from a WOLFSSL_CTX structure;

Return Values:

On success returns the read ahead flag.

SSL_FAILURE: If ctx is NULL then SSL_FAILURE is returned.

Parameters:

ctx - WOLFSSL_CTX structure to get read ahead flag from.

281

Example:

WOLFSSL_CTX* ctx;

int flag;

// setup ctx

flag = wolfSSL_CTX_get_read_ahead(ctx);

//check flag

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free, wolfSSL_CTX_set_read_ahead

wolfSSL_CTX_set_read_ahead

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_set_read_ahead ->

int wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX* ctx, int v);

Description:

This function sets the read ahead flag in the WOLFSSL_CTX structure;

Return Values:

SSL_SUCCESS: If ctx read ahead flag set.

SSL_FAILURE: If ctx is NULL then SSL_FAILURE is returned.

Parameters:

ctx - WOLFSSL_CTX structure to set read ahead flag.

Example:

WOLFSSL_CTX* ctx;

int flag;

int ret;

// setup ctx

282

ret = wolfSSL_CTX_set_read_ahead(ctx, flag);

// check return value

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free, wolfSSL_CTX_get_read_ahead

wolfSSL_CTX_set_tlsext_status_arg

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_set_tlsext_status_arg ->

long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX* ctx, void* arg);

Description:

This function sets the options argument to use with OCSP.

Return Values:

SSL_FAILURE: If ctx or it’s cert manager is NULL.

SSL_SUCCESS: If successfully set.

Parameters:

ctx - WOLFSSL_CTX structure to set user argument.

arg - user argument.

Example:

WOLFSSL_CTX* ctx;

void* data;

int ret;

// setup ctx

ret = wolfSSL_CTX_set_tlsext_status_arg(ctx, data);

//check ret value

283

See Also:

wolfSSL_CTX_new, wolfSSL_CTX_free

wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg

Synopsis:

#include <wolfssl/ssl.h>

SSL_CTX_set_tlsext_opaque_prf_input_callback_arg ->

long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(WOLFSSL_CTX* ctx,

void* arg);

Description:

This function sets the optional argument to be passed to the PRF callback.

Return Values:

SSL_FAILURE: If ctx is NULL.

SSL_SUCCESS: If successfully set.

Parameters:

ctx - WOLFSSL_CTX structure to set user argument.

arg - user argument.

Example:

WOLFSSL_CTX* ctx;

void* data;

int ret;

// setup ctx

ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data);

//check ret value

See Also:

284

wolfSSL_CTX_new, wolfSSL_CTX_free

wolfSSL_SetVersion

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetVersion(WOLFSSL* ssl, int version);

Description:

This function sets the SSL/TLS protocol version for the specified SSL session

(WOLFSSL object) using the version as specified by version.

This will override the protocol setting for the SSL session (ssl) - originally defined and

set by the SSL context (wolfSSL_CTX_new()) method type.

Return Values:

If successful the call will return SSL_SUCCESS.

BAD_FUNC_ARG will be returned if the input SSL object is NULL or an incorrect

protocol version is given for version.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

version - SSL/TLS protocol version. Possible values include WOLFSSL_SSLV3,

WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2.

Example:

int ret = 0;

WOLFSSL* ssl;

...

ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1);

if (ret != SSL_SUCCESS) {

/*failed to set SSL session protocol version*/

}

See Also:

285

wolfSSL_CTX_new

wolfSSL_use_old_poly

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_use_old_poly(WOLFSSL* ssl, int value);

Description:

Since there is some differences between the first release and newer versions of

chacha-poly AEAD construction we have added an option to communicate with

servers/clients using the older version. By default wolfSSL uses the new version.

Return Values:

If successful the call will return 0.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

value - whether or not to use the older version of setting up the information for

poly1305. Passing a flag value of 1 indicates yes use the old poly AEAD, to switch back

to using the new version pass a flag value of 0.

Example:

int ret = 0;

WOLFSSL* ssl;

...

ret = wolfSSL_use_old_poly(ssl, 1);

if (ret != 0) {

/*failed to set poly1305 AEAD version*/

}

wolfSSL_check_domain_name

Synopsis:

#include <wolfssl/ssl.h>

286

int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn);

Description:

wolfSSL by default checks the peer certificate for a valid date range and a verified

signature. Calling this function before wolfSSL_connect() or wolfSSL_accept() will add

a domain name check to the list of checks to perform. dn holds the domain name to

check against the peer certificate when it’s received.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FAILURE will be returned if a memory error was encountered.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

dn - domain name to check against the peer certificate when received.

Example:

int ret = 0;

WOLFSSL* ssl;

char* domain = (char*) “www.yassl.com”;

...

ret = wolfSSL_check_domain_name(ssl, domain);

if (ret != SSL_SUCCESS) {

/*failed to enable domain name check*/

}

See Also:

wolfSSL_set_cipher_list

Synopsis:

#include <wolfssl/ssl.h>

287

int wolfSSL_set_cipher_list(WOLFSSL* ssl, const char* list);

Description:

This function sets cipher suite list for a given WOLFSSL object (SSL session). The

ciphers in the list should be sorted in order of preference from highest to lowest. Each

call to wolfSSL_set_cipher_list() resets the cipher suite list for the specific SSL session

to the provided list each time the function is called.

The cipher suite list, list, is a null-terminated text string, and a colon-delimited list. For

example, one value for list may be

"DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256"

Valid cipher values are the full name values from the cipher_names[] array in

src/internal.c (for a definite list of valid cipher values check src/internal.c):

RC4-SHA

RC4-MD5

DES-CBC3-SHA

AES128-SHA

AES256-SHA

NULL-SHA

NULL-SHA256

DHE-RSA-AES128-SHA

DHE-RSA-AES256-SHA

PSK-AES128-CBC-SHA256

PSK-AES128-CBC-SHA

PSK-AES256-CBC-SHA

PSK-NULL-SHA256

PSK-NULL-SHA

HC128-MD5

HC128-SHA

HC128-B2B256

AES128-B2B256

AES256-B2B256

RABBIT-SHA

NTRU-RC4-SHA

NTRU-DES-CBC3-SHA

NTRU-AES128-SHA

NTRU-AES256-SHA

288

QSH

AES128-CCM-8

AES256-CCM-8

ECDHE-ECDSA-AES128-CCM-8

ECDHE-ECDSA-AES256-CCM-8

ECDHE-RSA-AES128-SHA

ECDHE-RSA-AES256-SHA

ECDHE-ECDSA-AES128-SHA

ECDHE-ECDSA-AES256-SHA

ECDHE-RSA-RC4-SHA

ECDHE-RSA-DES-CBC3-SHA

ECDHE-ECDSA-RC4-SHA

ECDHE-ECDSA-DES-CBC3-SHA

AES128-SHA256

AES256-SHA256

DHE-RSA-AES128-SHA256

DHE-RSA-AES256-SHA256

ECDH-RSA-AES128-SHA

ECDH-RSA-AES256-SHA

ECDH-ECDSA-AES128-SHA

ECDH-ECDSA-AES256-SHA

ECDH-RSA-RC4-SHA

ECDH-RSA-DES-CBC3-SHA

ECDH-ECDSA-RC4-SHA

ECDH-ECDSA-DES-CBC3-SHA

AES128-GCM-SHA256

AES256-GCM-SHA384

DHE-RSA-AES128-GCM-SHA256

DHE-RSA-AES256-GCM-SHA384

ECDHE-RSA-AES128-GCM-SHA256

ECDHE-RSA-AES256-GCM-SHA384

ECDHE-ECDSA-AES128-GCM-SHA256

ECDHE-ECDSA-AES256-GCM-SHA384

ECDH-RSA-AES128-GCM-SHA256

ECDH-RSA-AES256-GCM-SHA384

ECDH-ECDSA-AES128-GCM-SHA256

ECDH-ECDSA-AES256-GCM-SHA384

CAMELLIA128-SHA

DHE-RSA-CAMELLIA128-SHA

CAMELLIA256-SHA

289

DHE-RSA-CAMELLIA256-SHA

CAMELLIA128-SHA256

DHE-RSA-CAMELLIA128-SHA256

CAMELLIA256-SHA256

DHE-RSA-CAMELLIA256-SHA256

ECDHE-RSA-AES128-SHA256

ECDHE-ECDSA-AES128-SHA256

ECDH-RSA-AES128-SHA256

ECDH-ECDSA-AES128-SHA256

ECDHE-ECDSA-AES256-SHA384

ECDH-RSA-AES256-SHA384

ECDH-ECDSA-AES256-SHA384

Return Values:

SSL_SUCCESS will be returned upon successful function completion, otherwise

SSL_FAILURE will be returned on failure.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

list - null-terminated text string and a colon-delimited list of cipher suites to use with the

specified SSL session.

Example:

int ret = 0;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_set_cipher_list(ssl,

“DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);

if (ret != SSL_SUCCESS) {

/*failed to set cipher suite list*/

}

See Also:

wolfSSL_CTX_set_cipher_list

wolfSSL_new

wolfSSL_CTX_set_cipher_list

290

Synopsis:

int wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX* ctx, const char* list);

Description:

This function sets cipher suite list for a given WOLFSSL_CTX. This cipher suite list

becomes the default list for any new SSL sessions (WOLFSSL) created using this

context. The ciphers in the list should be sorted in order of preference from highest to

lowest. Each call to wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the

specific SSL context to the provided list each time the function is called.

The cipher suite list, list, is a null-terminated text string, and a colon-delimited list. For

example, one value for list may be

"DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256"

Valid cipher values are the full name values from the cipher_names[] array in

src/internal.c (for a definite list of valid cipher values check src/internal.c):

RC4-SHA

RC4-MD5

DES-CBC3-SHA

AES128-SHA

AES256-SHA

NULL-SHA

NULL-SHA256

DHE-RSA-AES128-SHA

DHE-RSA-AES256-SHA

PSK-AES128-CBC-SHA256

PSK-AES128-CBC-SHA

PSK-AES256-CBC-SHA

PSK-NULL-SHA256

PSK-NULL-SHA

HC128-MD5

HC128-SHA

HC128-B2B256

AES128-B2B256

AES256-B2B256

RABBIT-SHA

291

QSH

AES128-CCM-8

AES256-CCM-8

ECDHE-ECDSA-AES128-CCM-8

ECDHE-ECDSA-AES256-CCM-8

ECDHE-RSA-AES128-SHA

ECDHE-RSA-AES256-SHA

ECDHE-ECDSA-AES128-SHA

ECDHE-ECDSA-AES256-SHA

ECDHE-RSA-RC4-SHA

ECDHE-RSA-DES-CBC3-SHA

ECDHE-ECDSA-RC4-SHA

ECDHE-ECDSA-DES-CBC3-SHA

AES128-SHA256

AES256-SHA256

DHE-RSA-AES128-SHA256

DHE-RSA-AES256-SHA256

ECDH-RSA-AES128-SHA

ECDH-RSA-AES256-SHA

ECDH-ECDSA-AES128-SHA

ECDH-ECDSA-AES256-SHA

ECDH-RSA-RC4-SHA

ECDH-RSA-DES-CBC3-SHA

ECDH-ECDSA-RC4-SHA

ECDH-ECDSA-DES-CBC3-SHA

AES128-GCM-SHA256

AES256-GCM-SHA384

DHE-RSA-AES128-GCM-SHA256

DHE-RSA-AES256-GCM-SHA384

ECDHE-RSA-AES128-GCM-SHA256

ECDHE-RSA-AES256-GCM-SHA384

ECDHE-ECDSA-AES128-GCM-SHA256

ECDHE-ECDSA-AES256-GCM-SHA384

ECDH-RSA-AES128-GCM-SHA256

ECDH-RSA-AES256-GCM-SHA384

ECDH-ECDSA-AES128-GCM-SHA256

ECDH-ECDSA-AES256-GCM-SHA384

CAMELLIA128-SHA

DHE-RSA-CAMELLIA128-SHA

CAMELLIA256-SHA

292

DHE-RSA-CAMELLIA256-SHA

CAMELLIA128-SHA256

DHE-RSA-CAMELLIA128-SHA256

CAMELLIA256-SHA256

DHE-RSA-CAMELLIA256-SHA256

ECDHE-RSA-AES128-SHA256

ECDHE-ECDSA-AES128-SHA256

ECDH-RSA-AES128-SHA256

ECDH-ECDSA-AES128-SHA256

ECDHE-ECDSA-AES256-SHA384

ECDH-RSA-AES256-SHA384

ECDH-ECDSA-AES256-SHA384

Return Values:

SSL_SUCCESS will be returned upon successful function completion, otherwise

SSL_FAILURE will be returned on failure.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

list - null-terminated text string and a colon-delimited list of cipher suites to use with the

specified SSL context.

Example:

WOLFSSL_CTX* ctx = 0;

...

ret = wolfSSL_CTX_set_cipher_list(ctx,

“DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);

if (ret != SSL_SUCCESS) {

/*failed to set cipher suite list*/

}

See Also:

wolfSSL_set_cipher_list

wolfSSL_CTX_new

293

Synopsis:

#include <wolfssl/ssl.h>

EVP_aes_128_ecb ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_aes_128_ecb(void);

EVP_aes_192_ecb ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_aes_192_ecb(void);

EVP_aes_256_ecb ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_aes_256_ecb(void);

Description:

Getter functions for the respective WOLFSSL_EVP_CIPHER pointers.

wolfSSL_EVP_init() must be called once in the program first to populate these cipher

strings.

Return Values:

Returns a WOLFSSL_EVP_CIPHER pointer.

Parameters:

None

Example:

WOLFSSL_EVP_CIPHER* cipher;

cipher = wolfSSL_EVP_aes_192_ecb();

….

294

See Also:

wolfSSL_EVP_CIPHER_CTX_init

wolfSSL_EVP_CIPHER_block_size

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CIPHER_block_size ->

int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER* cipher);

Description:

This is a getter function for the block size of cipher.

Return Values:

Returns the block size.

Parameters:

cipher - cipher to get block size of.

Example:

printf(“block size = %d\n”,

wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_aes_256_ecb()));

See Also:

wolfSSL_EVP_aes_256_ctr

wolfSSL_EVP_CIPHER_CTX_block_size

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CIPHER_CTX_block_size ->

295

int wolfSSL_EVP_CIPHER_CTX_block_size(const WOLFSSL_EVP_CIPHER_CTX*

ctx);

Description:

This is a getter function for the ctx block size.

Return Values:

Returns ctx->block_size.

Parameters:

ctx - the cipher ctx to get block size of.

Example:

const WOLFSSL_CVP_CIPHER_CTX* ctx;

//set up ctx

printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_CTX_block_size(ctx));

See Also:

wolfSSL_EVP_CIPHER_block_size

wolfSSL_EVP_CIPHER_CTX_set_flags

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CIPHER_CTX_set_flags ->

void wolfSSL_EVP_CIPHER_CTX_set_flags(WOLFSSL_EVP_CIPHER_CTX* ctx, int

flags);

Description:

Setter function for WOLFSSL_EVP_CIPHER_CTX structure.

296

Return Values:

None

Parameters:

ctx - structure to set flag.

flag - flag to set in structure.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx;

int flag;

// create ctx

wolfSSL_EVP_CIPHER_CTX_set_flags(ctx, flag);

See Also:

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_set_key_length

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CIPHER_CTX_set_key_length ->

int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* ctx,

int keylen);

Description:

Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length.

Return Values:

SSL_SUCCESS: If successfully set.

SSL_FAILURE: If failed to set key length/

297

Parameters:

ctx - structure to set key length.

keylen - key length.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx;

int keylen;

// create ctx

wolfSSL_EVP_CIPHER_CTX_set_key_length(ctx, keylen);

See Also:

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_set_padding

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CIPHER_CTX_set_padding ->

int wolfSSL_EVP_CIPHER_CTX_set_padding(WOLFSSL_EVP_CIPHER_CTX* ctx, int

padding);

Description:

Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding.

Return Values:

SSL_SUCCESS: If successfully set.

BAD_FUNC_ARG: If null argument passed in.

Parameters:

ctx - structure to set padding flag.

298

padding - 0 for not setting padding, 1 for setting padding.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx;

// create ctx

wolfSSL_EVP_CIPHER_CTX_set_padding(ctx, 1);

See Also:

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CipherFinal

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CipherFinal ->

int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX* ctx, unsigned char* out,

int* out1);

Description:

This function performs the final cipher operations adding in padding. If

WOLFSSL_EVP_CIPH_NO_PADDING flag is set in WOLFSSL_EVP_CIPHER_CTX

structure then 1 is returned and no encryption/decryption is done. If padding flag is seti

padding is added and encrypted when ctx is set to encrypt, padding values are checked

when set to decrypt.

Return Values:

1:Returned on success

0: If encountering a failure.

Parameters:

ctx - structure to decrypt/encrypt with.

299

out - buffer for final decrypt/encrypt.

out1 - size of out buffer when data has been added by function.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx;

int out1;

unsigned char out[64];

// create ctx

wolfSSL_EVP_CipherFinal(ctx, out, &out1);

See Also:

wolfSSL_EVP_CIPHER_CTX_new

wolfSSL_CipherInit_ex

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CipherInit_ex ->

int wolfSSL_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, const

WOLFSSL_EVP_CIPHER* type, WOLFSSL_ENGINE* impl, unsigned char* key,

unsigned char* iv, int enc);

Description:

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for

wolfSSL_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE.

Return Values:

SSL_SUCCESS: If successfully set.

SSL_FAILURE: If not successful.

Parameters:

ctx - structure to initialize.

300

type - type of encryption/decryption to do, for example AES.

impl - engine to use. N/A for wolfSSL, can be NULL.

key - key to set .

iv - iv if needed by algorithm.

enc - encryption (1) or decryption (0) flag.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;

WOLFSSL_ENGINE* e = NULL;

unsigned char key[16];

unsigned char iv[12];

wolfCrypt_Init();

ctx = wolfSSL_EVP_CIPHER_CTX_new();

if (ctx == NULL) {

printf("issue creating ctx\n");

return -1;

}

printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL,

EVP_aes_128_ cbc(), e, key, iv, 1));

printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx,

EVP_aes_128_c bc(), e, key, iv, 1));

// free resources

See Also:

wolfSSL_EVP_CIPHER_CTX_new, wolfCrypt_Init, wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_CipherUpdate

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_CipherUpdate ->

301

int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX* ctx, unsigned char*

out, int *outl, const unsigned char* in, int inl);

Description:

Function for encrypting/decrypting data. In buffer is added to be encrypted or decrypted

and out buffer holds the results. outl will be the length of encrypted/decrypted

information.

Return Values:

SSL_SUCCESS: If successfull.

SSL_FAILURE: If not successful.

Parameters:

ctx - structure to get cipher type from.

out - buffer to hold output.

outl - adjusted to be size of output.

in - buffer to perform operation on.

inl - length of input buffer.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;

unsigned char out[100];

int outl;

unsigned char in[100];

int inl = 100;

ctx = wolfSSL_EVP_CIPHER_CTX_new();

// set up ctx

ret = wolfSSL_EVP_CipherUpdate(ctx, out, outl, in, inl);

// check ret value

// buffer out holds outl bytes of data

// free resources

302

See Also:

wolfSSL_EVP_CIPHER_CTX_new, wolfCrypt_Init, wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_DecryptInit_ex

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_DecryptInit_ex ->

int wolfSSL_EVP_DecryptInit_ex

Description:

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for

wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets

encrypt flag to be decrypt.

Return Values:

SSL_SUCCESS: If successfully set.

SSL_FAILURE: If not successful.

Parameters:

ctx - structure to initialize.

type - type of encryption/decryption to do, for example AES.

impl - engine to use. N/A for wolfSSL, can be NULL.

key - key to set .

iv - iv if needed by algorithm.

enc - encryption (1) or decryption (0) flag.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;

303

WOLFSSL_ENGINE* e = NULL;

unsigned char key[16];

unsigned char iv[12];

wolfCrypt_Init();

ctx = wolfSSL_EVP_CIPHER_CTX_new();

if (ctx == NULL) {

printf("issue creating ctx\n");

return -1;

}

printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL,

EVP_aes_128_ cbc(), e, key, iv, 1));

printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx,

EVP_aes_128_c bc(), e, key, iv, 1));

// free resources

See Also:

wolfSSL_EVP_CIPHER_CTX_new, wolfCrypt_Init, wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_des_cbc, wolfSSL_EVP_des_ecb

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_des_cbc ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void);

EVP_des_ecb ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ecb(void);

304

Description:

Getter functions for the respective WOLFSSL_EVP_CIPHER pointers.

wolfSSL_EVP_init() must be called once in the program first to populate these cipher

strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ecb().

Return Values:

Returns a WOLFSSL_EVP_CIPHER pointer for DES operations.

Parameters:

None

Example:

WOLFSSL_EVP_CIPHER* cipher;

cipher = wolfSSL_EVP_des_ecb();

….

See Also:

wolfSSL_EVP_CIPHER_CTX_init

wolfSSL_EVP_des_cbc, wolfSSL_EVP_des_ecb

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_des_ede3_cbc ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede_cbc(void);

EVP_des_ede3_ecb ->

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void);

305

Description:

Getter functions for the respective WOLFSSL_EVP_CIPHER pointers.

wolfSSL_EVP_init() must be called once in the program first to populate these cipher

strings. WOLFSSL_DES_ECB macro must be defined for

wolfSSL_EVP_des_ede3_ecb().

Return Values:

Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations.

Parameters:

None

Example:

printf("block size des ede3 cbc = %d\n",

wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc()));

printf("block size des ede3 ecb = %d\n",

wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_ecb()));

See Also:

wolfSSL_EVP_CIPHER_CTX_init

wolfSSL_EVP_DigestInit_ex

Synopsis:

#include <wolfssl/openssl/evp.h>

EVP_DigestInit_ex ->

int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx, const

WOLFSSL_EVP_MD* type, WOLFSSL_ENGINE* impl);

Description:

306

Function for initializing WOLFSSL_EVP_MD_CTX. This function is a wrapper for

wolfSSL_EVP_DigestInit() because wolfSSL does not use WOLFSSL_ENGINE.

Return Values:

SSL_SUCCESS: If successfully set.

SSL_FAILURE: If not successful.

Parameters:

ctx - structure to initialize.

type - type of hash to do, for example SHA.

impl - engine to use. N/A for wolfSSL, can be NULL.

Example:

WOLFSSL_EVP_MD_CTX* md = NULL;

wolfCrypt_Init();

md = wolfSSL_EVP_MD_CTX_new();

if (md == NULL) {

printf("error setting md\n");

return -1;

}

printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md,

wolfSSL_EVP_sha1(), e));

//free resources

See Also:

wolfSSL_EVP_MD_CTX_new, wolfCrypt_Init, wolfSSL_EVP_MD_CTX_free

wolfSSL_EVP_EncryptInit_ex

Synopsis:

#include <wolfssl/openssl/evp.h>

307

EVP_EncryptInit_ex ->

int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, const

WOLFSSL_EVP_Cipher* type, WOLFSSL_ENGINE* impl, unsigned char* key,

unsigned char* iv);

Description:

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for

wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets

encrypt flag to be encrypt.

Return Values:

SSL_SUCCESS: If successfully set.

SSL_FAILURE: If not successful.

Parameters:

ctx - structure to initialize.

type - type of encryption to do, for example AES.

impl - engine to use. N/A for wolfSSL, can be NULL.

key - key to use.

iv - iv to use.

Example:

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;

wolfCrypt_Init();

ctx = wolfSSL_EVP_CIPHER_CTX_new();

if (ctx == NULL) {

printf("error setting ctx\n");

return -1;

}

308

printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx,

wolfSSL_EVP_aes_128_cbc(), e, key, iv));

//free resources

See Also:

wolfSSL_EVP_CIPHER_CTX_new, wolfCrypt_Init, wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_set_compression

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_set_compression(WOLFSSL* ssl);

Description:

Turns on the ability to use compression for the SSL connection. Both sides must have

compression turned on otherwise compression will not be used. The zlib library

performs the actual data compression. To compile into the library use --with-libz for the

configure system and define HAVE_LIBZ otherwise.

Keep in mind that 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.

Return Values:

If successful the call will return SSL_SUCCESS.

NOT_COMPILED_IN will be returned if compression support wasn’t built into the library.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret = 0;

309

WOLFSSL* ssl = 0;

...

ret = wolfSSL_set_compression(ssl);

if (ret == SSL_SUCCESS) {

/*successfully enabled compression for SSL session*/

}

See Also:

wolfSSL_set_fd

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_set_fd(WOLFSSL* ssl, int fd);

Description:

This function assigns a file descriptor (fd) as the input/output facility for the SSL

connection. Typically this will be a socket file descriptor.

Return Values:

If successful the call will return SSL_SUCCESS, otherwise, Bad_FUNC_ARG will be

returned.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

fd - file descriptor to use with SSL/TLS connection.

Example:

int sockfd;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_set_fd(ssl, sockfd);

if (ret != SSL_SUCCESS) {

/*failed to set SSL file descriptor*/

310

}

See Also:

wolfSSL_SetIOSend

wolfSSL_SetIORecv

wolfSSL_SetIOReadCtx

wolfSSL_SetIOWriteCtx

wolfSSL_set_group_messages

Synopsis:

int wolfSSL_set_group_messages(WOLFSSL* ssl);

Description:

This function turns on grouping of handshake messages where possible.

Return Values:

SSL_SUCCESS will be returned upon success.

BAD_FUNC_ARG will be returned if the input context is null.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

WOLFSSL* ssl = 0;

...

ret = wolfSSL_set_group_messages(ssl);

if (ret != SSL_SUCCESS) {

// failed to set handshake message grouping

}

See Also:

wolfSSL_CTX_set_group_messages

wolfSSL_new

311

wolfSSL_CTX_set_group_messages

Synopsis:

int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX* ctx);

Description:

This function turns on grouping of handshake messages where possible.

Return Values:

SSL_SUCCESS will be returned upon success.

BAD_FUNC_ARG will be returned if the input context is null.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = 0;

...

ret = wolfSSL_CTX_set_group_messages(ctx);

if (ret != SSL_SUCCESS) {

/*failed to set handshake message grouping*/

}

See Also:

wolfSSL_set_group_messages

wolfSSL_CTX_new

wolfSSL_set_session

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_set_session(WOLFSSL* ssl, WOLFSSL_SESSION* session);

312

Description:

This function sets the session to be used when the SSL object, ssl, is used to establish

a SSL/TLS connection.

For session resumption, before calling wolfSSL_shutdown() with your session object, an

application should save the session ID from the object with a call to

wolfSSL_get_session(), which returns a pointer to the session. Later, the application

should create a new WOLFSSL object and assign the saved session with

wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and

wolfSSL will try to resume the session. The wolfSSL server code allows session

resumption by default.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

SSL_FAILURE will be returned on failure. This could be caused by the session cache

being disabled, or if the session has timed out.

Parameters:

ssl - pointer to the SSL object, created with wolfSSL_new().

session - pointer to the WOLFSSL_SESSION used to set the session for ssl.

Example:

int ret = 0;

WOLFSSL* ssl = 0;

WOLFSSL_SESSION* session;

...

ret = wolfSSL_get_session(ssl, session);

if (ret != SSL_SUCCESS) {

/*failed to set the SSL session*/

}

...

See Also:

313

wolfSSL_get_session

wolfSSL_CTX_set_session_cache_mode

Synopsis:

long wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX* ctx, long mode);

Description:

This function enables or disables SSL session caching. Behavior depends on the value

used for mode. The following values for mode are available:

SSL_SESS_CACHE_OFF

- disable session caching. Session caching is turned on by default.

SSL_SESS_CACHE_NO_AUTO_CLEAR

- Disable auto-flushing of the session cache. Auto-flushing is turned on by

default.

Return Values:

SSL_SUCCESS will be returned upon success.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

mode - modifier used to change behavior of the session cache.

Example:

WOLFSSL_CTX* ctx = 0;

...

ret = wolfSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);

if (ret != SSL_SUCCESS) {

/*failed to turn SSL session caching off*/

}

See Also:

wolfSSL_flush_sessions

wolfSSL_get_session

314

wolfSSL_set_session

wolfSSL_get_sessionID

wolfSSL_CTX_set_timeout

wolfSSL_set_timeout

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_set_timeout(WOLFSSL* ssl, unsigned int to);

Description:

This function sets the SSL session timeout value in seconds.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

BAD_FUNC_ARG will be returned if ssl is NULL.

Parameters:

ssl - pointer to the SSL object, created with wolfSSL_new().

to - value, in seconds, used to set the SSL session timeout.

Example:

int ret = 0;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_set_timeout(ssl, 500);

if (ret != SSL_SUCCESS) {

/*failed to set session timeout value*/

}

...

See Also:

wolfSSL_get_session

wolfSSL_set_session

315

wolfSSL_CTX_set_timeout

Synopsis:

int wolfSSL_CTX_set_timeout(WOLFSSL_CTX* ctx, unsigned int to);

Description:

This function sets the timeout value for SSL sessions, in seconds, for the specified SSL

context.

Return Values:

SSL_SUCCESS will be returned upon success.

BAD_FUNC_ARG will be returned when the input context (ctx) is null.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

to - session timeout value in seconds

Example:

WOLFSSL_CTX* ctx = 0;

...

ret = wolfSSL_CTX_set_timeout(ctx, 500);

if (ret != SSL_SUCCESS) {

/*failed to set session timeout value*/

}

See Also:

wolfSSL_flush_sessions

wolfSSL_get_session

wolfSSL_set_session

wolfSSL_get_sessionID

wolfSSL_CTX_set_session_cache_mode

316

wolfSSL_set_using_nonblock

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_set_using_nonblock(WOLFSSL* ssl, int nonblock);

Description:

This function informs the WOLFSSL object that the underlying I/O is non-blocking.

After an application creates a WOLFSSL object, if it will be used with a non-blocking

socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know

that receiving EWOULDBLOCK means that the recvfrom call would block rather than

that it timed out.

Return Values:

This function does not have a return value.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

nonblock - value used to set non-blocking flag on WOLFSSL object. Use 1 to specify

non-blocking, otherwise 0.

Example:

WOLFSSL* ssl = 0;

...

wolfSSL_set_using_nonblock(ssl, 1);

See Also:

wolfSSL_get_using_nonblock

wolfSSL_dtls_got_timeout

wolfSSL_dtls_get_current_timeout

317

wolfSSL_set_verify

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_set_verify(WOLFSSL* ssl, int mode, VerifyCallback vc);

typedef int (*VerifyCallback)(int, WOLFSSL_X509_STORE_CTX*);

Description:

This function sets the verification method for remote peers and also allows a verify

callback to be registered with the SSL session. The verify callback will be called only

when a verification failure has occurred. If no verify callback is desired, the NULL

pointer can be used for verify_callback.

The verification mode of peer certificates is a logically OR’d list of flags. The possible

flag values include:

SSL_VERIFY_NONE

Client mode: the client will not verify the certificate received from the server and

the handshake will continue as normal.

Server mode: the server will not send a certificate request to the client. As

such, client verification will not be enabled.

SSL_VERIFY_PEER

Client mode: the client will verify the certificate received from the server during

the handshake. This is turned on by default in wolfSSL, therefore, using this

option has no effect.

Server mode: the server will send a certificate request to the client and verify the

client certificate received.

SSL_VERIFY_FAIL_IF_NO_PEER_CERT

Client mode: no effect when used on the client side.

Server mode: the verification will fail on the server side if the client fails to send

318

a certificate when requested to do so (when using SSL_VERIFY_PEER on the

SSL server).

SSL_VERIFY_FAIL_EXCEPT_PSK

Client mode: no effect when used on the client side.

Server mode: the verification is the same as

SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK

connection. If a PSK connection is being made then the connection will go

through without a peer cert.

Return Values:

This function has no return value.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

mode - session timeout value in seconds

verify_callback - callback to be called when verification fails. If no callback is desired,

the NULL pointer can be used for verify_callback.

Example:

WOLFSSL* ssl = 0;

...

wolfSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT,

0);

See Also:

wolfSSL_CTX_set_verify

319

Synopsis:

void wolfSSL_CTX_set_verify(WOLFSSL_CTX* ctx, int mode,

VerifyCallback vc);

typedef int (*VerifyCallback)(int, WOLFSSL_X509_STORE_CTX*);

Description:

This function sets the verification method for remote peers and also allows a verify

callback to be registered with the SSL context. The verify callback will be called only

when a verification failure has occurred. If no verify callback is desired, the NULL

pointer can be used for verify_callback.

The verification mode of peer certificates is a logically OR’d list of flags. The possible

flag values include:

SSL_VERIFY_NONE

Client mode: the client will not verify the certificate received from the server and

the handshake will continue as normal.

Server mode: the server will not send a certificate request to the client. As

such, client verification will not be enabled.

SSL_VERIFY_PEER

Client mode: the client will verify the certificate received from the server during

the handshake. This is turned on by default in wolfSSL, therefore, using this

option has no effect.

Server mode: the server will send a certificate request to the client and verify the

client certificate received.

SSL_VERIFY_FAIL_IF_NO_PEER_CERT

Client mode: no effect when used on the client side.

Server mode: the verification will fail on the server side if the client fails to send

a certificate when requested to do so (when using SSL_VERIFY_PEER on the

SSL server).

320

SSL_VERIFY_FAIL_EXCEPT_PSK

Client mode: no effect when used on the client side.

Server mode: the verification is the same as

SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK

connection. If a PSK connection is being made then the connection will go

through without a peer cert.

Return Values:

This function has no return value.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

mode - session timeout value in seconds

verify_callback - callback to be called when verification fails. If no callback is desired,

the NULL pointer can be used for verify_callback.

Example:

WOLFSSL_CTX* ctx = 0;

...

wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_PEER |

SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);

See Also:

wolfSSL_set_verify

wolfSSL_CTX_get_verify_depth

Synopsis:

#include <wolfssl/ssl.h>

321

long wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX* ctx);

Description:

This function gets the certificate chaining depth using the CTX structure.

Return Values:

MAX_CHAIN_DEPTH - returned if the CTX struct is not NULL. The constant

representation of the max certificate chain peer depth.

BAD_FUNC_ARG - returned if the CTX structure is NULL.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_METHOD method; /*protocol method*/

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);

…

long ret = wolfSSL_CTX_get_verify_depth(ctx);

if(ret == EXPECTED){

/*You have the expected value*/

} else {

/*Handle an unexpected depth*/

}

See Also:

wolfSSL_CTX_use_certificate_chain_file

wolfSSL_get_verify_depth

wolfSSL_CTX_UnloadCAs

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX* ctx);

322

Description:

This function unloads the CA signer list and frees the whole signer table.

Return Values:

SSL_SUCCESS - returned on successful execution of the function.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX struct is NULL or there are

otherwise unpermitted argument values passed in a subroutine.

BAD_MUTEX_E - returned if there was a mutex error. The LockMutex() did not return

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_METHOD method = wolfTLSv1_2_client_method();

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);

…

if(!wolfSSL_CTX_UnloadCAs(ctx)){

/*The function did not unload CAs*/

}

See Also:

wolfSSL_CertManagerUnloadCAs

LockMutex

FreeSignerTable

UnlockMutex

wolfSSL_dtls_set_timeout_init

Synopsis:

#include <wolfssl/ssl.h>

323

int wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int timeout);

Description:

This function sets the dtls timeout.

Return Values:

SSL_SUCCESS - returned if the function executes without an error. The

dtls_timeout_init and the dtls_timeout members of SSL have been set.

BAD_FUNC_ARG - returned if the WOLFSSL struct is NULL or if the timeout is not

greater than 0. It will also return if the timeout argument exceeds the maximum value

allowed.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

timeout - an int type that will be set to the dtls_timeout_init member of the WOLFSSL

structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int timeout = TIMEOUT; /*timeout value*/

...

if(wolfSSL_dtls_set_timeout_init(ssl, timeout)){

/*the dtls timeout was set*/

} else {

/*Failed to set DTLS timeout. */

}

See Also:

wolfSSL_dtls_set_timeout_max

wolfSSL_dtls_got_timeout

wolfSSL_GetCookieCtx

Synopsis:

#include <wolfssl/ssl.h>

324

void* wolfSSL_GetCookieCtx(WOLFSSL* ssl);

Description:

This function returns the IOCB_CookieCtx member of the WOLFSSL structure.

Return Values:

The function returns a void pointer value stored in the IOCB_CookieCtx.

NULL - if the WOLFSSL struct is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

void* cookie;

...

cookie = wolfSSL_GetCookieCtx(ssl);

if(cookie != NULL){

/*You have the cookie */

}

See Also:

wolfSSL_SetCookieCtx

wolfSSL_CTX_SetGenCookie

wolfSSL_CTX_UseSessionTicket

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx)

Description:

This function sets wolfSSL context to use a session ticket.

325

Return Values:

SSL_SUCCESS: Function executed successfully.

BAD_FUNC_ARG: Returned if ctx is null.

MEMORY_E: Error allocating memory in internal function.

Parameters:

ctx - The WOLFSSL_CTX structure to use.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS)

{

/* Error setting session ticket */

}

See Also:

TLSX_UseSessionTicket

wolfSSL_UseSupportedQSH

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseSupportedQSH(WOLFSSL* ssl, word16 name)

Description:

This function sets the ssl session to use supported QSH provided by name.

326

Return Values:

SSL_SUCCESS: Successfully set supported QSH.

BAD_FUNC_ARG: ssl is null or name is invalid.

MEMORY_E: Error allocating memory for operation.

Parameters:

ssl - Pointer to ssl session to use.

name - Name of a supported QSH. Valid names are WOLFSSL_NTRU_EESS439,

WOLFSSL_NTRU_EESS593, or WOLFSSL_NTRU_EESS743.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

word16 qsh_name = WOLFSSL_NTRU_EESS439;

if(wolfSSL_UseSupportedQSH(ssl,qsh_name) != SSL_SUCCESS)

{

/* Error setting QSH */

}

See Also:

TLSX_UseQSHScheme

wolfSSL_UseALPN

Synopsis:

327

#include <wolfssl/ssl.h>

int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list,

word32 protocol_name_listSz, byte options)

Description:

Setup ALPN use for a wolfSSL session.

Return Values:

SSL_SUCCESS: Success

BAD_FUNC_ARG: Returned if ssl or protocol_name_list is null or

protocol_name_listSz is too large or options contain something not supported.

MEMORY_ERROR: Error allocating memory for protocol list.

SSL_FAILURE: Error

Parameters:

ssl - The wolfSSL session to use.

protocol_name_list - List of protocol names to use. Comma delimited string is

required.

protocol_name_listSz - Size of the list of protocol names.

options - WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or

WOLFSSL_ALPN_FAILED_ON_MISMATCH.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

char alpn_list[] = { /* ALPN List */ }

328

if(wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list),

WOLFSSL_APN_FAILED_ON_MISMATCH) != SSL_SUCCESS)

{

/* Error setting session ticket */

}

See Also:

TLSX_UseALPN

wolfSSL_CTX_trust_peer_cert

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX* ctx, const char* file,

int type);

Description:

This function loads a certificate to use for verifying a peer when performing a TLS/SSL

handshake. The peer certificate sent during the handshake is compared by using the

SKID when available and the signature. If these two things do not match then any

loaded CAs are used.

Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

329

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

file - pointer to name of the file containing certificates

type - type of certificate being loaded ie SSL_FILETYPE_ASN1 or

SSL_FILETYPE_PEM.

Example:

int ret = 0;

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

...

ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

/* error loading trusted peer cert */

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_file

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_file

wolfSSL_CTX_trust_peer_buffer

wolfSSL_CTX_Unload_trust_peers

330

wolfSSL_use_certificate_file

wolfSSL_use_PrivateKey_file

wolfSSL_use_certificate_chain_file

wolfSSL_CTX_trust_peer_buffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX* ctx, const unsigned char* buffer,

long sz, int type);

Description:

This function loads a certificate to use for verifying a peer when performing a TLS/SSL

handshake. The peer certificate sent during the handshake is compared by using the

SKID when available and the signature. If these two things do not match then any

loaded CAs are used. Is the same functionality as wolfSSL_CTX_trust_peer_cert except

is from a buffer instead of a file.

Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT

Please see the examples for proper usage.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

331

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

buffer - pointer to the buffer containing certificates

sz - length of the buffer input

type - type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or

SSL_FILETYPE_PEM.

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

...

ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error loading trusted peer cert

}

...

See Also:

wolfSSL_CTX_load_verify_buffer

wolfSSL_CTX_use_certificate_file

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_CTX_use_NTRUPrivateKey_file

wolfSSL_CTX_use_certificate_chain_file

wolfSSL_CTX_trust_peer_cert

wolfSSL_CTX_Unload_trust_peers

wolfSSL_use_certificate_file

wolfSSL_use_PrivateKey_file

332

wolfSSL_use_certificate_chain_file

wolfSSL_CTX_Unload_trust_peers

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX* ctx);

Description:

This function is used to unload all previously loaded trusted peer certificates.

Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT.

Return Values:

If successful the call will return SSL_SUCCESS.

BAD_FUNC_ARG will be returned if ctx is NULL.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

Example:

int ret = 0;

WOLFSSL_CTX* ctx;

333

...

ret = wolfSSL_CTX_Unload_trust_peers(ctx);

if (ret != SSL_SUCCESS) {

// error unloading trusted peer certs

}

...

See Also:

wolfSSL_CTX_trust_peer_buffer

wolfSSL_CTX_trust_peer_cert

wolfSSL_CTX_allow_anon_cipher

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX* ctx);

Description:

This function enables the havAnon member of the CTX structure if HAVE_ANON is

defined during compilation.

Return Values:

SSL_SUCCESS - returned if the function executed successfully and the haveAnnon

member of the CTX is set to 1.

SSL_FAILURE - returned if the CTX structure was NULL.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

334

#ifdef HAVE_ANON

if(cipherList == NULL){

wolfSSL_CTX_allow_anon_cipher(ctx);

if(wolfSSL_CTX_set_cipher_list(ctx, “ADH_AES128_SHA”) !=

SSL_SUCCESS){

/*failure case*/

}

#endif

See Also:

wolfSSL_CTX_memrestore_cert_cache

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_memrestore_cert_cache(WOLFSSL* ssl);

Description:

This function restores the certificate cache from memory.

Return Values:

SSL_SUCCESS - returned if the function and subroutines executed without an error.

BAD_FUNC_ARG - returned if the ctx or mem parameters are NULL or if the sz

parameter is less than or equal to zero.

BUFFER_E - returned if the cert cache memory buffer is too small.

CACHE_MATCH_ERROR - returned if there was a cert cache header mismatch.

BAD_MUTEX_E - returned if the lock mutex on failed.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

mem - a void pointer with a value that will be restored to the certificate cache.

335

sz - an int type that represents the size of the mem parameter.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

void* mem;

int sz = (*int) sizeof(mem);

…

if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){

/*The success case*/

}

See Also:

CM_MemRestoreCertCache

wolfSSL_CTX_SetMinVersion

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version);

Description:

This function sets the minimum downgrade version allowed. Applicable only when the

connection allows downgrade using (wolfSSLv23_client_method or

wolfSSLv23_server_method).

Return Values:

SSL_SUCCESS - returned if the function returned without error and the minimum

version is set.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure was NULL or if the

minimum version is not supported.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

version - an integer representation of the version to be set as the minimum:

336

WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or

WOLFSSL_TLSV1_2 = 3.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

int version; /*macro representation */

…

if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){

/*Failed to set min version*/

}

See Also:

SetMinVersionHelper

17.4 Callbacks

The functions in this section have to do with callbacks which the application is able to

set in relation to wolfSSL.

wolfSSL_SetIOReadCtx

Synopsis:

void wolfSSL_SetIOReadCtx(WOLFSSL* ssl, void *rctx);

Description:

This function registers a context for the SSL session’s receive callback function. By

default, wolfSSL sets the file descriptor passed to wolfSSL_set_fd() as the context when

wolfSSL is using the system’s TCP library. If you’ve registered your own receive

callback you may want to set a specific context for the session. For example, if you’re

using memory buffers the context may be a pointer to a structure describing where and

how to access the memory buffers.

Return Values:

No return values are used for this function.

Parameters:

337

ssl - pointer to the SSL session, created with wolfSSL_new().

rctx - pointer to the context to be registered with the SSL session’s (ssl) receive

callback function.

Example:

int sockfd;

WOLFSSL* ssl = 0;

...

/*Manually setting the socket fd as the receive CTX, for example*/

wolfSSL_SetIOReadCtx(ssl, &sockfd);

...

See Also:

wolfSSL_SetIORecv

wolfSSL_SetIOSend

wolfSSL_SetIOWriteCtx

Synopsis:

void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *wctx);

Description:

This function registers a context for the SSL session’s send callback function. By

default, wolfSSL sets the file descriptor passed to wolfSSL_set_fd() as the context when

wolfSSL is using the system’s TCP library. If you’ve registered your own send callback

you may want to set a specific context for the session. For example, if you’re using

memory buffers the context may be a pointer to a structure describing where and how to

access the memory buffers.

Return Values:

No return values are used for this function.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

wctx - pointer to the context to be registered with the SSL session’s (ssl) send callback

338

function.

Example:

int sockfd;

WOLFSSL* ssl = 0;

...

/*Manually setting the socket fd as the send CTX, for example*/

wolfSSL_SetIOSendCtx(ssl, &sockfd);

...

See Also:

wolfSSL_SetIORecv

wolfSSL_SetIOSend

wolfSSL_SetIOReadCtx

wolfSSL_SetIOReadFlags

Synopsis:

void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);

Description:

This function sets the flags for the receive callback to use for the given SSL session.

The receive callback could be either the default wolfSSL EmbedReceive callback, or a

custom callback specified by the user (see wolfSSL_SetIORecv). The default flag value

is set internally by wolfSSL to the value of 0.

The default wolfSSL receive callback uses the recv() function to receive data from the

socket. From the recv() man page:

“The flags argument to a recv() function is formed by or'ing one or more of the values:

MSG_OOB process out-of-band data

MSG_PEEK peek at incoming message

MSG_WAITALL wait for full request or error

The MSG_OOB flag requests receipt of out-of-band data that would not be received in

the normal data stream. Some protocols place expedited data at the head of the normal

data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK

339

flag causes the receive operation to return data from the beginning of the receive queue

without removing that data from the queue. Thus, a subsequent receive call will return

the same data. The MSG_WAITALL flag requests that the operation block until the full

request is satisfied. However, the call may still return less data than requested if a

signal is caught, an error or disconnect occurs, or the next data to be received is of a

different type than that returned.”

Return Values:

No return values are used for this function.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

flags - value of the I/O read flags for the specified SSL session (ssl).

Example:

WOLFSSL* ssl = 0;

...

/*Manually setting recv flags to 0*/

wolfSSL_SetIOReadFlags(ssl, 0);

...

See Also:

wolfSSL_SetIORecv

wolfSSL_SetIOSend

wolfSSL_SetIOReadCtx

wolfSSL_SetIOWriteFlags

Synopsis:

void wolfSSL_SetIOWriteFlags( WOLFSSL* ssl, int flags);

Description:

This function sets the flags for the send callback to use for the given SSL session. The

send callback could be either the default wolfSSL EmbedSend callback, or a custom

callback specified by the user (see wolfSSL_SetIOSend). The default flag value is set

internally by wolfSSL to the value of 0.

The default wolfSSL send callback uses the send() function to send data from the

340

socket. From the send() man page:

“The flags parameter may include one or more of the following:

#define MSG_OOB 0x1 /* process out-of-band data */

#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */

The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this

notion (e.g. SOCK_STREAM); the underlying protocol must also support ``out-of-band''

data. MSG_DONTROUTE is usually used only by diagnostic or routing programs.”

Return Values:

No return values are used for this function.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

flags - value of the I/O send flags for the specified SSL session (ssl).

Example:

WOLFSSL* ssl = 0;

...

/*Manually setting send flags to 0*/

wolfSSL_SetIOSendFlags(ssl, 0);

...

See Also:

wolfSSL_SetIORecv

wolfSSL_SetIOSend

wolfSSL_SetIOReadCtx

wolfSSL_SetIORecv

Synopsis:

void wolfSSL_SetIORecv(WOLFSSL_CTX* ctx, CallbackIORecv CBIORecv);

typedef int (*CallbackIORecv)(WOLFSSL* ssl, char* buf, int sz, void* ctx);

Description:

341

This function registers a receive callback for wolfSSL to get input data. By default,

wolfSSL uses EmbedReceive() as the callback which uses the system’s TCP recv()

function. The user can register a function to get input from memory, some other

network module, or from anywhere. Please see the EmbedReceive() function in

src/io.c as a guide for how the function should work and for error codes. In particular,

IO_ERR_WANT_READ should be returned for non blocking receive when no data is

ready.

Return Values:

No return values are used for this function.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

callback - function to be registered as the receive callback for the wolfSSL context, ctx.

The signature of this function must follow that as shown above in the Synopsis section.

Example:

WOLFSSL_CTX* ctx = 0;

/*Receive callback prototype*/

int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);

/*Register the custom receive callback with wolfSSL*/

wolfSSL_SetIORecv(ctx, MyEmbedReceive);

int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx)

{

/*custom EmbedReceive function*/

}

See Also:

wolfSSL_SetIOSend

wolfSSL_SetIOReadCtx

wolfSSL_SetIOWriteCtx

wolfSSL_SetIOSend

Synopsis:

void wolfSSL_SetIOSend(WOLFSSL_CTX* ctx, CallbackIOSend CBIOSend);

342

typedef int (*CallbackIOSend)(WOLFSSL* ssl, char* buf, int sz, void* ctx);

Description:

This function registers a send callback for wolfSSL to write output data. By default,

wolfSSL uses EmbedSend() as the callback which uses the system’s TCP send()

function. The user can register a function to send output to memory, some other

network module, or to anywhere. Please see the EmbedSend() function in src/io.c as a

guide for how the function should work and for error codes. In particular,

IO_ERR_WANT_WRITE should be returned for non blocking send when the action

cannot be taken yet.

Return Values:

No return values are used for this function.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

callback - function to be registered as the send callback for the wolfSSL context, ctx.

The signature of this function must follow that as shown above in the Synopsis section.

Example:

WOLFSSL_CTX* ctx = 0;

/*Receive callback prototype*/

int MyEmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx);

/*Register the custom receive callback with wolfSSL*/

wolfSSL_SetIOSend(ctx, MyEmbedSend);

int MyEmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx)

{

/*custom EmbedSend function*/

}

See Also:

wolfSSL_SetIORecv

wolfSSL_SetIOReadCtx

wolfSSL_SetIOWriteCtx

343

wolfSSL_CTX_set_TicketEncCb

Synopsis:

#include <wolfssl/ssl.h>

typedef int (*SessionTicketEncCb)(WOLFSSL*,

unsigned char key_name[WOLFSSL_TICKET_NAME_SZ],

unsigned char iv[WOLFSSL_TICKET_IV_SZ],

unsigned char mac[WOLFSSL_TICKET_MAC_SZ],

int enc, unsigned char* ticket, int inLen, int* outLen, void* userCtx);

int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx, SessionTicketEncCb);

Description:

This function sets the session ticket key encrypt callback function for a server to support

session tickets as specified in RFC 5077.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid

arguments to the function.

Parameters:

ctx - pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().

cb - user callback function to encrypt/decrypt session tickets

Callback Parameters:

ssl - pointer to the WOLFSSL object, created with wolfSSL_new()

key_name - unique key name for this ticket context, should be randomly generated

iv - unique IV for this ticket, up to 128 bits, should be randomly generated

344

mac - up to 256 bit mac for this ticket

enc - if this encrypt parameter is true the user should fill in key_name, iv, mac, and

encrypt the ticket in-place of length inLen and set the resulting output length in *outLen.

Returning WOLFSSL_TICKET_RET_OK tells wolfSSL that the encryption was

successful. If this encrypt parameter is false, the user should perform a decrypt of the

ticket in-place of length inLen using key_name, iv, and mac. The resulting decrypt

length should be set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL

to proceed using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE

tells wolfSSL to use the decrypted ticket but also to generate a new one to send to the

client, helpful if recently rolled keys and don’t want to force a full handshake. Returning

WOLFSSL_TICKET_RET_REJECT tells wolfSSL to reject this ticket, perform a full

handshake, and create a new standard session ID for normal session resumption.

Returning WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection

attempt with a fatal error.

ticket - the input/output buffer for the encrypted ticket. See the enc parameter

inLen - the input length of the ticket parameter

outLen - the resulting output length of the ticket parameter. When entering the callback

outLen will indicate the maximum size available in the ticket buffer.

userCtx - the user context set with wolfSSL_CTX_set_TicketEncCtx()

Example:

See wolfssl/test.h myTicketEncCb() used by the example server and example

echoserver.

See Also:

wolfSSL_CTX_set_TicketHint

wolfSSL_CTX_set_TicketEncCtx

wolfSSL_CTX_set_TicketEncCb

Synopsis:

#include <wolfssl/ssl.h>

typedef int (*SessionTicketEncCb)(WOLFSSL*,

345

unsigned char key_name[WOLFSSL_TICKET_NAME_SZ],

unsigned char iv[WOLFSSL_TICKET_IV_SZ],

unsigned char mac[WOLFSSL_TICKET_MAC_SZ],

int enc, unsigned char* ticket, int inLen, int* outLen, void* userCtx);

int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx, SessionTicketEncCb);

Description:

This function sets the session ticket key encrypt callback function for a server to support

session tickets as specified in RFC 5077.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid

arguments to the function.

Parameters:

ctx - pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().

cb - user callback function to encrypt/decrypt session tickets

Callback Parameters:

ssl - pointer to the WOLFSSL object, created with wolfSSL_new()

key_name - unique key name for this ticket context, should be randomly generated

iv - unique IV for this ticket, up to 128 bits, should be randomly generated

mac - up to 256 bit mac for this ticket

enc - if this encrypt parameter is true the user should fill in key_name, iv, mac, and

encrypt the ticket in-place of length inLen and set the resulting output length in *outLen.

Returning WOLFSSL_TICKET_RET_OK tells wolfSSL that the encryption was

successful. If this encrypt parameter is false, the user should perform a decrypt of the

ticket in-place of length inLen using key_name, iv, and mac. The resulting decrypt

346

length should be set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL

to proceed using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE

tells wolfSSL to use the decrypted ticket but also to generate a new one to send to the

client, helpful if recently rolled keys and don’t want to force a full handshake. Returning

WOLFSSL_TICKET_RET_REJECT tells wolfSSL to reject this ticket, perform a full

handshake, and create a new standard session ID for normal session resumption.

Returning WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection

attempt with a fatal error.

ticket - the input/output buffer for the encrypted ticket. See the enc parameter

inLen - the input length of the ticket parameter

outLen - the resulting output length of the ticket parameter. When entering the callback

outLen will indicate the maximum size available in the ticket buffer.

userCtx - the user context set with wolfSSL_CTX_set_TicketEncCtx()

Example:

See wolfssl/test.h myTicketEncCb() used by the example server and example

echoserver.

See Also:

wolfSSL_CTX_set_TicketHint

wolfSSL_CTX_set_TicketEncCtx

wolfSSL_CTX_set_TicketHint

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX* ctx, int hint);

Description:

This function sets the session ticket hint relayed to the client. For server side use.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

347

BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid

arguments to the function.

Parameters:

ctx - pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().

hint - number of seconds the ticket might be valid for. Hint to client.

See Also:

wolfSSL_CTX_set_TicketEncCb()

wolfSSL_CTX_set_TicketEncCtx

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void* userCtx);

Description:

This function sets the session ticket encrypt user context for the callback. For server

side use.

Return Values:

SSL_SUCCESS will be returned upon successfully setting the session.

BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid

arguments to the function.

Parameters:

ctx - pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().

userCtx - the user context for the callback

348

See Also:

wolfSSL_CTX_set_TicketEncCb()

wolfSSL_CTX_SetCACb

Synopsis:

void wolfSSL_CTX_SetCACb(WOLFSSL_CTX* ctx, CallbackCACache cb);

typedef void (*CallbackCACache)(unsigned char* der, int sz, int type);

Description:

This function registers a callback with the SSL context (WOLFSSL_CTX) to be called

when a new CA certificate is loaded into wolfSSL. The callback is given a buffer with

the DER-encoded certificate.

Return Values:

This function has no return value.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

callback - function to be registered as the CA callback for the wolfSSL context, ctx. The

signature of this function must follow that as shown above in the Synopsis section.

Example:

WOLFSSL_CTX* ctx = 0;

/*CA callback prototype*/

int MyCACallback(unsigned char *der, int sz, int type);

/*Register the custom CA callback with the SSL context*/

wolfSSL_CTX_SetCACb(ctx, MyCACallback);

int MyCACallback(unsigned char* der, int sz, int type)

{

/* custom CA callback function, DER-encoded cert

located in “der” of size “sz” with type “type” */

}

349

See Also:

wolfSSL_CTX_load_verify_locations

wolfSSL_connect_ex

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_connect_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,

TimeoutCallBack toCb, Timeval timeout);

typedef int (*HandShakeCallBack)(HandShakeInfo*);

typedef int (*TimeoutCallBack)(TimeoutInfo*);

typedef struct timeval Timeval;

typedef struct handShakeInfo_st {

char cipherName[MAX_CIPHERNAME_SZ + 1]; /* negotiated

name */

char

packetNames[MAX_PACKETS_HANDSHAKE][MAX_PACKETNAME_SZ+1];

/* SSL packet

names */

int numberPackets; /* actual # of packets */

int negotiationError; /* cipher/parameter err */

} HandShakeInfo;

typedef struct timeoutInfo_st {

char timeoutName[MAX_TIMEOUT_NAME_SZ +1]; /*timeout

Name*/

int flags; /* for future

use*/

int numberPackets; /* actual # of

packets */

PacketInfo packets[MAX_PACKETS_HANDSHAKE]; /* list of

packets */

Timeval timeoutValue; /* timer that caused

350

it */

} TimeoutInfo;

typedef struct packetInfo_st {

char packetName[MAX_PACKETNAME_SZ + 1]; /*SSL name*/

Timeval timestamp; /*when it occured */

unsigned char value[MAX_VALUE_SZ]; /*if fits, it's here*/

unsigned char* bufferValue; /*otherwise here(non 0)*/

int valueSz; /*sz of value or buffer*/

} PacketInfo;

Description:

wolfSSL_connect_ex() is an extension that allows a HandShake Callback to be set.

This can be useful in embedded systems for debugging support when a debugger isn’t

available and sniffing is impractical. The HandShake Callback will be called whether or

not a handshake error occurred. No dynamic memory is used since the maximum

number of SSL packets is known. Packet names can be accessed through

packetNames[].

The connect extension also allows a Timeout Callback to be set along with a timeout

value. This is useful if the user doesn’t want to wait for the TCP stack to timeout.

This extension can be called with either, both, or neither callbacks.

Return Values:

If successful the call will return SSL_SUCCESS.

GETTIME_ERROR will be returned if gettimeofday() encountered an error.

SETITIMER_ERROR will be returned if setitimer() encountered an error.

SIGACT_ERROR will be returned if sigaction() encountered an error.

SSL_FATAL_ERROR will be returned if the underlying SSL_connect() call encountered

an error.

See Also:

wolfSSL_accept_ex

351

wolfSSL_accept_ex

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_accept_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,

TimeoutCallBack toCb, Timeval timeout);

typedef int (*HandShakeCallBack)(HandShakeInfo*);

typedef int (*TimeoutCallBack)(TimeoutInfo*);

typedef struct timeval Timeval;

typedef struct handShakeInfo_st {

char cipherName[MAX_CIPHERNAME_SZ + 1]; /*negotiated

name*/

char

packetNames[MAX_PACKETS_HANDSHAKE][MAX_PACKETNAME_SZ+1];

/* SSL packet names */

int numberPackets; /*actual # of packets */

int negotiationError; /*cipher/parameter err */

} HandShakeInfo;

typedef struct timeoutInfo_st {

char timeoutName[MAX_TIMEOUT_NAME_SZ +1]; /*timeout

Name*/

int flags; /*for future

use*/

int numberPackets; /*actual # of

packets */

PacketInfo packets[MAX_PACKETS_HANDSHAKE]; /*list of

packets */

Timeval timeoutValue; /* timer that

caused it*/

} TimeoutInfo;

352

typedef struct packetInfo_st {

char packetName[MAX_PACKETNAME_SZ + 1];/*SSL name */

Timeval timestamp; /*when it occured */

unsigned char value[MAX_VALUE_SZ]; /*if fits, it's here */

unsigned char* bufferValue; /*otherwise here(non 0)*/

int valueSz; /*sz of value or buffer*/

} PacketInfo;

Description:

wolfSSL_accept_ex() is an extension that allows a HandShake Callback to be set. This

can be useful in embedded systems for debugging support when a debugger isn’t

available and sniffing is impractical. The HandShake Callback will be called whether or

not a handshake error occurred. No dynamic memory is used since the maximum

number of SSL packets is known. Packet names can be accessed through

packetNames[].

The connect extension also allows a Timeout Callback to be set along with a timeout

value. This is useful if the user doesn’t want to wait for the TCP stack to timeout.

This extension can be called with either, both, or neither callbacks.

Return Values:

If successful the call will return SSL_SUCCESS.

GETTIME_ERROR will be returned if gettimeofday() encountered an error.

SETITIMER_ERROR will be returned if setitimer() encountered an error.

SIGACT_ERROR will be returned if sigaction() encountered an error.

SSL_FATAL_ERROR will be returned if the underlying SSL_accept() call encountered

an error.

See Also:

wolfSSL_connect_ex

wolfSSL_SetLoggingCb

Synopsis:

#include <wolfssl/wolfcrypt/logging.h>

353

int wolfSSL_SetLoggingCb(wolfSSL_Logging_cb log_function);

typedef void (*wolfSSL_Logging_cb)(const int logLevel, const char *const logMessage);

Description:

This function registers a logging callback that will be used to handle the wolfSSL log

message. By default, if the system supports it fprintf() to stderr is used but by using

this function anything can be done by the user.

Return Values:

If successful this function will return 0.

BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.

Parameters:

log_function - function to register as a logging callback. Function signature must

follow the above prototype.

Example:

int ret = 0;

/*Logging callback prototype*/

void MyLoggingCallback(const int logLevel, const char* const logMessage);

/*Register the custom logging callback with wolfSSL*/

ret = wolfSSL_SetLoggingCb(MyLoggingCallback);

if (ret != 0) {

/*failed to set logging callback*/

}

void MyLoggingCallback(const int logLevel, const char* const logMessage)

{

/*custom logging function*/

}

See Also:

wolfSSL_Debugging_ON

wolfSSL_Debugging_OFF

354

wolfSSL_SetTlsHmacInner

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetTlsHmacInner(WOLFSSL* ssl, byte* inner, word32 sz,

int content, int verify);

Description:

Allows caller to set the Hmac Inner vector for message sending/receiving. The result is

written to inner which should be at least wolfSSL_GetHmacSize() bytes. The size of

the message is specified by sz, content is the type of message, and verify specifies

whether this is a verification of a peer message. Valid for cipher types excluding

WOLFSSL_AEAD_TYPE.

Return Values:

If successful the call will return 1.

BAD_FUNC_ARG will be returned for an error state.

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetHmacType()

wolfSSL_CTX_SetMacEncryptCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX*, CallbackMacEncrypt);

typedef int (*CallbackMacEncrypt)(WOLFSSL* ssl, unsigned char* macOut,

const unsigned char* macIn, unsigned int macInSz, int macContent,

int macVerify, unsigned char* encOut, const unsigned char* encIn,

unsigned int encSz, void* ctx);

Description:

Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback. The

callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are

355

available for the user’s convenience. macOut is the output buffer where the result of

the mac should be stored. macIn is the mac input buffer and macInSz notes the size of

the buffer. macContent and macVerify are needed for wolfSSL_SetTlsHmacInner()

and be passed along as is. encOut is the output buffer where the result on the

encryption should be stored. encIn is the input buffer to encrypt while encSz is the size

of the input. An example callback can be found wolfssl/test.h myMacEncryptCb().

Return Values:

See Also:

wolfSSL_SetMacEncryptCtx()

wolfSSL_GetMacEncryptCtx()

wolfSSL_SetMacEncryptCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetMacEncryptCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback Context

to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetMacEncryptCb()

wolfSSL_GetMacEncryptCtx()

wolfSSL_GetMacEncryptCtx

Synopsis:

#include <wolfssl/ssl.h>

356

void* wolfSSL_GetMacEncryptCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Atomic User Record Processing Mac/Encrypt Callback

Context previously stored with wolfSSL_SetMacEncryptCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetMacEncryptCb()

wolfSSL_SetMacEncryptCtx()

wolfSSL_CTX_SetDecryptVerifyCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX*, CallbackDecryptVerify);

typedef int (*CallbackDecryptVerify)(WOLFSSL* ssl,

unsigned char* decOut, const unsigned char* decIn,

unsigned int decSz, int content, int verify, unsigned int* padSz,

void* ctx);

Description:

Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback. The

callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are

available for the user’s convenience. decOut is the output buffer where the result of the

decryption should be stored. decIn is the encrypted input buffer and decInSz notes the

size of the buffer. content and verify are needed for wolfSSL_SetTlsHmacInner() and

be passed along as is. padSz is an output variable that should be set with the total

value of the padding. That is, the mac size plus any padding and pad bytes. An

example callback can be found wolfssl/test.h myDecryptVerifyCb().

Return Values:

357

See Also:

wolfSSL_SetMacEncryptCtx()

wolfSSL_GetMacEncryptCtx()

wolfSSL_SetDecryptVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetDecryptVerifyCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context

to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetDecryptVerifyCb()

wolfSSL_GetDecryptVerifyCtx()

wolfSSL_GetDecryptVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetDecryptVerifyCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Atomic User Record Processing Decrypt/Verify Callback

Context previously stored with wolfSSL_SetDecryptVerifyCtx().

Return Values:

If successful the call will return a valid pointer to the context.

358

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetDecryptVerifyCb()

wolfSSL_SetDecryptVerifyCtx()

wolfSSL_CTX_SetEccSignCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX*, CallbackEccSign);

typedef int (*CallbackEccSign)(WOLFSSL* ssl,

const unsigned char* in, unsigned int inSz,

unsigned char* out, unsigned int* outSz,

const unsigned char* keyDer, unsigned int keySz,

void* ctx);

Description:

Allows caller to set the Public Key Callback for ECC Signing. The callback should

return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the

user’s convenience. in is the input buffer to sign while inSz denotes the length of the

input. out is the output buffer where the result of the signature should be stored. outSz

is an input/output variable that specifies the size of the output buffer upon invocation

and the actual size of the signature should be stored there before returning. keyDer is

the ECC Private key in ASN1 format and keySz is the length of the key in bytes. An

example callback can be found wolfssl/test.h myEccSign().

Return Values:

See Also:

wolfSSL_SetEccSignCtx()

wolfSSL_GetEccSignCtx()

wolfSSL_SetEccSignCtx

359

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetEccSignCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key Ecc Signing Callback Context to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetEccSignCb()

wolfSSL_GetEccSignCtx()

wolfSSL_GetEccSignCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetEccSignCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored

with wolfSSL_SetEccSignCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetEccSignCb()

wolfSSL_SetEccSignCtx()

wolfSSL_CTX_SetEccVerifyCb

360

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX*, CallbackEccVerify);

typedef int (*CallbackEccVerify)(WOLFSSL* ssl,

const unsigned char* sig, unsigned int sigSz,

const unsigned char* hash, unsigned int hashSz,

const unsigned char* keyDer, unsigned int keySz,

int* result, void* ctx);

Description:

Allows caller to set the Public Key Callback for ECC Verification. The callback should

return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the

user’s convenience. sig is the signature to verify and sigSz denotes the length of the

signature. hash is an input buffer containing the digest of the message and hashSz

denotes the length in bytes of the hash. result is an output variable where the result of

the verification should be stored, 1 for success and 0 for failure. keyDer is the ECC

Private key in ASN1 format and keySz is the length of the key in bytes. An example

callback can be found wolfssl/test.h myEccVerify().

Return Values:

See Also:

wolfSSL_SetEccVerifyCtx()

wolfSSL_GetEccVerifyCtx()

wolfSSL_SetEccVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetEccVerifyCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key Ecc Verification Callback Context to ctx.

361

Return Values:

See Also:

wolfSSL_CTX_SetEccVerifyCb()

wolfSSL_GetEccVerifyCtx()

wolfSSL_GetEccVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetEccVerifyCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key Ecc Verification Callback Context previously

stored with wolfSSL_SetEccVerifyCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetEccVerifyCb()

wolfSSL_SetEccVerifyCtx()

wolfSSL_CTX_SetRsaSignCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetEccRsaCb(WOLFSSL_CTX*, CallbackRsaSign);

typedef int (*CallbackRsaSign)(WOLFSSL* ssl,

const unsigned char* in, unsigned int inSz,

unsigned char* out, unsigned int* outSz,

362

const unsigned char* keyDer, unsigned int keySz,

void* ctx);

Description:

Allows caller to set the Public Key Callback for RSA Signing. The callback should

return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the

user’s convenience. in is the input buffer to sign while inSz denotes the length of the

input. out is the output buffer where the result of the signature should be stored. outSz

is an input/output variable that specifies the size of the output buffer upon invocation

and the actual size of the signature should be stored there before returning. keyDer is

the RSA Private key in ASN1 format and keySz is the length of the key in bytes. An

example callback can be found wolfssl/test.h myRsaSign().

Return Values:

See Also:

wolfSSL_SetRsaSignCtx()

wolfSSL_GetRsaSignCtx()

wolfSSL_SetRsaSignCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetRsaSignCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key RSA Signing Callback Context to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetRsaSignCb()

wolfSSL_GetRsaSignCtx()

363

wolfSSL_GetRsaSignCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetRsaSignCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key RSA Signing Callback Context previously stored

with wolfSSL_SetRsaSignCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetRsaSignCb()

wolfSSL_SetRsaSignCtx()

wolfSSL_CTX_SetRsaVerifyCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX*, CallbackRsaVerify);

typedef int (*CallbackRsaVerify)(WOLFSSL* ssl,

unsigned char* sig, unsigned int sigSz,

unsigned char** out,

const unsigned char* keyDer, unsigned int keySz,

void* ctx);

Description:

Allows caller to set the Public Key Callback for RSA Verification. The callback should

return the number of plaintext bytes for success or < 0 for an error. The ssl and ctx

pointers are available for the user’s convenience. sig is the signature to verify and

sigSz denotes the length of the signature. out should be set to the beginning of the

verification buffer after the decryption process and any padding. keyDer is the RSA

364

Public key in ASN1 format and keySz is the length of the key in bytes. An example

callback can be found wolfssl/test.h myRsaVerify().

Return Values:

Also:

wolfSSL_SetRsaVerifyCtx()

wolfSSL_GetRsaVerifyCtx()

wolfSSL_SetRsaVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetRsaVerifyCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key RSA Verification Callback Context to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetRsaVerifyCb()

wolfSSL_GetRsaVerifyCtx()

wolfSSL_GetRsaVerifyCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetRsaVerifyCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key RSA Verification Callback Context previously

365

stored with wolfSSL_SetRsaVerifyCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetRsaVerifyCb()

wolfSSL_SetRsaVerifyCtx()

wolfSSL_CTX_SetRsaEncCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX*, CallbackRsaEnc);

typedef int (*CallbackRsaEnc)(WOLFSSL* ssl,

const unsigned char* in, unsigned int inSz,

unsigned char* out, unsigned int* outSz,

const unsigned char* keyDer, unsigned int keySz,

void* ctx);

Description:

Allows caller to set the Public Key Callback for RSA Public Encrypt. The callback

should return 0 for success or < 0 for an error. The ssl and ctx pointers are available

for the user’s convenience. in is the input buffer to encrypt while inSz denotes the

length of the input. out is the output buffer where the result of the encryption should be

stored. outSz is an input/output variable that specifies the size of the output buffer

upon invocation and the actual size of the encryption should be stored there before

returning. keyDer is the RSA Public key in ASN1 format and keySz is the length of the

key in bytes. An example callback can be found wolfssl/test.h myRsaEnc().

Return Values:

See Also:

wolfSSL_SetRsaEncCtx()

366

wolfSSL_GetRsaEncCtx()

wolfSSL_SetRsaEncCtx

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetRsaEncCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key RSA Public Encrypt Callback Context to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetRsaEncCb()

wolfSSL_GetRsaEncCtx()

wolfSSL_GetRsaEncCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetRsaEncCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key RSA Public Encrypt Callback Context previously

stored with wolfSSL_SetRsaEncCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

367

wolfSSL_CTX_SetRsaEncCb()

wolfSSL_SetRsaEncCtx()

wolfSSL_CTX_SetRsaDecCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX*, CallbackRsaDec);

typedef int (*CallbackRsaDec)(WOLFSSL* ssl,

unsigned char* in, unsigned int inSz,

unsigned char** out,

const unsigned char* keyDer, unsigned int keySz,

void* ctx);

Description:

Allows caller to set the Public Key Callback for RSA Private Decrypt. The callback

should return the number of plaintext bytes for success or < 0 for an error. The ssl and

ctx pointers are available for the user’s convenience. in is the input buffer to decrypt

and inSz denotes the length of the input. out should be set to the beginning of the

decryption buffer after the decryption process and any padding. keyDer is the RSA

Private key in ASN1 format and keySz is the length of the key in bytes. An example

callback can be found wolfssl/test.h myRsaDec().

Return Values:

See Also:

wolfSSL_SetRsaDecCtx()

wolfSSL_GetRsaDecCtx()

wolfSSL_SetRsaDecCtx

Synopsis:

#include <wolfssl/ssl.h>

368

void wolfSSL_SetRsaDecCtx(WOLFSSL*, void* ctx);

Description:

Allows caller to set the Public Key RSA Private Decrypt Callback Context to ctx.

Return Values:

See Also:

wolfSSL_CTX_SetRsaDecCb()

wolfSSL_GetRsaDecCtx()

wolfSSL_GetRsaDecCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetRsaDecCtx(WOLFSSL*);

Description:

Allows caller to retrieve the Public Key RSA Private Decrypt Callback Context

previously stored with wolfSSL_SetRsaDecCtx().

Return Values:

If successful the call will return a valid pointer to the context.

NULL will be returned for a blank context.

See Also:

wolfSSL_CTX_SetRsaDecCb()

wolfSSL_SetRsaDecCtx()

wolfSSL_set_SessionTicket_cb

Synopsis:

#include <wolfssl/ssl.h>

369

int wolfSSL_set_SessionTicket_cb(WOLFSSL* ssl, CallbackSessionTicket cb,

void* ctx);

Description:

This function sets the session ticket callback. The type CallbackSessionTicket is a

function pointer with the signature of:

int (*CallbackSessionTicket)(WOLFSSL*, const unsigned char*, int, void*)

Return Values:

SSL_SUCCESS - returned if the function executed without error.

BAD_FUNC_ARG - returned if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer to the type CallbackSessionTicket.

ctx - a void pointer to the session_ticket_ctx member of the WOLFSSL structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

int sessionTicketCB(WOLFSSL* ssl, const unsigned char* ticket, int ticketSz,

void* ctx){ … }

wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”);

See Also:

wolfSSL_set_SessionTicket

CallbackSessionTicket

sessionTicketCB

wolfSSL_set_session_secret_cb

Synopsis:

#include <wolfssl/ssl.h>

370

int wolfSSL_set_session_secret_cb(WOLFSSL* ssl, SessionSecretCb cb, void* ctx);

Description:

This function sets the session secret callback function. The SessionSecretCb type has

the signature:

int (*SessionSecretCb)(WOLFSSL* ssl, void* secret, int* secretSz, void* ctx).

The sessionSecretCb member of the WOLFSSL struct is set to the parameter cb.

Return Values:

SSL_SUCCESS - returned if the execution of the function did not return an error.

SSL_FATAL_ERROR - returned if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a SessionSecretCb type that is a function pointer with the above signature.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz, void* ctx) =

SessionSecretCb; /*Signature of SessionSecretCb*/

…

int wolfSSL_set_session_secret_cb(ssl, SessionSecretCB, (void*)ssl->ctx){

/*Function body. */

}

See Also:

SessionSecretCb

wolfSSL_CTX_SetGenCookie

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX* ctx, CallbackGenCookie cb);

371

Description:

This function sets the callback for the CBIOCookie member of the WOLFSSL_CTX

structure. The CallbackGenCookie type is a function pointer and has the signature:

int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned char* buf, int sz, void* ctx);

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a CallbackGenCookie type function pointer with the signature of

CallbackGenCookie.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

int SetGenCookieCB(WOLFSSL* ssl, unsigned char* buf, int sz, void* ctx){

/*Callback function body. */

}

…

wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB);

See Also:

CallbackGenCookie

wolfSSL_SetHsDoneCb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetHsDoneCb(WOLFSSL* ssl, HandShakeDoneCb cb, void* user_ctx);

Description:

This function sets the handshake done callback. The hsDoneCb and hsDoneCtx

members of the WOLFSSL structure are set in this function.

Return Values:

372

SSL_SUCCESS - returned if the function executed without an error. The hsDoneCb and

hsDoneCtx members of the WOLFSSL struct are set.

BAD_FUNC_ARG - returned if the WOLFSSL struct is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer of type HandShakeDoneCb with the signature of the form:

int (*HandShakeDoneCb)(WOLFSSL*, void*);

user_ctx - a void pointer to the user registered context.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

int myHsDoneCb(WOLFSSL* ssl, void* user_ctx){

/*callback function */

}

…

wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL);

See Also:

HandShakeDoneCb

wolfSSL_SetFuzzerCb

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCtx);

Description:

This function sets the fuzzer callback.

Return Values:

This function has no return value.

373

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cbf - a CallbackFuzzer type that is a function pointer of the form:

int (*CallbackFuzzer)(WOLFSSL* ssl, const unsigned char* buf, int sz,

int type, void* fuzzCtx);

fCtx - a void pointer type that will be set to the fuzzerCtx member of the WOLFSSL

structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

void* fCtx;

int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz,

int type, void* fuzzCtx){

/*function definition*/

}

…

wolfSSL_SetFuzzerCb(ssl, callbackFuzzerCB, fCtx);

See Also:

CallbackFuzzer

wolfSSL_CertManagerSetCRL_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER* cm,

CbMissingCRL cb);

Description:

This function sets the CRL Certificate Manager callback. If HAVE_CRL is defined and a

matching CRL record is not found then the cbMissingCRL is called (set via

wolfSSL_CertManagerSetCRL_Cb). This allows you to externally retrieve the CRL and

load it.

Return Values:

374

SSL_SUCCESS - returned upon successful execution of the function and subroutines.

BAD_FUNC_ARG - returned if the WOLFSSL_CERT_MANAGER structure is NULL.

Parameters:

cm - the WOLFSSL_CERT_MANAGER structure holding the information for the

certificate.

cb - a function pointer to (*CbMissingCRL) that is set to the cbMissingCRL member of

the WOLFSSL_CERT_MANAGER.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

void cb(const char* url){

/*Function body. */

}

…

CbMissingCRL cb = CbMissingCRL;

…

if(ctx){

return wolfSSL_CertManagerSetCRL_Cb(ssl->ctx->cm, cb);

}

See Also:

CbMissingCRL

wolfSSL_SetCRL_Cb

wolfSSL_SetOCSP_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, CbOCSPRespFree

respFreeCb, void* ioCbCtx);

Description:

This function sets the OCSP callback in the WOLFSSL_CERT_MANAGER structure.

375

Return Values:

SSL_SUCCESS - returned if the function executes without error. The ocspIOCb,

ocspRespFreeCb, and ocspIOCtx memebers of the CM are set.

BAD_FUNC_ARG - returned if the WOLFSSL or WOLFSSL_CERT_MANAGER

structures are NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

ioCb - a function pointer to type CbOCSPIO.

respFreeCb - a function pointer to type CbOCSPRespFree which is the call to free the

response memory.

ioCbCtx - a void pointer that will be held in the ocspIOCtx member of the CM.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

…

int OCSPIO_CB(void* , const char*, int , unsigned char* , int,

unsigned char**){ /*must have this signature*/

/*Function Body*/

}

…

void OCSPRespFree_CB(void* , unsigned char* ){ /*must have this signature*/

/*function body*/

}

…

void* ioCbCtx;

CbOCSPRespFree CB_OCSPRespFree;

if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB(/*Pass args*/), CB_OCSPRespFree,

ioCbCtx) != SSL_SUCCESS){

/*Callback not set */

}

See Also:

wolfSSL_CertManagerSetOCSP_Cb

CbOCSPIO

CbOCSPRespFree

376

wolfSSL_SetCRL_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetCRL_Cb(WOLFSSL* ssl, CbMissingCRL cb);

Description:

Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure.

Return Values:

SSL_SUCCESS - returned if the function or subroutine executes without error. The

cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set.

BAD_FUNC_ARG - returned if the WOLFSSL or WOLFSSL_CERT_MANAGER

structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer to CbMissingCRL.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

void cb(const char* url)/*required signature */

{

/*Function body */

}

…

int crlCb = wolfSSL_SetCRL_Cb(ssl, cb);

if(crlCb != SSL_SUCCESS){

/*The callback was not set properly */

}

See Also:

CbMissingCRL

wolfSSL_CertManagerSetCRL_Cb

377

wolfSSL_CTX_SetOCSP_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX* ctx, CbOCSPIO ioCb,

CbOCSPRespFree respFreeCb, void* ioCbCtx);

Description:

Sets the callback for the OCSP in the WOLFSSL_CTX structure.

Return Values:

SSL_SUCCESS - returned if the function executed successfully. The ocspIOCb,

ocspRespFreeCb, and ocspIOCtx members in the CM were successfully set.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX or WOLFSSL_CERT_MANAGER

structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

ioCb - a CbOCSPIO type that is a function pointer.

respFreeCb - a CbOCSPRespFree type that is a function pointer.

ioCbCtx - a void pointer that will be held in the WOLFSSL_CERT_MANAGER.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

…

CbOCSPIO ocspIOCb;

CbOCSPRespFree ocspRespFreeCb;

…

void* ioCbCtx;

int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb, ocspRespFreeCb,

ioCbCtx);

378

if(isSetOCSP != SSL_SUCCESS){

/*The function did not return successfully. */

}

See Also:

wolfSSL_CertManagerSetOCSP_Cb

CbOCSPIO

CbOCSPRespFree

wolfSSL_CertManagerSetOCSP_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER* cm,

CbOCSPIO ioCb, CbOCSPRespFree respFreeCb, void* ioCbCtx);

Description:

The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER.

Return Values:

SSL_SUCCESS - returned on successful execution. The arguments are saved in the

WOLFSSL_CERT_MANAGER structure.

BAD_FUNC_ARG - returned if the WOLFSSL_CERT_MANAGER is NULL.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure.

ioCb - a function pointer of type CbOCSPIO.

respFreeCb - a function pointer of type CbOCSPRespFree.

ioCbCtx - a void pointer variable to the I/O callback user registered context.

Example:

wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb,

CbOCSPRespFree respFreeCb, void* ioCbCtx){

379

…

return wolfSSL_CertManagerSetOCSP_Cb(ssl->ctx->cm, ioCb, respFreeCb,

ioCbCtx);

See Also:

wolfSSL_CertManagerSetOCSPOverrideURL

wolfSSL_CertManagerCheckOCSP

wolfSSL_CertManagerEnableOCSPStapling

wolfSSL_ENableOCSP

wolfSSL_DisableOCSP

wolfSSL_SetOCSP_Cb

wolfSSL_set_psk_client_callback

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_set_psk_client_callback(WOLFSSL* ssl, wc_psk_client_callback cb);

Description:

Sets the PSK client side callback.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer to type wc_psk_client_callback.

Example:

WOLFSSL* ssl;

unsigned int cb(WOLFSSL*, const char*, char*)/*Header of function*

{

/*Funciton body */

}

…

cb = wc_psk_client_callback;

if(ssl){

wolfSSL_set_psk_client_callback(ssl, cb);

380

} else {

/*could not set callback */

}

See Also:

wolfSSL_CTX_set_psk_client_callback

wolfSSL_CTX_set_psk_server_callback

wolfSSL_set_psk_server_callback

wolfSSL_CTX_SetCRL_Cb

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX* ctx, CbMissingCRL cb);

Description:

This function will set the callback argument to the cbMissingCRL member of the

WOLFSSL_CERT_MANAGER structure by calling wolfSSL_CertManagerSetCRL_Cb.

Return Values:

SSL_SUCCESS - returned for a successful execution. The

WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully set

to cb.

BAD_FUNC_ARG - returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER are

NULL.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

cb - a pointer to a callback function of type CbMissingCRL. Signature requirement:

void (*CbMissingCRL)(const char* url);

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

…

void cb(const char* url)/*Required signature*/

{

381

/*Function body*/

}

…

if (wolfSSL_CTX_SetCRL_Cb(ctx, cb) != SSL_SUCCESS){

/*Failure case, cb was not set correctly. */

}

See Also:

wolfSSL_CertManagerSetCRL_Cb

CbMissingCRL

wolfSSL_CTX_set_psk_server_callback

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX* ctx,

wc_psk_server_callback cb);

Description:

This function sets the psk callback for the server side in the WOLFSSL_CTX structure.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer for the callback and will be stored in the WOLFSSL_CTX

structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

unsigned int cb(WOLFSSL*, const char*, unsigned char*, unsigned int)

/*signature requirement*/

{

/*Function body. */

}

382

…

if(ctx != NULL){

wolfSSL_CTX_set_psk_server_callback(ctx, cb);

} else {

/*The CTX object was not properly initialized. */

}

See Also:

wc_psk_server_callback

wolfSSL_set_psk_client_callback

wolfSSL_set_psk_server_callback

wolfSSL_CTX_set_psk_client_callback

wolfSSL_set_psk_server_callback

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_set_psk_server_callback(WOLFSSL* ssl, wc_psk_server_callback cb);

Description:

Sets the psk callback for the server side by setting the WOLFSSL structure options

members.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

cb - a function pointer for the callback and will be stored in the WOLFSSL structure.

Example:

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

…

int cb(WOLFSSL*, const char*, unsigned char*, unsigned int)/*Required sig. */

{

383

/*Function body. */

}

…

if(ssl != NULL && cb != NULL){

wolfSSL_set_psk_server_callback(ssl, cb);

}

See Also:

wolfSSL_set_psk_client_callback

wolfSSL_set_psk_server_callback

wolfSSL_CTX_set_psk_server_callback

wolfSSL_CTX_set_psk_client_callback

wolfSSL_get_psk_identity_hint

wc_psk_server_callback

InitSuites

wolfSSL_CTX_set_psk_client_callback

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX* ctx,

wc_psk_client_callback cb);

Description:

The function sets the client_psk_cb member of the WOLFSSL_CTX structure.

Return Values:

This function has no return value.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

cb - wc_psk_client_callback is a function pointer that will be stored in the

WOLFSSL_CTX structure.

Example:

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(/*protocol def*/);

384

…

static INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,

char* identity, unsigned int id_max_len, unsigned char* key,

Unsigned int key_max_len){

…

wolfSSL_CTX_set_psk_client_callback(ctx, my_psk_client_cb);

See Also:

(*wc_psk_client_callback)

wolfSSL_set_psk_client_callback

wolfSSL_set_psk_server_callback

wolfSSL_CTX_set_psk_server_callback

wolfSSL_CTX_set_psk_client_callback

EmbedReceiveFrom

Synopsis:

#include <wolfssl/ssl.h>

int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void* ctx);

Description:

This function is the receive embedded callback.

Return Values:

This function returns the nb bytes read if the execution was successful.

WOLFSSL_CBIO_ERR_WANT_READ - if the connection refused or if a ‘would block’

error was thrown in the function.

WOLFSSL_CBIO_ERR_TIMEOUT - returned if the socket timed out.

WOLFSSL_CBIO_ERR_CONN_RST - returned if the connection reset.

WOLFSSL_CBIO_ERR_ISR - returned if the socket was interrupted.

WOLFSSL_CBIO_ERR_GENERAL - returned if there was a general error.

385

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a constant char pointer to the buffer.

sz - an int type representing the size of the buffer.

ctx - a void pointer to the WOLFSSL_CTX context.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new(ctx);

char* buf; /*Allocate / Initialize */

int sz = sizeof(buf)/sizeof(char);

(void*)ctx;

…

int nb = EmbedReceiveFrom(ssl, buf, sz, ctx);

if(nb > 0){

/*nb is the number of bytes written and is positive*/

}

See Also:

TranslateReturnCode

RECVFROM_FUNCTION

Setsockopt

EmbedReceive

Synopsis:

#include <wolfssl/ssl.h>

int EmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);

Description:

This function is the receive embedded callback.

Return Values:

This function returns the number of bytes read.

386

WOLFSSL_CBIO_ERR_WANT_READ - returned with a “Would block” message if the

last error was SOCKET_EWOULDBLCOK or SOCKET_EAGAIN.

WOLFSSL_CBIO_ERR_TIMEOUT - returned with a “Socket timeout” message.

WOLFSSL_CBIO_ERR_CONN_RST - returned with a “Connection reset” message if

the last error was SOCKET_ECONNRESET.

WOLFSSL_CBIO_ERR_ISR - returned with a “Socket interrupted” message if the last

error was SOCKET_EINTR.

WOLFSSL_CBIO_ERR_WANT_READ - returned with a “Connection refused” messag

if the last error was SOCKET_ECONNREFUSED.

WOLFSSL_CBIO_ERR_CONN_CLOSE - returned with a “Connection aborted”

message if the last error was SOCKET_ECONNABORTED.

WOLFSSL_CBIO_ERR_GENERAL - returned with a “General error” message if the

last error was not specified.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a char pointer representation of the buffer.

sz - the size of the buffer.

ctx - a void pointer to user registered context. In the default case the ctx is a socket

descriptor pointer.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

char* buf; /*The buffer. */

int sz; /* Size of buf */

void* ctx;

int bytesRead = EmbedReceive(ssl, buf, sz, ctx);

if(bytesRead <= 0){

387

/*There were no bytes read. Failure case. */

}

See Also:

wolfSSL_dtls_get_current_timeout

TranslateReturnCode

RECV_FUNCTION

EmbedSend

Synopsis:

#include <wolfssl/ssl.h>

int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx);

Description:

This function is the send embedded callback.

Return Values:

This function returns the number of bytes sent.

WOLFSSL_CBIO_ERR_WANT_WRITE - returned with a “Would block” message if the

last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN.

WOLFSSL_CBIO_ERR_CONN_RST - returned with a “Connection reset” message if

the last error was SOCKET_ECONNRESET.

WOLFSSL_CBIO_ERR_ISR - returned with a “Socket interrupted” message if the last

error was SOCKET_EINTR.

WOLFSSL_CBIO_ERR_CONN_CLOSE - returned with a “Socket EPIPE” message if

the last error was SOCKET_EPIPE.

WOLFSSL_CBIO_ERR_GENERAL - returned with a “General error” message if the

last error was not specified.

Parameters:

388

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a char pointer representing the buffer.

sz - the size of the buffer.

ctx - a void pointer to user registered context.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

char* buf; /*buffer*/

int sz; /*size of buffer*/

void* ctx;

int dSent = EmbedSend(ssl, buf, sz, ctx);

if(dSent <= 0){

/*No byes sent. Failure case. */

}

See Also:

TranslateReturnCode

SEND_FUNCTION

LastError

InitSSL_Ctx

LastError

EmbedSendTo

Synopsis:

#include <wolfssl/ssl.h>

int EmbedSendTo(WOLFSSL* ssl, char8 buf, int sz, void* ctx);

Description:

This function is the send embedded callback.

Return Values:

This function returns the number of bytes sent.

WOLFSSL_CBIO_ERR_WANT_WRITE - returned with a “Would Block” message if the

389

last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error.

WOLFSSL_CBIO_ERR_CONN_RST - returned with a “Connection reset” message if

the last error was SOCKET_ECONNRESET.

WOLFSSL_CBIO_ERR_ISR - returned with a “Socket interrupted” message if the last

error was SOCKET_EINTR.

WOLFSSL_CBIO_ERR_CONN_CLOSE - returned with a “Socket EPIPE” message if

the last error was WOLFSSL_CBIO_ERR_CONN_CLOSE.

WOLFSSL_CBIO_ERR_GENERAL - returned with a “General error” message if the

last error was not specified.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a char pointer representing the buffer.

sz - the size of the buffer.

ctx - a void pointer to the user registered context. The default case is a

WOLFSSL_DTLS_CTX sructure.

Example:

WOLFSSL* ssl;

…

char* buf;

int sz; /*Size of buffer */

void* ctx;

int sEmbed = EmbedSendto(ssl, buf, sz, ctx);

if(sEmbed <= 0){

/*No bytes sent. Failure case. */

}

See Also:

LastError

EmbedSend

390

EmbedReceive

EmbedGenerateCookie

Synopsis:

#include <wolfssl/ssl.h>

int EmbedGenerateCookie(WOLFSSL* ssl, byte* buf, int sz, void* ctx);

Description:

This function is the DTLS Generate Cookie callback.

Return Values:

This function returns the number of bytes copied into the buffer.

GEN_COOKIE_E - returned if the getpeername failed in EmbedGenerateCookie.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - byte pointer representing the buffer. It is the destination from XMEMCPY().

sz - the size of the buffer.

ctx - a void pointer to user registered context.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

byte buffer[BUFFER_SIZE];

int sz = sizeof(buffer)/sizeof(byte);

void* ctx;

…

int ret = EmbedGenerateCookie(ssl, buffer, sz, ctx);

if(ret > 0){

/*EmbedGenerateCookie code block for success*/

}

391

See Also:

wc_ShaHash

EmbedGenerateCookie

XMEMCPY

XMEMSET

EmbedOcspRespFree

Synopsis:

#include <wolfssl/ssl.h>

void EmbedOcspRespFree(void* ctx, byte* resp);

Description:

This function frees the response buffer.

Return Values:

This function has no return value.

Parameters:

ctx - a void pointer to heap hint.

resp - a byte pointer representing the response.

Example:

void* ctx;

byte* resp; /*Response buffer. */

…

EmbedOcspRespFree(ctx, resp);

See Also:

XFREE

392

17.5 Error Handling and Debugging

The functions in this section have to do with printing and handling errors as well as

enabling and disabling debugging in wolfSSL.

wolfSSL_ERR_error_string

Synopsis:

#include <wolfssl/ssl.h>

char* wolfSSL_ERR_error_string(unsigned long errNumber, char* data);

Description:

This function converts an error code returned by wolfSSL_get_error() into a more

human-readable error string. errNumber is the error code returned by

wolfSSL_get_error() and data is the storage buffer which the error string will be placed

in.

The maximum length of data is 80 characters by default, as defined by

MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h.

Return Values:

On successful completion, this function returns the same string as is returned in data.

Upon failure, this function returns a string with the appropriate failure reason, msg.

Parameters:

errNumber - error code returned by wolfSSL_get_error().

data - output buffer containing human-readable error string matching errNumber.

Example:

int err = 0;

WOLFSSL* ssl;

char buffer[80];

...

err = wolfSSL_get_error(ssl, 0);

wolfSSL_ERR_error_string(err, buffer);

printf(“err = %d, %s\n”, err, buffer);

393

See Also:

wolfSSL_get_error

wolfSSL_ERR_error_string_n

wolfSSL_ERR_print_errors_fp

wolfSSL_load_error_strings

wolfSSL_ERR_error_string_n

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_ERR_error_string_n(unsigned long e, char* buf, unsigned long len);

Description:

This function is a version of wolfSSL_ERR_error_string() where len specifies the

maximum number of characters that may be written to buf. Like

wolfSSL_ERR_error_string(), this function converts an error code returned from

wolfSSL_get_error() into a more human-readable error string. The human-readable

string is placed in buf.

Return Values:

This function has no return value.

Parameters:

e - error code returned by wolfSSL_get_error().

buff - output buffer containing human-readable error string matching e.

len - maximum length in characters which may be written to buf.

Example:

int err = 0;

WOLFSSL* ssl;

char buffer[80];

...

err = wolfSSL_get_error(ssl, 0);

wolfSSL_ERR_error_string_n(err, buffer, 80);

printf(“err = %d, %s\n”, err, buffer);

394

See Also:

wolfSSL_get_error

wolfSSL_ERR_error_string

wolfSSL_ERR_print_errors_fp

wolfSSL_load_error_strings

wolfSSL_ERR_peek_last_error

Synopsis:

#include <wolfssl/ssl.h>

ERR_peek_last_error ->

unsigned long wolfSSL_ERR_peek_last_error(void);

Description:

This function returns the absolute value of the last error from WOLFSSL_ERROR

encountered.

Return Values:

Returns absolute value of last error.

Parameters:

None

Example:

unsigned long err;

...

err = wolfSSL_ERR_peek_last_error();

// inspect err value

See Also:

wolfSSL_ERR_print_errors_fp

395

wolfSSL_ERR_print_errors_fp

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_ERR_print_errors_fp(FILE* fp, int err);

Description:

This function converts an error code returned by wolfSSL_get_error() into a more

human-readable error string and prints that string to the output file - fp. err is the error

code returned by wolfSSL_get_error() and fp is the file which the error string will be

placed in.

Return Values:

This function has no return value.

Parameters:

fp - output file for human-readable error string to be written to.

err - error code returned by wolfSSL_get_error().

Example:

int err = 0;

WOLFSSL* ssl;

FILE* fp = ...

...

err = wolfSSL_get_error(ssl, 0);

wolfSSL_ERR_print_errors_fp(fp, err);

See Also:

wolfSSL_get_error

wolfSSL_ERR_error_string

wolfSSL_ERR_error_string_n

wolfSSL_load_error_strings

wolfSSL_get_error

Synopsis:

396

#include <wolfssl/ssl.h>

int wolfSSL_get_error(WOLFSSL* ssl, int ret);

Description:

This function returns a unique error code describing why the previous API function call

(wolfSSL_connect, wolfSSL_accept, wolfSSL_read, wolfSSL_write, etc.) resulted in an

error return code (SSL_FAILURE). The return value of the previous function is passed

to wolfSSL_get_error through ret.

After wolfSSL_get_error is called and returns the unique error code,

wolfSSL_ERR_error_string() may be called to get a human-readable error string. See

wolfSSL_ERR_error_string() for more information.

Return Values:

On successful completion, this function will return the unique error code describing why

the previous API function failed.

SSL_ERROR_NONE will be returned if ret > 0.

Parameters:

ssl - pointer to the SSL object, created with wolfSSL_new().

ret - return value of the previous function that resulted in an error return code.

Example:

int err = 0;

WOLFSSL* ssl;

char buffer[80];

...

err = wolfSSL_get_error(ssl, 0);

wolfSSL_ERR_error_string(err, buffer);

printf(“err = %d, %s\n”, err, buffer);

See Also:

wolfSSL_ERR_error_string

wolfSSL_ERR_error_string_n

wolfSSL_ERR_print_errors_fp

wolfSSL_load_error_strings

397

wolfSSL_load_error_strings

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_load_error_strings(void);

Description:

This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no

action.

Return Values:

This function has no return value.

Parameters:

This function takes no parameters.

Example:

wolfSSL_load_error_strings();

See Also:

wolfSSL_get_error

wolfSSL_ERR_error_string

wolfSSL_ERR_error_string_n

wolfSSL_ERR_print_errors_fp

wolfSSL_load_error_strings

wolfSSL_want_read

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_want_read(WOLFSSL* ssl)

Description:

This function is similar to calling wolfSSL_get_error() and getting

398

SSL_ERROR_WANT_READ in return. If the underlying error state is

SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.

Return Values:

1 - wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the underlying I/O

has data available for reading.

0 - There is no SSL_ERROR_WANT_READ error state.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_want_read(ssl);

if (ret == 1) {

// underlying I/O has data available for reading (SSL_ERROR_WANT_READ)

}

See Also:

wolfSSL_want_write

wolfSSL_get_error

wolfSSL_want_write

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_want_write(WOLFSSL* ssl)

Description:

This function is similar to calling wolfSSL_get_error() and getting

SSL_ERROR_WANT_WRITE in return. If the underlying error state is

SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.

399

Return Values:

1 - wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the underlying I/O

needs data to be written in order for progress to be made in the underlying SSL

connection.

0 - There is no SSL_ERROR_WANT_WRITE error state.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_want_write(ssl);

if (ret == 1) {

// underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)

}

See Also:

wolfSSL_want_read

wolfSSL_get_error

wolfSSL_Debugging_ON

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_Debugging_ON(void);

Description:

If logging has been enabled at build time this function turns on logging at runtime. To

enable logging at build time use --enable-debug or define DEBUG_WOLFSSL

Return Values:

If successful this function will return 0.

400

NOT_COMPILED_IN is the error that will be returned if logging isn’t enabled for this

build.

Parameters:

This function has no parameters.

Example:

wolfSSL_Debugging_ON();

See Also:

wolfSSL_Debugging_OFF

wolfSSL_SetLoggingCb

wolfSSL_Debugging_OFF

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_Debugging_OFF(void);

Description:

This function turns off runtime logging messages. If they’re already off, no action is

taken.

Return Values:

No return values are returned by this function.

Parameters:

This function has no parameters.

Example:

wolfSSL_Debugging_OFF();

See Also:

wolfSSL_Debugging_ON

wolfSSL_SetLoggingCb

401

17.6 OCSP and CRL

The functions in this section have to do with using OCSP (Online Certificate Status

Protocol) and CRL (Certificate Revocation List) with wolfSSL.

wolfSSL_CTX_EnableOCSP

Synopsis:

long wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX* ctx, int options);

Description:

This function sets options to configure behavior of OCSP functionality in wolfSSL. The

value of options if formed by or’ing one or more of the following options:

WOLFSSL_OCSP_ENABLE

- enable OCSP lookups

WOLFSSL_OCSP_URL_OVERRIDE

- use the override URL instead of the URL in certificates.

The override URL is specified using the wolfSSL_CTX_SetOCSP_OverrideURL()

function.

This function only sets the OCSP options when wolfSSL has been compiled with OCSP

support (--enable-ocsp, #define HAVE_OCSP).

Return Values:

SSL_SUCCESS is returned upon success

SSL_FAILURE is returned upon failure

402

NOT_COMPILED_IN is returned when this function has been called, but OCSP support

was not enabled when wolfSSL was compiled.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

options - value used to set the OCSP options.

Example:

WOLFSSL_CTX* ctx = 0;

...

wolfSSL_CTX_OCSP_set_options(ctx, WOLFSSL_OCSP_ENABLE);

See Also:

wolfSSL_CTX_OCSP_set_override_url

wolfSSL_CTX_SetOCSP_OverrideURL

Synopsis:

int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX* ctx, const char* url);

Description:

This function manually sets the URL for OCSP to use. By default, OCSP will use the

URL found in the individual certificate unless the WOLFSSL_OCSP_URL_OVERRIDE

option is set using the wolfSSL_CTX_EnableOCSP.

Return Values:

SSL_SUCCESS is returned upon success

SSL_FAILURE is returned upon failure

NOT_COMPILED_IN is returned when this function has been called, but OCSP support

was not enabled when wolfSSL was compiled.

Parameters:

ctx - pointer to the SSL context, created with wolfSSL_CTX_new().

403

url - pointer to the OCSP URL for wolfSSL to use.

Example:

WOLFSSL_CTX* ctx = 0;

...

wolfSSL_CTX_OCSP_set_override_url(ctx, “custom-url-here”);

See Also:

wolfSSL_CTX_OCSP_set_options

wolfSSL_EnableCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_EnableCRL(WOLFSSL* ssl, int options);

Description:

Enables CRL certificate revocation.

Return Values:

SSL_SUCCESS - the function and subroutines returned with no errors.

BAD_FUNC_ARG - returned if the WOLFSSL structure is NULL.

MEMORY_E - returned if the allocation of memory failed.

SSL_FAILURE - returned if the InitCRL function does not return successfully.

NOT_COMPILED_IN - HAVE_CRL was not enabled during the compiling.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

options - an integer that is used to determine the setting of crlCheckAll member of the

WOLFSSL_CERT_MANAGER structure.

404

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

…

if (wolfSSL_EnableCRL(ssl, WOLFSSL_CRL_CHECKALL) != SSL_SUCCESS){

/*Failure case. SSL_SUCCESS was not returned by this function or a

subroutine */

}

See Also:

wolfSSL_CertManagerEnableCRL

InitCRL

wolfSSL_DisableOCSP

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_DisableOCSP(WOLFSSL* ssl);

Description:

Disables the OCSP certificate revocation option.

Return Values:

SSL_SUCCESS - returned if the function and its subroutine return with no errors. The

ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was successfully

set.

BAD_FUNC_ARG - returned if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

…

405

if(wolfSSL_DisableOCSP(ssl) != SSL_SUCCESS){

/*Returned with an error. Failure case in this block. */

}

See Also:

wolfSSL_CertManagerDisableOCSP

wolfSSL_UseOCSPStapling

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseOCSPStapling(WOLFSSL* ssl, byte status_type, byte options);

Description:

Stapling eliminates the need to contact the CA. Stapling lowers the cost of certificate

revocation check presented in OCSP.

Return Values:

SSL_SUCCESS - returned if TLSX_UseCertificateStatusRequest executes without

error.

MEMORY_E - returned if there is an error with the allocation of memory.

BAD_FUNC_ARG - returned if there is an argument that has a NULL or otherwise

unacceptable value passed into the function.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

status_type - a byte type that is passed through to

TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest

structure.

options - a byte type that is passed through to TLSX_UseCertificateStatusRequest()

and stored in the CertificateStatusRequest structure.

Example:

406

WOLFSSL* ssl = wolfSSL_new(ctx);

…

if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP,

WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){

/*Failed case. */

}

See Also:

TLSX_UseCertificateStatusRequest

wolfSSL_CTX_UseOCSPStapling

EmbedOcspLookup

Synopsis:

#include <wolfssl/ssl.h>

int EmbedOcspLookup(void* ctx, const char* url, int urlSz, byte* ocspReqBuf,

int ocspReqSz, byte** ocspRespBuf);

Description:

This function retrieves the OCSP response from an OCSP responder URL given an

input request.

Return Values:

>0 - OCSP Response Size

-1 - Error returned.

Parameters:

ctx - a void pointer representing the heap pointer.

url - a char pointer for the OCSP url for certificate verification.

urlSz - a byte pointer for the url size.

ocspReqBuf - a byte pointer for the OCSP request buffer.

ocspReqSz - an int type representing the size of the request buffer.

407

ocspRespBuf - a byte pointer that holds the OCSP response.

Example:

WOLFSSL_CERT_MANAGER* cm;

int options;

int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER* cm, int options){

…

#ifndef WOLFSSL_USER_IO

cm->ocspIOCb = EmbedOcspLookup;

cm->ocspRespFreeCb = EmbedOcspRespFree;

#endif

See Also:

Process_http_response

build_http_request

wolfSSL_CertManagerEnableOCSPStapling

wolfSSL_CTX_UseOCSPStaplingV2

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx, bute status_type,

byte options);

Description:

Creates and initializes the certificate status request for OCSP Stapling.

Return Values:

SSL_SUCCESS - if the function and subroutines executed without error.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure is NULL or if the side

variable is not client side.

MEMORY_E - returned if the allocation of memory failed.

Parameters:

408

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

status_type - a byte type that is located in the CertificatStatusRequest structure and

must be either WOLFSSL_CSR2_OCSP or WOLFSSL_CSR2_OCSP_MULTI.

options - a byte type that will be held in CertificateStatusRequestItemV2 struct.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

byte status_type;

byte options;

...

if(wolfSSL_CTX_UseOCSPStaplingV2(ctx, status_type, options); != SSL_SUCCESS){

/*Failure case. */

}

See Also:

TLSX_UseCertificateStatusRequestV2

wc_RNG_GenerateBlock

TLSX_Push

wolfSSL_UseOCSPStaplingV2

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl, byte status_type, byte options);

Description:

The function sets the status type and options for OCSP.

Return Values:

SSL_SUCCESS - returned if the function and subroutines executed without error.

MEMORY_E - returned if there was an allocation of memory error.

409

BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted argument was passed

to the function or a subroutine.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

status_type - a byte type that loads the OCSP status type.

options - a byte type that holds the OCSP options, set in wolfSSL_SNI_SetOptions()

and wolfSSL_CTX_SNI_SetOptions().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if (wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, 0) !=

SSL_SUCCESS){

/*Did not execute properly. Failure case code block. */

}

See Also:

TLSX_UseCertificatStatusRequestV2

wolfSSL_SNI_SetOptions

wolfSSL_CTX_SNI_SetOptions

wolfSSL_CTX_LoadCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX* ctx, const char* path, int type,

int monitor);

Description:

This function loads CRL into the WOLFSSL_CTX structure through

wolfSSL_CertManagerLoadCRL().

410

Return Values:

SSL_SUCCESS - returned if the function and its subroutines execute without error.

BAD_FUNC_ARG - returned if this function or any subroutines are passed NULL

structures.

BAD_PATH_ERROR - returned if the path variable opens as NULL.

MEMORY_E - returned if an allocation of memory failed.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

path - the path to the certificate.

type - an integer variable holding the type of certificate.

monitor - an integer variable used to determine if the monitor path is requested.

Example:

WOLFSSL_CTX* ctx;

const char* path;

…

return wolfSSL_CTX_LoadCRL(ctx, path, SSL_FILETYPE_PEM, 0);

See Also:

wolfSSL_CertManagerLoadCRL

LoadCRL

wolfSSL_CertManagerLoadCRLBuffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER* cm,

const unsigned char* buff, long sz, int type);

Description:

411

The function loads the CRL file by calling BufferLoadCRL.

Return Values:

SSL_SUCCESS - returned if the function completed without errors.

BAD_FUNC_ARG - returned if the WOLFSSL_CERT_MANAGER is NULL .

SSL_FATAL_ERROR - returned if there is an error associated with the

WOLFSSL_CERT_MANAGER.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure.

buff - a constant byte type and is the buffer.

sz - a long int representing the size of the buffer.

type - a long integer that holds the certificate type.

Example:

WOLFSSL_CERT_MANAGER* cm;

const unsigned char* buff;

long sz; /*size of buffer*/

int type; /*cert type*/

...

int ret = wolfSSL_CertManagerLoadCRLBuffer(cm, buff, sz, type);

if(ret == SSL_SUCCESS){

return ret;

} else {

/*Failure case. */

}

See Also:

BufferLoadCRL

wolfSSL_CertManagerEnableCRL

wolfSSL_LoadCRL

412

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, int monitor);

Description:

A wrapper function that ends up calling LoadCRL to load the certificate for revocation

checking.

Return Values:

WOLFSSL_SUCCESS - returned if the function and all of the subroutines executed

without error.

SSL_FATAL_ERROR - returned if one of the subroutines does not return successfully.

BAD_FUNC_ARG - f the WOLFSSL_CERT_MANAGER or the WOLFSSL structure are

NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

path - a constant character pointer that holds the path to the crl file.

type - an integer representing the type of certificate.

monitor - an integer variable used to verify the monitor path if requested.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

const char* crlPemDir;

…

if(wolfSSL_LoadCRL(ssl, crlPemDir, SSL_FILETYPE_PEM, 0) != SSL_SUCCESS){

/*Failure case. Did not return SSL_SUCCESS. */

}

See Also:

wolfSSL_CertManagerLoadCRL

wolfSSL_CertManagerEnableCRL

413

LoadCRL

wolfSSL_DisableCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_DisableCRL(WOLFSSL* ssl);

Description:

Disables CRL certificate revocation.

Return Values:

SSL_SUCCESS - wolfSSL_CertMangerDisableCRL successfully disabled the

crlEnabled member of the WOLFSSL_CERT_MANAGER structure.

BAD_FUNC_ARG - the WOLFSSL structure was NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_DisableCRL(ssl) != SSL_SUCCESS){

/*Failure case*/

}

See Also:

wolfSSL_CertManagerDisableCRL

wolfSSL_CertManagerDisableOCSP

Synopsis:

#include <wolfssl/ssl.h>

414

int wolfSSL_CertManagerDisableOCSP(WOLFSSL* ssl);

Description:

Disables OCSP certificate revocation.

Return Values:

SSL_SUCCESS - wolfSSL_CertMangerDisableCRL successfully disabled the

crlEnabled member of the WOLFSSL_CERT_MANAGER structure.

BAD_FUNC_ARG - the WOLFSSL structure was NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_CertManagerDisableOCSP(ssl) != SSL_SUCCESS){

/*Fail case. */

}

See Also:

wolfSSL_DisableCRL

wolfSSL_CertManagerCheckCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER* cm, byte* der,

int sz);

Description:

Check CRL if the option is enabled and compares the cert to the CRL list.

415

Return Values:

SSL_SUCCESS - returns if the function returned as expected. If the crlEnabled member

of the WOLFSSL_CERT_MANAGER struct is turned on.

MEMORY_E - returns if the allocated memory failed.

BAD_FUNC_ARG - if the WOLFSSL_CERT_MANAGER is NULL.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER struct.

der - pointer to a DER formatted certificate.

sz - size of the certificate.

Example:

WOLFSSL_CERT_MANAGER* cm;

byte* der;

int sz; /*size of der */

...

if(wolfSSL_CertManagerCheckCRL(cm, der, sz) != SSL_SUCCESS){

/*Error returned. Deal with failure case. */

}

See Also:

CheckCertCRL

ParseCertRelative

wolfSSL_CertManagerSetCRL_CB

InitDecodedCert

wolfSSL_CTX_EnableCRL

Synopsis:

416

#include <wolfssl/ssl.h>

int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options);

Description:

Enables CRL certificate verification through the CTX.

Return Values:

SSL_SUCCESS - returned if this function and it’s subroutines execute without errors.

BAD_FUNC_ARG - returned if the CTX struct is NULL or there was otherwise an

invalid argument passed in a subroutine.

MEMORY_E - returned if there was an error allocating memory during execution of the

function.

SSL_FAILURE - returned if the crl member of the WOLFSSL_CERT_MANAGER fails

to initialize correctly.

NOT_COMPILED_IN - wolfSSL was not compiled with the HAVE_CRL option.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_CTX_EnableCRL(ssl->ctx, options) != SSL_SUCCESS){

/*The function failed*/

}

See Also:

wolfSSL_CertManagerEnableCRL

InitCRL

wolfSSL_CTX_DisableCRL

417

wolfSSL_CTX_DisableCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx);

Description:

This function disables CRL verification in the CTX structure.

Return Values:

SSL_SUCCESS - returned if the function executes without error. The crlEnabled

member of the WOLFSSL_CERT_MANAGER struct is set to 0.

BAD_FUNC_ARG - returned if either the CTX struct or the CM struct has a NULL

value.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_CTX_DisableCRL(ssl->ctx) != SSL_SUCCESS){

/*Failure case.*/

}

See Also:

wolfSSL_CertManagerDisableCRL

wolfSSL_EnableOCSP

Synopsis:

#include <wolfssl/ssl.h>

418

int wolfSSL_EnableOCSP(WOLFSSL* ssl, int options);

Description:

This function enables OCSP certificate verification.

Return Values:

SSL_SUCCESS - returned if the function and subroutines executes without errors.

BAD_FUNC_ARG - returned if an argument in this function or any subroutine receives

an invalid argument value.

MEMORY_E - returned if there was an error allocating memory for a structure or other

variable.

NOT_COMPILED_IN - returned if wolfSSL was not compiled with the HAVE_OCSP

option.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

options - an integer type passed to wolfSSL_CertMangerENableOCSP() used for

settings check.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int options; /*initialize to option constant*/

…

int ret = wolfSSL_EnableOCSP(ssl, options);

if(ret != SSL_SUCCESS){

/*OCSP is not enabled*/

}

See Also:

wolfSSL_CertManagerEnableOCSP

wolfSSL_CTX_UseOCSPStapling

419

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx, byte status_type,

byte options);

Description:

This function requests the certificate status during the handshake.

Return Values:

SSL_SUCCESS - returned if the function and subroutines execute without error.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure is NULL or otherwise if a

unpermitted value is passed to a subroutine.

MEMORY_E - returned if the function or subroutine failed to properly allocate memory.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

status_type - a byte type that is passed through to

TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest

structure.

options - a byte type that is passed through to TLSX_UseCertificateStatusRequest()

and stored in the CertificateStatusRequest structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

byte statusRequest = 0; /*Initialize status request*/

…

switch(statusRequest){

case WOLFSSL_CSR_OCSP:

if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP,

WOLF_CSR_OCSP_USE_NONCE) != SSL_SUCCESS){

/*UseCertificateStatusRequest failed*/

}

/*Continue switch cases*/

See Also:

420

wolfSSL_UseOCSPStaplingV2

wolfSSL_UseOCSPStapling

TLSX_UseCertificateStatusRequest

wolfSSL_CTX_DisableOCSP

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX* ctx);

Description:

This function disables OCSP certificate revocation checking by affecting the

ocspEnabled member of the WOLFSSL_CERT_MANAGER structure.

Return Values:

SSL_SUCCESS - returned if the function executes without error. The ocspEnabled

member of the CM has been disabled.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure is NULL.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(!wolfSSL_CTX_DisableOCSP(ssl->ctx)){

/*OCSP is not disabled*/

}

See Also:

wolfSSL_DisableOCSP

wolfSSL_CertManagerDisableOCSP

421

wolfSSL_CTX_EnableOCSPStapling

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx);

Description:

This function enables OCSP stapling by calling

wolfSSL_CertManagerEnableOCSPStapling().

Return Values:

SSL_SUCCESS - returned if there were no errors and the function executed

successfully.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure is NULL or otherwise if

there was a unpermitted argument value passed to a subroutine.

MEMORY_E - returned if there was an issue allocating memory.

SSL_FAILURE - returned if the initialization of the OCSP structure failed.

NOT_COMPILED_IN - returned if wolfSSL was not compiled with

HAVE_CERTIFICATE_STATUS_REQUEST option.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example:

WOLFSSL* ssl = WOLFSSL_new();

ssl->method.version; /*set to desired protocol*/

...

if(!wolfSSL_CTX_EnableOCSPStapling(ssl->ctx)){

/*OCSP stapling is not enabled*/

}

See Also:

422

wolfSSL_CertManagerEnableOCSPStapling

InitOCSP

wolfSSL_CertManagerEnableOCSPStapling

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CertManagerEnableOCSPStapling(WOLFSSL_CERT_MANAGER* cm);

Description:

This function turns on OCSP stapling if it is not turned on as well as set the options.

Return Values:

SSL_SUCCESS - returned if there were no errors and the function executed

successfully.

BAD_FUNC_ARG - returned if the WOLFSSL_CERT_MANAGER structure is NULL or

otherwise if there was a unpermitted argument value passed to a subroutine.

MEMORY_E - returned if there was an issue allocating memory.

SSL_FAILURE - returned if the initialization of the OCSP structure failed.

NOT_COMPILED_IN - returned if wolfSSL was not compiled with

HAVE_CERTIFICATE_STATUS_REQUEST option.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the

WOLFSSL_CTX structure.

Example:

int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx){

…

return wolfSSL_CertManagerEnableOCSPStapling(ctx->cm);

See Also:

423

wolfSSL_CTX_EnableOCSPStapling

wolfSSL_SetOCSP_OverrideURL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url);

Description:

This function sets the ocspOverrideURL member in the WOLFSSL_CERT_MANAGER

structure.

Return Values:

SSL_SUCCESS - returned on successful execution of the function.

BAD_FUNC_ARG - returned if the WOLFSSL struct is NULL or if a unpermitted

argument was passed to a subroutine.

MEMORY_E - returned if there was an error allocating memory in the subroutine.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

url - a constant char pointer to the url that will be stored in the ocspOverrideURL

member of the WOLFSSL_CERT_MANAGER structure.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

char url[URLSZ];

...

if(wolfSSL_SetOCSP_OverrideURL(ssl, url)){

/*The override url is set to the new value*/

}

See Also:

wolfSSL_CertManagerSetOCSPOverrideURL

424

17.7 Informational

The functions in this section are informational. They allow the application to gather

some kind of information about the current status or setup of wolfSSL.

wolfSSL_GetObjectSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetObjectSize(void);

Description:

This function returns the size of the WOLFSSL object and will be dependent on build

options and settings. If SHOW_SIZES has been defined when building wolfSSL, this

function will also print the sizes of individual objects within the WOLFSSL object (Suites,

Ciphers, etc.) to stdout.

Return Values:

This function returns the size of the WOLFSSL object.

Parameters:

This function has no parameters.

Example:

int size = 0;

size = wolfSSL_GetObjectSize();

printf(“sizeof(WOLFSSL) = %d\n”, size);

See Also:

wolfSSL_new();

425

wolfSSL_GetMacSecret

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_GetMacSecret(WOLFSSL* ssl, int verify);

Description:

Allows retrieval of the Hmac/Mac secret from the handshake process. The verify

parameter specifies whether this is for verification of a peer message.

Return Values:

If successful the call will return a valid pointer to the secret. The size of the secret can

be obtained from wolfSSL_GetHmacSize().

NULL will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

verify - specifies whether this is for verification of a peer message.

See Also:

wolfSSL_GetHmacSize()

wolfSSL_GetClientWriteKey

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_GetClientWriteKey(WOLFSSL* ssl);

Description:

Allows retrieval of the client write key from the handshake process.

Return Values:

426

If successful the call will return a valid pointer to the key. The size of the key can be

obtained from wolfSSL_GetKeySize().

NULL will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetKeySize()

wolfSSL_GetClientWriteIV()

wolfSSL_GetClientWriteIV

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_GetClientWriteIV(WOLFSSL* ssl);

Description:

Allows retrieval of the client write IV (initialization vector) from the handshake process.

Return Values:

If successful the call will return a valid pointer to the IV. The size of the IV can be

obtained from wolfSSL_GetCipherBlockSize().

NULL will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetCipherBlockSize()

wolfSSL_GetClientWriteKey()

wolfSSL_GetServerWriteKey

427

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_GetServerWriteKey(WOLFSSL* ssl);

Description:

Allows retrieval of the server write key from the handshake process.

Return Values:

If successful the call will return a valid pointer to the key. The size of the key can be

obtained from wolfSSL_GetKeySize().

NULL will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetKeySize()

wolfSSL_GetServerWriteIV()

wolfSSL_GetServerWriteIV

Synopsis:

#include <wolfssl/ssl.h>

const byte* wolfSSL_GetServerWriteIV(WOLFSSL* ssl);

Description:

Allows retrieval of the server write IV (initialization vector) from the handshake process.

Return Values:

If successful the call will return a valid pointer to the IV. The size of the IV can be

obtained from wolfSSL_GetCipherBlockSize().

NULL will be returned for an error state.

428

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetCipherBlockSize()

wolfSSL_GetClientWriteKey()

wolfSSL_GetKeySize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetKeySize(WOLFSSL* ssl);

Description:

Allows retrieval of the key size from the handshake process.

Return Values:

If successful the call will return the key size in bytes.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetClientWriteKey()

wolfSSL_GetServerWriteKey()

wolfSSL_GetSide

Synopsis:

#include <wolfssl/ssl.h>

429

int wolfSSL_GetSide(WOLFSSL* ssl);

Description:

Allows retrieval of the side of this WOLFSSL connection.

Return Values:

If successful the call will return either WOLFSSL_SERVER_END or

WOLFSSL_CLIENT_END depending on the side of WOLFSSL object.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetClientWriteKey()

wolfSSL_GetServerWriteKey()

wolfSSL_IsTLSv1_1

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_IsTLSV1_1(WOLFSSL* ssl);

Description:

Allows caller to determine if the negotiated protocol version is at least TLS version 1.1

or greater.

Return Values:

If successful the call will return 1 for true or 0 for false.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

430

See Also:

wolfSSL_GetSide()

wolfSSL_GetBulkCipher

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetBulkCipher(WOLFSSL* ssl);

Description:

Allows caller to determine the negotiated bulk cipher algorithm from the handshake.

Return Values:

If successful the call will return one of the following:

wolfssl_cipher_null

wolfssl_des

wolfssl_triple_des

wolfssl_aes

wolfssl_aes_gcm

wolfssl_aes_ccm

wolfssl_camellia

wolfssl_hc128

wolfssl_rabbit

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetCipherBlockSize()

wolfSSL_GetKeySize()

wolfSSL_GetCipherBlockSize

431

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetCipherBlockSize(WOLFSSL* ssl);

Description:

Allows caller to determine the negotiated cipher block size from the handshake.

Return Values:

If successful the call will return the size in bytes of the cipher block size.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetKeySize()

wolfSSL_GetAeadMacSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetAeadMacSize(WOLFSSL* ssl);

Description:

Allows caller to determine the negotiated aead mac size from the handshake. For

cipher type WOLFSSL_AEAD_TYPE.

Return Values:

If successful the call will return the size in bytes of the aead mac size.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

432

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetKeySize()

wolfSSL_GetHmacSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetHmacSize(WOLFSSL* ssl);

Description:

Allows caller to determine the negotiated (h)mac size from the handshake. For cipher

types except WOLFSSL_AEAD_TYPE.

Return Values:

If successful the call will return the size in bytes of the (h)mac size.

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetHmacType()

wolfSSL_GetHmacType

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetHmacType(WOLFSSL* ssl);

Description:

433

Allows caller to determine the negotiated (h)mac type from the handshake. For cipher

types except WOLFSSL_AEAD_TYPE.

Return Values:

If successful the call will return one of the following:

MD5

SHA

SHA256

SHA384

BAD_FUNC_ARG or SSL_FATAL_ERROR will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetHmacSize()

wolfSSL_GetCipherType

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetCipherType(WOLFSSL* ssl);

Description:

Allows caller to determine the negotiated cipher type from the handshake.

Return Values:

If successful the call will return one of the following:

WOLFSSL_BLOCK_TYPE

WOLFSSL_STREAM_TYPE

WOLFSSL_AEAD_TYPE

434

BAD_FUNC_ARG will be returned for an error state.

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetBulkCipher()

wolfSSL_GetHmacType()

wolfSSL_GetOutputSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetOutputSize(WOLFSSL* ssl, int inSz);

Description:

Returns the record layer size of the plaintext input. This is helpful when an application

wants to know how many bytes will be sent across the Transport layer, given a specified

plaintext input size.

This function must be called after the SSL/TLS handshake has been completed.

Return Values:

Upon success, the requested size will be returned. Upon error, one of the following will

be returned:

INPUT_SIZE_E will be returned if the input size is greater than the maximum TLS

fragment size (see wolfSSL_GetMaxOutputSize())

BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS

handshake has not been completed yet

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

inSz - size of plaintext data

435

See Also:

wolfSSL_GetMaxOutputSize()

wolfSSL_GetMaxOutputSize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetMaxOutputSize(WOLFSSL* ssl);

Description:

Returns the maximum record layer size for plaintext data. This will correspond to either

the maximum SSL/TLS record size as specified by the protocol standard, the maximum

TLS fragment size as set by the TLS Max Fragment Length extension.

This function is helpful when the application has called wolfSSL_GetOutputSize() and

received a INPUT_SIZE_E error.

This function must be called after the SSL/TLS handshake has been completed.

Return Values:

Upon success, the maximum output size will be returned. Upon error, one of the

following will be returned:

BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS

handshake has not been completed yet

Parameters:

ssl - a pointer to a WOLFSSL object, created using wolfSSL_new().

See Also:

wolfSSL_GetOutputSize()

17.8 Connection, Session, and I/O

The functions in this section deal with setting up the SSL/TLS connection, managing

436

SSL sessions, and input/output.

wolfSSL_accept

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_accept(WOLFSSL* ssl);

Description:

This function is called on the server side and waits for an SSL client to initiate the

SSL/TLS handshake. When this function is called, the underlying communication

channel has already been set up.

wolfSSL_accept() works with both blocking and non-blocking I/O. When the underlying

I/O is non-blocking, wolfSSL_accept() will return when the underlying I/O could not

satisfy the needs of wolfSSL_accept to continue the handshake. In this case, a call to

wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to

wolfSSL_accept when data is available to read and wolfSSL will pick up where it left off.

When using a non-blocking socket, nothing needs to be done, but select() can be used

to check for the required condition.

If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake

has been finished or an error occurred.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error

code, call wolfSSL_get_error().

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

int ret = 0;

int err = 0;

437

WOLFSSL* ssl;

char buffer[80];

...

ret = wolfSSL_accept(ssl);

if (ret != SSL_SUCCESS) {

err = wolfSSL_get_error(ssl, ret);

printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));

}

See Also:

wolfSSL_get_error

wolfSSL_connect

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_connect(WOLFSSL* ssl);

Description:

This function is called on the client side and initiates an SSL/TLS handshake with a

server. When this function is called, the underlying communication channel has already

been set up.

wolfSSL_connect() works with both blocking and non-blocking I/O. When the

underlying I/O is non-blocking, wolfSSL_connect() will return when the underlying I/O

could not satisfy the needs of wolfSSL_connect to continue the handshake. In this

case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to

wolfSSL_connect() when the underlying I/O is ready and wolfSSL will pick up where it

left off. When using a non-blocking socket, nothing needs to be done, but select() can

be used to check for the required condition.

If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake

has been finished or an error occurred.

wolfSSL takes a different approach to certificate verification than OpenSSL does. The

default policy for the client is to verify the server, this means that if you don't load CAs to

verify the server you'll get a connect error, unable to verify (-155). It you want to mimic

OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and

438

reducing security you can do this by calling:

SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);

before calling SSL_new(); Though it's not recommended.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error

code, call wolfSSL_get_error().

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

int ret = 0;

int err = 0;

WOLFSSL* ssl;

char buffer[80];

...

ret = wolfSSL_connect(ssl);

if (ret != SSL_SUCCESS) {

err = wolfSSL_get_error(ssl, ret);

printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));

}

See Also:

wolfSSL_get_error

wolfSSL_accept

wolfSSL_connect_cert

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_connect_cert(WOLFSSL* ssl);

439

Description:

This function is called on the client side and initiates an SSL/TLS handshake with a

server only long enough to get the peer’s certificate chain. When this function is called,

the underlying communication channel has already been set up.

wolfSSL_connect_cert() works with both blocking and non-blocking I/O. When the

underlying I/O is non-blocking, wolfSSL_connect_cert() will return when the underlying

I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the handshake.

In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ

or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to

wolfSSL_connect_cert() when the underlying I/O is ready and wolfSSL will pick up

where it left off. When using a non-blocking socket, nothing needs to be done, but

select() can be used to check for the required condition.

If the underlying I/O is blocking, wolfSSL_connect_cert() will only return once the peer’s

certificate chain has been received.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_FAILURE will be returned if the SSL session parameter is NULL.

SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error

code, call wolfSSL_get_error().

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

int ret = 0;

int err = 0;

WOLFSSL* ssl;

char buffer[80];

...

ret = wolfSSL_connect_cert(ssl);

if (ret != SSL_SUCCESS) {

err = wolfSSL_get_error(ssl, ret);

printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));

}

440

See Also:

wolfSSL_get_error

wolfSSL_connect

wolfSSL_accept

wolfSSL_get_fd

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_fd(const WOLFSSL* ssl);

Description:

This function returns the file descriptor (fd) used as the input/output facility for the SSL

connection. Typically this will be a socket file descriptor.

Return Values:

If successful the call will return the SSL session file descriptor.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int sockfd;

WOLFSSL* ssl = 0;

...

sockfd = wolfSSL_get_fd(ssl);

...

See Also:

wolfSSL_set_fd

wolfSSL_get_session

Synopsis:

#include <wolfssl/ssl.h>

441

WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);

Description:

This function returns a pointer to the current session (WOLFSSL_SESSION) used in

ssl. The WOLFSSL_SESSION pointed to contains all the necessary information

required to perform a session resumption and reestablish the connection without a new

handshake.

For session resumption, before calling wolfSSL_shutdown() with your session object, an

application should save the session ID from the object with a call to

wolfSSL_get_session(), which returns a pointer to the session. Later, the application

should create a new WOLFSSL object and assign the saved session with

wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and

wolfSSL will try to resume the session. The wolfSSL server code allows session

resumption by default.

Return Values:

If successful the call will return a pointer to the the current SSL session object.

NULL will be returned if ssl is NULL, the SSL session cache is disabled, wolfSSL

doesn’t have the Session ID available, or mutex functions fail.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

WOLFSSL* ssl = 0;

WOLFSSL_SESSION* session = 0;

...

session = wolfSSL_get_session(ssl);

if (session == NULL) {

/*failed to get session pointer*/

}

...

See Also:

wolfSSL_set_session

wolfSSL_get_using_nonblock

442

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_using_nonblock(WOLFSSL* ssl);

Description:

This function allows the application to determine if wolfSSL is using non-blocking I/O. If

wolfSSL is using non-blocking I/O, this function will return 1, otherwise 0.

After an application creates a WOLFSSL object, if it will be used with a non-blocking

socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know

that receiving EWOULDBLOCK means that the recvfrom call would block rather than

that it timed out.

Return Values:

0 - underlying I/O is blocking.

1 - underlying I/O is non-blocking.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret = 0;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_get_using_nonblock(ssl);

if (ret == 1) {

/*underlying I/O is non-blocking*/

}

...

See Also:

wolfSSL_set_session

wolfSSL_flush_sessions

Synopsis:

443

#include <wolfssl/ssl.h>

void wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm);

Description:

This function flushes session from the session cache which have expired. The time, tm,

is used for the time comparison.

Note that wolfSSL currently uses a static table for sessions, so no flushing is needed.

As such, this function is currently just a stub. This function provides OpenSSL

compatibility (SSL_flush_sessions) when wolfSSL is compiled with the OpenSSL

compatibility layer.

Return Values:

This function does not have a return value.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

tm - time used in session expiration comparison.

Example:

WOLFSSL_CTX* ssl;

...

wolfSSL_flush_sessions(ctx, time(0));

See Also:

wolfSSL_get_session

wolfSSL_set_session

wolfSSL_negotiate

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_negotiate(WOLFSSL* ssl);

Description:

444

Performs the actual connect or accept based on the side of the SSL method. If called

from the client side then an wolfSSL_connect() is done while a wolfSSL_accept() is

performed if called from the server side.

Return Values:

SSL_SUCCESS will be returned if successful. (Note, older versions will return 0.)

SSL_FATAL_ERROR will be returned if the underlying call resulted in an error. Use

wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int ret = SSL_FATAL_ERROR;

WOLFSSL* ssl = 0;

...

ret = wolfSSL_negotiate(ssl);

if (ret == SSL_FATAL_ERROR) {

/*SSL establishment failed*/

int error_code = wolfSSL_get_error(ssl);

...

}

...

See Also:

SSL_connect

SSL_accept

wolfSSL_peek

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_peek(WOLFSSL* ssl, void* data, int sz);

Description:

This function copies sz bytes from the SSL session (ssl) internal read buffer into the

buffer data. This function is identical to wolfSSL_read() except that the data in the

internal SSL session receive buffer is not removed or modified.

445

If necessary, like wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if

the handshake has not already been performed yet by wolfSSL_connect() or

wolfSSL_accept().

The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max

record size can be controlled by the MAX_RECORD_SIZE define in

<wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record

internally before it is able to process and decrypt the record. Because of this, a call to

wolfSSL_peek() will only be able to return the maximum buffer size which has been

decrypted at the time of calling. There may be additional not-yet-decrypted data waiting

in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next

call to wolfSSL_peek() / wolfSSL_read().

If sz is larger than the number of bytes in the internal read buffer, SSL_peek() will return

the bytes available in the internal read buffer. If no bytes are buffered in the internal

read buffer yet, a call to wolfSSL_peek() will trigger processing of the next record.

Return Values:

>0 - the number of bytes read upon success.

0 - will be returned upon failure. This may be caused by a either a clean (close notify

alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for

the specific error code.

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_peek() again. Use wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

data - buffer where wolfSSL_peek() will place data read.

sz - number of bytes to read into data.

446

Example:

WOLFSSL* ssl = 0;

char reply[1024];

...

input = wolfSSL_peek(ssl, reply, sizeof(reply));

if (input > 0) {

/*“input” number of bytes returned into buffer “reply”*/

}

See Also:

wolfSSL_read

wolfSSL_pending

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_pending(WOLFSSL* ssl);

Description:

This function returns the number of bytes which are buffered and available in the SSL

object to be read by wolfSSL_read().

Return Values:

This function returns the number of bytes pending.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

Example:

int pending = 0;

WOLFSSL* ssl = 0;

...

pending = wolfSSL_pending(ssl);

printf(“There are %d bytes buffered and available for reading”, pending);

447

See Also:

wolfSSL_recv

wolfSSL_read

wolfSSL_peek

wolfSSL_read

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_read(WOLFSSL* ssl, void* data, int sz);

Description:

This function reads sz bytes from the SSL session (ssl) internal read buffer into the

buffer data. The bytes read are removed from the internal receive buffer.

If necessary wolfSSL_read() will negotiate an SSL/TLS session if the handshake has

not already been performed yet by wolfSSL_connect() or wolfSSL_accept().

The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max

record size can be controlled by the MAX_RECORD_SIZE define in

<wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record

internally before it is able to process and decrypt the record. Because of this, a call to

wolfSSL_read() will only be able to return the maximum buffer size which has been

decrypted at the time of calling. There may be additional not-yet-decrypted data waiting

in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next

call to wolfSSL_read().

If sz is larger than the number of bytes in the internal read buffer, SSL_read() will return

the bytes available in the internal read buffer. If no bytes are buffered in the internal

read buffer yet, a call to wolfSSL_read() will trigger processing of the next record.

Return Values:

>0 - the number of bytes read upon success.

0 - will be returned upon failure. This may be caused by a either a clean (close notify

alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for

the specific error code.

448

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_read() again. Use wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

data - buffer where wolfSSL_read() will place data read.

sz - number of bytes to read into data.

Example:

WOLFSSL* ssl = 0;

char reply[1024];

...

input = wolfSSL_read(ssl, reply, sizeof(reply));

if (input > 0) {

/*“input” number of bytes returned into buffer “reply”*/

}

See wolfSSL examples (client, server, echoclient, echoserver) for more complete

examples of wolfSSL_read().

See Also:

wolfSSL_recv

wolfSSL_write

wolfSSL_peek

wolfSSL_pending

wolfSSL_recv

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_recv(WOLFSSL* ssl, void* data, int sz, int flags);

449

Description:

This function reads sz bytes from the SSL session (ssl) internal read buffer into the

buffer data using the specified flags for the underlying recv operation. The bytes read

are removed from the internal receive buffer. This function is identical to

wolfSSL_read() except that it allows the application to set the recv flags for the

underlying read operation.

If necessary wolfSSL_recv() will negotiate an SSL/TLS session if the handshake has

not already been performed yet by wolfSSL_connect() or wolfSSL_accept().

The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max

record size can be controlled by the MAX_RECORD_SIZE define in

<wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record

internally before it is able to process and decrypt the record. Because of this, a call to

wolfSSL_recv() will only be able to return the maximum buffer size which has been

decrypted at the time of calling. There may be additional not-yet-decrypted data waiting

in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next

call to wolfSSL_recv().

If sz is larger than the number of bytes in the internal read buffer, SSL_recv() will return

the bytes available in the internal read buffer. If no bytes are buffered in the internal

read buffer yet, a call to wolfSSL_recv() will trigger processing of the next record.

Return Values:

>0 - the number of bytes read upon success.

0 - will be returned upon failure. This may be caused by a either a clean (close notify

alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for

the specific error code.

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

450

data - buffer where wolfSSL_recv() will place data read.

sz - number of bytes to read into data.

flags - the recv flags to use for the underlying recv operation.

Example:

WOLFSSL* ssl = 0;

char reply[1024];

int flags = ... ;

...

input = wolfSSL_recv(ssl, reply, sizeof(reply), flags);

if (input > 0) {

/*“input” number of bytes returned into buffer “reply”*/

}

See Also:

wolfSSL_read

wolfSSL_write

wolfSSL_peek

wolfSSL_pending

wolfSSL_send

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_send(WOLFSSL* ssl, const void* data, int sz, int flags);

Description:

This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the

specified flags for the underlying write operation.

If necessary wolfSSL_send() will negotiate an SSL/TLS session if the handshake has

not already been performed yet by wolfSSL_connect() or wolfSSL_accept().

wolfSSL_send() works with both blocking and non-blocking I/O. When the underlying

451

I/O is non-blocking, wolfSSL_send() will return when the underlying I/O could not satisfy

the needs of wolfSSL_send to continue. In this case, a call to wolfSSL_get_error() will

yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling

process must then repeat the call to wolfSSL_send() when the underlying I/O is ready.

If the underlying I/O is blocking, wolfSSL_send() will only return once the buffer data of

size sz has been completely written or an error occurred.

Return Values:

>0 - the number of bytes written upon success.

0 - will be returned upon failure. Call wolfSSL_get_error() for the specific error code.

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_send() again. Use wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

data - data buffer to send to peer.

sz - size, in bytes, of data to be sent to peer.

flags - the send flags to use for the underlying send operation.

Example:

WOLFSSL* ssl = 0;

char msg[64] = “hello wolfssl!”;

int msgSz = (int)strlen(msg);

int flags = ... ;

...

input = wolfSSL_send(ssl, msg, msgSz, flags);

if (input != msgSz) {

// wolfSSL_send() failed

452

}

See Also:

wolfSSL_write

wolfSSL_read

wolfSSL_recv

wolfSSL_write

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_write(WOLFSSL* ssl, const void* data, int sz);

Description:

This function writes sz bytes from the buffer, data, to the SSL connection, ssl.

If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has

not already been performed yet by wolfSSL_connect() or wolfSSL_accept().

wolfSSL_write() works with both blocking and non-blocking I/O. When the underlying

I/O is non-blocking, wolfSSL_write() will return when the underlying I/O could not satisfy

the needs of wolfSSL_write() to continue. In this case, a call to wolfSSL_get_error() will

yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling

process must then repeat the call to wolfSSL_write() when the underlying I/O is ready.

If the underlying I/O is blocking, wolfSSL_write() will only return once the buffer data of

size sz has been completely written or an error occurred.

Return Values:

>0 - the number of bytes written upon success.

0 - will be returned upon failure. Call wolfSSL_get_error() for the specific error code.

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code.

453

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

data - data buffer which will be sent to peer.

sz - size, in bytes, of data to send to the peer (data).

Example:

WOLFSSL* ssl = 0;

char msg[64] = “hello wolfssl!”;

int msgSz = (int)strlen(msg);

int flags;

int ret;

...

ret = wolfSSL_write(ssl, msg, msgSz);

if (ret <= 0) {

/*wolfSSL_write() failed, call wolfSSL_get_error()*/

}

See wolfSSL examples (client, server, echoclient, echoserver) for more more detailed

examples of wolfSSL_write().

See Also:

wolfSSL_send

wolfSSL_read

wolfSSL_recv

wolfSSL_writev

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_writev(WOLFSSL* ssl, const struct iovec* iov, int iovcnt);

Description:

Simulates writev semantics but doesn’t actually do block at a time because of

SSL_write() behavior and because front adds may be small. Makes porting into

software that uses writev easier.

454

Return Values:

>0 - the number of bytes written upon success.

0 - will be returned upon failure. Call wolfSSL_get_error() for the specific error code.

MEMORY_ERROR will be returned if a memory error was encountered.

SSL_FATAL_ERROR - will be returned upon failure when either an error occurred or,

when using non-blocking sockets, the SSL_ERROR_WANT_READ or

SSL_ERROR_WANT_WRITE error was received and and the application needs to call

wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code.

Parameters:

ssl - pointer to the SSL session, created with wolfSSL_new().

iov - array of I/O vectors to write

iovcnt - number of vectors in iov array.

Example:

WOLFSSL* ssl = 0;

char *bufA = “hello\n”;

char *bufB = “hello world\n”;

int iovcnt;

struct iovec iov[2];

iov[0].iov_base = buffA;

iov[0].iov_len = strlen(buffA);

iov[1].iov_base = buffB;

iov[1].iov_len = strlen(buffB);

iovcnt = 2;

...

ret = wolfSSL_writev(ssl, iov, iovcnt);

/*wrote “ret” bytes, or error if <= 0.*/

See Also:

wolfSSL_write

455

wolfSSL_SESSION_get_peer_chain

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_X509_CHAIN*

wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION* session);

Description:

Returns the peer certificate chain from the WOLFSSL_SESSION struct.

Return Values:

A pointer to a WOLFSSL_X509_CHAIN structure that contains the peer certification

chain.

Parameters:

session - a pointer to a WOLFSSL_SESSION structure.

Example:

WOLFSSL_SESSION* session;

WOLFSSL_X509_CHAIN* chain;

...

chain = wolfSSL_SESSION_get_peer_chain(session);

if(!chain){

/*There was no chain. Failure case. */

}

See Also:

get_locked_session_stats

wolfSSL_GetSessionAtIndex

wolfSSL_GetSessionIndex

AddSession

wolfSSL_get_session_cache_memsize

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_session_cache_memsize(void);

456

Description:

This function returns how large the session cache save buffer should be.

Return Values:

This function returns an integer that represents the size of the session cache save

buffer.

Parameters:

This function has no parameters.

Example:

int sz = /*Minimum size for error checking*/;

...

if(sz < wolfSSL_get_session_cache_memsize()){

/*Memory buffer is too small*/

}

See Also:

wolfSSL_memrestore_session_cache

wolfSSL_set_SessionTicket

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_set_SessionTicket(WOLFSSL* ssl, byte* buf, word32 bufSz);

Description:

This function sets the ticket member of the WOLFSSL_SESSION structure within the

WOLFSSL struct. The buffer passed into the function is copied to memory.

Return Values:

SSL_SUCCESS - returned on successful execution of the function. The function

returned without errors.

BAD_FUNC_ARG - returned if the WOLFSSL structure is NULL. This will also be

thrown if the buf argument is NULL but the bufSz argument is not zero.

457

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a byte pointer that gets loaded into the ticket member of the session structure.

bufSz - a word32 type that represents the size of the buffer.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

byte* buffer; /*File to load*/

word32 bufSz; /*size of buffer*/

...

if(wolfSSL_KeepArrays(ssl, buffer, bufSz) != SSL_SUCCESS){

/*There was an error loading the buffer to memory. */

}

See Also:

wolfSSL_set_SessionTicket_cb

nwolfSSL_GetSessionAtIndex

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetSessionAtIndex(int idx, WOLFSSL_SESSION* session);

Description:

This function gets the session at specified index of the session cache and copies it into

memory. The WOLFSSL_SESSION structure holds the session information.

Return Values:

SSL_SUCCESS - returned if the function executed successfully and no errors were

thrown.

BAD_MUTEX_E - returned if there was an unlock or lock mutex error.

SSL_FAILURE - returned if the function did not execute successfully.

458

Parameters:

idx - an int type representing the session index.

session - a pointer to the WOLFSSL_SESSION structure.

Example:

int idx; /*The index to locate the session. */

WOLFSSL_SESSION* session; /*Buffer to copy to. */

...

if(wolfSSL_GetSessionAtIndex(idx, session) != SSL_SUCCESS){

/*Failure case. */

}

See Also:

UnLockMutex

LockMutex

wolfSSL_GetSessionIndex

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_GetSessionIndex(WOLFSSL* ssl);

Description:

This function gets the session index of the WOLFSSL structure.

Return Values:

The function returns an int type representing the sessionIndex within the WOLFSSL

struct.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX_new(/*protocol method*/);

459

WOLFSSL* ssl = WOLFSSL_new(ctx);

...

int sesIdx = wolfSSL_GetSessionIndex(ssl);

if(sesIdx < 0 || sesIdx > sizeof(ssl->sessionIndex)/sizeof(int)){

/* You have an out of bounds index number and something is not

right. */

}

See Also:

wolfSSL_GetSessionAtIndex

wolfSSL_save_session_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_save_session_cache(const char* fname);

Description:

This function persists the session cache to file. It doesn’t use memsave because of

additional memory use.

Return Values:

SSL_SUCCESS - returned if the function executed without error. The session cache

has been written to a file.

SSL_BAD_FILE - returned if fname cannot be opened or is otherwise corrupt.

FWRITE_ERROR - returned if XFWRITE failed to write to the file.

BAD_MUTEX_E - returned if there was a mutex lock failure.

Parameters:

fname - is a constant char pointer that points to a file for writing.

Example:

460

const char* fname;

...

if(wolfSSL_save_session_cache(fname) != SSL_SUCCESS){

/*Fail to write to file. */

}

See Also:

XFWRITE

wolfSSL_restore_session_cache

wolfSSL_memrestore_session_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_memrestore_session_cache(const void* mem, int sz);

Description:

This function restores the persistent session cache from memory.

Return Values:

SSL_SUCCESS - returned if the function executed without an error.

BUFFER_E - returned if the memory buffer is too small.

BAD_MUTEX_E - returned if the session cache mutex lock failed.

CACHE_MATCH_ERROR - returned if the session cache header match failed.

Parameters:

mem - a constant void pointer containing the source of the restoration.

sz - an integer representing the size of the memory buffer.

Example:

const void* memoryFile;

461

int szMf;

...

if(wolfSSL_memrestore_session_cache(memoryFile, szMf) != SSL_SUCCESS){

/*Failure case. SSL_SUCCESS was not returned. */

}

See Also:

wolfSSL_save_session_cache

wolfSSL_PrintSessionStats

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_PrintSessionStats(void);

Description:

This function prints the statistics from the session.

Return Values:

SSL_SUCCESS - returned if the function and subroutines return without error. The

session stats have been successfully retrieved and printed.

BAD_FUNC_ARG - returned if the subroutine wolfSSL_get_session_stats() was

passed an unacceptable argument.

BAD_MUTEX_E - returned if there was a mutex error in the subroutine.

Parameters:

This function takes no parameters.

Example:

/*You will need to have a session object to retrieve stats from. */

if(wolfSSL_PrintSessionStats(void) != SSL_SUCCESS ){

/*Did not print session stats*/

}

See Also:

wolfSSL_get_session_stats

462

wolfSSL_restore_session_cache

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_restore_session_cache(WOLFSSL* ssl);

Description:

This function restores the persistent session cache from file. It does not use memstore

because of additional memory use.

Return Values:

SSL_SUCCESS - returned if the function executed without error.

SSL_BAD_FILE - returned if the file passed into the function was corrupted and could

not be opened by XFOPEN.

FREAD_ERROR - returned if the file had a read error from XFREAD.

CACHE_MATCH_ERROR - returned if the session cache header match failed.

BAD_MUTEX_E - returned if there was a mutex lock failure.

Parameters:

fname - a constant char pointer file input that will be read.

Example:

const char *fname;

...

if(wolfSSL_restore_session_cache(fname) != SSL_SUCCESS){

/*Failure case. The function did not return SSL_SUCCESS. */

}

See Also:

XFREAD

XFOPEN

463

wolfSSL_get_session_stats

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_session_stats(word32* active, word32 *total, word32* peak,

word32* maxSessions);

Description:

This function gets the statistics for the session.

Return Values:

SSL_SUCCESS - returned if the function and subroutines return without error. The

session stats have been successfully retrieved and printed.

BAD_FUNC_ARG - returned if the subroutine wolfSSL_get_session_stats() was

passed an unacceptable argument.

BAD_MUTEX_E - returned if there was a mutex error in the subroutine.

Parameters:

active - a word32 pointer representing the total current sessions.

total - a word32 pointer representing the total sessions.

peak - a word32 pointer representing the peak sessions.

maxSessions - a word32 pointer representing the maximum sessions.

Example:

int wolfSSL_PrintSessionStats(void){

…

ret = wolfSSL_get_session_stats(&totalSessionsNow, &totalSessionsSeen, &peak,

&maxSessions);

…

return ret;

See Also:

get_locked_session_stats

464

wolfSSL_PrintSessionStats

wolfSSL_session_reused

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_session_reused(WOLFSSL* ssl);

Description:

This function returns the resuming member of the options struct. The flag indicates

whether or not to reuse a session. If not, a new session must be established.

Return Values:

This function returns an int type held in the Options structure representing the flag for

session reuse.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

…

if(!wolfSSL_session_reused(sslResume)){

/*No session reuse allowed. */

}

See Also:

wolfSSL_SESSION_free

wolfSSL_GetSessionIndex

wolfSSL_memsave_session_cache

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_memsave_session_cache(void* mem, int sz);

465

Description:

This function persists session cache to memory.

Return Values:

SSL_SUCCESS - returned if the function executed without error. The session cache

has been successfully persisted to memory.

BAD_MUTEX_E - returned if there was a mutex lock error.

BUFFER_E - returned if the buffer size was too small.

Parameters:

mem - a void pointer representing the destination for the memory copy, XMEMCPY().

sz - an int type representing the size of mem.

Example:

void* mem;

int sz; /*Max size of the memory buffer. */

…

if(wolfSSL_memsave_session_cache(mem, sz) != SSL_SUCCESS){

/*Failure case, you did not persist the session cache to memory */

}

See Also:

XMEMCPY

wolfSSL_get_session_cache_memsize

wolfSSL_SetIO_NetX

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxSocket,

ULONG waitOption);

Description:

466

This function sets the nxSocket and nxWait members of the nxCtx struct within the

WOLFSSL structure.

Return Values:

This function has no return value.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

nxSocket - a pointer to type NX_TCP_SOCKET that is set to the nxSocket member of

the nxCTX structure.

waitOption - a ULONG type that is set to the nxWait member of the nxCtx structure.

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

NX_TCP_SOCKET* nxSocket; /*Initialize */

ULONG waitOption; /*Initialize */

…

if(ssl != NULL || nxSocket != NULL || waitOption <= 0){

wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption);

} else {

/*You need to pass in good parameters. */

}

See Also:

set_fd

NetX_Send

NetX_Receive

wolfSSL_GetIOReadCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetIOReadCtx(WOLFSSL* ssl);

Description:

This function returns the IOCB_ReadCtx member of the WOLFSSL struct.

467

Return Values:

This function returns a void pointer to the IOCB_ReadCtx member of the WOLFSSL

structure.

NULL - returned if the WOLFSSL struct is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

void* ioRead;

...

ioRead = wolfSSL_GetIOReadCtx(ssl);

if(ioRead == NULL){

/*Failure case. The ssl object was NULL. */

}

See Also:

wolfSSL_GetIOWriteCtx

wolfSSL_SetIOReadFlags

wolfSSL_SetIOWriteCtx

wolfSSL_SetIOReadCtx

wolfSSL_SetIOSend

wolfSSL_GetIOWriteCtx

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl);

Description:

This function returns the IOCB_WriteCtx member of the WOLFSSL structure.

Return Values:

This function returns a void pointer to the IOCB_WriteCtx member of the WOLFSSL

structure.

NULL - returned if the WOLFSSL struct is NULL.

468

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl;

void* ioWrite;

...

ioWrite = wolfSSL_GetIOWriteCtx(ssl);

if(ioWrite == NULL){

/*The funciton returned NULL. */

}

See Also:

wolfSSL_GetIOReadCtx

wolfSSL_SetIOWriteCtx

wolfSSL_SetIOReadCtx

wolfSSL_SetIOSend

wolfSSL_Rehandshake

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_Rehandshake(WOLFSSL* ssl);

Description:

This function executes a secure renegotiation handshake; this is user forced as wolfSSL

discourages this functionality.

Return Values:

SSL_SUCCESS - returned if the function executed without error.

BAD_FUNC_ARG - returned if the WOLFSSL structure was NULL or otherwise if an

unacceptable argument was passed in a subroutine.

SECURE_RENEGOTIATION_E - returned if there was an error with renegotiating the

handshake.

469

SSL_FATAL_ERROR - returned if there was an error with the server or client

configuration and the renegotiation could not be completed. See wolfSSL_negotiate().

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL* ssl = wolfSSL_new(ctx);

...

if(wolfSSL_Rehandshake(ssl) != SSL_SUCCESS){

/*There was an error and the rehandshake is not successful. */

}

See Also:

wolfSSL_negotiate

wc_InitSha512

wc_InitSha384

wc_InitSha256

wc_InitSha

wc_InitMd5

wolfSSL_UseSecureRenegotiation

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl)

Description:

This function forces secure renegotiation for the supplied WOLFSSL structure. This is

not recommended.

Return Values:

SSL_SUCCESS: Successfully set secure renegotiation.

BAD_FUNC_ARG: Returns error if ssl is null.

470

MEMORY_E: Returns error if unable to allocate memory for secure renegotiation.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

if(wolfSSL_UseSecureRenegotiation(ssl) != SSL_SUCCESS)

{

/* Error setting secure renegotiation */

}

See Also:

TLSX_Find

TLSX_UseSecureRenegotiation

wolfSSL_UseSessionTicket

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseSessionTicket(WOLFSSL* ssl)

Description:

Force provided WOLFSSL structure to use session ticket. The constant

HAVE_SESSION_TICKET should be defined and the constant NO_WOLFSSL_CLIENT

should not be defined to use this function.

471

Return Values:

SSL_SUCCESS: Successfully set use session ticket.

BAD_FUNC_ARG: Returned if ssl is null.

MEMORY_E: Error allocating memory for setting session ticket.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

if(wolfSSL_UseSessionTicket(ssl) != SSL_SUCCESS)

{

/* Error setting session ticket */

}

See Also:

TLSX_UseSessionTicket

wolfSSL_get_current_cipher_suite

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_current_cipher_suite(WOLFSSL* ssl)

Description:

472

Returns the current cipher suit an ssl session is using.

Return Values:

ssl->options.cipherSuite: An integer representing the current cipher suite.

0: The ssl session provided is null.

Parameters:

ssl - The SSL session to check.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

if(wolfSSL_get_current_cipher_suite(ssl) == 0)

{

/* Error getting cipher suite */

}

See Also:

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_get_cipher_list

Synopsis:

#include <wolfssl/ssl.h>

char* wolfSSL_get_cipher_list(int priority)

473

Description:

Get the name of cipher at priority level passed in.

Return Values:

string: Success

0: Priority is either out of bounds or not valid.

Parameters:

priority - Integer representing the priority level of a cipher.

Example:

printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1));

See Also:

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_isQSH

Synopsis:

#include <wolfssl/ssl.h>

wolfSSL_isQSH(WOLFSSL* ssl)

Description:

Checks if QSH is used in the supplied SSL session.

Return Values:

0: Not used

1: Is used

474

Parameters:

ssl - Pointer to the SSL session to check.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

if(wolfSSL_isQSH(ssl) == 1)

{

/* SSL is using QSH. */

}

See Also:

wolfSSL_UseSupportedQSH

wolfSSL_get_version

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_get_version(WOLFSSL* ssl)

Description:

Returns the SSL version being used as a string.

Return Values:

"SSLv3": Using SSLv3

475

"TLSv1": Using TLSv1

"TLSv1.1": Using TLSv1.1

"TLSv1.2": Using TLSv1.2

"TLSv1.3": Using TLSv1.3

"DTLS": Using DTLS

"DTLSv1.2": Using DTLSv1.2

"unknown": There was a problem determining which version of TLS being used.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

printf(wolfSSL_get_version("Using version: %s", ssl));

See Also:

wolfSSL_lib_version

wolfSSL_get_ciphers

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_ciphers(char* buf, int len);

Description:

This function gets the ciphers enabled in wolfSSL.

476

Return Values:

SSL_SUCCESS - returned if the function executed without error.

BAD_FUNC_ARG - returned if the buf parameter was NULL or if the len argument was

less than or equal to zero.

BUFFER_E - returned if the buffer is not large enough and will overflow.

Parameters:

buf - a char pointer representing the buffer.

len - the length of the buffer.

Example:

static void ShowCiphers(void){

char* ciphers; /*initialize*/

int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers));

if(ret == SSL_SUCCES){

printf(“%s\n”, ciphers);

}

See Also:

GetCipherNames

wolfSSL_get_cipher_list

ShowCiphers

wolfSSL_get_verify_depth

Synopsis:

#include <wolfssl/ssl.h>

long wolfSSL_get_verify_depth(WOLFSSL* ssl);

Description:

This function returns the maximum chain depth allowed, which is 9 by default, for a valid

session i.e. there is a non-null session object (ssl).

477

Return Values:

MAX_CHAIN_DEPTH - returned if the WOLFSSL_CTX structure is not NULL. By

default the value is 9.

BAD_FUNC_ARG - returned if the WOLFSSL_CTX structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

...

long sslDep = wolfSSL_get_verify_depth(ssl);

if(sslDep > EXPECTED){

/*The verified depth is greater than what was expected*/

} else {

/*The verified depth is smaller or equal to the expected value */

}

See Also:

wolfSSL_CTX_get_verify_depth

wolfSSL_get_cipher

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_get_cipher(WOLFSSL* ssl);

Description:

This function matches the cipher suite in the SSL object with the available suites.

Return Values:

This function returns the string value of the suite matched. It will return “None” if there

are no suites matched.

478

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

#ifdef WOLFSSL_DTLS

…

/*make sure a valid suite is used */

if(wolfSSL_get_cipher(ssl) == NULL){

WOLFSSL_MSG(“Can not match cipher suite imported”);

return MATCH_SUITE_ERROR;

}

…

#endif /*WOLFSSL_DTLS */

See Also:

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_CIPHER_get_name

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher);

Description:

This function matches the cipher suite in the SSL object with the available suites and

returns the string representation.

Return Values:

This function returns the string representation of the matched cipher suite. It will return

“None” if there are no suites matched.

Parameters:

cipher - a constant pointer to a WOLFSSL_CIPHER structure.

Example:

479

WOLFSSL* ssl;

/*gets cipher name in the format DHE_RSA ...*/

const char* wolfSSL_get_cipher_name_internal(WOLFSSL* ssl){

WOLFSSL_CIPHER* cipher;

const char* fullName;

…

cipher = wolfSSL_get_curent_cipher(ssl);

fullName = wolfSSL_CIPHER_get_name(cipher);

if(fullName){

/*sanity check on returned cipher*/

}

See Also:

wolfSSL_get_cipher

wolfSSL_get_current_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_cipher_name

Synopsis:

#include <wolfssl/ssl.h>

const char* wolfSSL_get_cipher_name(WOLFSSL* ssl);

Description:

This function gets the cipher name in the format DHE-RSA by passing through

argument to wolfSSL_get_cipher_name_internal.

Return Values:

This function returns the string representation of the cipher suite that was matched.

NULL - error or cipher not found.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

480

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

char* cipherS = wolfSSL_get_cipher_name(ssl);

if(cipher == NULL){

/*There was not a cipher suite matched */

} else {

/*There was a cipher suite matched*/

printf(“%s\n”, cipherS);

}

See Also:

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_current_cipher

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_CIPHER* wolfSSL_get_current_cipher(WOLFSSL* ssl);

Description:

This function returns a pointer to the current cipher in the ssl session.

Return Values:

The function returns the address of the cipher member of the WOLFSSL struct. This is

a pointer to the WOLFSSL_CIPHER structure.

NULL - returned if the WOLFSSL structure is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

481

…

WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher;

if(!cipherCurr){

/*Failure case. */

} else {

/*The cipher was returned to cipherCurr */

}

See Also:

wolfSSL_get_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_cipher_name

wolfSSL_get_SessionTicket

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_SessionTicket(WOLFSSL* ssl, byte* buf, word32* bufSz);

Description:

This function copies the ticket member of the Session structure to the buffer.

Return Values:

SSL_SUCCESS - returned if the function executed without error.

BAD_FUNC_ARG - returned if one of the arguments was NULL or if the bufSz

argument was 0.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - a byte pointer representing the memory buffer.

bufSz - a word32 pointer representing the buffer size.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

482

WOLFSSL* ssl = wolfSSL_new(ctx);

byte* buf;

word32 bufSz; /*Initialize with buf size*/

…

if(wolfSSL_get_SessionTicket(ssl, buf, bufSz) <= 0){

/*Nothing was written to the buffer*/

} else {

/*the buffer holds the content from ssl->session.ticket */

}

See Also:

wolfSSL_UseSessionTicket

wolfSSL_set_SessionTicket

wolfSSL_lib_version_hex

Synopsis:

#include <wolfssl/ssl.h>

word32 wolfSSL_lib_version_hex(void);

Description:

This function returns the current library version in hexadecimal notation.

Return Values:

LILBWOLFSSL_VERSION_HEX - returns the hexidecimal version defined in

wolfssl/version.h.

Parameters:

This function does not take any parameters.

Example:

word32 libV;

libV = wolfSSL_lib_version_hex();

if(libV != EXPECTED_HEX){

/*How to handle an unexpected value*/

} else {

/*The expected result for libV */

}

483

See Also:

wolfSSL_lib_version

wolfSSL_SNI_Status

Synopsis:

#include <wolfssl/ssl.h>

byte wolfSSL_SNI_Status(WOLFSSL* ssl, byte type);

Description:

This function gets the status of an SNI object.

Return Values:

This function returns the byte value of the SNI struct’s status member if the SNI is not

NULL.

0 - if the SNI object is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

type - the SNI type.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

…

#define AssertIntEQ(x, y) AssertInt(x, y, ==, !=)

…

Byte type = WOLFSSL_SNI_HOST_NAME;

char* request = (char*)&type;

AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type));

…

See Also:

TLSX_SNI_Status

TLSX_SNI_find

484

TLSX_Find

wolfSSL_get_alert_history

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_get_alert_history(WOLFSSL* ssl, WOLFSSL_ALERT_HISTORY *h);

Description:

This function gets the alert history.

Return Values:

SSL_SUCCESS - returned when the function completed successfully. Either there was

alert history or there wasn’t, either way, the return value is SSL_SUCCESS.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

h - a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the WOLFSSL

struct’s alert_history member’s value.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

WOLFSSL_ALERT_HISTORY* h;

...

wolfSSL_get_alert_history(ssl, h);

/* h now has a copy of the ssl->alert_history contents */

See Also:

wolfSSL_get_error

wolfSSL_lib_version

Synopsis:

#include <wolfssl/ssl.h>

485

const char* wolfSSL_KeepArrays(void);

Description:

This function returns the current library version.

Return Values:

LIBWOLFSSL_VERSION_STRING - a const char pointer defining the version.

Parameters:

This function takes no parameters.

Example:

char version[MAXSIZE];

version = wolfSSL_KeepArrays();

…

if(version != ExpectedVersion){

/*Handle the mismatch case*/

}

See Also:

word32_wolfSSL_lib_version_hex

wolfSSL_CTX_UseCavium

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_UseCavium(WOLFSSL_CTX* ctx, int devId)

Description:

Forces provided WOLFSSL_CTX to use cavium.

Return Values:

SSL_SUCCESS: Successfully set cavium.

486

BAD_FUNC_ARG: Returns if ctx is null.

Parameters:

ctx - Pointer to WOLFSSL_CTX to use.

devId - The value to set the ctx->devId to.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

if(wolfSSL_CTX_UseCavium(ctx, CAVIUM_DEV_ID) != SSL_SUCCESS)

{

/* Error setting session ticket */

}

See Also:

wolfSSL_UseCavium

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_UseCavium(WOLFSSL* ssl, int devId)

Description:

Forces provided WOLFSSL structure to use cavium.

Return Values:

SSL_SUCCESS: Success

487

BAD_FUNC_ARG: Returned if ssl is null.

Parameters:

ssl - Pointer to the WOLFSSL session. Created with wolfSSL_new()

devId - Value to set ssl->devId to.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

WOLFSSL_METHOD method = /* Some wolfSSL method */

ctx = wolfSSL_CTX_new(method);

ssl = wolfSSL_new(ctx);

if(wolfSSL_UseCavium(ssl, CAVIUM_DEV_ID) != SSL_SUCCESS)

{

/* Error setting session ticket */

}

See Also:

wolfSSL_CTX_UseCavium

wolfSSL_set_jobject

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr);

Description:

This function sets the jObjectRef member of the WOLFSSL structure.

Return Values:

SSL_SUCCESS - returned if jObjectRef is properly set to objPtr.

488

SSL_FAILURE - returned if the function did not properly execute and jObjectRef is not

set.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

objPtr - a void pointer that will be set to jObjectRef.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = WOLFSSL_new();

void* objPtr = &obj;

...

if(wolfSSL_set_jobject(ssl, objPtr)){

/*The success case*/

}

See Also:

wolfSSL_get_jobject

Synopsis:

#include <wolfssl/ssl.h>

void* wolfSSL_get_jobject(WOLFSSL* ssl);

Description:

This function returns the jObjectRef member of the WOLFSSL structure.

Return Values:

If the WOLFSSL struct is not NULL, the function returns the jObjectRef value.

NULL - returned if the WOLFSSL struct is NULL.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

489

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*protocol method*/);

WOLFSSL* ssl = wolfSSL(ctx);

...

void* jobject = wolfSSL_get_jobject(ssl);

if(jobject != NULL){

/*Success case*/

}

See Also:

wolfSSL_set_jobject

wolfSSL_BIO_ctrl_pending

Synopsis:

#include <wolfssl/ssl.h>

size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO* bio);

Description:

Gets the number of pending bytes to read. If BIO type is BIO_BIO then is the number to

read from pair. If BIO contains an SSL object then is pending data from SSL object

(wolfSSL_pending(ssl)). If is BIO_MEMORY type then returns the size of memory

buffer.

Return Values:

0 or greater: number of pending bytes.

Parameters:

bio - pointer to the WOLFSSL_BIO structure that has already been created

Example:

WOLFSSL_BIO* bio;

int pending;

490

bio = wolfSSL_BIO_new();

….

pending = wolfSSL_BIO_ctrl_pending(bio);

See Also:

wolfSSL_BIO_make_bio_pair, wolfSSL_BIO_new

wolfSSL_BIO_get_mem_ptr

Synopsis:

#include <wolfssl/ssl.h>

BIO_get_mem_ptr ->

long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO* bio, WOLFSSL_BUF_MEM** ptr);

Description:

This is a getter function for WOLFSSL_BIO memory pointer.

Return Values:

SSL_SUCCESS: On successfully getting the pointer SSL_SUCCESS is returned

(currently value of 1).

SSL_FAILURE: Returned if NULL arguments are passed in (currently value of 0).

Parameters:

bio - pointer to the WOLFSSL_BIO structure for getting memory pointer.

ptr - structure that is currently a char*. Is set to point to bio’s memory.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_BUF_MEM* pt;

// setup bio

wolfSSL_BIO_get_mem_ptr(bio, &pt);

//use pt

491

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_reset

Synopsis:

#include <wolfssl/ssl.h>

BIO_reset ->

int wolfSSL_BIO_reset(WOLFSSL_BIO* bio);

Description:

Resets bio to an initial state. As an example for type BIO_BIO this resets the read and

write index.

Return Values:

0: On successfully resetting the bio.

-1 (WOLFSSL_BIO_ERROR): Returned on bad input or unsuccessful reset.

Parameters:

bio - WOLFSSL_BIO structure to reset.

Example:

WOLFSSL_BIO* bio;

// setup bio

wolfSSL_BIO_reset(bio);

//use pt

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_ERR_load_BIO_strings

Synopsis:

492

#include <wolfssl/ssl.h>

ERR_load_BIO_strings ->

void wolfSSL_ERR_load_BIO_strings(void)

Description:

Do nothing. wolfSSL error string is statically defined.

Return Values:

None

Parameters:

none

Example:

wolfSSL_ERR_load_BIO_strings();

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_s_socket

Synopsis:

#include <wolfssl/ssl.h>

BIO_s_socket ->

WOLFSSL_BIO_METHOD* wolfSSL_BIO_s_socket(void);

Description:

This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.

Return Values:

493

WOLFSSL_BIO_METHOD*: pointer to a WOLFSSL_BIO_METHOD structure that is a

socket type

Parameters:

None

Example:

WOLFSSL_BIO* bio;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_set_fd

Synopsis:

#include <wolfssl/ssl.h>

BIO_set_fd ->

long wolfSSL_BIO_set_fd(WOLFSSL_BIO* bio, int fd, int closeF);

Description:

Sets the file descriptor for bio to use.

Return Values:

Returns SSL_SUCCESS (1).

Parameters:

bio - WOLFSSL_BIO structure to set fd.

fd - file descriptor to use.

closeF - flag for behavior when closing fd.

494

Example:

WOLFSSL_BIO* bio;

int fd;

// setup bio

wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE);

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_set_write_buf_size

Synopsis:

#include <wolfssl/ssl.h>

BIO_set_write_buf_size ->

int wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO* bio, long size;

Description:

This is used to set the size of write buffer for a WOLFSSL_BIO. If write buffer has been

previously set this function will free it when resetting the size. It is similar to

wolfSSL_BIO_reset in that it resets read and write indexes to 0.

Return Values:

SSL_SUCCESS: On successfully setting the write buffer.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set fd.

size - size of buffer to allocate.

Example:

WOLFSSL_BIO* bio;

int ret;

495

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());

ret = wolfSSL_BIO_set_write_buf_size(bio, 15000);

// check return value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_make_bio_pair

Synopsis:

#include <wolfssl/ssl.h>

BIO_make_bio_pair ->

int wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO* b1, WOLFSSL_BIO* b2);

Description:

This is used to pair two bios together. A pair of bios acts similar to a two way pipe

writing to one can be read by the other and vice versa. It is expected that both bios be in

the same thread, this function is not thread safe. Freeing one of the two bios removes

both from being paired. If a write buffer size was not previously set for either of the bios

it is set to a default size of 17000 (WOLFSSL_BIO_SIZE) before being paired.

Return Values:

SSL_SUCCESS: On successfully pairing the two bios.

SSL_FAILURE: If an error case was encountered.

Parameters:

b1 - WOLFSSL_BIO structure to set pair.

b2 - second WOLFSSL_BIO structure to complete pair.

Example:

496

WOLFSSL_BIO* bio;

WOLFSSL_BIO* bio2;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());

bio2 = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());

ret = wolfSSL_BIO_make_bio_pair(bio, bio2);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_ctrl_reset_read_request

Synopsis:

#include <wolfssl/ssl.h>

BIO_ctrl_reset_read_request ->

int wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO* bio);

Description:

This is used to set the read request flag back to 0.

Return Values:

SSL_SUCCESS: On successfully setting value.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set read request flag.

Example:

WOLFSSL_BIO* bio;

int ret;

...

497

ret = wolfSSL_BIO_ctrl_reset_read_request(bio);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_nread

Synopsis:

#include <wolfssl/ssl.h>

BIO_nread ->

int wolfSSL_BIO_nread(WOLFSSL_BIO* bio, char** buf, int num);

Description:

This is used to get a buffer pointer for reading from. The internal read index is advanced

by the number returned from the function call with buf being pointed to the beginning of

the buffer to read from. In the case that less bytes are in the read buffer than the value

requested with num the lesser value is returned. Reading past the value returned can

result in reading out of array bounds.

Return Values:

0 or greater: on success return the number of bytes to read

-1: on error case with nothing to read return -1 (WOLFSSL_BIO_ERROR)

Parameters:

bio - WOLFSSL_BIO structure to read from.

buf - pointer to set at beginning of read array.

num -number of bytes to try and read.

Example:

WOLFSSL_BIO* bio;

498

char* bufPt;

int ret;

// set up bio

ret = wolfSSL_BIO_nread(bio, &bufPt, 10); // try to read 10 bytes

// handle negative ret check

// read ret bytes from bufPt

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_nwrite

wolfSSL_BIO_nread0

Synopsis:

#include <wolfssl/ssl.h>

BIO_nread ->

int wolfSSL_BIO_nread0(WOLFSSL_BIO* bio, char** buf);

Description:

This is used to get a buffer pointer for reading from. Unlike wolfSSL_BIO_nread the

internal read index is not advanced by the number returned from the function call.

Reading past the value returned can result in reading out of array bounds.

Return Values:

Greater than 0: on success return the number of bytes to read

Parameters:

bio - WOLFSSL_BIO structure to read from.

buf - pointer to set at beginning of read array.

Example:

WOLFSSL_BIO* bio;

char* bufPt;

499

int ret;

// set up bio

ret = wolfSSL_BIO_nread0(bio, &bufPt); // read as many bytes as possible

// handle negative ret check

// read ret bytes from bufPt

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_nwrite0

wolfSSL_BIO_nwrite

Synopsis:

#include <wolfssl/ssl.h>

BIO_nwrite ->

int wolfSSL_BIO_nwrite(WOLFSSL_BIO* bio, char** buf, int num);

Description:

Gets a pointer to the buffer for writing as many bytes as returned by the function.

Writing more bytes to the pointer returned then the value returned can result in writing

out of bounds.

Return Values:

Returns the number of bytes that can be written to the buffer pointer returned.

WOLFSSL_BIO_UNSET: -2 in the case that is not part of a bio pair

WOLFSSL_BIO_ERROR: -1 in the case that there is no more room to write to

Parameters:

bio - WOLFSSL_BIO structure to write to.

buf - pointer to buffer to write to.

num - number of bytes desired to be written.

Example:

WOLFSSL_BIO* bio;

500

char* bufPt;

int ret;

// set up bio

ret = wolfSSL_BIO_nwrite(bio, &bufPt, 10); // try to write 10 bytes

// handle negative ret check

// write ret bytes to bufPt

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_free, wolfSSL_BIO_nread

wolfSSL_BIO_puts

Synopsis:

#include <wolfssl/ssl.h>

BIO_puts ->

int wolfSSL_BIO_puts(WOLFSSL_BIO* bio, const char* data)

Description:

BIO_puts() tries to write a NUL-terminated string data to BIO bio.

Return Values:

Return the number of bytes that is successfully written.

SSL_FAILURE: o data was successfully written.

Parameters:

bio - WOLFSSL_BIO structure to write to.

data - pointer to buffer to write to.

Example:

WOLFSSL_BIO* bio;

char* data;

501

int ret;

// set up bio

ret = wolfSSL_BIO_puts (bio, &data, 10);

// handle negative ret check

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_free, wolfSSL_BIO_read

wolfSSL_BIO_set_fp

Synopsis:

#include <wolfssl/ssl.h>

BIO_set_fp ->

long wolfSSL_BIO_set_fp(WOLFSSL_BIO* bio, XFILE fp, int c);

Description:

This is used to set the internal file pointer for a BIO.

Return Values:

SSL_SUCCESS: On successfully setting file pointer.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set pair.

fp - file pointer to set in bio.

502

c - close file behavior flag.

Example:

WOLFSSL_BIO* bio;

XFILE fp;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());

ret = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_get_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_get_fp

Synopsis:

#include <wolfssl/ssl.h>

BIO_get_fp ->

long wolfSSL_BIO_get_fp(WOLFSSL_BIO* bio, XFILE fp);

Description:

This is used to get the internal file pointer for a BIO.

Return Values:

SSL_SUCCESS: On successfully getting file pointer.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set pair.

fp - file pointer to set in bio.

Example:

503

WOLFSSL_BIO* bio;

XFILE fp;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());

ret = wolfSSL_BIO_get_fp(bio, &fp);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_seek

Synopsis:

#include <wolfssl/ssl.h>

BIO_seek ->

int wolfSSL_BIO_seek(WOLFSSL_BIO* bio, int ofs);

Description:

This function adjusts the file pointer to the offset given. This is the offset from the head

of the file.

Return Values:

0: On successfully seeking.

-1: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set.

ofs - offset into file.

Example:

WOLFSSL_BIO* bio;

504

XFILE fp;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());

ret = wolfSSL_BIO_set_fp(bio, &fp);

// check ret value

ret = wolfSSL_BIO_seek(bio, 3);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_write_filename

Synopsis:

#include <wolfssl/ssl.h>

BIO_write_filename ->

int wolfSSL_BIO_write_filename(WOLFSSL_BIO* bio, char* name);

Description:

This is used to set and write to a file. WIll overwrite any data currently in the file and is

set to close the file when the bio is freed.

Return Values:

SSL_SUCCESS: On successfully opening and setting file.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to set file.

name - name of file to write to.

Example:

WOLFSSL_BIO* bio;

505

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());

ret = wolfSSL_BIO_write_filename(bio, “test.txt”);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_file, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_get_mem_data

Synopsis:

#include <wolfssl/ssl.h>

BIO_get_mem_data ->

int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio, const byte** p);

Description:

This is used to set a byte pointer to the start of the internal memory buffer.

Return Values:

On success the size of the buffer is returned

SSL_FATAL_ERROR: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to get memory buffer of.

p - byte pointer to set to memory buffer.

Example:

WOLFSSL_BIO* bio;

const byte* p;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());

ret = wolfSSL_BIO_get_mem_data(bio, &p);

506

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_get_mem_ptr

Synopsis:

#include <wolfssl/ssl.h>

BIO_get_mem_ptr ->

long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO* bio, WOLFSSL_BUF_MEM** ptr);

Description:

This is used to get the internal memory pointer from a BIO.

Return Values:

SSL_SUCCESS: On successfully getting memory pointer.

SSL_FAILURE: If an error case was encountered.

Parameters:

bio - WOLFSSL_BIO structure to get memory pointer from.

ptr - pointer to WOLFSSL_BUF_MEM structure.

Example:

WOLFSSL_BIO* bio;

WOLFSSL_BUF_MEM* p;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());

ret = wolfSSL_BIO_get_mem_ptr(bio, &p);

// check ret value

See Also:

507

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

wolfSSL_BIO_set_mem_eof_return

Synopsis:

#include <wolfssl/ssl.h>

BIO_set_mem_eof_return ->

long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO* bio, int v);

Description:

This is used to set the end of file value. Common value is -1 so as not to get confused

with expected positive values.

Return Values:

Returns 0

Parameters:

bio - WOLFSSL_BIO structure to set end of file value.

v - value to set in bio.

Example:

WOLFSSL_BIO* bio;

int ret;

bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());

ret = wolfSSL_BIO_set_mem_eof_return(bio, -1);

// check ret value

See Also:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem, wolfSSL_BIO_set_fp

wolfSSL_BIO_new, wolfSSL_BIO_free

508

17.9 DTLS Specific

The functions in this section are specific to using DTLS with wolfSSL.

wolfSSL_dtls

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls(WOLFSSL* ssl);

Description:

This function is used to determine if the SSL session has been configured to use DTLS.

Return Values:

If the SSL session (ssl) has been configured to use DTLS, this function will return 1,

otherwise 0.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

int ret = 0;

WOLFSSL* ssl;

...

ret = wolfSSL_dtls(ssl);

if (ret) {

// SSL session has been configured to use DTLS

}

See Also:

wolfSSL_dtls_get_current_timeout

wolfSSL_dtls_get_peer

wolfSSL_dtls_got_timeout

wolfSSL_dtls_set_peer

wolfSSL_dtls_get_current_timeout

509

Synopsis:

#include <wolfssl/ssl.h>

wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl);

Description:

This function returns the current timeout value in seconds for the WOLFSSL object.

When using non-blocking sockets, something in the user code needs to decide when to

check for available recv data and how long it has been waiting. The value returned by

this function indicates how long the application should wait.

Return Values:

The current DTLS timeout value in seconds, or NOT_COMPILED_IN if wolfSSL was not

built with DTLS support.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

int timeout = 0;

WOLFSSL* ssl;

...

timeout = wolfSSL_get_dtls_current_timeout(ssl);

printf(“DTLS timeout (sec) = %d\n”, timeout);

See Also:

wolfSSL_dtls

wolfSSL_dtls_get_peer

wolfSSL_dtls_got_timeout

wolfSSL_dtls_set_peer

wolfSSL_dtls_get_peer

Synopsis:

#include <wolfssl/ssl.h>

510

int wolfSSL_dtls_get_peer(WOLFSSL* ssl, void* peer, unsigned int* peerSz);

Description:

This function gets the sockaddr_in (of size peerSz) of the current DTLS peer. The

function will compare peerSz to the actual DTLS peer size stored in the SSL session. If

the peer will fit into peer, the peer’s sockaddr_in will be copied into peer, with peerSz

set to the size of peer.

Return Values:

SSL_SUCCESS will be returned upon success.

SSL_FAILURE will be returned upon failure.

SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS

support.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

peer - pointer to memory location to store peer’s sockaddr_in structure.

peerSz - input/output size. As input, the size of the allocated memory pointed to by

peer. As output, the size of the actual sockaddr_in structure pointed to by peer.

Example:

int ret = 0;

WOLFSSL* ssl;

sockaddr_in addr;

...

ret = wolfSSL_dtls_get_peer(ssl, &addr, sizeof(addr));

if (ret != SSL_SUCCESS) {

// failed to get DTLS peer

}

See Also:

wolfSSL_dtls_get_current_timeout

wolfSSL_dtls_got_timeout

wolfSSL_dtls_set_peer

511

wolfSSL_dtls

wolfSSL_dtls_got_timeout

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls_got_timeout(WOLFSSL* ssl);

Description:

When using non-blocking sockets with DTLS, this function should be called on the

WOLFSSL object when the controlling code thinks the transmission has timed out. It

performs the actions needed to retry the last transmit, including adjusting the timeout

value. If it has been too long, this will return a failure.

Return Values:

SSL_SUCCESS will be returned upon success

SSL_FATAL_ERROR will be returned if there have been too many

retransmissions/timeouts without getting a response from the peer.

NOT_COMPILED_IN will be returned if wolfSSL was not compiled with DTLS support.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

Example:

See the following files for usage examples:

<wolfssl_root>/examples/client/client.c

<wolfssl_root>/examples/server/server.c

See Also:

wolfSSL_dtls_get_current_timeout

wolfSSL_dtls_get_peer

wolfSSL_dtls_set_peer

wolfSSL_dtls

512

wolfSSL_dtls_set_peer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls_set_peer(WOLFSSL* ssl, void* peer, unsigned int peerSz);

Description:

This function sets the DTLS peer, peer (sockaddr_in) with size of peerSz.

Return Values:

SSL_SUCCESS will be returned upon success.

SSL_FAILURE will be returned upon failure.

SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS

support.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

peer - pointer to peer’s sockaddr_in structure.

peerSz - size of the sockaddr_in structure pointed to by peer.

Example:

int ret = 0;

WOLFSSL* ssl;

sockaddr_in addr;

...

ret = wolfSSL_dtls_set_peer(ssl, &addr, sizeof(addr));

if (ret != SSL_SUCCESS) {

// failed to set DTLS peer

}

See Also:

513

wolfSSL_dtls_get_current_timeout

wolfSSL_dtls_get_peer

wolfSSL_dtls_got_timeout

wolfSSL_dtls

wolfSSL_dtls_set_timeout_max

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int timeout);

Description:

This function sets the maximum dtls timeout.

Return Values:

SSL_SUCCESS - returned if the function executed without an error.

BAD_FUNC_ARG - returned if the WOLFSSL struct is NULL or if the timeout argument

is not greater than zero or is less than the dtls_timeout_init member of the WOLFSSL

structure.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

timeout - an int type representing the dtls maximum timeout.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

int timeout = TIMEOUTVAL;

...

int ret = wolfSSL_dtls_set_timeout_max(ssl);

if(!ret){

/*Failed to set the max timeout*/

}

See Also:

514

wolfSSL_dtls_set_timeout_init

wolfSSL_dtls_got_timeout

wolfSSL_DTLS_SetCookieSecret

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_DTLS_SetCookieSecret(WOLFSSL* ssl, const byte* secret,

word32 secretSz);

Description:

This function sets a new dtls cookie secret.

Return Values:

0 - returned if the function executed without an error.

BAD_FUNC_ARG - returned if there was an argument passed to the function with an

unacceptable value.

COOKIE_SECRET_SZ - returned if the secret size is 0.

MEMORY_ERROR - returned if there was a problem allocating memory for a new

cookie secret.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

secret - a constant byte pointer representing the secret buffer.

secretSz - the size of the buffer.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(/*method*/);

WOLFSSL* ssl = wolfSSL_new(ctx);

const* byte secret;

word32 secretSz; /*size of secret*/

…

515

if(!wolfSSL_DTLS_SetCookieSecret(ssl, secret, secretSz)){

/*Code block for failure to set DTLS cookie secret*/

} else {

/*Success! Cookie secret is set. */

}

See Also:

ForceZero

wc_RNG_GenerateBlock

XMEMCPY

wolfDTLSv1_2_client_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* wolfDTLSv1_2_client_method(void);

Description:

This function initializes the DTLS v1.2 client method.

Return Values:

This function returns a pointer to a new WOLFSSL_METHOD structure.

Parameters:

This function has no parameters.

Example:

wolfSSL_Init();

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_client_method());

…

WOLFSSL* ssl = wolfSSL_new(ctx);

…

See Also:

516

wolfSSL_Init

wolfSSL_CTX_new

wolfSSL_dtls_export

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf, unsigned int* sz);

Description:

The wolfSSL_dtls_export() function is used to serialize a WOLFSSL session into the

provided buffer. Allows for less memory overhead than using a function callback for

sending a session and choice over when the session is serialized. If buffer is NULL

when passed to function then sz will be set to the size of buffer needed for serializing

the WOLFSSL session.

Return Values:

If successful, the amount of the buffer used will be returned.

All unsuccessful return values will be less than 0.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - buffer to hold serialized session.

sz - size of buffer.

Example:

WOLFSSL* ssl;

int ret;

unsigned char buf[MAX];

517

bufSz = MAX;

...

ret = wolfSSL_dtls_export(ssl, buf, bufSz);

if (ret < 0) {

// handle error case

}

...

See Also:

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_CTX_dtls_set_export

wolfSSL_dtls_import

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_dtls_import(WOLFSSL* ssl, unsigned char* buf, unsigned int sz);

Description:

The wolfSSL_dtls_import() function is used to parse in a serialized session state. This

allows for picking up the connection after the handshake has been completed.

Return Values:

If successful, the amount of the buffer read will be returned.

All unsuccessful return values will be less than 0.

If a version mismatch is found ie DTLS v1 and ctx was set up for DTLS v1.2 then

VERSSION_ERROR is returned.

Parameters:

518

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

buf - serialized session to import.

sz - size of serialized session buffer.

Example:

WOLFSSL* ssl;

int ret;

unsigned char buf[MAX];

bufSz = MAX;

...

//get information sent from wc_dtls_export function and place it in buf

fread(buf, 1, bufSz, input);

ret = wolfSSL_dtls_import(ssl, buf, bufSz);

if (ret < 0) {

// handle error case

}

// no wolfSSL_accept needed since handshake was already done

...

ret = wolfSSL_write(ssl) and wolfSSL_read(ssl);

...

See Also:

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_CTX_dtls_set_export

wolfSSL_dtls_set_export

Synopsis:

#include <wolfssl/ssl.h>

519

int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func);

Description:

The wolfSSL_dtls_set_export() function is used to set the callback function for exporting

a session. It is allowed to pass in NULL as the parameter func to clear the export

function previously stored. Used on the server side and is called immediately after

handshake is completed.

Return Values:

If successful, the call will return SSL_SUCCESS.

If null or not expected arguments are passed in BAD_FUNC_ARG is returned.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

func - wc_dtls_export function to use when exporting a session.

Example:

int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);

// body of send session (wc_dtls_export) that passses buf (serialized

session) to destination

WOLFSSL* ssl;

int ret;

...

ret = wolfSSL_dtls_set_export(ssl, send_session);

if (ret != SSL_SUCCESS) {

// handle error case

}

...

ret = wolfSSL_accept(ssl);

520

...

See Also:

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_CTX_dtls_set_export

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx, wc_dtls_export func);

Description:

The wolfSSL_CTX_dtls_set_export() function is used to set the callback function for

exporting a session. It is allowed to pass in NULL as the parameter func to clear the

export function previously stored. Used on the server side and is called immediately

after handshake is completed.

Return Values:

If successful, the call will return SSL_SUCCESS.

If null or not expected arguments are passed in BAD_FUNC_ARG is returned.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

func - wc_dtls_export function to use when exporting a session.

Example:

int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);

// body of send session (wc_dtls_export) that passses buf (serialized

521

session) to destination

WOLFSSL_CTX* ctx;

int ret;

...

ret = wolfSSL_CTX_dtls_set_export(ctx, send_session);

if (ret != SSL_SUCCESS) {

// handle error case

}

...

ret = wolfSSL_accept(ssl);

...

See Also:

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_dtls_set_export

Static buffer use

wolfSSL_CTX_load_static_memory

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx, wolfSSL_method_func

method, unsigned char* buf, unsigned int sz, int flag, int max);

Description:

This function is used to set aside static memory for a CTX. Memory set aside is then

used for the CTX’s lifetime and for any SSL objects created from the CTX. By passing in

a NULL ctx pointer and a wolfSSL_method_func function the creation of the CTX itself

will also use static memory. wolfSSL_method_func has the function signature of

WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap);.

Passing in 0 for max makes it behave as if not set and no max concurrent use

522

restrictions is in place.

The flag value passed in determines how the memory is used and behavior while

operating. Available flags are the following.

0 - default general memory

WOLFMEM_IO_POOL - used for input/output buffer when sending receiving messages.

Overrides general memory, so all memory in buffer passed in is used for IO.

WOLFMEM_IO_FIXED - same as WOLFMEM_IO_POOL but each SSL now keeps two

buffers to themselves for their lifetime.

WOLFMEM_TRACK_STATS - each SSL keeps track of memory stats while running.

Return Values:

If successful, SSL_SUCCESS will be returned.

All unsuccessful return values will be less than 0 or equal to SSL_FAILURE.

Parameters:

ctx - address of pointer to a WOLFSSL_CTX structure.

method - function to create protocol. (should be NULL if ctx is not also NULL)

buf - memory to use for all operations.

sz - size of memory buffer being passed in.

flag - type of memory.

max - max concurrent operations.

Example:

WOLFSSL_CTX* ctx;

WOLFSSL* ssl;

int ret;

unsigned char memory[MAX];

523

int memorySz = MAX;

unsigned char IO[MAX];

int IOSz = MAX;

int flag = WOLFMEM_IO_FIXED | WOLFMEM_TRACK_STATS;

...

// create ctx also using static memory, start with general memory to use

ctx = NULL:

ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex,

memory, memorySz, 0, MAX_CONCURRENT_HANDSHAKES);

if (ret != SSL_SUCCESS) {

// handle error case

}

// load in memory for use with IO

ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag,

MAX_CONCURRENT_IO);

if (ret != SSL_SUCCESS) {

// handle error case

}

...

See Also:

wolfSSL_CTX_new

wolfSSL_CTX_is_static_memory

wolfSSL_is_static_memory

wolfSSL_CTX_is_static_memory

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx, WOLFSSL_MEM_STATS*

mem_stats);

Description:

This function does not change any of the connections behavior and is used only for

524

gathering information about the static memory usage.

Return Values:

A value of 1 is returned if using static memory for the CTX is true.

0 is returned if not using static memory.

Parameters:

ctx - a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

mem_stats - structure to hold information about static memory usage.

Example:

WOLFSSL_CTX* ctx;

int ret;

WOLFSSL_MEM_STATS mem_stats;

...

//get information about static memory with CTX

ret = wolfSSL_CTX_is_static_memory(ctx, &mem_stats);

if (ret == 1) {

// handle case of is using static memory

// print out or inspect elements of mem_stats

}

if (ret == 0) {

//handle case of ctx not using static memory

}

…

See Also:

wolfSSL_CTX_new

wolfSSL_CTX_load_static_memory

wolfSSL_is_static_memory

525

wolfSSL_is_static_memory

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_is_static_memory(WOLFSSL* ssl, WOLFSSL_MEM_CONN_STATS*

mem_stats);

Description:

wolfSSL_is_static_memory is used to gather information about a SSL’s static memory

usage. The return value indicates if static memory is being used and

WOLFSSL_MEM_CONN_STATS will be filled out if and only if the flag

WOLFMEM_TRACK_STATS was passed to the parent CTX when loading in static

memory.

Return Values:

A value of 1 is returned if using static memory for the CTX is true.

0 is returned if not using static memory.

Parameters:

ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().

mem_stats - structure to contain static memory usage.

Example:

WOLFSSL* ssl;

int ret;

WOLFSSL_MEM_CONN_STATS mem_stats;

...

ret = wolfSSL_is_static_memory(ssl, mem_stats);

if (ret == 1) {

// handle case when is static memory

526

// investigate elements in mem_stats if WOLFMEM_TRACK_STATS flag

}

...

See Also:

wolfSSL_new

wolfSSL_CTX_is_static_memory

wolfDTLSv1_2_server_method

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* wolfDTLSv1_2_server_method(void);

Description:

This function creates and initializes a WOLFSSL_METHOD for the server side.

Return Values:

This function returns a WOLFSSL_METHOD pointer.

Parameters:

This function takes no parameters.

Example:

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_server_method());

WOLFSSL* ssl = WOLFSSL_new(ctx);

…

See Also:

wolfSSL_CTX_new

527

17.10 Memory Abstraction Layer

The functions in this section are used when an application sets its own memory

handling functions by using the wolfSSL memory abstraction layer.

wolfSSL_Malloc

Synopsis:

#include <wolfssl/wolfcrypt/memory.h>

void* wolfSSL_Malloc(size_t size)

Description:

This function is similar to malloc(), but calls the memory allocation function which

wolfSSL has been configured to use. By default, wolfSSL uses malloc(). This can be

changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Return Values:

If successful, this function returns a pointer to allocated memory. If there is an error,

NULL will be returned. Specific return values may be dependent on the underlying

memory allocation function being used (if not using the default malloc()).

Parameters:

size - number of bytes to allocate.

Example:

char* buffer;

buffer = (char*) wolfSSL_Malloc(20);

if (buffer == NULL) {

// failed to allocate memory

}

See Also:

wolfSSL_Free

wolfSSL_Realloc

528

wolfSSL_SetAllocators

wolfSSL_Realloc

Synopsis:

#include <wolfssl/wolfcrypt/memory.h>

void* wolfSSL_Realloc(void *ptr, size_t size)

Description:

This function is similar to realloc(), but calls the memory re-allocation function which

wolfSSL has been configured to use. By default, wolfSSL uses realloc(). This can be

changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Return Values:

If successful, this function returns a pointer to re-allocated memory. This may be the

same pointer as ptr, or a new pointer location. If there is an error, NULL will be

returned. Specific return values may be dependent on the underlying memory re-

allocation function being used (if not using the default realloc()).

Parameters:

ptr - pointer to the previously-allocated memory, to be reallocated.

size - number of bytes to allocate.

Example:

char* buffer;

buffer = (char*) wolfSSL_Realloc(30);

if (buffer == NULL) {

// failed to re-allocate memory

}

See Also:

wolfSSL_Free

wolfSSL_Malloc

wolfSSL_SetAllocators

529

wolfSSL_Free

Synopsis:

#include <wolfssl/wolfcrypt/memory.h>

void wolfSSL_Free(void* ptr)

Description:

This function is similar to free(), but calls the memory free function which wolfSSL has

been configured to use. By default, wolfSSL uses free(). This can be changed using

the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Return Values:

This function does not have a return value.

Parameters:

ptr - pointer to the memory to be freed.

Example:

char* buffer;

...

wolfSSL_Free(buffer);

See Also:

wolfSSL_Alloc

wolfSSL_Realloc

wolfSSL_SetAllocators

Synopsis:

#include <wolfssl/wolfcrypt/memory.h>

int wolfSSL_SetAllocators(wolfSSL_Malloc_cb malloc_function,

wolfSSL_Free_cb free_function,

wolfSSL_Realloc_cb realloc_function);

530

typedef void *(*wolfSSL_Malloc_cb)(size_t size);

typedef void (*wolfSSL_Free_cb)(void *ptr);

typedef void *(*wolfSSL_Realloc_cb)(void *ptr, size_t size);

Description:

This function registers the allocation functions used by wolfSSL. By default, if the

system supports it, malloc/free and realloc are used. Using this function allows the user

at runtime to install their own memory handlers.

Return Values:

If successful this function will return 0.

BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.

Parameters:

malloc_function - memory allocation function for wolfSSL to use. Function signature

must match wolfSSL_Malloc_cb prototype, above.

free_function - memory free function for wolfSSL to use. Function signature must

match wolfSSL_Free_cb prototype, above.

realloc_function - memory re-allocation function for wolfSSL to use. Function

signature must match wolfSSL_Realloc_cb prototype, above.

Example:

int ret = 0;

// Memory function prototypes

void* MyMalloc(size_t size);

void MyFree(void* ptr);

void* MyRealloc(void* ptr, size_t size);

// Register custom memory functions with wolfSSL

ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc);

if (ret != 0) {

// failed to set memory functions

}

void* MyMalloc(size_t size)

531

{

// custom malloc function

}

void MyFree(void* ptr)

{

// custom free function

}

void* MyRealloc(void* ptr, size_t size)

{

// custom realloc function

}

See Also:

17.11 Certificate Manager

The functions in this section are part of the wolfSSL Certificate Manager. The

Certificate Manager allows applications to load and verify certificates external to the

SSL/TLS connection.

wolfSSL_CertManagerDisableCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANGER* cm);

Description:

Turns off Certificate Revocation List checking when verifying certificates with the

Certificate Manager. By default, CRL checking is off. You can use this function to

temporarily or permanently disable CRL checking with this Certificate Manager context

that previously had CRL checking enabled.

Return Values:

If successful the call will return SSL_SUCCESS.

BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.

532

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, created using

wolfSSL_CertManagerNew().

Example:

int ret = 0;

WOLFSSL_CERT_MANAGER* cm;

...

ret = wolfSSL_CertManagerDisableCRL(cm);

if (ret != SSL_SUCCESS) {

// error disabling cert manager

}

...

See Also:

wolfSSL_CertManagerEnableCRL

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANGER* cm, int options);

Description:

Turns on Certificate Revocation List checking when verifying certificates with the

Certificate Manager. By default, CRL checking is off. options include

WOLFSSL_CRL_CHECKALL which performs CRL checking on each certificate in the

chain versus the Leaf certificate only which is the default.

Return Values:

If successful the call will return SSL_SUCCESS.

NOT_COMPILED_IN will be returned if wolfSSL was not built with CRL enabled.

MEMORY_E will be returned if an out of memory condition occurs.

533

BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.

SSL_FAILURE will be returned if the CRL context cannot be initialized properly.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, created using

wolfSSL_CertManagerNew().

options - options to use when enabling the Certification Manager, cm.

Example:

int ret = 0;

WOLFSSL_CERT_MANAGER* cm;

...

ret = wolfSSL_CertManagerEnableCRL(cm, 0);

if (ret != SSL_SUCCESS) {

// error enabling cert manager

}

...

See Also:

wolfSSL_CertManagerDisableCRL

wolfSSL_CertManagerFree

Synopsis:

#include <wolfssl/ssl.h>

void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANGER* cm);

Description:

Frees all resources associated with the Certificate Manager context. Call this when you

no longer need to use the Certificate Manager.

Return Values:

No return value is used.

534

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, created using

wolfSSL_CertManagerNew().

Example:

WOLFSSL_CERT_MANAGER* cm;

...

wolfSSL_CertManagerFree(cm);

See Also:

wolfSSL_CertManagerNew

wolfSSL_CertManagerLoadCA

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANGER* cm,

const char* file, const char* path);

Description:

Specifies the locations for CA certificate loading into the manager context. The PEM

certificate CAfile may contain several trusted CA certificates. If CApath is not NULL it

specifies a directory containing CA certificates in PEM format.

Return Values:

If successful the call will return SSL_SUCCESS.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

535

BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.

SSL_FATAL_ERROR - will be returned upon failure.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, created using

wolfSSL_CertManagerNew().

file - pointer to the name of the file containing CA certificates to load.

path - pointer to the name of a directory path containing CA certificates to load. The

NULL pointer may be used if no certificate directory is desired.

Example:

int ret = 0;

WOLFSSL_CERT_MANAGER* cm;

...

ret = wolfSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0);

if (ret != SSL_SUCCESS) {

// error loading CA certs into cert manager

}

See Also:

wolfSSL_CertManagerVerify

wolfSSL_CertManagerNew

Synopsis:

#include <wolfssl/ssl.h>

WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew(void);

Description:

Allocates and initializes a new Certificate Manager context. This context may be used

independent of SSL needs. It may be used to load certificates, verify certificates, and

check the revocation status.

536

Return Values:

If successful the call will return a valid WOLFSSL_CERT_MANAGER pointer.

NULL will be returned for an error state.

Parameters:

There are no parameters for this function.

Example:

WOLFSSL_CERT_MANAGER* cm;

cm = wolfSSL_CertManagerNew();

if (cm == NULL) {

// error creating new cert manager

}

See Also:

wolfSSL_CertManagerFree

wolfSSL_CertManagerVerify

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANGER* cm, const char* fname,

int fomat);

Description:

Specifies the certificate to verify with the Certificate Manager context. The format can

be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.

Return Values:

If successful the call will return SSL_SUCCESS.

ASN_SIG_CONFIRM_E will be returned if the signature could not be verified.

ASN_SIG_OID_E will be returned if the signature type is not supported.

537

CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked.

CRL_MISSING is an error that is returned if a current issuer CRL is not available.

ASN_BEFORE_DATE_E will be returned if the current date is before the before date.

ASN_AFTER_DATE_E will be returned if the current date is after the after date.

SSL_BAD_FILETYPE will be returned if the file is the wrong format.

SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.

MEMORY_E will be returned if an out of memory condition occurs.

ASN_INPUT_E will be returned if Base16 decoding fails on the file.

BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.

Parameters:

cm - a pointer to a WOLFSSL_CERT_MANAGER structure, created using

wolfSSL_CertManagerNew().

fname - pointer to the name of the file containing the certificates to verify.

format - format of the certificate to verify - either SSL_FILETYPE_ASN1 or

SSL_FILETYPE_PEM.

Example:

int ret = 0;

WOLFSSL_CERT_MANAGER* cm;

...

ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”,

SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error verifying certificate

}

538

See Also:

wolfSSL_CertManagerLoadCA

wolfSSL_CertManagerVerifyBuffer

Synopsis:

#include <wolfssl/ssl.h>

int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANGER* cm,

const byte* buff, long sz, int format);

Description:

Specifies the certificate buffer to verify with the Certificate Manager context. The format

can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.