My Project
Functions
wolfSSL Connection, Session, and I/O

Functions

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

Detailed Description

Function Documentation

◆ wolfSSL_accept()

int wolfSSL_accept ( WOLFSSL *  )

This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_accept when data is available to read and wolfSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred.

Returns
SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().
Parameters
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));
}
char * wolfSSL_ERR_error_string(unsigned long, char *)
This function converts an error code returned by wolfSSL_get_error() into a more human-readable error...
int wolfSSL_get_error(WOLFSSL *ssl, int ret)
This function returns a unique error code describing why the previous API function call (wolfSSL_conn...
int wolfSSL_accept(WOLFSSL *)
This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handsh...
See also
wolfSSL_get_error
wolfSSL_connect

◆ wolfSSL_accept_TLSv13()

wolfSSL_accept_TLSv13 ( WOLFSSL *  ssl)

This function is called on the server side and waits for a SSL/TLS client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_accept when data is available to read and wolfSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred. Call this function when expecting a TLS v1.3 connection though older version ClientHello messages are supported.

Returns
SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().
Parameters
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));
}
wolfSSL_accept_TLSv13(WOLFSSL *ssl)
This function is called on the server side and waits for a SSL/TLS client to initiate the SSL/TLS han...
See also
wolfSSL_get_error
wolfSSL_connect_TLSv13
wolfSSL_connect
wolfSSL_accept_TLSv13
wolfSSL_accept

◆ wolfSSL_BIO_ctrl_pending()

size_t wolfSSL_BIO_ctrl_pending ( WOLFSSL_BIO *  b)

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

Returns
>=0 number of pending bytes.
Parameters
biopointer 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);
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...
See also
wolfSSL_BIO_make_bio_pair
wolfSSL_BIO_new

◆ wolfSSL_BIO_ctrl_reset_read_request()

int wolfSSL_BIO_ctrl_reset_read_request ( WOLFSSL_BIO *  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

WOLFSSL_BIO* bio;
int ret;
...
// check ret value
int wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *b)
This is used to set the read request flag back to 0.
See also
wolfSSL_BIO_new, wolfSSL_BIO_s_mem
wolfSSL_BIO_new, wolfSSL_BIO_free

◆ wolfSSL_BIO_get_fp()

long wolfSSL_BIO_get_fp ( WOLFSSL_BIO *  bio,
XFILE *  fp 
)

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

Returns
SSL_SUCCESS On successfully getting file pointer.
SSL_FAILURE If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to set pair.
fpfile 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
long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE *fp)
This is used to get the internal file pointer for a BIO.
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

◆ wolfSSL_BIO_get_mem_data()

int wolfSSL_BIO_get_mem_data ( WOLFSSL_BIO *  bio,
void *  p 
)

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

Returns
size On success the size of the buffer is returned
SSL_FATAL_ERROR If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to get memory buffer of.
pbyte 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
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.
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

◆ wolfSSL_BIO_get_mem_ptr()

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

This is a getter function for WOLFSSL_BIO memory pointer.

Returns
SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is returned (currently value of 1).
SSL_FAILURE Returned if NULL arguments are passed in (currently value of 0).
Parameters
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

WOLFSSL_BIO* bio;
WOLFSSL_BUF_MEM* pt;
// setup bio
//use pt
long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m)
This is a getter function for WOLFSSL_BIO memory pointer.
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem

◆ wolfSSL_BIO_make_bio_pair()

int wolfSSL_BIO_make_bio_pair ( WOLFSSL_BIO *  b1,
WOLFSSL_BIO *  b2 
)

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

Returns
SSL_SUCCESS On successfully pairing the two bios.
SSL_FAILURE If an error case was encountered.
Parameters
b1WOLFSSL_BIO structure to set pair.
b2second 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
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 ...
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_free

◆ wolfSSL_BIO_nread()

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

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

Returns
>=0 on success return the number of bytes to read
WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1
Parameters
bioWOLFSSL_BIO structure to read from.
bufpointer to set at beginning of read array.
numnumber 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
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 num...
See also
wolfSSL_BIO_new
wolfSSL_BIO_nwrite

◆ wolfSSL_BIO_nread0()

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

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

Returns
>=0 on success return the number of bytes to read
Parameters
bioWOLFSSL_BIO structure to read from.
bufpointer 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
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 ind...
See also
wolfSSL_BIO_new
wolfSSL_BIO_nwrite0

