wolfSSL Connection, Session, and I/O

Functions

	Name
long	wolfSSL_get_verify_depth(WOLFSSL * ssl) This function returns the maximum chain depth allowed, which is 9 by default, for a valid session i.e. there is a non_null session object (ssl).
char *	wolfSSL_get_cipher_list(int priority) Get the name of cipher at priority level passed in.
int	wolfSSL_get_ciphers(char * buf, int len) This function gets the ciphers enabled in wolfSSL.
const char *	wolfSSL_get_cipher_name(WOLFSSL * ssl) This function gets the cipher name in the format DHE-RSA by passing through argument to wolfSSL_get_cipher_name_internal.
int	wolfSSL_get_fd(const WOLFSSL * ) This function returns the file descriptor (fd) used as the input/output facility for the SSL connection. Typically this will be a socket file descriptor.
int	wolfSSL_get_using_nonblock(WOLFSSL * ) This function allows the application to determine if wolfSSL is using non_blocking I/O. If wolfSSL is using non_blocking I/O, this function will return 1, otherwise 0. After an application creates a WOLFSSL object, if it will be used with a non_blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
int	wolfSSL_write(WOLFSSL * ssl, const void * data, int sz) This function writes sz bytes from the buffer, data, to the SSL connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data feature is compiled in, this function progresses the handshake only up to the point when it is possible to send data. Next invocations of wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the handshake. wolfSSL_write() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_write() will return when the underlying I/O could not satisfy the needs of wolfSSL_write() 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_write() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred.
int	wolfSSL_read(WOLFSSL * ssl, void * data, int sz) This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data. The bytes read are removed from the internal receive buffer. If necessary wolfSSL_read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_read() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_read() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_read() will trigger processing of the next record.
int	wolfSSL_peek(WOLFSSL * ssl, void * data, int sz) This function copies sz bytes from the SSL session (ssl) internal read buffer into the buffer data. This function is identical to wolfSSL_read() except that the data in the internal SSL session receive buffer is not removed or modified. If necessary, like wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_peek() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_peek() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_peek() will trigger processing of the next record.
int	wolfSSL_accept(WOLFSSL * ) This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. 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_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred.
int	wolfSSL_send(WOLFSSL * ssl, const void * data, int sz, int flags) This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the specified flags for the underlying write operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). wolfSSL_send() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_send() will return when the underlying I/O could not satisfy the needs of wolfSSL_send 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_send() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred.
int	wolfSSL_recv(WOLFSSL * ssl, void * data, int sz, int flags) This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data using the specified flags for the underlying recv operation. The bytes read are removed from the internal receive buffer. This function is identical to wolfSSL_read() except that it allows the application to set the recv flags for the underlying read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_recv() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_recv(). If sz is larger than the number of bytes in the internal read buffer, SSL_recv() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_recv() will trigger processing of the next record.
int	wolfSSL_get_alert_history(WOLFSSL * ssl, WOLFSSL_ALERT_HISTORY * h) This function gets the alert history.
WOLFSSL_SESSION *	wolfSSL_get_session(WOLFSSL * ssl) When NO_SESSION_CACHE_REF is defined this function returns a pointer to the current session (WOLFSSL_SESSION) used in ssl. This function returns a non_persistent pointer to the WOLFSSL_SESSION object. The pointer returned will be freed when wolfSSL_free is called. This call should only be used to inspect or modify the current session. For session resumption it is recommended to use wolfSSL_get1_session(). For backwards compatibility when NO_SESSION_CACHE_REF is not defined this function returns a persistent session object pointer that is stored in the local cache. The cache size is finite and there is a risk that the session object will be overwritten by another ssl connection by the time the application calls wolfSSL_set_session() on it. It is recommended to define NO_SESSION_CACHE_REF in your application and to use wolfSSL_get1_session() for session resumption.
void	wolfSSL_flush_sessions(WOLFSSL_CTX * ctx, long tm) This function flushes session from the session cache which have expired. The time, tm, is used for the time comparison. Note that wolfSSL currently uses a static table for sessions, so no flushing is needed. As such, this function is currently just a stub. This function provides OpenSSL compatibility (SSL_flush_sessions) when wolfSSL is compiled with the OpenSSL compatibility layer.
int	wolfSSL_GetSessionIndex(WOLFSSL * ssl) This function gets the session index of the WOLFSSL structure.
int	wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION * session) This function gets the session at specified index of the session cache and copies it into memory. The WOLFSSL_SESSION structure holds the session information.
WOLFSSL_X509_CHAIN *	wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION * session) Returns the peer certificate chain from the WOLFSSL_SESSION struct.
int	wolfSSL_pending(WOLFSSL * ) This function returns the number of bytes which are buffered and available in the SSL object to be read by wolfSSL_read().
int	wolfSSL_save_session_cache(const char * fname) This function persists the session cache to file. It doesn’t use memsave because of additional memory use.
int	wolfSSL_restore_session_cache(const char * fname) This function restores the persistent session cache from file. It does not use memstore because of additional memory use.
int	wolfSSL_memsave_session_cache(void * mem, int sz) This function persists session cache to memory.
int	wolfSSL_memrestore_session_cache(const void * mem, int sz) This function restores the persistent session cache from memory.
int	wolfSSL_get_session_cache_memsize(void ) This function returns how large the session cache save buffer should be.
int	wolfSSL_session_reused(WOLFSSL * ssl) This function returns the resuming member of the options struct. The flag indicates whether or not to reuse a session. If not, a new session must be established.
const char *	wolfSSL_get_version(WOLFSSL * ssl) Returns the SSL version being used as a string.
int	wolfSSL_get_current_cipher_suite(WOLFSSL * ssl) Returns the current cipher suit an ssl session is using.
WOLFSSL_CIPHER *	wolfSSL_get_current_cipher(WOLFSSL * ssl) This function returns a pointer to the current cipher in the ssl session.
const char *	wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER * cipher) This function matches the cipher suite in the SSL object with the available suites and returns the string representation.
const char *	wolfSSL_get_cipher(WOLFSSL * ) This function matches the cipher suite in the SSL object with the available suites.
int	wolfSSL_BIO_get_mem_data(WOLFSSL_BIO * bio, void * p) This is used to set a byte pointer to the start of the internal memory buffer.
long	wolfSSL_BIO_set_fd(WOLFSSL_BIO * b, int fd, int flag) Sets the file descriptor for bio to use.
int	wolfSSL_BIO_set_close(WOLFSSL_BIO * b, long flag) Sets the close flag, used to indicate that the i/o stream should be closed when the BIO is freed.
WOLFSSL_BIO_METHOD *	wolfSSL_BIO_s_socket(void ) This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
int	wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO * b, long size) This is used to set the size of write buffer for a WOLFSSL_BIO. If write buffer has been previously set this function will free it when resetting the size. It is similar to wolfSSL_BIO_reset in that it resets read and write indexes to 0.
int	wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO * b1, WOLFSSL_BIO * b2) This is used to pair two bios together. A pair of bios acts similar to a two way pipe writing to one can be read by the other and vice versa. It is expected that both bios be in the same thread, this function is not thread safe. Freeing one of the two bios removes both from being paired. If a write buffer size was not previously set for either of the bios it is set to a default size of 17000 (WOLFSSL_BIO_SIZE) before being paired.
int	wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO * bio) This is used to set the read request flag back to 0.
int	wolfSSL_BIO_nread0(WOLFSSL_BIO * bio, char ** buf) This is used to get a buffer pointer for reading from. Unlike wolfSSL_BIO_nread the internal read index is not advanced by the number returned from the function call. Reading past the value returned can result in reading out of array bounds.
int	wolfSSL_BIO_nread(WOLFSSL_BIO * bio, char ** buf, int num) This is used to get a buffer pointer for reading from. The internal read index is advanced by the number returned from the function call with buf being pointed to the beginning of the buffer to read from. In the case that less bytes are in the read buffer than the value requested with num the lesser value is returned. Reading past the value returned can result in reading out of array bounds.
int	wolfSSL_BIO_nwrite(WOLFSSL_BIO * bio, char ** buf, int num) Gets a pointer to the buffer for writing as many bytes as returned by the function. Writing more bytes to the pointer returned then the value returned can result in writing out of bounds.
int	wolfSSL_BIO_reset(WOLFSSL_BIO * bio) Resets bio to an initial state. As an example for type BIO_BIO this resets the read and write index.
int	wolfSSL_BIO_seek(WOLFSSL_BIO * bio, int ofs) This function adjusts the file pointer to the offset given. This is the offset from the head of the file.
int	wolfSSL_BIO_write_filename(WOLFSSL_BIO * bio, char * name) This is used to set and write to a file. WIll overwrite any data currently in the file and is set to close the file when the bio is freed.
long	wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO * bio, int v) This is used to set the end of file value. Common value is -1 so as not to get confused with expected positive values.
long	wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO * bio, WOLFSSL_BUF_MEM ** m) This is a getter function for WOLFSSL_BIO memory pointer.
const char *	wolfSSL_lib_version(void ) This function returns the current library version.
word32	wolfSSL_lib_version_hex(void ) This function returns the current library version in hexadecimal notation.
int	wolfSSL_negotiate(WOLFSSL * ssl) Performs the actual connect or accept based on the side of the SSL method. If called from the client side then an wolfSSL_connect() is done while a wolfSSL_accept() is performed if called from the server side.
int	wolfSSL_connect_cert(WOLFSSL * ssl) This function is called on the client side and initiates an SSL/TLS handshake with a server only long enough to get the peer’s certificate chain. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect_cert() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect_cert() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the handshake. 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_connect_cert() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect_cert() will only return once the peer’s certificate chain has been received.
int	wolfSSL_writev(WOLFSSL * ssl, const struct iovec * iov, int iovcnt) Simulates writev semantics but doesn’t actually do block at a time because of SSL_write() behavior and because front adds may be small. Makes porting into software that uses writev easier.
unsigned char	wolfSSL_SNI_Status(WOLFSSL * ssl, unsigned char type) This function gets the status of an SNI object.
int	wolfSSL_UseSecureRenegotiation(WOLFSSL * ssl) This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended.
int	wolfSSL_Rehandshake(WOLFSSL * ssl) This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality.
int	wolfSSL_UseSessionTicket(WOLFSSL * ssl) Force provided WOLFSSL structure to use session ticket. The constant HAVE_SESSION_TICKET should be defined and the constant NO_WOLFSSL_CLIENT should not be defined to use this function.
int	wolfSSL_get_SessionTicket(WOLFSSL * ssl, unsigned char * buf, word32 * bufSz) This function copies the ticket member of the Session structure to the buffer.
int	wolfSSL_set_SessionTicket(WOLFSSL * ssl, const unsigned char * buf, word32 bufSz) This function sets the ticket member of the WOLFSSL_SESSION structure within the WOLFSSL struct. The buffer passed into the function is copied to memory.
int	wolfSSL_PrintSessionStats(void ) This function prints the statistics from the session.
int	wolfSSL_get_session_stats(unsigned int * active, unsigned int * total, unsigned int * peak, unsigned int * maxSessions) This function gets the statistics for the session.
long	wolfSSL_BIO_set_fp(WOLFSSL_BIO * bio, XFILE fp, int c) This is used to set the internal file pointer for a BIO.
long	wolfSSL_BIO_get_fp(WOLFSSL_BIO * bio, XFILE * fp) This is used to get the internal file pointer for a BIO.
size_t	wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO * b) Gets the number of pending bytes to read. If BIO type is BIO_BIO then is the number to read from pair. If BIO contains an SSL object then is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY type then returns the size of memory buffer.
int	wolfSSL_set_jobject(WOLFSSL * ssl, void * objPtr) This function sets the jObjectRef member of the WOLFSSL structure.
void *	wolfSSL_get_jobject(WOLFSSL * ssl) This function returns the jObjectRef member of the WOLFSSL structure.
int	wolfSSL_connect(WOLFSSL * ssl) This function is called on the client side and initiates an SSL/TLS handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. 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_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.
int	wolfSSL_update_keys(WOLFSSL * ssl) This function is called on a TLS v1.3 client or server wolfSSL to force the rollover of keys. A KeyUpdate message is sent to the peer and new keys are calculated for encryption. The peer will send back a KeyUpdate message and the new decryption keys will then be calculated. This function can only be called after a handshake has been completed.
int	wolfSSL_key_update_response(WOLFSSL * ssl, int * required) This function is called on a TLS v1.3 client or server wolfSSL to determine whether a rollover of keys is in progress. When wolfSSL_update_keys() is called, a KeyUpdate message is sent and the encryption key is updated. The decryption key is updated when the response is received.
int	wolfSSL_request_certificate(WOLFSSL * ssl) This function requests a client certificate from the TLS v1.3 client. This is useful when a web server is serving some pages that require client authentication and others that don't. A maximum of 256 requests can be sent on a connection.
int	wolfSSL_connect_TLSv13(WOLFSSL * ) This function is called on the client side and initiates a TLS v1.3 handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. 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_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.
	wolfSSL_accept_TLSv13(WOLFSSL * ssl) This function is called on the server side and waits for a SSL/TLS client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. 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_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred. Call this function when expecting a TLS v1.3 connection though older version ClientHello messages are supported.
