Functions
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). More...
 
WOLFSSL_API char * wolfSSL_get_cipher_list (int priority)
 Get the name of cipher at priority level passed in. More...
 
WOLFSSL_API int wolfSSL_get_ciphers (char *, int)
 This function gets the ciphers enabled in wolfSSL. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_get_alert_history (WOLFSSL *, WOLFSSL_ALERT_HISTORY *)
 This function gets the alert history. More...
 
WOLFSSL_API WOLFSSL_SESSIONwolfSSL_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. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_GetSessionIndex (WOLFSSL *ssl)
 This function gets the session index of the WOLFSSL structure. More...
 
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. More...
 
WOLFSSL_API WOLFSSL_X509_CHAINwolfSSL_SESSION_get_peer_chain (WOLFSSL_SESSION *session)
 Returns the peer certificate chain from the WOLFSSL_SESSION struct. More...
 
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(). More...
 
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. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_memsave_session_cache (void *, int)
 This function persists session cache to memory. More...
 
WOLFSSL_API int wolfSSL_memrestore_session_cache (const void *, int)
 This function restores the persistent session cache from memory. More...
 
WOLFSSL_API int wolfSSL_get_session_cache_memsize (void)
 This function returns how large the session cache save buffer should be. More...
 
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. More...
 
WOLFSSL_API const char * wolfSSL_get_version (WOLFSSL *)
 Returns the SSL version being used as a string. More...
 
WOLFSSL_API int wolfSSL_get_current_cipher_suite (WOLFSSL *ssl)
 Returns the current cipher suit an ssl session is using. More...
 
WOLFSSL_API WOLFSSL_CIPHERwolfSSL_get_current_cipher (WOLFSSL *)
 This function returns a pointer to the current cipher in the ssl session. More...
 
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. More...
 
WOLFSSL_API const char * wolfSSL_get_cipher (WOLFSSL *)
 This function matches the cipher suite in the SSL object with the available suites. More...
 
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. More...
 
WOLFSSL_API long wolfSSL_BIO_set_fd (WOLFSSL_BIO *b, int fd, int flag)
 Sets the file descriptor for bio to use. More...
 
WOLFSSL_API WOLFSSL_BIO_METHODwolfSSL_BIO_s_socket (void)
 This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD. More...
 
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. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_BIO_ctrl_reset_read_request (WOLFSSL_BIO *b)
 This is used to set the read request flag back to 0. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
WOLFSSL_API const char * wolfSSL_lib_version (void)
 This function returns the current library version. More...
 
WOLFSSL_API unsigned int wolfSSL_lib_version_hex (void)
 This function returns the current library version in hexadecimal notation. More...
 
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. More...
 
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. More...
 
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. More...
 
WOLFSSL_API unsigned char wolfSSL_SNI_Status (WOLFSSL *ssl, unsigned char type)
 This function gets the status of an SNI object. More...
 
WOLFSSL_API int wolfSSL_UseSecureRenegotiation (WOLFSSL *ssl)
 This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended. More...
 
WOLFSSL_API int wolfSSL_Rehandshake (WOLFSSL *ssl)
 This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_get_SessionTicket (WOLFSSL *, unsigned char *, unsigned int *)
 This function copies the ticket member of the Session structure to the buffer. More...
 
WOLFSSL_API int wolfSSL_set_SessionTicket (WOLFSSL *, const unsigned char *, unsigned int)
 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...
 
WOLFSSL_API int wolfSSL_isQSH (WOLFSSL *ssl)
 Checks if QSH is used in the supplied SSL session. More...
 
WOLFSSL_API int wolfSSL_PrintSessionStats (void)
 This function prints the statistics from the session. More...
 
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. More...
 
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. More...
 
WOLFSSL_API long wolfSSL_BIO_get_fp (WOLFSSL_BIO *bio, XFILE *fp)
 This is used to get the internal file pointer for a BIO. More...
 
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. More...
 
WOLFSSL_API int wolfSSL_set_jobject (WOLFSSL *ssl, void *objPtr)
 This function sets the jObjectRef member of the WOLFSSL structure. More...
 
WOLFSSL_API 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...
 
WOLFSSL_API void * wolfSSL_GetIOReadCtx (WOLFSSL *ssl)
 This function returns the IOCB_ReadCtx member of the WOLFSSL struct. More...
 
WOLFSSL_API void * wolfSSL_GetIOWriteCtx (WOLFSSL *ssl)
 This function returns the IOCB_WriteCtx member of the WOLFSSL structure. More...
 
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. More...
 

Detailed Description

Function Documentation

◆ wolfSSL_accept()

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.

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
ssla 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
biopointer to the WOLFSSL_BIO structure that has already been created.

Example

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
bioWOLFSSL_BIO structure to set read request flag.

Example

int ret;
...
// 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
bioWOLFSSL_BIO structure to set pair.
fpfile pointer to set in bio.