◆ wolfSSL_BIO_nwrite()

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

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

Returns
int Returns the number of bytes that can be written to the buffer pointer returned.
WOLFSSL_BIO_UNSET(-2) in the case that is not part of a bio pair
WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to write to
Parameters
bioWOLFSSL_BIO structure to write to.
bufpointer to buffer to write to.
numnumber 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
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....
See also
wolfSSL_BIO_new
wolfSSL_BIO_free
wolfSSL_BIO_nread

◆ wolfSSL_BIO_reset()

int wolfSSL_BIO_reset ( WOLFSSL_BIO *  bio)

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

Returns
0 On successfully resetting the bio.
WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset.
Parameters
bioWOLFSSL_BIO structure to reset.

Example

WOLFSSL_BIO* bio;
// setup bio
//use pt
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.
See also
wolfSSL_BIO_new
wolfSSL_BIO_free

◆ wolfSSL_BIO_s_socket()

WOLFSSL_BIO_METHOD* wolfSSL_BIO_s_socket ( void  )

This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.

Returns
WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure that is a socket type
Parameters
noneNo parameters.

Example

WOLFSSL_BIO* bio;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);
WOLFSSL_BIO_METHOD * wolfSSL_BIO_s_socket(void)
This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem

◆ wolfSSL_BIO_seek()

int wolfSSL_BIO_seek ( WOLFSSL_BIO *  bio,
int  ofs 
)

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

Returns
0 On successfully seeking.
-1 If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to set.
ofsoffset 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
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 f...
long wolfSSL_BIO_set_fp(WOLFSSL_BIO *bio, XFILE fp, int c)
This is used to set the internal file pointer for a BIO.
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

◆ wolfSSL_BIO_set_close()

int wolfSSL_BIO_set_close ( WOLFSSL_BIO *  b,
long  flag 
)

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

Returns
SSL_SUCCESS(1) upon success.
Parameters
bioWOLFSSL_BIO structure.
flagflag for behavior when closing i/o stream.

Example

WOLFSSL_BIO* bio;
// setup bio
wolfSSL_BIO_set_close(bio, BIO_NOCLOSE);
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.
See also
wolfSSL_BIO_new
wolfSSL_BIO_free

◆ wolfSSL_BIO_set_fd()

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

Sets the file descriptor for bio to use.

Returns
SSL_SUCCESS(1) upon success.
Parameters
bioWOLFSSL_BIO structure to set fd.
fdfile descriptor to use.
closeFflag for behavior when closing fd.

Example

WOLFSSL_BIO* bio;
int fd;
// setup bio
wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE);
long wolfSSL_BIO_set_fd(WOLFSSL_BIO *b, int fd, int flag)
Sets the file descriptor for bio to use.
See also
wolfSSL_BIO_new
wolfSSL_BIO_free

◆ wolfSSL_BIO_set_fp()

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

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

Returns
SSL_SUCCESS On successfully setting file pointer.
SSL_FAILURE If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to set pair.
fpfile pointer to set in bio.
cclose file behavior flag.

Example

WOLFSSL_BIO* bio;
XFILE fp;
int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
ret = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE);
// check ret value
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_get_fp
wolfSSL_BIO_free

◆ wolfSSL_BIO_set_mem_eof_return()

long wolfSSL_BIO_set_mem_eof_return ( WOLFSSL_BIO *  bio,
int  v 
)

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

Returns
0 returned on completion
Parameters
bioWOLFSSL_BIO structure to set end of file value.
vvalue to set in bio.

Example

WOLFSSL_BIO* bio;
int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
// check ret value
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...
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

◆ wolfSSL_BIO_set_write_buf_size()

int wolfSSL_BIO_set_write_buf_size ( WOLFSSL_BIO *  b,
long  size 
)

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

Returns
SSL_SUCCESS On successfully setting the write buffer.
SSL_FAILURE If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to set fd.
sizesize of buffer to allocate.

Example

WOLFSSL_BIO* bio;
int ret;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
// check return value
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 s...
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_mem
wolfSSL_BIO_free

◆ wolfSSL_BIO_write_filename()

int wolfSSL_BIO_write_filename ( WOLFSSL_BIO *  bio,
char *  name 
)

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

Returns
SSL_SUCCESS On successfully opening and setting file.
SSL_FAILURE If an error case was encountered.
Parameters
bioWOLFSSL_BIO structure to set file.
namename 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
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 ...
See also
wolfSSL_BIO_new
wolfSSL_BIO_s_file
wolfSSL_BIO_set_fp
wolfSSL_BIO_free

