Functions
wolfSSL Initialization/Shutdown

Functions

WOLFSSL_API int wolfSSL_shutdown (WOLFSSL *)
 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. More...
 
WOLFSSL_API int wolfSSL_SetServerID (WOLFSSL *, const unsigned char *, int, int)
 This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused. More...
 
WOLFSSL_API int wolfSSL_library_init (void)
 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. More...
 
WOLFSSL_API int wolfSSL_get_shutdown (const WOLFSSL *)
 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. More...
 
WOLFSSL_API int wolfSSL_is_init_finished (WOLFSSL *)
 This function checks to see if the connection is established. More...
 
WOLFSSL_API int wolfSSL_Init (void)
 Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library. More...
 
WOLFSSL_API int wolfSSL_Cleanup (void)
 Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it will free any resources used by the library. More...
 
WOLFSSL_API int wolfSSL_SetMinVersion (WOLFSSL *ssl, int version)
 This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method). More...
 
WOLFSSL_API int wolfSSL_ALPN_GetProtocol (WOLFSSL *ssl, char **protocol_name, unsigned short *size)
 This function gets the protocol name set by the server. More...
 
WOLFSSL_API int wolfSSL_ALPN_GetPeerProtocol (WOLFSSL *ssl, char **list, unsigned short *listSz)
 This function copies the alpn_client_list data from the SSL object to the buffer. More...
 
WOLFSSL_API int wolfSSL_MakeTlsMasterSecret (unsigned char *ms, unsigned int msLen, const unsigned char *pms, unsigned int pmsLen, const unsigned char *cr, const unsigned char *sr, int tls1_2, int hash_type)
 This function copies the values of cr and sr then passes through to PRF (pseudo random function) and returns that value. More...
 

Detailed Description

Function Documentation

◆ wolfSSL_ALPN_GetPeerProtocol()

WOLFSSL_API int wolfSSL_ALPN_GetPeerProtocol ( WOLFSSL ssl,
char **  list,
unsigned short *  listSz 
)

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

Returns
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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
lista pointer to the buffer. The data from the SSL object will be copied into it.
listSzthe buffer size.

Example

#import <wolfssl/ssl.h>
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_ALPN_GetProtocol()

WOLFSSL_API int wolfSSL_ALPN_GetProtocol ( WOLFSSL ssl,
char **  protocol_name,
unsigned short *  size 
)

This function gets the protocol name set by the server.

Returns
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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
protocol_namea pointer to a char that represents the protocol name and will be held in the ALPN structure.
sizea 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

◆ wolfSSL_Cleanup()

WOLFSSL_API int wolfSSL_Cleanup ( void  )

Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it will free any resources used by the library.

Returns
SSL_SUCCESS return no errors.
BAD_MUTEX_E a mutex error return.]

Example

See also
wolfSSL_Init

◆ wolfSSL_get_shutdown()

WOLFSSL_API int wolfSSL_get_shutdown ( const WOLFSSL )

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.

Returns
1 SSL_SENT_SHUTDOWN is returned.
2 SS_RECEIVED_SHUTDOWN is returned.
Parameters
ssla constant pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

#include <wolfssl/ssl.h>
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
int ret;
if(ret == 1){
SSL_SENT_SHUTDOWN
} else if(ret == 2){
SSL_RECEIVED_SHUTDOWN
} else {
Fatal error.
}
See also
wolfSSL_SESSION_free

◆ wolfSSL_Init()

WOLFSSL_API int wolfSSL_Init ( void  )

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

Returns
SSL_SUCCESS If successful the call will return.
BAD_MUTEX_E is an error that may be returned.
WC_INIT_E wolfCrypt initialization error returned.

Example

int ret = 0;
ret = wolfSSL_Init();
if (ret != SSL_SUCCESS) {
failed to initialize wolfSSL library
}
See also
wolfSSL_Cleanup

◆ wolfSSL_is_init_finished()

WOLFSSL_API int wolfSSL_is_init_finished ( WOLFSSL )

This function checks to see if the connection is established.

Returns
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 connection is not established i.e. the WOLFSSL struct is null or the handshake is not done.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

EXAMPLE

#include <wolfssl/ssl.h>
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
Handshake is done and connection is established
}
See also
wolfSSL_set_accept_state
wolfSSL_get_keys
wolfSSL_set_shutdown

◆ wolfSSL_library_init()

WOLFSSL_API int wolfSSL_library_init ( void  )

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.

Returns
SSL_SUCCESS If successful the call will return.
SSL_FATAL_ERROR is returned upon failure.
Parameters
noneNo parameters.

Example

int ret = 0;
if (ret != SSL_SUCCESS) {
failed to initialize wolfSSL
}
...
See also
wolfSSL_Init
wolfSSL_Cleanup

◆ wolfSSL_MakeTlsMasterSecret()

WOLFSSL_API int wolfSSL_MakeTlsMasterSecret ( unsigned char *  ms,
unsigned int  msLen,
const unsigned char *  pms,
unsigned int  pmsLen,
const unsigned char *  cr,
const unsigned char *  sr,
int  tls1_2,
int  hash_type 
)

This function copies the values of cr and sr then passes through to PRF (pseudo random function) and returns that value.

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
msthe master secret held in the Arrays structure.
msLenthe length of the master secret.
pmsthe pre-master secret held in the Arrays structure.
pmsLenthe length of the pre-master secret.
crthe client random.
srthe server random.
tls1_2signifies that the version is at least tls version 1.2.
hash_typesignifies the hash type.

Example

WOLFSSL* ssl;
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
p_hash
MakeTlsMasterSecret

◆ wolfSSL_SetMinVersion()

WOLFSSL_API int wolfSSL_SetMinVersion ( WOLFSSL ssl,
int  version 
)

This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method).

Returns
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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
versionan 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; macro representation
if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
Failed to set min version
}
See also
SetMinVersionHelper

◆ wolfSSL_SetServerID()

WOLFSSL_API int wolfSSL_SetServerID ( WOLFSSL ,
const unsigned char *  ,
int  ,
int   
)

This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused.

Returns
SSL_SUCCESS returned if the finction executed without error.
BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter is NULL or if len is not greater than zero.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
ida constant byte pointer that will be copied to the serverID member of the WOLFSSL_SESSION structure.
lenan int type representing the length of the session id parameter.
newSessionan 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_shutdown()

WOLFSSL_API int wolfSSL_shutdown ( WOLFSSL )

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.

Returns
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
sslpointer to the SSL session created with wolfSSL_new().

Example

#include <wolfssl/ssl.h>
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