int	wolfSSL_write_early_data(WOLFSSL * ssl, const void * data, int sz, int * outSz) This function writes early data to the server on resumption. Call this function instead of wolfSSL_connect() or wolfSSL_connect_TLSv13() to connect to the server and send the data in the handshake. This function is only used with clients.
int	wolfSSL_read_early_data(WOLFSSL * ssl, void * data, int sz, int * outSz) This function reads any early data from a client on resumption. Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13() to accept a client and read any early data in the handshake. The function should be invoked until wolfSSL_is_init_finished() returns true. Early data may be sent by the client in multiple messages. If there is no early data then the handshake will be processed as normal. This function is only used with servers.
void *	wolfSSL_GetIOReadCtx(WOLFSSL * ssl) This function returns the IOCB_ReadCtx member of the WOLFSSL struct.
void *	wolfSSL_GetIOWriteCtx(WOLFSSL * ssl) This function returns the IOCB_WriteCtx member of the WOLFSSL structure.
void	wolfSSL_SetIO_NetX(WOLFSSL * ssl, NX_TCP_SOCKET * nxsocket, ULONG waitoption) This function sets the nxSocket and nxWait members of the nxCtx struct within the WOLFSSL structure.

Functions Documentation

function wolfSSL_get_verify_depth

long wolfSSL_get_verify_depth(
    WOLFSSL * ssl
)

This function returns the maximum chain depth allowed, which is 9 by default, for a valid session i.e. there is a non-null session object (ssl).

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: wolfSSL_CTX_get_verify_depth

Return:

MAX_CHAIN_DEPTH returned if the WOLFSSL structure is not NULL. By default the value is 9.
BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
long sslDep = wolfSSL_get_verify_depth(ssl);

if(sslDep > EXPECTED){
    // The verified depth is greater than what was expected
} else {
    // The verified depth is smaller or equal to the expected value
}

function wolfSSL_get_cipher_list

char * wolfSSL_get_cipher_list(
    int priority
)

Get the name of cipher at priority level passed in.

Parameters:

priority Integer representing the priority level of a cipher.

See:

Return:

string Success
0 Priority is either out of bounds or not valid.

