wolfSSL Connection, Session, and I/O

Functions
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). More...
char *	wolfSSL_get_cipher_list (int priority)
	Get the name of cipher at priority level passed in. More...
int	wolfSSL_get_ciphers (char *buf, int len)
	This function gets the ciphers enabled in wolfSSL. More...
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. More...
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. More...
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. More...
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 invokations 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. More...
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_root>/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. More...
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_root>/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. More...
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. More...
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. More...
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_root>/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. More...
int	wolfSSL_get_alert_history (WOLFSSL *ssl, WOLFSSL_ALERT_HISTORY *h)
	This function gets the alert history. More...
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. More...
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. More...
int	wolfSSL_GetSessionIndex (WOLFSSL *ssl)
	This function gets the session index of the WOLFSSL structure. More...
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. More...
WOLFSSL_X509_CHAIN *	wolfSSL_SESSION_get_peer_chain (WOLFSSL_SESSION *session)
	Returns the peer certificate chain from the WOLFSSL_SESSION struct. More...
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(). More...
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. More...
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. More...
int	wolfSSL_memsave_session_cache (void *mem, int sz)
	This function persists session cache to memory. More...
int	wolfSSL_memrestore_session_cache (const void *mem, int sz)
	This function restores the persistent session cache from memory. More...
int	wolfSSL_get_session_cache_memsize (void)
	This function returns how large the session cache save buffer should be. More...
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. More...
const char *	wolfSSL_get_version (WOLFSSL *ssl)
	Returns the SSL version being used as a string. More...
int	wolfSSL_get_current_cipher_suite (WOLFSSL *ssl)
	Returns the current cipher suit an ssl session is using. More...
WOLFSSL_CIPHER *	wolfSSL_get_current_cipher (WOLFSSL *ssl)
	This function returns a pointer to the current cipher in the ssl session. More...
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. More...
const char *	wolfSSL_get_cipher (WOLFSSL *)
	This function matches the cipher suite in the SSL object with the available suites. More...
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. More...
long	wolfSSL_BIO_set_fd (WOLFSSL_BIO *b, int fd, int flag)
	Sets the file descriptor for bio to use. More...
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. More...
WOLFSSL_BIO_METHOD *	wolfSSL_BIO_s_socket (void)
	This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD. More...
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. More...
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. More...
int	wolfSSL_BIO_ctrl_reset_read_request (WOLFSSL_BIO *bio)
	This is used to set the read request flag back to 0. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
long	wolfSSL_BIO_get_mem_ptr (WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m)
	This is a getter function for WOLFSSL_BIO memory pointer. More...
const char *	wolfSSL_lib_version (void)
	This function returns the current library version. More...
word32	wolfSSL_lib_version_hex (void)
	This function returns the current library version in hexadecimal notation. More...
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. More...
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. More...
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. More...
unsigned char	wolfSSL_SNI_Status (WOLFSSL *ssl, unsigned char type)
	This function gets the status of an SNI object. More...
int	wolfSSL_UseSecureRenegotiation (WOLFSSL *ssl)
	This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended. More...
int	wolfSSL_Rehandshake (WOLFSSL *ssl)
	This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality. More...
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. More...
int	wolfSSL_get_SessionTicket (WOLFSSL *ssl, unsigned char *buf, word32 *bufSz)
	This function copies the ticket member of the Session structure to the buffer. More...
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. More...
int	wolfSSL_PrintSessionStats (void)
	This function prints the statistics from the session. More...
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. More...
long	wolfSSL_BIO_set_fp (WOLFSSL_BIO *bio, XFILE fp, int c)
	This is used to set the internal file pointer for a BIO. More...
long	wolfSSL_BIO_get_fp (WOLFSSL_BIO *bio, XFILE *fp)
	This is used to get the internal file pointer for a BIO. More...
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. More...
int	wolfSSL_set_jobject (WOLFSSL *ssl, void *objPtr)
	This function sets the jObjectRef member of the WOLFSSL structure. More...
void *	wolfSSL_get_jobject (WOLFSSL *ssl)
	This function returns the jObjectRef member of the WOLFSSL structure. More...
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. More...
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. More...
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. More...
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. More...
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. More...
	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. More...
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. More...
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 messsages. If there is no early data then the handshake will be processed as normal. This function is only used with servers. More...
void *	wolfSSL_GetIOReadCtx (WOLFSSL *ssl)
	This function returns the IOCB_ReadCtx member of the WOLFSSL struct. More...
void *	wolfSSL_GetIOWriteCtx (WOLFSSL *ssl)
	This function returns the IOCB_WriteCtx member of the WOLFSSL structure. More...
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. More...

Detailed Description

Function Documentation

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.

Returns

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().

Parameters

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

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));
}

See also

