wolfSSL Initialization/Shutdown
Functions
Name | |
---|---|
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. |
int | wolfSSL_SetServerID(WOLFSSL * ssl, const unsigned char * id, int len, int newSession) This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused. |
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. |
int | wolfSSL_get_shutdown(const WOLFSSL * ssl) 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. |
int | wolfSSL_is_init_finished(WOLFSSL * ssl) This function checks to see if the connection is established. |
int | wolfSSL_Init(void ) Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library. |
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. |
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). |
int | wolfSSL_ALPN_GetProtocol(WOLFSSL * ssl, char ** protocol_name, unsigned short * size) This function gets the protocol name set by the server. |
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. |
int | wolfSSL_MakeTlsMasterSecret(unsigned char * ms, word32 msLen, const unsigned char * pms, word32 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 wc_PRF (pseudo random function) and returns that value. |
int | wolfSSL_preferred_group(WOLFSSL * ssl) This function returns the key exchange group the client prefers to use in the TLS v1.3 handshake. Call this function to after a handshake is complete to determine which group the server prefers so that this information can be used in future connections to pre-generate a key pair for key exchange. |
int | wolfSSL_get_client_suites_sigalgs(const WOLFSSL * ssl, const byte suites, word16 * suiteSz, const byte hashSigAlgo, word16 * hashSigAlgoSz) This function returns the raw list of ciphersuites and signature algorithms offered by the client. The lists are only stored and returned inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to be able to dynamically load certificates and keys based on the available ciphersuites and signature algorithms. |
WOLFSSL_CIPHERSUITE_INFO | wolfSSL_get_ciphersuite_info(byte first, byte second) This returns information about the ciphersuite directly from the raw ciphersuite bytes. |
int | wolfSSL_get_sigalg_info(byte first, byte second, int * hashAlgo, int * sigAlgo) This returns information about the hash and signature algorithm directly from the raw ciphersuite bytes. |
Functions Documentation
function wolfSSL_shutdown
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.
Parameters:
- ssl pointer to the SSL session created with wolfSSL_new().
See:
Return:
- 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.
Example
#include <wolfssl/ssl.h>
int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_shutdown(ssl);
if (ret != 0) {
// failed to shut down SSL connection
}
function wolfSSL_SetServerID
int wolfSSL_SetServerID(
WOLFSSL * ssl,
const unsigned char * id,
int len,
int newSession
)
This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused.
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
- id a constant byte pointer that will be copied to the serverID member of the WOLFSSL_SESSION structure.
- len an int type representing the length of the session id parameter.
- newSession an int type representing the flag to denote whether to reuse a session or not.
See: wolfSSL_set_session
Return:
- SSL_SUCCESS returned if the function executed without error.
- BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter is NULL or if len is not greater than zero.
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 == WOLFSSL_SUCCESS) {
// The Id was successfully set
}
function wolfSSL_library_init
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.
Parameters:
- none No parameters.
See:
Return:
- SSL_SUCCESS If successful the call will return.
- SSL_FATAL_ERROR is returned upon failure.
Example
int ret = 0;
ret = wolfSSL_library_init();
if (ret != SSL_SUCCESS) {
failed to initialize wolfSSL
}
...
function wolfSSL_get_shutdown
int wolfSSL_get_shutdown(
const WOLFSSL * ssl
)
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.
Parameters:
- ssl a constant pointer to a WOLFSSL structure, created using wolfSSL_new().
See: wolfSSL_SESSION_free
Return:
- 1 SSL_SENT_SHUTDOWN is returned.
- 2 SSL_RECEIVED_SHUTDOWN is returned.
Example
#include <wolfssl/ssl.h>
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
…
int ret;
ret = wolfSSL_get_shutdown(ssl);
if(ret == 1){
SSL_SENT_SHUTDOWN
} else if(ret == 2){
SSL_RECEIVED_SHUTDOWN
} else {
Fatal error.
}
function wolfSSL_is_init_finished
int wolfSSL_is_init_finished(
WOLFSSL * ssl
)
This function checks to see if the connection is established.
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
See:
- wolfSSL_set_accept_state
- wolfSSL_get_keys
- wolfSSL_set_shutdown
Return:
- 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 established i.e. the WOLFSSL handshake is done.
EXAMPLE
#include <wolfssl/ssl.h>
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_is_init_finished(ssl)){
Handshake is done and connection is established
}
function wolfSSL_Init
int wolfSSL_Init(
void
)
Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library.
See: wolfSSL_Cleanup
Return:
- 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
}
function wolfSSL_Cleanup
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.
See: wolfSSL_Init
Return:
- SSL_SUCCESS return no errors.
- BAD_MUTEX_E a mutex error return.]
Example
wolfSSL_Cleanup();
function wolfSSL_SetMinVersion
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).
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
- version an 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.
See: SetMinVersionHelper
Return:
- 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.
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
}
function wolfSSL_ALPN_GetProtocol
int wolfSSL_ALPN_GetProtocol(
WOLFSSL * ssl,
char ** protocol_name,
unsigned short * size
)
This function gets the protocol name set by the server.
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
- protocol_name a pointer to a char that represents the protocol name and will be held in the ALPN structure.
- size a word16 type that represents the size of the protocol_name.
See:
- TLSX_ALPN_GetRequest
- TLSX_Find
Return:
- 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.
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
}
function wolfSSL_ALPN_GetPeerProtocol
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.
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
- list a pointer to the buffer. The data from the SSL object will be copied into it.
- listSz the buffer size.
See: wolfSSL_UseALPN
Return:
- 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.
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
}
function wolfSSL_MakeTlsMasterSecret
int wolfSSL_MakeTlsMasterSecret(
unsigned char * ms,
word32 msLen,
const unsigned char * pms,
word32 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 wc_PRF (pseudo random function) and returns that value.
Parameters:
- ms the master secret held in the Arrays structure.
- msLen the length of the master secret.
- pms the pre-master secret held in the Arrays structure.
- pmsLen the length of the pre-master secret.
- cr the client random.
- sr the server random.
- tls1_2 signifies that the version is at least tls version 1.2.
- hash_type signifies the hash type.
See:
- wc_PRF
- MakeTlsMasterSecret
Return:
- 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.
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;
}
function wolfSSL_preferred_group
int wolfSSL_preferred_group(
WOLFSSL * ssl
)
This function returns the key exchange group the client prefers to use in the TLS v1.3 handshake. Call this function to after a handshake is complete to determine which group the server prefers so that this information can be used in future connections to pre-generate a key pair for key exchange.
Parameters:
- ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
See:
- wolfSSL_UseKeyShare
- wolfSSL_CTX_set_groups
- wolfSSL_set_groups
- wolfSSL_CTX_set1_groups_list
- wolfSSL_set1_groups_list
Return:
- BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
- SIDE_ERROR if called with a server.
- NOT_READY_ERROR if called before handshake is complete.
- Group identifier if successful.
Example
int ret;
int group;
WOLFSSL* ssl;
...
ret = wolfSSL_CTX_set1_groups_list(ssl)
if (ret < 0) {
// failed to get group
}
group = ret;
function wolfSSL_get_client_suites_sigalgs
int wolfSSL_get_client_suites_sigalgs(
const WOLFSSL * ssl,
const byte ** suites,
word16 * suiteSz,
const byte ** hashSigAlgo,
word16 * hashSigAlgoSz
)
This function returns the raw list of ciphersuites and signature algorithms offered by the client. The lists are only stored and returned inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to be able to dynamically load certificates and keys based on the available ciphersuites and signature algorithms.
Parameters:
- ssl The WOLFSSL object to extract the lists from.
- optional suites Raw and unfiltered list of client ciphersuites
- optional suiteSz Size of suites in bytes
- optional hashSigAlgo Raw and unfiltered list of client signature algorithms
- optional hashSigAlgoSz Size of hashSigAlgo in bytes
See:
Return:
- WOLFSSL_SUCCESS when suites available
- WOLFSSL_FAILURE when suites not available
Example
int certCB(WOLFSSL* ssl, void* arg)
{
const byte* suites = NULL;
word16 suiteSz = 0;
const byte* hashSigAlgo = NULL;
word16 hashSigAlgoSz = 0;
wolfSSL_get_client_suites_sigalgs(ssl, &suites, &suiteSz, &hashSigAlgo,
&hashSigAlgoSz);
// Choose certificate to load based on ciphersuites and sigalgs
}
WOLFSSL* ctx;
ctx = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
wolfSSL_CTX_set_cert_cb(ctx, certCB, NULL);
function wolfSSL_get_ciphersuite_info
WOLFSSL_CIPHERSUITE_INFO wolfSSL_get_ciphersuite_info(
byte first,
byte second
)
This returns information about the ciphersuite directly from the raw ciphersuite bytes.
Parameters:
- first First byte of the ciphersuite
- second Second byte of the ciphersuite
See:
Return: WOLFSSL_CIPHERSUITE_INFO A struct containing information about the type of authentication used in the ciphersuite.
Example
WOLFSSL_CIPHERSUITE_INFO info =
wolfSSL_get_ciphersuite_info(suites[0], suites[1]);
if (info.rsaAuth)
haveRSA = 1;
else if (info.eccAuth)
haveECC = 1;
function wolfSSL_get_sigalg_info
int wolfSSL_get_sigalg_info(
byte first,
byte second,
int * hashAlgo,
int * sigAlgo
)
This returns information about the hash and signature algorithm directly from the raw ciphersuite bytes.
Parameters:
- first First byte of the hash and signature algorithm
- second Second byte of the hash and signature algorithm
- hashAlgo The enum wc_HashType of the MAC algorithm
- sigAlgo The enum Key_Sum of the authentication algorithm
See:
Return:
- 0 when info was correctly set
- BAD_FUNC_ARG when either input parameters are NULL or the bytes are not a recognized sigalg suite
Example
enum wc_HashType hashAlgo;
enum Key_Sum sigAlgo;
wolfSSL_get_sigalg_info(hashSigAlgo[idx+0], hashSigAlgo[idx+1],
&hashAlgo, &sigAlgo);
if (sigAlgo == RSAk || sigAlgo == RSAPSSk)
haveRSA = 1;
else if (sigAlgo == ECDSAk)
haveECC = 1;
Updated on 2024-12-24 at 01:15:56 +0000