◆ wolfSSL_CIPHER_get_name()

const char* wolfSSL_CIPHER_get_name ( const WOLFSSL_CIPHER *  cipher)

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

Returns
string This function returns the string representation of the matched cipher suite.
none It will return “None” if there are no suites matched.
Parameters
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){
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
}
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 st...
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));
}
int wolfSSL_connect(WOLFSSL *ssl)
This function is called on the client side and initiates an SSL/TLS handshake with a server....
See also
wolfSSL_get_error
wolfSSL_accept

◆ wolfSSL_connect_cert()

int wolfSSL_connect_cert ( WOLFSSL *  ssl)

This function is called on the client side and initiates an SSL/TLS handshake with a server only long enough to get the peer’s certificate chain. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect_cert() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_connect_cert() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_connect_cert() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect_cert() will only return once the peer’s certificate chain has been received.

Returns
SSL_SUCCESS upon success.
SSL_FAILURE will be returned if the SSL session parameter is NULL.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().
Parameters
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));
}
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...
See also
wolfSSL_get_error
wolfSSL_connect
wolfSSL_accept

◆ wolfSSL_connect_TLSv13()

int wolfSSL_connect_TLSv13 ( WOLFSSL *  )

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

Returns
SSL_SUCCESS upon success.
SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().
Parameters
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));
}
int wolfSSL_connect_TLSv13(WOLFSSL *)
This function is called on the client side and initiates a TLS v1.3 handshake with a server....
See also
wolfSSL_get_error
wolfSSL_connect
wolfSSL_accept_TLSv13
wolfSSL_accept

◆ wolfSSL_flush_sessions()

void wolfSSL_flush_sessions ( WOLFSSL_CTX *  ctx,
long  tm 
)

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

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

Example

WOLFSSL_CTX* ssl;
...
wolfSSL_flush_sessions(ctx, time(0));
See also
wolfSSL_get1_session
wolfSSL_set_session

◆ wolfSSL_get_alert_history()

int wolfSSL_get_alert_history ( WOLFSSL *  ssl,
WOLFSSL_ALERT_HISTORY *  h 
)

This function gets the alert history.

Returns
SSL_SUCCESS returned when the function completed successfully. Either there was alert history or there wasn’t, either way, the return value is SSL_SUCCESS.
Parameters
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_ALERT_HISTORY* h;
...
wolfSSL_get_alert_history(ssl, h);
// h now has a copy of the ssl->alert_history contents
WOLFSSL * wolfSSL_new(WOLFSSL_CTX *)
This function creates a new SSL session, taking an already created SSL context as input.
WOLFSSL_CTX * wolfSSL_CTX_new(WOLFSSL_METHOD *)
This function creates a new SSL context, taking a desired SSL/TLS protocol method for input.
See also
wolfSSL_get_error

◆ wolfSSL_get_cipher()

const char* wolfSSL_get_cipher ( WOLFSSL *  )

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

Returns
This function returns the string value of the suite matched. It will return “None” if there are no suites matched.
Parameters
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
const char * wolfSSL_get_cipher(WOLFSSL *)
This function matches the cipher suite in the SSL object with the available suites.
See also
wolfSSL_CIPHER_get_name
wolfSSL_get_current_cipher

◆ wolfSSL_get_cipher_list()

char* wolfSSL_get_cipher_list ( int  priority)

Get the name of cipher at priority level passed in.

Returns
string Success
0 Priority is either out of bounds or not valid.
Parameters
priorityInteger representing the priority level of a cipher.

Example

printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1));
char * wolfSSL_get_cipher_list(int priority)
Get the name of cipher at priority level passed in.
See also
wolfSSL_CIPHER_get_name
wolfSSL_get_current_cipher

◆ wolfSSL_get_cipher_name()

const char* wolfSSL_get_cipher_name ( WOLFSSL *  ssl)

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

Returns
string This function returns the string representation of the cipher suite that was matched.
NULL error or cipher not found.
Parameters
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);
}
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_c...
See also
wolfSSL_CIPHER_get_name
wolfSSL_get_current_cipher
wolfSSL_get_cipher_name_internal

◆ wolfSSL_get_ciphers()

int wolfSSL_get_ciphers ( char *  buf,
int  len 
)

