wolfSSL Connection, Session, and I/O

Functions
WOLFSSL_API 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).
WOLFSSL_API char *	wolfSSL_get_cipher_list (int priority)
	Get the name of cipher at priority level passed in.
WOLFSSL_API int	wolfSSL_get_ciphers (char *, int)
	This function gets the ciphers enabled in wolfSSL.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API int	wolfSSL_write (WOLFSSL *, const void *, int)
	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(). 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.
WOLFSSL_API int	wolfSSL_read (WOLFSSL *, void *, int)
	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.
WOLFSSL_API int	wolfSSL_peek (WOLFSSL *, void *, int)
	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.
WOLFSSL_API 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.
WOLFSSL_API int	wolfSSL_send (WOLFSSL *, const void *, 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.
WOLFSSL_API int	wolfSSL_recv (WOLFSSL *, void *, 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.
WOLFSSL_API int	wolfSSL_get_alert_history (WOLFSSL *, WOLFSSL_ALERT_HISTORY *)
	This function gets the alert history.
WOLFSSL_API WOLFSSL_SESSION *	wolfSSL_get_session (WOLFSSL *)
	This function returns a pointer to the current session (WOLFSSL_SESSION) used in ssl. The WOLFSSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default.
WOLFSSL_API void	wolfSSL_flush_sessions (WOLFSSL_CTX *, long)
	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.
WOLFSSL_API int	wolfSSL_GetSessionIndex (WOLFSSL *ssl)
	This function gets the session index of the WOLFSSL structure.
WOLFSSL_API int	wolfSSL_GetSessionAtIndex (int index, WOLFSSL_SESSION *session)
	This function gets the session at specified index of the session cache and copies it into memory. The WOLFSSL_SESSION structure holds the session information.
WOLFSSL_API WOLFSSL_X509_CHAIN *	wolfSSL_SESSION_get_peer_chain (WOLFSSL_SESSION *session)
	Returns the peer certificate chain from the WOLFSSL_SESSION struct.
WOLFSSL_API 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().
WOLFSSL_API int	wolfSSL_save_session_cache (const char *)
	This function persists the session cache to file. It doesn’t use memsave because of additional memory use.
WOLFSSL_API int	wolfSSL_restore_session_cache (const char *)
	This function restores the persistent session cache from file. It does not use memstore because of additional memory use.
WOLFSSL_API int	wolfSSL_memsave_session_cache (void *, int)
	This function persists session cache to memory.
WOLFSSL_API int	wolfSSL_memrestore_session_cache (const void *, int)
	This function restores the persistent session cache from memory.
WOLFSSL_API int	wolfSSL_get_session_cache_memsize (void)
	This function returns how large the session cache save buffer should be.
WOLFSSL_API int	wolfSSL_session_reused (WOLFSSL *)
	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.
WOLFSSL_API const char *	wolfSSL_get_version (WOLFSSL *)
	Returns the SSL version being used as a string.
WOLFSSL_API int	wolfSSL_get_current_cipher_suite (WOLFSSL *ssl)
	Returns the current cipher suit an ssl session is using.
WOLFSSL_API WOLFSSL_CIPHER *	wolfSSL_get_current_cipher (WOLFSSL *)
	This function returns a pointer to the current cipher in the ssl session.
WOLFSSL_API 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.
WOLFSSL_API const char *	wolfSSL_get_cipher (WOLFSSL *)
	This function matches the cipher suite in the SSL object with the available suites.
WOLFSSL_API 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.
WOLFSSL_API long	wolfSSL_BIO_set_fd (WOLFSSL_BIO *b, int fd, int flag)
	Sets the file descriptor for bio to use.
WOLFSSL_API int	wolfSSL_BIO_set_close (WOLFSSL_BIO *b, long flag)
	Sets the close flag, used to indicate that the i/o stream should be closed when the BIO is freed.
WOLFSSL_API WOLFSSL_BIO_METHOD *	wolfSSL_BIO_s_socket (void)
	This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API int	wolfSSL_BIO_ctrl_reset_read_request (WOLFSSL_BIO *b)
	This is used to set the read request flag back to 0.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API long	wolfSSL_BIO_get_mem_ptr (WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m)
	This is a getter function for WOLFSSL_BIO memory pointer.
WOLFSSL_API const char *	wolfSSL_lib_version (void)
	This function returns the current library version.
WOLFSSL_API word32	wolfSSL_lib_version_hex (void)
	This function returns the current library version in hexadecimal notation.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API 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.
WOLFSSL_API unsigned char	wolfSSL_SNI_Status (WOLFSSL *ssl, unsigned char type)
	This function gets the status of an SNI object.
WOLFSSL_API int	wolfSSL_UseSecureRenegotiation (WOLFSSL *ssl)
	This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended.
WOLFSSL_API int	wolfSSL_Rehandshake (WOLFSSL *ssl)
	This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality.
WOLFSSL_API 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.
WOLFSSL_API int	wolfSSL_get_SessionTicket (WOLFSSL *, unsigned char *, word32 *)
	This function copies the ticket member of the Session structure to the buffer.
WOLFSSL_API int	wolfSSL_set_SessionTicket (WOLFSSL *, const unsigned char *, word32)
	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.
WOLFSSL_API int	wolfSSL_isQSH (WOLFSSL *ssl)
	Checks if QSH is used in the supplied SSL session.
WOLFSSL_API int	wolfSSL_PrintSessionStats (void)
	This function prints the statistics from the session.
WOLFSSL_API 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.
WOLFSSL_API long	wolfSSL_BIO_set_fp (WOLFSSL_BIO *bio, XFILE fp, int c)
	This is used to set the internal file pointer for a BIO.
WOLFSSL_API long	wolfSSL_BIO_get_fp (WOLFSSL_BIO *bio, XFILE *fp)
	This is used to get the internal file pointer for a BIO.
WOLFSSL_API 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.
WOLFSSL_API int	wolfSSL_set_jobject (WOLFSSL *ssl, void *objPtr)
	This function sets the jObjectRef member of the WOLFSSL structure.
WOLFSSL_API void *	wolfSSL_get_jobject (WOLFSSL *ssl)
	This function returns the jObjectRef member of the WOLFSSL structure.
WOLFSSL_API void *	wolfSSL_GetIOReadCtx (WOLFSSL *ssl)
	This function returns the IOCB_ReadCtx member of the WOLFSSL struct.
WOLFSSL_API void *	wolfSSL_GetIOWriteCtx (WOLFSSL *ssl)
	This function returns the IOCB_WriteCtx member of the WOLFSSL structure.
WOLFSSL_API 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.

Detailed Description

Function Documentation

wolfSSL_accept()

WOLFSSL_API int wolfSSL_accept

(

WOLFSSL *

ssl

)

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

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

WOLFSSL_API int wolfSSL_BIO_ctrl_reset_read_request

(

WOLFSSL_BIO *

b

)

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

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

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

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

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

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

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

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

WOLFSSL_API 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_API 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()

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

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

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

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

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

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

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

WOLFSSL_API 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_cert()

WOLFSSL_API 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_flush_sessions()

WOLFSSL_API 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_get_session

wolfSSL_set_session

wolfSSL_get_alert_history()

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

WOLFSSL_API const char * wolfSSL_get_cipher

(

WOLFSSL *

ssl

)

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

WOLFSSL_API 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

Get the name of cipher at priority level passed in.

wolfSSL_get_cipher_name()

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

WOLFSSL_API 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_API 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()

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

WOLFSSL_API int wolfSSL_get_fd

(

const WOLFSSL *

ssl

)

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

WOLFSSL_API 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_API WOLFSSL_SESSION * wolfSSL_get_session

(

WOLFSSL *

ssl

)

This function returns a pointer to the current session (WOLFSSL_SESSION) used in ssl. The WOLFSSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default.

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 = 0;
WOLFSSL_SESSION* session = 0;
...
session = wolfSSL_get_session(ssl);
if (session == NULL) {
    // failed to get session pointer
}
...

See also

wolfSSL_set_session

wolfSSL_get_session_cache_memsize()

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

WOLFSSL_API 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

get_locked_session_stats

wolfSSL_PrintSessionStats

wolfSSL_get_SessionTicket()

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

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

WOLFSSL_API 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_CTX structure is not NULL. By default the value is 9.

BAD_FUNC_ARG returned if the WOLFSSL_CTX 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()

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

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

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

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

WOLFSSL_API 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_isQSH()

WOLFSSL_API int wolfSSL_isQSH

(

WOLFSSL *

ssl

)

Checks if QSH is used in the supplied SSL session.

Returns

0 Not used

1 Is used

Parameters

ssl	Pointer to 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_isQSH(ssl) == 1)
{
    // SSL is using QSH.
}

See also

wolfSSL_UseSupportedQSH

wolfSSL_lib_version()

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

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

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

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

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

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

WOLFSSL_API int wolfSSL_pending

(

WOLFSSL *

ssl

)

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

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

WOLFSSL_API 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_recv()

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

WOLFSSL_API 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_restore_session_cache()

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

WOLFSSL_API 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

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

WOLFSSL_API 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_API 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

get_locked_session_stats

wolfSSL_GetSessionAtIndex

wolfSSL_GetSessionIndex

AddSession

wolfSSL_session_reused()

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

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

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

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

WOLFSSL_API 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_UseSecureRenegotiation()

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

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

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

WOLFSSL_API 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