Example

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
bioWOLFSSL_BIO structure to get memory buffer of.
pbyte pointer to set to memory buffer.

Example

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
biopointer to the WOLFSSL_BIO structure for getting memory pointer.
ptrstructure that is currently a char*. Is set to point to bio’s memory.

Example

// setup bio
//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
b1WOLFSSL_BIO structure to set pair.
b2second WOLFSSL_BIO structure to complete pair.

Example

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
bioWOLFSSL_BIO structure to read from.
bufpointer to set at beginning of read array.
numnumber of bytes to try and read.

Example

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
bioWOLFSSL_BIO structure to read from.
bufpointer to set at beginning of read array.

Example

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
bioWOLFSSL_BIO structure to write to.
bufpointer to buffer to write to.
numnumber of bytes desired to be written.

Example

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
bioWOLFSSL_BIO structure to reset.

Example

// setup 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
noneNo parameters.

Example

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
bioWOLFSSL_BIO structure to set.
ofsoffset into file.

Example

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_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
bioWOLFSSL_BIO structure to set fd.
fdfile descriptor to use.
closeFflag for behavior when closing fd.

Example

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
bioWOLFSSL_BIO structure to set pair.
fpfile pointer to set in bio.
cclose file behavior flag.

Example

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
bioWOLFSSL_BIO structure to set end of file value.
vvalue to set in bio.

Example

int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
// 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
bioWOLFSSL_BIO structure to set fd.
sizesize of buffer to allocate.

Example

int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
// 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
bioWOLFSSL_BIO structure to set file.
namename of file to write to.

Example

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
ciphera 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){
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
ssla 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()

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
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 ,
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.

Returns
none No returns.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
tmtime used in session expiration comparison.

Example

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

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
ha 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_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 )

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
ssla 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
priorityInteger 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
ssla 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 *  ,
int   
)

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
bufa char pointer representing the buffer.
lenthe 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 )

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
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
sslThe SSL session to check.

Example

WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);
{
// 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 )

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
sslpointer 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
ssla 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 )

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
sslpointer 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
noneNo parameters.

Example

int sz = // Minimum size for error checking;
...
// 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
activea word32 pointer representing the total current sessions.
totala word32 pointer representing the total sessions.
peaka word32 pointer representing the peak sessions.
maxSessionsa word32 pointer representing the maximum sessions.

Example

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 ,
unsigned char *  ,
unsigned int *   
)

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
bufa byte pointer representing the memory buffer.
bufSza 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
sslpointer to the SSL session, created with wolfSSL_new().

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
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
ssla 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 )

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

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
ssla 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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

WOLFSSL* ssl;
void* ioWrite;
...
ioWrite = wolfSSL_GetIOWriteCtx(ssl);
if(ioWrite == NULL){
// The funciton 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
idxan int type representing the session index.
sessiona 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
ssla 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
sslPointer to the SSL session to check.

Example

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
noneNo 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 unsigned int wolfSSL_lib_version_hex ( void  )

This function returns the current library version in hexadecimal notation.

Returns
LILBWOLFSSL_VERSION_HEX returns the hexidecimal version defined in wolfssl/version.h.
Parameters
noneNo parameters.

Example

word32 libV;
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 *  ,
int   
)

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
mema constant void pointer containing the source of the restoration.
szan 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 *  ,
int   
)

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
mema void pointer representing the destination for the memory copy, XMEMCPY().
szan 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
sslpointer 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 ,
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.

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
sslpointer to the SSL session, created with wolfSSL_new().
databuffer where wolfSSL_peek() will place data read.
sznumber 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 )

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
sslpointer 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
noneNo 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 ,
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.

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
sslpointer to the SSL session, created with wolfSSL_new().
databuffer where wolfSSL_read() will place data read.
sznumber 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 ,
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.

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
sslpointer to the SSL session, created with wolfSSL_new().
databuffer where wolfSSL_recv() will place data read.
sznumber of bytes to read into data.
flagsthe 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
ssla 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 *  )

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
fnamea 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 *  )

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

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
sslpointer to the SSL session, created with wolfSSL_new().
datadata buffer to send to peer.
szsize, in bytes, of data to be sent to peer.
flagsthe 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
sessiona pointer to a WOLFSSL_SESSION structure.

Example

WOLFSSL_SESSION* 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 )

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
ssla 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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
objPtra 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 ,
const unsigned char *  ,
unsigned  int 
)

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
bufa byte pointer that gets loaded into the ticket member of the session structure.
bufSza 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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
nxSocketa pointer to type NX_TCP_SOCKET that is set to the nxSocket member of the nxCTX structure.
waitOptiona 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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
typethe 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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

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

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
sslpointer to the SSL session, created with wolfSSL_new().
datadata buffer which will be sent to peer.
szsize, 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
sslpointer to the SSL session, created with wolfSSL_new().
iovarray of I/O vectors to write
iovcntnumber 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