This function gets the ciphers enabled in wolfSSL.

Returns
SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if the buf parameter was NULL or if the len argument was less than or equal to zero.
BUFFER_E returned if the buffer is not large enough and will overflow.
Parameters
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);
}
}
int wolfSSL_get_ciphers(char *buf, int len)
This function gets the ciphers enabled in wolfSSL.
See also
GetCipherNames
wolfSSL_get_cipher_list
ShowCiphers

◆ wolfSSL_get_current_cipher()

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);
WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher;
if(!cipherCurr){
// Failure case.
} else {
// The cipher was returned to cipherCurr
}
WOLFSSL_CIPHER * wolfSSL_get_current_cipher(WOLFSSL *)
This function returns a pointer to the current cipher in the ssl session.
See also
wolfSSL_get_cipher
wolfSSL_get_cipher_name_internal
wolfSSL_get_cipher_name

◆ wolfSSL_get_current_cipher_suite()

int wolfSSL_get_current_cipher_suite ( WOLFSSL *  ssl)

Returns the current cipher suit an ssl session is using.

Returns
ssl->options.cipherSuite An integer representing the current cipher suite.
0 The ssl session provided is null.
Parameters
sslThe SSL session to check.

Example

WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);
{
// Error getting cipher suite
}
int wolfSSL_get_current_cipher_suite(WOLFSSL *ssl)
Returns the current cipher suit an ssl session is using.
int wolfSSL_Init(void)
Initializes the wolfSSL library for use. Must be called once per application and before any other cal...
See also
wolfSSL_CIPHER_get_name
wolfSSL_get_current_cipher
wolfSSL_get_cipher_list

◆ wolfSSL_get_fd()

int wolfSSL_get_fd ( const WOLFSSL *  )

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

Returns
fd If successful the call will return the SSL session file descriptor.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().

Example

int sockfd;
WOLFSSL* ssl = 0;
...
sockfd = wolfSSL_get_fd(ssl);
...
int wolfSSL_get_fd(const WOLFSSL *)
This function returns the file descriptor (fd) used as the input/output facility for the SSL connecti...
See also
wolfSSL_set_fd

◆ wolfSSL_get_jobject()

void* wolfSSL_get_jobject ( WOLFSSL *  ssl)

This function returns the jObjectRef member of the WOLFSSL structure.

Returns
value If the WOLFSSL struct is not NULL, the function returns the jObjectRef value.
NULL returned if the WOLFSSL struct is NULL.
Parameters
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
}
void * wolfSSL_get_jobject(WOLFSSL *ssl)
This function returns the jObjectRef member of the WOLFSSL structure.
See also
wolfSSL_set_jobject

◆ wolfSSL_get_session()

WOLFSSL_SESSION* wolfSSL_get_session ( WOLFSSL *  ssl)

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

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

Example

WOLFSSL* ssl;
WOLFSSL_SESSION* session;
...
session = wolfSSL_get_session(ssl);
if (session == NULL) {
// failed to get session pointer
}
...
WOLFSSL_SESSION * wolfSSL_get_session(WOLFSSL *ssl)
When NO_SESSION_CACHE_REF is defined this function returns a pointer to the current session (WOLFSSL_...
See also
wolfSSL_get1_session
wolfSSL_set_session

◆ wolfSSL_get_session_cache_memsize()

int wolfSSL_get_session_cache_memsize ( void  )

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

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

Example

int sz = // Minimum size for error checking;
...
// Memory buffer is too small
}
int wolfSSL_get_session_cache_memsize(void)
This function returns how large the session cache save buffer should be.
See also
wolfSSL_memrestore_session_cache

◆ wolfSSL_get_session_stats()

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

This function gets the statistics for the session.

Returns
SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed.
BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument.
BAD_MUTEX_E returned if there was a mutex error in the subroutine.
Parameters
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;
int wolfSSL_PrintSessionStats(void)
This function prints the statistics from the session.
int wolfSSL_get_session_stats(unsigned int *active, unsigned int *total, unsigned int *peak, unsigned int *maxSessions)
This function gets the statistics for the session.
See also
wolfSSL_PrintSessionStats

◆ wolfSSL_get_SessionTicket()

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

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

Returns
SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if one of the arguments was NULL or if the bufSz argument was 0.
Parameters
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
}
int wolfSSL_get_SessionTicket(WOLFSSL *ssl, unsigned char *buf, word32 *bufSz)
This function copies the ticket member of the Session structure to the buffer.
See also
wolfSSL_UseSessionTicket
wolfSSL_set_SessionTicket

