wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.1  Initialization / Shutdown


The functions in this section have to do with initializing the wolfSSL library and shutting it down (freeing resources) after it is no longer needed by the application.






wolfSSL_Init


Synopsis:

#include <wolfssl/ssl.h>


int wolfSSL_Init(void);


Description:

Initializes the wolfSSL library for use.  Must be called once per application and before any other call to the library.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_MUTEX_ERROR is an error that may be returned.


Parameters:


This function has no parameters.


Example:


int ret = 0;

ret = wolfSSL_Init();

if (ret != SSL_SUCCESS) {

// failed to initialize wolfSSL library

}


See Also:

wolfSSL_Cleanup






wolfSSL_library_init


Synopsis:

#include <wolfssl/ssl.h>


int wolfSSL_library_init(void)


Description:

Initializes the wolfSSL library for use.  Must be called once per application and before any other call to the library.


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:

CyaSSL_Init

CyaSSL_Cleanup






wolfSSL_Cleanup


Synopsis:

#include <wolfssl/ssl.h>


void 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:

No return value for this function.


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

wolfSSL_free

wolfSSL_CTX_free




 

Questions? +1 (425) 245-8247