wolfSSL_get_error

wolfSSL_connect

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.

Returns

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().

Parameters

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

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));
}

See also

wolfSSL_get_error

wolfSSL_connect_TLSv13

wolfSSL_connect

wolfSSL_accept_TLSv13

wolfSSL_accept

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.

Returns

>=0 number of pending bytes.

Parameters

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

Example

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

See also

wolfSSL_BIO_make_bio_pair

wolfSSL_BIO_new

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.

Returns

SSL_SUCCESS On successfully setting value.

SSL_FAILURE If an error case was encountered.

Parameters

bio	WOLFSSL_BIO structure to set read request flag.

Example

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

See also

wolfSSL_BIO_new, wolfSSL_BIO_s_mem

wolfSSL_BIO_new, wolfSSL_BIO_free

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.

Returns

SSL_SUCCESS On successfully getting file pointer.

SSL_FAILURE If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_set_fp

wolfSSL_BIO_free

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.

Returns

size On success the size of the buffer is returned

SSL_FATAL_ERROR If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_set_fp

wolfSSL_BIO_free

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.

Returns

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

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.

Example

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

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.

Returns

SSL_SUCCESS On successfully pairing the two bios.

SSL_FAILURE If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_free

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.

Returns

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

WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1

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.

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_nwrite

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.

Returns

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

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_nwrite0

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.

Returns

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

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_free

wolfSSL_BIO_nread

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.

Returns

0 On successfully resetting the bio.

WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset.

Parameters

bio	WOLFSSL_BIO structure to reset.

Example

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_free

wolfSSL_BIO_s_socket()

WOLFSSL_BIO_METHOD* wolfSSL_BIO_s_socket

(

void

)

This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.

Returns

WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure that is a socket type

Parameters

none	No parameters.

Example

WOLFSSL_BIO* bio;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

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.

Returns

0 On successfully seeking.

-1 If an error case was encountered.

Parameters

bio	WOLFSSL_BIO structure to set.
ofs	offset into file.

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_set_fp

wolfSSL_BIO_free

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.

Returns

SSL_SUCCESS(1) upon success.

Parameters

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

Example

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_free

wolfSSL_BIO_set_fd()

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

Sets the file descriptor for bio to use.

Returns

SSL_SUCCESS(1) upon success.

Parameters

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

Example

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_free

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.

Returns

SSL_SUCCESS On successfully setting file pointer.

SSL_FAILURE If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_get_fp

wolfSSL_BIO_free

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.

Returns

0 returned on completion

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_set_fp

wolfSSL_BIO_free

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.

Returns

SSL_SUCCESS On successfully setting the write buffer.

SSL_FAILURE If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_mem

wolfSSL_BIO_free

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.

Returns

SSL_SUCCESS On successfully opening and setting file.

SSL_FAILURE If an error case was encountered.

Parameters

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

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

See also

wolfSSL_BIO_new

wolfSSL_BIO_s_file

wolfSSL_BIO_set_fp

wolfSSL_BIO_free

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.

Returns

string This function returns the string representation of the matched cipher suite.

none It will return “None” if there are no suites matched.

Parameters

cipher

a constant pointer to a WOLFSSL_CIPHER structure.

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
}

See also

wolfSSL_get_cipher

wolfSSL_get_current_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_cipher_name

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.

Returns

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().

Parameters

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

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));
}

See also

wolfSSL_get_error

wolfSSL_accept

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.

Returns

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().

Parameters

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

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));
}

See also

wolfSSL_get_error

wolfSSL_connect

wolfSSL_accept

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.

Returns

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().

Parameters

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

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));
}

See also

wolfSSL_get_error

wolfSSL_connect

wolfSSL_accept_TLSv13

wolfSSL_accept

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.

Returns

none No returns.

Parameters

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

Example

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

See also

wolfSSL_get1_session

wolfSSL_set_session

wolfSSL_get_alert_history()

int wolfSSL_get_alert_history	(	WOLFSSL *	ssl,
		WOLFSSL_ALERT_HISTORY *	h
	)

This function gets the alert history.

Returns

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.

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.

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

See also

wolfSSL_get_error

wolfSSL_get_cipher()

const char* wolfSSL_get_cipher

(

WOLFSSL *

)

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

Returns

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

Parameters

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

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

See also

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_get_cipher_list()

char* wolfSSL_get_cipher_list

(

int

priority

)

Get the name of cipher at priority level passed in.

Returns

string Success

0 Priority is either out of bounds or not valid.

Parameters

priority

Integer representing the priority level of a cipher.

Example

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

See also

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

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.

Returns

string This function returns the string representation of the cipher suite that was matched.

NULL error or cipher not found.

Parameters

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

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);
}

See also

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_ciphers()