◆ wolfSSL_get_using_nonblock()

int wolfSSL_get_using_nonblock ( WOLFSSL *  )

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

Returns
0 underlying I/O is blocking.
1 underlying I/O is non-blocking.
Parameters
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
}
...
int wolfSSL_get_using_nonblock(WOLFSSL *)
This function allows the application to determine if wolfSSL is using non-blocking I/O....
See also
wolfSSL_set_session

◆ wolfSSL_get_verify_depth()

long wolfSSL_get_verify_depth ( WOLFSSL *  ssl)

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

Returns
MAX_CHAIN_DEPTH returned if the WOLFSSL_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
}
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....
See also
wolfSSL_CTX_get_verify_depth

◆ wolfSSL_get_version()

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_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));
const char * wolfSSL_get_version(WOLFSSL *)
Returns the SSL version being used as a string.
See also
wolfSSL_lib_version

◆ wolfSSL_GetIOReadCtx()

void* wolfSSL_GetIOReadCtx ( WOLFSSL *  ssl)

This function returns the IOCB_ReadCtx member of the WOLFSSL struct.

Returns
pointer This function returns a void pointer to the IOCB_ReadCtx member of the WOLFSSL structure.
NULL returned if the WOLFSSL struct is NULL.
Parameters
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.
}
void * wolfSSL_GetIOReadCtx(WOLFSSL *ssl)
This function returns the IOCB_ReadCtx member of the WOLFSSL struct.
See also
wolfSSL_GetIOWriteCtx
wolfSSL_SetIOReadFlags
wolfSSL_SetIOWriteCtx
wolfSSL_SetIOReadCtx
wolfSSL_CTX_SetIOSend

◆ wolfSSL_GetIOWriteCtx()

void* wolfSSL_GetIOWriteCtx ( WOLFSSL *  ssl)

This function returns the IOCB_WriteCtx member of the WOLFSSL structure.

Returns
pointer This function returns a void pointer to the IOCB_WriteCtx member of the WOLFSSL structure.
NULL returned if the WOLFSSL struct is NULL.
Parameters
ssla 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.
}
void * wolfSSL_GetIOWriteCtx(WOLFSSL *ssl)
This function returns the IOCB_WriteCtx member of the WOLFSSL structure.
See also
wolfSSL_GetIOReadCtx
wolfSSL_SetIOWriteCtx
wolfSSL_SetIOReadCtx
wolfSSL_CTX_SetIOSend

◆ wolfSSL_GetSessionAtIndex()

int wolfSSL_GetSessionAtIndex ( int  index,
WOLFSSL_SESSION *  session 
)

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

Returns
SSL_SUCCESS returned if the function executed successfully and no errors were thrown.
BAD_MUTEX_E returned if there was an unlock or lock mutex error.
SSL_FAILURE returned if the function did not execute successfully.
Parameters
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.
}
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....
See also
UnLockMutex
LockMutex
wolfSSL_GetSessionIndex

◆ wolfSSL_GetSessionIndex()

int wolfSSL_GetSessionIndex ( WOLFSSL *  ssl)

This function gets the session index of the WOLFSSL structure.

Returns
int The function returns an int type representing the sessionIndex within the WOLFSSL struct.
Parameters
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.
}
int wolfSSL_GetSessionIndex(WOLFSSL *ssl)
This function gets the session index of the WOLFSSL structure.
See also
wolfSSL_GetSessionAtIndex

◆ wolfSSL_key_update_response()

int wolfSSL_key_update_response ( WOLFSSL *  ssl,
int *  required 
)

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

Parameters
[in]ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
[out]required0 when no key update response required. 1 when no key update response required.
Returns
0 on successful.
BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.

Example

int ret;
WOLFSSL* ssl;
int required;
...
ret = wolfSSL_key_update_response(ssl, &required);
if (ret != 0) {
// bad parameters
}
if (required) {
// encrypt Key updated, awaiting response to change decrypt key
}
int wolfSSL_key_update_response(WOLFSSL *ssl, int *required)
This function is called on a TLS v1.3 client or server wolfSSL to determine whether a rollover of key...
See also
wolfSSL_update_keys

◆ wolfSSL_lib_version()

const char* wolfSSL_lib_version ( void  )

This function returns the current library version.