Example

printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1));

function wolfSSL_get_ciphers

int wolfSSL_get_ciphers(
    char * buf,
    int len
)

This function gets the ciphers enabled in wolfSSL.

Parameters:

buf a char pointer representing the buffer.
len the length of the buffer.

See:

GetCipherNames
wolfSSL_get_cipher_list
ShowCiphers

Return:

SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if the buf parameter was NULL or if the len argument was less than or equal to zero.
BUFFER_E returned if the buffer is not large enough and will overflow.

Example

static void ShowCiphers(void){
char* ciphers;
int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers));

if(ret == SSL_SUCCES){
        printf(“%s\n”, ciphers);
    }
}

function wolfSSL_get_cipher_name

const char * wolfSSL_get_cipher_name(
    WOLFSSL * ssl
)

This function gets the cipher name in the format DHE-RSA by passing through argument to wolfSSL_get_cipher_name_internal.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

wolfSSL_CIPHER_get_name
wolfSSL_get_current_cipher
wolfSSL_get_cipher_name_internal

Return:

string This function returns the string representation of the cipher suite that was matched.
NULL error or cipher not found.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
char* cipherS = wolfSSL_get_cipher_name(ssl);

if(cipher == NULL){
    // There was not a cipher suite matched
} else {
    // There was a cipher suite matched
    printf(“%s\n”, cipherS);
}

function wolfSSL_get_fd

int wolfSSL_get_fd(
    const WOLFSSL * 
)

This function returns the file descriptor (fd) used as the input/output facility for the SSL connection. Typically this will be a socket file descriptor.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().

See: wolfSSL_set_fd

Return: fd If successful the call will return the SSL session file descriptor.

Example

int sockfd;
WOLFSSL* ssl = 0;
...
sockfd = wolfSSL_get_fd(ssl);
...

function wolfSSL_get_using_nonblock

int wolfSSL_get_using_nonblock(
    WOLFSSL * 
)

This function allows the application to determine if wolfSSL is using non-blocking I/O. If wolfSSL is using non-blocking I/O, this function will return 1, otherwise 0. After an application creates a WOLFSSL object, if it will be used with a non-blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().

See: wolfSSL_set_session

Return:

0 underlying I/O is blocking.
1 underlying I/O is non-blocking.

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_get_using_nonblock(ssl);
if (ret == 1) {
    // underlying I/O is non-blocking
}
...

function wolfSSL_write

int wolfSSL_write(
    WOLFSSL * ssl,
    const void * data,
    int sz
)

This function writes sz bytes from the buffer, data, to the SSL connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data feature is compiled in, this function progresses the handshake only up to the point when it is possible to send data. Next invocations of wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the handshake. wolfSSL_write() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_write() will return when the underlying I/O could not satisfy the needs of wolfSSL_write() 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_write() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
data data buffer which will be sent to peer.
sz size, in bytes, of data to send to the peer (data).

See:

Return:

0 the number of bytes written upon success.
0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char msg[64] = “hello wolfssl!”;
int msgSz = (int)strlen(msg);
int flags;
int ret;
...

ret = wolfSSL_write(ssl, msg, msgSz);
if (ret <= 0) {
    // wolfSSL_write() failed, call wolfSSL_get_error()
}

function wolfSSL_read

int wolfSSL_read(
    WOLFSSL * ssl,
    void * data,
    int sz
)

This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data. The bytes read are removed from the internal receive buffer. If necessary wolfSSL_read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_read() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not-yet-decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_read() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_read() will trigger processing of the next record.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
data buffer where wolfSSL_read() will place data read.
sz number of bytes to read into data.

See:

Return:

0 the number of bytes read upon success.
0 will be returned upon failure. This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_read() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char reply[1024];
...

input = wolfSSL_read(ssl, reply, sizeof(reply));
if (input > 0) {
    // “input” number of bytes returned into buffer “reply”
}

See wolfSSL examples (client, server, echoclient, echoserver) for more
complete examples of wolfSSL_read().

function wolfSSL_peek

int wolfSSL_peek(
    WOLFSSL * ssl,
    void * data,
    int sz
)

This function copies sz bytes from the SSL session (ssl) internal read buffer into the buffer data. This function is identical to wolfSSL_read() except that the data in the internal SSL session receive buffer is not removed or modified. If necessary, like wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_peek() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_peek() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_peek() will trigger processing of the next record.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
data buffer where wolfSSL_peek() will place data read.
sz number of bytes to read into data.

See: wolfSSL_read

Return:

0 the number of bytes read upon success.
0 will be returned upon failure. This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_peek() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char reply[1024];
...

input = wolfSSL_peek(ssl, reply, sizeof(reply));
if (input > 0) {
    // “input” number of bytes returned into buffer “reply”
}

function wolfSSL_accept

int wolfSSL_accept(
    WOLFSSL * 
)

This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. 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_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...

ret = wolfSSL_accept(ssl);
if (ret != SSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_send

int wolfSSL_send(
    WOLFSSL * ssl,
    const void * data,
    int sz,
    int flags
)

This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the specified flags for the underlying write operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). wolfSSL_send() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_send() will return when the underlying I/O could not satisfy the needs of wolfSSL_send 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_send() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
data data buffer to send to peer.
sz size, in bytes, of data to be sent to peer.
flags the send flags to use for the underlying send operation.

See:

Return:

0 the number of bytes written upon success.
0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_send() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char msg[64] = “hello wolfssl!”;
int msgSz = (int)strlen(msg);
int flags = ... ;
...

input = wolfSSL_send(ssl, msg, msgSz, flags);
if (input != msgSz) {
    // wolfSSL_send() failed
}

function wolfSSL_recv

int wolfSSL_recv(
    WOLFSSL * ssl,
    void * data,
    int sz,
    int flags
)

This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data using the specified flags for the underlying recv operation. The bytes read are removed from the internal receive buffer. This function is identical to wolfSSL_read() except that it allows the application to set the recv flags for the underlying read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_recv() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_recv(). If sz is larger than the number of bytes in the internal read buffer, SSL_recv() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_recv() will trigger processing of the next record.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
data buffer where wolfSSL_recv() will place data read.
sz number of bytes to read into data.
flags the recv flags to use for the underlying recv operation.

See:

Return:

0 the number of bytes read upon success.
0 will be returned upon failure. This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char reply[1024];
int flags = ... ;
...

input = wolfSSL_recv(ssl, reply, sizeof(reply), flags);
if (input > 0) {
    // “input” number of bytes returned into buffer “reply”
}

function wolfSSL_get_alert_history

int wolfSSL_get_alert_history(
    WOLFSSL * ssl,
    WOLFSSL_ALERT_HISTORY * h
)

This function gets the alert history.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
h a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the WOLFSSL struct’s alert_history member’s value.

See: wolfSSL_get_error

Return: SSL_SUCCESS returned when the function completed successfully. Either there was alert history or there wasn’t, either way, the return value is SSL_SUCCESS.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
WOLFSSL_ALERT_HISTORY* h;
...
wolfSSL_get_alert_history(ssl, h);
// h now has a copy of the ssl->alert_history  contents

function wolfSSL_get_session

WOLFSSL_SESSION * wolfSSL_get_session(
    WOLFSSL * ssl
)

When NO_SESSION_CACHE_REF is defined this function returns a pointer to the current session (WOLFSSL_SESSION) used in ssl. This function returns a non-persistent pointer to the WOLFSSL_SESSION object. The pointer returned will be freed when wolfSSL_free is called. This call should only be used to inspect or modify the current session. For session resumption it is recommended to use wolfSSL_get1_session(). For backwards compatibility when NO_SESSION_CACHE_REF is not defined this function returns a persistent session object pointer that is stored in the local cache. The cache size is finite and there is a risk that the session object will be overwritten by another ssl connection by the time the application calls wolfSSL_set_session() on it. It is recommended to define NO_SESSION_CACHE_REF in your application and to use wolfSSL_get1_session() for session resumption.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().

