The three steps to using WolfSSL in a server side application
This page describes how, in just a few easy steps, the WolfSSL library can be used to
to ensure the security and integrity of a server side networking application.
The information on this page is nearly identical to that found on the
Simple WolfSSL Client Side Example
page. It is repeated here for consistency - with the differences highlighted
where they exist.
wolfssl/ssl.h contains the WolfSSL structures, data definitions, and function
prototypes. It must be included in all the source files that use the
The header file that must be included in all source files that use the WolfSSL library
Initialising the library and creating a WolfSSL context
wolfSSL_Init() prepares the WolfSSL library for use, and must be
called before any other WolfSSL API functions.
Next, a variable of type WOLFSSL_CTX is required to store context information,
and can be created using wolfSSL_CTX_new(). The SSL or TLS protocol
to use is specified as the context is created using the function's
parameter. Options include SSLv3, TLSv1, TLSv1.1, TLSv1.2, or DTLS.
This example demonstrates the TLSv1 server protocol being selected (the client
side example selects TLSv1 client). The values
to use to select the other protocol options are listed in the user manual.
The client side example demonstrated a Certificate Authority (CA) file being
loaded into the WolfSSL context. In addition to the CA, the server context must also
be loaded with the server certificate, and a key file. This allows the server to send its
certificate to the client for verification.
wolfSSL_CTX_load_verify_locations() is called to load the CA,
wolfSSL_CTX_use_certificate_file() to load the certificate, and
wolfSSL_CTX_use_PrivateKey_file to load the private key file.
/* Define a structure to hold the WolfSSL context. */
/* Initialise WolfSSL. This must be done before any other WolfSSL functions
are called. */
/* Attempt to create a context that uses the TLS V1 server protocol. */
xWolfSSL_Context = wolfSSL_CTX_new( CyaTLSv1_server_method() );
if( xWolfSSL_Context != NULL )
/* Load the CA certificate. Real applications should ensure that
wolfSSL_CTX_load_verify_locations() returns SSL_SUCCESS before proceeding. */
wolfSSL_CTX_load_verify_locations( xWolfSSL_Context, "ca-cert.pem", 0 );
/* Again, checking of the return values is omitted from this example,
just for clarity. Real applications must ensure the following two
functions return SSL_SUCCESS. */
wolfSSL_CTX_use_certificate_file( xWolfSSL_Context, "server-cert.pem", SSL_FILETYPE_PEM );
wolfSSL_CTX_use_PrivateKey_file( xWolfSSL_Context, "server-key.pem", SSL_FILETYPE_PEM );
Library initialisation, protocol selection, and loading the CA certificate,
server certificate and private key into the WolfSSL context.
Associating a WolfSSL object with a connected socket
Each accepted connection must be associated with a WolfSSL object.
WolfSSL objects are created using wolfSSL_new(), and associated
with a TCP socket using wolfSSL_set_fd().
/* A connection has been accepted by the server. Create a WolfSSL
object for use with the newly connected socket. */
xWolfSSL_Object = wolfSSL_new( xWolfSSL_Context );
if( xWolfSSL_Object != NULL )
/* Associate the created WolfSSL object with the connected socket
wolfSSL_set_fd( xWolfSSL_Object, sockfd );
Creating a WolfSSL object, and associating it with an accepted connection
Using the socket
Secure communication can now be made through the socket by using
wolfSSL_write() in place of the standard sockets write() or send() functions,
and wolfSSL_read() in place of the standard sockets read() or recv().
Note that the first parameter to both wolfSSL_write() and wolfSSL_read()
is not the socket descriptor, but the WolfSSL object that is associated with
the socket descriptor.
Writing to and reading from a socket using the WolfSSL API
Deleting allocated resources
WolfSSL API functions that result in dynamic resource allocation have a counterpart
function that should be called to free the resource when it is no longer required.
The code snippet below shows how the objects created in this small example should be freed.
/* WolfSSL objects should be deleted when they are no longer required. */
wolfSSL_free( xWolfSSL_Object );
/* The WolfSSL context should be deleted if it is no longer required. However,
because most deeply embedded applications will keep the context for the lifetime
of the application, and only ever be restarted when the system is rebooted, it
might be that the context is never explicitly freed. */
wolfSSL_CTX_free( xWolfSSL_Context );
/* The library itself should be shut down cleanly if it too is no longer
required. Again, because most deeply embedded applications will require the
library for the lifetime of the application, and only ever be restarted when
the system is rebooted, it might be that the library is never explicitly closed. */
Deleting objects that were dynamically allocated in this example