Returns
LIBWOLFSSL_VERSION_STRING a const char pointer defining the version.
Parameters
noneNo parameters.

Example

char version[MAXSIZE];
version = wolfSSL_KeepArrays();
if(version != ExpectedVersion){
// Handle the mismatch case
}
void wolfSSL_KeepArrays(WOLFSSL *)
Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. Calling this function befo...
See also
word32_wolfSSL_lib_version_hex

◆ wolfSSL_lib_version_hex()

word32 wolfSSL_lib_version_hex ( void  )

This function returns the current library version in hexadecimal notation.

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

Example

word32 libV;
if(libV != EXPECTED_HEX){
// How to handle an unexpected value
} else {
// The expected result for libV
}
word32 wolfSSL_lib_version_hex(void)
This function returns the current library version in hexadecimal notation.
See also
wolfSSL_lib_version

◆ wolfSSL_memrestore_session_cache()

int wolfSSL_memrestore_session_cache ( const void *  mem,
int  sz 
)

This function restores the persistent session cache from memory.

Returns
SSL_SUCCESS returned if the function executed without an error.
BUFFER_E returned if the memory buffer is too small.
BAD_MUTEX_E returned if the session cache mutex lock failed.
CACHE_MATCH_ERROR returned if the session cache header match failed.
Parameters
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.
}
int wolfSSL_memrestore_session_cache(const void *mem, int sz)
This function restores the persistent session cache from memory.
See also
wolfSSL_save_session_cache

◆ wolfSSL_memsave_session_cache()

int wolfSSL_memsave_session_cache ( void *  mem,
int  sz 
)

This function persists session cache to memory.

Returns
SSL_SUCCESS returned if the function executed without error. The session cache has been successfully persisted to memory.
BAD_MUTEX_E returned if there was a mutex lock error.
BUFFER_E returned if the buffer size was too small.
Parameters
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
}
int wolfSSL_memsave_session_cache(void *mem, int sz)
This function persists session cache to memory.
See also
XMEMCPY
wolfSSL_get_session_cache_memsize

◆ wolfSSL_negotiate()

int wolfSSL_negotiate ( WOLFSSL *  ssl)

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

Returns
SSL_SUCCESS will be returned if successful. (Note, older versions will return 0.)
SSL_FATAL_ERROR will be returned if the underlying call resulted in an error. Use wolfSSL_get_error() to get a specific error code.
Parameters
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);
...
}
...
int wolfSSL_negotiate(WOLFSSL *ssl)
Performs the actual connect or accept based on the side of the SSL method. If called from the client ...
See also
SSL_connect
SSL_accept

◆ wolfSSL_peek()

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

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

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

◆ wolfSSL_pending()

int wolfSSL_pending ( WOLFSSL *  )

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

Returns
int This function returns the number of bytes pending.
Parameters
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);
int wolfSSL_pending(WOLFSSL *)
This function returns the number of bytes which are buffered and available in the SSL object to be re...
See also
wolfSSL_recv
wolfSSL_read
wolfSSL_peek

◆ wolfSSL_PrintSessionStats()

int wolfSSL_PrintSessionStats ( void  )

This function prints the statistics from the session.

Returns
SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed.
BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument.
BAD_MUTEX_E returned if there was a mutex error in the subroutine.
Parameters
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()

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
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().
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....
See also
wolfSSL_recv
wolfSSL_write
wolfSSL_peek
wolfSSL_pending

◆ wolfSSL_read_early_data()

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

This function reads any early data from a client on resumption. Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13() to accept a client and read any early data in the handshake. If there is no early data than the handshake will be processed as normal. This function is only used with servers.

Parameters
[in,out]ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
[out]dataa buffer to hold the early data read from client.
[in]szsize of the buffer in bytes.
[out]outSznumber of bytes of early data read.
Returns
BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or not using TLSv1.3.
SIDE_ERROR if called with a client.
WOLFSSL_FATAL_ERROR if accepting a connection fails.
WOLFSSL_SUCCESS if successful.

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
byte earlyData[128];
int outSz;
char buffer[80];
...
ret = wolfSSL_read_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
if (ret != SSL_SUCCESS) {
err = wolfSSL_get_error(ssl, ret);
printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}
if (outSz > 0) {
// early data available
}
if (ret != SSL_SUCCESS) {
err = wolfSSL_get_error(ssl, ret);
printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}
int wolfSSL_read_early_data(WOLFSSL *ssl, void *data, int sz, int *outSz)
This function reads any early data from a client on resumption. Call this function instead of wolfSSL...
See also
wolfSSL_write_early_data
wolfSSL_accept
wolfSSL_accept_TLSv13