See:

Return:

pointer If successful the call will return a pointer to the the current SSL session object.
NULL will be returned if ssl is NULL, the SSL session cache is disabled, wolfSSL doesn’t have the Session ID available, or mutex functions fail.

Example

WOLFSSL* ssl;
WOLFSSL_SESSION* session;
...
session = wolfSSL_get_session(ssl);
if (session == NULL) {
    // failed to get session pointer
}
...

function wolfSSL_flush_sessions

void wolfSSL_flush_sessions(
    WOLFSSL_CTX * ctx,
    long tm
)

This function flushes session from the session cache which have expired. The time, tm, is used for the time comparison. Note that wolfSSL currently uses a static table for sessions, so no flushing is needed. As such, this function is currently just a stub. This function provides OpenSSL compatibility (SSL_flush_sessions) when wolfSSL is compiled with the OpenSSL compatibility layer.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
tm time used in session expiration comparison.

See:

Return: none No returns.

Example

WOLFSSL_CTX* ssl;
...
wolfSSL_flush_sessions(ctx, time(0));

function wolfSSL_GetSessionIndex

int wolfSSL_GetSessionIndex(
    WOLFSSL * ssl
)

This function gets the session index of the WOLFSSL structure.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: wolfSSL_GetSessionAtIndex

Return: int The function returns an int type representing the sessionIndex within the WOLFSSL struct.

Example

WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
...
int sesIdx = wolfSSL_GetSessionIndex(ssl);

if(sesIdx < 0 || sesIdx > sizeof(ssl->sessionIndex)/sizeof(int)){
    // You have an out of bounds index number and something is not right.
}

function wolfSSL_GetSessionAtIndex

int wolfSSL_GetSessionAtIndex(
    int index,
    WOLFSSL_SESSION * session
)

This function gets the session at specified index of the session cache and copies it into memory. The WOLFSSL_SESSION structure holds the session information.

Parameters:

idx an int type representing the session index.
session a pointer to the WOLFSSL_SESSION structure.

See:

UnLockMutex
LockMutex
wolfSSL_GetSessionIndex

Return:

SSL_SUCCESS returned if the function executed successfully and no errors were thrown.
BAD_MUTEX_E returned if there was an unlock or lock mutex error.
SSL_FAILURE returned if the function did not execute successfully.

Example

int idx; // The index to locate the session.
WOLFSSL_SESSION* session;  // Buffer to copy to.
...
if(wolfSSL_GetSessionAtIndex(idx, session) != SSL_SUCCESS){
    // Failure case.
}

function wolfSSL_SESSION_get_peer_chain

WOLFSSL_X509_CHAIN * wolfSSL_SESSION_get_peer_chain(
    WOLFSSL_SESSION * session
)

Returns the peer certificate chain from the WOLFSSL_SESSION struct.

Parameters:

session a pointer to a WOLFSSL_SESSION structure.

See:

Return: pointer A pointer to a WOLFSSL_X509_CHAIN structure that contains the peer certification chain.

Example

WOLFSSL_SESSION* session;
WOLFSSL_X509_CHAIN* chain;
...
chain = wolfSSL_SESSION_get_peer_chain(session);
if(!chain){
    // There was no chain. Failure case.
}

function wolfSSL_pending

int wolfSSL_pending(
    WOLFSSL * 
)

This function returns the number of bytes which are buffered and available in the SSL object to be read by wolfSSL_read().

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().

See:

Return: int This function returns the number of bytes pending.

Example

int pending = 0;
WOLFSSL* ssl = 0;
...

pending = wolfSSL_pending(ssl);
printf(“There are %d bytes buffered and available for reading”, pending);

function wolfSSL_save_session_cache

int wolfSSL_save_session_cache(
    const char * fname
)

This function persists the session cache to file. It doesn’t use memsave because of additional memory use.

Parameters:

fname is a constant char pointer that points to a file for writing.

See:

Return:

SSL_SUCCESS returned if the function executed without error. The session cache has been written to a file.
SSL_BAD_FILE returned if fname cannot be opened or is otherwise corrupt.
FWRITE_ERROR returned if XFWRITE failed to write to the file.
BAD_MUTEX_E returned if there was a mutex lock failure.

Example

const char* fname;
...
if(wolfSSL_save_session_cache(fname) != SSL_SUCCESS){
    // Fail to write to file.
}

function wolfSSL_restore_session_cache

int wolfSSL_restore_session_cache(
    const char * fname
)

This function restores the persistent session cache from file. It does not use memstore because of additional memory use.

Parameters:

fname a constant char pointer file input that will be read.

See:

XFREAD
XFOPEN

Return:

SSL_SUCCESS returned if the function executed without error.
SSL_BAD_FILE returned if the file passed into the function was corrupted and could not be opened by XFOPEN.
FREAD_ERROR returned if the file had a read error from XFREAD.
CACHE_MATCH_ERROR returned if the session cache header match failed.
BAD_MUTEX_E returned if there was a mutex lock failure.

Example

const char *fname;
...
if(wolfSSL_restore_session_cache(fname) != SSL_SUCCESS){
    // Failure case. The function did not return SSL_SUCCESS.
}

function wolfSSL_memsave_session_cache

int wolfSSL_memsave_session_cache(
    void * mem,
    int sz
)

This function persists session cache to memory.

Parameters:

mem a void pointer representing the destination for the memory copy, XMEMCPY().
sz an int type representing the size of mem.

See:

XMEMCPY
wolfSSL_get_session_cache_memsize

Return:

SSL_SUCCESS returned if the function executed without error. The session cache has been successfully persisted to memory.
BAD_MUTEX_E returned if there was a mutex lock error.
BUFFER_E returned if the buffer size was too small.

Example

void* mem;
int sz; // Max size of the memory buffer.
…
if(wolfSSL_memsave_session_cache(mem, sz) != SSL_SUCCESS){
    // Failure case, you did not persist the session cache to memory
}

function wolfSSL_memrestore_session_cache

int wolfSSL_memrestore_session_cache(
    const void * mem,
    int sz
)

This function restores the persistent session cache from memory.

Parameters:

mem a constant void pointer containing the source of the restoration.
sz an integer representing the size of the memory buffer.

See: wolfSSL_save_session_cache

Return:

SSL_SUCCESS returned if the function executed without an error.
BUFFER_E returned if the memory buffer is too small.
BAD_MUTEX_E returned if the session cache mutex lock failed.
CACHE_MATCH_ERROR returned if the session cache header match failed.

Example

const void* memoryFile;
int szMf;
...
if(wolfSSL_memrestore_session_cache(memoryFile, szMf) != SSL_SUCCESS){
    // Failure case. SSL_SUCCESS was not returned.
}

function wolfSSL_get_session_cache_memsize

int wolfSSL_get_session_cache_memsize(
    void 
)

This function returns how large the session cache save buffer should be.

Parameters:

none No parameters.

See: wolfSSL_memrestore_session_cache

Return: int This function returns an integer that represents the size of the session cache save buffer.

Example

int sz = // Minimum size for error checking;
...
if(sz < wolfSSL_get_session_cache_memsize()){
    // Memory buffer is too small
}

function wolfSSL_session_reused

int wolfSSL_session_reused(
    WOLFSSL * ssl
)

This function returns the resuming member of the options struct. The flag indicates whether or not to reuse a session. If not, a new session must be established.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return: This function returns an int type held in the Options structure representing the flag for session reuse.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
…
if(!wolfSSL_session_reused(sslResume)){
    // No session reuse allowed.
}

