Common Terms and Types in wolfSSL Lightweight SSL

If you are using or thinking about using the wolfSSL lightweight SSL/TLS library in your application or project, it’s oftentimes helpful to get a general overview of some of the terms and types which are used in a simple wolfSSL connection. Below we have included a general summary of these types.

1) socket: wolfSSL uses the type SOCKET_T to allow different TCP stacks to be used.

2) SSL Context:  wolfSSL uses the type CYASSL_CTX*.  This is either a client context or a server context.  Multiple SSL connections can be created from a single CYASSL_CTX*.  The context holds CA certificates, keys, and options for the connections that will be created from it.

3) SSL Connection:  wolfSSL uses the type CYASSL* to represent a single SSL connection.  This object is created from a parent CYASSL_CTX*.  It may contain a SOCKET_T if the underlying I/O is socket based, but that is not a requirement. With wolfSSL’s I/O callbacks a memory buffer, file, or event handler may be used instead.

1) SSL Session:  wolfSSL uses the type CYASSL_SESSION*.  Each time a full SSL handshake is done on a CYASSL* Connection object a new CYASSL_SESSION* is created.  A single CYASSL_SESSION* can later be used to do session resumption on multiple different CYASSL* connections.

For example, let`s say a browser has 3 tabs open to a simple secure site.  The browser would need:

1 CYASSL_CTX* client context with CA certificates loaded.

3 SOCKET_T sockets, 1 for each tab.

3 CYASSL* connections, one for each tab.  Each connection owns one of the 3 unique SOCKET_T but was created from the same CYASSL_CTX*.

1 CYASSL_SESSION* was created from the first tab.  The 2nd and 3rd tab would use the initial CYASSL_SESSION* to do session resumption with their respective CYASSL* connections.

Code wise, to retrieve a session the application would just call wolfSSL_get_session() before ending the connection with wolfSSL_shutdown().

CYASSL_SESSION* mySession = wolfSSL_get_session(ssl_conn1);

To later use that session on a new CYASSL connection (ssl_conn2), do:

wolfSSL_set_session(ssl_conn2, mySession);

before calling wolfSSL_connect().  Connection 2 will attempt session resumption.

For more detailed information, the wolfSSL API reference discusses each function in more detail:

The wolfSSL example client (examples/client/client.c in the general wolfSSL download) does session resumption if the user passes -r to the command line.  If you search for get_session and set_session you should see right where it`s used.