◆ wolfSSL_recv()

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

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

Returns
>0 the number of bytes read upon success.
0 will be returned upon failure. This may be caused by a either a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific error code.
Parameters
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”
}
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 usi...
See also
wolfSSL_read
wolfSSL_write
wolfSSL_peek
wolfSSL_pending

◆ wolfSSL_Rehandshake()

int wolfSSL_Rehandshake ( WOLFSSL *  ssl)

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

Returns
SSL_SUCCESS returned if the function executed without error.
BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise if an unacceptable argument was passed in a subroutine.
SECURE_RENEGOTIATION_E returned if there was an error with renegotiating the handshake.
SSL_FATAL_ERROR returned if there was an error with the server or client configuration and the renegotiation could not be completed. See wolfSSL_negotiate().
Parameters
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.
}
int wolfSSL_Rehandshake(WOLFSSL *ssl)
This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages t...
See also
wolfSSL_negotiate
wc_InitSha512
wc_InitSha384
wc_InitSha256
wc_InitSha
wc_InitMd5

◆ wolfSSL_request_certificate()

int wolfSSL_request_certificate ( WOLFSSL *  ssl)

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

Parameters
[in,out]ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
Returns
BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
WANT_WRITE if the writing is not ready.
SIDE_ERROR if called with a client.
NOT_READY_ERROR if called when the handshake is not finished.
POST_HAND_AUTH_ERROR if posthandshake authentication is disallowed.
MEMORY_E if dynamic memory allocation fails.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
if (ret == WANT_WRITE) {
// need to call again when I/O ready
}
else if (ret != WOLFSSL_SUCCESS) {
// failed to request a client certificate
}
int wolfSSL_request_certificate(WOLFSSL *ssl)
This function requests a client certificate from the TLS v1.3 client. This is useful when a web serve...
See also
wolfSSL_allow_post_handshake_auth
wolfSSL_write

◆ wolfSSL_restore_session_cache()

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.
}
int wolfSSL_restore_session_cache(const char *)
This function restores the persistent session cache from file. It does not use memstore because of ad...
See also
XFREAD
XFOPEN

◆ wolfSSL_save_session_cache()

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.
}
int wolfSSL_save_session_cache(const char *)
This function persists the session cache to file. It doesn’t use memsave because of additional memory...
See also
XFWRITE
wolfSSL_restore_session_cache
wolfSSL_memrestore_session_cache

◆ wolfSSL_send()

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

This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the specified flags for the underlying write operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). wolfSSL_send() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_send() will return when the underlying I/O could not satisfy the needs of wolfSSL_send to continue. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_send() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred.

Returns
>0 the number of bytes written upon success.
0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code.
SSL_FATAL_ERROR will be returned upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call wolfSSL_send() again. Use wolfSSL_get_error() to get a specific error code.
Parameters
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
}
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 ...
See also
wolfSSL_write
wolfSSL_read
wolfSSL_recv

◆ wolfSSL_SESSION_get_peer_chain()

WOLFSSL_X509_CHAIN* wolfSSL_SESSION_get_peer_chain ( WOLFSSL_SESSION *  session)

Returns the peer certificate chain from the WOLFSSL_SESSION struct.

Returns
pointer A pointer to a WOLFSSL_X509_CHAIN structure that contains the peer certification chain.
Parameters
sessiona pointer to a WOLFSSL_SESSION structure.

Example

WOLFSSL_SESSION* session;
WOLFSSL_X509_CHAIN* chain;
...
if(!chain){
// There was no chain. Failure case.
}
WOLFSSL_X509_CHAIN * wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION *session)
Returns the peer certificate chain from the WOLFSSL_SESSION struct.
See also
wolfSSL_GetSessionAtIndex
wolfSSL_GetSessionIndex
AddSession

◆ wolfSSL_session_reused()

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.
}
int wolfSSL_session_reused(WOLFSSL *)
This function returns the resuming member of the options struct. The flag indicates whether or not to...
See also
wolfSSL_SESSION_free
wolfSSL_GetSessionIndex
wolfSSL_memsave_session_cache

◆ wolfSSL_set_jobject()

int wolfSSL_set_jobject ( WOLFSSL *  ssl,
void *  objPtr 
)