function wolfSSL_get_version

const char * wolfSSL_get_version(
    WOLFSSL * ssl
)

Returns the SSL version being used as a string.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: wolfSSL_lib_version

Return:

"SSLv3" Using SSLv3
"TLSv1" Using TLSv1
"TLSv1.1" Using TLSv1.1
"TLSv1.2" Using TLSv1.2
"TLSv1.3" Using TLSv1.3
"DTLS": Using DTLS
"DTLSv1.2" Using DTLSv1.2
"unknown" There was a problem determining which version of TLS being used.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);
printf(wolfSSL_get_version("Using version: %s", ssl));

function wolfSSL_get_current_cipher_suite

int wolfSSL_get_current_cipher_suite(
    WOLFSSL * ssl
)

Returns the current cipher suit an ssl session is using.

Parameters:

ssl The SSL session to check.

See:

Return:

ssl->options.cipherSuite An integer representing the current cipher suite.
0 The ssl session provided is null.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);

if(wolfSSL_get_current_cipher_suite(ssl) == 0)
{
    // Error getting cipher suite
}

function wolfSSL_get_current_cipher

WOLFSSL_CIPHER * wolfSSL_get_current_cipher(
    WOLFSSL * ssl
)

This function returns a pointer to the current cipher in the ssl session.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

wolfSSL_get_cipher
wolfSSL_get_cipher_name_internal
wolfSSL_get_cipher_name

Return:

The function returns the address of the cipher member of the WOLFSSL struct. This is a pointer to the WOLFSSL_CIPHER structure.
NULL returned if the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher;

if(!cipherCurr){
    // Failure case.
} else {
    // The cipher was returned to cipherCurr
}

function wolfSSL_CIPHER_get_name

const char * wolfSSL_CIPHER_get_name(
    const WOLFSSL_CIPHER * cipher
)

This function matches the cipher suite in the SSL object with the available suites and returns the string representation.

Parameters:

cipher a constant pointer to a WOLFSSL_CIPHER structure.

See:

Return:

string This function returns the string representation of the matched cipher suite.
none It will return “None” if there are no suites matched.

Example

// gets cipher name in the format DHE_RSA ...
const char* wolfSSL_get_cipher_name_internal(WOLFSSL* ssl){
WOLFSSL_CIPHER* cipher;
const char* fullName;
…
cipher = wolfSSL_get_curent_cipher(ssl);
fullName = wolfSSL_CIPHER_get_name(cipher);

if(fullName){
    // sanity check on returned cipher
}

function wolfSSL_get_cipher

const char * wolfSSL_get_cipher(
    WOLFSSL * 
)

This function matches the cipher suite in the SSL object with the available suites.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return: This function returns the string value of the suite matched. It will return “None” if there are no suites matched.

Example

#ifdef WOLFSSL_DTLS
…
// make sure a valid suite is used
if(wolfSSL_get_cipher(ssl) == NULL){
    WOLFSSL_MSG(“Can not match cipher suite imported”);
    return MATCH_SUITE_ERROR;
}
…
#endif // WOLFSSL_DTLS

function wolfSSL_BIO_get_mem_data

int wolfSSL_BIO_get_mem_data(
    WOLFSSL_BIO * bio,
    void * p
)

This is used to set a byte pointer to the start of the internal memory buffer.

Parameters:

bio WOLFSSL_BIO structure to get memory buffer of.
p byte pointer to set to memory buffer.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

Return:

size On success the size of the buffer is returned
SSL_FATAL_ERROR If an error case was encountered.

Example

WOLFSSL_BIO* bio;
const byte* p;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
ret  = wolfSSL_BIO_get_mem_data(bio, &p);
// check ret value

function wolfSSL_BIO_set_fd

long wolfSSL_BIO_set_fd(
    WOLFSSL_BIO * b,
    int fd,
    int flag
)

Sets the file descriptor for bio to use.

Parameters:

bio WOLFSSL_BIO structure to set fd.
fd file descriptor to use.
closeF flag for behavior when closing fd.

See:

wolfSSL_BIO_new
wolfSSL_BIO_free

Return: SSL_SUCCESS(1) upon success.

Example

WOLFSSL_BIO* bio;
int fd;
// setup bio
wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE);

function wolfSSL_BIO_set_close

int wolfSSL_BIO_set_close(
    WOLFSSL_BIO * b,
    long flag
)

Sets the close flag, used to indicate that the i/o stream should be closed when the BIO is freed.

Parameters:

bio WOLFSSL_BIO structure.
flag flag for behavior when closing i/o stream.

See:

wolfSSL_BIO_new
wolfSSL_BIO_free

Return: SSL_SUCCESS(1) upon success.

Example

WOLFSSL_BIO* bio;
// setup bio
wolfSSL_BIO_set_close(bio, BIO_NOCLOSE);

function wolfSSL_BIO_s_socket

WOLFSSL_BIO_METHOD * wolfSSL_BIO_s_socket(
    void 
)

This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.

Parameters:

none No parameters.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem

Return: WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure that is a socket type

Example

WOLFSSL_BIO* bio;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);

function wolfSSL_BIO_set_write_buf_size

int wolfSSL_BIO_set_write_buf_size(
    WOLFSSL_BIO * b,
    long size
)

This is used to set the size of write buffer for a WOLFSSL_BIO. If write buffer has been previously set this function will free it when resetting the size. It is similar to wolfSSL_BIO_reset in that it resets read and write indexes to 0.

Parameters:

bio WOLFSSL_BIO structure to set fd.
size size of buffer to allocate.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully setting the write buffer.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
ret = wolfSSL_BIO_set_write_buf_size(bio, 15000);
// check return value

function wolfSSL_BIO_make_bio_pair

int wolfSSL_BIO_make_bio_pair(
    WOLFSSL_BIO * b1,
    WOLFSSL_BIO * b2
)

This is used to pair two bios together. A pair of bios acts similar to a two way pipe writing to one can be read by the other and vice versa. It is expected that both bios be in the same thread, this function is not thread safe. Freeing one of the two bios removes both from being paired. If a write buffer size was not previously set for either of the bios it is set to a default size of 17000 (WOLFSSL_BIO_SIZE) before being paired.

Parameters:

b1 WOLFSSL_BIO structure to set pair.
b2 second WOLFSSL_BIO structure to complete pair.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully pairing the two bios.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
WOLFSSL_BIO* bio2;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
bio2 = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
ret = wolfSSL_BIO_make_bio_pair(bio, bio2);
// check ret value

function wolfSSL_BIO_ctrl_reset_read_request

int wolfSSL_BIO_ctrl_reset_read_request(
    WOLFSSL_BIO * bio
)

This is used to set the read request flag back to 0.

Parameters:

bio WOLFSSL_BIO structure to set read request flag.

See:

wolfSSL_BIO_new, wolfSSL_BIO_s_mem
wolfSSL_BIO_new, wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully setting value.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
int ret;
...
ret = wolfSSL_BIO_ctrl_reset_read_request(bio);
// check ret value

function wolfSSL_BIO_nread0

int wolfSSL_BIO_nread0(
    WOLFSSL_BIO * bio,
    char ** buf
)

This is used to get a buffer pointer for reading from. Unlike wolfSSL_BIO_nread the internal read index is not advanced by the number returned from the function call. Reading past the value returned can result in reading out of array bounds.

Parameters:

bio WOLFSSL_BIO structure to read from.
buf pointer to set at beginning of read array.

See:

wolfSSL_BIO_new
wolfSSL_BIO_nwrite0

Return: >=0 on success return the number of bytes to read

Example

WOLFSSL_BIO* bio;
char* bufPt;
int ret;
// set up bio
ret = wolfSSL_BIO_nread0(bio, &bufPt); // read as many bytes as possible
// handle negative ret check
// read ret bytes from bufPt