int wolfSSL_get_ciphers	(	char *	buf,
		int	len
	)

This function gets the ciphers enabled in wolfSSL.

Returns

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.

Parameters

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

Example

static void ShowCiphers(void){
char* ciphers;
int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers));
 
if(ret == SSL_SUCCES){
        printf(“%s\n”, ciphers);
    }
}

See also

GetCipherNames

wolfSSL_get_cipher_list

ShowCiphers

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.

Returns

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.

Parameters

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

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
}

See also

wolfSSL_get_cipher

wolfSSL_get_cipher_name_internal

wolfSSL_get_cipher_name

wolfSSL_get_current_cipher_suite()

int wolfSSL_get_current_cipher_suite

(

WOLFSSL *

ssl

)

Returns the current cipher suit an ssl session is using.

Returns

ssl->options.cipherSuite An integer representing the current cipher suite.

0 The ssl session provided is null.

Parameters

ssl	The SSL session to check.

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
}

See also

wolfSSL_CIPHER_get_name

wolfSSL_get_current_cipher

wolfSSL_get_cipher_list

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.

Returns

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

Parameters

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

Example

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

See also

wolfSSL_set_fd

wolfSSL_get_jobject()

void* wolfSSL_get_jobject

(

WOLFSSL *

ssl

)

This function returns the jObjectRef member of the WOLFSSL structure.

Returns

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

NULL returned if the WOLFSSL struct is NULL.

Parameters

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

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL(ctx);
...
void* jobject = wolfSSL_get_jobject(ssl);
 
if(jobject != NULL){
    // Success case
}

See also

wolfSSL_set_jobject

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.

Returns

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.

Parameters

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

Example

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

See also

wolfSSL_get1_session

wolfSSL_set_session

wolfSSL_get_session_cache_memsize()

int wolfSSL_get_session_cache_memsize

(

void

)

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

Returns

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

Parameters

none	No parameters.

Example

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

See also

wolfSSL_memrestore_session_cache

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.

Returns

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.

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.

Example

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

See also

wolfSSL_PrintSessionStats

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.

Returns

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.

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.

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
}

See also

wolfSSL_UseSessionTicket

wolfSSL_set_SessionTicket

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.

Returns

0 underlying I/O is blocking.

1 underlying I/O is non-blocking.

Parameters

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

Example

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

See also

wolfSSL_set_session

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

Returns

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.

Parameters

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

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
}

See also

wolfSSL_CTX_get_verify_depth

wolfSSL_get_version()

const char* wolfSSL_get_version

(

WOLFSSL *

ssl

)

Returns the SSL version being used as a string.

Returns

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

Parameters

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

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));

See also

wolfSSL_lib_version

wolfSSL_GetIOReadCtx()

void* wolfSSL_GetIOReadCtx

(

WOLFSSL *

ssl

)

This function returns the IOCB_ReadCtx member of the WOLFSSL struct.

Returns

pointer This function returns a void pointer to the IOCB_ReadCtx member of the WOLFSSL structure.

NULL returned if the WOLFSSL struct is NULL.

Parameters

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

Example

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

See also

wolfSSL_GetIOWriteCtx

wolfSSL_SetIOReadFlags

wolfSSL_SetIOWriteCtx

wolfSSL_SetIOReadCtx

wolfSSL_CTX_SetIOSend

wolfSSL_GetIOWriteCtx()

void* wolfSSL_GetIOWriteCtx

(

WOLFSSL *

ssl

)

This function returns the IOCB_WriteCtx member of the WOLFSSL structure.

Returns

pointer This function returns a void pointer to the IOCB_WriteCtx member of the WOLFSSL structure.

NULL returned if the WOLFSSL struct is NULL.

Parameters

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

Example

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

See also

wolfSSL_GetIOReadCtx

wolfSSL_SetIOWriteCtx

wolfSSL_SetIOReadCtx

wolfSSL_CTX_SetIOSend

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.

Returns

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.

Parameters

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

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

See also

UnLockMutex

LockMutex

wolfSSL_GetSessionIndex

wolfSSL_GetSessionIndex()

int wolfSSL_GetSessionIndex

(

WOLFSSL *

ssl

)

This function gets the session index of the WOLFSSL structure.

Returns

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

Parameters

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

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

See also

wolfSSL_GetSessionAtIndex

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

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

Returns

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
}

See also

wolfSSL_update_keys

wolfSSL_lib_version()

const char* wolfSSL_lib_version

(

void

)

This function returns the current library version.

Returns

LIBWOLFSSL_VERSION_STRING a const char pointer defining the version.

Parameters

none	No parameters.

Example

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

See also

word32_wolfSSL_lib_version_hex

wolfSSL_lib_version_hex()

word32 wolfSSL_lib_version_hex