This function sets the jObjectRef member of the WOLFSSL structure.

Returns
SSL_SUCCESS returned if jObjectRef is properly set to objPtr.
SSL_FAILURE returned if the function did not properly execute and jObjectRef is not set.
Parameters
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
}
int wolfSSL_set_jobject(WOLFSSL *ssl, void *objPtr)
This function sets the jObjectRef member of the WOLFSSL structure.
See also
wolfSSL_get_jobject

◆ wolfSSL_set_SessionTicket()

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

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

Returns
SSL_SUCCESS returned on successful execution of the function. The function returned without errors.
BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will also be thrown if the buf argument is NULL but the bufSz argument is not zero.
Parameters
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()

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.
}
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.
See also
set_fd
NetX_Send
NetX_Receive

◆ wolfSSL_SNI_Status()

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

This function gets the status of an SNI object.

Returns
value This function returns the byte value of the SNI struct’s status member if the SNI is not NULL.
0 if the SNI object is NULL.
Parameters
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));
unsigned char wolfSSL_SNI_Status(WOLFSSL *ssl, unsigned char type)
This function gets the status of an SNI object.
See also
TLSX_SNI_Status
TLSX_SNI_find
TLSX_Find

◆ wolfSSL_update_keys()

int wolfSSL_update_keys ( WOLFSSL *  ssl)

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

Parameters
[in,out]ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
Returns
BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
WANT_WRITE if the writing is not ready.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
if (ret == WANT_WRITE) {
// need to call again when I/O ready
}
else if (ret != WOLFSSL_SUCCESS) {
// failed to send key update
}
int wolfSSL_update_keys(WOLFSSL *ssl)
This function is called on a TLS v1.3 client or server wolfSSL to force the rollover of keys....
See also
wolfSSL_write

◆ wolfSSL_UseSecureRenegotiation()

int wolfSSL_UseSecureRenegotiation ( WOLFSSL *  ssl)

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

Returns
SSL_SUCCESS Successfully set secure renegotiation.
BAD_FUNC_ARG Returns error if ssl is null.
MEMORY_E Returns error if unable to allocate memory for secure renegotiation.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

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
}
int wolfSSL_UseSecureRenegotiation(WOLFSSL *ssl)
This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended...
See also
TLSX_Find
TLSX_UseSecureRenegotiation

◆ wolfSSL_UseSessionTicket()

int wolfSSL_UseSessionTicket ( WOLFSSL *  ssl)

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

Returns
SSL_SUCCESS Successfully set use session ticket.
BAD_FUNC_ARG Returned if ssl is null.
MEMORY_E Error allocating memory for setting session ticket.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

Example

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
}
int wolfSSL_UseSessionTicket(WOLFSSL *ssl)
Force provided WOLFSSL structure to use session ticket. The constant HAVE_SESSION_TICKET should be de...
See also
TLSX_UseSessionTicket

◆ wolfSSL_write()

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

This function writes sz bytes from the buffer, data, to the SSL connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). 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()
}
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,...
See also
wolfSSL_send
wolfSSL_read
wolfSSL_recv

◆ wolfSSL_write_early_data()

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

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

Parameters
[in,out]ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
[in]datathe buffer holding the early data to write to server.
[in]szthe amount of early data to write in bytes.
[out]outSzthe amount of early data written in bytes.
Returns
BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or not using TLSv1.3.
SIDE_ERROR if called with a server.
WOLFSSL_FATAL_ERROR if the connection is not made.
WOLFSSL_SUCCESS if successful.

Example

int ret = 0;
int err = 0;
WOLFSSL* ssl;
byte earlyData[] = { early data };
int outSz;
char buffer[80];
...
ret = wolfSSL_write_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
if (ret != WOLFSSL_SUCCESS) {
err = wolfSSL_get_error(ssl, ret);
printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
goto err_label;
}
if (outSz < sizeof(earlyData)) {
// not all early data was sent
}
if (ret != SSL_SUCCESS) {
err = wolfSSL_get_error(ssl, ret);
printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
}
int wolfSSL_write_early_data(OLFSSL *ssl, const void *data, int sz, int *outSz)
This function writes early data to the server on resumption. Call this function instead of wolfSSL_co...
See also
wolfSSL_read_early_data
wolfSSL_connect
wolfSSL_connect_TLSv13

◆ wolfSSL_writev()

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

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

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