function wolfSSL_BIO_nread

int wolfSSL_BIO_nread(
    WOLFSSL_BIO * bio,
    char ** buf,
    int num
)

This is used to get a buffer pointer for reading from. The internal read index is advanced by the number returned from the function call with buf being pointed to the beginning of the buffer to read from. In the case that less bytes are in the read buffer than the value requested with num the lesser value is returned. Reading past the value returned can result in reading out of array bounds.

Parameters:

bio WOLFSSL_BIO structure to read from.
buf pointer to set at beginning of read array.
num number of bytes to try and read.

See:

wolfSSL_BIO_new
wolfSSL_BIO_nwrite

Return:

=0 on success return the number of bytes to read
WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1

Example

WOLFSSL_BIO* bio;
char* bufPt;
int ret;

// set up bio
ret = wolfSSL_BIO_nread(bio, &bufPt, 10); // try to read 10 bytes
// handle negative ret check
// read ret bytes from bufPt

function wolfSSL_BIO_nwrite

int wolfSSL_BIO_nwrite(
    WOLFSSL_BIO * bio,
    char ** buf,
    int num
)

Gets a pointer to the buffer for writing as many bytes as returned by the function. Writing more bytes to the pointer returned then the value returned can result in writing out of bounds.

Parameters:

bio WOLFSSL_BIO structure to write to.
buf pointer to buffer to write to.
num number of bytes desired to be written.

See:

wolfSSL_BIO_new
wolfSSL_BIO_free
wolfSSL_BIO_nread

Return:

int Returns the number of bytes that can be written to the buffer pointer returned.
WOLFSSL_BIO_UNSET(-2) in the case that is not part of a bio pair
WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to write to

Example

WOLFSSL_BIO* bio;
char* bufPt;
int ret;
// set up bio
ret = wolfSSL_BIO_nwrite(bio, &bufPt, 10); // try to write 10 bytes
// handle negative ret check
// write ret bytes to bufPt

function wolfSSL_BIO_reset

int wolfSSL_BIO_reset(
    WOLFSSL_BIO * bio
)

Resets bio to an initial state. As an example for type BIO_BIO this resets the read and write index.

Parameters:

bio WOLFSSL_BIO structure to reset.

See:

wolfSSL_BIO_new
wolfSSL_BIO_free

Return:

0 On successfully resetting the bio.
WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset.

Example

WOLFSSL_BIO* bio;
// setup bio
wolfSSL_BIO_reset(bio);
//use pt

function wolfSSL_BIO_seek

int wolfSSL_BIO_seek(
    WOLFSSL_BIO * bio,
    int ofs
)

This function adjusts the file pointer to the offset given. This is the offset from the head of the file.

Parameters:

bio WOLFSSL_BIO structure to set.
ofs offset into file.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

Return:

0 On successfully seeking.
-1 If an error case was encountered.

Example

WOLFSSL_BIO* bio;
XFILE fp;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
ret  = wolfSSL_BIO_set_fp(bio, &fp);
// check ret value
ret  = wolfSSL_BIO_seek(bio, 3);
// check ret value

function wolfSSL_BIO_write_filename

int wolfSSL_BIO_write_filename(
    WOLFSSL_BIO * bio,
    char * name
)

This is used to set and write to a file. WIll overwrite any data currently in the file and is set to close the file when the bio is freed.

Parameters:

bio WOLFSSL_BIO structure to set file.
name name of file to write to.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_file
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully opening and setting file.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
ret  = wolfSSL_BIO_write_filename(bio, “test.txt”);
// check ret value

function wolfSSL_BIO_set_mem_eof_return

long wolfSSL_BIO_set_mem_eof_return(
    WOLFSSL_BIO * bio,
    int v
)

This is used to set the end of file value. Common value is -1 so as not to get confused with expected positive values.

Parameters:

bio WOLFSSL_BIO structure to set end of file value.
v value to set in bio.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

Return: 0 returned on completion

Example

WOLFSSL_BIO* bio;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
ret  = wolfSSL_BIO_set_mem_eof_return(bio, -1);
// check ret value

function wolfSSL_BIO_get_mem_ptr

long wolfSSL_BIO_get_mem_ptr(
    WOLFSSL_BIO * bio,
    WOLFSSL_BUF_MEM ** m
)

This is a getter function for WOLFSSL_BIO memory pointer.

Parameters:

bio pointer to the WOLFSSL_BIO structure for getting memory pointer.
ptr structure that is currently a char*. Is set to point to bio’s memory.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem

Return:

SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is returned (currently value of 1).
SSL_FAILURE Returned if NULL arguments are passed in (currently value of 0).

Example

WOLFSSL_BIO* bio;
WOLFSSL_BUF_MEM* pt;
// setup bio
wolfSSL_BIO_get_mem_ptr(bio, &pt);
//use pt

function wolfSSL_lib_version

const char * wolfSSL_lib_version(
    void 
)

This function returns the current library version.

Parameters:

none No parameters.

See: word32_wolfSSL_lib_version_hex

Return: LIBWOLFSSL_VERSION_STRING a const char pointer defining the version.

Example

char version[MAXSIZE];
version = wolfSSL_KeepArrays();
…
if(version != ExpectedVersion){
    // Handle the mismatch case
}

function wolfSSL_lib_version_hex

word32 wolfSSL_lib_version_hex(
    void 
)

This function returns the current library version in hexadecimal notation.

Parameters:

none No parameters.

See: wolfSSL_lib_version

Return: LILBWOLFSSL_VERSION_HEX returns the hexadecimal version defined in wolfssl/version.h.

Example

word32 libV;
libV = wolfSSL_lib_version_hex();

if(libV != EXPECTED_HEX){
    // How to handle an unexpected value
} else {
    // The expected result for libV
}

function wolfSSL_negotiate

int wolfSSL_negotiate(
    WOLFSSL * ssl
)

Performs the actual connect or accept based on the side of the SSL method. If called from the client side then an wolfSSL_connect() is done while a wolfSSL_accept() is performed if called from the server side.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().

See:

SSL_connect
SSL_accept

Return:

SSL_SUCCESS will be returned if successful. (Note, older versions will return 0.)
SSL_FATAL_ERROR will be returned if the underlying call resulted in an error. Use wolfSSL_get_error() to get a specific error code.

Example

int ret = SSL_FATAL_ERROR;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_negotiate(ssl);
if (ret == SSL_FATAL_ERROR) {
    // SSL establishment failed
int error_code = wolfSSL_get_error(ssl);
...
}
...

function wolfSSL_connect_cert

int wolfSSL_connect_cert(
    WOLFSSL * ssl
)

This function is called on the client side and initiates an SSL/TLS handshake with a server only long enough to get the peer’s certificate chain. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect_cert() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_connect_cert() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the handshake. 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_connect_cert() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect_cert() will only return once the peer’s certificate chain has been received.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS upon success.
SSL_FAILURE will be returned if the SSL session parameter is NULL.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
ret = wolfSSL_connect_cert(ssl);
if (ret != SSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_writev

int wolfSSL_writev(
    WOLFSSL * ssl,
    const struct iovec * iov,
    int iovcnt
)

Simulates writev semantics but doesn’t actually do block at a time because of SSL_write() behavior and because front adds may be small. Makes porting into software that uses writev easier.

Parameters:

ssl pointer to the SSL session, created with wolfSSL_new().
iov array of I/O vectors to write
iovcnt number of vectors in iov array.

See: wolfSSL_write

Return:

0 the number of bytes written upon success.
0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code.
MEMORY_ERROR will be returned if a memory error was encountered.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code.

Example

WOLFSSL* ssl = 0;
char *bufA = “hello\n”;
char *bufB = “hello world\n”;
int iovcnt;
struct iovec iov[2];

iov[0].iov_base = buffA;
iov[0].iov_len = strlen(buffA);
iov[1].iov_base = buffB;
iov[1].iov_len = strlen(buffB);
iovcnt = 2;
...
ret = wolfSSL_writev(ssl, iov, iovcnt);
// wrote “ret” bytes, or error if <= 0.

function wolfSSL_SNI_Status

unsigned char wolfSSL_SNI_Status(
    WOLFSSL * ssl,
    unsigned char type
)

This function gets the status of an SNI object.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
type the SNI type.

See:

TLSX_SNI_Status
TLSX_SNI_find
TLSX_Find

Return:

value This function returns the byte value of the SNI struct’s status member if the SNI is not NULL.
0 if the SNI object is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
#define AssertIntEQ(x, y) AssertInt(x, y, ==, !=)
…
Byte type = WOLFSSL_SNI_HOST_NAME;
char* request = (char*)&type;
AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type));
…