(

void

)

This function returns the current library version in hexadecimal notation.

Returns

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

Parameters

none	No parameters.

Example

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

See also

wolfSSL_lib_version

wolfSSL_memrestore_session_cache()

int wolfSSL_memrestore_session_cache	(	const void *	mem,
		int	sz
	)

This function restores the persistent session cache from memory.

Returns

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.

Parameters

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

Example

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

See also

wolfSSL_save_session_cache

wolfSSL_memsave_session_cache()

int wolfSSL_memsave_session_cache	(	void *	mem,
		int	sz
	)

This function persists session cache to memory.

Returns

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.

Parameters

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

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
}

See also

XMEMCPY

wolfSSL_get_session_cache_memsize

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.

Returns

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.

Parameters

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

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);
...
}
...

See also

SSL_connect

SSL_accept

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_root>/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.

Returns

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

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.

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”
}

See also

wolfSSL_read

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().

Returns

int This function returns the number of bytes pending.

Parameters

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

Example

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

See also

wolfSSL_recv

wolfSSL_read

wolfSSL_peek

wolfSSL_PrintSessionStats()

int wolfSSL_PrintSessionStats

(

void

)

This function prints the statistics from the session.

Returns

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.

Parameters

none	No parameters.

Example

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

See also

wolfSSL_get_session_stats

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_root>/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.

Returns

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

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.

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().

See also

wolfSSL_recv

wolfSSL_write

wolfSSL_peek

wolfSSL_pending

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 messsages. If there is no early data then the handshake will be processed as normal. This function is only used with servers.

Parameters

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

Returns

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));

See also

wolfSSL_write_early_data

wolfSSL_accept

wolfSSL_accept_TLSv13

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_root>/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.

Returns

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

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.

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”
}

See also

wolfSSL_read

wolfSSL_write

wolfSSL_peek

wolfSSL_pending

wolfSSL_Rehandshake()

int wolfSSL_Rehandshake

(

WOLFSSL *

ssl

)

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

Returns

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().

Parameters

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

Example

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

See also

wolfSSL_negotiate

wc_InitSha512

wc_InitSha384

wc_InitSha256

wc_InitSha

wc_InitMd5

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

[in,out]

ssl

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

Returns

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
}

See also

wolfSSL_allow_post_handshake_auth

wolfSSL_write

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.

Returns

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.

Parameters

fname

a constant char pointer file input that will be read.

Example

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

See also

XFREAD

XFOPEN

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.

Returns

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.

Parameters

fname

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

Example

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

See also

XFWRITE

wolfSSL_restore_session_cache

wolfSSL_memrestore_session_cache

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.

Returns

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

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.

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
}

See also

wolfSSL_write

wolfSSL_read

wolfSSL_recv

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.

Returns

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

Parameters

session

a pointer to a WOLFSSL_SESSION structure.

Example

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

See also

wolfSSL_GetSessionAtIndex

wolfSSL_GetSessionIndex

AddSession

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.

Returns

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

Parameters

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

Example

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

See also

wolfSSL_SESSION_free

wolfSSL_GetSessionIndex

wolfSSL_memsave_session_cache

wolfSSL_set_jobject()

int wolfSSL_set_jobject	(	WOLFSSL *	ssl,
		void *	objPtr
	)

This function sets the jObjectRef member of the WOLFSSL structure.

Returns

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.

Parameters

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

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
}

See also

wolfSSL_get_jobject

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.

Returns

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.

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.

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

See also

wolfSSL_set_SessionTicket_cb

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.

Returns

none No returns.

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.

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

See also

set_fd

NetX_Send

NetX_Receive

wolfSSL_SNI_Status()

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

This function gets the status of an SNI object.

Returns

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.

Parameters

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

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));
…

See also

TLSX_SNI_Status

TLSX_SNI_find

TLSX_Find

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

[in,out]

ssl

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

Returns

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
}

See also

wolfSSL_write

wolfSSL_UseSecureRenegotiation()

int wolfSSL_UseSecureRenegotiation

(

WOLFSSL *

ssl

)

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

Returns

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.

Parameters

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

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
}

See also

TLSX_Find

TLSX_UseSecureRenegotiation

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.

Returns

SSL_SUCCESS Successfully set use session ticket.

BAD_FUNC_ARG Returned if ssl is null.

MEMORY_E Error allocating memory for setting session ticket.

Parameters

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

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
}

See also

TLSX_UseSessionTicket

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

Returns

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

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

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()
}

See also

wolfSSL_send

wolfSSL_read

wolfSSL_recv

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

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

Returns

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));
}

See also

wolfSSL_read_early_data

wolfSSL_connect

wolfSSL_connect_TLSv13

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.

Returns

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

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.

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.

See also

wolfSSL_write