FreeRTOS+ Ecosystem Showcase
FreeRTOS royalty free RTOS RSS feed  Real time embedded FreeRTOS mailing list  
FreeRTOS Home FreeRTOS+ Home Contact / Enquiries

Simple CyaSSL Client Side Example

The three steps to using CyaSSL in a client side FreeRTOS application
The three steps to using CyaSSL in a client side application

Introduction

This page describes how, in just a few easy steps, the CyaSSL library can be used to to ensure the security and integrity of a client side networking application.


Header files

cyassl/ssl.h contains the CyaSSL structures, data definitions, and function prototypes. It must be included in all the source files that use the CyaSSL library. 


#include "cyassl/ssl.h"
The header file that must be included in all source files that use the CyaSSL library


Initialising the library and creating a CyaSSL context

CyaSSL_Init() prepares the CyaSSL library for use, and must be called before any other CyaSSL API functions.

Next, a variable of type CYASSL_CTX is required to store context information, and can be created using CyaSSL_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 client protocol being selected. The values to use to select the other protocol options are listed in the user manual.

The final initialisation step is loading a Certificate Authority (CA) into the CyaSSL context. This allows authentication with the server the client will connect to. CyaSSL_CTX_load_verify_locations() is used for this purpose. In the example below, the first function parameter specifies the context into which the CA is loaded, and the second the CA certificate that is used. The third parameter can be used to specify a file path that will be searched for certificates, but in this case the file path is not necessary and so set to 0. 


/* Define a structure to hold the CyaSSL context. */
CYASSL_CTX* xCyaSSL_Context;

    /* Initialise CyaSSL.  This must be done before any other CyaSSL functions
    are called. */
    CyaSSL_Init();

    /* Attempt to create a context that uses the TLS V1 client protocol. */
    xCyaSSL_Context = CyaSSL_CTX_new( CyaTLSv1_client_method() );

    if( xCyaSSL_Context != NULL )
    {
        /* Load the CA certificate.  Real applications should ensure that
        CyaSSL_CTX_load_verify_locations() returns SSL_SUCCESS before proceeding. */
        CyaSSL_CTX_load_verify_locations( xCyaSSL_Context, "ca-cert.pem", 0 );
    }
Library initialisation, protocol selection, and loading the CA certificate


Associating a CyaSSL object with a connected socket

Each TCP connection must be associated with a CyaSSL object. CyaSSL objects are created using CyaSSL_new(), and associated with a TCP socket using CyaSSL_set_fd(). 


CYASSL* xCyaSSL_Object;

    /* Standard Berkeley sockets connect function. */
    if( connect( sockfd, (SA *) &servaddr, sizeof( servaddr ) ) == 0 )
    {
        /* The connect was successful.  Create a CyaSSL object to associate with
        this connection.  The context created during initialisation is passed as
        the function parameter. */
        xCyaSSL_Object = CyaSSL_new( xCyaSSL_Context );
        
        if( xCyaSSL_Object != NULL )
        {
            /* Associate the created CyaSSL object with the connected socket. */
            CyaSSL_set_fd( xCyaSSL_Object, sockfd );
        }
    }
Creating a CyaSSL object, and associating it with a connected socket


Using the socket

Secure communication can now be made through the socket by using CyaSSL_write() in place of the standard sockets write() or send() functions, and CyaSSL_read() in place of the standard sockets read() or recv().

Note that the first parameter to both CyaSSL_write() and CyaSSL_read() is not the socket descriptor, but the CyaSSL object that is associated with the socket descriptor. 


char ucTxBuf[ MAXLINE ], ucRxBuf[ MAXLINE ];

    if( CyaSSL_write( xCyaSSL_Object, ucTxBuf, strlen( ucTxBuf ) ) != strlen( ucTxBuf ) )
    {
        /* Send failed. */
    }

    if( CyaSSL_read( xCyaSSL_Object, ucRxBuf, MAXLINE ) <= 0 )
    {
        /* Read failed. */
    }
Writing to and reading from a socket using the CyaSSL API


Deleting allocated resources

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



    /* CyaSSL objects should be deleted when they are no longer required. */
    CyaSSL_free( xCyaSSL_Object );
    
    /* The CyaSSL 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. */
    CyaSSL_CTX_free( xCyaSSL_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. */
    CyaSSL_Cleanup();
Deleting objects that were dynamically allocated in this example


[ Back to the top ]    [ About FreeRTOS ]    [ FreeRTOS+ Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2013 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd.. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.