function wolfSSL_UseSecureRenegotiation

int wolfSSL_UseSecureRenegotiation(
    WOLFSSL * ssl
)

This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

TLSX_Find
TLSX_UseSecureRenegotiation

Return:

SSL_SUCCESS Successfully set secure renegotiation.
BAD_FUNC_ARG Returns error if ssl is null.
MEMORY_E Returns error if unable to allocate memory for secure renegotiation.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);

if(wolfSSL_UseSecureRenegotiation(ssl) != SSL_SUCCESS)
{
    // Error setting secure renegotiation
}

function wolfSSL_Rehandshake

int wolfSSL_Rehandshake(
    WOLFSSL * ssl
)

This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise if an unacceptable argument was passed in a subroutine.
SECURE_RENEGOTIATION_E returned if there was an error with renegotiating the handshake.
SSL_FATAL_ERROR returned if there was an error with the server or client configuration and the renegotiation could not be completed. See wolfSSL_negotiate().

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_Rehandshake(ssl) != SSL_SUCCESS){
    // There was an error and the rehandshake is not successful.
}

function wolfSSL_UseSessionTicket

int wolfSSL_UseSessionTicket(
    WOLFSSL * ssl
)

Force provided WOLFSSL structure to use session ticket. The constant HAVE_SESSION_TICKET should be defined and the constant NO_WOLFSSL_CLIENT should not be defined to use this function.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: TLSX_UseSessionTicket

Return:

SSL_SUCCESS Successfully set use session ticket.
BAD_FUNC_ARG Returned if ssl is null.
MEMORY_E Error allocating memory for setting session ticket.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);

if(wolfSSL_UseSessionTicket(ssl) != SSL_SUCCESS)
{
    // Error setting session ticket
}

function wolfSSL_get_SessionTicket

int wolfSSL_get_SessionTicket(
    WOLFSSL * ssl,
    unsigned char * buf,
    word32 * bufSz
)

This function copies the ticket member of the Session structure to the buffer.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
buf a byte pointer representing the memory buffer.
bufSz a word32 pointer representing the buffer size.

See:

Return:

SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if one of the arguments was NULL or if the bufSz argument was 0.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
byte* buf;
word32 bufSz;  // Initialize with buf size
…
if(wolfSSL_get_SessionTicket(ssl, buf, bufSz) <= 0){
    // Nothing was written to the buffer
} else {
    // the buffer holds the content from ssl->session->ticket
}

function wolfSSL_set_SessionTicket

int wolfSSL_set_SessionTicket(
    WOLFSSL * ssl,
    const unsigned char * buf,
    word32 bufSz
)

This function sets the ticket member of the WOLFSSL_SESSION structure within the WOLFSSL struct. The buffer passed into the function is copied to memory.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
buf a byte pointer that gets loaded into the ticket member of the session structure.
bufSz a word32 type that represents the size of the buffer.

See: wolfSSL_set_SessionTicket_cb

Return:

SSL_SUCCESS returned on successful execution of the function. The function returned without errors.
BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will also be thrown if the buf argument is NULL but the bufSz argument is not zero.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
byte* buffer; // File to load
word32 bufSz;
...
if(wolfSSL_KeepArrays(ssl, buffer, bufSz) != SSL_SUCCESS){
    // There was an error loading the buffer to memory.
}

function wolfSSL_PrintSessionStats

int wolfSSL_PrintSessionStats(
    void 
)

This function prints the statistics from the session.

Parameters:

none No parameters.

See: wolfSSL_get_session_stats

Return:

SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed.
BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument.
BAD_MUTEX_E returned if there was a mutex error in the subroutine.

Example

// You will need to have a session object to retrieve stats from.
if(wolfSSL_PrintSessionStats(void) != SSL_SUCCESS   ){
    // Did not print session stats
}

function wolfSSL_get_session_stats

int wolfSSL_get_session_stats(
    unsigned int * active,
    unsigned int * total,
    unsigned int * peak,
    unsigned int * maxSessions
)

This function gets the statistics for the session.

Parameters:

active a word32 pointer representing the total current sessions.
total a word32 pointer representing the total sessions.
peak a word32 pointer representing the peak sessions.
maxSessions a word32 pointer representing the maximum sessions.

See: wolfSSL_PrintSessionStats

Return:

SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed.
BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument.
BAD_MUTEX_E returned if there was a mutex error in the subroutine.

Example

int wolfSSL_PrintSessionStats(void){
…
ret = wolfSSL_get_session_stats(&totalSessionsNow,
&totalSessionsSeen, &peak, &maxSessions);
…
return ret;

function wolfSSL_BIO_set_fp

long wolfSSL_BIO_set_fp(
    WOLFSSL_BIO * bio,
    XFILE fp,
    int c
)

This is used to set the internal file pointer for a BIO.

Parameters:

bio WOLFSSL_BIO structure to set pair.
fp file pointer to set in bio.
c close file behavior flag.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_get_fp
wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully setting file pointer.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
XFILE fp;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
ret  = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE);
// check ret value

function wolfSSL_BIO_get_fp

long wolfSSL_BIO_get_fp(
    WOLFSSL_BIO * bio,
    XFILE * fp
)

This is used to get the internal file pointer for a BIO.

Parameters:

bio WOLFSSL_BIO structure to set pair.
fp file pointer to set in bio.

See:

wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

Return:

SSL_SUCCESS On successfully getting file pointer.
SSL_FAILURE If an error case was encountered.

Example

WOLFSSL_BIO* bio;
XFILE fp;
int ret;
bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
ret  = wolfSSL_BIO_get_fp(bio, &fp);
// check ret value

function wolfSSL_BIO_ctrl_pending

size_t wolfSSL_BIO_ctrl_pending(
    WOLFSSL_BIO * b
)

Gets the number of pending bytes to read. If BIO type is BIO_BIO then is the number to read from pair. If BIO contains an SSL object then is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY type then returns the size of memory buffer.

Parameters:

bio pointer to the WOLFSSL_BIO structure that has already been created.

See:

wolfSSL_BIO_make_bio_pair
wolfSSL_BIO_new

Return: >=0 number of pending bytes.

Example

WOLFSSL_BIO* bio;
int pending;
bio = wolfSSL_BIO_new();
…
pending = wolfSSL_BIO_ctrl_pending(bio);

function wolfSSL_set_jobject

int wolfSSL_set_jobject(
    WOLFSSL * ssl,
    void * objPtr
)

This function sets the jObjectRef member of the WOLFSSL structure.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
objPtr a void pointer that will be set to jObjectRef.

See: wolfSSL_get_jobject

Return:

SSL_SUCCESS returned if jObjectRef is properly set to objPtr.
SSL_FAILURE returned if the function did not properly execute and jObjectRef is not set.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new();
void* objPtr = &obj;
...
if(wolfSSL_set_jobject(ssl, objPtr)){
    // The success case
}

function wolfSSL_get_jobject

void * wolfSSL_get_jobject(
    WOLFSSL * ssl
)

This function returns the jObjectRef member of the WOLFSSL structure.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: wolfSSL_set_jobject

Return:

value If the WOLFSSL struct is not NULL, the function returns the jObjectRef value.
NULL returned if the WOLFSSL struct is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL(ctx);
...
void* jobject = wolfSSL_get_jobject(ssl);

if(jobject != NULL){
    // Success case
}

function wolfSSL_connect

int wolfSSL_connect(
    WOLFSSL * ssl
)

This function is called on the client side and initiates an SSL/TLS handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. 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_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS If successful.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
ret = wolfSSL_connect(ssl);
if (ret != SSL_SUCCESS) {
err = wolfSSL_get_error(ssl, ret);
printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_update_keys

int wolfSSL_update_keys(
    WOLFSSL * ssl
)

This function is called on a TLS v1.3 client or server wolfSSL to force the rollover of keys. A KeyUpdate message is sent to the peer and new keys are calculated for encryption. The peer will send back a KeyUpdate message and the new decryption keys will then be calculated. This function can only be called after a handshake has been completed.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See: wolfSSL_write

Return:

BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
WANT_WRITE if the writing is not ready.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_update_keys(ssl);
if (ret == WANT_WRITE) {
    // need to call again when I/O ready
}
else if (ret != WOLFSSL_SUCCESS) {
    // failed to send key update
}

function wolfSSL_key_update_response

int wolfSSL_key_update_response(
    WOLFSSL * ssl,
    int * required
)

This function is called on a TLS v1.3 client or server wolfSSL to determine whether a rollover of keys is in progress. When wolfSSL_update_keys() is called, a KeyUpdate message is sent and the encryption key is updated. The decryption key is updated when the response is received.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
required 0 when no key update response required. 1 when no key update response required.

See: wolfSSL_update_keys

Return:

0 on successful.
BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.

Example

int ret;
WOLFSSL* ssl;
int required;
...
ret = wolfSSL_key_update_response(ssl, &required);
if (ret != 0) {
    // bad parameters
}
if (required) {
    // encrypt Key updated, awaiting response to change decrypt key
}

function wolfSSL_request_certificate

int wolfSSL_request_certificate(
    WOLFSSL * ssl
)

This function requests a client certificate from the TLS v1.3 client. This is useful when a web server is serving some pages that require client authentication and others that don't. A maximum of 256 requests can be sent on a connection.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
WANT_WRITE if the writing is not ready.
SIDE_ERROR if called with a client.
NOT_READY_ERROR if called when the handshake is not finished.
POST_HAND_AUTH_ERROR if posthandshake authentication is disallowed.
MEMORY_E if dynamic memory allocation fails.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_request_certificate(ssl);
if (ret == WANT_WRITE) {
    // need to call again when I/O ready
}
else if (ret != WOLFSSL_SUCCESS) {
    // failed to request a client certificate
}

function wolfSSL_connect_TLSv13

int wolfSSL_connect_TLSv13(
    WOLFSSL * 
)

This function is called on the client side and initiates a TLS v1.3 handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. 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_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...

ret = wolfSSL_connect_TLSv13(ssl);
if (ret != SSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_accept_TLSv13

wolfSSL_accept_TLSv13(
    WOLFSSL * ssl
)

This function is called on the server side and waits for a SSL/TLS client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. 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_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred. Call this function when expecting a TLS v1.3 connection though older version ClientHello messages are supported.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...

ret = wolfSSL_accept_TLSv13(ssl);
if (ret != SSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_write_early_data

int wolfSSL_write_early_data(
    WOLFSSL * ssl,
    const void * data,
    int sz,
    int * outSz
)

This function writes early data to the server on resumption. Call this function instead of wolfSSL_connect() or wolfSSL_connect_TLSv13() to connect to the server and send the data in the handshake. This function is only used with clients.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
data the buffer holding the early data to write to server.
sz the amount of early data to write in bytes.
outSz the amount of early data written in bytes.

See:

Return:

BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or not using TLSv1.3.
SIDE_ERROR if called with a server.
WOLFSSL_FATAL_ERROR if the connection is not made.
WOLFSSL_SUCCESS if successful.

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
byte earlyData[] = { early data };
int outSz;
char buffer[80];
...

ret = wolfSSL_write_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
if (ret != WOLFSSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
    goto err_label;
}
if (outSz < sizeof(earlyData)) {
    // not all early data was sent
}
ret = wolfSSL_connect_TLSv13(ssl);
if (ret != SSL_SUCCESS) {
    err = wolfSSL_get_error(ssl, ret);
    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}

function wolfSSL_read_early_data

int wolfSSL_read_early_data(
    WOLFSSL * ssl,
    void * data,
    int sz,
    int * outSz
)

This function reads any early data from a client on resumption. Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13() to accept a client and read any early data in the handshake. The function should be invoked until wolfSSL_is_init_finished() returns true. Early data may be sent by the client in multiple messages. If there is no early data then the handshake will be processed as normal. This function is only used with servers.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
data a buffer to hold the early data read from client.
sz size of the buffer in bytes.
outSz number of bytes of early data read.

See:

Return:

BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or not using TLSv1.3.
SIDE_ERROR if called with a client.
WOLFSSL_FATAL_ERROR if accepting a connection fails.
Number of early data bytes read (may be zero).

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
byte earlyData[128];
int outSz;
char buffer[80];
...

do {
    ret = wolfSSL_read_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
    if (ret < 0) {
        err = wolfSSL_get_error(ssl, ret);
        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
    }
    if (outSz > 0) {
        // early data available
    }
} while (!wolfSSL_is_init_finished(ssl));

function wolfSSL_GetIOReadCtx

void * wolfSSL_GetIOReadCtx(
    WOLFSSL * ssl
)

This function returns the IOCB_ReadCtx member of the WOLFSSL struct.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

pointer This function returns a void pointer to the IOCB_ReadCtx member of the WOLFSSL structure.
NULL returned if the WOLFSSL struct is NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
void* ioRead;
...
ioRead = wolfSSL_GetIOReadCtx(ssl);
if(ioRead == NULL){
    // Failure case. The ssl object was NULL.
}

function wolfSSL_GetIOWriteCtx

void * wolfSSL_GetIOWriteCtx(
    WOLFSSL * ssl
)

This function returns the IOCB_WriteCtx member of the WOLFSSL structure.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

See:

Return:

pointer This function returns a void pointer to the IOCB_WriteCtx member of the WOLFSSL structure.
NULL returned if the WOLFSSL struct is NULL.

Example

WOLFSSL* ssl;
void* ioWrite;
...
ioWrite = wolfSSL_GetIOWriteCtx(ssl);
if(ioWrite == NULL){
    // The function returned NULL.
}

function wolfSSL_SetIO_NetX

void wolfSSL_SetIO_NetX(
    WOLFSSL * ssl,
    NX_TCP_SOCKET * nxsocket,
    ULONG waitoption
)

This function sets the nxSocket and nxWait members of the nxCtx struct within the WOLFSSL structure.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
nxSocket a pointer to type NX_TCP_SOCKET that is set to the nxSocket member of the nxCTX structure.
waitOption a ULONG type that is set to the nxWait member of the nxCtx structure.

See:

set_fd
NetX_Send
NetX_Receive

Return: none No returns.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
NX_TCP_SOCKET* nxSocket;
ULONG waitOption;
…
if(ssl != NULL || nxSocket != NULL || waitOption <= 0){
wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption);
} else {
    // You need to pass in good parameters.
}

Updated on 2024-11-22 at 01:12:39 +0000