ssl.h

Functions

	Name
WOLFSSL_METHOD *	wolfDTLSv1_2_client_method_ex(void * heap) This function initializes the DTLS v1.2 client method.
WOLFSSL_METHOD *	wolfSSLv23_method(void ) This function returns a WOLFSSL_METHOD similar to wolfSSLv23_client_method except that it is not determined which side yet (server/client).
WOLFSSL_METHOD *	wolfSSLv3_server_method(void ) The wolfSSLv3_server_method() function is used to indicate that the application is a server and will only support the SSL 3.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfSSLv3_client_method(void ) The wolfSSLv3_client_method() function is used to indicate that the application is a client and will only support the SSL 3.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_server_method(void ) The wolfTLSv1_server_method() function is used to indicate that the application is a server and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_client_method(void ) The wolfTLSv1_client_method() function is used to indicate that the application is a client and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_1_server_method(void ) The wolfTLSv1_1_server_method() function is used to indicate that the application is a server and will only support the TLS 1.1 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_1_client_method(void ) The wolfTLSv1_1_client_method() function is used to indicate that the application is a client and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_2_server_method(void ) The wolfTLSv1_2_server_method() function is used to indicate that the application is a server and will only support the TLS 1.2 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_2_client_method(void ) The wolfTLSv1_2_client_method() function is used to indicate that the application is a client and will only support the TLS 1.2 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfDTLSv1_client_method(void ) The wolfDTLSv1_client_method() function is used to indicate that the application is a client and will only support the DTLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).
WOLFSSL_METHOD *	wolfDTLSv1_server_method(void ) The wolfDTLSv1_server_method() function is used to indicate that the application is a server and will only support the DTLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).
WOLFSSL_METHOD *	wolfDTLSv1_3_server_method(void ) The wolfDTLSv1_3_server_method() function is used to indicate that the application is a server and will only support the DTLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLSv1.3 support (–enable_dtls13, or by defining wolfSSL_DTLS13).
WOLFSSL_METHOD *	wolfDTLSv1_3_client_method(void ) The wolfDTLSv1_3_client_method() function is used to indicate that the application is a client and will only support the DTLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLSv1.3 support (–enable_dtls13, or by defining wolfSSL_DTLS13).
WOLFSSL_METHOD *	wolfDTLS_server_method(void ) The wolfDTLS_server_method() function is used to indicate that the application is a server and will support the highest version of DTLS available and all the version up to the minimum version allowed. The default minimum version allowed is based on the define WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using wolfSSL_SetMinVersion(). This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).
WOLFSSL_METHOD *	wolfDTLS_client_method(void ) The wolfDTLS_client_method() function is used to indicate that the application is a client and will support the highest version of DTLS available and all the version up to the minimum version allowed. The default minimum version allowed is based on the define WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using wolfSSL_SetMinVersion(). This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).
WOLFSSL_METHOD *	wolfDTLSv1_2_server_method(void ) This function creates and initializes a WOLFSSL_METHOD for the server side.
int	wolfSSL_use_old_poly(WOLFSSL * ssl, int value) Since there is some differences between the first release and newer versions of chacha-poly AEAD construction we have added an option to communicate with servers/clients using the older version. By default wolfSSL uses the new version.
int	wolfSSL_dtls_import(WOLFSSL * ssl, unsigned char * buf, unsigned int sz) The wolfSSL_dtls_import() function is used to parse in a serialized session state. This allows for picking up the connection after the handshake has been completed.
int	wolfSSL_tls_import(WOLFSSL * ssl, const unsigned char * buf, unsigned int sz) Used to import a serialized TLS session. This function is for importing the state of the connection. WARNING: buf contains sensitive information about the state and is best to be encrypted before storing if stored. Additional debug info can be displayed with the macro WOLFSSL_SESSION_EXPORT_DEBUG defined.
int	wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX * ctx, wc_dtls_export func) The wolfSSL_CTX_dtls_set_export() function is used to set the callback function for exporting a session. It is allowed to pass in NULL as the parameter func to clear the export function previously stored. Used on the server side and is called immediately after handshake is completed.
int	wolfSSL_dtls_set_export(WOLFSSL * ssl, wc_dtls_export func) The wolfSSL_dtls_set_export() function is used to set the callback function for exporting a session. It is allowed to pass in NULL as the parameter func to clear the export function previously stored. Used on the server side and is called immediately after handshake is completed.
int	wolfSSL_dtls_export(WOLFSSL * ssl, unsigned char * buf, unsigned int * sz) The wolfSSL_dtls_export() function is used to serialize a WOLFSSL session into the provided buffer. Allows for less memory overhead than using a function callback for sending a session and choice over when the session is serialized. If buffer is NULL when passed to function then sz will be set to the size of buffer needed for serializing the WOLFSSL session.
int	wolfSSL_tls_export(WOLFSSL * ssl, unsigned char * buf, unsigned int * sz) Used to export a serialized TLS session. This function is for exporting a serialized state of the connection. In most cases wolfSSL_get1_session should be used instead of wolfSSL_tls_export. Additional debug info can be displayed with the macro WOLFSSL_SESSION_EXPORT_DEBUG defined. WARNING: buf contains sensitive information about the state and is best to be encrypted before storing if stored.
int	wolfSSL_CTX_load_static_memory(WOLFSSL_CTX * ctx, wolfSSL_method_func method, unsigned char * buf, unsigned int sz, int flag, int max) This function is used to set aside static memory for a CTX. Memory set aside is then used for the CTX’s lifetime and for any SSL objects created from the CTX. By passing in a NULL ctx pointer and a wolfSSL_method_func function the creation of the CTX itself will also use static memory. wolfSSL_method_func has the function signature of WOLFSSL_METHOD (wolfSSL_method_func)(void heap);. Passing in 0 for max makes it behave as if not set and no max concurrent use restrictions is in place. The flag value passed in determines how the memory is used and behavior while operating. Available flags are the following: 0 - default general memory, WOLFMEM_IO_POOL - used for input/output buffer when sending receiving messages and overrides general memory, so all memory in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory stats while running.
int	wolfSSL_CTX_is_static_memory(WOLFSSL_CTX * ctx, WOLFSSL_MEM_STATS * mem_stats) This function does not change any of the connections behavior and is used only for gathering information about the static memory usage.
int	wolfSSL_is_static_memory(WOLFSSL * ssl, WOLFSSL_MEM_CONN_STATS * mem_stats) wolfSSL_is_static_memory is used to gather information about a SSL’s static memory usage. The return value indicates if static memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent CTX when loading in static memory.
int	wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX * ctx, const char * file, int format) This function loads a certificate file into the SSL context (WOLFSSL_CTX). The file is provided by the file argument. The format argument specifies the format type of the file, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX * ctx, const char * file, int format) This function loads a private key file into the SSL context (WOLFSSL_CTX). The file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX * ctx, const char * file, const char * path) This function loads PEM_formatted CA certificate files into the SSL context (WOLFSSL_CTX). These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The path argument is a pointer to the name of a directory that contains certificates of trusted root CAs. If the value of file is not NULL, path may be specified as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not defined when building the library, wolfSSL will load all CA certificates located in the given directory. This function will attempt to load all files in the directory. This function expects PEM formatted CERT_TYPE file with header “--—BEGIN CERTIFICATE--—”.
int	wolfSSL_CTX_load_verify_locations_ex(WOLFSSL_CTX * ctx, const char * file, const char * path, unsigned int flags) This function loads PEM_formatted CA certificate files into the SSL context (WOLFSSL_CTX). These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The path argument is a pointer to the name of a directory that contains certificates of trusted root CAs. If the value of file is not NULL, path may be specified as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not defined when building the library, wolfSSL will load all CA certificates located in the given directory. This function will attempt to load all files in the directory based on flags specified. This function expects PEM formatted CERT_TYPE files with header “--—BEGIN CERTIFICATE--—”.
const char **	wolfSSL_get_system_CA_dirs(word32 * num) This function returns a pointer to an array of strings representing directories wolfSSL will search for system CA certs when wolfSSL_CTX_load_system_CA_certs is called. On systems that don't store certificates in an accessible system directory (such as Apple platforms), this function will always return NULL.
int	wolfSSL_CTX_load_system_CA_certs(WOLFSSL_CTX * ctx) On most platforms (including Linux and Windows), this function attempts to load CA certificates into a WOLFSSL_CTX from an OS-dependent CA certificate store. Loaded certificates will be trusted.
int	wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX * ctx, const char * file, int type) This function loads a certificate to use for verifying a peer when performing a TLS/SSL handshake. The peer certificate sent during the handshake is compared by using the SKID when available and the signature. If these two things do not match then any loaded CAs are used. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the examples for proper usage.
int	wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX * ctx, const char * file) This function loads a chain of certificates into the SSL context (WOLFSSL_CTX). The file containing the certificate chain is provided by the file argument, and must contain PEM_formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject cert.
int	wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX * ctx, const char * file, int format) This function loads the private RSA key used in the SSL connection into the SSL context (WOLFSSL_CTX). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable_opensslExtra, #define OPENSSL_EXTRA), and is identical to the more_typically used wolfSSL_CTX_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.
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).
long	wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX * ctx) This function gets the certificate chaining depth using the CTX structure.
int	wolfSSL_use_certificate_file(WOLFSSL * ssl, const char * file, int format) This function loads a certificate file into the SSL session (WOLFSSL structure). The certificate file is provided by the file argument. The format argument specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
int	wolfSSL_use_PrivateKey_file(WOLFSSL * ssl, const char * file, int format) This function loads a private key file into the SSL session (WOLFSSL structure). The key file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
int	wolfSSL_use_certificate_chain_file(WOLFSSL * ssl, const char * file) This function loads a chain of certificates into the SSL session (WOLFSSL structure). The file containing the certificate chain is provided by the file argument, and must contain PEM_formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject certificate.
int	wolfSSL_use_RSAPrivateKey_file(WOLFSSL * ssl, const char * file, int format) This function loads the private RSA key used in the SSL connection into the SSL session (WOLFSSL structure). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable_opensslExtra, #define OPENSSL_EXTRA), and is identical to the more_typically used wolfSSL_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.
int	wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX * ctx, const char * file, int format) This function is similar to wolfSSL_CTX_load_verify_locations, but allows the loading of DER_formatted CA files into the SSL context (WOLFSSL_CTX). It may still be used to load PEM_formatted CA files as well. These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The format argument specifies the format which the certificates are in either, SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations, this function does not allow the loading of CA certificates from a given directory path. Note that this function is only available when the wolfSSL library was compiled with WOLFSSL_DER_LOAD defined.
WOLFSSL_CTX *	wolfSSL_CTX_new(WOLFSSL_METHOD * ) This function creates a new SSL context, taking a desired SSL/TLS protocol method for input.
WOLFSSL *	wolfSSL_new(WOLFSSL_CTX * ) This function creates a new SSL session, taking an already created SSL context as input.
int	wolfSSL_set_fd(WOLFSSL * ssl, int fd) This function assigns a file descriptor (fd) as the input/output facility for the SSL connection. Typically this will be a socket file descriptor.
int	wolfSSL_set_dtls_fd_connected(WOLFSSL * ssl, int fd) This function assigns a file descriptor (fd) as the input/output facility for the SSL connection. Typically this will be a socket file descriptor. This is a DTLS specific API because it marks that the socket is connected. recvfrom and sendto calls on this fd will have the addr and addr_len parameters set to NULL.
int	wolfDTLS_SetChGoodCb(WOLFSSL * ssl, ClientHelloGoodCb cb, void * user_ctx) Allows setting a callback for a correctly processed and verified DTLS client hello. When using a cookie exchange mechanism (either the HelloVerifyRequest in DTLS 1.2 or the HelloRetryRequest with a cookie extension in DTLS 1.3) this callback is called after the cookie exchange has succeeded. This is useful to use one WOLFSSL object as the listener for new connections and being able to isolate the WOLFSSL object once the ClientHello is verified (either through a cookie exchange or just checking if the ClientHello had the correct format). DTLS 1.2: https://datatracker.ietf.org/doc/html/rfc6347#section_4.2.1 DTLS 1.3: https://www.rfc_editor.org/rfc/rfc8446#section_4.2.2.
char *	wolfSSL_get_cipher_list(int priority) Get the name of cipher at priority level passed in.
int	wolfSSL_get_ciphers(char * buf, int len) This function gets the ciphers enabled in wolfSSL.
const char *	wolfSSL_get_cipher_name(WOLFSSL * ssl) This function gets the cipher name in the format DHE-RSA by passing through argument to wolfSSL_get_cipher_name_internal.
int	wolfSSL_get_fd(const WOLFSSL * ) This function returns the file descriptor (fd) used as the input/output facility for the SSL connection. Typically this will be a socket file descriptor.
void	wolfSSL_set_using_nonblock(WOLFSSL * ssl, int nonblock) This function informs the WOLFSSL object that the underlying I/O is non_blocking. After an application creates a WOLFSSL object, if it will be used with a non_blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
int	wolfSSL_get_using_nonblock(WOLFSSL * ) This function allows the application to determine if wolfSSL is using non_blocking I/O. If wolfSSL is using non_blocking I/O, this function will return 1, otherwise 0. After an application creates a WOLFSSL object, if it will be used with a non_blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
int	wolfSSL_write(WOLFSSL * ssl, const void * data, int sz) This function writes sz bytes from the buffer, data, to the SSL connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data feature is compiled in, this function progresses the handshake only up to the point when it is possible to send data. Next invocations of wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the handshake. wolfSSL_write() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_write() will return when the underlying I/O could not satisfy the needs of wolfSSL_write() to continue. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_write() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred.
int	wolfSSL_read(WOLFSSL * ssl, void * data, int sz) This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data. The bytes read are removed from the internal receive buffer. If necessary wolfSSL_read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_read() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_read() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_read() will trigger processing of the next record.
int	wolfSSL_peek(WOLFSSL * ssl, void * data, int sz) This function copies sz bytes from the SSL session (ssl) internal read buffer into the buffer data. This function is identical to wolfSSL_read() except that the data in the internal SSL session receive buffer is not removed or modified. If necessary, like wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_peek() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes in the internal read buffer, SSL_peek() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_peek() will trigger processing of the next record.
int	wolfSSL_accept(WOLFSSL * ) This function is called on the server side and waits for an SSL client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred.
void	wolfSSL_CTX_free(WOLFSSL_CTX * ) This function frees an allocated WOLFSSL_CTX object. This function decrements the CTX reference count and only frees the context when the reference count has reached 0.
void	wolfSSL_free(WOLFSSL * ) This function frees an allocated wolfSSL object.
int	wolfSSL_shutdown(WOLFSSL * ) This function shuts down an active SSL/TLS connection using the SSL session, ssl. This function will try to send a “close notify” alert to the peer. The calling application can choose to wait for the peer to send its “close notify” alert in response or just go ahead and shut down the underlying connection after directly calling wolfSSL_shutdown (to save resources). Either option is allowed by the TLS specification. If the underlying connection will be used again in the future, the complete two_directional shutdown procedure must be performed to keep synchronization intact between the peers. wolfSSL_shutdown() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_shutdown() will return an error if the underlying I/O could not satisfy the needs of wolfSSL_shutdown() 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_shutdown() when the underlying I/O is ready.
int	wolfSSL_send(WOLFSSL * ssl, const void * data, int sz, int flags) This function writes sz bytes from the buffer, data, to the SSL connection, ssl, using the specified flags for the underlying write operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). wolfSSL_send() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_send() will return when the underlying I/O could not satisfy the needs of wolfSSL_send to continue. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_send() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred.
int	wolfSSL_recv(WOLFSSL * ssl, void * data, int sz, int flags) This function reads sz bytes from the SSL session (ssl) internal read buffer into the buffer data using the specified flags for the underlying recv operation. The bytes read are removed from the internal receive buffer. This function is identical to wolfSSL_read() except that it allows the application to set the recv flags for the underlying read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a maximum size of 16kB (the max record size can be controlled by the MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to wolfSSL_recv() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not_yet_decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to wolfSSL_recv(). If sz is larger than the number of bytes in the internal read buffer, SSL_recv() will return the bytes available in the internal read buffer. If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_recv() will trigger processing of the next record.
int	wolfSSL_get_error(WOLFSSL * ssl, int ret) This function returns a unique error code describing why the previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). The return value of the previous function is passed to wolfSSL_get_error through ret. After wolfSSL_get_error is called and returns the unique error code, wolfSSL_ERR_error_string() may be called to get a human_readable error string. See wolfSSL_ERR_error_string() for more information.
int	wolfSSL_get_alert_history(WOLFSSL * ssl, WOLFSSL_ALERT_HISTORY * h) This function gets the alert history.
int	wolfSSL_set_session(WOLFSSL * ssl, WOLFSSL_SESSION * session) This function sets the session to be used when the SSL object, ssl, is used to establish a SSL/TLS connection. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get1_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. The object returned by wolfSSL_get1_session() needs to be freed after the application is done with it by calling wolfSSL_SESSION_free() on it.
WOLFSSL_SESSION *	wolfSSL_get_session(WOLFSSL * ssl) When NO_SESSION_CACHE_REF is defined this function returns a pointer to the current session (WOLFSSL_SESSION) used in ssl. This function returns a non_persistent pointer to the WOLFSSL_SESSION object. The pointer returned will be freed when wolfSSL_free is called. This call should only be used to inspect or modify the current session. For session resumption it is recommended to use wolfSSL_get1_session(). For backwards compatibility when NO_SESSION_CACHE_REF is not defined this function returns a persistent session object pointer that is stored in the local cache. The cache size is finite and there is a risk that the session object will be overwritten by another ssl connection by the time the application calls wolfSSL_set_session() on it. It is recommended to define NO_SESSION_CACHE_REF in your application and to use wolfSSL_get1_session() for session resumption.
void	wolfSSL_flush_sessions(WOLFSSL_CTX * ctx, long tm) This function flushes session from the session cache which have expired. The time, tm, is used for the time comparison. Note that wolfSSL currently uses a static table for sessions, so no flushing is needed. As such, this function is currently just a stub. This function provides OpenSSL compatibility (SSL_flush_sessions) when wolfSSL is compiled with the OpenSSL compatibility layer.
int	wolfSSL_SetServerID(WOLFSSL * ssl, const unsigned char * id, int len, int newSession) This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused.
int	wolfSSL_GetSessionIndex(WOLFSSL * ssl) This function gets the session index of the WOLFSSL structure.
int	wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION * session) This function gets the session at specified index of the session cache and copies it into memory. The WOLFSSL_SESSION structure holds the session information.
WOLFSSL_X509_CHAIN *	wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION * session) Returns the peer certificate chain from the WOLFSSL_SESSION struct.
void	wolfSSL_CTX_set_verify(WOLFSSL_CTX * ctx, int mode, VerifyCallback verify_callback) This function sets the verification method for remote peers and also allows a verify callback to be registered with the SSL context. The verify callback will be called only when a verification failure has occurred. If no verify callback is desired, the NULL pointer can be used for verify_callback. The verification mode of peer certificates is a logically OR’d list of flags. The possible flag values include: SSL_VERIFY_NONE Client mode: the client will not verify the certificate received from the server and the handshake will continue as normal. Server mode: the server will not send a certificate request to the client. As such, client verification will not be enabled. SSL_VERIFY_PEER Client mode: the client will verify the certificate received from the server during the handshake. This is turned on by default in wolfSSL, therefore, using this option has no effect. Server mode: the server will send a certificate request to the client and verify the client certificate received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when used on the client side. Server mode: the verification will fail on the server side if the client fails to send a certificate when requested to do so (when using SSL_VERIFY_PEER on the SSL server). SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client side. Server mode: the verification is the same as SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. If a PSK connection is being made then the connection will go through without a peer cert.
void	wolfSSL_set_verify(WOLFSSL * ssl, int mode, VerifyCallback verify_callback) This function sets the verification method for remote peers and also allows a verify callback to be registered with the SSL session. The verify callback will be called only when a verification failure has occurred. If no verify callback is desired, the NULL pointer can be used for verify_callback. The verification mode of peer certificates is a logically OR’d list of flags. The possible flag values include: SSL_VERIFY_NONE Client mode: the client will not verify the certificate received from the server and the handshake will continue as normal. Server mode: the server will not send a certificate request to the client. As such, client verification will not be enabled. SSL_VERIFY_PEER Client mode: the client will verify the certificate received from the server during the handshake. This is turned on by default in wolfSSL, therefore, using this option has no effect. Server mode: the server will send a certificate request to the client and verify the client certificate received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when used on the client side. Server mode: the verification will fail on the server side if the client fails to send a certificate when requested to do so (when using SSL_VERIFY_PEER on the SSL server). SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client side. Server mode: the verification is the same as SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. If a PSK connection is being made then the connection will go through without a peer cert.
void	wolfSSL_SetCertCbCtx(WOLFSSL * ssl, void * ctx) This function stores user CTX object information for verify callback.
void	wolfSSL_CTX_SetCertCbCtx(WOLFSSL_CTX * ctx, void * userCtx) This function stores user CTX object information for verify callback.
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().
void	wolfSSL_load_error_strings(void ) This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action.
int	wolfSSL_library_init(void ) This function is called internally in wolfSSL_CTX_new(). This function is a wrapper around wolfSSL_Init() and exists for OpenSSL compatibility (SSL_library_init) when wolfSSL has been compiled with OpenSSL compatibility layer. wolfSSL_Init() is the more typically-used wolfSSL initialization function.
int	wolfSSL_SetDevId(WOLFSSL * ssl, int devId) This function sets the Device Id at the WOLFSSL session level.
int	wolfSSL_CTX_SetDevId(WOLFSSL_CTX * ctx, int devId) This function sets the Device Id at the WOLFSSL_CTX context level.
int	wolfSSL_CTX_GetDevId(WOLFSSL_CTX * ctx, WOLFSSL * ssl) This function retrieves the Device Id.
long	wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX * ctx, long mode) This function enables or disables SSL session caching. Behavior depends on the value used for mode. The following values for mode are available: SSL_SESS_CACHE_OFF- disable session caching. Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR - Disable auto-flushing of the session cache. Auto-flushing is turned on by default.
int	wolfSSL_set_session_secret_cb(WOLFSSL * ssl, SessionSecretCb cb, void * ctx) This function sets the session secret callback function. The SessionSecretCb type has the signature: int (SessionSecretCb)(WOLFSSL ssl, void secret, int secretSz, void* ctx). The sessionSecretCb member of the WOLFSSL struct is set to the parameter cb.
int	wolfSSL_save_session_cache(const char * fname) This function persists the session cache to file. It doesn’t use memsave because of additional memory use.
int	wolfSSL_restore_session_cache(const char * fname) This function restores the persistent session cache from file. It does not use memstore because of additional memory use.
int	wolfSSL_memsave_session_cache(void * mem, int sz) This function persists session cache to memory.
int	wolfSSL_memrestore_session_cache(const void * mem, int sz) This function restores the persistent session cache from memory.
int	wolfSSL_get_session_cache_memsize(void ) This function returns how large the session cache save buffer should be.
int	wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX * ctx, const char * fname) This function writes the cert cache from memory to file.
int	wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX * ctx, const char * fname) This function persistes certificate cache from a file.
int	wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX * ctx, void * mem, int sz, int * used) This function persists the certificate cache to memory.
int	wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX * ctx, const void * mem, int sz) This function restores the certificate cache from memory.
int	wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX * ctx) Returns the size the certificate cache save buffer needs to be.
int	wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX * ctx, const char * list) This function sets cipher suite list for a given WOLFSSL_CTX. This cipher suite list becomes the default list for any new SSL sessions (WOLFSSL) created using this context. The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the specific SSL context to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256" Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)
int	wolfSSL_set_cipher_list(WOLFSSL * ssl, const char * list) This function sets cipher suite list for a given WOLFSSL object (SSL session). The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_set_cipher_list() resets the cipher suite list for the specific SSL session to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256". Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)
void	wolfSSL_dtls_set_using_nonblock(WOLFSSL * ssl, int nonblock) This function informs the WOLFSSL DTLS object that the underlying UDP I/O is non_blocking. After an application creates a WOLFSSL object, if it will be used with a non_blocking UDP socket, call wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
int	wolfSSL_dtls_get_using_nonblock(WOLFSSL * ssl) This function allows the application to determine if wolfSSL is using non_blocking I/O with UDP. 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 UDP socket, call wolfSSL_dtls_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. This function is only meaningful to DTLS sessions.
int	wolfSSL_dtls_get_current_timeout(WOLFSSL * ssl) This function returns the current timeout value in seconds for the WOLFSSL object. When using non-blocking sockets, something in the user code needs to decide when to check for available recv data and how long it has been waiting. The value returned by this function indicates how long the application should wait.
int	wolfSSL_dtls13_use_quick_timeout(WOLFSSL * ssl) This function returns true if the application should setup a quicker timeout. When using non_blocking sockets, something in the user code needs to decide when to check for available data and how long it needs to wait. If this function returns true, it means that the library already detected some disruption in the communication, but it wants to wait for a little longer in case some messages from the other peers are still in flight. Is up to the application to fine tune the value of this timer, a good one may be dtls_get_current_timeout() / 4.
void	wolfSSL_dtls13_set_send_more_acks(WOLFSSL * ssl, int value) This function sets whether the library should send ACKs to the other peer immediately when detecting disruption or not. Sending ACKs immediately assures minimum latency but it may consume more bandwidth than necessary. If the application manages the timer by itself and this option is set to 0 then application code can use wolfSSL_dtls13_use_quick_timeout() to determine if it should setup a quicker timeout to send those delayed ACKs.
int	wolfSSL_dtls_set_timeout_init(WOLFSSL * ssl, int ) This function sets the dtls timeout.
int	wolfSSL_dtls_set_timeout_max(WOLFSSL * ssl, int ) This function sets the maximum dtls timeout.
int	wolfSSL_dtls_got_timeout(WOLFSSL * ssl) When using non-blocking sockets with DTLS, this function should be called on the WOLFSSL object when the controlling code thinks the transmission has timed out. It performs the actions needed to retry the last transmit, including adjusting the timeout value. If it has been too long, this will return a failure.
int	wolfSSL_dtls_retransmit(WOLFSSL * ssl) When using non-blocking sockets with DTLS, this function retransmits the last handshake flight ignoring the expected timeout value and retransmit count. It is useful for applications that are using DTLS and need to manage even the timeout and retry count.
int	wolfSSL_dtls(WOLFSSL * ssl) This function is used to determine if the SSL session has been configured to use DTLS.
int	wolfSSL_dtls_set_peer(WOLFSSL * ssl, void * peer, unsigned int peerSz) This function sets the DTLS peer, peer (sockaddr_in) with size of peerSz.
int	wolfSSL_dtls_get_peer(WOLFSSL * ssl, void * peer, unsigned int * peerSz) This function gets the sockaddr_in (of size peerSz) of the current DTLS peer. The function will compare peerSz to the actual DTLS peer size stored in the SSL session. If the peer will fit into peer, the peer’s sockaddr_in will be copied into peer, with peerSz set to the size of peer.
char *	wolfSSL_ERR_error_string(unsigned long errNumber, char * data) This function converts an error code returned by wolfSSL_get_error() into a more human_readable error string. errNumber is the error code returned by wolfSSL_get_error() and data is the storage buffer which the error string will be placed in. The maximum length of data is 80 characters by default, as defined by MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h.
void	wolfSSL_ERR_error_string_n(unsigned long e, char * buf, unsigned long sz) This function is a version of wolfSSL_ERR_error_string() where len specifies the maximum number of characters that may be written to buf. Like wolfSSL_ERR_error_string(), this function converts an error code returned from wolfSSL_get_error() into a more human-readable error string. The human-readable string is placed in buf.
int	wolfSSL_get_shutdown(const WOLFSSL * ssl) This function checks the shutdown conditions in closeNotify or connReset or sentNotify members of the Options structure. The Options structure is within the WOLFSSL structure.
int	wolfSSL_session_reused(WOLFSSL * ssl) This function returns the resuming member of the options struct. The flag indicates whether or not to reuse a session. If not, a new session must be established.
int	wolfSSL_is_init_finished(WOLFSSL * ssl) This function checks to see if the connection is established.
const char *	wolfSSL_get_version(WOLFSSL * ssl) Returns the SSL version being used as a string.
int	wolfSSL_get_current_cipher_suite(WOLFSSL * ssl) Returns the current cipher suit an ssl session is using.
WOLFSSL_CIPHER *	wolfSSL_get_current_cipher(WOLFSSL * ssl) This function returns a pointer to the current cipher in the ssl session.
const char *	wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER * cipher) This function matches the cipher suite in the SSL object with the available suites and returns the string representation.
const char *	wolfSSL_get_cipher(WOLFSSL * ) This function matches the cipher suite in the SSL object with the available suites.
WOLFSSL_SESSION *	wolfSSL_get1_session(WOLFSSL * ssl) This function returns the WOLFSSL_SESSION from the WOLFSSL structure as a reference type. This requires calling wolfSSL_SESSION_free to release the session reference. The WOLFSSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get1_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. The object returned by wolfSSL_get1_session() needs to be freed after the application is done with it by calling wolfSSL_SESSION_free() on it.
WOLFSSL_METHOD *	wolfSSLv23_client_method(void ) The wolfSSLv23_client_method() function is used to indicate that the application is a client and will support the highest protocol version supported by the server between SSL 3.0 _ TLS 1.3. This function allocates memory for and initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). Both wolfSSL clients and servers have robust version downgrade capability. If a specific protocol version method is used on either side, then only that version will be negotiated or an error will be returned. For example, a client that uses TLSv1 and tries to connect to a SSLv3 only server will fail, likewise connecting to a TLSv1.1 will fail as well. To resolve this issue, a client that uses the wolfSSLv23_client_method() function will use the highest protocol version supported by the server and downgrade to SSLv3 if needed. In this case, the client will be able to connect to a server running SSLv3 - TLSv1.3.
int	wolfSSL_BIO_get_mem_data(WOLFSSL_BIO * bio, void * p) This is used to set a byte pointer to the start of the internal memory buffer.
long	wolfSSL_BIO_set_fd(WOLFSSL_BIO * b, int fd, int flag) Sets the file descriptor for bio to use.
int	wolfSSL_BIO_set_close(WOLFSSL_BIO * b, long flag) Sets the close flag, used to indicate that the i/o stream should be closed when the BIO is freed.
WOLFSSL_BIO_METHOD *	wolfSSL_BIO_s_socket(void ) This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
int	wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO * b, long size) This is used to set the size of write buffer for a WOLFSSL_BIO. If write buffer has been previously set this function will free it when resetting the size. It is similar to wolfSSL_BIO_reset in that it resets read and write indexes to 0.
int	wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO * b1, WOLFSSL_BIO * b2) This is used to pair two bios together. A pair of bios acts similar to a two way pipe writing to one can be read by the other and vice versa. It is expected that both bios be in the same thread, this function is not thread safe. Freeing one of the two bios removes both from being paired. If a write buffer size was not previously set for either of the bios it is set to a default size of 17000 (WOLFSSL_BIO_SIZE) before being paired.
int	wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO * bio) This is used to set the read request flag back to 0.
int	wolfSSL_BIO_nread0(WOLFSSL_BIO * bio, char ** buf) This is used to get a buffer pointer for reading from. Unlike wolfSSL_BIO_nread the internal read index is not advanced by the number returned from the function call. Reading past the value returned can result in reading out of array bounds.
int	wolfSSL_BIO_nread(WOLFSSL_BIO * bio, char ** buf, int num) This is used to get a buffer pointer for reading from. The internal read index is advanced by the number returned from the function call with buf being pointed to the beginning of the buffer to read from. In the case that less bytes are in the read buffer than the value requested with num the lesser value is returned. Reading past the value returned can result in reading out of array bounds.
int	wolfSSL_BIO_nwrite(WOLFSSL_BIO * bio, char ** buf, int num) Gets a pointer to the buffer for writing as many bytes as returned by the function. Writing more bytes to the pointer returned then the value returned can result in writing out of bounds.
int	wolfSSL_BIO_reset(WOLFSSL_BIO * bio) Resets bio to an initial state. As an example for type BIO_BIO this resets the read and write index.
int	wolfSSL_BIO_seek(WOLFSSL_BIO * bio, int ofs) This function adjusts the file pointer to the offset given. This is the offset from the head of the file.
int	wolfSSL_BIO_write_filename(WOLFSSL_BIO * bio, char * name) This is used to set and write to a file. WIll overwrite any data currently in the file and is set to close the file when the bio is freed.
long	wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO * bio, int v) This is used to set the end of file value. Common value is -1 so as not to get confused with expected positive values.
long	wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO * bio, WOLFSSL_BUF_MEM ** m) This is a getter function for WOLFSSL_BIO memory pointer.
char *	wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME * name, char * in, int sz) This function copies the name of the x509 into a buffer.
WOLFSSL_X509_NAME *	wolfSSL_X509_get_issuer_name(WOLFSSL_X509 * cert) This function returns the name of the certificate issuer.
WOLFSSL_X509_NAME *	wolfSSL_X509_get_subject_name(WOLFSSL_X509 * cert) This function returns the subject member of the WOLFSSL_X509 structure.
int	wolfSSL_X509_get_isCA(WOLFSSL_X509 * cert) Checks the isCa member of the WOLFSSL_X509 structure and returns the value.
int	wolfSSL_X509_NAME_get_text_by_NID(WOLFSSL_X509_NAME * name, int nid, char * buf, int len) This function gets the text related to the passed in NID value.
int	wolfSSL_X509_get_signature_type(WOLFSSL_X509 * cert) This function returns the value stored in the sigOID member of the WOLFSSL_X509 structure.
void	wolfSSL_X509_free(WOLFSSL_X509 * x509) This function frees a WOLFSSL_X509 structure.
int	wolfSSL_X509_get_signature(WOLFSSL_X509 * x509, unsigned char * buf, int * bufSz) Gets the X509 signature and stores it in the buffer.
int	wolfSSL_X509_STORE_add_cert(WOLFSSL_X509_STORE * store, WOLFSSL_X509 * x509) This function adds a certificate to the WOLFSSL_X509_STRE structure.
WOLFSSL_STACK *	wolfSSL_X509_STORE_CTX_get_chain(WOLFSSL_X509_STORE_CTX * ctx) This function is a getter function for chain variable in WOLFSSL_X509_STORE_CTX structure. Currently chain is not populated.
int	wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE * store, unsigned long flag) This function takes in a flag to change the behavior of the WOLFSSL_X509_STORE structure passed in. An example of a flag used is WOLFSSL_CRL_CHECK.
const byte *	wolfSSL_X509_notBefore(WOLFSSL_X509 * x509) This function the certificate "not before" validity encoded as a byte array.
const byte *	wolfSSL_X509_notAfter(WOLFSSL_X509 * x509) This function the certificate "not after" validity encoded as a byte array.
WOLFSSL_BIGNUM *	wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGER * ai, WOLFSSL_BIGNUM * bn) This function is used to copy a WOLFSSL_ASN1_INTEGER value to a WOLFSSL_BIGNUM structure.
long	wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX * ctx, WOLFSSL_X509 * x509) This function adds the certificate to the internal chain being built in the WOLFSSL_CTX structure.
int	wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX * ctx) This function returns the get read ahead flag from a WOLFSSL_CTX structure.
int	wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX * ctx, int v) This function sets the read ahead flag in the WOLFSSL_CTX structure.
long	wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX * ctx, void * arg) This function sets the options argument to use with OCSP.
long	wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(WOLFSSL_CTX * ctx, void * arg) This function sets the optional argument to be passed to the PRF callback.
long	wolfSSL_set_options(WOLFSSL * s, long op) This function sets the options mask in the ssl. Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE, SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_COMPRESSION.
long	wolfSSL_get_options(const WOLFSSL * ssl) This function returns the current options mask.
long	wolfSSL_set_tlsext_debug_arg(WOLFSSL * ssl, void * arg) This is used to set the debug argument passed around.
long	wolfSSL_set_tlsext_status_type(WOLFSSL * s, int type) This function is called when the client application request that a server send back an OCSP status response (also known as OCSP stapling).Currently, the only supported type is TLSEXT_STATUSTYPE_ocsp.
long	wolfSSL_get_verify_result(const WOLFSSL * ssl) This is used to get the results after trying to verify the peer's certificate.
void	wolfSSL_ERR_print_errors_fp(XFILE fp, int err) This function converts an error code returned by wolfSSL_get_error() into a more human_readable error string and prints that string to the output file _ fp. err is the error code returned by wolfSSL_get_error() and fp is the file which the error string will be placed in.
void	wolfSSL_ERR_print_errors_cb(int()(const char str, size_t len, void *u) cb, void * u) This function uses the provided callback to handle error reporting. The callback function is executed for each error line. The string, length, and userdata are passed into the callback parameters.
void	wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX * ctx, wc_psk_client_callback cb) The function sets the client_psk_cb member of the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_client_callback(WOLFSSL * ssl, wc_psk_client_callback ) Sets the PSK client side callback.
const char *	wolfSSL_get_psk_identity_hint(const WOLFSSL * ) This function returns the psk identity hint.
const char *	wolfSSL_get_psk_identity(const WOLFSSL * ) The function returns a constant pointer to the client_identity member of the Arrays structure.
int	wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX * ctx, const char * hint) This function stores the hint argument in the server_hint member of the WOLFSSL_CTX structure.
int	wolfSSL_use_psk_identity_hint(WOLFSSL * ssl, const char * hint) This function stores the hint argument in the server_hint member of the Arrays structure within the WOLFSSL structure.
void	wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX * ctx, wc_psk_server_callback cb) This function sets the psk callback for the server side in the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_server_callback(WOLFSSL * ssl, wc_psk_server_callback cb) Sets the psk callback for the server side by setting the WOLFSSL structure options members.
int	wolfSSL_set_psk_callback_ctx(WOLFSSL * ssl, void * psk_ctx) Sets a PSK user context in the WOLFSSL structure options member.
int	wolfSSL_CTX_set_psk_callback_ctx(WOLFSSL_CTX * ctx, void * psk_ctx) Sets a PSK user context in the WOLFSSL_CTX structure.
void *	wolfSSL_get_psk_callback_ctx(WOLFSSL * ssl) Get a PSK user context in the WOLFSSL structure options member.
void *	wolfSSL_CTX_get_psk_callback_ctx(WOLFSSL_CTX * ctx) Get a PSK user context in the WOLFSSL_CTX structure.
int	wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX * ) This function enables the havAnon member of the CTX structure if HAVE_ANON is defined during compilation.
WOLFSSL_METHOD *	wolfSSLv23_server_method(void ) The wolfSSLv23_server_method() function is used to indicate that the application is a server and will support clients connecting with protocol version from SSL 3.0 _ TLS 1.3. This function allocates memory for and initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
int	wolfSSL_state(WOLFSSL * ssl) This is used to get the internal error state of the WOLFSSL structure.
WOLFSSL_X509 *	wolfSSL_get_peer_certificate(WOLFSSL * ssl) This function gets the peer’s certificate.
int	wolfSSL_want_read(WOLFSSL * ) This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_READ in return. If the underlying error state is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.
int	wolfSSL_want_write(WOLFSSL * ) This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_WRITE in return. If the underlying error state is SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.
int	wolfSSL_check_domain_name(WOLFSSL * ssl, const char * dn) wolfSSL by default checks the peer certificate for a valid date range and a verified signature. Calling this function before wolfSSL_connect() or wolfSSL_accept() will add a domain name check to the list of checks to perform. dn holds the domain name to check against the peer certificate when it’s received.
int	wolfSSL_Init(void ) Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library.
int	wolfSSL_Cleanup(void ) Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it will free any resources used by the library.
const char *	wolfSSL_lib_version(void ) This function returns the current library version.
word32	wolfSSL_lib_version_hex(void ) This function returns the current library version in hexadecimal notation.
int	wolfSSL_negotiate(WOLFSSL * ssl) Performs the actual connect or accept based on the side of the SSL method. If called from the client side then an wolfSSL_connect() is done while a wolfSSL_accept() is performed if called from the server side.
int	wolfSSL_set_compression(WOLFSSL * ssl) Turns on the ability to use compression for the SSL connection. Both sides must have compression turned on otherwise compression will not be used. The zlib library performs the actual data compression. To compile into the library use –with-libz for the configure system and define HAVE_LIBZ otherwise. Keep in mind that while compressing data before sending decreases the actual size of the messages being sent and received, the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks.
int	wolfSSL_set_timeout(WOLFSSL * ssl, unsigned int to) This function sets the SSL session timeout value in seconds.
int	wolfSSL_CTX_set_timeout(WOLFSSL_CTX * ctx, unsigned int to) This function sets the timeout value for SSL sessions, in seconds, for the specified SSL context.
WOLFSSL_X509_CHAIN *	wolfSSL_get_peer_chain(WOLFSSL * ssl) Retrieves the peer’s certificate chain.
int	wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN * chain) Retrieve's the peers certificate chain count.
int	wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN * chain, int idx) Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx).
unsigned char *	wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN * chain, int idx) Retrieves the peer’s ASN1.DER certificate at index (idx).
WOLFSSL_X509 *	wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN * chain, int idx) This function gets the peer’s wolfSSL_X509_certificate at index (idx) from the chain of certificates.
int	wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN * chain, int idx, unsigned char * buf, int inLen, int * outLen) Retrieves the peer’s PEM certificate at index (idx).
const unsigned char *	wolfSSL_get_sessionID(const WOLFSSL_SESSION * s) Retrieves the session’s ID. The session ID is always 32 bytes long.
int	wolfSSL_X509_get_serial_number(WOLFSSL_X509 * x509, unsigned char * in, int * inOutSz) Retrieves the peer’s certificate serial number. The serial number buffer (in) should be at least 32 bytes long and be provided as the inOutSz argument as input. After calling the function inOutSz will hold the actual length in bytes written to the in buffer.
char *	wolfSSL_X509_get_subjectCN(WOLFSSL_X509 * ) Returns the common name of the subject from the certificate.
const unsigned char *	wolfSSL_X509_get_der(WOLFSSL_X509 * x509, int * outSz) This function gets the DER encoded certificate in the WOLFSSL_X509 struct.
WOLFSSL_ASN1_TIME *	wolfSSL_X509_get_notAfter(WOLFSSL_X509 * ) This function checks to see if x509 is NULL and if it’s not, it returns the notAfter member of the x509 struct.
int	wolfSSL_X509_version(WOLFSSL_X509 * ) This function retrieves the version of the X509 certificate.
WOLFSSL_X509 *	wolfSSL_X509_d2i_fp(WOLFSSL_X509 ** x509, FILE * file) If NO_STDIO_FILESYSTEM is defined this function will allocate heap memory, initialize a WOLFSSL_X509 structure and return a pointer to it.
WOLFSSL_X509 *	wolfSSL_X509_load_certificate_file(const char * fname, int format) The function loads the x509 certificate into memory.
unsigned char *	wolfSSL_X509_get_device_type(WOLFSSL_X509 * x509, unsigned char * in, int * inOutSz) This function copies the device type from the x509 structure to the buffer.
unsigned char *	wolfSSL_X509_get_hw_type(WOLFSSL_X509 * x509, unsigned char * in, int * inOutSz) The function copies the hwType member of the WOLFSSL_X509 structure to the buffer.
unsigned char *	wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509 * x509, unsigned char * in, int * inOutSz) This function returns the hwSerialNum member of the x509 object.
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.
WC_PKCS12 *	wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO * bio, WC_PKCS12 ** pkcs12) wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 information from WOLFSSL_BIO to the structure WC_PKCS12. The information is divided up in the structure as a list of Content Infos along with a structure to hold optional MAC information. After the information has been divided into chunks (but not decrypted) in the structure WC_PKCS12, it can then be parsed and decrypted by calling.
WC_PKCS12 *	wolfSSL_i2d_PKCS12_bio(WOLFSSL_BIO * bio, WC_PKCS12 * pkcs12) wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert information from the structure WC_PKCS12 to WOLFSSL_BIO.
int	wolfSSL_PKCS12_parse(WC_PKCS12 * pkcs12, const char * psw, WOLFSSL_EVP_PKEY pkey, WOLFSSL_X509 cert, WOLF_STACK_OF(WOLFSSL_X509) ** ca) PKCS12 can be enabled with adding –enable_opensslextra to the configure command. It can use triple DES and RC4 for decryption so would recommend also enabling these features when enabling opensslextra (–enable_des3 –enable_arc4). wolfSSL does not currently support RC2 so decryption with RC2 is currently not available. This may be noticeable with default encryption schemes used by OpenSSL command line to create .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this function does is check the MAC is correct if present. If the MAC fails then the function returns and does not try to decrypt any of the stored Content Infos. This function then parses through each Content Info looking for a bag type, if the bag type is known it is decrypted as needed and either stored in the list of certificates being built or as a key found. After parsing through all bags the key found is then compared with the certificate list until a matching pair is found. This matching pair is then returned as the key and certificate, optionally the certificate list found is returned as a STACK_OF certificates. At the moment a CRL, Secret or SafeContents bag will be skipped over and not parsed. It can be seen if these or other “Unknown” bags are skipped over by viewing the debug print out. Additional attributes such as friendly name are skipped over when parsing a PKCS12 file.
int	wolfSSL_SetTmpDH(WOLFSSL * ssl, const unsigned char * p, int pSz, const unsigned char * g, int gSz) Server Diffie-Hellman Ephemeral parameters setting. This function sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE.
int	wolfSSL_SetTmpDH_buffer(WOLFSSL * ssl, const unsigned char * b, long sz, int format) The function calls the wolfSSL_SetTMpDH_buffer_wrapper, which is a wrapper for Diffie-Hellman parameters.
int	wolfSSL_SetTmpDH_file(WOLFSSL * ssl, const char * f, int format) This function calls wolfSSL_SetTmpDH_file_wrapper to set server Diffie-Hellman parameters.
int	wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX * ctx, const unsigned char * p, int pSz, const unsigned char * g, int gSz) Sets the parameters for the server CTX Diffie-Hellman.
int	wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX * ctx, const unsigned char * b, long sz, int format) A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper.
int	wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX * ctx, const char * f, int format) The function calls wolfSSL_SetTmpDH_file_wrapper to set the server Diffie-Hellman parameters.
int	wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX * ctx, word16 ) This function sets the minimum size (in bits) of the Diffie Hellman key size by accessing the minDhKeySz member in the WOLFSSL_CTX structure.
int	wolfSSL_SetMinDhKey_Sz(WOLFSSL * ssl, word16 keySz_bits) Sets the minimum size (in bits) for a Diffie-Hellman key in the WOLFSSL structure.
int	wolfSSL_CTX_SetMaxDhKey_Sz(WOLFSSL_CTX * ctx, word16 keySz_bits) This function sets the maximum size (in bits) of the Diffie Hellman key size by accessing the maxDhKeySz member in the WOLFSSL_CTX structure.
int	wolfSSL_SetMaxDhKey_Sz(WOLFSSL * ssl, word16 keySz_bits) Sets the maximum size (in bits) for a Diffie-Hellman key in the WOLFSSL structure.
int	wolfSSL_GetDhKey_Sz(WOLFSSL * ) Returns the value of dhKeySz (in bits) that is a member of the options structure. This value represents the Diffie-Hellman key size in bytes.
int	wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX * ctx, short keySz) Sets the minimum RSA key size in both the WOLFSSL_CTX structure and the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_SetMinRsaKey_Sz(WOLFSSL * ssl, short keySz) Sets the minimum allowable key size in bits for RSA located in the WOLFSSL structure.
int	wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX * ssl, short keySz) Sets the minimum size in bits for the ECC key in the WOLF_CTX structure and the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_SetMinEccKey_Sz(WOLFSSL * ssl, short keySz) Sets the value of the minEccKeySz member of the options structure. The options struct is a member of the WOLFSSL structure and is accessed through the ssl parameter.
int	wolfSSL_make_eap_keys(WOLFSSL * ssl, void * key, unsigned int len, const char * label) This function is used by EAP_TLS and EAP-TTLS to derive keying material from the master secret.
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.
int	wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX * ) This function unloads the CA signer list and frees the whole signer table.
int	wolfSSL_CTX_UnloadIntermediateCerts(WOLFSSL_CTX * ctx) This function unloads intermediate certificates added to the CA signer list and frees them.
int	wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX * ) This function is used to unload all previously loaded trusted peer certificates. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT.
int	wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a certificate to use for verifying a peer when performing a TLS/SSL handshake. The peer certificate sent during the handshake is compared by using the SKID when available and the signature. If these two things do not match then any loaded CAs are used. Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from a buffer instead of a file. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage.
int	wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a CA certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_load_verify_buffer_ex(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format, int userChain, word32 flags) This function loads a CA certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. The _ex version was added in PR 2413 and supports additional arguments for userChain and flags.
int	wolfSSL_CTX_load_verify_chain_buffer_format(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a CA certificate chain buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a private key buffer into the SSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz) This function loads a certificate chain buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. The buffer must be in PEM format and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage.
int	wolfSSL_use_certificate_buffer(WOLFSSL * ssl, const unsigned char * in, long sz, int format) This function loads a certificate buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_use_PrivateKey_buffer(WOLFSSL * ssl, const unsigned char * in, long sz, int format) This function loads a private key buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.
int	wolfSSL_use_certificate_chain_buffer(WOLFSSL * ssl, const unsigned char * in, long sz) This function loads a certificate chain buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. The buffer must be in PEM format and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage.
int	wolfSSL_UnloadCertsKeys(WOLFSSL * ) This function unloads any certificates or keys that SSL owns.
int	wolfSSL_CTX_set_group_messages(WOLFSSL_CTX * ) This function turns on grouping of handshake messages where possible.
int	wolfSSL_set_group_messages(WOLFSSL * ) This function turns on grouping of handshake messages where possible.
void	wolfSSL_SetFuzzerCb(WOLFSSL * ssl, CallbackFuzzer cbf, void * fCtx) This function sets the fuzzer callback.
int	wolfSSL_DTLS_SetCookieSecret(WOLFSSL * ssl, const unsigned char * secret, unsigned int secretSz) This function sets a new dtls cookie secret.
WC_RNG *	wolfSSL_GetRNG(WOLFSSL * ssl) This function retrieves the random number.
int	wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX * ctx, int version) This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method).
int	wolfSSL_SetMinVersion(WOLFSSL * ssl, int version) This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method).
int	wolfSSL_GetObjectSize(void ) This function returns the size of the WOLFSSL object and will be dependent on build options and settings. If SHOW_SIZES has been defined when building wolfSSL, this function will also print the sizes of individual objects within the WOLFSSL object (Suites, Ciphers, etc.) to stdout.
int	wolfSSL_GetOutputSize(WOLFSSL * ssl, int inSz) Returns the record layer size of the plaintext input. This is helpful when an application wants to know how many bytes will be sent across the Transport layer, given a specified plaintext input size. This function must be called after the SSL/TLS handshake has been completed.
int	wolfSSL_GetMaxOutputSize(WOLFSSL * ) Returns the maximum record layer size for plaintext data. This will correspond to either the maximum SSL/TLS record size as specified by the protocol standard, the maximum TLS fragment size as set by the TLS Max Fragment Length extension. This function is helpful when the application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E error. This function must be called after the SSL/TLS handshake has been completed.
int	wolfSSL_SetVersion(WOLFSSL * ssl, int version) This function sets the SSL/TLS protocol version for the specified SSL session (WOLFSSL object) using the version as specified by version. This will override the protocol setting for the SSL session (ssl) _ originally defined and set by the SSL context (wolfSSL_CTX_new()) method type.
void	wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX * ctx, CallbackMacEncrypti cb) Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. macOut is the output buffer where the result of the mac should be stored. macIn is the mac input buffer and macInSz notes the size of the buffer. macContent and macVerify are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. encOut is the output buffer where the result on the encryption should be stored. encIn is the input buffer to encrypt while encSz is the size of the input. An example callback can be found wolfssl/test.h myMacEncryptCb().
void	wolfSSL_SetMacEncryptCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback Context to ctx.
void *	wolfSSL_GetMacEncryptCtx(WOLFSSL * ssl) Allows caller to retrieve the Atomic User Record Processing Mac/Encrypt Callback Context previously stored with wolfSSL_SetMacEncryptCtx().
void	wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX * ctx, CallbackDecryptVerify cb) Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. decOut is the output buffer where the result of the decryption should be stored. decIn is the encrypted input buffer and decInSz notes the size of the buffer. content and verify are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. padSz is an output variable that should be set with the total value of the padding. That is, the mac size plus any padding and pad bytes. An example callback can be found wolfssl/test.h myDecryptVerifyCb().
void	wolfSSL_SetDecryptVerifyCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context to ctx.
void *	wolfSSL_GetDecryptVerifyCtx(WOLFSSL * ssl) Allows caller to retrieve the Atomic User Record Processing Decrypt/Verify Callback Context previously stored with wolfSSL_SetDecryptVerifyCtx().
const unsigned char *	wolfSSL_GetMacSecret(WOLFSSL * ssl, int verify) Allows retrieval of the Hmac/Mac secret from the handshake process. The verify parameter specifies whether this is for verification of a peer message.
const unsigned char *	wolfSSL_GetClientWriteKey(WOLFSSL * ) Allows retrieval of the client write key from the handshake process.
const unsigned char *	wolfSSL_GetClientWriteIV(WOLFSSL * ) Allows retrieval of the client write IV (initialization vector) from the handshake process.
const unsigned char *	wolfSSL_GetServerWriteKey(WOLFSSL * ) Allows retrieval of the server write key from the handshake process.
const unsigned char *	wolfSSL_GetServerWriteIV(WOLFSSL * ) Allows retrieval of the server write IV (initialization vector) from the handshake process.
int	wolfSSL_GetKeySize(WOLFSSL * ) Allows retrieval of the key size from the handshake process.
int	wolfSSL_GetIVSize(WOLFSSL * ) Returns the iv_size member of the specs structure held in the WOLFSSL struct.
int	wolfSSL_GetSide(WOLFSSL * ) Allows retrieval of the side of this WOLFSSL connection.
int	wolfSSL_IsTLSv1_1(WOLFSSL * ) Allows caller to determine if the negotiated protocol version is at least TLS version 1.1 or greater.
int	wolfSSL_GetBulkCipher(WOLFSSL * ) Allows caller to determine the negotiated bulk cipher algorithm from the handshake.
int	wolfSSL_GetCipherBlockSize(WOLFSSL * ) Allows caller to determine the negotiated cipher block size from the handshake.
int	wolfSSL_GetAeadMacSize(WOLFSSL * ) Allows caller to determine the negotiated aead mac size from the handshake. For cipher type WOLFSSL_AEAD_TYPE.
int	wolfSSL_GetHmacSize(WOLFSSL * ) Allows caller to determine the negotiated (h)mac size from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.
int	wolfSSL_GetHmacType(WOLFSSL * ) Allows caller to determine the negotiated (h)mac type from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.
int	wolfSSL_GetCipherType(WOLFSSL * ) Allows caller to determine the negotiated cipher type from the handshake.
int	wolfSSL_SetTlsHmacInner(WOLFSSL * ssl, byte * inner, word32 sz, int content, int verify) Allows caller to set the Hmac Inner vector for message sending/receiving. The result is written to inner which should be at least wolfSSL_GetHmacSize() bytes. The size of the message is specified by sz, content is the type of message, and verify specifies whether this is a verification of a peer message. Valid for cipher types excluding WOLFSSL_AEAD_TYPE.
void	wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX * ctx, CallbackEccSign cb) Allows caller to set the Public Key Callback for ECC Signing. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to sign while inSz denotes the length of the input. out is the output buffer where the result of the signature should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning. keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccSign().
void	wolfSSL_SetEccSignCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key Ecc Signing Callback Context to ctx.
void *	wolfSSL_GetEccSignCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with wolfSSL_SetEccSignCtx().
void	wolfSSL_CTX_SetEccSignCtx(WOLFSSL_CTX * ctx, void * userCtx) Allows caller to set the Public Key Ecc Signing Callback Context to ctx.
void *	wolfSSL_CTX_GetEccSignCtx(WOLFSSL_CTX * ctx) Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with wolfSSL_SetEccSignCtx().
void	wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX * ctx, CallbackEccVerify cb) Allows caller to set the Public Key Callback for ECC Verification. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. sig is the signature to verify and sigSz denotes the length of the signature. hash is an input buffer containing the digest of the message and hashSz denotes the length in bytes of the hash. result is an output variable where the result of the verification should be stored, 1 for success and 0 for failure. keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccVerify().
void	wolfSSL_SetEccVerifyCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key Ecc Verification Callback Context to ctx.
void *	wolfSSL_GetEccVerifyCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key Ecc Verification Callback Context previously stored with wolfSSL_SetEccVerifyCtx().
void	wolfSSL_CTX_SetRsaSignCb(WOLFSSL_CTX * ctx, CallbackRsaSign cb) Allows caller to set the Public Key Callback for RSA Signing. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to sign while inSz denotes the length of the input. out is the output buffer where the result of the signature should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning. keyDer is the RSA Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaSign().
void	wolfSSL_SetRsaSignCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key RSA Signing Callback Context to ctx.
void *	wolfSSL_GetRsaSignCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key RSA Signing Callback Context previously stored with wolfSSL_SetRsaSignCtx().
void	wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX * ctx, CallbackRsaVerify cb) Allows caller to set the Public Key Callback for RSA Verification. The callback should return the number of plaintext bytes for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. sig is the signature to verify and sigSz denotes the length of the signature. out should be set to the beginning of the verification buffer after the decryption process and any padding. keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaVerify().
void	wolfSSL_SetRsaVerifyCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key RSA Verification Callback Context to ctx.
void *	wolfSSL_GetRsaVerifyCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key RSA Verification Callback Context previously stored with wolfSSL_SetRsaVerifyCtx().
void	wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX * ctx, CallbackRsaEnc cb) Allows caller to set the Public Key Callback for RSA Public Encrypt. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to encrypt while inSz denotes the length of the input. out is the output buffer where the result of the encryption should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the encryption should be stored there before returning. keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaEnc().
void	wolfSSL_SetRsaEncCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key RSA Public Encrypt Callback Context to ctx.
void *	wolfSSL_GetRsaEncCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key RSA Public Encrypt Callback Context previously stored with wolfSSL_SetRsaEncCtx().
void	wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX * ctx, CallbackRsaDec cb) Allows caller to set the Public Key Callback for RSA Private Decrypt. The callback should return the number of plaintext bytes for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to decrypt and inSz denotes the length of the input. out should be set to the beginning of the decryption buffer after the decryption process and any padding. keyDer is the RSA Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaDec().
void	wolfSSL_SetRsaDecCtx(WOLFSSL * ssl, void * ctx) Allows caller to set the Public Key RSA Private Decrypt Callback Context to ctx.
void *	wolfSSL_GetRsaDecCtx(WOLFSSL * ssl) Allows caller to retrieve the Public Key RSA Private Decrypt Callback Context previously stored with wolfSSL_SetRsaDecCtx().
void	wolfSSL_CTX_SetCACb(WOLFSSL_CTX * ctx, CallbackCACache cb) This function registers a callback with the SSL context (WOLFSSL_CTX) to be called when a new CA certificate is loaded into wolfSSL. The callback is given a buffer with the DER-encoded certificate.
WOLFSSL_CERT_MANAGER *	wolfSSL_CertManagerNew_ex(void * heap) Allocates and initializes a new Certificate Manager context. This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status.
WOLFSSL_CERT_MANAGER *	wolfSSL_CertManagerNew(void ) Allocates and initializes a new Certificate Manager context. This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status.
void	wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER * ) Frees all resources associated with the Certificate Manager context. Call this when you no longer need to use the Certificate Manager.
int	wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER * cm, const char * f, const char * d) Specifies the locations for CA certificate loading into the manager context. The PEM certificate CAfile may contain several trusted CA certificates. If CApath is not NULL it specifies a directory containing CA certificates in PEM format.
int	wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER * cm, const unsigned char * in, long sz, int format) Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and returning that result using a temporary cm so as not to lose the information in the cm passed into the function.
int	wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER * cm) This function unloads the CA signer list.
int	wolfSSL_CertManagerUnloadIntermediateCerts(WOLFSSL_CERT_MANAGER * cm) This function unloads intermediate certificates add to the CA signer list.
int	wolfSSL_CertManagerUnload_trust_peers(WOLFSSL_CERT_MANAGER * cm) The function will free the Trusted Peer linked list and unlocks the trusted peer list.
int	wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER * cm, const char * f, int format) Specifies the certificate to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
int	wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER * cm, const unsigned char * buff, long sz, int format) Specifies the certificate buffer to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
void	wolfSSL_CertManagerSetVerify(WOLFSSL_CERT_MANAGER * cm, VerifyCallback vc) The function sets the verifyCallback function in the Certificate Manager. If present, it will be called for each cert loaded. If there is a verification error, the verify callback can be used to over-ride the error.
int	wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER * cm, unsigned char * der, int sz) Check CRL if the option is enabled and compares the cert to the CRL list.
int	wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER * cm, int options) Turns on Certificate Revocation List checking when verifying certificates with the Certificate Manager. By default, CRL checking is off. options include WOLFSSL_CRL_CHECKALL which performs CRL checking on each certificate in the chain versus the Leaf certificate only which is the default.
int	wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANAGER * ) Turns off Certificate Revocation List checking when verifying certificates with the Certificate Manager. By default, CRL checking is off. You can use this function to temporarily or permanently disable CRL checking with this Certificate Manager context that previously had CRL checking enabled.
int	wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER * cm, const char * path, int type, int monitor) Error checks and passes through to LoadCRL() in order to load the cert into the CRL for revocation checking. An updated CRL can be loaded by first calling wolfSSL_CertManagerFreeCRL, then loading the new CRL.
int	wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER * cm, const unsigned char * buff, long sz, int type) The function loads the CRL file by calling BufferLoadCRL.
int	wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER * cm, CbMissingCRL cb) This function sets the CRL Certificate Manager callback. If HAVE_CRL is defined and a matching CRL record is not found then the cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This allows you to externally retrieve the CRL and load it.
int	wolfSSL_CertManagerSetCRLUpdate_Cb(WOLFSSL_CERT_MANAGER * cm, CbUpdateCRL cb) This function sets the CRL Update callback. If HAVE_CRL and HAVE_CRL_UPDATE_CB is defined , and an entry with the same issuer and a lower CRL number exists when a CRL is added, then the CbUpdateCRL is called with the details of the existing entry and the new one replacing it.
int	wolfSSL_CertManagerGetCRLInfo(WOLFSSL_CERT_MANAGER * cm, CrlInfo * info, const byte * buff, long sz, int type) This function yields a structure with parsed CRL information from an encoded CRL buffer.
int	wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER * cm, unsigned char * der, int sz) The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled to signify that the OCSP check option is enabled.
int	wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER * cm, int options) Turns on OCSP if it’s turned off and if compiled with the set option available.
int	wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER * ) Disables OCSP certificate revocation.
int	wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER * cm, const char * url) The function copies the url to the ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER * cm, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb, void * ioCbCtx) The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER.
int	wolfSSL_CertManagerEnableOCSPStapling(WOLFSSL_CERT_MANAGER * cm) This function turns on OCSP stapling if it is not turned on as well as set the options.
int	wolfSSL_EnableCRL(WOLFSSL * ssl, int options) Enables CRL certificate revocation.
int	wolfSSL_DisableCRL(WOLFSSL * ssl) Disables CRL certificate revocation.
int	wolfSSL_LoadCRL(WOLFSSL * ssl, const char * path, int type, int monitor) A wrapper function that ends up calling LoadCRL to load the certificate for revocation checking.
int	wolfSSL_SetCRL_Cb(WOLFSSL * ssl, CbMissingCRL cb) Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_EnableOCSP(WOLFSSL * ssl, int options) This function enables OCSP certificate verification. The value of options if formed by or’ing one or more of the following options: WOLFSSL_OCSP_URL_OVERRIDE _ use the override URL instead of the URL in certificates. The override URL is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests.
int	wolfSSL_DisableOCSP(WOLFSSL * ) Disables the OCSP certificate revocation option.
int	wolfSSL_SetOCSP_OverrideURL(WOLFSSL * ssl, const char * url) This function sets the ocspOverrideURL member in the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_SetOCSP_Cb(WOLFSSL * ssl, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb, void * ioCbCtx) This function sets the OCSP callback in the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_CTX_EnableCRL(WOLFSSL_CTX * ctx, int options) Enables CRL certificate verification through the CTX.
int	wolfSSL_CTX_DisableCRL(WOLFSSL_CTX * ctx) This function disables CRL verification in the CTX structure.
int	wolfSSL_CTX_LoadCRL(WOLFSSL_CTX * ctx, const char * path, int type, int monitor) This function loads CRL into the WOLFSSL_CTX structure through wolfSSL_CertManagerLoadCRL().
int	wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX * ctx, CbMissingCRL cb) This function will set the callback argument to the cbMissingCRL member of the WOLFSSL_CERT_MANAGER structure by calling wolfSSL_CertManagerSetCRL_Cb.
int	wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX * ctx, int options) This function sets options to configure behavior of OCSP functionality in wolfSSL. The value of options if formed by or’ing one or more of the following options: WOLFSSL_OCSP_URL_OVERRIDE _ use the override URL instead of the URL in certificates. The override URL is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests.
int	wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX * ) This function disables OCSP certificate revocation checking by affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure.
int	wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX * ctx, const char * url) This function manually sets the URL for OCSP to use. By default, OCSP will use the URL found in the individual certificate unless the WOLFSSL_OCSP_URL_OVERRIDE option is set using the wolfSSL_CTX_EnableOCSP.
int	wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX * ctx, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb, void * ioCbCtx) Sets the callback for the OCSP in the WOLFSSL_CTX structure.
int	wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX * ) This function enables OCSP stapling by calling wolfSSL_CertManagerEnableOCSPStapling().
void	wolfSSL_KeepArrays(WOLFSSL * ) Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. Calling this function before the handshake begins will prevent wolfSSL from freeing temporary arrays. Temporary arrays may be needed for things such as wolfSSL_get_keys() or PSK hints. When the user is done with temporary arrays, either wolfSSL_FreeArrays() may be called to free the resources immediately, or alternatively the resources will be freed when the associated SSL object is freed.
void	wolfSSL_FreeArrays(WOLFSSL * ) Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. If wolfSSL_KeepArrays() has been called before the handshake, wolfSSL will not free temporary arrays. This function explicitly frees temporary arrays and should be called when the user is done with temporary arrays and does not want to wait for the SSL object to be freed to free these resources.
int	wolfSSL_UseSNI(WOLFSSL * ssl, unsigned char type, const void * data, unsigned short size) This function enables the use of Server Name Indication in the SSL object passed in the 'ssl' parameter. It means that the SNI extension will be sent on ClientHello by wolfSSL client and wolfSSL server will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.
int	wolfSSL_CTX_UseSNI(WOLFSSL_CTX * ctx, unsigned char type, const void * data, unsigned short size) This function enables the use of Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the SNI extension will be sent on ClientHello by wolfSSL clients and wolfSSL servers will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.
void	wolfSSL_SNI_SetOptions(WOLFSSL * ssl, unsigned char type, unsigned char options) This function is called on the server side to configure the behavior of the SSL session using Server Name Indication in the SSL object passed in the 'ssl' parameter. The options are explained below.
void	wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX * ctx, unsigned char type, unsigned char options) This function is called on the server side to configure the behavior of the SSL sessions using Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. The options are explained below.
int	wolfSSL_SNI_GetFromBuffer(const unsigned char * clientHello, unsigned int helloSz, unsigned char type, unsigned char * sni, unsigned int * inOutSz) This function is called on the server side to retrieve the Server Name Indication provided by the client from the Client Hello message sent by the client to start a session. It does not requires context or session setup to retrieve the SNI.
unsigned char	wolfSSL_SNI_Status(WOLFSSL * ssl, unsigned char type) This function gets the status of an SNI object.
unsigned short	wolfSSL_SNI_GetRequest(WOLFSSL * ssl, unsigned char type, void ** data) This function is called on the server side to retrieve the Server Name Indication provided by the client in a SSL session.
int	wolfSSL_UseALPN(WOLFSSL * ssl, char * protocol_name_list, unsigned int protocol_name_listSz, unsigned char options) Setup ALPN use for a wolfSSL session.
int	wolfSSL_ALPN_GetProtocol(WOLFSSL * ssl, char ** protocol_name, unsigned short * size) This function gets the protocol name set by the server.
int	wolfSSL_ALPN_GetPeerProtocol(WOLFSSL * ssl, char ** list, unsigned short * listSz) This function copies the alpn_client_list data from the SSL object to the buffer.
int	wolfSSL_UseMaxFragment(WOLFSSL * ssl, unsigned char mfl) This function is called on the client side to enable the use of Maximum Fragment Length in the SSL object passed in the 'ssl' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients.
int	wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX * ctx, unsigned char mfl) This function is called on the client side to enable the use of Maximum Fragment Length for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients.
int	wolfSSL_UseTruncatedHMAC(WOLFSSL * ssl) This function is called on the client side to enable the use of Truncated HMAC in the SSL object passed in the 'ssl' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients.
int	wolfSSL_CTX_UseTruncatedHMAC(WOLFSSL_CTX * ctx) This function is called on the client side to enable the use of Truncated HMAC for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients.
int	wolfSSL_UseOCSPStapling(WOLFSSL * ssl, unsigned char status_type, unsigned char options) Stapling eliminates the need to contact the CA. Stapling lowers the cost of certificate revocation check presented in OCSP.
int	wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX * ctx, unsigned char status_type, unsigned char options) This function requests the certificate status during the handshake.
int	wolfSSL_UseOCSPStaplingV2(WOLFSSL * ssl, unsigned char status_type, unsigned char options) The function sets the status type and options for OCSP.
int	wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX * ctx, unsigned char status_type, unsigned char options) Creates and initializes the certificate status request for OCSP Stapling.
int	wolfSSL_UseSupportedCurve(WOLFSSL * ssl, word16 name) This function is called on the client side to enable the use of Supported Elliptic Curves Extension in the SSL object passed in the 'ssl' parameter. It means that the supported curves enabled will be sent on ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves.
int	wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX * ctx, word16 name) This function is called on the client side to enable the use of Supported Elliptic Curves Extension for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the supported curves enabled will be sent on ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves.
int	wolfSSL_UseSecureRenegotiation(WOLFSSL * ssl) This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended.
int	wolfSSL_Rehandshake(WOLFSSL * ssl) This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality.
int	wolfSSL_UseSessionTicket(WOLFSSL * ssl) Force provided WOLFSSL structure to use session ticket. The constant HAVE_SESSION_TICKET should be defined and the constant NO_WOLFSSL_CLIENT should not be defined to use this function.
int	wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX * ctx) This function sets wolfSSL context to use a 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.
int	wolfSSL_set_SessionTicket(WOLFSSL * ssl, const unsigned char * buf, word32 bufSz) This function sets the ticket member of the WOLFSSL_SESSION structure within the WOLFSSL struct. The buffer passed into the function is copied to memory.
int	wolfSSL_set_SessionTicket_cb(WOLFSSL * ssl, CallbackSessionTicket cb, void * ctx) This function sets the session ticket callback. The type CallbackSessionTicket is a function pointer with the signature of: int (CallbackSessionTicket)(WOLFSSL, const unsigned char, int, void)
int	wolfSSL_send_SessionTicket(WOLFSSL * ssl) This function sends a session ticket to the client after a TLS v1.3 handhsake has been established.
int	wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX * ctx, SessionTicketEncCb ) This function sets the session ticket key encrypt callback function for a server to support session tickets as specified in RFC 5077.
int	wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX * ctx, int ) This function sets the session ticket hint relayed to the client. For server side use.
int	wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX * ctx, void * ) This function sets the session ticket encrypt user context for the callback. For server side use.
void *	wolfSSL_CTX_get_TicketEncCtx(WOLFSSL_CTX * ctx) This function gets the session ticket encrypt user context for the callback. For server side use.
int	wolfSSL_SetHsDoneCb(WOLFSSL * ssl, HandShakeDoneCb cb, void * user_ctx) This function sets the handshake done callback. The hsDoneCb and hsDoneCtx members of the WOLFSSL structure are set in this function.
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.
int	wolfSSL_MakeTlsMasterSecret(unsigned char * ms, word32 msLen, const unsigned char * pms, word32 pmsLen, const unsigned char * cr, const unsigned char * sr, int tls1_2, int hash_type) This function copies the values of cr and sr then passes through to wc_PRF (pseudo random function) and returns that value.
int	wolfSSL_DeriveTlsKeys(unsigned char * key_data, word32 keyLen, const unsigned char * ms, word32 msLen, const unsigned char * sr, const unsigned char * cr, int tls1_2, int hash_type) An external facing wrapper to derive TLS Keys.
int	wolfSSL_connect_ex(WOLFSSL * ssl, HandShakeCallBack hsCb, TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout) wolfSSL_connect_ex() is an extension that allows a HandShake Callback to be set. This can be useful in embedded systems for debugging support when a debugger isn’t available and sniffing is impractical. The HandShake Callback will be called whether or not a handshake error occurred. No dynamic memory is used since the maximum number of SSL packets is known. Packet names can be accessed through packetNames[]. The connect extension also allows a Timeout Callback to be set along with a timeout value. This is useful if the user doesn’t want to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks.
int	wolfSSL_accept_ex(WOLFSSL * ssl, HandShakeCallBacki hsCb, TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout) wolfSSL_accept_ex() is an extension that allows a HandShake Callback to be set. This can be useful in embedded systems for debugging support when a debugger isn’t available and sniffing is impractical. The HandShake Callback will be called whether or not a handshake error occurred. No dynamic memory is used since the maximum number of SSL packets is known. Packet names can be accessed through packetNames[]. The connect extension also allows a Timeout Callback to be set along with a timeout value. This is useful if the user doesn’t want to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks.
long	wolfSSL_BIO_set_fp(WOLFSSL_BIO * bio, XFILE fp, int c) This is used to set the internal file pointer for a BIO.
long	wolfSSL_BIO_get_fp(WOLFSSL_BIO * bio, XFILE * fp) This is used to get the internal file pointer for a BIO.
int	wolfSSL_check_private_key(const WOLFSSL * ssl) This function checks that the private key is a match with the certificate being used.
int	wolfSSL_X509_get_ext_by_NID(const WOLFSSL_X509 * x509, int nid, int lastPos) This function looks for and returns the extension index matching the passed in NID value.
void *	wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509 * x509, int nid, int * c, int * idx) This function looks for and returns the extension matching the passed in NID value.
int	wolfSSL_X509_digest(const WOLFSSL_X509 * x509, const WOLFSSL_EVP_MD * digest, unsigned char * buf, unsigned int * len) This function returns the hash of the DER certificate.
int	wolfSSL_use_certificate(WOLFSSL * ssl, WOLFSSL_X509 * x509) his is used to set the certificate for WOLFSSL structure to use during a handshake.
int	wolfSSL_use_certificate_ASN1(WOLFSSL * ssl, unsigned char * der, int derSz) This is used to set the certificate for WOLFSSL structure to use during a handshake. A DER formatted buffer is expected.
int	wolfSSL_use_PrivateKey(WOLFSSL * ssl, WOLFSSL_EVP_PKEY * pkey) This is used to set the private key for the WOLFSSL structure.
int	wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL * ssl, unsigned char * der, long derSz) This is used to set the private key for the WOLFSSL structure. A DER formatted key buffer is expected.
int	wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL * ssl, unsigned char * der, long derSz) This is used to set the private key for the WOLFSSL structure. A DER formatted RSA key buffer is expected.
WOLFSSL_DH *	wolfSSL_DSA_dup_DH(const WOLFSSL_DSA * r) This function duplicates the parameters in dsa to a newly created WOLFSSL_DH structure.
int	wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION * ses, unsigned char * out, int outSz) This is used to get the master key after completing a handshake.
int	wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION * ses) This is used to get the master secret key length.
void	wolfSSL_CTX_set_cert_store(WOLFSSL_CTX * ctx, WOLFSSL_X509_STORE * str) This is a setter function for the WOLFSSL_X509_STORE structure in ctx.
WOLFSSL_X509 *	wolfSSL_d2i_X509_bio(WOLFSSL_BIO * bio, WOLFSSL_X509 ** x509) This function get the DER buffer from bio and converts it to a WOLFSSL_X509 structure.
WOLFSSL_X509_STORE *	wolfSSL_CTX_get_cert_store(WOLFSSL_CTX * ctx) This is a getter function for the WOLFSSL_X509_STORE structure in ctx.
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.
size_t	wolfSSL_get_server_random(const WOLFSSL * ssl, unsigned char * out, size_t outlen) This is used to get the random data sent by the server during the handshake.
size_t	wolfSSL_get_client_random(const WOLFSSL * ssl, unsigned char * out, size_t outSz) This is used to get the random data sent by the client during the handshake.
wc_pem_password_cb *	wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX * ctx) This is a getter function for the password callback set in ctx.
void *	wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX * ctx) This is a getter function for the password callback user data set in ctx.
WOLFSSL_X509 *	wolfSSL_PEM_read_bio_X509_AUX(WOLFSSL_BIO * bp, WOLFSSL_X509 ** x, wc_pem_password_cb * cb, void * u) This function behaves the same as wolfSSL_PEM_read_bio_X509. AUX signifies containing extra information such as trusted/rejected use cases and friendly name for human readability.
long	wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX * ctx, WOLFSSL_DH * dh) Initializes the WOLFSSL_CTX structure’s dh member with the Diffie-Hellman parameters.
WOLFSSL_DSA *	wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO * bp, WOLFSSL_DSA ** x, wc_pem_password_cb * cb, void * u) This function get the DSA parameters from a PEM buffer in bio.
unsigned long	wolfSSL_ERR_peek_last_error(void ) This function returns the absolute value of the last error from WOLFSSL_ERROR encountered.
	WOLF_STACK_OF(WOLFSSL_X509 ) const This function gets the peer’s certificate chain.
long	wolfSSL_CTX_clear_options(WOLFSSL_CTX * ctx, long opt) This function resets option bits of WOLFSSL_CTX object.
int	wolfSSL_set_jobject(WOLFSSL * ssl, void * objPtr) This function sets the jObjectRef member of the WOLFSSL structure.
void *	wolfSSL_get_jobject(WOLFSSL * ssl) This function returns the jObjectRef member of the WOLFSSL structure.
int	wolfSSL_set_msg_callback(WOLFSSL * ssl, SSL_Msg_Cb cb) This function sets a callback in the ssl. The callback is to observe handshake messages. NULL value of cb resets the callback.
int	wolfSSL_set_msg_callback_arg(WOLFSSL * ssl, void * arg) This function sets associated callback context value in the ssl. The value is handed over to the callback argument.
char *	wolfSSL_X509_get_next_altname(WOLFSSL_X509 * ) This function returns the next, if any, altname from the peer certificate.
WOLFSSL_ASN1_TIME *	wolfSSL_X509_get_notBefore(WOLFSSL_X509 * ) The function checks to see if x509 is NULL and if it’s not, it returns the notBefore member of the x509 struct.
int	wolfSSL_connect(WOLFSSL * ssl) This function is called on the client side and initiates an SSL/TLS handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.
int	wolfSSL_send_hrr_cookie(WOLFSSL * ssl, const unsigned char * secret, unsigned int secretSz) This function is called on the server side to indicate that a HelloRetryRequest message must contain a Cookie and, in case of using protocol DTLS v1.3, that the handshake will always include a cookie exchange. Please note that when using protocol DTLS v1.3, the cookie exchange is enabled by default. The Cookie holds a hash of the current transcript so that another server process can handle the ClientHello in reply. The secret is used when generating the integrity check on the Cookie data.
int	wolfSSL_disable_hrr_cookie(WOLFSSL * ssl) This function is called on the server side to indicate that a HelloRetryRequest message must NOT contain a Cookie and that, if using protocol DTLS v1.3, a cookie exchange will not be included in the handshake. Please note that not doing a cookie exchange when using protocol DTLS v1.3 can make the server susceptible to DoS/Amplification attacks.
int	wolfSSL_CTX_no_ticket_TLSv13(WOLFSSL_CTX * ctx) This function is called on the server to stop it from sending a resumption session ticket once the handshake is complete.
int	wolfSSL_no_ticket_TLSv13(WOLFSSL * ssl) This function is called on the server to stop it from sending a resumption session ticket once the handshake is complete.
int	wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX * ctx) This function is called on a TLS v1.3 wolfSSL context to disallow Diffie_Hellman (DH) style key exchanges when handshakes are using pre-shared keys for authentication.
int	wolfSSL_no_dhe_psk(WOLFSSL * ssl) This function is called on a TLS v1.3 client or server wolfSSL to disallow Diffie_Hellman (DH) style key exchanges when handshakes are using pre-shared keys for authentication.
int	wolfSSL_update_keys(WOLFSSL * ssl) This function is called on a TLS v1.3 client or server wolfSSL to force the rollover of keys. A KeyUpdate message is sent to the peer and new keys are calculated for encryption. The peer will send back a KeyUpdate message and the new decryption keys will then be calculated. This function can only be called after a handshake has been completed.
int	wolfSSL_key_update_response(WOLFSSL * ssl, int * required) This function is called on a TLS v1.3 client or server wolfSSL to determine whether a rollover of keys is in progress. When wolfSSL_update_keys() is called, a KeyUpdate message is sent and the encryption key is updated. The decryption key is updated when the response is received.
int	wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX * ctx) This function is called on a TLS v1.3 client wolfSSL context to allow a client certificate to be sent post handshake upon request from server. This is useful when connecting to a web server that has some pages that require client authentication and others that don't.
int	wolfSSL_allow_post_handshake_auth(WOLFSSL * ssl) This function is called on a TLS v1.3 client wolfSSL to allow a client certificate to be sent post handshake upon request from server. A Post-Handshake Client Authentication extension is sent in the ClientHello. This is useful when connecting to a web server that has some pages that require client authentication and others that don't.
int	wolfSSL_request_certificate(WOLFSSL * ssl) This function requests a client certificate from the TLS v1.3 client. This is useful when a web server is serving some pages that require client authentication and others that don't. A maximum of 256 requests can be sent on a connection.
int	wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX * ctx, char * list) This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_set1_groups_list(WOLFSSL * ssl, char * list) This function sets the list of elliptic curve groups to allow on a wolfSSL in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_preferred_group(WOLFSSL * ssl) This function returns the key exchange group the client prefers to use in the TLS v1.3 handshake. Call this function to after a handshake is complete to determine which group the server prefers so that this information can be used in future connections to pre-generate a key pair for key exchange.
int	wolfSSL_CTX_set_groups(WOLFSSL_CTX * ctx, int * groups, int count) This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_set_groups(WOLFSSL * ssl, int * groups, int count) This function sets the list of elliptic curve groups to allow on a wolfSSL. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_connect_TLSv13(WOLFSSL * ) This function is called on the client side and initiates a TLS v1.3 handshake with a server. When this function is called, the underlying communication channel has already been set up. wolfSSL_connect() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred. wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (_155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.
	wolfSSL_accept_TLSv13(WOLFSSL * ssl) This function is called on the server side and waits for a SSL/TLS client to initiate the SSL/TLS handshake. When this function is called, the underlying communication channel has already been set up. wolfSSL_accept() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_accept() will return when the underlying I/O could not satisfy the needs of wolfSSL_accept to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_accept when data is available to read and wolfSSL will pick up where it left off. When using a non_blocking socket, nothing needs to be done, but select() can be used to check for the required condition. If the underlying I/O is blocking, wolfSSL_accept() will only return once the handshake has been finished or an error occurred. Call this function when expecting a TLS v1.3 connection though older version ClientHello messages are supported.
int	wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX * ctx, unsigned int sz) This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange using the wolfSSL context. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.
int	wolfSSL_set_max_early_data(WOLFSSL * ssl, unsigned int sz) This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.
int	wolfSSL_write_early_data(WOLFSSL * ssl, const void * data, int sz, int * outSz) This function writes early data to the server on resumption. Call this function instead of wolfSSL_connect() or wolfSSL_connect_TLSv13() to connect to the server and send the data in the handshake. This function is only used with clients.
int	wolfSSL_read_early_data(WOLFSSL * ssl, void * data, int sz, int * outSz) This function reads any early data from a client on resumption. Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13() to accept a client and read any early data in the handshake. The function should be invoked until wolfSSL_is_init_finished() returns true. Early data may be sent by the client in multiple messages. If there is no early data then the handshake will be processed as normal. This function is only used with servers.
void	wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX * ctx, wc_psk_client_tls13_callback cb) This function sets the Pre_Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_client_tls13_callback(WOLFSSL * ssl, wc_psk_client_tls13_callback cb) This function sets the Pre_Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the options field in WOLFSSL structure.
void	wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX * ctx, wc_psk_server_tls13_callback cb) This function sets the Pre_Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_server_tls13_callback(WOLFSSL * ssl, wc_psk_server_tls13_callback cb) This function sets the Pre_Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the options field in WOLFSSL structure.
int	wolfSSL_UseKeyShare(WOLFSSL * ssl, word16 group) This function creates a key share entry from the group including generating a key pair. The KeyShare extension contains all the generated public keys for key exchange. If this function is called, then only the groups specified will be included. Call this function when a preferred group has been previously established for the server.
int	wolfSSL_NoKeyShares(WOLFSSL * ssl) This function is called to ensure no key shares are sent in the ClientHello. This will force the server to respond with a HelloRetryRequest if a key exchange is required in the handshake. Call this function when the expected key exchange group is not known and to avoid the generation of keys unnecessarily. Note that an extra round-trip will be required to complete the handshake when a key exchange is required.
WOLFSSL_METHOD *	wolfTLSv1_3_server_method_ex(void * heap) This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_client_method_ex(void * heap) This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_server_method(void ) This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_client_method(void ) This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_method_ex(void * heap) This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).
WOLFSSL_METHOD *	wolfTLSv1_3_method(void ) This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).
int	wolfSSL_CTX_set_ephemeral_key(WOLFSSL_CTX * ctx, int keyAlgo, const char * key, unsigned int keySz, int format) This function sets a fixed / static ephemeral key for testing only.
int	wolfSSL_set_ephemeral_key(WOLFSSL * ssl, int keyAlgo, const char * key, unsigned int keySz, int format) This function sets a fixed / static ephemeral key for testing only.
int	wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX * ctx, int keyAlgo, const unsigned char ** key, unsigned int * keySz) This function returns pointer to loaded key as ASN.1/DER.
int	wolfSSL_get_ephemeral_key(WOLFSSL * ssl, int keyAlgo, const unsigned char ** key, unsigned int * keySz) This function returns pointer to loaded key as ASN.1/DER.
int	wolfSSL_RSA_sign_generic_padding(int type, const unsigned char * m, unsigned int mLen, unsigned char * sigRet, unsigned int * sigLen, WOLFSSL_RSA * rsa, int flag, int padding) Sign a message with the chosen message digest, padding, and RSA key.
int	wolfSSL_dtls13_has_pending_msg(WOLFSSL * ssl) checks if DTLSv1.3 stack has some messages sent but not yet acknowledged by the other peer
unsigned int	wolfSSL_SESSION_get_max_early_data(const WOLFSSL_SESSION * s) Get the maximum size of Early Data from a session.
int	wolfSSL_CRYPTO_get_ex_new_index(int , void * , void * , void * , void * ) Get a new index for external data. This entry applies also for the following API:
int	wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX * ctx, const char * buf, int len) In case this function is called in a client side, set certificate types that can be sent to its peer. In case called in a server side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
int	wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX * ctx, const char * buf, int len) In case this function is called in a server side, set certificate types that can be sent to its peer. In case called in a client side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
int	wolfSSL_set_client_cert_type(WOLFSSL * ssl, const char * buf, int len) In case this function is called in a client side, set certificate types that can be sent to its peer. In case called in a server side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
int	wolfSSL_set_server_cert_type(WOLFSSL * ssl, const char * buf, int len) In case this function is called in a server side, set certificate types that can be sent to its peer. In case called in a client side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
int	wolfSSL_get_negotiated_client_cert_type(WOLFSSL * ssl, int * tp) This function returns the result of the client certificate type negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is returned as the certificate type.
int	wolfSSL_get_negotiated_server_cert_type(WOLFSSL * ssl, int * tp) This function returns the result of the server certificate type negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is returned as the certificate type.
int	wolfSSL_dtls_cid_use(WOLFSSL * ssl) Enable use of ConnectionID extensions for the SSL object. See RFC 9146 and RFC 9147.
int	wolfSSL_dtls_cid_is_enabled(WOLFSSL * ssl) If invoked after the handshake is complete it checks if ConnectionID was successfully negotiated for the SSL object. See RFC 9146 and RFC 9147.
int	wolfSSL_dtls_cid_set(WOLFSSL * ssl, unsigned char * cid, unsigned int size) Set the ConnectionID used by the other peer to send records in this connection. See RFC 9146 and RFC 9147. The ConnectionID must be at maximum DTLS_CID_MAX_SIZE, that is an tunable compile time define, and it can't never be bigger than 255 bytes.
int	wolfSSL_dtls_cid_get_rx_size(WOLFSSL * ssl, unsigned int * size) Get the size of the ConnectionID used by the other peer to send records in this connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.
int	wolfSSL_dtls_cid_get_rx(WOLFSSL * ssl, unsigned char * buffer, unsigned int bufferSz) Copy the ConnectionID used by the other peer to send records in this connection into the buffer pointed by the parameter buffer. See RFC 9146 and RFC.
int	wolfSSL_dtls_cid_get_tx_size(WOLFSSL * ssl, unsigned int * size) Get the size of the ConnectionID used to send records in this connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.
int	wolfSSL_dtls_cid_get_tx(WOLFSSL * ssl, unsigned char * buffer, unsigned int bufferSz) Copy the ConnectionID used when sending records in this connection into the buffer pointer by the parameter buffer. See RFC 9146 and RFC 9147. The available size need to be provided in bufferSz.
int	wolfSSL_get_client_suites_sigalgs(const WOLFSSL * ssl, const byte suites, word16 * suiteSz, const byte hashSigAlgo, word16 * hashSigAlgoSz) This function returns the raw list of ciphersuites and signature algorithms offered by the client. The lists are only stored and returned inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to be able to dynamically load certificates and keys based on the available ciphersuites and signature algorithms.
WOLFSSL_CIPHERSUITE_INFO	wolfSSL_get_ciphersuite_info(byte first, byte second) This returns information about the ciphersuite directly from the raw ciphersuite bytes.
int	wolfSSL_get_sigalg_info(byte first, byte second, int * hashAlgo, int * sigAlgo) This returns information about the hash and signature algorithm directly from the raw ciphersuite bytes.

Functions Documentation

function wolfDTLSv1_2_client_method_ex

WOLFSSL_METHOD * wolfDTLSv1_2_client_method_ex(
    void * heap
)

This function initializes the DTLS v1.2 client method.

Parameters:

• none No parameters.

See:

• wolfSSL_Init
• wolfSSL_CTX_new

Return: pointer This function returns a pointer to a new WOLFSSL_METHOD structure.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_client_method());
…
WOLFSSL* ssl = wolfSSL_new(ctx);
…

function wolfSSLv23_method

WOLFSSL_METHOD * wolfSSLv23_method(
    void 
)

This function returns a WOLFSSL_METHOD similar to wolfSSLv23_client_method except that it is not determined which side yet (server/client).

Parameters:

• none No parameters.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD pointer
• NULL Null if memory allocation error or failure to create method

Example

WOLFSSL* ctx;
ctx  = wolfSSL_CTX_new(wolfSSLv23_method());
// check ret value

function wolfSSLv3_server_method

WOLFSSL_METHOD * wolfSSLv3_server_method(
    void 
)

The wolfSSLv3_server_method() function is used to indicate that the application is a server and will only support the SSL 3.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfSSLv3_server_method();
if (method == NULL) {
    unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfSSLv3_client_method

WOLFSSL_METHOD * wolfSSLv3_client_method(
    void 
)

The wolfSSLv3_client_method() function is used to indicate that the application is a client and will only support the SSL 3.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfSSLv3_client_method();
if (method == NULL) {
    unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_server_method

WOLFSSL_METHOD * wolfTLSv1_server_method(
    void 
)

The wolfTLSv1_server_method() function is used to indicate that the application is a server and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_server_method();
if (method == NULL) {
    unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_client_method

WOLFSSL_METHOD * wolfTLSv1_client_method(
    void 
)

The wolfTLSv1_client_method() function is used to indicate that the application is a client and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_client_method();
if (method == NULL) {
    unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_1_server_method

WOLFSSL_METHOD * wolfTLSv1_1_server_method(
    void 
)

The wolfTLSv1_1_server_method() function is used to indicate that the application is a server and will only support the TLS 1.1 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_1_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_1_client_method

WOLFSSL_METHOD * wolfTLSv1_1_client_method(
    void 
)

The wolfTLSv1_1_client_method() function is used to indicate that the application is a client and will only support the TLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_1_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_2_server_method

WOLFSSL_METHOD * wolfTLSv1_2_server_method(
    void 
)

The wolfTLSv1_2_server_method() function is used to indicate that the application is a server and will only support the TLS 1.2 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_2_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_2_client_method

WOLFSSL_METHOD * wolfTLSv1_2_client_method(
    void 
)

The wolfTLSv1_2_client_method() function is used to indicate that the application is a client and will only support the TLS 1.2 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters.

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_2_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLSv1_client_method

WOLFSSL_METHOD * wolfDTLSv1_client_method(
    void 
)

The wolfDTLSv1_client_method() function is used to indicate that the application is a client and will only support the DTLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).

Parameters:

• none No parameters.

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLSv1_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLSv1_server_method

WOLFSSL_METHOD * wolfDTLSv1_server_method(
    void 
)

The wolfDTLSv1_server_method() function is used to indicate that the application is a server and will only support the DTLS 1.0 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).

Parameters:

• none No parameters.

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLSv1_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLSv1_3_server_method

WOLFSSL_METHOD * wolfDTLSv1_3_server_method(
    void 
)

The wolfDTLSv1_3_server_method() function is used to indicate that the application is a server and will only support the DTLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLSv1.3 support (–enable_dtls13, or by defining wolfSSL_DTLS13).

Parameters:

• none No parameters.

See: wolfDTLSv1_3_client_method

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLSv1_3_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLSv1_3_client_method

WOLFSSL_METHOD * wolfDTLSv1_3_client_method(
    void 
)

The wolfDTLSv1_3_client_method() function is used to indicate that the application is a client and will only support the DTLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLSv1.3 support (–enable_dtls13, or by defining wolfSSL_DTLS13).

Parameters:

• none No parameters.

See: wolfDTLSv1_3_server_method

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLSv1_3_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLS_server_method

WOLFSSL_METHOD * wolfDTLS_server_method(
    void 
)

The wolfDTLS_server_method() function is used to indicate that the application is a server and will support the highest version of DTLS available and all the version up to the minimum version allowed. The default minimum version allowed is based on the define WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using wolfSSL_SetMinVersion(). This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).

Parameters:

• none No parameters.

See:

• wolfDTLS_client_method
• wolfSSL_SetMinVersion

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLS_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLS_client_method

WOLFSSL_METHOD * wolfDTLS_client_method(
    void 
)

The wolfDTLS_client_method() function is used to indicate that the application is a client and will support the highest version of DTLS available and all the version up to the minimum version allowed. The default minimum version allowed is based on the define WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using wolfSSL_SetMinVersion(). This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). This function is only available when wolfSSL has been compiled with DTLS support (–enable_dtls, or by defining wolfSSL_DTLS).

Parameters:

• none No parameters.

See:

• wolfDTLS_server_method
• wolfSSL_SetMinVersion

Return:

• • If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfDTLS_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfDTLSv1_2_server_method

WOLFSSL_METHOD * wolfDTLSv1_2_server_method(
    void 
)

This function creates and initializes a WOLFSSL_METHOD for the server side.

Parameters:

• none No parameters.

See: wolfSSL_CTX_new

Return: This function returns a WOLFSSL_METHOD pointer.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_server_method());
WOLFSSL* ssl = WOLFSSL_new(ctx);
…

function wolfSSL_use_old_poly

int wolfSSL_use_old_poly(
    WOLFSSL * ssl,
    int value
)

Since there is some differences between the first release and newer versions of chacha-poly AEAD construction we have added an option to communicate with servers/clients using the older version. By default wolfSSL uses the new version.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• value whether or not to use the older version of setting up the information for poly1305. Passing a flag value of 1 indicates yes use the old poly AEAD, to switch back to using the new version pass a flag value of 0.

See: none

Return: 0 upon success

Example

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

ret = wolfSSL_use_old_poly(ssl, 1);
if (ret != 0) {
    // failed to set poly1305 AEAD version
}

function wolfSSL_dtls_import

int wolfSSL_dtls_import(
    WOLFSSL * ssl,
    unsigned char * buf,
    unsigned int sz
)

The wolfSSL_dtls_import() function is used to parse in a serialized session state. This allows for picking up the connection after the handshake has been completed.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• buf serialized session to import.
• sz size of serialized session buffer.

See:

• wolfSSL_new
• wolfSSL_CTX_new
• wolfSSL_CTX_dtls_set_export

Return:

• Success If successful, the amount of the buffer read will be returned.
• Failure All unsuccessful return values will be less than 0.
• VERSION_ERROR If a version mismatch is found ie DTLS v1 and ctx was set up for DTLS v1.2 then VERSION_ERROR is returned.

Example

WOLFSSL* ssl;
int ret;
unsigned char buf[MAX];
bufSz = MAX;
...
//get information sent from wc_dtls_export function and place it in buf
fread(buf, 1, bufSz, input);
ret = wolfSSL_dtls_import(ssl, buf, bufSz);
if (ret < 0) {
// handle error case
}
// no wolfSSL_accept needed since handshake was already done
...
ret = wolfSSL_write(ssl) and wolfSSL_read(ssl);
...

function wolfSSL_tls_import

int wolfSSL_tls_import(
    WOLFSSL * ssl,
    const unsigned char * buf,
    unsigned int sz
)

Used to import a serialized TLS session. This function is for importing the state of the connection. WARNING: buf contains sensitive information about the state and is best to be encrypted before storing if stored. Additional debug info can be displayed with the macro WOLFSSL_SESSION_EXPORT_DEBUG defined.

Parameters:

• ssl WOLFSSL structure to import the session into
• buf serialized session
• sz size of buffer 'buf'

See:

• wolfSSL_dtls_import
• wolfSSL_tls_export

Return: the number of bytes read from buffer 'buf'

function wolfSSL_CTX_dtls_set_export

int wolfSSL_CTX_dtls_set_export(
    WOLFSSL_CTX * ctx,
    wc_dtls_export func
)

The wolfSSL_CTX_dtls_set_export() function is used to set the callback function for exporting a session. It is allowed to pass in NULL as the parameter func to clear the export function previously stored. Used on the server side and is called immediately after handshake is completed.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• func wc_dtls_export function to use when exporting a session.

See:

• wolfSSL_new
• wolfSSL_CTX_new
• wolfSSL_dtls_set_export
• Static buffer use

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG If null or not expected arguments are passed in

Example

int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
// body of send session (wc_dtls_export) that passes
// buf (serialized session) to destination
WOLFSSL_CTX* ctx;
int ret;
...
ret = wolfSSL_CTX_dtls_set_export(ctx, send_session);
if (ret != SSL_SUCCESS) {
    // handle error case
}
...
ret = wolfSSL_accept(ssl);
...

function wolfSSL_dtls_set_export

int wolfSSL_dtls_set_export(
    WOLFSSL * ssl,
    wc_dtls_export func
)

The wolfSSL_dtls_set_export() function is used to set the callback function for exporting a session. It is allowed to pass in NULL as the parameter func to clear the export function previously stored. Used on the server side and is called immediately after handshake is completed.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• func wc_dtls_export function to use when exporting a session.

See:

• wolfSSL_new
• wolfSSL_CTX_new
• wolfSSL_CTX_dtls_set_export

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG If null or not expected arguments are passed in

Example

int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
// body of send session (wc_dtls_export) that passes
// buf (serialized session) to destination
WOLFSSL* ssl;
int ret;
...
ret = wolfSSL_dtls_set_export(ssl, send_session);
if (ret != SSL_SUCCESS) {
    // handle error case
}
...
ret = wolfSSL_accept(ssl);
...

function wolfSSL_dtls_export

int wolfSSL_dtls_export(
    WOLFSSL * ssl,
    unsigned char * buf,
    unsigned int * sz
)

The wolfSSL_dtls_export() function is used to serialize a WOLFSSL session into the provided buffer. Allows for less memory overhead than using a function callback for sending a session and choice over when the session is serialized. If buffer is NULL when passed to function then sz will be set to the size of buffer needed for serializing the WOLFSSL session.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• buf buffer to hold serialized session.
• sz size of buffer.

See:

• wolfSSL_new
• wolfSSL_CTX_new
• wolfSSL_CTX_dtls_set_export
• wolfSSL_dtls_import

Return:

• Success If successful, the amount of the buffer used will be returned.
• Failure All unsuccessful return values will be less than 0.

Example

WOLFSSL* ssl;
int ret;
unsigned char buf[MAX];
bufSz = MAX;
...
ret = wolfSSL_dtls_export(ssl, buf, bufSz);
if (ret < 0) {
    // handle error case
}
...

function wolfSSL_tls_export

int wolfSSL_tls_export(
    WOLFSSL * ssl,
    unsigned char * buf,
    unsigned int * sz
)

Used to export a serialized TLS session. This function is for exporting a serialized state of the connection. In most cases wolfSSL_get1_session should be used instead of wolfSSL_tls_export. Additional debug info can be displayed with the macro WOLFSSL_SESSION_EXPORT_DEBUG defined. WARNING: buf contains sensitive information about the state and is best to be encrypted before storing if stored.

Parameters:

• ssl WOLFSSL structure to export the session from
• buf output of serialized session
• sz size in bytes set in 'buf'

See:

• wolfSSL_dtls_import
• wolfSSL_tls_import

Return: the number of bytes written into buffer 'buf'

function wolfSSL_CTX_load_static_memory

int wolfSSL_CTX_load_static_memory(
    WOLFSSL_CTX ** ctx,
    wolfSSL_method_func method,
    unsigned char * buf,
    unsigned int sz,
    int flag,
    int max
)

This function is used to set aside static memory for a CTX. Memory set aside is then used for the CTX’s lifetime and for any SSL objects created from the CTX. By passing in a NULL ctx pointer and a wolfSSL_method_func function the creation of the CTX itself will also use static memory. wolfSSL_method_func has the function signature of WOLFSSL_METHOD* (wolfSSL_method_func)(void heap);. Passing in 0 for max makes it behave as if not set and no max concurrent use restrictions is in place. The flag value passed in determines how the memory is used and behavior while operating. Available flags are the following: 0 - default general memory, WOLFMEM_IO_POOL - used for input/output buffer when sending receiving messages and overrides general memory, so all memory in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory stats while running.

Parameters:

• ctx address of pointer to a WOLFSSL_CTX structure.
• method function to create protocol. (should be NULL if ctx is not also NULL)
• buf memory to use for all operations.
• sz size of memory buffer being passed in.
• flag type of memory.
• max max concurrent operations.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_is_static_memory
• wolfSSL_is_static_memory

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE upon failure.

Example

WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
int ret;
unsigned char memory[MAX];
int memorySz = MAX;
unsigned char IO[MAX];
int IOSz = MAX;
int flag = WOLFMEM_IO_FIXED | WOLFMEM_TRACK_STATS;
...
// create ctx also using static memory, start with general memory to use
ctx = NULL:
ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex,
memory, memorySz, 0,    MAX_CONCURRENT_HANDSHAKES);
if (ret != SSL_SUCCESS) {
// handle error case
}
// load in memory for use with IO
ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag,
MAX_CONCURRENT_IO);
if (ret != SSL_SUCCESS) {
// handle error case
}
...

function wolfSSL_CTX_is_static_memory

int wolfSSL_CTX_is_static_memory(
    WOLFSSL_CTX * ctx,
    WOLFSSL_MEM_STATS * mem_stats
)

This function does not change any of the connections behavior and is used only for gathering information about the static memory usage.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• mem_stats structure to hold information about static memory usage.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_load_static_memory
• wolfSSL_is_static_memory

Return:

• 1 is returned if using static memory for the CTX is true.
• 0 is returned if not using static memory.

Example

WOLFSSL_CTX* ctx;
int ret;
WOLFSSL_MEM_STATS mem_stats;
...
//get information about static memory with CTX
ret = wolfSSL_CTX_is_static_memory(ctx, &mem_stats);
if (ret == 1) {
    // handle case of is using static memory
    // print out or inspect elements of mem_stats
}
if (ret == 0) {
    //handle case of ctx not using static memory
}
…

function wolfSSL_is_static_memory

int wolfSSL_is_static_memory(
    WOLFSSL * ssl,
    WOLFSSL_MEM_CONN_STATS * mem_stats
)

wolfSSL_is_static_memory is used to gather information about a SSL’s static memory usage. The return value indicates if static memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent CTX when loading in static memory.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• mem_stats structure to contain static memory usage.

See:

• wolfSSL_new
• wolfSSL_CTX_is_static_memory

Return:

• 1 is returned if using static memory for the CTX is true.
• 0 is returned if not using static memory.

Example

WOLFSSL* ssl;
int ret;
WOLFSSL_MEM_CONN_STATS mem_stats;
...
ret = wolfSSL_is_static_memory(ssl, mem_stats);
if (ret == 1) {
    // handle case when is static memory
    // investigate elements in mem_stats if WOLFMEM_TRACK_STATS flag
}
...

function wolfSSL_CTX_use_certificate_file

int wolfSSL_CTX_use_certificate_file(
    WOLFSSL_CTX * ctx,
    const char * file,
    int format
)

This function loads a certificate file into the SSL context (WOLFSSL_CTX). The file is provided by the file argument. The format argument specifies the format type of the file, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
• file a pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL context.
• format - format of the certificates pointed to by file. Possible options are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_use_certificate_file
• wolfSSL_use_certificate_buffer

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE If the function call fails, possible causes might include the file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs, Base16 decoding fails on the file.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_use_certificate_file(ctx, “./client-cert.pem”,
                                 SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

function wolfSSL_CTX_use_PrivateKey_file

int wolfSSL_CTX_use_PrivateKey_file(
    WOLFSSL_CTX * ctx,
    const char * file,
    int format
)

This function loads a private key file into the SSL context (WOLFSSL_CTX). The file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_use_PrivateKey_file
• wolfSSL_use_PrivateKey_buffer
• wc_CryptoCb_RegisterDevice
• wolfSSL_CTX_SetDevId

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE The file is in the wrong format, or the wrong format has been given using the “format” argument. The file doesn’t exist, can’t be read, or is corrupted. An out of memory condition occurs. Base16 decoding fails on the file. The key file is encrypted but no password is provided.

If using an external key store and do not have the private key you can instead provide the public key and register the crypro callback to handle the signing. For this you can build with either build with crypto callbacks or PK callbacks. To enable crypto callbacks use –enable-cryptocb or WOLF_CRYPTO_CB and register a crypto callback using wc_CryptoCb_RegisterDevice and set the associated devId using wolfSSL_CTX_SetDevId.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_use_PrivateKey_file(ctx, “./server-key.pem”,
                                SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading key file
}
...

function wolfSSL_CTX_load_verify_locations

int wolfSSL_CTX_load_verify_locations(
    WOLFSSL_CTX * ctx,
    const char * file,
    const char * path
)

This function loads PEM-formatted CA certificate files into the SSL context (WOLFSSL_CTX). These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The path argument is a pointer to the name of a directory that contains certificates of trusted root CAs. If the value of file is not NULL, path may be specified as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not defined when building the library, wolfSSL will load all CA certificates located in the given directory. This function will attempt to load all files in the directory. This function expects PEM formatted CERT_TYPE file with header “--—BEGIN CERTIFICATE--—”.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• file pointer to name of the file containing PEM-formatted CA certificates.
• path pointer to the name of a directory to load PEM-formatted certificates from.

See:

• wolfSSL_CTX_load_verify_locations_ex
• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_file
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_use_certificate_file
• wolfSSL_use_PrivateKey_file
• wolfSSL_use_certificate_chain_file

Return:

• SSL_SUCCESS up success.
• SSL_FAILURE will be returned if ctx is NULL, or if both file and path are NULL.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• ASN_BEFORE_DATE_E will be returned if the current date is before the before date.
• ASN_AFTER_DATE_E will be returned if the current date is after the after date.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.
• BAD_PATH_ERROR will be returned if opendir() fails when trying to open path.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_load_verify_locations(ctx, “./ca-cert.pem”, NULL);
if (ret != WOLFSSL_SUCCESS) {
    // error loading CA certs
}
...

function wolfSSL_CTX_load_verify_locations_ex

int wolfSSL_CTX_load_verify_locations_ex(
    WOLFSSL_CTX * ctx,
    const char * file,
    const char * path,
    unsigned int flags
)

This function loads PEM-formatted CA certificate files into the SSL context (WOLFSSL_CTX). These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The path argument is a pointer to the name of a directory that contains certificates of trusted root CAs. If the value of file is not NULL, path may be specified as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not defined when building the library, wolfSSL will load all CA certificates located in the given directory. This function will attempt to load all files in the directory based on flags specified. This function expects PEM formatted CERT_TYPE files with header “--—BEGIN CERTIFICATE--—”.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• file pointer to name of the file containing PEM-formatted CA certificates.
• path pointer to the name of a directory to load PEM-formatted certificates from.
• flags possible mask values are: WOLFSSL_LOAD_FLAG_IGNORE_ERR, WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY and WOLFSSL_LOAD_FLAG_PEM_CA_ONLY

See:

• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_file
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_use_certificate_file
• wolfSSL_use_PrivateKey_file
• wolfSSL_use_certificate_chain_file

Return:

• SSL_SUCCESS up success.
• SSL_FAILURE will be returned if ctx is NULL, or if both file and path are NULL. This will also be returned if at least one cert is loaded successfully but there is one or more that failed. Check error stack for reason.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.
• BAD_PATH_ERROR will be returned if opendir() fails when trying to open path.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_load_verify_locations_ex(ctx, NULL, “./certs/external",
    WOLFSSL_LOAD_FLAG_PEM_CA_ONLY);
if (ret != WOLFSSL_SUCCESS) {
    // error loading CA certs
}
...

function wolfSSL_get_system_CA_dirs

const char ** wolfSSL_get_system_CA_dirs(
    word32 * num
)

This function returns a pointer to an array of strings representing directories wolfSSL will search for system CA certs when wolfSSL_CTX_load_system_CA_certs is called. On systems that don't store certificates in an accessible system directory (such as Apple platforms), this function will always return NULL.

Parameters:

• num pointer to a word32 that will be populated with the length of the array of strings.

See:

• wolfSSL_CTX_load_system_CA_certs
• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_load_verify_locations_ex

Return:

• Valid pointer on success.
• NULL pointer on failure.

Example

WOLFSSL_CTX* ctx;
const char** dirs;
word32 numDirs;

dirs = wolfSSL_get_system_CA_dirs(&numDirs);
for (int i = 0; i < numDirs; ++i) {
    printf("Potential system CA dir: %s\n", dirs[i]);
}
...

function wolfSSL_CTX_load_system_CA_certs

int wolfSSL_CTX_load_system_CA_certs(
    WOLFSSL_CTX * ctx
)

On most platforms (including Linux and Windows), this function attempts to load CA certificates into a WOLFSSL_CTX from an OS-dependent CA certificate store. Loaded certificates will be trusted.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().

See:

• wolfSSL_get_system_CA_dirs
• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_load_verify_locations_ex

Return:

• WOLFSSL_SUCCESS on success.
• WOLFSSL_BAD_PATH if no system CA certs were loaded.
• WOLFSSL_FAILURE for other failure types (e.g. Windows cert store wasn't properly closed).

On Apple platforms (excluding macOS), certificates can't be obtained from the system, and therefore cannot be loaded into the wolfSSL certificate manager. For these platforms, this function enables TLS connections bound to the WOLFSSL_CTX to use the native system trust APIs to verify authenticity of the peer certificate chain if the authenticity of the peer cannot first be authenticated against certificates loaded by the user.

The platforms supported and tested are: Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), Windows 10/11, Android, macOS, and iOS.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_load_system_CA_certs(ctx,);
if (ret != WOLFSSL_SUCCESS) {
    // error loading system CA certs
}
...

function wolfSSL_CTX_trust_peer_cert

int wolfSSL_CTX_trust_peer_cert(
    WOLFSSL_CTX * ctx,
    const char * file,
    int type
)

This function loads a certificate to use for verifying a peer when performing a TLS/SSL handshake. The peer certificate sent during the handshake is compared by using the SKID when available and the signature. If these two things do not match then any loaded CAs are used. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• file pointer to name of the file containing certificates
• type type of certificate being loaded ie SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_file
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_CTX_trust_peer_buffer
• wolfSSL_CTX_Unload_trust_peers
• wolfSSL_use_certificate_file
• wolfSSL_use_PrivateKey_file
• wolfSSL_use_certificate_chain_file

Return:

• SSL_SUCCES upon success.
• SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Example

int ret = 0;
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
...

ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”,
SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading trusted peer cert
}
...

function wolfSSL_CTX_use_certificate_chain_file

int wolfSSL_CTX_use_certificate_chain_file(
    WOLFSSL_CTX * ctx,
    const char * file
)

This function loads a chain of certificates into the SSL context (WOLFSSL_CTX). The file containing the certificate chain is provided by the file argument, and must contain PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject cert.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
• file a pointer to the name of the file containing the chain of certificates to be loaded into the wolfSSL SSL context. Certificates must be in PEM format.

See:

• wolfSSL_CTX_use_certificate_file
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_use_certificate_file
• wolfSSL_use_certificate_buffer

Return:

• SSL_SUCCESS upon success
• SSL_FAILURE If the function call fails, possible causes might include the file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_use_certificate_chain_file(ctx, “./cert-chain.pem”);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

function wolfSSL_CTX_use_RSAPrivateKey_file

int wolfSSL_CTX_use_RSAPrivateKey_file(
    WOLFSSL_CTX * ctx,
    const char * file,
    int format
)

This function loads the private RSA key used in the SSL connection into the SSL context (WOLFSSL_CTX). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
• file a pointer to the name of the file containing the RSA private key to be loaded into the wolfSSL SSL context, with format as specified by format.
• format the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

See:

• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_use_RSAPrivateKey_file
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_PrivateKey_file

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE If the function call fails, possible causes might include: The input key file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”,
                                   SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading private key file
}
...

function wolfSSL_get_verify_depth

long wolfSSL_get_verify_depth(
    WOLFSSL * ssl
)

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

Parameters:

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

See: wolfSSL_CTX_get_verify_depth

Return:

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

Example

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

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

function wolfSSL_CTX_get_verify_depth

long wolfSSL_CTX_get_verify_depth(
    WOLFSSL_CTX * ctx
)

This function gets the certificate chaining depth using the CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_get_verify_depth

Return:

• MAX_CHAIN_DEPTH returned if the CTX struct is not NULL. The constant representation of the max certificate chain peer depth.
• BAD_FUNC_ARG returned if the CTX structure is NULL.

Example

WOLFSSL_METHOD method; // protocol method
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
…
long ret = wolfSSL_CTX_get_verify_depth(ctx);

if(ret == EXPECTED){
    //  You have the expected value
} else {
    //  Handle an unexpected depth
}

function wolfSSL_use_certificate_file

int wolfSSL_use_certificate_file(
    WOLFSSL * ssl,
    const char * file,
    int format
)

This function loads a certificate file into the SSL session (WOLFSSL structure). The certificate file is provided by the file argument. The format argument specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Parameters:

• ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
• file a pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL session, with format as specified by format.
• format the encoding type of the certificate specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

See:

• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_certificate_file
• wolfSSL_use_certificate_buffer

Return:

• SSL_SUCCESS upon success
• SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs, Base16 decoding fails on the file

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_certificate_file(ssl, “./client-cert.pem”,
                             SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

function wolfSSL_use_PrivateKey_file

int wolfSSL_use_PrivateKey_file(
    WOLFSSL * ssl,
    const char * file,
    int format
)

This function loads a private key file into the SSL session (WOLFSSL structure). The key file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Parameters:

• ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
• file a pointer to the name of the file containing the key file to be loaded into the wolfSSL SSL session, with format as specified by format.
• format the encoding type of the key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

See:

• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_use_PrivateKey_buffer
• wc_CryptoCb_RegisterDevice
• wolfSSL_SetDevId

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, The file doesn’t exist, can’t be read, or is corrupted, An out of memory condition occurs, Base16 decoding fails on the file, The key file is encrypted but no password is provided

If using an external key store and do not have the private key you can instead provide the public key and register the crypro callback to handle the signing. For this you can build with either build with crypto callbacks or PK callbacks. To enable crypto callbacks use –enable-cryptocb or WOLF_CRYPTO_CB and register a crypto callback using wc_CryptoCb_RegisterDevice and set the associated devId using wolfSSL_SetDevId.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_PrivateKey_file(ssl, “./server-key.pem”,
                            SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading key file
}
...

function wolfSSL_use_certificate_chain_file

int wolfSSL_use_certificate_chain_file(
    WOLFSSL * ssl,
    const char * file
)

This function loads a chain of certificates into the SSL session (WOLFSSL structure). The file containing the certificate chain is provided by the file argument, and must contain PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject certificate.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
• file a pointer to the name of the file containing the chain of certificates to be loaded into the wolfSSL SSL session. Certificates must be in PEM format.

See:

• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs

Example

int ret = 0;
WOLFSSL* ctx;
...
ret = wolfSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

function wolfSSL_use_RSAPrivateKey_file

int wolfSSL_use_RSAPrivateKey_file(
    WOLFSSL * ssl,
    const char * file,
    int format
)

This function loads the private RSA key used in the SSL connection into the SSL session (WOLFSSL structure). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
• file a pointer to the name of the file containing the RSA private key to be loaded into the wolfSSL SSL session, with format as specified by format.
• format the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

See:

• wolfSSL_CTX_use_RSAPrivateKey_file
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_PrivateKey_file

Return:

• SSL_SUCCESS upon success
• SSL_FAILURE If the function call fails, possible causes might include: The input key file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”,
                               SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading private key file
}
...

function wolfSSL_CTX_der_load_verify_locations

int wolfSSL_CTX_der_load_verify_locations(
    WOLFSSL_CTX * ctx,
    const char * file,
    int format
)

This function is similar to wolfSSL_CTX_load_verify_locations, but allows the loading of DER-formatted CA files into the SSL context (WOLFSSL_CTX). It may still be used to load PEM-formatted CA files as well. These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake. The root certificate file, provided by the file argument, may be a single certificate or a file containing multiple certificates. If multiple CA certs are included in the same file, wolfSSL will load them in the same order they are presented in the file. The format argument specifies the format which the certificates are in either, SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations, this function does not allow the loading of CA certificates from a given directory path. Note that this function is only available when the wolfSSL library was compiled with WOLFSSL_DER_LOAD defined.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
• file a pointer to the name of the file containing the CA certificates to be loaded into the wolfSSL SSL context, with format as specified by format.
• format the encoding type of the certificates specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

See:

• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_load_verify_buffer

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE upon failure.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_der_load_verify_locations(ctx, “./ca-cert.der”,
                                      SSL_FILETYPE_ASN1);
if (ret != SSL_SUCCESS) {
    // error loading CA certs
}
...

function wolfSSL_CTX_new

WOLFSSL_CTX * wolfSSL_CTX_new(
    WOLFSSL_METHOD * 
)

This function creates a new SSL context, taking a desired SSL/TLS protocol method for input.

Parameters:

• method pointer to the desired WOLFSSL_METHOD to use for the SSL context. This is created using one of the wolfSSLvXX_XXXX_method() functions to specify SSL/TLS/DTLS protocol level.

See: wolfSSL_new

Return:

• pointer If successful the call will return a pointer to the newly-created WOLFSSL_CTX.
• NULL upon failure.

Example

WOLFSSL_CTX*    ctx    = 0;
WOLFSSL_METHOD* method = 0;

method = wolfSSLv3_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}

function wolfSSL_new

WOLFSSL * wolfSSL_new(
    WOLFSSL_CTX * 
)

This function creates a new SSL session, taking an already created SSL context as input.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().

See: wolfSSL_CTX_new

Return:

• • If successful the call will return a pointer to the newly-created wolfSSL structure.
• NULL Upon failure.

Example

#include <wolfssl/ssl.h>

WOLFSSL*     ssl = NULL;
WOLFSSL_CTX* ctx = 0;

ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}

ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // SSL object creation failed
}

function wolfSSL_set_fd

int wolfSSL_set_fd(
    WOLFSSL * ssl,
    int fd
)

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

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• fd file descriptor to use with SSL/TLS connection.

See:

• wolfSSL_CTX_SetIOSend
• wolfSSL_CTX_SetIORecv
• wolfSSL_SetIOReadCtx
• wolfSSL_SetIOWriteCtx

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG upon failure.

Example

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

ret = wolfSSL_set_fd(ssl, sockfd);
if (ret != SSL_SUCCESS) {
    // failed to set SSL file descriptor
}

function wolfSSL_set_dtls_fd_connected

int wolfSSL_set_dtls_fd_connected(
    WOLFSSL * ssl,
    int fd
)

This function assigns a file descriptor (fd) as the input/output facility for the SSL connection. Typically this will be a socket file descriptor. This is a DTLS specific API because it marks that the socket is connected. recvfrom and sendto calls on this fd will have the addr and addr_len parameters set to NULL.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• fd file descriptor to use with SSL/TLS connection.

See:

• wolfSSL_CTX_SetIOSend
• wolfSSL_CTX_SetIORecv
• wolfSSL_SetIOReadCtx
• wolfSSL_SetIOWriteCtx
• wolfDTLS_SetChGoodCb

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG upon failure.

Example

int sockfd;
WOLFSSL* ssl = 0;
...
if (connect(sockfd, peer_addr, peer_addr_len) != 0) {
    // handle connect error
}
...
ret = wolfSSL_set_dtls_fd_connected(ssl, sockfd);
if (ret != SSL_SUCCESS) {
    // failed to set SSL file descriptor
}

function wolfDTLS_SetChGoodCb

int wolfDTLS_SetChGoodCb(
    WOLFSSL * ssl,
    ClientHelloGoodCb cb,
    void * user_ctx
)

Allows setting a callback for a correctly processed and verified DTLS client hello. When using a cookie exchange mechanism (either the HelloVerifyRequest in DTLS 1.2 or the HelloRetryRequest with a cookie extension in DTLS 1.3) this callback is called after the cookie exchange has succeeded. This is useful to use one WOLFSSL object as the listener for new connections and being able to isolate the WOLFSSL object once the ClientHello is verified (either through a cookie exchange or just checking if the ClientHello had the correct format). DTLS 1.2: https://datatracker.ietf.org/doc/html/rfc6347#section-4.2.1 DTLS 1.3: https://www.rfc-editor.org/rfc/rfc8446#section-4.2.2.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• fd file descriptor to use with SSL/TLS connection.

See: wolfSSL_set_dtls_fd_connected

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG upon failure.

Example

// Called when we have verified a connection
static int chGoodCb(WOLFSSL* ssl, void* arg)
{
    // setup peer and file descriptors

}

if (wolfDTLS_SetChGoodCb(ssl, chGoodCb, NULL) != WOLFSSL_SUCCESS) {
     // error setting callback
}

function wolfSSL_get_cipher_list

char * wolfSSL_get_cipher_list(
    int priority
)

Get the name of cipher at priority level passed in.

Parameters:

• priority Integer representing the priority level of a cipher.

See:

• wolfSSL_CIPHER_get_name
• wolfSSL_get_current_cipher

Return:

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

Example

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

function wolfSSL_get_ciphers

int wolfSSL_get_ciphers(
    char * buf,
    int len
)

This function gets the ciphers enabled in wolfSSL.

Parameters:

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

See:

• GetCipherNames
• wolfSSL_get_cipher_list
• ShowCiphers

Return:

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

Example

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

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

function wolfSSL_get_cipher_name

const char * wolfSSL_get_cipher_name(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_CIPHER_get_name
• wolfSSL_get_current_cipher
• wolfSSL_get_cipher_name_internal

Return:

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

Example

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

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

function wolfSSL_get_fd

int wolfSSL_get_fd(
    const WOLFSSL * 
)

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

Parameters:

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

See: wolfSSL_set_fd

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

Example

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

function wolfSSL_set_using_nonblock

void wolfSSL_set_using_nonblock(
    WOLFSSL * ssl,
    int nonblock
)

This function informs the WOLFSSL object that the underlying I/O is non-blocking. After an application creates a WOLFSSL object, if it will be used with a non-blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• nonblock value used to set non-blocking flag on WOLFSSL object. Use 1 to specify non-blocking, otherwise 0.

See:

• wolfSSL_get_using_nonblock
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_get_current_timeout

Return: none No return.

Example

WOLFSSL* ssl = 0;
...
wolfSSL_set_using_nonblock(ssl, 1);

function wolfSSL_get_using_nonblock

int wolfSSL_get_using_nonblock(
    WOLFSSL * 
)

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

Parameters:

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

See: wolfSSL_set_session

Return:

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

Example

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

function wolfSSL_write

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

This function writes sz bytes from the buffer, data, to the SSL connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data feature is compiled in, this function progresses the handshake only up to the point when it is possible to send data. Next invocations of wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the handshake. wolfSSL_write() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_write() will return when the underlying I/O could not satisfy the needs of wolfSSL_write() to continue. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_write() when the underlying I/O is ready. If the underlying I/O is blocking, wolfSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred.

Parameters:

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

See:

• wolfSSL_send
• wolfSSL_read
• wolfSSL_recv

Return:

• 0 the number of bytes written upon success.

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

Example

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

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

function wolfSSL_read

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

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

Parameters:

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

See:

• wolfSSL_recv
• wolfSSL_write
• wolfSSL_peek
• wolfSSL_pending

Return:

• 0 the number of bytes read upon success.

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

Example

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

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

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

function wolfSSL_peek

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

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

Parameters:

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

See: wolfSSL_read

Return:

• 0 the number of bytes read upon success.

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

Example

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

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

function wolfSSL_accept

int wolfSSL_accept(
    WOLFSSL * 
)

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

Parameters:

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

See:

• wolfSSL_get_error
• wolfSSL_connect

Return:

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

Example

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

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

function wolfSSL_CTX_free

void wolfSSL_CTX_free(
    WOLFSSL_CTX * 
)

This function frees an allocated WOLFSSL_CTX object. This function decrements the CTX reference count and only frees the context when the reference count has reached 0.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().

See:

• wolfSSL_CTX_new
• wolfSSL_new
• wolfSSL_free

Return: none No return.

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_free(ctx);

function wolfSSL_free

void wolfSSL_free(
    WOLFSSL * 
)

This function frees an allocated wolfSSL object.

Parameters:

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

See:

• wolfSSL_CTX_new
• wolfSSL_new
• wolfSSL_CTX_free

Return: none No return.

Example

#include <wolfssl/ssl.h>

WOLFSSL* ssl = 0;
...
wolfSSL_free(ssl);

function wolfSSL_shutdown

int wolfSSL_shutdown(
    WOLFSSL * 
)

This function shuts down an active SSL/TLS connection using the SSL session, ssl. This function will try to send a “close notify” alert to the peer. The calling application can choose to wait for the peer to send its “close notify” alert in response or just go ahead and shut down the underlying connection after directly calling wolfSSL_shutdown (to save resources). Either option is allowed by the TLS specification. If the underlying connection will be used again in the future, the complete two-directional shutdown procedure must be performed to keep synchronization intact between the peers. wolfSSL_shutdown() works with both blocking and non_blocking I/O. When the underlying I/O is non_blocking, wolfSSL_shutdown() will return an error if the underlying I/O could not satisfy the needs of wolfSSL_shutdown() 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_shutdown() when the underlying I/O is ready.

Parameters:

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

See:

• wolfSSL_free
• wolfSSL_CTX_free

Return:

• SSL_SUCCESS will be returned upon success.
• SSL_SHUTDOWN_NOT_DONE will be returned when shutdown has not finished, and the function should be called again.
• SSL_FATAL_ERROR will be returned upon failure. Call wolfSSL_get_error() for a more specific error code.

Example

#include <wolfssl/ssl.h>

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_shutdown(ssl);
if (ret != 0) {
    // failed to shut down SSL connection
}

function wolfSSL_send

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

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

Parameters:

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

See:

• wolfSSL_write
• wolfSSL_read
• wolfSSL_recv

Return:

• 0 the number of bytes written upon success.

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

Example

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

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

function wolfSSL_recv

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

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

Parameters:

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

See:

• wolfSSL_read
• wolfSSL_write
• wolfSSL_peek
• wolfSSL_pending

Return:

• 0 the number of bytes read upon success.

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

Example

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

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

function wolfSSL_get_error

int wolfSSL_get_error(
    WOLFSSL * ssl,
    int ret
)

This function returns a unique error code describing why the previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). The return value of the previous function is passed to wolfSSL_get_error through ret. After wolfSSL_get_error is called and returns the unique error code, wolfSSL_ERR_error_string() may be called to get a human_readable error string. See wolfSSL_ERR_error_string() for more information.

Parameters:

• ssl pointer to the SSL object, created with wolfSSL_new().
• ret return value of the previous function that resulted in an error return code.

See:

• wolfSSL_ERR_error_string
• wolfSSL_ERR_error_string_n
• wolfSSL_ERR_print_errors_fp
• wolfSSL_load_error_strings

Return:

• On successful completion, this function will return the unique error code describing why the previous API function failed.
• SSL_ERROR_NONE will be returned if ret > 0. For ret <= 0, there are some cases when this value can also be returned when a previous API appeared to return an error code but no error actually occurred. An example is calling wolfSSL_read() with a zero sz parameter. A 0 return from wolfSSL_read() usually indicates an error but in this case no error occurred. If wolfSSL_get_error() is called afterwards, SSL_ERROR_NONE will be returned.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
wolfSSL_ERR_error_string(err, buffer);
printf(“err = %d, %s\n”, err, buffer);

function wolfSSL_get_alert_history

int wolfSSL_get_alert_history(
    WOLFSSL * ssl,
    WOLFSSL_ALERT_HISTORY * h
)

This function gets the alert history.

Parameters:

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

See: wolfSSL_get_error

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

Example

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

function wolfSSL_set_session

int wolfSSL_set_session(
    WOLFSSL * ssl,
    WOLFSSL_SESSION * session
)

This function sets the session to be used when the SSL object, ssl, is used to establish a SSL/TLS connection. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get1_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. The object returned by wolfSSL_get1_session() needs to be freed after the application is done with it by calling wolfSSL_SESSION_free() on it.

Parameters:

• ssl pointer to the SSL object, created with wolfSSL_new().
• session pointer to the WOLFSSL_SESSION used to set the session for ssl.

See: wolfSSL_get1_session

Return:

• SSL_SUCCESS will be returned upon successfully setting the session.
• SSL_FAILURE will be returned on failure. This could be caused by the session cache being disabled, or if the session has timed out.
• When OPENSSL_EXTRA and WOLFSSL_ERROR_CODE_OPENSSL are defined, SSL_SUCCESS will be returned even if the session has timed out.

Example

int ret;
WOLFSSL* ssl;
WOLFSSL_SESSION* session;
...
session = wolfSSL_get1_session(ssl);
if (session == NULL) {
    // failed to get session object from ssl object
}
...
ret = wolfSSL_set_session(ssl, session);
if (ret != SSL_SUCCESS) {
    // failed to set the SSL session
}
wolfSSL_SESSION_free(session);
...

function wolfSSL_get_session

WOLFSSL_SESSION * wolfSSL_get_session(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_get1_session
• wolfSSL_set_session

Return:

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

Example

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

function wolfSSL_flush_sessions

void wolfSSL_flush_sessions(
    WOLFSSL_CTX * ctx,
    long tm
)

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

Parameters:

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

See:

• wolfSSL_get1_session
• wolfSSL_set_session

Return: none No returns.

Example

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

function wolfSSL_SetServerID

int wolfSSL_SetServerID(
    WOLFSSL * ssl,
    const unsigned char * id,
    int len,
    int newSession
)

This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• id a constant byte pointer that will be copied to the serverID member of the WOLFSSL_SESSION structure.
• len an int type representing the length of the session id parameter.
• newSession an int type representing the flag to denote whether to reuse a session or not.

See: wolfSSL_set_session

Return:

• SSL_SUCCESS returned if the function executed without error.
• BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter is NULL or if len is not greater than zero.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol );
WOLFSSL* ssl = WOLFSSL_new(ctx);
const byte id[MAX_SIZE];  // or dynamically create space
int len = 0; // initialize length
int newSession = 0; // flag to allow
…
int ret = wolfSSL_SetServerID(ssl, id, len, newSession);

if (ret == WOLFSSL_SUCCESS) {
    // The Id was successfully set
}

function wolfSSL_GetSessionIndex

int wolfSSL_GetSessionIndex(
    WOLFSSL * ssl
)

This function gets the session index of the WOLFSSL structure.

Parameters:

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

See: wolfSSL_GetSessionAtIndex

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

Example

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

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

function wolfSSL_GetSessionAtIndex

int wolfSSL_GetSessionAtIndex(
    int index,
    WOLFSSL_SESSION * session
)

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

Parameters:

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

See:

• UnLockMutex
• LockMutex
• wolfSSL_GetSessionIndex

Return:

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

Example

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

function wolfSSL_SESSION_get_peer_chain

WOLFSSL_X509_CHAIN * wolfSSL_SESSION_get_peer_chain(
    WOLFSSL_SESSION * session
)

Returns the peer certificate chain from the WOLFSSL_SESSION struct.

Parameters:

• session a pointer to a WOLFSSL_SESSION structure.

See:

• wolfSSL_GetSessionAtIndex
• wolfSSL_GetSessionIndex
• AddSession

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

Example

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

function wolfSSL_CTX_set_verify

void wolfSSL_CTX_set_verify(
    WOLFSSL_CTX * ctx,
    int mode,
    VerifyCallback verify_callback
)

This function sets the verification method for remote peers and also allows a verify callback to be registered with the SSL context. The verify callback will be called only when a verification failure has occurred. If no verify callback is desired, the NULL pointer can be used for verify_callback. The verification mode of peer certificates is a logically OR’d list of flags. The possible flag values include: SSL_VERIFY_NONE Client mode: the client will not verify the certificate received from the server and the handshake will continue as normal. Server mode: the server will not send a certificate request to the client. As such, client verification will not be enabled. SSL_VERIFY_PEER Client mode: the client will verify the certificate received from the server during the handshake. This is turned on by default in wolfSSL, therefore, using this option has no effect. Server mode: the server will send a certificate request to the client and verify the client certificate received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when used on the client side. Server mode: the verification will fail on the server side if the client fails to send a certificate when requested to do so (when using SSL_VERIFY_PEER on the SSL server). SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client side. Server mode: the verification is the same as SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. If a PSK connection is being made then the connection will go through without a peer cert.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• mode flags indicating verification mode for peer's cert.
• verify_callback callback to be called when verification fails. If no callback is desired, the NULL pointer can be used for verify_callback.

See: wolfSSL_set_verify

Return: none No return.

Example

WOLFSSL_CTX*    ctx    = 0;
...
wolfSSL_CTX_set_verify(ctx, (WOLFSSL_VERIFY_PEER |
                       WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT), NULL);

function wolfSSL_set_verify

void wolfSSL_set_verify(
    WOLFSSL * ssl,
    int mode,
    VerifyCallback verify_callback
)

This function sets the verification method for remote peers and also allows a verify callback to be registered with the SSL session. The verify callback will be called only when a verification failure has occurred. If no verify callback is desired, the NULL pointer can be used for verify_callback. The verification mode of peer certificates is a logically OR’d list of flags. The possible flag values include: SSL_VERIFY_NONE Client mode: the client will not verify the certificate received from the server and the handshake will continue as normal. Server mode: the server will not send a certificate request to the client. As such, client verification will not be enabled. SSL_VERIFY_PEER Client mode: the client will verify the certificate received from the server during the handshake. This is turned on by default in wolfSSL, therefore, using this option has no effect. Server mode: the server will send a certificate request to the client and verify the client certificate received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when used on the client side. Server mode: the verification will fail on the server side if the client fails to send a certificate when requested to do so (when using SSL_VERIFY_PEER on the SSL server). SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client side. Server mode: the verification is the same as SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. If a PSK connection is being made then the connection will go through without a peer cert.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• mode flags indicating verification mode for peer's cert.
• verify_callback callback to be called when verification fails. If no callback is desired, the NULL pointer can be used for verify_callback.

See: wolfSSL_CTX_set_verify

Return: none No return.

Example

WOLFSSL* ssl = 0;
...
wolfSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);

function wolfSSL_SetCertCbCtx

void wolfSSL_SetCertCbCtx(
    WOLFSSL * ssl,
    void * ctx
)

This function stores user CTX object information for verify callback.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• ctx a void pointer that is set to WOLFSSL structure’s verifyCbCtx member’s value.

See:

• wolfSSL_CTX_save_cert_cache
• wolfSSL_CTX_restore_cert_cache
• wolfSSL_CTX_set_verify

Return: none No return.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
(void*)ctx;
...
if(ssl != NULL){
wolfSSL_SetCertCbCtx(ssl, ctx);
} else {
    // Error case, the SSL is not initialized properly.
}

function wolfSSL_CTX_SetCertCbCtx

void wolfSSL_CTX_SetCertCbCtx(
    WOLFSSL_CTX * ctx,
    void * userCtx
)

This function stores user CTX object information for verify callback.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure.
• userCtx a void pointer that is used to set WOLFSSL_CTX structure’s verifyCbCtx member’s value.

See:

• wolfSSL_CTX_save_cert_cache
• wolfSSL_CTX_restore_cert_cache
• wolfSSL_CTX_set_verify

Return: none No return.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
void* userCtx = NULL; // Assign some user defined context
...
if(ctx != NULL){
    wolfSSL_SetCertCbCtx(ctx, userCtx);
} else {
    // Error case, the SSL is not initialized properly.
}

function wolfSSL_pending

int wolfSSL_pending(
    WOLFSSL * 
)

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

Parameters:

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

See:

• wolfSSL_recv
• wolfSSL_read
• wolfSSL_peek

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

Example

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

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

function wolfSSL_load_error_strings

void wolfSSL_load_error_strings(
    void 
)

This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action.

Parameters:

• none No parameters.

See:

• wolfSSL_get_error
• wolfSSL_ERR_error_string
• wolfSSL_ERR_error_string_n
• wolfSSL_ERR_print_errors_fp
• wolfSSL_load_error_strings

Return: none No returns.

Example

wolfSSL_load_error_strings();

function wolfSSL_library_init

int wolfSSL_library_init(
    void 
)

This function is called internally in wolfSSL_CTX_new(). This function is a wrapper around wolfSSL_Init() and exists for OpenSSL compatibility (SSL_library_init) when wolfSSL has been compiled with OpenSSL compatibility layer. wolfSSL_Init() is the more typically-used wolfSSL initialization function.

Parameters:

• none No parameters.

See:

• wolfSSL_Init
• wolfSSL_Cleanup

Return:

• SSL_SUCCESS If successful the call will return.
• SSL_FATAL_ERROR is returned upon failure.

Example

int ret = 0;
ret = wolfSSL_library_init();
if (ret != SSL_SUCCESS) {
    failed to initialize wolfSSL
}
...

function wolfSSL_SetDevId

int wolfSSL_SetDevId(
    WOLFSSL * ssl,
    int devId
)

This function sets the Device Id at the WOLFSSL session level.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

• wolfSSL_CTX_SetDevId
• wolfSSL_CTX_GetDevId

Return:

• WOLFSSL_SUCCESS upon success.
• BAD_FUNC_ARG if ssl is NULL.

Example

WOLFSSL* ssl;
int DevId = -2;

wolfSSL_SetDevId(ssl, devId);

function wolfSSL_CTX_SetDevId

int wolfSSL_CTX_SetDevId(
    WOLFSSL_CTX * ctx,
    int devId
)

This function sets the Device Id at the WOLFSSL_CTX context level.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

• wolfSSL_SetDevId
• wolfSSL_CTX_GetDevId

Return:

• WOLFSSL_SUCCESS upon success.
• BAD_FUNC_ARG if ssl is NULL.

Example

WOLFSSL_CTX* ctx;
int DevId = -2;

wolfSSL_CTX_SetDevId(ctx, devId);

function wolfSSL_CTX_GetDevId

int wolfSSL_CTX_GetDevId(
    WOLFSSL_CTX * ctx,
    WOLFSSL * ssl
)

This function retrieves the Device Id.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• ssl pointer to a SSL object, created with wolfSSL_new().

See:

• wolfSSL_SetDevId
• wolfSSL_CTX_SetDevId

Return:

• devId upon success.
• INVALID_DEVID if both ssl and ctx are NULL.

Example

WOLFSSL_CTX* ctx;

wolfSSL_CTX_GetDevId(ctx, ssl);

function wolfSSL_CTX_set_session_cache_mode

long wolfSSL_CTX_set_session_cache_mode(
    WOLFSSL_CTX * ctx,
    long mode
)

This function enables or disables SSL session caching. Behavior depends on the value used for mode. The following values for mode are available: SSL_SESS_CACHE_OFF- disable session caching. Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR - Disable auto-flushing of the session cache. Auto-flushing is turned on by default.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• mode modifier used to change behavior of the session cache.

See:

• wolfSSL_flush_sessions
• wolfSSL_get1_session
• wolfSSL_set_session
• wolfSSL_get_sessionID
• wolfSSL_CTX_set_timeout

Return: SSL_SUCCESS will be returned upon success.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);
if (ret != SSL_SUCCESS) {
    // failed to turn SSL session caching off
}

function wolfSSL_set_session_secret_cb

int wolfSSL_set_session_secret_cb(
    WOLFSSL * ssl,
    SessionSecretCb cb,
    void * ctx
)

This function sets the session secret callback function. The SessionSecretCb type has the signature: int (SessionSecretCb)(WOLFSSL ssl, void secret, int secretSz, void* ctx). The sessionSecretCb member of the WOLFSSL struct is set to the parameter cb.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a SessionSecretCb type that is a function pointer with the above signature.
• ctx a pointer to the user context to be stored

See: SessionSecretCb

Return:

• SSL_SUCCESS returned if the execution of the function did not return an error.
• SSL_FATAL_ERROR returned if the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
// Signature of SessionSecretCb
int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz,
void* ctx) = SessionSecretCb;
…
int wolfSSL_set_session_secret_cb(ssl, SessionSecretCB, (void*)ssl->ctx){
    // Function body.
}

function wolfSSL_save_session_cache

int wolfSSL_save_session_cache(
    const char * fname
)

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

Parameters:

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

See:

• XFWRITE
• wolfSSL_restore_session_cache
• wolfSSL_memrestore_session_cache

Return:

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

Example

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

function wolfSSL_restore_session_cache

int wolfSSL_restore_session_cache(
    const char * fname
)

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

Parameters:

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

See:

• XFREAD
• XFOPEN

Return:

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

Example

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

function wolfSSL_memsave_session_cache

int wolfSSL_memsave_session_cache(
    void * mem,
    int sz
)

This function persists session cache to memory.

Parameters:

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

See:

• XMEMCPY
• wolfSSL_get_session_cache_memsize

Return:

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

Example

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

function wolfSSL_memrestore_session_cache

int wolfSSL_memrestore_session_cache(
    const void * mem,
    int sz
)

This function restores the persistent session cache from memory.

Parameters:

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

See: wolfSSL_save_session_cache

Return:

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

Example

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

function wolfSSL_get_session_cache_memsize

int wolfSSL_get_session_cache_memsize(
    void 
)

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

Parameters:

• none No parameters.

See: wolfSSL_memrestore_session_cache

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

Example

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

function wolfSSL_CTX_save_cert_cache

int wolfSSL_CTX_save_cert_cache(
    WOLFSSL_CTX * ctx,
    const char * fname
)

This function writes the cert cache from memory to file.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, holding the certificate information.
• fname a constant char pointer that points to a file for writing.

See:

• CM_SaveCertCache
• DoMemSaveCertCache

Return:

• SSL_SUCCESS if CM_SaveCertCache exits normally.
• BAD_FUNC_ARG is returned if either of the arguments are NULL.
• SSL_BAD_FILE if the cert cache save file could not be opened.
• BAD_MUTEX_E if the lock mutex failed.
• MEMORY_E the allocation of memory failed.
• FWRITE_ERROR Certificate cache file write failed.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
const char* fname;
...
if(wolfSSL_CTX_save_cert_cache(ctx, fname)){
    // file was written.
}

function wolfSSL_CTX_restore_cert_cache

int wolfSSL_CTX_restore_cert_cache(
    WOLFSSL_CTX * ctx,
    const char * fname
)

This function persistes certificate cache from a file.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, holding the certificate information.
• fname a constant char pointer that points to a file for reading.

See:

• CM_RestoreCertCache
• XFOPEN

Return:

• SSL_SUCCESS returned if the function, CM_RestoreCertCache, executes normally.
• SSL_BAD_FILE returned if XFOPEN returns XBADFILE. The file is corrupted.
• MEMORY_E returned if the allocated memory for the temp buffer fails.
• BAD_FUNC_ARG returned if fname or ctx have a NULL value.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
const char* fname = "path to file";
...
if(wolfSSL_CTX_restore_cert_cache(ctx, fname)){
    // check to see if the execution was successful
}

function wolfSSL_CTX_memsave_cert_cache

int wolfSSL_CTX_memsave_cert_cache(
    WOLFSSL_CTX * ctx,
    void * mem,
    int sz,
    int * used
)

This function persists the certificate cache to memory.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• mem a void pointer to the destination (output buffer).
• sz the size of the output buffer.
• used a pointer to size of the cert cache header.

See:

• DoMemSaveCertCache
• GetCertCacheMemSize
• CM_MemRestoreCertCache
• CM_GetCertCacheMemSize

Return:

• SSL_SUCCESS returned on successful execution of the function. No errors were thrown.
• BAD_MUTEX_E mutex error where the WOLFSSL_CERT_MANAGER member caLock was not 0 (zero).
• BAD_FUNC_ARG returned if ctx, mem, or used is NULL or if sz is less than or equal to 0 (zero).
• BUFFER_E output buffer mem was too small.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol );
void* mem;
int sz;
int* used;
...
if(wolfSSL_CTX_memsave_cert_cache(ctx, mem, sz, used) != SSL_SUCCESS){
    // The function returned with an error
}

function wolfSSL_CTX_memrestore_cert_cache

int wolfSSL_CTX_memrestore_cert_cache(
    WOLFSSL_CTX * ctx,
    const void * mem,
    int sz
)

This function restores the certificate cache from memory.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• mem a void pointer with a value that will be restored to the certificate cache.
• sz an int type that represents the size of the mem parameter.

See: CM_MemRestoreCertCache

Return:

• SSL_SUCCESS returned if the function and subroutines executed without an error.
• BAD_FUNC_ARG returned if the ctx or mem parameters are NULL or if the sz parameter is less than or equal to zero.
• BUFFER_E returned if the cert cache memory buffer is too small.
• CACHE_MATCH_ERROR returned if there was a cert cache header mismatch.
• BAD_MUTEX_E returned if the lock mutex on failed.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
void* mem;
int sz = (*int) sizeof(mem);
…
if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){
    // The success case
}

function wolfSSL_CTX_get_cert_cache_memsize

int wolfSSL_CTX_get_cert_cache_memsize(
    WOLFSSL_CTX * ctx
)

Returns the size the certificate cache save buffer needs to be.

Parameters:

• ctx a pointer to a wolfSSL_CTX structure, created using wolfSSL_CTX_new().

See: CM_GetCertCacheMemSize

Return:

• int integer value returned representing the memory size upon success.
• BAD_FUNC_ARG is returned if the WOLFSSL_CTX struct is NULL.
• BAD_MUTEX_E - returned if there was a mutex lock error.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol);
...
int certCacheSize = wolfSSL_CTX_get_cert_cache_memsize(ctx);

if(certCacheSize != BAD_FUNC_ARG || certCacheSize != BAD_MUTEX_E){
// Successfully retrieved the memory size.
}

function wolfSSL_CTX_set_cipher_list

int wolfSSL_CTX_set_cipher_list(
    WOLFSSL_CTX * ctx,
    const char * list
)

This function sets cipher suite list for a given WOLFSSL_CTX. This cipher suite list becomes the default list for any new SSL sessions (WOLFSSL) created using this context. The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the specific SSL context to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256" Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• list null-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL context.

See:

• wolfSSL_set_cipher_list
• wolfSSL_CTX_new

Return:

• SSL_SUCCESS will be returned upon successful function completion.
• SSL_FAILURE will be returned on failure.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_cipher_list(ctx,
“DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);
if (ret != SSL_SUCCESS) {
    // failed to set cipher suite list
}

function wolfSSL_set_cipher_list

int wolfSSL_set_cipher_list(
    WOLFSSL * ssl,
    const char * list
)

This function sets cipher suite list for a given WOLFSSL object (SSL session). The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_set_cipher_list() resets the cipher suite list for the specific SSL session to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256". Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• list null-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL session.

See:

• wolfSSL_CTX_set_cipher_list
• wolfSSL_new

Return:

• SSL_SUCCESS will be returned upon successful function completion.
• SSL_FAILURE will be returned on failure.

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_cipher_list(ssl,
“DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);
if (ret != SSL_SUCCESS) {
    // failed to set cipher suite list
}

function wolfSSL_dtls_set_using_nonblock

void wolfSSL_dtls_set_using_nonblock(
    WOLFSSL * ssl,
    int nonblock
)

This function informs the WOLFSSL DTLS object that the underlying UDP I/O is non-blocking. After an application creates a WOLFSSL object, if it will be used with a non-blocking UDP socket, call wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.

Parameters:

• ssl pointer to the DTLS session, created with wolfSSL_new().
• nonblock value used to set non-blocking flag on WOLFSSL object. Use 1 to specify non-blocking, otherwise 0.

See:

• wolfSSL_dtls_get_using_nonblock
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_get_current_timeout

Return: none No return.

Example

WOLFSSL* ssl = 0;
...
wolfSSL_dtls_set_using_nonblock(ssl, 1);

function wolfSSL_dtls_get_using_nonblock

int wolfSSL_dtls_get_using_nonblock(
    WOLFSSL * ssl
)

This function allows the application to determine if wolfSSL is using non-blocking I/O with UDP. 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 UDP socket, call wolfSSL_dtls_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. This function is only meaningful to DTLS sessions.

Parameters:

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

See:

• wolfSSL_dtls_set_using_nonblock
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_using_nonblock

Return:

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

Example

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

function wolfSSL_dtls_get_current_timeout

int wolfSSL_dtls_get_current_timeout(
    WOLFSSL * ssl
)

This function returns the current timeout value in seconds for the WOLFSSL object. When using non-blocking sockets, something in the user code needs to decide when to check for available recv data and how long it has been waiting. The value returned by this function indicates how long the application should wait.

Parameters:

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

See:

• wolfSSL_dtls
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_peer

Return:

• seconds The current DTLS timeout value in seconds
• NOT_COMPILED_IN if wolfSSL was not built with DTLS support.

Example

int timeout = 0;
WOLFSSL* ssl;
...
timeout = wolfSSL_get_dtls_current_timeout(ssl);
printf(“DTLS timeout (sec) = %d\n”, timeout);

function wolfSSL_dtls13_use_quick_timeout

int wolfSSL_dtls13_use_quick_timeout(
    WOLFSSL * ssl
)

This function returns true if the application should setup a quicker timeout. When using non-blocking sockets, something in the user code needs to decide when to check for available data and how long it needs to wait. If this function returns true, it means that the library already detected some disruption in the communication, but it wants to wait for a little longer in case some messages from the other peers are still in flight. Is up to the application to fine tune the value of this timer, a good one may be dtls_get_current_timeout() / 4.

Parameters:

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

See:

• wolfSSL_dtls
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_peer
• wolfSSL_dtls13_set_send_more_acks

Return: true if the application code should setup a quicker timeout

function wolfSSL_dtls13_set_send_more_acks

void wolfSSL_dtls13_set_send_more_acks(
    WOLFSSL * ssl,
    int value
)

This function sets whether the library should send ACKs to the other peer immediately when detecting disruption or not. Sending ACKs immediately assures minimum latency but it may consume more bandwidth than necessary. If the application manages the timer by itself and this option is set to 0 then application code can use wolfSSL_dtls13_use_quick_timeout() to determine if it should setup a quicker timeout to send those delayed ACKs.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• value 1 to set the option, 0 to disable the option

See:

• wolfSSL_dtls
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_peer
• wolfSSL_dtls13_use_quick_timeout

function wolfSSL_dtls_set_timeout_init

int wolfSSL_dtls_set_timeout_init(
    WOLFSSL * ssl,
    int 
)

This function sets the dtls timeout.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• timeout an int type that will be set to the dtls_timeout_init member of the WOLFSSL structure.

See:

• wolfSSL_dtls_set_timeout_max
• wolfSSL_dtls_got_timeout

Return:

• SSL_SUCCESS returned if the function executes without an error. The dtls_timeout_init and the dtls_timeout members of SSL have been set.
• BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if the timeout is not greater than 0. It will also return if the timeout argument exceeds the maximum value allowed.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int timeout = TIMEOUT;
...
if(wolfSSL_dtls_set_timeout_init(ssl, timeout)){
    // the dtls timeout was set
} else {
    // Failed to set DTLS timeout.
}

function wolfSSL_dtls_set_timeout_max

int wolfSSL_dtls_set_timeout_max(
    WOLFSSL * ssl,
    int 
)

This function sets the maximum dtls timeout.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• timeout an int type representing the dtls maximum timeout.

See:

• wolfSSL_dtls_set_timeout_init
• wolfSSL_dtls_got_timeout

Return:

• SSL_SUCCESS returned if the function executed without an error.
• BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if the timeout argument is not greater than zero or is less than the dtls_timeout_init member of the WOLFSSL structure.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int timeout = TIMEOUTVAL;
...
int ret = wolfSSL_dtls_set_timeout_max(ssl);
if(!ret){
    // Failed to set the max timeout
}

function wolfSSL_dtls_got_timeout

int wolfSSL_dtls_got_timeout(
    WOLFSSL * ssl
)

When using non-blocking sockets with DTLS, this function should be called on the WOLFSSL object when the controlling code thinks the transmission has timed out. It performs the actions needed to retry the last transmit, including adjusting the timeout value. If it has been too long, this will return a failure.

Parameters:

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

See:

• wolfSSL_dtls_get_current_timeout
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_set_peer
• wolfSSL_dtls

Return:

• SSL_SUCCESS will be returned upon success
• SSL_FATAL_ERROR will be returned if there have been too many retransmissions/timeouts without getting a response from the peer.
• NOT_COMPILED_IN will be returned if wolfSSL was not compiled with DTLS support.

Example

See the following files for usage examples:
<wolfssl_root>/examples/client/client.c
<wolfssl_root>/examples/server/server.c

function wolfSSL_dtls_retransmit

int wolfSSL_dtls_retransmit(
    WOLFSSL * ssl
)

When using non-blocking sockets with DTLS, this function retransmits the last handshake flight ignoring the expected timeout value and retransmit count. It is useful for applications that are using DTLS and need to manage even the timeout and retry count.

Parameters:

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

See:

• wolfSSL_dtls_get_current_timeout
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls

Return:

• SSL_SUCCESS will be returned upon success
• SSL_FATAL_ERROR will be returned if there have been too many retransmissions/timeouts without getting a response from the peer.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_dtls_retransmit(ssl);

function wolfSSL_dtls

int wolfSSL_dtls(
    WOLFSSL * ssl
)

This function is used to determine if the SSL session has been configured to use DTLS.

Parameters:

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

See:

• wolfSSL_dtls_get_current_timeout
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_peer

Return:

• 1 If the SSL session (ssl) has been configured to use DTLS, this function will return 1.
• 0 otherwise.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_dtls(ssl);
if (ret) {
    // SSL session has been configured to use DTLS
}

function wolfSSL_dtls_set_peer

int wolfSSL_dtls_set_peer(
    WOLFSSL * ssl,
    void * peer,
    unsigned int peerSz
)

This function sets the DTLS peer, peer (sockaddr_in) with size of peerSz.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• peer pointer to peer’s sockaddr_in structure. If NULL then the peer information in ssl is cleared.
• peerSz size of the sockaddr_in structure pointed to by peer. If 0 then the peer information in ssl is cleared.

See:

• wolfSSL_dtls_get_current_timeout
• wolfSSL_dtls_get_peer
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls

Return:

• SSL_SUCCESS will be returned upon success.
• SSL_FAILURE will be returned upon failure.
• SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS support.

Example

int ret = 0;
WOLFSSL* ssl;
sockaddr_in addr;
...
ret = wolfSSL_dtls_set_peer(ssl, &addr, sizeof(addr));
if (ret != SSL_SUCCESS) {
    // failed to set DTLS peer
}

function wolfSSL_dtls_get_peer

int wolfSSL_dtls_get_peer(
    WOLFSSL * ssl,
    void * peer,
    unsigned int * peerSz
)

This function gets the sockaddr_in (of size peerSz) of the current DTLS peer. The function will compare peerSz to the actual DTLS peer size stored in the SSL session. If the peer will fit into peer, the peer’s sockaddr_in will be copied into peer, with peerSz set to the size of peer.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• peer pointer to memory location to store peer’s sockaddr_in structure.
• peerSz input/output size. As input, the size of the allocated memory pointed to by peer. As output, the size of the actual sockaddr_in structure pointed to by peer.

See:

• wolfSSL_dtls_get_current_timeout
• wolfSSL_dtls_got_timeout
• wolfSSL_dtls_set_peer
• wolfSSL_dtls

Return:

• SSL_SUCCESS will be returned upon success.
• SSL_FAILURE will be returned upon failure.
• SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS support.

Example

int ret = 0;
WOLFSSL* ssl;
sockaddr_in addr;
...
ret = wolfSSL_dtls_get_peer(ssl, &addr, sizeof(addr));
if (ret != SSL_SUCCESS) {
    // failed to get DTLS peer
}

function wolfSSL_ERR_error_string

char * wolfSSL_ERR_error_string(
    unsigned long errNumber,
    char * data
)

This function converts an error code returned by wolfSSL_get_error() into a more human_readable error string. errNumber is the error code returned by wolfSSL_get_error() and data is the storage buffer which the error string will be placed in. The maximum length of data is 80 characters by default, as defined by MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h.

Parameters:

• errNumber error code returned by wolfSSL_get_error().
• data output buffer containing human-readable error string matching errNumber.

See:

• wolfSSL_get_error
• wolfSSL_ERR_error_string_n
• wolfSSL_ERR_print_errors_fp
• wolfSSL_load_error_strings

Return:

• success On successful completion, this function returns the same string as is returned in data.
• failure Upon failure, this function returns a string with the appropriate failure reason, msg.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
wolfSSL_ERR_error_string(err, buffer);
printf(“err = %d, %s\n”, err, buffer);

function wolfSSL_ERR_error_string_n

void wolfSSL_ERR_error_string_n(
    unsigned long e,
    char * buf,
    unsigned long sz
)

This function is a version of wolfSSL_ERR_error_string() where len specifies the maximum number of characters that may be written to buf. Like wolfSSL_ERR_error_string(), this function converts an error code returned from wolfSSL_get_error() into a more human-readable error string. The human-readable string is placed in buf.

Parameters:

• e error code returned by wolfSSL_get_error().
• buff output buffer containing human-readable error string matching e.
• len maximum length in characters which may be written to buf.

See:

• wolfSSL_get_error
• wolfSSL_ERR_error_string
• wolfSSL_ERR_print_errors_fp
• wolfSSL_load_error_strings

Return: none No returns.

Example

int err = 0;
WOLFSSL* ssl;
char buffer[80];
...
err = wolfSSL_get_error(ssl, 0);
wolfSSL_ERR_error_string_n(err, buffer, 80);
printf(“err = %d, %s\n”, err, buffer);

function wolfSSL_get_shutdown

int wolfSSL_get_shutdown(
    const WOLFSSL * ssl
)

This function checks the shutdown conditions in closeNotify or connReset or sentNotify members of the Options structure. The Options structure is within the WOLFSSL structure.

Parameters:

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

See: wolfSSL_SESSION_free

Return:

• 1 SSL_SENT_SHUTDOWN is returned.
• 2 SSL_RECEIVED_SHUTDOWN is returned.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
…
int ret;
ret = wolfSSL_get_shutdown(ssl);

if(ret == 1){
    SSL_SENT_SHUTDOWN
} else if(ret == 2){
    SSL_RECEIVED_SHUTDOWN
} else {
    Fatal error.
}

function wolfSSL_session_reused

int wolfSSL_session_reused(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_SESSION_free
• wolfSSL_GetSessionIndex
• wolfSSL_memsave_session_cache

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

Example

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

function wolfSSL_is_init_finished

int wolfSSL_is_init_finished(
    WOLFSSL * ssl
)

This function checks to see if the connection is established.

Parameters:

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

See:

• wolfSSL_set_accept_state
• wolfSSL_get_keys
• wolfSSL_set_shutdown

Return:

• 0 returned if the connection is not established, i.e. the WOLFSSL struct is NULL or the handshake is not done.
• 1 returned if the connection is established i.e. the WOLFSSL handshake is done.

EXAMPLE

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_is_init_finished(ssl)){
    Handshake is done and connection is established
}

function wolfSSL_get_version

const char * wolfSSL_get_version(
    WOLFSSL * ssl
)

Returns the SSL version being used as a string.

Parameters:

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

See: wolfSSL_lib_version

Return:

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

Example

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

function wolfSSL_get_current_cipher_suite

int wolfSSL_get_current_cipher_suite(
    WOLFSSL * ssl
)

Returns the current cipher suit an ssl session is using.

Parameters:

• ssl The SSL session to check.

See:

• wolfSSL_CIPHER_get_name
• wolfSSL_get_current_cipher
• wolfSSL_get_cipher_list

Return:

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

Example

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

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

function wolfSSL_get_current_cipher

WOLFSSL_CIPHER * wolfSSL_get_current_cipher(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_get_cipher
• wolfSSL_get_cipher_name_internal
• wolfSSL_get_cipher_name

Return:

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

Example

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

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

function wolfSSL_CIPHER_get_name

const char * wolfSSL_CIPHER_get_name(
    const WOLFSSL_CIPHER * cipher
)

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

Parameters:

• cipher a constant pointer to a WOLFSSL_CIPHER structure.

See:

• wolfSSL_get_cipher
• wolfSSL_get_current_cipher
• wolfSSL_get_cipher_name_internal
• wolfSSL_get_cipher_name

Return:

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

Example

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

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

function wolfSSL_get_cipher

const char * wolfSSL_get_cipher(
    WOLFSSL * 
)

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

Parameters:

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

See:

• wolfSSL_CIPHER_get_name
• wolfSSL_get_current_cipher

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

Example

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

function wolfSSL_get1_session

WOLFSSL_SESSION * wolfSSL_get1_session(
    WOLFSSL * ssl
)

This function returns the WOLFSSL_SESSION from the WOLFSSL structure as a reference type. This requires calling wolfSSL_SESSION_free to release the session reference. The WOLFSSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake. For session resumption, before calling wolfSSL_shutdown() with your session object, an application should save the session ID from the object with a call to wolfSSL_get1_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. The object returned by wolfSSL_get1_session() needs to be freed after the application is done with it by calling wolfSSL_SESSION_free() on it.

Parameters:

• ssl WOLFSSL structure to get session from.

See:

• wolfSSL_new
• wolfSSL_free
• wolfSSL_SESSION_free

Return:

• WOLFSSL_SESSION On success return session pointer.
• NULL will be returned if ssl is NULL, the SSL session cache is disabled, wolfSSL doesn’t have the Session ID available, or mutex functions fail.

Example

WOLFSSL* ssl;
WOLFSSL_SESSION* ses;
// attempt/complete handshake
wolfSSL_connect(ssl);
ses  = wolfSSL_get1_session(ssl);
// check ses information
// disconnect / setup new SSL instance
wolfSSL_set_session(ssl, ses);
// attempt/resume handshake
wolfSSL_SESSION_free(ses);

function wolfSSLv23_client_method

WOLFSSL_METHOD * wolfSSLv23_client_method(
    void 
)

The wolfSSLv23_client_method() function is used to indicate that the application is a client and will support the highest protocol version supported by the server between SSL 3.0 _ TLS 1.3. This function allocates memory for and initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). Both wolfSSL clients and servers have robust version downgrade capability. If a specific protocol version method is used on either side, then only that version will be negotiated or an error will be returned. For example, a client that uses TLSv1 and tries to connect to a SSLv3 only server will fail, likewise connecting to a TLSv1.1 will fail as well. To resolve this issue, a client that uses the wolfSSLv23_client_method() function will use the highest protocol version supported by the server and downgrade to SSLv3 if needed. In this case, the client will be able to connect to a server running SSLv3 - TLSv1.3.

Parameters:

• none No parameters

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSL_CTX_new

Return:

• pointer upon success a pointer to a WOLFSSL_METHOD.
• Failure If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;
method = wolfSSLv23_client_method();
if (method == NULL) {
// unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfSSL_BIO_get_mem_data

int wolfSSL_BIO_get_mem_data(
    WOLFSSL_BIO * bio,
    void * p
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_set_fp
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_set_fd

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

Sets the file descriptor for bio to use.

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_free

Return: SSL_SUCCESS(1) upon success.

Example

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

function wolfSSL_BIO_set_close

int wolfSSL_BIO_set_close(
    WOLFSSL_BIO * b,
    long flag
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_free

Return: SSL_SUCCESS(1) upon success.

Example

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

function wolfSSL_BIO_s_socket

WOLFSSL_BIO_METHOD * wolfSSL_BIO_s_socket(
    void 
)

This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.

Parameters:

• none No parameters.

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem

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

Example

WOLFSSL_BIO* bio;
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);

function wolfSSL_BIO_set_write_buf_size

int wolfSSL_BIO_set_write_buf_size(
    WOLFSSL_BIO * b,
    long size
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_make_bio_pair

int wolfSSL_BIO_make_bio_pair(
    WOLFSSL_BIO * b1,
    WOLFSSL_BIO * b2
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_ctrl_reset_read_request

int wolfSSL_BIO_ctrl_reset_read_request(
    WOLFSSL_BIO * bio
)

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

Parameters:

• bio WOLFSSL_BIO structure to set read request flag.

See:

• wolfSSL_BIO_new, wolfSSL_BIO_s_mem
• wolfSSL_BIO_new, wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_nread0

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

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_nwrite0

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

Example

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

function wolfSSL_BIO_nread

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

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_nwrite

Return:

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

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

Example

WOLFSSL_BIO* bio;
char* bufPt;
int ret;

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

function wolfSSL_BIO_nwrite

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

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_free
• wolfSSL_BIO_nread

Return:

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

Example

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

function wolfSSL_BIO_reset

int wolfSSL_BIO_reset(
    WOLFSSL_BIO * bio
)

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

Parameters:

• bio WOLFSSL_BIO structure to reset.

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_seek

int wolfSSL_BIO_seek(
    WOLFSSL_BIO * bio,
    int ofs
)

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

Parameters:

• bio WOLFSSL_BIO structure to set.
• ofs offset into file.

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_set_fp
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_write_filename

int wolfSSL_BIO_write_filename(
    WOLFSSL_BIO * bio,
    char * name
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_file
• wolfSSL_BIO_set_fp
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_set_mem_eof_return

long wolfSSL_BIO_set_mem_eof_return(
    WOLFSSL_BIO * bio,
    int v
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_set_fp
• wolfSSL_BIO_free

Return: 0 returned on completion

Example

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

function wolfSSL_BIO_get_mem_ptr

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

This is a getter function for WOLFSSL_BIO memory pointer.

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem

Return:

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

Example

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

function wolfSSL_X509_NAME_oneline

char * wolfSSL_X509_NAME_oneline(
    WOLFSSL_X509_NAME * name,
    char * in,
    int sz
)

This function copies the name of the x509 into a buffer.

Parameters:

• name a pointer to a WOLFSSL_X509 structure.
• in a buffer to hold the name copied from the WOLFSSL_X509_NAME structure.
• sz the maximum size of the buffer.

See:

• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_isCA
• wolfSSL_get_peer_certificate
• wolfSSL_X509_version

Return: A char pointer to the buffer with the WOLFSSL_X509_NAME structures name member’s data is returned if the function executed normally.

Example

WOLFSSL_X509 x509;
char* name;
...
name = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);

if(name <= 0){
    // There’s nothing in the buffer.
}

function wolfSSL_X509_get_issuer_name

WOLFSSL_X509_NAME * wolfSSL_X509_get_issuer_name(
    WOLFSSL_X509 * cert
)

This function returns the name of the certificate issuer.

Parameters:

• cert a pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_isCA
• wolfSSL_get_peer_certificate
• wolfSSL_X509_NAME_oneline

Return:

• point a pointer to the WOLFSSL_X509 struct’s issuer member is returned.
• NULL if the cert passed in is NULL.

Example

WOLFSSL_X509* x509;
WOLFSSL_X509_NAME issuer;
...
issuer = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);

if(!issuer){
    // NULL was returned
} else {
    // issuer hods the name of the certificate issuer.
}

function wolfSSL_X509_get_subject_name

WOLFSSL_X509_NAME * wolfSSL_X509_get_subject_name(
    WOLFSSL_X509 * cert
)

This function returns the subject member of the WOLFSSL_X509 structure.

Parameters:

• cert a pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_isCA
• wolfSSL_get_peer_certificate

Return: pointer a pointer to the WOLFSSL_X509_NAME structure. The pointer may be NULL if the WOLFSSL_X509 struct is NULL or if the subject member of the structure is NULL.

Example

WOLFSSL_X509* cert;
WOLFSSL_X509_NAME name;
…
name = wolfSSL_X509_get_subject_name(cert);
if(name == NULL){
    // Deal with the NULL cacse
}

function wolfSSL_X509_get_isCA

int wolfSSL_X509_get_isCA(
    WOLFSSL_X509 * cert
)

Checks the isCa member of the WOLFSSL_X509 structure and returns the value.

Parameters:

• cert a pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_isCA

Return:

• isCA returns the value in the isCA member of the WOLFSSL_X509 structure is returned.
• 0 returned if there is not a valid x509 structure passed in.

Example

WOLFSSL* ssl;
...
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_X509_get_isCA(ssl)){
    // This is the CA
}else {
    // Failure case
}

function wolfSSL_X509_NAME_get_text_by_NID

int wolfSSL_X509_NAME_get_text_by_NID(
    WOLFSSL_X509_NAME * name,
    int nid,
    char * buf,
    int len
)

This function gets the text related to the passed in NID value.

Parameters:

• name WOLFSSL_X509_NAME to search for text.
• nid NID to search for.
• buf buffer to hold text when found.
• len length of buffer.

See: none

Return: int returns the size of the text buffer.

Example

WOLFSSL_X509_NAME* name;
char buffer[100];
int bufferSz;
int ret;
// get WOLFSSL_X509_NAME
ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName,
buffer, bufferSz);

//check ret value

function wolfSSL_X509_get_signature_type

int wolfSSL_X509_get_signature_type(
    WOLFSSL_X509 * cert
)

This function returns the value stored in the sigOID member of the WOLFSSL_X509 structure.

Parameters:

• cert a pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_signature
• wolfSSL_X509_version
• wolfSSL_X509_get_der
• wolfSSL_X509_get_serial_number
• wolfSSL_X509_notBefore
• wolfSSL_X509_notAfter
• wolfSSL_X509_free

Return:

• 0 returned if the WOLFSSL_X509 structure is NULL.
• int an integer value is returned which was retrieved from the x509 object.

Example

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                        DYNAMIC_TYPE_X509);
...
int x509SigType = wolfSSL_X509_get_signature_type(x509);

if(x509SigType != EXPECTED){
// Deal with an unexpected value
}

function wolfSSL_X509_free

void wolfSSL_X509_free(
    WOLFSSL_X509 * x509
)

This function frees a WOLFSSL_X509 structure.

Parameters:

• x509 a pointer to the WOLFSSL_X509 struct.

See:

• wolfSSL_X509_get_signature
• wolfSSL_X509_version
• wolfSSL_X509_get_der
• wolfSSL_X509_get_serial_number
• wolfSSL_X509_notBefore
• wolfSSL_X509_notAfter

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509) ;

wolfSSL_X509_free(x509);

function wolfSSL_X509_get_signature

int wolfSSL_X509_get_signature(
    WOLFSSL_X509 * x509,
    unsigned char * buf,
    int * bufSz
)

Gets the X509 signature and stores it in the buffer.

Parameters:

• x509 pointer to a WOLFSSL_X509 structure.
• buf a char pointer to the buffer.
• bufSz an integer pointer to the size of the buffer.

See:

• wolfSSL_X509_get_serial_number
• wolfSSL_X509_get_signature_type
• wolfSSL_X509_get_device_type

Return:

• SSL_SUCCESS returned if the function successfully executes. The signature is loaded into the buffer.
• SSL_FATAL_ERRROR returns if the x509 struct or the bufSz member is NULL. There is also a check for the length member of the sig structure (sig is a member of x509).

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509);
unsigned char* buf; // Initialize
int* bufSz = sizeof(buf)/sizeof(unsigned char);
...
if(wolfSSL_X509_get_signature(x509, buf, bufSz) != SSL_SUCCESS){
    // The function did not execute successfully.
} else{
    // The buffer was written to correctly.
}

function wolfSSL_X509_STORE_add_cert

int wolfSSL_X509_STORE_add_cert(
    WOLFSSL_X509_STORE * store,
    WOLFSSL_X509 * x509
)

This function adds a certificate to the WOLFSSL_X509_STRE structure.

Parameters:

• str certificate store to add the certificate to.
• x509 certificate to add.

See: wolfSSL_X509_free

Return:

• SSL_SUCCESS If certificate is added successfully.
• SSL_FATAL_ERROR: If certificate is not added successfully.

Example

WOLFSSL_X509_STORE* str;
WOLFSSL_X509* x509;
int ret;
ret = wolfSSL_X509_STORE_add_cert(str, x509);
//check ret value

function wolfSSL_X509_STORE_CTX_get_chain

WOLFSSL_STACK * wolfSSL_X509_STORE_CTX_get_chain(
    WOLFSSL_X509_STORE_CTX * ctx
)

This function is a getter function for chain variable in WOLFSSL_X509_STORE_CTX structure. Currently chain is not populated.

Parameters:

• ctx certificate store ctx to get parse chain from.

See: wolfSSL_sk_X509_free

Return:

• pointer if successful returns WOLFSSL_STACK (same as STACK_OF(WOLFSSL_X509)) pointer
• Null upon failure

Example

WOLFSSL_STACK* sk;
WOLFSSL_X509_STORE_CTX* ctx;
sk = wolfSSL_X509_STORE_CTX_get_chain(ctx);
//check sk for NULL and then use it. sk needs freed after done.

function wolfSSL_X509_STORE_set_flags

int wolfSSL_X509_STORE_set_flags(
    WOLFSSL_X509_STORE * store,
    unsigned long flag
)

This function takes in a flag to change the behavior of the WOLFSSL_X509_STORE structure passed in. An example of a flag used is WOLFSSL_CRL_CHECK.

Parameters:

• str certificate store to set flag in.
• flag flag for behavior.

See:

• wolfSSL_X509_STORE_new
• wolfSSL_X509_STORE_free

Return:

• SSL_SUCCESS If no errors were encountered when setting the flag.
• <0 a negative value will be returned upon failure.

Example

WOLFSSL_X509_STORE* str;
int ret;
// create and set up str
ret = wolfSSL_X509_STORE_set_flags(str, WOLFSSL_CRL_CHECKALL);
If (ret != SSL_SUCCESS) {
    //check ret value and handle error case
}

function wolfSSL_X509_notBefore

const byte * wolfSSL_X509_notBefore(
    WOLFSSL_X509 * x509
)

This function the certificate "not before" validity encoded as a byte array.

Parameters:

• x509 pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_signature
• wolfSSL_X509_version
• wolfSSL_X509_get_der
• wolfSSL_X509_get_serial_number
• wolfSSL_X509_notAfter
• wolfSSL_X509_free

Return:

• NULL returned if the WOLFSSL_X509 structure is NULL.
• byte is returned that contains the notBeforeData.

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                        DYNAMIC_TYPE_X509);
...
byte* notBeforeData = wolfSSL_X509_notBefore(x509);

function wolfSSL_X509_notAfter

const byte * wolfSSL_X509_notAfter(
    WOLFSSL_X509 * x509
)

This function the certificate "not after" validity encoded as a byte array.

Parameters:

• x509 pointer to a WOLFSSL_X509 structure.

See:

• wolfSSL_X509_get_signature
• wolfSSL_X509_version
• wolfSSL_X509_get_der
• wolfSSL_X509_get_serial_number
• wolfSSL_X509_notBefore
• wolfSSL_X509_free

Return:

• NULL returned if the WOLFSSL_X509 structure is NULL.
• byte is returned that contains the notAfterData.

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                        DYNAMIC_TYPE_X509);
...
byte* notAfterData = wolfSSL_X509_notAfter(x509);

function wolfSSL_ASN1_INTEGER_to_BN

WOLFSSL_BIGNUM * wolfSSL_ASN1_INTEGER_to_BN(
    const WOLFSSL_ASN1_INTEGER * ai,
    WOLFSSL_BIGNUM * bn
)

This function is used to copy a WOLFSSL_ASN1_INTEGER value to a WOLFSSL_BIGNUM structure.

Parameters:

• ai WOLFSSL_ASN1_INTEGER structure to copy from.
• bn if wanting to copy into an already existing WOLFSSL_BIGNUM struct then pass in a pointer to it. Optionally this can be NULL and a new WOLFSSL_BIGNUM structure will be created.

See: none

Return:

• pointer On successfully copying the WOLFSSL_ASN1_INTEGER value a WOLFSSL_BIGNUM pointer is returned.
• Null upon failure.

Example

WOLFSSL_ASN1_INTEGER* ai;
WOLFSSL_BIGNUM* bn;
// create ai
bn = wolfSSL_ASN1_INTEGER_to_BN(ai, NULL);

// or if having already created bn and wanting to reuse structure
// wolfSSL_ASN1_INTEGER_to_BN(ai, bn);
// check bn is or return value is not NULL

function wolfSSL_CTX_add_extra_chain_cert

long wolfSSL_CTX_add_extra_chain_cert(
    WOLFSSL_CTX * ctx,
    WOLFSSL_X509 * x509
)

This function adds the certificate to the internal chain being built in the WOLFSSL_CTX structure.

Parameters:

• ctx WOLFSSL_CTX structure to add certificate to.
• x509 certificate to add to the chain.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return:

• SSL_SUCCESS after successfully adding the certificate.
• SSL_FAILURE if failing to add the certificate to the chain.

Example

WOLFSSL_CTX* ctx;
WOLFSSL_X509* x509;
int ret;
// create ctx
ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509);
// check ret value

function wolfSSL_CTX_get_read_ahead

int wolfSSL_CTX_get_read_ahead(
    WOLFSSL_CTX * ctx
)

This function returns the get read ahead flag from a WOLFSSL_CTX structure.

Parameters:

• ctx WOLFSSL_CTX structure to get read ahead flag from.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free
• wolfSSL_CTX_set_read_ahead

Return:

• flag On success returns the read ahead flag.
• SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.

Example

WOLFSSL_CTX* ctx;
int flag;
// setup ctx
flag = wolfSSL_CTX_get_read_ahead(ctx);
//check flag

function wolfSSL_CTX_set_read_ahead

int wolfSSL_CTX_set_read_ahead(
    WOLFSSL_CTX * ctx,
    int v
)

This function sets the read ahead flag in the WOLFSSL_CTX structure.

Parameters:

• ctx WOLFSSL_CTX structure to set read ahead flag.
• v read ahead flag

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free
• wolfSSL_CTX_get_read_ahead

Return:

• SSL_SUCCESS If ctx read ahead flag set.
• SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.

Example

WOLFSSL_CTX* ctx;
int flag;
int ret;
// setup ctx
ret = wolfSSL_CTX_set_read_ahead(ctx, flag);
// check return value

function wolfSSL_CTX_set_tlsext_status_arg

long wolfSSL_CTX_set_tlsext_status_arg(
    WOLFSSL_CTX * ctx,
    void * arg
)

This function sets the options argument to use with OCSP.

Parameters:

• ctx WOLFSSL_CTX structure to set user argument.
• arg user argument.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return:

• SSL_FAILURE If ctx or it’s cert manager is NULL.
• SSL_SUCCESS If successfully set.

Example

WOLFSSL_CTX* ctx;
void* data;
int ret;
// setup ctx
ret = wolfSSL_CTX_set_tlsext_status_arg(ctx, data);

//check ret value

function wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg

long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(
    WOLFSSL_CTX * ctx,
    void * arg
)

This function sets the optional argument to be passed to the PRF callback.

Parameters:

• ctx WOLFSSL_CTX structure to set user argument.
• arg user argument.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return:

• SSL_FAILURE If ctx is NULL.
• SSL_SUCCESS If successfully set.

Example

WOLFSSL_CTX* ctx;
void* data;
int ret;
// setup ctx
ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data);
//check ret value

function wolfSSL_set_options

long wolfSSL_set_options(
    WOLFSSL * s,
    long op
)

This function sets the options mask in the ssl. Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE, SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_COMPRESSION.

Parameters:

• s WOLFSSL structure to set options mask.
• op This function sets the options mask in the ssl. Some valid options are: SSL_OP_ALL SSL_OP_COOKIE_EXCHANGE SSL_OP_NO_SSLv2 SSL_OP_NO_SSLv3 SSL_OP_NO_TLSv1 SSL_OP_NO_TLSv1_1 SSL_OP_NO_TLSv1_2 SSL_OP_NO_COMPRESSION

See:

• wolfSSL_new
• wolfSSL_free
• wolfSSL_get_options

Return: val Returns the updated options mask value stored in ssl.

Example

WOLFSSL* ssl;
unsigned long mask;
mask = SSL_OP_NO_TLSv1
mask  = wolfSSL_set_options(ssl, mask);
// check mask

function wolfSSL_get_options

long wolfSSL_get_options(
    const WOLFSSL * ssl
)

This function returns the current options mask.

Parameters:

• ssl WOLFSSL structure to get options mask from.

See:

• wolfSSL_new
• wolfSSL_free
• wolfSSL_set_options

Return: val Returns the mask value stored in ssl.

Example

WOLFSSL* ssl;
unsigned long mask;
mask  = wolfSSL_get_options(ssl);
// check mask

function wolfSSL_set_tlsext_debug_arg

long wolfSSL_set_tlsext_debug_arg(
    WOLFSSL * ssl,
    void * arg
)

This is used to set the debug argument passed around.

Parameters:

• ssl WOLFSSL structure to set argument in.
• arg argument to use.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• SSL_SUCCESS On successful setting argument.
• SSL_FAILURE If an NULL ssl passed in.

Example

WOLFSSL* ssl;
void* args;
int ret;
// create ssl object
ret  = wolfSSL_set_tlsext_debug_arg(ssl, args);
// check ret value

function wolfSSL_set_tlsext_status_type

long wolfSSL_set_tlsext_status_type(
    WOLFSSL * s,
    int type
)

This function is called when the client application request that a server send back an OCSP status response (also known as OCSP stapling).Currently, the only supported type is TLSEXT_STATUSTYPE_ocsp.

Parameters:

• s pointer to WOLFSSL struct which is created by SSL_new() function
• type ssl extension type which TLSEXT_STATUSTYPE_ocsp is only supported.

See:

• wolfSSL_new
• wolfSSL_CTX_new
• wolfSSL_free
• wolfSSL_CTX_free

Return:

• 1 upon success.
• 0 upon error.

Example

WOLFSSL *ssl;
WOLFSSL_CTX *ctx;
int ret;
ctx = wolfSSL_CTX_new(wolfSSLv23_server_method());
ssl = wolfSSL_new(ctx);
ret = WolfSSL_set_tlsext_status_type(ssl,TLSEXT_STATUSTYPE_ocsp);
wolfSSL_free(ssl);
wolfSSL_CTX_free(ctx);

function wolfSSL_get_verify_result

long wolfSSL_get_verify_result(
    const WOLFSSL * ssl
)

This is used to get the results after trying to verify the peer's certificate.

Parameters:

• ssl WOLFSSL structure to get verification results from.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• X509_V_OK On successful verification.
• SSL_FAILURE If an NULL ssl passed in.

Example

WOLFSSL* ssl;
long ret;
// attempt/complete handshake
ret  = wolfSSL_get_verify_result(ssl);
// check ret value

function wolfSSL_ERR_print_errors_fp

void wolfSSL_ERR_print_errors_fp(
    XFILE fp,
    int err
)

This function converts an error code returned by wolfSSL_get_error() into a more human_readable error string and prints that string to the output file _ fp. err is the error code returned by wolfSSL_get_error() and fp is the file which the error string will be placed in.

Parameters:

• fp output file for human-readable error string to be written to.
• err error code returned by wolfSSL_get_error().

See:

• wolfSSL_get_error
• wolfSSL_ERR_error_string
• wolfSSL_ERR_error_string_n
• wolfSSL_load_error_strings

Return: none No returns.

Example

int err = 0;
WOLFSSL* ssl;
FILE* fp = ...
...
err = wolfSSL_get_error(ssl, 0);
wolfSSL_ERR_print_errors_fp(fp, err);

function wolfSSL_ERR_print_errors_cb

void wolfSSL_ERR_print_errors_cb(
    int(*)(const char *str, size_t len, void *u) cb,
    void * u
)

This function uses the provided callback to handle error reporting. The callback function is executed for each error line. The string, length, and userdata are passed into the callback parameters.

Parameters:

• cb the callback function.
• u userdata to pass into the callback function.

See:

• wolfSSL_get_error
• wolfSSL_ERR_error_string
• wolfSSL_ERR_error_string_n
• wolfSSL_load_error_strings

Return: none No returns.

Example

int error_cb(const char *str, size_t len, void *u)
{ fprintf((FILE*)u, "%-*.*s\n", (int)len, (int)len, str); return 0; }
...
FILE* fp = ...
wolfSSL_ERR_print_errors_cb(error_cb, fp);

function wolfSSL_CTX_set_psk_client_callback

void wolfSSL_CTX_set_psk_client_callback(
    WOLFSSL_CTX * ctx,
    wc_psk_client_callback cb
)

The function sets the client_psk_cb member of the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• cb wc_psk_client_callback is a function pointer that will be stored in the WOLFSSL_CTX structure. Return value is the key length on success or zero on error. unsigned int (wc_psk_client_callback) PSK client callback parameters: WOLFSSL ssl - Pointer to the wolfSSL structure const char hint - A stored string that could be displayed to provide a hint to the user. char identity - The ID will be stored here. unsigned int id_max_len - Size of the ID buffer. unsigned char* key - The key will be stored here. unsigned int key_max_len - The max size of the key.

See:

• wolfSSL_set_psk_client_callback
• wolfSSL_set_psk_server_callback
• wolfSSL_CTX_set_psk_server_callback
• wolfSSL_CTX_set_psk_client_callback

Return: none No returns.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
…
static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
char* identity, unsigned int id_max_len, unsigned char* key,
Unsigned int key_max_len){
…
wolfSSL_CTX_set_psk_client_callback(ctx, my_psk_client_cb);

function wolfSSL_set_psk_client_callback

void wolfSSL_set_psk_client_callback(
    WOLFSSL * ssl,
    wc_psk_client_callback 
)

Sets the PSK client side callback.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer to type wc_psk_client_callback. Return value is the key length on success or zero on error. unsigned int (wc_psk_client_callback) PSK client callback parameters: WOLFSSL ssl - Pointer to the wolfSSL structure const char hint - A stored string that could be displayed to provide a hint to the user. char identity - The ID will be stored here. unsigned int id_max_len - Size of the ID buffer. unsigned char* key - The key will be stored here. unsigned int key_max_len - The max size of the key.

See:

• wolfSSL_CTX_set_psk_client_callback
• wolfSSL_CTX_set_psk_server_callback
• wolfSSL_set_psk_server_callback

Return: none No returns.

Example

WOLFSSL* ssl;
static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
char* identity, unsigned int id_max_len, unsigned char* key,
Unsigned int key_max_len){
…
if(ssl){
wolfSSL_set_psk_client_callback(ssl, my_psk_client_cb);
} else {
    // could not set callback
}

function wolfSSL_get_psk_identity_hint

const char * wolfSSL_get_psk_identity_hint(
    const WOLFSSL * 
)

This function returns the psk identity hint.

Parameters:

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

See: wolfSSL_get_psk_identity

Return:

• pointer a const char pointer to the value that was stored in the arrays member of the WOLFSSL structure is returned.
• NULL returned if the WOLFSSL or Arrays structures are NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
char* idHint;
...
idHint = wolfSSL_get_psk_identity_hint(ssl);
if(idHint){
    // The hint was retrieved
    return idHint;
} else {
    // Hint wasn’t successfully retrieved
}

function wolfSSL_get_psk_identity

const char * wolfSSL_get_psk_identity(
    const WOLFSSL * 
)

The function returns a constant pointer to the client_identity member of the Arrays structure.

Parameters:

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

See:

• wolfSSL_get_psk_identity_hint
• wolfSSL_use_psk_identity_hint

Return:

• string the string value of the client_identity member of the Arrays structure.
• NULL if the WOLFSSL structure is NULL or if the Arrays member of the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
const char* pskID;
...
pskID = wolfSSL_get_psk_identity(ssl);

if(pskID == NULL){
    // There is not a value in pskID
}

function wolfSSL_CTX_use_psk_identity_hint

int wolfSSL_CTX_use_psk_identity_hint(
    WOLFSSL_CTX * ctx,
    const char * hint
)

This function stores the hint argument in the server_hint member of the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• hint a constant char pointer that will be copied to the WOLFSSL_CTX structure.

See: wolfSSL_use_psk_identity_hint

Return: SSL_SUCCESS returned for successful execution of the function.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
const char* hint;
int ret;
…
ret = wolfSSL_CTX_use_psk_identity_hint(ctx, hint);
if(ret == SSL_SUCCESS){
    // Function was successful.
return ret;
} else {
    // Failure case.
}

function wolfSSL_use_psk_identity_hint

int wolfSSL_use_psk_identity_hint(
    WOLFSSL * ssl,
    const char * hint
)

This function stores the hint argument in the server_hint member of the Arrays structure within the WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• hint a constant character pointer that holds the hint to be saved in memory.

See: wolfSSL_CTX_use_psk_identity_hint

Return:

• SSL_SUCCESS returned if the hint was successfully stored in the WOLFSSL structure.
• SSL_FAILURE returned if the WOLFSSL or Arrays structures are NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
const char* hint;
...
if(wolfSSL_use_psk_identity_hint(ssl, hint) != SSL_SUCCESS){
    // Handle failure case.
}

function wolfSSL_CTX_set_psk_server_callback

void wolfSSL_CTX_set_psk_server_callback(
    WOLFSSL_CTX * ctx,
    wc_psk_server_callback cb
)

This function sets the psk callback for the server side in the WOLFSSL_CTX structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer for the callback and will be stored in the WOLFSSL_CTX structure. Return value is the key length on success or zero on error. unsigned int (wc_psk_server_callback) PSK server callback parameters WOLFSSL ssl - Pointer to the wolfSSL structure char identity - The ID will be stored here. unsigned char key - The key will be stored here. unsigned int key_max_len - The max size of the key.

See:

• wc_psk_server_callback
• wolfSSL_set_psk_client_callback
• wolfSSL_set_psk_server_callback
• wolfSSL_CTX_set_psk_client_callback

Return: none No returns.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
                       unsigned char* key, unsigned int key_max_len)
{
    // Function body.
}
…
if(ctx != NULL){
    wolfSSL_CTX_set_psk_server_callback(ctx, my_psk_server_cb);
} else {
    // The CTX object was not properly initialized.
}

function wolfSSL_set_psk_server_callback

void wolfSSL_set_psk_server_callback(
    WOLFSSL * ssl,
    wc_psk_server_callback cb
)

Sets the psk callback for the server side by setting the WOLFSSL structure options members.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer for the callback and will be stored in the WOLFSSL structure. Return value is the key length on success or zero on error. unsigned int (wc_psk_server_callback) PSK server callback parameters WOLFSSL ssl - Pointer to the wolfSSL structure char identity - The ID will be stored here. unsigned char key - The key will be stored here. unsigned int key_max_len - The max size of the key.

See:

• wolfSSL_set_psk_client_callback
• wolfSSL_CTX_set_psk_server_callback
• wolfSSL_CTX_set_psk_client_callback
• wolfSSL_get_psk_identity_hint
• wc_psk_server_callback
• InitSuites

Return: none No returns.

Example

WOLFSSL_CTX* ctx;
WOLFSSL* ssl;
…
static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
                       unsigned char* key, unsigned int key_max_len)
{
    // Function body.
}
…
if(ssl != NULL && cb != NULL){
    wolfSSL_set_psk_server_callback(ssl, my_psk_server_cb);
}

function wolfSSL_set_psk_callback_ctx

int wolfSSL_set_psk_callback_ctx(
    WOLFSSL * ssl,
    void * psk_ctx
)

Sets a PSK user context in the WOLFSSL structure options member.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• psk_ctx void pointer to user PSK context

See:

• wolfSSL_get_psk_callback_ctx
• wolfSSL_CTX_set_psk_callback_ctx
• wolfSSL_CTX_get_psk_callback_ctx

Return: WOLFSSL_SUCCESS or WOLFSSL_FAILURE

function wolfSSL_CTX_set_psk_callback_ctx

int wolfSSL_CTX_set_psk_callback_ctx(
    WOLFSSL_CTX * ctx,
    void * psk_ctx
)

Sets a PSK user context in the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• psk_ctx void pointer to user PSK context

See:

• wolfSSL_set_psk_callback_ctx
• wolfSSL_get_psk_callback_ctx
• wolfSSL_CTX_get_psk_callback_ctx

Return: WOLFSSL_SUCCESS or WOLFSSL_FAILURE

function wolfSSL_get_psk_callback_ctx

void * wolfSSL_get_psk_callback_ctx(
    WOLFSSL * ssl
)

Get a PSK user context in the WOLFSSL structure options member.

Parameters:

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

See:

• wolfSSL_set_psk_callback_ctx
• wolfSSL_CTX_set_psk_callback_ctx
• wolfSSL_CTX_get_psk_callback_ctx

Return: void pointer to user PSK context

function wolfSSL_CTX_get_psk_callback_ctx

void * wolfSSL_CTX_get_psk_callback_ctx(
    WOLFSSL_CTX * ctx
)

Get a PSK user context in the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_CTX_set_psk_callback_ctx
• wolfSSL_set_psk_callback_ctx
• wolfSSL_get_psk_callback_ctx

Return: void pointer to user PSK context

function wolfSSL_CTX_allow_anon_cipher

int wolfSSL_CTX_allow_anon_cipher(
    WOLFSSL_CTX * 
)

This function enables the havAnon member of the CTX structure if HAVE_ANON is defined during compilation.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See: none

Return:

• SSL_SUCCESS returned if the function executed successfully and the haveAnnon member of the CTX is set to 1.
• SSL_FAILURE returned if the CTX structure was NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
#ifdef HAVE_ANON
if(cipherList == NULL){
    wolfSSL_CTX_allow_anon_cipher(ctx);
    if(wolfSSL_CTX_set_cipher_list(ctx, “ADH_AES128_SHA”) != SSL_SUCCESS){
        // failure case
    }
}
#endif

function wolfSSLv23_server_method

WOLFSSL_METHOD * wolfSSLv23_server_method(
    void 
)

The wolfSSLv23_server_method() function is used to indicate that the application is a server and will support clients connecting with protocol version from SSL 3.0 _ TLS 1.3. This function allocates memory for and initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• none No parameters

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSL_CTX_new

Return:

• pointer If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• Failure If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfSSLv23_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfSSL_state

int wolfSSL_state(
    WOLFSSL * ssl
)

This is used to get the internal error state of the WOLFSSL structure.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• wolfssl_error returns ssl error state, usually a negative
• BAD_FUNC_ARG if ssl is NULL.
• ssl WOLFSSL structure to get state from.

Example

WOLFSSL* ssl;
int ret;
// create ssl object
ret  = wolfSSL_state(ssl);
// check ret value

function wolfSSL_get_peer_certificate

WOLFSSL_X509 * wolfSSL_get_peer_certificate(
    WOLFSSL * ssl
)

This function gets the peer’s certificate.

Parameters:

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

See:

• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_isCA

Return:

• pointer a pointer to the peerCert member of the WOLFSSL_X509 structure if it exists.
• 0 returned if the peer certificate issuer size is not defined.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
WOLFSSL_X509* peerCert = wolfSSL_get_peer_certificate(ssl);

if(peerCert){
    // You have a pointer peerCert to the peer certification
}

function wolfSSL_want_read

int wolfSSL_want_read(
    WOLFSSL * 
)

This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_READ in return. If the underlying error state is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.

Parameters:

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

See:

• wolfSSL_want_write
• wolfSSL_get_error

Return:

• 1 wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the underlying I/O has data available for reading.
• 0 There is no SSL_ERROR_WANT_READ error state.

Example

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

ret = wolfSSL_want_read(ssl);
if (ret == 1) {
    // underlying I/O has data available for reading (SSL_ERROR_WANT_READ)
}

function wolfSSL_want_write

int wolfSSL_want_write(
    WOLFSSL * 
)

This function is similar to calling wolfSSL_get_error() and getting SSL_ERROR_WANT_WRITE in return. If the underlying error state is SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.

Parameters:

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

See:

• wolfSSL_want_read
• wolfSSL_get_error

Return:

• 1 wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the underlying I/O needs data to be written in order for progress to be made in the underlying SSL connection.
• 0 There is no SSL_ERROR_WANT_WRITE error state.

Example

int ret;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_want_write(ssl);
if (ret == 1) {
    // underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)
}

function wolfSSL_check_domain_name

int wolfSSL_check_domain_name(
    WOLFSSL * ssl,
    const char * dn
)

wolfSSL by default checks the peer certificate for a valid date range and a verified signature. Calling this function before wolfSSL_connect() or wolfSSL_accept() will add a domain name check to the list of checks to perform. dn holds the domain name to check against the peer certificate when it’s received.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• dn domain name to check against the peer certificate when received.

See: none

Return:

• SSL_SUCCESS upon success.
• SSL_FAILURE will be returned if a memory error was encountered.

Example

int ret = 0;
WOLFSSL* ssl;
char* domain = (char*) “www.yassl.com”;
...

ret = wolfSSL_check_domain_name(ssl, domain);
if (ret != SSL_SUCCESS) {
   // failed to enable domain name check
}

function wolfSSL_Init

int wolfSSL_Init(
    void 
)

Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library.

See: wolfSSL_Cleanup

Return:

• SSL_SUCCESS If successful the call will return.
• BAD_MUTEX_E is an error that may be returned.
• WC_INIT_E wolfCrypt initialization error returned.

Example

int ret = 0;
ret = wolfSSL_Init();
if (ret != SSL_SUCCESS) {
    failed to initialize wolfSSL library
}

function wolfSSL_Cleanup

int wolfSSL_Cleanup(
    void 
)

Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it will free any resources used by the library.

See: wolfSSL_Init

Return:

• SSL_SUCCESS return no errors.
• BAD_MUTEX_E a mutex error return.]

Example

wolfSSL_Cleanup();

function wolfSSL_lib_version

const char * wolfSSL_lib_version(
    void 
)

This function returns the current library version.

Parameters:

• none No parameters.

See: word32_wolfSSL_lib_version_hex

Return: LIBWOLFSSL_VERSION_STRING a const char pointer defining the version.

Example

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

function wolfSSL_lib_version_hex

word32 wolfSSL_lib_version_hex(
    void 
)

This function returns the current library version in hexadecimal notation.

Parameters:

• none No parameters.

See: wolfSSL_lib_version

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

Example

word32 libV;
libV = wolfSSL_lib_version_hex();

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

function wolfSSL_negotiate

int wolfSSL_negotiate(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• SSL_connect
• SSL_accept

Return:

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

Example

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

function wolfSSL_set_compression

int wolfSSL_set_compression(
    WOLFSSL * ssl
)

Turns on the ability to use compression for the SSL connection. Both sides must have compression turned on otherwise compression will not be used. The zlib library performs the actual data compression. To compile into the library use –with-libz for the configure system and define HAVE_LIBZ otherwise. Keep in mind that while compressing data before sending decreases the actual size of the messages being sent and received, the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks.

Parameters:

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

See: none

Return:

• SSL_SUCCESS upon success.
• NOT_COMPILED_IN will be returned if compression support wasn’t built into the library.

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_compression(ssl);
if (ret == SSL_SUCCESS) {
    // successfully enabled compression for SSL session
}

function wolfSSL_set_timeout

int wolfSSL_set_timeout(
    WOLFSSL * ssl,
    unsigned int to
)

This function sets the SSL session timeout value in seconds.

Parameters:

• ssl pointer to the SSL object, created with wolfSSL_new().
• to value, in seconds, used to set the SSL session timeout.

See:

• wolfSSL_get1_session
• wolfSSL_set_session

Return:

• SSL_SUCCESS will be returned upon successfully setting the session.
• BAD_FUNC_ARG will be returned if ssl is NULL.

Example

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

ret = wolfSSL_set_timeout(ssl, 500);
if (ret != SSL_SUCCESS) {
    // failed to set session timeout value
}
...

function wolfSSL_CTX_set_timeout

int wolfSSL_CTX_set_timeout(
    WOLFSSL_CTX * ctx,
    unsigned int to
)

This function sets the timeout value for SSL sessions, in seconds, for the specified SSL context.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• to session timeout value in seconds.

See:

• wolfSSL_flush_sessions
• wolfSSL_get1_session
• wolfSSL_set_session
• wolfSSL_get_sessionID
• wolfSSL_CTX_set_session_cache_mode

Return:

• the previous timeout value, if WOLFSSL_ERROR_CODE_OPENSSL is
• defined on success. If not defined, SSL_SUCCESS will be returned.
• BAD_FUNC_ARG will be returned when the input context (ctx) is null.

Example

WOLFSSL_CTX*    ctx    = 0;
...
ret = wolfSSL_CTX_set_timeout(ctx, 500);
if (ret != SSL_SUCCESS) {
    // failed to set session timeout value
}

function wolfSSL_get_peer_chain

WOLFSSL_X509_CHAIN * wolfSSL_get_peer_chain(
    WOLFSSL * ssl
)

Retrieves the peer’s certificate chain.

Parameters:

• ssl pointer to a valid WOLFSSL structure.

See:

• wolfSSL_get_chain_count
• wolfSSL_get_chain_length
• wolfSSL_get_chain_cert
• wolfSSL_get_chain_cert_pem

Return:

• chain If successful the call will return the peer’s certificate chain.
• 0 will be returned if an invalid WOLFSSL pointer is passed to the function.

Example

none

function wolfSSL_get_chain_count

int wolfSSL_get_chain_count(
    WOLFSSL_X509_CHAIN * chain
)

Retrieve's the peers certificate chain count.

Parameters:

• chain pointer to a valid WOLFSSL_X509_CHAIN structure.

See:

• wolfSSL_get_peer_chain
• wolfSSL_get_chain_length
• wolfSSL_get_chain_cert
• wolfSSL_get_chain_cert_pem

Return:

• Success If successful the call will return the peer’s certificate chain count.
• 0 will be returned if an invalid chain pointer is passed to the function.

Example

none

function wolfSSL_get_chain_length

int wolfSSL_get_chain_length(
    WOLFSSL_X509_CHAIN * chain,
    int idx
)

Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx).

Parameters:

• chain pointer to a valid WOLFSSL_X509_CHAIN structure.
• idx index to start of chain.

See:

• wolfSSL_get_peer_chain
• wolfSSL_get_chain_count
• wolfSSL_get_chain_cert
• wolfSSL_get_chain_cert_pem

Return:

• Success If successful the call will return the peer’s certificate length in bytes by index.
• 0 will be returned if an invalid chain pointer is passed to the function.

Example

none

function wolfSSL_get_chain_cert

unsigned char * wolfSSL_get_chain_cert(
    WOLFSSL_X509_CHAIN * chain,
    int idx
)

Retrieves the peer’s ASN1.DER certificate at index (idx).

Parameters:

• chain pointer to a valid WOLFSSL_X509_CHAIN structure.
• idx index to start of chain.

See:

• wolfSSL_get_peer_chain
• wolfSSL_get_chain_count
• wolfSSL_get_chain_length
• wolfSSL_get_chain_cert_pem

Return:

• Success If successful the call will return the peer’s certificate by index.
• 0 will be returned if an invalid chain pointer is passed to the function.

Example

none

function wolfSSL_get_chain_X509

WOLFSSL_X509 * wolfSSL_get_chain_X509(
    WOLFSSL_X509_CHAIN * chain,
    int idx
)

This function gets the peer’s wolfSSL_X509_certificate at index (idx) from the chain of certificates.

Parameters:

• chain a pointer to the WOLFSSL_X509_CHAIN used for no dynamic memory SESSION_CACHE.
• idx the index of the WOLFSSL_X509 certificate.

See:

• InitDecodedCert
• ParseCertRelative
• CopyDecodedToX509

Return: pointer returns a pointer to a WOLFSSL_X509 structure.

Note that it is the user's responsibility to free the returned memory by calling wolfSSL_FreeX509().

Example

WOLFSSL_X509_CHAIN* chain = &session->chain;
int idx = 999; // set idx
...
WOLFSSL_X509_CHAIN ptr;
prt = wolfSSL_get_chain_X509(chain, idx);

if(ptr != NULL){
    // ptr contains the cert at the index specified
    wolfSSL_FreeX509(ptr);
} else {
    // ptr is NULL
}

function wolfSSL_get_chain_cert_pem

int wolfSSL_get_chain_cert_pem(
    WOLFSSL_X509_CHAIN * chain,
    int idx,
    unsigned char * buf,
    int inLen,
    int * outLen
)

Retrieves the peer’s PEM certificate at index (idx).

Parameters:

• chain pointer to a valid WOLFSSL_X509_CHAIN structure.
• idx indexto start of chain.

See:

• wolfSSL_get_peer_chain
• wolfSSL_get_chain_count
• wolfSSL_get_chain_length
• wolfSSL_get_chain_cert

Return:

• Success If successful the call will return the peer’s certificate by index.
• 0 will be returned if an invalid chain pointer is passed to the function.

Example

none

function wolfSSL_get_sessionID

const unsigned char * wolfSSL_get_sessionID(
    const WOLFSSL_SESSION * s
)

Retrieves the session’s ID. The session ID is always 32 bytes long.

Parameters:

• session pointer to a valid wolfssl session.

See: SSL_get_session

Return: id The session ID.

Example

none

function wolfSSL_X509_get_serial_number

int wolfSSL_X509_get_serial_number(
    WOLFSSL_X509 * x509,
    unsigned char * in,
    int * inOutSz
)

Retrieves the peer’s certificate serial number. The serial number buffer (in) should be at least 32 bytes long and be provided as the inOutSz argument as input. After calling the function inOutSz will hold the actual length in bytes written to the in buffer.

Parameters:

• in The serial number buffer and should be at least 32 bytes long
• inOutSz will hold the actual length in bytes written to the in buffer.

See: SSL_get_peer_certificate

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG will be returned if a bad function argument was encountered.

Example

none

function wolfSSL_X509_get_subjectCN

char * wolfSSL_X509_get_subjectCN(
    WOLFSSL_X509 * 
)

Returns the common name of the subject from the certificate.

Parameters:

• x509 a pointer to a WOLFSSL_X509 structure containing certificate information.

See:

• wolfSSL_X509_Name_get_entry
• wolfSSL_X509_get_next_altname
• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_subject_name

Return:

• NULL returned if the x509 structure is null
• string a string representation of the subject's common name is returned upon success

Example

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                        DYNAMIC_TYPE_X509);
...
int x509Cn = wolfSSL_X509_get_subjectCN(x509);
if(x509Cn == NULL){
    // Deal with NULL case
} else {
    // x509Cn contains the common name
}

function wolfSSL_X509_get_der

const unsigned char * wolfSSL_X509_get_der(
    WOLFSSL_X509 * x509,
    int * outSz
)

This function gets the DER encoded certificate in the WOLFSSL_X509 struct.

Parameters:

• x509 a pointer to a WOLFSSL_X509 structure containing certificate information.
• outSz length of the derBuffer member of the WOLFSSL_X509 struct.

See:

• wolfSSL_X509_version
• wolfSSL_X509_Name_get_entry
• wolfSSL_X509_get_next_altname
• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_subject_name

Return:

• buffer This function returns the DerBuffer structure’s buffer member, which is of type byte.
• NULL returned if the x509 or outSz parameter is NULL.

Example

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                        DYNAMIC_TYPE_X509);
int* outSz; // initialize
...
byte* x509Der = wolfSSL_X509_get_der(x509, outSz);
if(x509Der == NULL){
    // Failure case one of the parameters was NULL
}

function wolfSSL_X509_get_notAfter

WOLFSSL_ASN1_TIME * wolfSSL_X509_get_notAfter(
    WOLFSSL_X509 * 
)

This function checks to see if x509 is NULL and if it’s not, it returns the notAfter member of the x509 struct.

Parameters:

• x509 a pointer to the WOLFSSL_X509 struct.

See: wolfSSL_X509_get_notBefore

Return:

• pointer to struct with ASN1_TIME to the notAfter member of the x509 struct.
• NULL returned if the x509 object is NULL.

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509) ;
...
const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notAfter(x509);
if(notAfter == NULL){
    // Failure case, the x509 object is null.
}

function wolfSSL_X509_version

int wolfSSL_X509_version(
    WOLFSSL_X509 * 
)

This function retrieves the version of the X509 certificate.

Parameters:

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

See:

• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_isCA
• wolfSSL_get_peer_certificate

Return:

• 0 returned if the x509 structure is NULL.
• version the version stored in the x509 structure will be returned.

Example

WOLFSSL_X509* x509;
int version;
...
version = wolfSSL_X509_version(x509);
if(!version){
    // The function returned 0, failure case.
}

function wolfSSL_X509_d2i_fp

WOLFSSL_X509 * wolfSSL_X509_d2i_fp(
    WOLFSSL_X509 ** x509,
    FILE * file
)

If NO_STDIO_FILESYSTEM is defined this function will allocate heap memory, initialize a WOLFSSL_X509 structure and return a pointer to it.

Parameters:

• x509 a pointer to a WOLFSSL_X509 pointer.
• file a defined type that is a pointer to a FILE.

See:

• wolfSSL_X509_d2i
• XFTELL
• XREWIND
• XFSEEK

Return:

• *WOLFSSL_X509 WOLFSSL_X509 structure pointer is returned if the function executes successfully.
• NULL if the call to XFTELL macro returns a negative value.

Example

WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509);
WOLFSSL_X509** x509 = x509a;
XFILE file;  (mapped to struct fs_file*)
...
WOLFSSL_X509* newX509 = wolfSSL_X509_d2i_fp(x509, file);
if(newX509 == NULL){
    // The function returned NULL
}

function wolfSSL_X509_load_certificate_file

WOLFSSL_X509 * wolfSSL_X509_load_certificate_file(
    const char * fname,
    int format
)

The function loads the x509 certificate into memory.

Parameters:

• fname the certificate file to be loaded.
• format the format of the certificate.

See:

• InitDecodedCert
• PemToDer
• wolfSSL_get_certificate
• AssertNotNull

Return:

• pointer a successful execution returns pointer to a WOLFSSL_X509 structure.
• NULL returned if the certificate was not able to be written.

Example

#define cliCert    “certs/client-cert.pem”
…
X509* x509;
…
x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM);
AssertNotNull(x509);

function wolfSSL_X509_get_device_type

unsigned char * wolfSSL_X509_get_device_type(
    WOLFSSL_X509 * x509,
    unsigned char * in,
    int * inOutSz
)

This function copies the device type from the x509 structure to the buffer.

Parameters:

• x509 pointer to a WOLFSSL_X509 structure, created with WOLFSSL_X509_new().
• in a pointer to a byte type that will hold the device type (the buffer).
• inOutSz the minimum of either the parameter inOutSz or the deviceTypeSz member of the x509 structure.

See:

• wolfSSL_X509_get_hw_type
• wolfSSL_X509_get_hw_serial_number
• wolfSSL_X509_d2i

Return:

• pointer returns a byte pointer holding the device type from the x509 structure.
• NULL returned if the buffer size is NULL.

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509);
byte* in;
int* inOutSz;
...
byte* deviceType = wolfSSL_X509_get_device_type(x509, in, inOutSz);

if(!deviceType){
    // Failure case, NULL was returned.
}

function wolfSSL_X509_get_hw_type

unsigned char * wolfSSL_X509_get_hw_type(
    WOLFSSL_X509 * x509,
    unsigned char * in,
    int * inOutSz
)

The function copies the hwType member of the WOLFSSL_X509 structure to the buffer.

Parameters:

• x509 a pointer to a WOLFSSL_X509 structure containing certificate information.
• in pointer to type byte that represents the buffer.
• inOutSz pointer to type int that represents the size of the buffer.

See:

• wolfSSL_X509_get_hw_serial_number
• wolfSSL_X509_get_device_type

Return:

• byte The function returns a byte type of the data previously held in the hwType member of the WOLFSSL_X509 structure.
• NULL returned if inOutSz is NULL.

Example

WOLFSSL_X509* x509;  // X509 certificate
byte* in;  // initialize the buffer
int* inOutSz;  // holds the size of the buffer
...
byte* hwType = wolfSSL_X509_get_hw_type(x509, in, inOutSz);

if(hwType == NULL){
    // Failure case function returned NULL.
}

function wolfSSL_X509_get_hw_serial_number

unsigned char * wolfSSL_X509_get_hw_serial_number(
    WOLFSSL_X509 * x509,
    unsigned char * in,
    int * inOutSz
)

This function returns the hwSerialNum member of the x509 object.

Parameters:

• x509 pointer to a WOLFSSL_X509 structure containing certificate information.
• in a pointer to the buffer that will be copied to.
• inOutSz a pointer to the size of the buffer.

See:

• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_isCA
• wolfSSL_get_peer_certificate
• wolfSSL_X509_version

Return: pointer the function returns a byte pointer to the in buffer that will contain the serial number loaded from the x509 object.

Example

char* serial;
byte* in;
int* inOutSz;
WOLFSSL_X509 x509;
...
serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz);

if(serial == NULL || serial <= 0){
    // Failure case
}

function wolfSSL_connect_cert

int wolfSSL_connect_cert(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_get_error
• wolfSSL_connect
• wolfSSL_accept

Return:

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

Example

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

function wolfSSL_d2i_PKCS12_bio

WC_PKCS12 * wolfSSL_d2i_PKCS12_bio(
    WOLFSSL_BIO * bio,
    WC_PKCS12 ** pkcs12
)

wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 information from WOLFSSL_BIO to the structure WC_PKCS12. The information is divided up in the structure as a list of Content Infos along with a structure to hold optional MAC information. After the information has been divided into chunks (but not decrypted) in the structure WC_PKCS12, it can then be parsed and decrypted by calling.

Parameters:

• bio WOLFSSL_BIO structure to read PKCS12 buffer from.
• pkcs12 WC_PKCS12 structure pointer for new PKCS12 structure created. Can be NULL

See:

• wolfSSL_PKCS12_parse
• wc_PKCS12_free

Return:

• WC_PKCS12 pointer to a WC_PKCS12 structure.
• Failure If function failed it will return NULL.

Example

WC_PKCS12* pkcs;
WOLFSSL_BIO* bio;
WOLFSSL_X509* cert;
WOLFSSL_EVP_PKEY* pkey;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
wc_PKCS12_free(pkcs)
//use cert, pkey, and optionally certs stack

function wolfSSL_i2d_PKCS12_bio

WC_PKCS12 * wolfSSL_i2d_PKCS12_bio(
    WOLFSSL_BIO * bio,
    WC_PKCS12 * pkcs12
)

wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert information from the structure WC_PKCS12 to WOLFSSL_BIO.

Parameters:

• bio WOLFSSL_BIO structure to write PKCS12 buffer to.
• pkcs12 WC_PKCS12 structure for PKCS12 structure as input.

See:

• wolfSSL_PKCS12_parse
• wc_PKCS12_free

Return:

• 1 for success.
• Failure 0.

Example

WC_PKCS12 pkcs12;
FILE *f;
byte buffer[5300];
char file[] = "./test.p12";
int bytes;
WOLFSSL_BIO* bio;
pkcs12 = wc_PKCS12_new();
f = fopen(file, "rb");
bytes = (int)fread(buffer, 1, sizeof(buffer), f);
fclose(f);
//convert the DER file into an internal structure
wc_d2i_PKCS12(buffer, bytes, pkcs12);
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
//convert PKCS12 structure into bio
wolfSSL_i2d_PKCS12_bio(bio, pkcs12);
wc_PKCS12_free(pkcs)
//use bio

function wolfSSL_PKCS12_parse

int wolfSSL_PKCS12_parse(
    WC_PKCS12 * pkcs12,
    const char * psw,
    WOLFSSL_EVP_PKEY ** pkey,
    WOLFSSL_X509 ** cert,
    WOLF_STACK_OF(WOLFSSL_X509) ** ca
)

PKCS12 can be enabled with adding –enable-opensslextra to the configure command. It can use triple DES and RC4 for decryption so would recommend also enabling these features when enabling opensslextra (–enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so decryption with RC2 is currently not available. This may be noticeable with default encryption schemes used by OpenSSL command line to create .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this function does is check the MAC is correct if present. If the MAC fails then the function returns and does not try to decrypt any of the stored Content Infos. This function then parses through each Content Info looking for a bag type, if the bag type is known it is decrypted as needed and either stored in the list of certificates being built or as a key found. After parsing through all bags the key found is then compared with the certificate list until a matching pair is found. This matching pair is then returned as the key and certificate, optionally the certificate list found is returned as a STACK_OF certificates. At the moment a CRL, Secret or SafeContents bag will be skipped over and not parsed. It can be seen if these or other “Unknown” bags are skipped over by viewing the debug print out. Additional attributes such as friendly name are skipped over when parsing a PKCS12 file.

Parameters:

• pkcs12 WC_PKCS12 structure to parse.
• paswd password for decrypting PKCS12.
• pkey structure to hold private key decoded from PKCS12.
• cert structure to hold certificate decoded from PKCS12.
• stack optional stack of extra certificates.

See:

• wolfSSL_d2i_PKCS12_bio
• wc_PKCS12_free

Return:

• SSL_SUCCESS On successfully parsing PKCS12.
• SSL_FAILURE If an error case was encountered.

Example

WC_PKCS12* pkcs;
WOLFSSL_BIO* bio;
WOLFSSL_X509* cert;
WOLFSSL_EVP_PKEY* pkey;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
wc_PKCS12_free(pkcs)
//use cert, pkey, and optionally certs stack

function wolfSSL_SetTmpDH

int wolfSSL_SetTmpDH(
    WOLFSSL * ssl,
    const unsigned char * p,
    int pSz,
    const unsigned char * g,
    int gSz
)

Server Diffie-Hellman Ephemeral parameters setting. This function sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• p Diffie-Hellman prime number parameter.
• pSz size of p.
• g Diffie-Hellman “generator” parameter.
• gSz size of g.

See: SSL_accept

Return:

• SSL_SUCCESS upon success.
• MEMORY_ERROR will be returned if a memory error was encountered.
• SIDE_ERROR will be returned if this function is called on an SSL client instead of an SSL server.

Example

WOLFSSL* ssl;
static unsigned char p[] = {...};
static unsigned char g[] = {...};
...
wolfSSL_SetTmpDH(ssl, p, sizeof(p), g, sizeof(g));

function wolfSSL_SetTmpDH_buffer

int wolfSSL_SetTmpDH_buffer(
    WOLFSSL * ssl,
    const unsigned char * b,
    long sz,
    int format
)

The function calls the wolfSSL_SetTMpDH_buffer_wrapper, which is a wrapper for Diffie-Hellman parameters.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• buf allocated buffer passed in from wolfSSL_SetTMpDH_file_wrapper.
• sz a long int that holds the size of the file (fname within wolfSSL_SetTmpDH_file_wrapper).
• format an integer type passed through from wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate format.

See:

• wolfSSL_SetTmpDH_buffer_wrapper
• wc_DhParamsLoad
• wolfSSL_SetTmpDH
• PemToDer
• wolfSSL_CTX_SetTmpDH
• wolfSSL_CTX_SetTmpDH_file

Return:

• SSL_SUCCESS on successful execution.
• SSL_BAD_FILETYPE if the file type is not PEM and is not ASN.1. It will also be returned if the wc_DhParamsLoad does not return normally.
• SSL_NO_PEM_HEADER returns from PemToDer if there is not a PEM header.
• SSL_BAD_FILE returned if there is a file error in PemToDer.
• SSL_FATAL_ERROR returned from PemToDer if there was a copy error.
• MEMORY_E - if there was a memory allocation error.
• BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if there was otherwise a NULL argument passed to a subroutine.
• DH_KEY_SIZE_E is returned if their is a key size error in wolfSSL_SetTmpDH() or in wolfSSL_CTX_SetTmpDH().
• SIDE_ERROR returned if it is not the server side in wolfSSL_SetTmpDH.

Example

Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
Const char* fname, int format);
long sz = 0;
byte* myBuffer = staticBuffer[FILE_BUFFER_SIZE];
…
if(ssl)
ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);

function wolfSSL_SetTmpDH_file

int wolfSSL_SetTmpDH_file(
    WOLFSSL * ssl,
    const char * f,
    int format
)

This function calls wolfSSL_SetTmpDH_file_wrapper to set server Diffie-Hellman parameters.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• fname a constant char pointer holding the certificate.
• format an integer type that holds the format of the certification.

See:

• wolfSSL_CTX_SetTmpDH_file
• wolfSSL_SetTmpDH_file_wrapper
• wolfSSL_SetTmpDH_buffer
• wolfSSL_CTX_SetTmpDH_buffer
• wolfSSL_SetTmpDH_buffer_wrapper
• wolfSSL_SetTmpDH
• wolfSSL_CTX_SetTmpDH

Return:

• SSL_SUCCESS returned on successful completion of this function and its subroutines.
• MEMORY_E returned if a memory allocation failed in this function or a subroutine.
• SIDE_ERROR if the side member of the Options structure found in the WOLFSSL struct is not the server side.
• SSL_BAD_FILETYPE returns if the certificate fails a set of checks.
• DH_KEY_SIZE_E returned if the DH parameter's key size is less than the value of the minDhKeySz member in the WOLFSSL struct.
• DH_KEY_SIZE_E returned if the DH parameter's key size is greater than the value of the maxDhKeySz member in the WOLFSSL struct.
• BAD_FUNC_ARG returns if an argument value is NULL that is not permitted such as, the WOLFSSL structure.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
const char* dhParam;
…
AssertIntNE(SSL_SUCCESS,
wolfSSL_SetTmpDH_file(ssl, dhParam, SSL_FILETYPE_PEM));

function wolfSSL_CTX_SetTmpDH

int wolfSSL_CTX_SetTmpDH(
    WOLFSSL_CTX * ctx,
    const unsigned char * p,
    int pSz,
    const unsigned char * g,
    int gSz
)

Sets the parameters for the server CTX Diffie-Hellman.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• p a constant unsigned char pointer loaded into the buffer member of the serverDH_P struct.
• pSz an int type representing the size of p, initialized to MAX_DH_SIZE.
• g a constant unsigned char pointer loaded into the buffer member of the serverDH_G struct.
• gSz an int type representing the size of g, initialized to MAX_DH_SIZE.

See:

• wolfSSL_SetTmpDH
• wc_DhParamsLoad

Return:

• SSL_SUCCESS returned if the function and all subroutines return without error.
• BAD_FUNC_ARG returned if the CTX, p or g parameters are NULL.
• DH_KEY_SIZE_E returned if the DH parameter's key size is less than the value of the minDhKeySz member of the WOLFSSL_CTX struct.
• DH_KEY_SIZE_E returned if the DH parameter's key size is greater than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
• MEMORY_E returned if the allocation of memory failed in this function or a subroutine.

Exmaple

WOLFSSL_CTX* ctx =  WOLFSSL_CTX_new( protocol );
byte* p;
byte* g;
word32 pSz = (word32)sizeof(p)/sizeof(byte);
word32 gSz = (word32)sizeof(g)/sizeof(byte);
…
int ret =  wolfSSL_CTX_SetTmpDH(ctx, p, pSz, g, gSz);

if(ret != SSL_SUCCESS){
    // Failure case
}

function wolfSSL_CTX_SetTmpDH_buffer

int wolfSSL_CTX_SetTmpDH_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * b,
    long sz,
    int format
)

A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper.

Parameters:

• ctx a pointer to a WOLFSSL structure, created using wolfSSL_CTX_new().
• buf a pointer to a constant unsigned char type that is allocated as the buffer and passed through to wolfSSL_SetTmpDH_buffer_wrapper.
• sz a long integer type that is derived from the fname parameter in wolfSSL_SetTmpDH_file_wrapper().
• format an integer type passed through from wolfSSL_SetTmpDH_file_wrapper().

See:

• wolfSSL_SetTmpDH_buffer_wrapper
• wolfSSL_SetTMpDH_buffer
• wolfSSL_SetTmpDH_file_wrapper
• wolfSSL_CTX_SetTmpDH_file

Return:

• 0 returned for a successful execution.
• BAD_FUNC_ARG returned if the ctx or buf parameters are NULL.
• MEMORY_E if there is a memory allocation error.
• SSL_BAD_FILETYPE returned if format is not correct.

Example

static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
Const char* fname, int format);
#ifdef WOLFSSL_SMALL_STACK
byte staticBuffer[1]; // force heap usage
#else
byte* staticBuffer;
long sz = 0;
…
if(ssl){
    ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);
} else {
ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format);
}

function wolfSSL_CTX_SetTmpDH_file

int wolfSSL_CTX_SetTmpDH_file(
    WOLFSSL_CTX * ctx,
    const char * f,
    int format
)

The function calls wolfSSL_SetTmpDH_file_wrapper to set the server Diffie-Hellman parameters.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• fname a constant character pointer to a certificate file.
• format an integer type passed through from wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate format.

See:

• wolfSSL_SetTmpDH_buffer_wrapper
• wolfSSL_SetTmpDH
• wolfSSL_CTX_SetTmpDH
• wolfSSL_SetTmpDH_buffer
• wolfSSL_CTX_SetTmpDH_buffer
• wolfSSL_SetTmpDH_file_wrapper
• AllocDer
• PemToDer

Return:

• SSL_SUCCESS returned if the wolfSSL_SetTmpDH_file_wrapper or any of its subroutines return successfully.
• MEMORY_E returned if an allocation of dynamic memory fails in a subroutine.
• BAD_FUNC_ARG returned if the ctx or fname parameters are NULL or if a subroutine is passed a NULL argument.
• SSL_BAD_FILE returned if the certificate file is unable to open or if the a set of checks on the file fail from wolfSSL_SetTmpDH_file_wrapper.
• SSL_BAD_FILETYPE returned if the format is not PEM or ASN.1 from wolfSSL_SetTmpDH_buffer_wrapper().
• DH_KEY_SIZE_E returned if the DH parameter's key size is less than the value of the minDhKeySz member of the WOLFSSL_CTX struct.
• DH_KEY_SIZE_E returned if the DH parameter's key size is greater than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
• SIDE_ERROR returned in wolfSSL_SetTmpDH() if the side is not the server end.
• SSL_NO_PEM_HEADER returned from PemToDer if there is no PEM header.
• SSL_FATAL_ERROR returned from PemToDer if there is a memory copy failure.

Example

#define dhParam     “certs/dh2048.pem”
#DEFINE aSSERTiNTne(x, y)     AssertInt(x, y, !=, ==)
WOLFSSL_CTX* ctx;
…
AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method()))
…
AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam,
SSL_FILETYPE_PEM));

function wolfSSL_CTX_SetMinDhKey_Sz

int wolfSSL_CTX_SetMinDhKey_Sz(
    WOLFSSL_CTX * ctx,
    word16 
)

This function sets the minimum size (in bits) of the Diffie Hellman key size by accessing the minDhKeySz member in the WOLFSSL_CTX structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz_bits a word16 type used to set the minimum DH key size in bits. The WOLFSSL_CTX struct holds this information in the minDhKeySz member.

See:

• wolfSSL_SetMinDhKey_Sz
• wolfSSL_CTX_SetMaxDhKey_Sz
• wolfSSL_SetMaxDhKey_Sz
• wolfSSL_GetDhKey_Sz
• wolfSSL_CTX_SetTMpDH_file

Return:

• SSL_SUCCESS returned if the function completes successfully.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if the keySz_bits is greater than 16,000 or not divisible by 8.

Example

public static int CTX_SetMinDhKey_Sz(IntPtr ctx, short minDhKey){
…
return wolfSSL_CTX_SetMinDhKey_Sz(local_ctx, minDhKeyBits);

function wolfSSL_SetMinDhKey_Sz

int wolfSSL_SetMinDhKey_Sz(
    WOLFSSL * ssl,
    word16 keySz_bits
)

Sets the minimum size (in bits) for a Diffie-Hellman key in the WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz_bits a word16 type used to set the minimum DH key size in bits. The WOLFSSL_CTX struct holds this information in the minDhKeySz member.

See:

• wolfSSL_CTX_SetMinDhKey_Sz
• wolfSSL_GetDhKey_Sz

Return:

• SSL_SUCCESS the minimum size was successfully set.
• BAD_FUNC_ARG the WOLFSSL structure was NULL or if the keySz_bits is greater than 16,000 or not divisible by 8.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
word16 keySz_bits;
...
if(wolfSSL_SetMinDhKey_Sz(ssl, keySz_bits) != SSL_SUCCESS){
    // Failed to set.
}

function wolfSSL_CTX_SetMaxDhKey_Sz

int wolfSSL_CTX_SetMaxDhKey_Sz(
    WOLFSSL_CTX * ctx,
    word16 keySz_bits
)

This function sets the maximum size (in bits) of the Diffie Hellman key size by accessing the maxDhKeySz member in the WOLFSSL_CTX structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz_bits a word16 type used to set the maximum DH key size in bits. The WOLFSSL_CTX struct holds this information in the maxDhKeySz member.

See:

• wolfSSL_SetMinDhKey_Sz
• wolfSSL_CTX_SetMinDhKey_Sz
• wolfSSL_SetMaxDhKey_Sz
• wolfSSL_GetDhKey_Sz
• wolfSSL_CTX_SetTMpDH_file

Return:

• SSL_SUCCESS returned if the function completes successfully.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if the keySz_bits is greater than 16,000 or not divisible by 8.

Example

public static int CTX_SetMaxDhKey_Sz(IntPtr ctx, short maxDhKey){
…
return wolfSSL_CTX_SetMaxDhKey_Sz(local_ctx, keySz_bits);

function wolfSSL_SetMaxDhKey_Sz

int wolfSSL_SetMaxDhKey_Sz(
    WOLFSSL * ssl,
    word16 keySz_bits
)

Sets the maximum size (in bits) for a Diffie-Hellman key in the WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz a word16 type representing the bit size of the maximum DH key.

See:

• wolfSSL_CTX_SetMaxDhKey_Sz
• wolfSSL_GetDhKey_Sz

Return:

• SSL_SUCCESS the maximum size was successfully set.
• BAD_FUNC_ARG the WOLFSSL structure was NULL or the keySz parameter was greater than the allowable size or not divisible by 8.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
word16 keySz;
...
if(wolfSSL_SetMaxDhKey(ssl, keySz) != SSL_SUCCESS){
    // Failed to set.
}

function wolfSSL_GetDhKey_Sz

int wolfSSL_GetDhKey_Sz(
    WOLFSSL * 
)

Returns the value of dhKeySz (in bits) that is a member of the options structure. This value represents the Diffie-Hellman key size in bytes.

Parameters:

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

See:

• wolfSSL_SetMinDhKey_sz
• wolfSSL_CTX_SetMinDhKey_Sz
• wolfSSL_CTX_SetTmpDH
• wolfSSL_SetTmpDH
• wolfSSL_CTX_SetTmpDH_file

Return:

• dhKeySz returns the value held in ssl->options.dhKeySz which is an integer value representing a size in bits.
• BAD_FUNC_ARG returns if the WOLFSSL struct is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int dhKeySz;
...
dhKeySz = wolfSSL_GetDhKey_Sz(ssl);

if(dhKeySz == BAD_FUNC_ARG || dhKeySz <= 0){
    // Failure case
} else {
    // dhKeySz holds the size of the key.
}

function wolfSSL_CTX_SetMinRsaKey_Sz

int wolfSSL_CTX_SetMinRsaKey_Sz(
    WOLFSSL_CTX * ctx,
    short keySz
)

Sets the minimum RSA key size in both the WOLFSSL_CTX structure and the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• keySz a short integer type stored in minRsaKeySz in the ctx structure and the cm structure converted to bytes.

See: wolfSSL_SetMinRsaKey_Sz

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the ctx structure is NULL or the keySz is less than zero or not divisible by 8.

Example

WOLFSSL_CTX* ctx = SSL_CTX_new(method);
(void)minDhKeyBits;
ourCert = myoptarg;
…
minDhKeyBits = atoi(myoptarg);
…
if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){
…

function wolfSSL_SetMinRsaKey_Sz

int wolfSSL_SetMinRsaKey_Sz(
    WOLFSSL * ssl,
    short keySz
)

Sets the minimum allowable key size in bits for RSA located in the WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz a short integer value representing the the minimum key in bits.

See: wolfSSL_CTX_SetMinRsaKey_Sz

Return:

• SSL_SUCCESS the minimum was set successfully.
• BAD_FUNC_ARG returned if the ssl structure is NULL or if the ksySz is less than zero or not divisible by 8.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
short keySz;
…

int isSet =  wolfSSL_SetMinRsaKey_Sz(ssl, keySz);
if(isSet != SSL_SUCCESS){
    Failed to set.
}

function wolfSSL_CTX_SetMinEccKey_Sz

int wolfSSL_CTX_SetMinEccKey_Sz(
    WOLFSSL_CTX * ssl,
    short keySz
)

Sets the minimum size in bits for the ECC key in the WOLF_CTX structure and the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• keySz a short integer type that represents the minimum ECC key size in bits.

See: wolfSSL_SetMinEccKey_Sz

Return:

• SSL_SUCCESS returned for a successful execution and the minEccKeySz member is set.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if the keySz is negative or not divisible by 8.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
short keySz; // minimum key size
…
if(wolfSSL_CTX_SetMinEccKey(ctx, keySz) != SSL_SUCCESS){
    // Failed to set min key size
}

function wolfSSL_SetMinEccKey_Sz

int wolfSSL_SetMinEccKey_Sz(
    WOLFSSL * ssl,
    short keySz
)

Sets the value of the minEccKeySz member of the options structure. The options struct is a member of the WOLFSSL structure and is accessed through the ssl parameter.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• keySz value used to set the minimum ECC key size. Sets value in the options structure.

See:

• wolfSSL_CTX_SetMinEccKey_Sz
• wolfSSL_CTX_SetMinRsaKey_Sz
• wolfSSL_SetMinRsaKey_Sz

Return:

• SSL_SUCCESS if the function successfully set the minEccKeySz member of the options structure.
• BAD_FUNC_ARG if the WOLFSSL_CTX structure is NULL or if the key size (keySz) is less than 0 (zero) or not divisible by 8.

Example

WOLFSSL* ssl = wolfSSL_new(ctx); // New session
short keySz = 999; // should be set to min key size allowable
...
if(wolfSSL_SetMinEccKey_Sz(ssl, keySz) != SSL_SUCCESS){
    // Failure case.
}

function wolfSSL_make_eap_keys

int wolfSSL_make_eap_keys(
    WOLFSSL * ssl,
    void * key,
    unsigned int len,
    const char * label
)

This function is used by EAP_TLS and EAP-TTLS to derive keying material from the master secret.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• msk a void pointer variable that will hold the result of the p_hash function.
• len an unsigned integer that represents the length of the msk variable.
• label a constant char pointer that is copied from in wc_PRF().

See:

• wc_PRF
• wc_HmacFinal
• wc_HmacUpdate

Return:

• BUFFER_E returned if the actual size of the buffer exceeds the maximum size allowable.
• MEMORY_E returned if there is an error with memory allocation.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);;
void* msk;
unsigned int len;
const char* label;
…
return wolfSSL_make_eap_keys(ssl, msk, len, label);

function wolfSSL_writev

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

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

Parameters:

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

See: wolfSSL_write

Return:

• 0 the number of bytes written upon success.

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

Example

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

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

function wolfSSL_CTX_UnloadCAs

int wolfSSL_CTX_UnloadCAs(
    WOLFSSL_CTX * 
)

This function unloads the CA signer list and frees the whole signer table.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_CertManagerUnloadCAs
• LockMutex
• UnlockMutex

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there are otherwise unpermitted argument values passed in a subroutine.
• BAD_MUTEX_E returned if there was a mutex error. The LockMutex() did not return 0.

Example

WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
…
if(wolfSSL_CTX_UnloadCAs(ctx) != SSL_SUCCESS){
    // The function did not unload CAs
}

function wolfSSL_CTX_UnloadIntermediateCerts

int wolfSSL_CTX_UnloadIntermediateCerts(
    WOLFSSL_CTX * ctx
)

This function unloads intermediate certificates added to the CA signer list and frees them.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_CTX_UnloadCAs
• wolfSSL_CertManagerUnloadIntermediateCerts

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there are otherwise unpermitted argument values passed in a subroutine.
• BAD_STATE_E returned if the WOLFSSL_CTX has a reference count > 1.
• BAD_MUTEX_E returned if there was a mutex error. The LockMutex() did not return 0.

Example

WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
…
if(wolfSSL_CTX_UnloadIntermediateCerts(ctx) != NULL){
    // The function did not unload CAs
}

function wolfSSL_CTX_Unload_trust_peers

int wolfSSL_CTX_Unload_trust_peers(
    WOLFSSL_CTX * 
)

This function is used to unload all previously loaded trusted peer certificates. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().

See:

• wolfSSL_CTX_trust_peer_buffer
• wolfSSL_CTX_trust_peer_cert

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG will be returned if ctx is NULL.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_Unload_trust_peers(ctx);
if (ret != SSL_SUCCESS) {
    // error unloading trusted peer certs
}
...

function wolfSSL_CTX_trust_peer_buffer

int wolfSSL_CTX_trust_peer_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a certificate to use for verifying a peer when performing a TLS/SSL handshake. The peer certificate sent during the handshake is compared by using the SKID when available and the signature. If these two things do not match then any loaded CAs are used. Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from a buffer instead of a file. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• buffer pointer to the buffer containing certificates.
• sz length of the buffer input.
• type type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_file
• wolfSSL_CTX_use_PrivateKey_file
• wolfSSL_CTX_use_certificate_chain_file
• wolfSSL_CTX_trust_peer_cert
• wolfSSL_CTX_Unload_trust_peers
• wolfSSL_use_certificate_file
• wolfSSL_use_PrivateKey_file
• wolfSSL_use_certificate_chain_file

Return:

• SSL_SUCCESS upon success
• SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...

ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz,
SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
// error loading trusted peer cert
}
...

function wolfSSL_CTX_load_verify_buffer

int wolfSSL_CTX_load_verify_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a CA certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in pointer to the CA certificate buffer.
• sz size of the input CA certificate buffer, in.
• format format of the buffer certificate, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte certBuff[...];
long sz = sizeof(certBuff);
...

ret = wolfSSL_CTX_load_verify_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading CA certs from buffer
}
...

function wolfSSL_CTX_load_verify_buffer_ex

int wolfSSL_CTX_load_verify_buffer_ex(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format,
    int userChain,
    word32 flags
)

This function loads a CA certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. The _ex version was added in PR 2413 and supports additional arguments for userChain and flags.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in pointer to the CA certificate buffer.
• sz size of the input CA certificate buffer, in.
• format format of the buffer certificate, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
• userChain If using format WOLFSSL_FILETYPE_ASN1 this set to non-zero indicates a chain of DER's is being presented.
• flags See ssl.h around WOLFSSL_LOAD_VERIFY_DEFAULT_FLAGS.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte certBuff[...];
long sz = sizeof(certBuff);
...

// Example for force loading an expired certificate
ret = wolfSSL_CTX_load_verify_buffer_ex(ctx, certBuff, sz, SSL_FILETYPE_PEM,
    0, (WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY));
if (ret != SSL_SUCCESS) {
    // error loading CA certs from buffer
}
...

function wolfSSL_CTX_load_verify_chain_buffer_format

int wolfSSL_CTX_load_verify_chain_buffer_format(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a CA certificate chain buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More than one CA certificate may be loaded per buffer as long as the format is in PEM. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in pointer to the CA certificate buffer.
• sz size of the input CA certificate buffer, in.
• format format of the buffer certificate, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_locations
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte certBuff[...];
long sz = sizeof(certBuff);
...

ret = wolfSSL_CTX_load_verify_chain_buffer_format(ctx,
                     certBuff, sz, WOLFSSL_FILETYPE_ASN1);
if (ret != SSL_SUCCESS) {
    // error loading CA certs from buffer
}
...

function wolfSSL_CTX_use_certificate_buffer

int wolfSSL_CTX_use_certificate_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a certificate buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in the input buffer containing the certificate to be loaded.
• sz the size of the input buffer.
• format the format of the certificate located in the input buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte certBuff[...];
long sz = sizeof(certBuff);
...
ret = wolfSSL_CTX_use_certificate_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading certificate from buffer
}
...

function wolfSSL_CTX_use_PrivateKey_buffer

int wolfSSL_CTX_use_PrivateKey_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a private key buffer into the SSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in the input buffer containing the private key to be loaded.
• sz the size of the input buffer.
• format the format of the private key located in the input buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• NO_PASSWORD will be returned if the key file is encrypted but no password is provided.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte keyBuff[...];
long sz = sizeof(certBuff);
...
ret = wolfSSL_CTX_use_PrivateKey_buffer(ctx, keyBuff, sz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading private key from buffer
}
...

function wolfSSL_CTX_use_certificate_chain_buffer

int wolfSSL_CTX_use_certificate_chain_buffer(
    WOLFSSL_CTX * ctx,
    const unsigned char * in,
    long sz
)

This function loads a certificate chain buffer into the WOLFSSL Context. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. The buffer must be in PEM format and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• in the input buffer containing the PEM-formatted certificate chain to be loaded.
• sz the size of the input buffer.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
byte certChainBuff[...];
long sz = sizeof(certBuff);
...
ret = wolfSSL_CTX_use_certificate_chain_buffer(ctx, certChainBuff, sz);
if (ret != SSL_SUCCESS) {
    // error loading certificate chain from buffer
}
...

function wolfSSL_use_certificate_buffer

int wolfSSL_use_certificate_buffer(
    WOLFSSL * ssl,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a certificate buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• in buffer containing certificate to load.
• sz size of the certificate located in buffer.
• format format of the certificate to be loaded. Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_PrivateKey_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.

Example

int ret;
byte certBuff[...];
WOLFSSL* ssl = 0;
long buffSz = sizeof(certBuff);
...

ret = wolfSSL_use_certificate_buffer(ssl, certBuff, buffSz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // failed to load certificate from buffer
}

function wolfSSL_use_PrivateKey_buffer

int wolfSSL_use_PrivateKey_buffer(
    WOLFSSL * ssl,
    const unsigned char * in,
    long sz,
    int format
)

This function loads a private key buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. format specifies the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• in buffer containing private key to load.
• sz size of the private key located in buffer.
• format format of the private key to be loaded. Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_use_PrivateKey
• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_certificate_chain_buffer

Return:

• SSL_SUCCESS upon success.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• NO_PASSWORD will be returned if the key file is encrypted but no password is provided.

Example

int ret;
byte keyBuff[...];
WOLFSSL* ssl = 0;
long buffSz = sizeof(certBuff);
...
ret = wolfSSL_use_PrivateKey_buffer(ssl, keyBuff, buffSz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // failed to load private key from buffer
}

function wolfSSL_use_certificate_chain_buffer

int wolfSSL_use_certificate_chain_buffer(
    WOLFSSL * ssl,
    const unsigned char * in,
    long sz
)

This function loads a certificate chain buffer into the WOLFSSL object. It behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer is provided by the in argument of size sz. The buffer must be in PEM format and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage.

Parameters:

• ssl pointer to the SSL session, created with wolfSSL_new().
• in buffer containing certificate to load.
• sz size of the certificate located in buffer.

See:

• wolfSSL_CTX_load_verify_buffer
• wolfSSL_CTX_use_certificate_buffer
• wolfSSL_CTX_use_PrivateKey_buffer
• wolfSSL_CTX_use_certificate_chain_buffer
• wolfSSL_use_certificate_buffer
• wolfSSL_use_PrivateKey_buffer

Return:

• SSL_SUCCES upon success.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.

Example

int ret;
byte certChainBuff[...];
WOLFSSL* ssl = 0;
long buffSz = sizeof(certBuff);
...
ret = wolfSSL_use_certificate_chain_buffer(ssl, certChainBuff, buffSz);
if (ret != SSL_SUCCESS) {
    // failed to load certificate chain from buffer
}

function wolfSSL_UnloadCertsKeys

int wolfSSL_UnloadCertsKeys(
    WOLFSSL * 
)

This function unloads any certificates or keys that SSL owns.

Parameters:

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

See: wolfSSL_CTX_UnloadCAs

Return:

• SSL_SUCCESS - returned if the function executed successfully.
• BAD_FUNC_ARG - returned if the WOLFSSL object is NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
...
int unloadKeys = wolfSSL_UnloadCertsKeys(ssl);
if(unloadKeys != SSL_SUCCESS){
    // Failure case.
}

function wolfSSL_CTX_set_group_messages

int wolfSSL_CTX_set_group_messages(
    WOLFSSL_CTX * 
)

This function turns on grouping of handshake messages where possible.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().

See:

• wolfSSL_set_group_messages
• wolfSSL_CTX_new

Return:

• SSL_SUCCESS will be returned upon success.
• BAD_FUNC_ARG will be returned if the input context is null.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_group_messages(ctx);
if (ret != SSL_SUCCESS) {
    // failed to set handshake message grouping
}

function wolfSSL_set_group_messages

int wolfSSL_set_group_messages(
    WOLFSSL * 
)

This function turns on grouping of handshake messages where possible.

Parameters:

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

See:

• wolfSSL_CTX_set_group_messages
• wolfSSL_new

Return:

• SSL_SUCCESS will be returned upon success.
• BAD_FUNC_ARG will be returned if the input context is null.

Example

WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_group_messages(ssl);
if (ret != SSL_SUCCESS) {
// failed to set handshake message grouping
}

function wolfSSL_SetFuzzerCb

void wolfSSL_SetFuzzerCb(
    WOLFSSL * ssl,
    CallbackFuzzer cbf,
    void * fCtx
)

This function sets the fuzzer callback.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cbf a CallbackFuzzer type that is a function pointer of the form: int (CallbackFuzzer)(WOLFSSL ssl, const unsigned char buf, int sz, int type, void fuzzCtx);
• fCtx a void pointer type that will be set to the fuzzerCtx member of the WOLFSSL structure.

See: CallbackFuzzer

Return: none No returns.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
void* fCtx;

int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz,
            int type, void* fuzzCtx){
// function definition
}
…
wolfSSL_SetFuzzerCb(ssl, callbackFuzzerCB, fCtx);

function wolfSSL_DTLS_SetCookieSecret

int wolfSSL_DTLS_SetCookieSecret(
    WOLFSSL * ssl,
    const unsigned char * secret,
    unsigned int secretSz
)

This function sets a new dtls cookie secret.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• secret a constant byte pointer representing the secret buffer.
• secretSz the size of the buffer.

See:

• ForceZero
• wc_RNG_GenerateBlock

Return:

• 0 returned if the function executed without an error.
• BAD_FUNC_ARG returned if there was an argument passed to the function with an unacceptable value.
• COOKIE_SECRET_SZ returned if the secret size is 0.
• MEMORY_ERROR returned if there was a problem allocating memory for a new cookie secret.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
const* byte secret;
word32 secretSz; // size of secret
…
if(!wolfSSL_DTLS_SetCookieSecret(ssl, secret, secretSz)){
    // Code block for failure to set DTLS cookie secret
} else {
    // Success! Cookie secret is set.
}

function wolfSSL_GetRNG

WC_RNG * wolfSSL_GetRNG(
    WOLFSSL * ssl
)

This function retrieves the random number.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().

See: wolfSSL_CTX_new_rng

Return:

• rng upon success.
• NULL if ssl is NULL.

Example

WOLFSSL* ssl;

wolfSSL_GetRNG(ssl);

function wolfSSL_CTX_SetMinVersion

int wolfSSL_CTX_SetMinVersion(
    WOLFSSL_CTX * ctx,
    int version
)

This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method).

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• version an integer representation of the version to be set as the minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or WOLFSSL_TLSV1_2 = 3.

See: SetMinVersionHelper

Return:

• SSL_SUCCESS returned if the function returned without error and the minimum version is set.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX structure was NULL or if the minimum version is not supported.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
int version; // macrop representation
…
if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
    // Failed to set min version
}

function wolfSSL_SetMinVersion

int wolfSSL_SetMinVersion(
    WOLFSSL * ssl,
    int version
)

This function sets the minimum downgrade version allowed. Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method).

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• version an integer representation of the version to be set as the minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or WOLFSSL_TLSV1_2 = 3.

See: SetMinVersionHelper

Return:

• SSL_SUCCESS returned if this function and its subroutine executes without error.
• BAD_FUNC_ARG returned if the SSL object is NULL. In the subroutine this error is thrown if there is not a good version match.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol method);
WOLFSSL* ssl = WOLFSSL_new(ctx);
int version;  macro representation
…
if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
    Failed to set min version
}

function wolfSSL_GetObjectSize

int wolfSSL_GetObjectSize(
    void 
)

This function returns the size of the WOLFSSL object and will be dependent on build options and settings. If SHOW_SIZES has been defined when building wolfSSL, this function will also print the sizes of individual objects within the WOLFSSL object (Suites, Ciphers, etc.) to stdout.

Parameters:

• none No parameters.

See: wolfSSL_new

Return: size This function returns the size of the WOLFSSL object.

Example

int size = 0;
size = wolfSSL_GetObjectSize();
printf(“sizeof(WOLFSSL) = %d\n”, size);

function wolfSSL_GetOutputSize

int wolfSSL_GetOutputSize(
    WOLFSSL * ssl,
    int inSz
)

Returns the record layer size of the plaintext input. This is helpful when an application wants to know how many bytes will be sent across the Transport layer, given a specified plaintext input size. This function must be called after the SSL/TLS handshake has been completed.

Parameters:

• ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
• inSz size of plaintext data.

See: wolfSSL_GetMaxOutputSize

Return:

• size Upon success, the requested size will be returned
• INPUT_SIZE_E will be returned if the input size is greater than the maximum TLS fragment size (see wolfSSL_GetMaxOutputSize())
• BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS handshake has not been completed yet

Example

none

function wolfSSL_GetMaxOutputSize

int wolfSSL_GetMaxOutputSize(
    WOLFSSL * 
)

Returns the maximum record layer size for plaintext data. This will correspond to either the maximum SSL/TLS record size as specified by the protocol standard, the maximum TLS fragment size as set by the TLS Max Fragment Length extension. This function is helpful when the application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E error. This function must be called after the SSL/TLS handshake has been completed.

Parameters:

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

See: wolfSSL_GetOutputSize

Return:

• size Upon success, the maximum output size will be returned
• BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS handshake has not been completed yet.

Example

none

function wolfSSL_SetVersion

int wolfSSL_SetVersion(
    WOLFSSL * ssl,
    int version
)

This function sets the SSL/TLS protocol version for the specified SSL session (WOLFSSL object) using the version as specified by version. This will override the protocol setting for the SSL session (ssl) - originally defined and set by the SSL context (wolfSSL_CTX_new()) method type.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• version SSL/TLS protocol version. Possible values include WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2.

See: wolfSSL_CTX_new

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG will be returned if the input SSL object is NULL or an incorrect protocol version is given for version.

Example

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

ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1);
if (ret != SSL_SUCCESS) {
    // failed to set SSL session protocol version
}

function wolfSSL_CTX_SetMacEncryptCb

void wolfSSL_CTX_SetMacEncryptCb(
    WOLFSSL_CTX * ctx,
    CallbackMacEncrypti cb
)

Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. macOut is the output buffer where the result of the mac should be stored. macIn is the mac input buffer and macInSz notes the size of the buffer. macContent and macVerify are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. encOut is the output buffer where the result on the encryption should be stored. encIn is the input buffer to encrypt while encSz is the size of the input. An example callback can be found wolfssl/test.h myMacEncryptCb().

Parameters:

• No parameters.

See:

• wolfSSL_SetMacEncryptCtx
• wolfSSL_GetMacEncryptCtx

Return: none No return.

Example

none

function wolfSSL_SetMacEncryptCtx

void wolfSSL_SetMacEncryptCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetMacEncryptCb
• wolfSSL_GetMacEncryptCtx

Return: none No return.

Example

none

function wolfSSL_GetMacEncryptCtx

void * wolfSSL_GetMacEncryptCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Atomic User Record Processing Mac/Encrypt Callback Context previously stored with wolfSSL_SetMacEncryptCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetMacEncryptCb
• wolfSSL_SetMacEncryptCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetDecryptVerifyCb

void wolfSSL_CTX_SetDecryptVerifyCb(
    WOLFSSL_CTX * ctx,
    CallbackDecryptVerify cb
)

Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. decOut is the output buffer where the result of the decryption should be stored. decIn is the encrypted input buffer and decInSz notes the size of the buffer. content and verify are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. padSz is an output variable that should be set with the total value of the padding. That is, the mac size plus any padding and pad bytes. An example callback can be found wolfssl/test.h myDecryptVerifyCb().

Parameters:

• none No parameters.

See:

• wolfSSL_SetMacEncryptCtx
• wolfSSL_GetMacEncryptCtx

Return: none No returns.

Example

none

function wolfSSL_SetDecryptVerifyCtx

void wolfSSL_SetDecryptVerifyCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetDecryptVerifyCb
• wolfSSL_GetDecryptVerifyCtx

Return: none No returns.

Example

none

function wolfSSL_GetDecryptVerifyCtx

void * wolfSSL_GetDecryptVerifyCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Atomic User Record Processing Decrypt/Verify Callback Context previously stored with wolfSSL_SetDecryptVerifyCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetDecryptVerifyCb
• wolfSSL_SetDecryptVerifyCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_GetMacSecret

const unsigned char * wolfSSL_GetMacSecret(
    WOLFSSL * ssl,
    int verify
)

Allows retrieval of the Hmac/Mac secret from the handshake process. The verify parameter specifies whether this is for verification of a peer message.

Parameters:

• ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
• verify specifies whether this is for verification of a peer message.

See: wolfSSL_GetHmacSize

Return:

• pointer If successful the call will return a valid pointer to the secret. The size of the secret can be obtained from wolfSSL_GetHmacSize().
• NULL will be returned for an error state.

Example

none

function wolfSSL_GetClientWriteKey

const unsigned char * wolfSSL_GetClientWriteKey(
    WOLFSSL * 
)

Allows retrieval of the client write key from the handshake process.

Parameters:

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

See:

• wolfSSL_GetKeySize
• wolfSSL_GetClientWriteIV

Return:

• pointer If successful the call will return a valid pointer to the key. The size of the key can be obtained from wolfSSL_GetKeySize().
• NULL will be returned for an error state.

Example

none

function wolfSSL_GetClientWriteIV

const unsigned char * wolfSSL_GetClientWriteIV(
    WOLFSSL * 
)

Allows retrieval of the client write IV (initialization vector) from the handshake process.

Parameters:

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

See:

• wolfSSL_GetCipherBlockSize()
• wolfSSL_GetClientWriteKey()

Return:

• pointer If successful the call will return a valid pointer to the IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
• NULL will be returned for an error state.

Example

none

function wolfSSL_GetServerWriteKey

const unsigned char * wolfSSL_GetServerWriteKey(
    WOLFSSL * 
)

Allows retrieval of the server write key from the handshake process.

Parameters:

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

See:

• wolfSSL_GetKeySize
• wolfSSL_GetServerWriteIV

Return:

• pointer If successful the call will return a valid pointer to the key. The size of the key can be obtained from wolfSSL_GetKeySize().
• NULL will be returned for an error state.

Example

none

function wolfSSL_GetServerWriteIV

const unsigned char * wolfSSL_GetServerWriteIV(
    WOLFSSL * 
)

Allows retrieval of the server write IV (initialization vector) from the handshake process.

Parameters:

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

See:

• wolfSSL_GetCipherBlockSize
• wolfSSL_GetClientWriteKey

Return:

• pointer If successful the call will return a valid pointer to the IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
• NULL will be returned for an error state.

function wolfSSL_GetKeySize

int wolfSSL_GetKeySize(
    WOLFSSL * 
)

Allows retrieval of the key size from the handshake process.

Parameters:

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

See:

• wolfSSL_GetClientWriteKey
• wolfSSL_GetServerWriteKey

Return:

• size If successful the call will return the key size in bytes.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetIVSize

int wolfSSL_GetIVSize(
    WOLFSSL * 
)

Returns the iv_size member of the specs structure held in the WOLFSSL struct.

Parameters:

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

See:

• wolfSSL_GetKeySize
• wolfSSL_GetClientWriteIV
• wolfSSL_GetServerWriteIV

Return:

• iv_size returns the value held in ssl->specs.iv_size.
• BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int ivSize;
...
ivSize = wolfSSL_GetIVSize(ssl);

if(ivSize > 0){
    // ivSize holds the specs.iv_size value.
}

function wolfSSL_GetSide

int wolfSSL_GetSide(
    WOLFSSL * 
)

Allows retrieval of the side of this WOLFSSL connection.

Parameters:

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

See:

• wolfSSL_GetClientWriteKey
• wolfSSL_GetServerWriteKey

Return:

• success If successful the call will return either WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the side of WOLFSSL object.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_IsTLSv1_1

int wolfSSL_IsTLSv1_1(
    WOLFSSL * 
)

Allows caller to determine if the negotiated protocol version is at least TLS version 1.1 or greater.

Parameters:

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

See: wolfSSL_GetSide

Return:

• true/false If successful the call will return 1 for true or 0 for false.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetBulkCipher

int wolfSSL_GetBulkCipher(
    WOLFSSL * 
)

Allows caller to determine the negotiated bulk cipher algorithm from the handshake.

Parameters:

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

See:

• wolfSSL_GetCipherBlockSize
• wolfSSL_GetKeySize

Return:

• If successful the call will return one of the following: wolfssl_cipher_null, wolfssl_des, wolfssl_triple_des, wolfssl_aes, wolfssl_aes_gcm, wolfssl_aes_ccm, wolfssl_camellia.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetCipherBlockSize

int wolfSSL_GetCipherBlockSize(
    WOLFSSL * 
)

Allows caller to determine the negotiated cipher block size from the handshake.

Parameters:

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

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetKeySize

Return:

• size If successful the call will return the size in bytes of the cipher block size.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetAeadMacSize

int wolfSSL_GetAeadMacSize(
    WOLFSSL * 
)

Allows caller to determine the negotiated aead mac size from the handshake. For cipher type WOLFSSL_AEAD_TYPE.

Parameters:

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

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetKeySize

Return:

• size If successful the call will return the size in bytes of the aead mac size.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetHmacSize

int wolfSSL_GetHmacSize(
    WOLFSSL * 
)

Allows caller to determine the negotiated (h)mac size from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.

Parameters:

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

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetHmacType

Return:

• size If successful the call will return the size in bytes of the (h)mac size.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_GetHmacType

int wolfSSL_GetHmacType(
    WOLFSSL * 
)

Allows caller to determine the negotiated (h)mac type from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.

Parameters:

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

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetHmacSize

Return:

• If successful the call will return one of the following: MD5, SHA, SHA256, SHA384.
• BAD_FUNC_ARG may be returned for an error state.
• SSL_FATAL_ERROR may also be returned for an error state.

Example

none

function wolfSSL_GetCipherType

int wolfSSL_GetCipherType(
    WOLFSSL * 
)

Allows caller to determine the negotiated cipher type from the handshake.

Parameters:

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

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetHmacType

Return:

• If successful the call will return one of the following: WOLFSSL_BLOCK_TYPE, WOLFSSL_STREAM_TYPE, WOLFSSL_AEAD_TYPE.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_SetTlsHmacInner

int wolfSSL_SetTlsHmacInner(
    WOLFSSL * ssl,
    byte * inner,
    word32 sz,
    int content,
    int verify
)

Allows caller to set the Hmac Inner vector for message sending/receiving. The result is written to inner which should be at least wolfSSL_GetHmacSize() bytes. The size of the message is specified by sz, content is the type of message, and verify specifies whether this is a verification of a peer message. Valid for cipher types excluding WOLFSSL_AEAD_TYPE.

Parameters:

• none No parameters.

See:

• wolfSSL_GetBulkCipher
• wolfSSL_GetHmacType

Return:

• 1 upon success.
• BAD_FUNC_ARG will be returned for an error state.

Example

none

function wolfSSL_CTX_SetEccSignCb

void wolfSSL_CTX_SetEccSignCb(
    WOLFSSL_CTX * ctx,
    CallbackEccSign cb
)

Allows caller to set the Public Key Callback for ECC Signing. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to sign while inSz denotes the length of the input. out is the output buffer where the result of the signature should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning. keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccSign().

Parameters:

• none No parameters.

See:

• wolfSSL_SetEccSignCtx
• wolfSSL_GetEccSignCtx

Return: none No returns.

Example

none

function wolfSSL_SetEccSignCtx

void wolfSSL_SetEccSignCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key Ecc Signing Callback Context to ctx.

Parameters:

• ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
• ctx a pointer to the user context to be stored

See:

• wolfSSL_CTX_SetEccSignCb
• wolfSSL_GetEccSignCtx

Return: none No returns.

Example

none

function wolfSSL_GetEccSignCtx

void * wolfSSL_GetEccSignCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with wolfSSL_SetEccSignCtx().

Parameters:

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

See:

• wolfSSL_CTX_SetEccSignCb
• wolfSSL_SetEccSignCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetEccSignCtx

void wolfSSL_CTX_SetEccSignCtx(
    WOLFSSL_CTX * ctx,
    void * userCtx
)

Allows caller to set the Public Key Ecc Signing Callback Context to ctx.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• ctx a pointer to the user context to be stored

See:

• wolfSSL_CTX_SetEccSignCb
• wolfSSL_CTX_GetEccSignCtx

Return: none No returns.

Example

none

function wolfSSL_CTX_GetEccSignCtx

void * wolfSSL_CTX_GetEccSignCtx(
    WOLFSSL_CTX * ctx
)

Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with wolfSSL_SetEccSignCtx().

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

See:

• wolfSSL_CTX_SetEccSignCb
• wolfSSL_CTX_SetEccSignCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetEccVerifyCb

void wolfSSL_CTX_SetEccVerifyCb(
    WOLFSSL_CTX * ctx,
    CallbackEccVerify cb
)

Allows caller to set the Public Key Callback for ECC Verification. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. sig is the signature to verify and sigSz denotes the length of the signature. hash is an input buffer containing the digest of the message and hashSz denotes the length in bytes of the hash. result is an output variable where the result of the verification should be stored, 1 for success and 0 for failure. keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccVerify().

Parameters:

• none No parameters.

See:

• wolfSSL_SetEccVerifyCtx
• wolfSSL_GetEccVerifyCtx

Return: none No returns.

Example

none

function wolfSSL_SetEccVerifyCtx

void wolfSSL_SetEccVerifyCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key Ecc Verification Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetEccVerifyCb
• wolfSSL_GetEccVerifyCtx

Return: none No returns.

Example

none

function wolfSSL_GetEccVerifyCtx

void * wolfSSL_GetEccVerifyCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key Ecc Verification Callback Context previously stored with wolfSSL_SetEccVerifyCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetEccVerifyCb
• wolfSSL_SetEccVerifyCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetRsaSignCb

void wolfSSL_CTX_SetRsaSignCb(
    WOLFSSL_CTX * ctx,
    CallbackRsaSign cb
)

Allows caller to set the Public Key Callback for RSA Signing. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to sign while inSz denotes the length of the input. out is the output buffer where the result of the signature should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning. keyDer is the RSA Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaSign().

Parameters:

• none No parameters.

See:

• wolfSSL_SetRsaSignCtx
• wolfSSL_GetRsaSignCtx

Return: none No returns.

Example

none

function wolfSSL_SetRsaSignCtx

void wolfSSL_SetRsaSignCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key RSA Signing Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaSignCb
• wolfSSL_GetRsaSignCtx

Return: none No Returns.

Example

none

function wolfSSL_GetRsaSignCtx

void * wolfSSL_GetRsaSignCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key RSA Signing Callback Context previously stored with wolfSSL_SetRsaSignCtx().

Parameters:

• none No parameters.
• none No parameters.

See:

• wolfSSL_CTX_SetRsaSignCb
• wolfSSL_SetRsaSignCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetRsaVerifyCb

void wolfSSL_CTX_SetRsaVerifyCb(
    WOLFSSL_CTX * ctx,
    CallbackRsaVerify cb
)

Allows caller to set the Public Key Callback for RSA Verification. The callback should return the number of plaintext bytes for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. sig is the signature to verify and sigSz denotes the length of the signature. out should be set to the beginning of the verification buffer after the decryption process and any padding. keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaVerify().

Parameters:

• none No parameters.

See:

• wolfSSL_SetRsaVerifyCtx
• wolfSSL_GetRsaVerifyCtx

Return: none No returns.

function wolfSSL_SetRsaVerifyCtx

void wolfSSL_SetRsaVerifyCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key RSA Verification Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaVerifyCb
• wolfSSL_GetRsaVerifyCtx

Return: none No returns.

Example

none

function wolfSSL_GetRsaVerifyCtx

void * wolfSSL_GetRsaVerifyCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key RSA Verification Callback Context previously stored with wolfSSL_SetRsaVerifyCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaVerifyCb
• wolfSSL_SetRsaVerifyCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetRsaEncCb

void wolfSSL_CTX_SetRsaEncCb(
    WOLFSSL_CTX * ctx,
    CallbackRsaEnc cb
)

Allows caller to set the Public Key Callback for RSA Public Encrypt. The callback should return 0 for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to encrypt while inSz denotes the length of the input. out is the output buffer where the result of the encryption should be stored. outSz is an input/output variable that specifies the size of the output buffer upon invocation and the actual size of the encryption should be stored there before returning. keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaEnc().

Parameters:

• none No parameters.

See:

• wolfSSL_SetRsaEncCtx
• wolfSSL_GetRsaEncCtx

Return: none No returns.

Examples

none

function wolfSSL_SetRsaEncCtx

void wolfSSL_SetRsaEncCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key RSA Public Encrypt Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaEncCb
• wolfSSL_GetRsaEncCtx

Return: none No returns.

Example

none

function wolfSSL_GetRsaEncCtx

void * wolfSSL_GetRsaEncCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key RSA Public Encrypt Callback Context previously stored with wolfSSL_SetRsaEncCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaEncCb
• wolfSSL_SetRsaEncCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetRsaDecCb

void wolfSSL_CTX_SetRsaDecCb(
    WOLFSSL_CTX * ctx,
    CallbackRsaDec cb
)

Allows caller to set the Public Key Callback for RSA Private Decrypt. The callback should return the number of plaintext bytes for success or < 0 for an error. The ssl and ctx pointers are available for the user’s convenience. in is the input buffer to decrypt and inSz denotes the length of the input. out should be set to the beginning of the decryption buffer after the decryption process and any padding. keyDer is the RSA Private key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaDec().

Parameters:

• none No parameters.

See:

• wolfSSL_SetRsaDecCtx
• wolfSSL_GetRsaDecCtx

Return: none No returns.

Example

none

function wolfSSL_SetRsaDecCtx

void wolfSSL_SetRsaDecCtx(
    WOLFSSL * ssl,
    void * ctx
)

Allows caller to set the Public Key RSA Private Decrypt Callback Context to ctx.

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaDecCb
• wolfSSL_GetRsaDecCtx

Return: none No returns.

Example

none

function wolfSSL_GetRsaDecCtx

void * wolfSSL_GetRsaDecCtx(
    WOLFSSL * ssl
)

Allows caller to retrieve the Public Key RSA Private Decrypt Callback Context previously stored with wolfSSL_SetRsaDecCtx().

Parameters:

• none No parameters.

See:

• wolfSSL_CTX_SetRsaDecCb
• wolfSSL_SetRsaDecCtx

Return:

• pointer If successful the call will return a valid pointer to the context.
• NULL will be returned for a blank context.

Example

none

function wolfSSL_CTX_SetCACb

void wolfSSL_CTX_SetCACb(
    WOLFSSL_CTX * ctx,
    CallbackCACache cb
)

This function registers a callback with the SSL context (WOLFSSL_CTX) to be called when a new CA certificate is loaded into wolfSSL. The callback is given a buffer with the DER-encoded certificate.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• callback function to be registered as the CA callback for the wolfSSL context, ctx. The signature of this function must follow that as shown above in the Synopsis section.

See: wolfSSL_CTX_load_verify_locations

Return: none No return.

Example

WOLFSSL_CTX* ctx = 0;

// CA callback prototype
int MyCACallback(unsigned char *der, int sz, int type);

// Register the custom CA callback with the SSL context
wolfSSL_CTX_SetCACb(ctx, MyCACallback);

int MyCACallback(unsigned char* der, int sz, int type)
{
    // custom CA callback function, DER-encoded cert
    // located in “der” of size “sz” with type “type”
}

function wolfSSL_CertManagerNew_ex

WOLFSSL_CERT_MANAGER * wolfSSL_CertManagerNew_ex(
    void * heap
)

Allocates and initializes a new Certificate Manager context. This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status.

Parameters:

• none No parameters.

See: wolfSSL_CertManagerFree

Return:

• WOLFSSL_CERT_MANAGER If successful the call will return a valid WOLFSSL_CERT_MANAGER pointer.
• NULL will be returned for an error state.

function wolfSSL_CertManagerNew

WOLFSSL_CERT_MANAGER * wolfSSL_CertManagerNew(
    void 
)

Allocates and initializes a new Certificate Manager context. This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status.

Parameters:

• none No parameters.

See: wolfSSL_CertManagerFree

Return:

• WOLFSSL_CERT_MANAGER If successful the call will return a valid WOLFSSL_CERT_MANAGER pointer.
• NULL will be returned for an error state.

Example

#import <wolfssl/ssl.h>

WOLFSSL_CERT_MANAGER* cm;
cm = wolfSSL_CertManagerNew();
if (cm == NULL) {
// error creating new cert manager
}

function wolfSSL_CertManagerFree

void wolfSSL_CertManagerFree(
    WOLFSSL_CERT_MANAGER * 
)

Frees all resources associated with the Certificate Manager context. Call this when you no longer need to use the Certificate Manager.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See: wolfSSL_CertManagerNew

Return: none

Example

#include <wolfssl/ssl.h>

WOLFSSL_CERT_MANAGER* cm;
...
wolfSSL_CertManagerFree(cm);

function wolfSSL_CertManagerLoadCA

int wolfSSL_CertManagerLoadCA(
    WOLFSSL_CERT_MANAGER * cm,
    const char * f,
    const char * d
)

Specifies the locations for CA certificate loading into the manager context. The PEM certificate CAfile may contain several trusted CA certificates. If CApath is not NULL it specifies a directory containing CA certificates in PEM format.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• file pointer to the name of the file containing CA certificates to load.
• path pointer to the name of a directory path containing CA c ertificates to load. The NULL pointer may be used if no certificate directory is desired.

See: wolfSSL_CertManagerVerify

Return:

• SSL_SUCCESS If successful the call will return.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.
• SSL_FATAL_ERROR - will be returned upon failure.

Example

#include <wolfssl/ssl.h>

int ret = 0;
WOLFSSL_CERT_MANAGER* cm;
...
ret = wolfSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0);
if (ret != SSL_SUCCESS) {
// error loading CA certs into cert manager
}

function wolfSSL_CertManagerLoadCABuffer

int wolfSSL_CertManagerLoadCABuffer(
    WOLFSSL_CERT_MANAGER * cm,
    const unsigned char * in,
    long sz,
    int format
)

Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and returning that result using a temporary cm so as not to lose the information in the cm passed into the function.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• in buffer for cert information.
• sz length of the buffer.
• format certificate format, either PEM or DER.

See:

• wolfSSL_CTX_load_verify_buffer
• ProcessChainBuffer
• ProcessBuffer
• cm_pick_method

Return:

• SSL_FATAL_ERROR is returned if the WOLFSSL_CERT_MANAGER struct is NULL or if wolfSSL_CTX_new() returns NULL.
• SSL_SUCCESS is returned for a successful execution.

Example

WOLFSSL_CERT_MANAGER* cm = (WOLFSSL_CERT_MANAGER*)vp;
…
const unsigned char* in;
long sz;
int format;
…
if(wolfSSL_CertManagerLoadCABuffer(vp, sz, format) != SSL_SUCCESS){
    Error returned. Failure case code block.
}

function wolfSSL_CertManagerUnloadCAs

int wolfSSL_CertManagerUnloadCAs(
    WOLFSSL_CERT_MANAGER * cm
)

This function unloads the CA signer list.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See: UnlockMutex

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
• BAD_MUTEX_E returned if there was a mutex error.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
...
if(wolfSSL_CertManagerUnloadCAs(cm) != SSL_SUCCESS){
    Failure case.
}

function wolfSSL_CertManagerUnloadIntermediateCerts

int wolfSSL_CertManagerUnloadIntermediateCerts(
    WOLFSSL_CERT_MANAGER * cm
)

This function unloads intermediate certificates add to the CA signer list.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See: UnlockMutex

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
• BAD_MUTEX_E returned if there was a mutex error.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
...
if(wolfSSL_CertManagerUnloadIntermediateCerts(cm) != SSL_SUCCESS){
    Failure case.
}

function wolfSSL_CertManagerUnload_trust_peers

int wolfSSL_CertManagerUnload_trust_peers(
    WOLFSSL_CERT_MANAGER * cm
)

The function will free the Trusted Peer linked list and unlocks the trusted peer list.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See: UnLockMutex

Return:

• SSL_SUCCESS if the function completed normally.
• BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.
• BAD_MUTEX_E mutex error if tpLock, a member of the WOLFSSL_CERT_MANAGER struct, is 0 (nill).

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
...
if(wolfSSL_CertManagerUnload_trust_peers(cm) != SSL_SUCCESS){
    The function did not execute successfully.
}

function wolfSSL_CertManagerVerify

int wolfSSL_CertManagerVerify(
    WOLFSSL_CERT_MANAGER * cm,
    const char * f,
    int format
)

Specifies the certificate to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• fname pointer to the name of the file containing the certificates to verify.
• format format of the certificate to verify - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CertManagerLoadCA
• wolfSSL_CertManagerVerifyBuffer

Return:

• SSL_SUCCESS If successful.
• ASN_SIG_CONFIRM_E will be returned if the signature could not be verified.
• ASN_SIG_OID_E will be returned if the signature type is not supported.
• CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked.
• CRL_MISSING is an error that is returned if a current issuer CRL is not available.
• ASN_BEFORE_DATE_E will be returned if the current date is before the before date.
• ASN_AFTER_DATE_E will be returned if the current date is after the after date.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.

Example

int ret = 0;
WOLFSSL_CERT_MANAGER* cm;
...

ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”,
SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    error verifying certificate
}

function wolfSSL_CertManagerVerifyBuffer

int wolfSSL_CertManagerVerifyBuffer(
    WOLFSSL_CERT_MANAGER * cm,
    const unsigned char * buff,
    long sz,
    int format
)

Specifies the certificate buffer to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• buff buffer containing the certificates to verify.
• sz size of the buffer, buf.
• format format of the certificate to verify, located in buf - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

See:

• wolfSSL_CertManagerLoadCA
• wolfSSL_CertManagerVerify

Return:

• SSL_SUCCESS If successful.
• ASN_SIG_CONFIRM_E will be returned if the signature could not be verified.
• ASN_SIG_OID_E will be returned if the signature type is not supported.
• CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked.
• CRL_MISSING is an error that is returned if a current issuer CRL is not available.
• ASN_BEFORE_DATE_E will be returned if the current date is before the before date.
• ASN_AFTER_DATE_E will be returned if the current date is after the after date.
• SSL_BAD_FILETYPE will be returned if the file is the wrong format.
• SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.
• MEMORY_E will be returned if an out of memory condition occurs.
• ASN_INPUT_E will be returned if Base16 decoding fails on the file.
• BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.

Example

#include <wolfssl/ssl.h>

int ret = 0;
int sz = 0;
WOLFSSL_CERT_MANAGER* cm;
byte certBuff[...];
...

ret = wolfSSL_CertManagerVerifyBuffer(cm, certBuff, sz, SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    error verifying certificate
}

function wolfSSL_CertManagerSetVerify

void wolfSSL_CertManagerSetVerify(
    WOLFSSL_CERT_MANAGER * cm,
    VerifyCallback vc
)

The function sets the verifyCallback function in the Certificate Manager. If present, it will be called for each cert loaded. If there is a verification error, the verify callback can be used to over-ride the error.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• vc a VerifyCallback function pointer to the callback routine

See: wolfSSL_CertManagerVerify

Return: none No return.

Example

#include <wolfssl/ssl.h>

int myVerify(int preverify, WOLFSSL_X509_STORE_CTX* store)
{ // do custom verification of certificate }

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
...
wolfSSL_CertManagerSetVerify(cm, myVerify);

function wolfSSL_CertManagerCheckCRL

int wolfSSL_CertManagerCheckCRL(
    WOLFSSL_CERT_MANAGER * cm,
    unsigned char * der,
    int sz
)

Check CRL if the option is enabled and compares the cert to the CRL list.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER struct.
• der pointer to a DER formatted certificate.
• sz size of the certificate.

See:

• CheckCertCRL
• ParseCertRelative
• wolfSSL_CertManagerSetCRL_CB
• InitDecodedCert

Return:

• SSL_SUCCESS returns if the function returned as expected. If the crlEnabled member of the WOLFSSL_CERT_MANAGER struct is turned on.
• MEMORY_E returns if the allocated memory failed.
• BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.

Example

WOLFSSL_CERT_MANAGER* cm;
byte* der;
int sz; // size of der
...
if(wolfSSL_CertManagerCheckCRL(cm, der, sz) != SSL_SUCCESS){
    // Error returned. Deal with failure case.
}

function wolfSSL_CertManagerEnableCRL

int wolfSSL_CertManagerEnableCRL(
    WOLFSSL_CERT_MANAGER * cm,
    int options
)

Turns on Certificate Revocation List checking when verifying certificates with the Certificate Manager. By default, CRL checking is off. options include WOLFSSL_CRL_CHECKALL which performs CRL checking on each certificate in the chain versus the Leaf certificate only which is the default.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• options options to use when enabling the Certification Manager, cm.

See: wolfSSL_CertManagerDisableCRL

Return:

• SSL_SUCCESS If successful the call will return.
• NOT_COMPILED_IN will be returned if wolfSSL was not built with CRL enabled.
• MEMORY_E will be returned if an out of memory condition occurs.
• BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.
• SSL_FAILURE will be returned if the CRL context cannot be initialized properly.

Example

#include <wolfssl/ssl.h>

int ret = 0;
WOLFSSL_CERT_MANAGER* cm;
...

ret = wolfSSL_CertManagerEnableCRL(cm, 0);
if (ret != SSL_SUCCESS) {
    error enabling cert manager
}

...

function wolfSSL_CertManagerDisableCRL

int wolfSSL_CertManagerDisableCRL(
    WOLFSSL_CERT_MANAGER * 
)

Turns off Certificate Revocation List checking when verifying certificates with the Certificate Manager. By default, CRL checking is off. You can use this function to temporarily or permanently disable CRL checking with this Certificate Manager context that previously had CRL checking enabled.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See: wolfSSL_CertManagerEnableCRL

Return:

• SSL_SUCCESS If successful the call will return.
• BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.

Example

#include <wolfssl/ssl.h>

int ret = 0;
WOLFSSL_CERT_MANAGER* cm;
...
ret = wolfSSL_CertManagerDisableCRL(cm);
if (ret != SSL_SUCCESS) {
    error disabling cert manager
}
...

function wolfSSL_CertManagerLoadCRL

int wolfSSL_CertManagerLoadCRL(
    WOLFSSL_CERT_MANAGER * cm,
    const char * path,
    int type,
    int monitor
)

Error checks and passes through to LoadCRL() in order to load the cert into the CRL for revocation checking. An updated CRL can be loaded by first calling wolfSSL_CertManagerFreeCRL, then loading the new CRL.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• path a constant char pointer holding the CRL path.
• type type of certificate to be loaded.
• monitor requests monitoring in LoadCRL().

See:

• wolfSSL_CertManagerEnableCRL
• wolfSSL_LoadCRL
• wolfSSL_CertManagerFreeCRL

Return:

• SSL_SUCCESS if there is no error in wolfSSL_CertManagerLoadCRL and if LoadCRL returns successfully.
• BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER struct is NULL.
• SSL_FATAL_ERROR if wolfSSL_CertManagerEnableCRL returns anything other than SSL_SUCCESS.
• BAD_PATH_ERROR if the path is NULL.
• MEMORY_E if LoadCRL fails to allocate heap memory.

Example

#include <wolfssl/ssl.h>

int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type,
int monitor);
…
wolfSSL_CertManagerLoadCRL(SSL_CM(ssl), path, type, monitor);

function wolfSSL_CertManagerLoadCRLBuffer

int wolfSSL_CertManagerLoadCRLBuffer(
    WOLFSSL_CERT_MANAGER * cm,
    const unsigned char * buff,
    long sz,
    int type
)

The function loads the CRL file by calling BufferLoadCRL.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure.
• buff a constant byte type and is the buffer.
• sz a long int representing the size of the buffer.
• type a long integer that holds the certificate type.

See:

• BufferLoadCRL
• wolfSSL_CertManagerEnableCRL

Return:

• SSL_SUCCESS returned if the function completed without errors.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
• SSL_FATAL_ERROR returned if there is an error associated with the WOLFSSL_CERT_MANAGER.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CERT_MANAGER* cm;
const unsigned char* buff;
long sz; size of buffer
int type;  cert type
...
int ret = wolfSSL_CertManagerLoadCRLBuffer(cm, buff, sz, type);
if(ret == SSL_SUCCESS){
return ret;
} else {
    Failure case.
}

function wolfSSL_CertManagerSetCRL_Cb

int wolfSSL_CertManagerSetCRL_Cb(
    WOLFSSL_CERT_MANAGER * cm,
    CbMissingCRL cb
)

This function sets the CRL Certificate Manager callback. If HAVE_CRL is defined and a matching CRL record is not found then the cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This allows you to externally retrieve the CRL and load it.

Parameters:

• cm the WOLFSSL_CERT_MANAGER structure holding the information for the certificate.
• cb a function pointer to (*CbMissingCRL) that is set to the cbMissingCRL member of the WOLFSSL_CERT_MANAGER.

See:

• CbMissingCRL
• wolfSSL_SetCRL_Cb

Return:

• SSL_SUCCESS returned upon successful execution of the function and subroutines.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
…
void cb(const char* url){
    Function body.
}
…
CbMissingCRL cb = CbMissingCRL;
…
if(ctx){
    return wolfSSL_CertManagerSetCRL_Cb(SSL_CM(ssl), cb);
}

function wolfSSL_CertManagerSetCRLUpdate_Cb

int wolfSSL_CertManagerSetCRLUpdate_Cb(
    WOLFSSL_CERT_MANAGER * cm,
    CbUpdateCRL cb
)

This function sets the CRL Update callback. If HAVE_CRL and HAVE_CRL_UPDATE_CB is defined , and an entry with the same issuer and a lower CRL number exists when a CRL is added, then the CbUpdateCRL is called with the details of the existing entry and the new one replacing it.

Parameters:

• cm the WOLFSSL_CERT_MANAGER structure holding the information for the certificate.
• cb a function pointer to (CbUpdateCRL) that is set to the cbUpdateCRL member of the WOLFSSL_CERT_MANAGER. Signature requirement: void (CbUpdateCRL)(CrlInfo old, CrlInfo new);

See: CbUpdateCRL

Return:

• SSL_SUCCESS returned upon successful execution of the function and subroutines.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
…
void cb(CrlInfo *old, CrlInfo *new){
    Function body.
}
…
CbUpdateCRL cb = CbUpdateCRL;
…
if(ctx){
    return wolfSSL_CertManagerSetCRLUpdate_Cb(SSL_CM(ssl), cb);
}

function wolfSSL_CertManagerGetCRLInfo

int wolfSSL_CertManagerGetCRLInfo(
    WOLFSSL_CERT_MANAGER * cm,
    CrlInfo * info,
    const byte * buff,
    long sz,
    int type
)

This function yields a structure with parsed CRL information from an encoded CRL buffer.

Parameters:

• cm the WOLFSSL_CERT_MANAGER structure..
• info pointer to caller managed CrlInfo structure that will receive the CRL information.
• buff input buffer containing encoded CRL.
• sz the length in bytes of the input CRL data in buff.
• type WOLFSSL_FILETYPE_PEM or WOLFSSL_FILETYPE_DER
• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().

See:

• CbUpdateCRL
• wolfSSL_SetCRL_Cb
• wolfSSL_CertManagerLoadCRL

Return:

• SSL_SUCCESS returned upon successful execution of the function and subroutines.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
• SSL_SUCCESS returned upon successful execution of the function and subroutines.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.

Example

#include <wolfssl/ssl.h>

CrlInfo info;
WOLFSSL_CERT_MANAGER* cm = NULL;

cm = wolfSSL_CertManagerNew();

// Read crl data from file into buffer

wolfSSL_CertManagerGetCRLInfo(cm, &info, crlData, crlDataLen,
                              WOLFSSL_FILETYPE_PEM);

This function frees the CRL stored in the Cert Manager. An application can update the CRL by calling wolfSSL_CertManagerFreeCRL and then loading the new CRL.

Example

#include <wolfssl/ssl.h>

const char* crl1     = "./certs/crl/crl.pem";
WOLFSSL_CERT_MANAGER* cm = NULL;

cm = wolfSSL_CertManagerNew();
wolfSSL_CertManagerLoadCRL(cm, crl1, WOLFSSL_FILETYPE_PEM, 0);
…
wolfSSL_CertManagerFreeCRL(cm);

function wolfSSL_CertManagerCheckOCSP

int wolfSSL_CertManagerCheckOCSP(
    WOLFSSL_CERT_MANAGER * cm,
    unsigned char * der,
    int sz
)

The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled to signify that the OCSP check option is enabled.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• der a byte pointer to the certificate.
• sz an int type representing the size of the DER cert.

See:

• ParseCertRelative
• CheckCertOCSP

Return:

• SSL_SUCCESS returned on successful execution of the function. The ocspEnabled member of the WOLFSSL_CERT_MANAGER is enabled.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL or if an argument value that is not allowed is passed to a subroutine.
• MEMORY_E returned if there is an error allocating memory within this function or a subroutine.

Example

#import <wolfssl/ssl.h>

WOLFSSL* ssl = wolfSSL_new(ctx);
byte* der;
int sz; size of der
...
if(wolfSSL_CertManagerCheckOCSP(cm, der, sz) != SSL_SUCCESS){
 Failure case.
}

function wolfSSL_CertManagerEnableOCSP

int wolfSSL_CertManagerEnableOCSP(
    WOLFSSL_CERT_MANAGER * cm,
    int options
)

Turns on OCSP if it’s turned off and if compiled with the set option available.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew().
• options used to set values in WOLFSSL_CERT_MANAGER struct.

See: wolfSSL_CertManagerNew

Return:

• SSL_SUCCESS returned if the function call is successful.
• BAD_FUNC_ARG if cm struct is NULL.
• MEMORY_E if WOLFSSL_OCSP struct value is NULL.
• SSL_FAILURE initialization of WOLFSSL_OCSP struct fails to initialize.
• NOT_COMPILED_IN build not compiled with correct feature enabled.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
int options;
…
if(wolfSSL_CertManagerEnableOCSP(SSL_CM(ssl), options) != SSL_SUCCESS){
    Failure case.
}

function wolfSSL_CertManagerDisableOCSP

int wolfSSL_CertManagerDisableOCSP(
    WOLFSSL_CERT_MANAGER * 
)

Disables OCSP certificate revocation.

Parameters:

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

See: wolfSSL_DisableCRL

Return:

• SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
• BAD_FUNC_ARG the WOLFSSL structure was NULL.

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_CertManagerDisableOCSP(ssl) != SSL_SUCCESS){
    Fail case.
}

function wolfSSL_CertManagerSetOCSPOverrideURL

int wolfSSL_CertManagerSetOCSPOverrideURL(
    WOLFSSL_CERT_MANAGER * cm,
    const char * url
)

The function copies the url to the ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure.

Parameters:

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

See:

• ocspOverrideURL
• wolfSSL_SetOCSP_OverrideURL

Return:

• SSL_SUCCESS the function was able to execute as expected.
• BAD_FUNC_ARG the WOLFSSL_CERT_MANAGER struct is NULL.
• MEMEORY_E Memory was not able to be allocated for the ocspOverrideURL member of the certificate manager.

Example

#include <wolfssl/ssl.h>
WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
const char* url;
…
int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url)
…
if(wolfSSL_CertManagerSetOCSPOverrideURL(SSL_CM(ssl), url) != SSL_SUCCESS){
    Failure case.
}

function wolfSSL_CertManagerSetOCSP_Cb

int wolfSSL_CertManagerSetOCSP_Cb(
    WOLFSSL_CERT_MANAGER * cm,
    CbOCSPIO ioCb,
    CbOCSPRespFree respFreeCb,
    void * ioCbCtx
)

The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure.
• ioCb a function pointer of type CbOCSPIO.
• respFreeCb - a function pointer of type CbOCSPRespFree.
• ioCbCtx - a void pointer variable to the I/O callback user registered context.

See:

• wolfSSL_CertManagerSetOCSPOverrideURL
• wolfSSL_CertManagerCheckOCSP
• wolfSSL_CertManagerEnableOCSPStapling
• wolfSSL_EnableOCSP
• wolfSSL_DisableOCSP
• wolfSSL_SetOCSP_Cb

Return:

• SSL_SUCCESS returned on successful execution. The arguments are saved in the WOLFSSL_CERT_MANAGER structure.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.

Example

#include <wolfssl/ssl.h>

wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb,
CbOCSPRespFree respFreeCb, void* ioCbCtx){
…
return wolfSSL_CertManagerSetOCSP_Cb(SSL_CM(ssl), ioCb, respFreeCb, ioCbCtx);

function wolfSSL_CertManagerEnableOCSPStapling

int wolfSSL_CertManagerEnableOCSPStapling(
    WOLFSSL_CERT_MANAGER * cm
)

This function turns on OCSP stapling if it is not turned on as well as set the options.

Parameters:

• cm a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the WOLFSSL_CTX structure.

See: wolfSSL_CTX_EnableOCSPStapling

Return:

• SSL_SUCCESS returned if there were no errors and the function executed successfully.
• BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL or otherwise if there was a unpermitted argument value passed to a subroutine.
• MEMORY_E returned if there was an issue allocating memory.
• SSL_FAILURE returned if the initialization of the OCSP structure failed.
• NOT_COMPILED_IN returned if wolfSSL was not compiled with HAVE_CERTIFICATE_STATUS_REQUEST option.

Example

int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx){
…
return wolfSSL_CertManagerEnableOCSPStapling(ctx->cm);

function wolfSSL_EnableCRL

int wolfSSL_EnableCRL(
    WOLFSSL * ssl,
    int options
)

Enables CRL certificate revocation.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• options an integer that is used to determine the setting of crlCheckAll member of the WOLFSSL_CERT_MANAGER structure.

See:

• wolfSSL_CertManagerEnableCRL
• InitCRL

Return:

• SSL_SUCCESS the function and subroutines returned with no errors.
• BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
• MEMORY_E returned if the allocation of memory failed.
• SSL_FAILURE returned if the InitCRL function does not return successfully.
• NOT_COMPILED_IN HAVE_CRL was not enabled during the compiling.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
…
if (wolfSSL_EnableCRL(ssl, WOLFSSL_CRL_CHECKALL) != SSL_SUCCESS){
    // Failure case. SSL_SUCCESS was not returned by this function or
a subroutine
}

function wolfSSL_DisableCRL

int wolfSSL_DisableCRL(
    WOLFSSL * ssl
)

Disables CRL certificate revocation.

Parameters:

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

See:

• wolfSSL_CertManagerDisableCRL
• wolfSSL_CertManagerDisableOCSP

Return:

• SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
• BAD_FUNC_ARG the WOLFSSL structure was NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_DisableCRL(ssl) != SSL_SUCCESS){
    // Failure case
}

function wolfSSL_LoadCRL

int wolfSSL_LoadCRL(
    WOLFSSL * ssl,
    const char * path,
    int type,
    int monitor
)

A wrapper function that ends up calling LoadCRL to load the certificate for revocation checking.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• path a constant character pointer that holds the path to the crl file.
• type an integer representing the type of certificate.
• monitor an integer variable used to verify the monitor path if requested.

See:

• wolfSSL_CertManagerLoadCRL
• wolfSSL_CertManagerEnableCRL
• LoadCRL

Return:

• WOLFSSL_SUCCESS returned if the function and all of the subroutines executed without error.
• SSL_FATAL_ERROR returned if one of the subroutines does not return successfully.
• BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER or the WOLFSSL structure are NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
const char* crlPemDir;
…
if(wolfSSL_LoadCRL(ssl, crlPemDir, SSL_FILETYPE_PEM, 0) != SSL_SUCCESS){
    // Failure case. Did not return SSL_SUCCESS.
}

function wolfSSL_SetCRL_Cb

int wolfSSL_SetCRL_Cb(
    WOLFSSL * ssl,
    CbMissingCRL cb
)

Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer to CbMissingCRL.

See:

• CbMissingCRL
• wolfSSL_CertManagerSetCRL_Cb

Return:

• SSL_SUCCESS returned if the function or subroutine executes without error. The cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set.
• BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
void cb(const char* url) // required signature
{
    // Function body
}
…
int crlCb = wolfSSL_SetCRL_Cb(ssl, cb);
if(crlCb != SSL_SUCCESS){
    // The callback was not set properly
}

function wolfSSL_EnableOCSP

int wolfSSL_EnableOCSP(
    WOLFSSL * ssl,
    int options
)

This function enables OCSP certificate verification. The value of options if formed by or’ing one or more of the following options: WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in certificates. The override URL is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• options an integer type passed to wolfSSL_CertMangerENableOCSP() used for settings check.

See: wolfSSL_CertManagerEnableOCSP

Return:

• SSL_SUCCESS returned if the function and subroutines executes without errors.
• BAD_FUNC_ARG returned if an argument in this function or any subroutine receives an invalid argument value.
• MEMORY_E returned if there was an error allocating memory for a structure or other variable.
• NOT_COMPILED_IN returned if wolfSSL was not compiled with the HAVE_OCSP option.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int options; // initialize to option constant
…
int ret = wolfSSL_EnableOCSP(ssl, options);
if(ret != SSL_SUCCESS){
    // OCSP is not enabled
}

function wolfSSL_DisableOCSP

int wolfSSL_DisableOCSP(
    WOLFSSL * 
)

Disables the OCSP certificate revocation option.

Parameters:

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

See: wolfSSL_CertManagerDisableOCSP

Return:

• SSL_SUCCESS returned if the function and its subroutine return with no errors. The ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was successfully set.
• BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
…
if(wolfSSL_DisableOCSP(ssl) != SSL_SUCCESS){
    // Returned with an error. Failure case in this block.
}

function wolfSSL_SetOCSP_OverrideURL

int wolfSSL_SetOCSP_OverrideURL(
    WOLFSSL * ssl,
    const char * url
)

This function sets the ocspOverrideURL member in the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• url a constant char pointer to the url that will be stored in the ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure.

See: wolfSSL_CertManagerSetOCSPOverrideURL

Return:

• SSL_SUCCESS returned on successful execution of the function.
• BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if a unpermitted argument was passed to a subroutine.
• MEMORY_E returned if there was an error allocating memory in the subroutine.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
char url[URLSZ];
...
if(wolfSSL_SetOCSP_OverrideURL(ssl, url)){
    // The override url is set to the new value
}

function wolfSSL_SetOCSP_Cb

int wolfSSL_SetOCSP_Cb(
    WOLFSSL * ssl,
    CbOCSPIO ioCb,
    CbOCSPRespFree respFreeCb,
    void * ioCbCtx
)

This function sets the OCSP callback in the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• ioCb a function pointer to type CbOCSPIO.
• respFreeCb a function pointer to type CbOCSPRespFree which is the call to free the response memory.
• ioCbCtx a void pointer that will be held in the ocspIOCtx member of the CM.

See:

• wolfSSL_CertManagerSetOCSP_Cb
• CbOCSPIO
• CbOCSPRespFree

Return:

• SSL_SUCCESS returned if the function executes without error. The ocspIOCb, ocspRespFreeCb, and ocspIOCtx members of the CM are set.
• BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER structures are NULL.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
…
int OCSPIO_CB(void* , const char*, int , unsigned char* , int,
unsigned char**){  // must have this signature
// Function Body
}
…
void OCSPRespFree_CB(void* , unsigned char* ){ // must have this signature
    // function body
}
…
void* ioCbCtx;
CbOCSPRespFree CB_OCSPRespFree;

if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB( pass args ), CB_OCSPRespFree,
            ioCbCtx) != SSL_SUCCESS){
    // Callback not set
}

function wolfSSL_CTX_EnableCRL

int wolfSSL_CTX_EnableCRL(
    WOLFSSL_CTX * ctx,
    int options
)

Enables CRL certificate verification through the CTX.

Parameters:

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

See:

• wolfSSL_CertManagerEnableCRL
• InitCRL
• wolfSSL_CTX_DisableCRL

Return:

• SSL_SUCCESS returned if this function and it’s subroutines execute without errors.
• BAD_FUNC_ARG returned if the CTX struct is NULL or there was otherwise an invalid argument passed in a subroutine.
• MEMORY_E returned if there was an error allocating memory during execution of the function.
• SSL_FAILURE returned if the crl member of the WOLFSSL_CERT_MANAGER fails to initialize correctly.
• NOT_COMPILED_IN wolfSSL was not compiled with the HAVE_CRL option.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_CTX_EnableCRL(ssl->ctx, options) != SSL_SUCCESS){
    // The function failed
}

function wolfSSL_CTX_DisableCRL

int wolfSSL_CTX_DisableCRL(
    WOLFSSL_CTX * ctx
)

This function disables CRL verification in the CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See: wolfSSL_CertManagerDisableCRL

Return:

• SSL_SUCCESS returned if the function executes without error. The crlEnabled member of the WOLFSSL_CERT_MANAGER struct is set to 0.
• BAD_FUNC_ARG returned if either the CTX struct or the CM struct has a NULL value.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_CTX_DisableCRL(ssl->ctx) != SSL_SUCCESS){
    // Failure case.
}

function wolfSSL_CTX_LoadCRL

int wolfSSL_CTX_LoadCRL(
    WOLFSSL_CTX * ctx,
    const char * path,
    int type,
    int monitor
)

This function loads CRL into the WOLFSSL_CTX structure through wolfSSL_CertManagerLoadCRL().

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• path the path to the certificate.
• type an integer variable holding the type of certificate.
• monitor an integer variable used to determine if the monitor path is requested.

See:

• wolfSSL_CertManagerLoadCRL
• LoadCRL

Return:

• SSL_SUCCESS - returned if the function and its subroutines execute without error.
• BAD_FUNC_ARG - returned if this function or any subroutines are passed NULL structures.
• BAD_PATH_ERROR - returned if the path variable opens as NULL.
• MEMORY_E - returned if an allocation of memory failed.

Example

WOLFSSL_CTX* ctx;
const char* path;
…
return wolfSSL_CTX_LoadCRL(ctx, path, SSL_FILETYPE_PEM, 0);

function wolfSSL_CTX_SetCRL_Cb

int wolfSSL_CTX_SetCRL_Cb(
    WOLFSSL_CTX * ctx,
    CbMissingCRL cb
)

This function will set the callback argument to the cbMissingCRL member of the WOLFSSL_CERT_MANAGER structure by calling wolfSSL_CertManagerSetCRL_Cb.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• cb a pointer to a callback function of type CbMissingCRL. Signature requirement: void (CbMissingCRL)(const char url);

See:

• wolfSSL_CertManagerSetCRL_Cb
• CbMissingCRL

Return:

• SSL_SUCCESS returned for a successful execution. The WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully set to cb.
• BAD_FUNC_ARG returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER are NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
…
void cb(const char* url) // Required signature
{
    // Function body
}
…
if (wolfSSL_CTX_SetCRL_Cb(ctx, cb) != SSL_SUCCESS){
    // Failure case, cb was not set correctly.
}

function wolfSSL_CTX_EnableOCSP

int wolfSSL_CTX_EnableOCSP(
    WOLFSSL_CTX * ctx,
    int options
)

This function sets options to configure behavior of OCSP functionality in wolfSSL. The value of options if formed by or’ing one or more of the following options: WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in certificates. The override URL is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• options value used to set the OCSP options.

See:

• wolfSSL_CertManagerEnableOCSP
• wolfSSL_EnableOCSP

Return:

• SSL_SUCCESS is returned upon success.
• SSL_FAILURE is returned upon failure.
• NOT_COMPILED_IN is returned when this function has been called, but OCSP support was not enabled when wolfSSL was compiled.

This function only sets the OCSP options when wolfSSL has been compiled with OCSP support (–enable-ocsp, #define HAVE_OCSP).

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
int options; // initialize to option constant
…
int ret = wolfSSL_CTX_EnableOCSP(ctx, options);
if(ret != SSL_SUCCESS){
    // OCSP is not enabled
}

function wolfSSL_CTX_DisableOCSP

int wolfSSL_CTX_DisableOCSP(
    WOLFSSL_CTX * 
)

This function disables OCSP certificate revocation checking by affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_DisableOCSP
• wolfSSL_CertManagerDisableOCSP

Return:

• SSL_SUCCESS returned if the function executes without error. The ocspEnabled member of the CM has been disabled.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(!wolfSSL_CTX_DisableOCSP(ssl->ctx)){
    // OCSP is not disabled
}

function wolfSSL_CTX_SetOCSP_OverrideURL

int wolfSSL_CTX_SetOCSP_OverrideURL(
    WOLFSSL_CTX * ctx,
    const char * url
)

This function manually sets the URL for OCSP to use. By default, OCSP will use the URL found in the individual certificate unless the WOLFSSL_OCSP_URL_OVERRIDE option is set using the wolfSSL_CTX_EnableOCSP.

Parameters:

• ctx pointer to the SSL context, created with wolfSSL_CTX_new().
• url pointer to the OCSP URL for wolfSSL to use.

See: wolfSSL_CTX_OCSP_set_options

Return:

• SSL_SUCCESS is returned upon success.
• SSL_FAILURE is returned upon failure.
• NOT_COMPILED_IN is returned when this function has been called, but OCSP support was not enabled when wolfSSL was compiled.

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_OCSP_set_override_url(ctx, “custom-url-here”);

function wolfSSL_CTX_SetOCSP_Cb

int wolfSSL_CTX_SetOCSP_Cb(
    WOLFSSL_CTX * ctx,
    CbOCSPIO ioCb,
    CbOCSPRespFree respFreeCb,
    void * ioCbCtx
)

Sets the callback for the OCSP in the WOLFSSL_CTX structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• ioCb a CbOCSPIO type that is a function pointer.
• respFreeCb a CbOCSPRespFree type that is a function pointer.
• ioCbCtx a void pointer that will be held in the WOLFSSL_CERT_MANAGER.

See:

• wolfSSL_CertManagerSetOCSP_Cb
• CbOCSPIO
• CbOCSPRespFree

Return:

• SSL_SUCCESS returned if the function executed successfully. The ocspIOCb, ocspRespFreeCb, and ocspIOCtx members in the CM were successfully set.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX or WOLFSSL_CERT_MANAGER structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
…
CbOCSPIO ocspIOCb;
CbOCSPRespFree ocspRespFreeCb;
…
void* ioCbCtx;

int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb,
ocspRespFreeCb, ioCbCtx);

if(isSetOCSP != SSL_SUCCESS){
    // The function did not return successfully.
}

function wolfSSL_CTX_EnableOCSPStapling

int wolfSSL_CTX_EnableOCSPStapling(
    WOLFSSL_CTX * 
)

This function enables OCSP stapling by calling wolfSSL_CertManagerEnableOCSPStapling().

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

See:

• wolfSSL_CertManagerEnableOCSPStapling
• InitOCSP

Return:

• SSL_SUCCESS returned if there were no errors and the function executed successfully.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or otherwise if there was a unpermitted argument value passed to a subroutine.
• MEMORY_E returned if there was an issue allocating memory.
• SSL_FAILURE returned if the initialization of the OCSP structure failed.
• NOT_COMPILED_IN returned if wolfSSL was not compiled with HAVE_CERTIFICATE_STATUS_REQUEST option.

Example

WOLFSSL* ssl = WOLFSSL_new();
ssl->method.version; // set to desired protocol
...
if(!wolfSSL_CTX_EnableOCSPStapling(ssl->ctx)){
    // OCSP stapling is not enabled
}

function wolfSSL_KeepArrays

void wolfSSL_KeepArrays(
    WOLFSSL * 
)

Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. Calling this function before the handshake begins will prevent wolfSSL from freeing temporary arrays. Temporary arrays may be needed for things such as wolfSSL_get_keys() or PSK hints. When the user is done with temporary arrays, either wolfSSL_FreeArrays() may be called to free the resources immediately, or alternatively the resources will be freed when the associated SSL object is freed.

Parameters:

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

See: wolfSSL_FreeArrays

Return: none No return.

Example

WOLFSSL* ssl;
...
wolfSSL_KeepArrays(ssl);

function wolfSSL_FreeArrays

void wolfSSL_FreeArrays(
    WOLFSSL * 
)

Normally, at the end of the SSL handshake, wolfSSL frees temporary arrays. If wolfSSL_KeepArrays() has been called before the handshake, wolfSSL will not free temporary arrays. This function explicitly frees temporary arrays and should be called when the user is done with temporary arrays and does not want to wait for the SSL object to be freed to free these resources.

Parameters:

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

See: wolfSSL_KeepArrays

Return: none No return.

Example

WOLFSSL* ssl;
...
wolfSSL_FreeArrays(ssl);

function wolfSSL_UseSNI

int wolfSSL_UseSNI(
    WOLFSSL * ssl,
    unsigned char type,
    const void * data,
    unsigned short size
)

This function enables the use of Server Name Indication in the SSL object passed in the 'ssl' parameter. It means that the SNI extension will be sent on ClientHello by wolfSSL client and wolfSSL server will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• data pointer to the server name data.
• size size of the server name data.

See:

• wolfSSL_new
• wolfSSL_CTX_UseSNI

Return:

• WOLFSSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, data is NULL, type is a unknown value. (see below)
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
    strlen("www.yassl.com"));
if (ret != WOLFSSL_SUCCESS) {
    // sni usage failed
}

function wolfSSL_CTX_UseSNI

int wolfSSL_CTX_UseSNI(
    WOLFSSL_CTX * ctx,
    unsigned char type,
    const void * data,
    unsigned short size
)

This function enables the use of Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the SNI extension will be sent on ClientHello by wolfSSL clients and wolfSSL servers will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.

Parameters:

• ctx pointer to a SSL context, created with wolfSSL_CTX_new().
• type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• data pointer to the server name data.
• size size of the server name data.

See:

• wolfSSL_CTX_new
• wolfSSL_UseSNI

Return:

• WOLFSSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, data is NULL, type is a unknown value. (see below)
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ret = wolfSSL_CTX_UseSNI(ctx, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
    strlen("www.yassl.com"));
if (ret != WOLFSSL_SUCCESS) {
    // sni usage failed
}

function wolfSSL_SNI_SetOptions

void wolfSSL_SNI_SetOptions(
    WOLFSSL * ssl,
    unsigned char type,
    unsigned char options
)

This function is called on the server side to configure the behavior of the SSL session using Server Name Indication in the SSL object passed in the 'ssl' parameter. The options are explained below.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• options a bitwise semaphore with the chosen options. The available options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the handshake by sending a fatal-level unrecognized_name(112) alert if the hostname provided by the client mismatch with the servers.
• WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server will not send a SNI response instead of aborting the session.
• WOLFSSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server will send a SNI response as if the host names match instead of aborting the session.

See:

• wolfSSL_new
• wolfSSL_UseSNI
• wolfSSL_CTX_SNI_SetOptions

Return: none No returns.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
if (ret != WOLFSSL_SUCCESS) {
    // sni usage failed
}
wolfSSL_SNI_SetOptions(ssl, WOLFSSL_SNI_HOST_NAME,
    WOLFSSL_SNI_CONTINUE_ON_MISMATCH);

function wolfSSL_CTX_SNI_SetOptions

void wolfSSL_CTX_SNI_SetOptions(
    WOLFSSL_CTX * ctx,
    unsigned char type,
    unsigned char options
)

This function is called on the server side to configure the behavior of the SSL sessions using Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. The options are explained below.

Parameters:

• ctx pointer to a SSL context, created with wolfSSL_CTX_new().
• type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• options a bitwise semaphore with the chosen options. The available options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the handshake by sending a fatal-level unrecognized_name(112) alert if the hostname provided by the client mismatch with the servers.
• WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server will not send a SNI response instead of aborting the session.
• WOLFSSL_SNI_ANSWER_ON_MISMATCH With this option set, the server will send a SNI response as if the host names match instead of aborting the session.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_UseSNI
• wolfSSL_SNI_SetOptions

Return: none No returns.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
   // context creation failed
}
ret = wolfSSL_CTX_UseSNI(ctx, 0, "www.yassl.com", strlen("www.yassl.com"));
if (ret != WOLFSSL_SUCCESS) {
    // sni usage failed
}
wolfSSL_CTX_SNI_SetOptions(ctx, WOLFSSL_SNI_HOST_NAME,
WOLFSSL_SNI_CONTINUE_ON_MISMATCH);

function wolfSSL_SNI_GetFromBuffer

int wolfSSL_SNI_GetFromBuffer(
    const unsigned char * clientHello,
    unsigned int helloSz,
    unsigned char type,
    unsigned char * sni,
    unsigned int * inOutSz
)

This function is called on the server side to retrieve the Server Name Indication provided by the client from the Client Hello message sent by the client to start a session. It does not requires context or session setup to retrieve the SNI.

Parameters:

• buffer pointer to the data provided by the client (Client Hello).
• bufferSz size of the Client Hello message.
• type indicates which type of server name is been retrieved from the buffer. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• sni pointer to where the output is going to be stored.
• inOutSz pointer to the output size, this value will be updated to MIN("SNI's length", inOutSz).

See:

• wolfSSL_UseSNI
• wolfSSL_CTX_UseSNI
• wolfSSL_SNI_GetRequest

Return:

• WOLFSSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of this cases: buffer is NULL, bufferSz <= 0, sni is NULL, inOutSz is NULL or <= 0
• BUFFER_ERROR is the error returned when there is a malformed Client Hello message.
• INCOMPLETE_DATA is the error returned when there is not enough data to complete the extraction.

Example

unsigned char buffer[1024] = {0};
unsigned char result[32]   = {0};
int           length       = 32;
// read Client Hello to buffer...
ret = wolfSSL_SNI_GetFromBuffer(buffer, sizeof(buffer), 0, result, &length));
if (ret != WOLFSSL_SUCCESS) {
    // sni retrieve failed
}

function wolfSSL_SNI_Status

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

This function gets the status of an SNI object.

Parameters:

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

See:

• TLSX_SNI_Status
• TLSX_SNI_find
• TLSX_Find

Return:

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

Example

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

function wolfSSL_SNI_GetRequest

unsigned short wolfSSL_SNI_GetRequest(
    WOLFSSL * ssl,
    unsigned char type,
    void ** data
)

This function is called on the server side to retrieve the Server Name Indication provided by the client in a SSL session.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• type indicates which type of server name is been retrieved in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
• data pointer to the data provided by the client.

See:

• wolfSSL_UseSNI
• wolfSSL_CTX_UseSNI

Return: size the size of the provided SNI data.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
if (ret != WOLFSSL_SUCCESS) {
    // sni usage failed
}
if (wolfSSL_accept(ssl) == SSL_SUCCESS) {
    void *data = NULL;
    unsigned short size = wolfSSL_SNI_GetRequest(ssl, 0, &data);
}

function wolfSSL_UseALPN

int wolfSSL_UseALPN(
    WOLFSSL * ssl,
    char * protocol_name_list,
    unsigned int protocol_name_listSz,
    unsigned char options
)

Setup ALPN use for a wolfSSL session.

Parameters:

• ssl The wolfSSL session to use.
• protocol_name_list List of protocol names to use. Comma delimited string is required.
• protocol_name_listSz Size of the list of protocol names.
• options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or WOLFSSL_ALPN_FAILED_ON_MISMATCH.

See: TLSX_UseALPN

Return:

• WOLFSSL_SUCCESS: upon success.
• BAD_FUNC_ARG Returned if ssl or protocol_name_list is null or protocol_name_listSz is too large or options contain something not supported.
• MEMORY_ERROR Error allocating memory for protocol list.
• SSL_FAILURE upon failure.

Example

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

char alpn_list[] = {};

if (wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list),
    WOLFSSL_APN_FAILED_ON_MISMATCH) != WOLFSSL_SUCCESS)
{
   // Error setting session ticket
}

function wolfSSL_ALPN_GetProtocol

int wolfSSL_ALPN_GetProtocol(
    WOLFSSL * ssl,
    char ** protocol_name,
    unsigned short * size
)

This function gets the protocol name set by the server.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• protocol_name a pointer to a char that represents the protocol name and will be held in the ALPN structure.
• size a word16 type that represents the size of the protocol_name.

See:

• TLSX_ALPN_GetRequest
• TLSX_Find

Return:

• SSL_SUCCESS returned on successful execution where no errors were thrown.
• SSL_FATAL_ERROR returned if the extension was not found or if there was no protocol match with peer. There will also be an error thrown if there is more than one protocol name accepted.
• SSL_ALPN_NOT_FOUND returned signifying that no protocol match with peer was found.
• BAD_FUNC_ARG returned if there was a NULL argument passed into the function.

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
...
int err;
char* protocol_name = NULL;
Word16 protocol_nameSz = 0;
err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz);

if(err == SSL_SUCCESS){
    // Sent ALPN protocol
}

function wolfSSL_ALPN_GetPeerProtocol

int wolfSSL_ALPN_GetPeerProtocol(
    WOLFSSL * ssl,
    char ** list,
    unsigned short * listSz
)

This function copies the alpn_client_list data from the SSL object to the buffer.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• list a pointer to the buffer. The data from the SSL object will be copied into it.
• listSz the buffer size.

See: wolfSSL_UseALPN

Return:

• SSL_SUCCESS returned if the function executed without error. The alpn_client_list member of the SSL object has been copied to the list parameter.
• BAD_FUNC_ARG returned if the list or listSz parameter is NULL.
• BUFFER_ERROR returned if there will be a problem with the list buffer (either it’s NULL or the size is 0).
• MEMORY_ERROR returned if there was a problem dynamically allocating memory.

Example

#import <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
…
#ifdef HAVE_ALPN
char* list = NULL;
word16 listSz = 0;
…
err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz);

if(err == SSL_SUCCESS){
    List of protocols names sent by client
}

function wolfSSL_UseMaxFragment

int wolfSSL_UseMaxFragment(
    WOLFSSL * ssl,
    unsigned char mfl
)

This function is called on the client side to enable the use of Maximum Fragment Length in the SSL object passed in the 'ssl' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• mfl indicates which is the Maximum Fragment Length requested for the session. The available options are: enum { WOLFSSL_MFL_2_9 = 1, 512 bytes WOLFSSL_MFL_2_10 = 2, 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192 bytes wolfSSL ONLY!!! };

See:

• wolfSSL_new
• wolfSSL_CTX_UseMaxFragment

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, mfl is out of range.
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseMaxFragment(ssl, WOLFSSL_MFL_2_11);
if (ret != 0) {
    // max fragment usage failed
}

function wolfSSL_CTX_UseMaxFragment

int wolfSSL_CTX_UseMaxFragment(
    WOLFSSL_CTX * ctx,
    unsigned char mfl
)

This function is called on the client side to enable the use of Maximum Fragment Length for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients.

Parameters:

• ctx pointer to a SSL context, created with wolfSSL_CTX_new().
• mfl indicates which is the Maximum Fragment Length requested for the session. The available options are: enum { WOLFSSL_MFL_2_9 = 1 512 bytes, WOLFSSL_MFL_2_10 = 2 1024 bytes, WOLFSSL_MFL_2_11 = 3 2048 bytes WOLFSSL_MFL_2_12 = 4 4096 bytes, WOLFSSL_MFL_2_13 = 5 8192 bytes wolfSSL ONLY!!!, WOLFSSL_MFL_2_13 = 6 256 bytes wolfSSL ONLY!!! };

See:

• wolfSSL_CTX_new
• wolfSSL_UseMaxFragment

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, mfl is out of range.
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ret = wolfSSL_CTX_UseMaxFragment(ctx, WOLFSSL_MFL_2_11);
if (ret != 0) {
    // max fragment usage failed
}

function wolfSSL_UseTruncatedHMAC

int wolfSSL_UseTruncatedHMAC(
    WOLFSSL * ssl
)

This function is called on the client side to enable the use of Truncated HMAC in the SSL object passed in the 'ssl' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new()

See:

• wolfSSL_new
• wolfSSL_CTX_UseMaxFragment

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseTruncatedHMAC(ssl);
if (ret != 0) {
    // truncated HMAC usage failed
}

function wolfSSL_CTX_UseTruncatedHMAC

int wolfSSL_CTX_UseTruncatedHMAC(
    WOLFSSL_CTX * ctx
)

This function is called on the client side to enable the use of Truncated HMAC for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients.

Parameters:

• ctx pointer to a SSL context, created with wolfSSL_CTX_new().

See:

• wolfSSL_CTX_new
• wolfSSL_UseMaxFragment

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ret = wolfSSL_CTX_UseTruncatedHMAC(ctx);
if (ret != 0) {
    // truncated HMAC usage failed
}

function wolfSSL_UseOCSPStapling

int wolfSSL_UseOCSPStapling(
    WOLFSSL * ssl,
    unsigned char status_type,
    unsigned char options
)

Stapling eliminates the need to contact the CA. Stapling lowers the cost of certificate revocation check presented in OCSP.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• status_type a byte type that is passed through to TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure.
• options a byte type that is passed through to TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure.

See:

• TLSX_UseCertificateStatusRequest
• wolfSSL_CTX_UseOCSPStapling

Return:

• SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest executes without error.
• MEMORY_E returned if there is an error with the allocation of memory.
• BAD_FUNC_ARG returned if there is an argument that has a NULL or otherwise unacceptable value passed into the function.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
…
if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP,
WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){
    // Failed case.
}

function wolfSSL_CTX_UseOCSPStapling

int wolfSSL_CTX_UseOCSPStapling(
    WOLFSSL_CTX * ctx,
    unsigned char status_type,
    unsigned char options
)

This function requests the certificate status during the handshake.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• status_type a byte type that is passed through to TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure.
• options a byte type that is passed through to TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure.

See:

• wolfSSL_UseOCSPStaplingV2
• wolfSSL_UseOCSPStapling
• TLSX_UseCertificateStatusRequest

Return:

• SSL_SUCCESS returned if the function and subroutines execute without error.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or otherwise if a unpermitted value is passed to a subroutine.
• MEMORY_E returned if the function or subroutine failed to properly allocate memory.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
byte statusRequest = 0; // Initialize status request
…
switch(statusRequest){
    case WOLFSSL_CSR_OCSP:
        if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP,
WOLF_CSR_OCSP_USE_NONCE) != SSL_SUCCESS){
// UseCertificateStatusRequest failed
}
// Continue switch cases

function wolfSSL_UseOCSPStaplingV2

int wolfSSL_UseOCSPStaplingV2(
    WOLFSSL * ssl,
    unsigned char status_type,
    unsigned char options
)

The function sets the status type and options for OCSP.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• status_type a byte type that loads the OCSP status type.
• options a byte type that holds the OCSP options, set in wolfSSL_SNI_SetOptions() and wolfSSL_CTX_SNI_SetOptions().

See:

• TLSX_UseCertificatStatusRequestV2
• wolfSSL_SNI_SetOptions
• wolfSSL_CTX_SNI_SetOptions

Return:

• SSL_SUCCESS - returned if the function and subroutines executed without error.
• MEMORY_E - returned if there was an allocation of memory error.
• BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted argument was passed to the function or a subroutine.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
...
if (wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, 0) != SSL_SUCCESS){
    // Did not execute properly. Failure case code block.
}

function wolfSSL_CTX_UseOCSPStaplingV2

int wolfSSL_CTX_UseOCSPStaplingV2(
    WOLFSSL_CTX * ctx,
    unsigned char status_type,
    unsigned char options
)

Creates and initializes the certificate status request for OCSP Stapling.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• status_type a byte type that is located in the CertificatStatusRequest structure and must be either WOLFSSL_CSR2_OCSP or WOLFSSL_CSR2_OCSP_MULTI.
• options a byte type that will be held in CertificateStatusRequestItemV2 struct.

See:

• TLSX_UseCertificateStatusRequestV2
• wc_RNG_GenerateBlock
• TLSX_Push

Return:

• SSL_SUCCESS if the function and subroutines executed without error.
• BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or if the side variable is not client side.
• MEMORY_E returned if the allocation of memory failed.

Example

WOLFSSL_CTX* ctx  = wolfSSL_CTX_new( protocol method );
byte status_type;
byte options;
...
if(wolfSSL_CTX_UseOCSPStaplingV2(ctx, status_type, options); != SSL_SUCCESS){
    // Failure case.
}

function wolfSSL_UseSupportedCurve

int wolfSSL_UseSupportedCurve(
    WOLFSSL * ssl,
    word16 name
)

This function is called on the client side to enable the use of Supported Elliptic Curves Extension in the SSL object passed in the 'ssl' parameter. It means that the supported curves enabled will be sent on ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves.

Parameters:

• ssl pointer to a SSL object, created with wolfSSL_new().
• name indicates which curve will be supported for the session. The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, WOLFSSL_ECC_SECP521R1 = 0x19 };

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_UseSupportedCurve

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, name is a unknown value. (see below)
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
WOLFSSL* ssl = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ssl = wolfSSL_new(ctx);
if (ssl == NULL) {
    // ssl creation failed
}
ret = wolfSSL_UseSupportedCurve(ssl, WOLFSSL_ECC_SECP256R1);
if (ret != 0) {
    // Elliptic Curve Extension usage failed
}

function wolfSSL_CTX_UseSupportedCurve

int wolfSSL_CTX_UseSupportedCurve(
    WOLFSSL_CTX * ctx,
    word16 name
)

This function is called on the client side to enable the use of Supported Elliptic Curves Extension for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the supported curves enabled will be sent on ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves.

Parameters:

• ctx pointer to a SSL context, created with wolfSSL_CTX_new().
• name indicates which curve will be supported for the session. The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, WOLFSSL_ECC_SECP521R1 = 0x19 };

See:

• wolfSSL_CTX_new
• wolfSSL_UseSupportedCurve

Return:

• SSL_SUCCESS upon success.
• BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, name is a unknown value. (see below)
• MEMORY_E is the error returned when there is not enough memory.

Example

int ret = 0;
WOLFSSL_CTX* ctx = 0;
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
    // context creation failed
}
ret = wolfSSL_CTX_UseSupportedCurve(ctx, WOLFSSL_ECC_SECP256R1);
if (ret != 0) {
    // Elliptic Curve Extension usage failed
}

function wolfSSL_UseSecureRenegotiation

int wolfSSL_UseSecureRenegotiation(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• TLSX_Find
• TLSX_UseSecureRenegotiation

Return:

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

Example

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

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

function wolfSSL_Rehandshake

int wolfSSL_Rehandshake(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_negotiate
• wc_InitSha512
• wc_InitSha384
• wc_InitSha256
• wc_InitSha
• wc_InitMd5

Return:

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

Example

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

function wolfSSL_UseSessionTicket

int wolfSSL_UseSessionTicket(
    WOLFSSL * ssl
)

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

Parameters:

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

See: TLSX_UseSessionTicket

Return:

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

Example

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

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

function wolfSSL_CTX_UseSessionTicket

int wolfSSL_CTX_UseSessionTicket(
    WOLFSSL_CTX * ctx
)

This function sets wolfSSL context to use a session ticket.

Parameters:

• ctx The WOLFSSL_CTX structure to use.

See: TLSX_UseSessionTicket

Return:

• SSL_SUCCESS Function executed successfully.
• BAD_FUNC_ARG Returned if ctx is null.
• MEMORY_E Error allocating memory in internal function.

Example

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

if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS)
{
    // Error setting session ticket
}

function wolfSSL_get_SessionTicket

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

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

Parameters:

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

See:

• wolfSSL_UseSessionTicket
• wolfSSL_set_SessionTicket

Return:

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

Example

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

function wolfSSL_set_SessionTicket

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

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

Parameters:

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

See: wolfSSL_set_SessionTicket_cb

Return:

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

Example

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

function wolfSSL_set_SessionTicket_cb

int wolfSSL_set_SessionTicket_cb(
    WOLFSSL * ssl,
    CallbackSessionTicket cb,
    void * ctx
)

This function sets the session ticket callback. The type CallbackSessionTicket is a function pointer with the signature of: int (CallbackSessionTicket)(WOLFSSL, const unsigned char, int, void)

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer to the type CallbackSessionTicket.
• ctx a void pointer to the session_ticket_ctx member of the WOLFSSL structure.

See:

• wolfSSL_get_SessionTicket
• CallbackSessionTicket
• sessionTicketCB

Return:

• SSL_SUCCESS returned if the function executed without error.
• BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
int sessionTicketCB(WOLFSSL* ssl, const unsigned char* ticket, int ticketSz,
            void* ctx){ … }
wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”);

function wolfSSL_send_SessionTicket

int wolfSSL_send_SessionTicket(
    WOLFSSL * ssl
)

This function sends a session ticket to the client after a TLS v1.3 handhsake has been established.

Parameters:

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

See:

• wolfSSL_get_SessionTicket
• CallbackSessionTicket
• sessionTicketCB

Return:

• WOLFSSL_SUCCESS returned if a new session ticket was sent.
• BAD_FUNC_ARG returned if WOLFSSL structure is NULL, or not using TLS v1.3.
• SIDE_ERROR returned if not a server.
• NOT_READY_ERROR returned if the handshake has not completed.
• WOLFSSL_FATAL_ERROR returned if creating or sending message fails.

Example

int ret;
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
ret = wolfSSL_send_SessionTicket(ssl);
if (ret != WOLFSSL_SUCCESS) {
    // New session ticket not sent.
}

function wolfSSL_CTX_set_TicketEncCb

int wolfSSL_CTX_set_TicketEncCb(
    WOLFSSL_CTX * ctx,
    SessionTicketEncCb 
)

This function sets the session ticket key encrypt callback function for a server to support session tickets as specified in RFC 5077.

Parameters:

• ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
• cb user callback function to encrypt/decrypt session tickets
• ssl(Callback) pointer to the WOLFSSL object, created with wolfSSL_new()
• key_name(Callback) unique key name for this ticket context, should be randomly generated
• iv(Callback) unique IV for this ticket, up to 128 bits, should be randomly generated
• mac(Callback) up to 256 bit mac for this ticket
• enc(Callback) if this encrypt parameter is true the user should fill in key_name, iv, mac, and encrypt the ticket in-place of length inLen and set the resulting output length in outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL that the encryption was successful. If this encrypt parameter is false, the user should perform a decrypt of the ticket in-place of length inLen using key_name, iv, and mac. The resulting decrypt length should be set in outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL to proceed using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE tells wolfSSL to use the decrypted ticket but also to generate a new one to send to the client, helpful if recently rolled keys and don’t want to force a full handshake. Returning WOLFSSL_TICKET_RET_REJECT tells wolfSSL to reject this ticket, perform a full handshake, and create a new standard session ID for normal session resumption. Returning WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection attempt with a fatal error.
• ticket(Callback) the input/output buffer for the encrypted ticket. See the enc parameter
• inLen(Callback) the input length of the ticket parameter
• outLen(Callback) the resulting output length of the ticket parameter. When entering the callback outLen will indicate the maximum size available in the ticket buffer.
• userCtx(Callback) the user context set with wolfSSL_CTX_set_TicketEncCtx()

See:

• wolfSSL_CTX_set_TicketHint
• wolfSSL_CTX_set_TicketEncCtx

Return:

• SSL_SUCCESS will be returned upon successfully setting the session.
• BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function.

Example

See wolfssl/test.h myTicketEncCb() used by the example
server and example echoserver.

function wolfSSL_CTX_set_TicketHint

int wolfSSL_CTX_set_TicketHint(
    WOLFSSL_CTX * ctx,
    int 
)

This function sets the session ticket hint relayed to the client. For server side use.

Parameters:

• ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
• hint number of seconds the ticket might be valid for. Hint to client.

See: wolfSSL_CTX_set_TicketEncCb

Return:

• SSL_SUCCESS will be returned upon successfully setting the session.
• BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function.

Example

none

function wolfSSL_CTX_set_TicketEncCtx

int wolfSSL_CTX_set_TicketEncCtx(
    WOLFSSL_CTX * ctx,
    void * 
)

This function sets the session ticket encrypt user context for the callback. For server side use.

Parameters:

• ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
• userCtx the user context for the callback

See: wolfSSL_CTX_set_TicketEncCb

Return:

• SSL_SUCCESS will be returned upon successfully setting the session.
• BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function.

Example

none

function wolfSSL_CTX_get_TicketEncCtx

void * wolfSSL_CTX_get_TicketEncCtx(
    WOLFSSL_CTX * ctx
)

This function gets the session ticket encrypt user context for the callback. For server side use.

Parameters:

• ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().

See: wolfSSL_CTX_set_TicketEncCtx

Return:

• userCtx will be returned upon successfully getting the session.
• NULL will be returned on failure. This is caused by passing invalid arguments to the function, or when the user context has not been set.

Example

none

function wolfSSL_SetHsDoneCb

int wolfSSL_SetHsDoneCb(
    WOLFSSL * ssl,
    HandShakeDoneCb cb,
    void * user_ctx
)

This function sets the handshake done callback. The hsDoneCb and hsDoneCtx members of the WOLFSSL structure are set in this function.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a function pointer of type HandShakeDoneCb with the signature of the form: int (HandShakeDoneCb)(WOLFSSL, void*);
• user_ctx a void pointer to the user registered context.

See: HandShakeDoneCb

Return:

• SSL_SUCCESS returned if the function executed without an error. The hsDoneCb and hsDoneCtx members of the WOLFSSL struct are set.
• BAD_FUNC_ARG returned if the WOLFSSL struct is NULL.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
…
int myHsDoneCb(WOLFSSL* ssl, void* user_ctx){
    // callback function
}
…
wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL);

function wolfSSL_PrintSessionStats

int wolfSSL_PrintSessionStats(
    void 
)

This function prints the statistics from the session.

Parameters:

• none No parameters.

See: wolfSSL_get_session_stats

Return:

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

Example

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

function wolfSSL_get_session_stats

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

This function gets the statistics for the session.

Parameters:

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

See: wolfSSL_PrintSessionStats

Return:

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

Example

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

function wolfSSL_MakeTlsMasterSecret

int wolfSSL_MakeTlsMasterSecret(
    unsigned char * ms,
    word32 msLen,
    const unsigned char * pms,
    word32 pmsLen,
    const unsigned char * cr,
    const unsigned char * sr,
    int tls1_2,
    int hash_type
)

This function copies the values of cr and sr then passes through to wc_PRF (pseudo random function) and returns that value.

Parameters:

• ms the master secret held in the Arrays structure.
• msLen the length of the master secret.
• pms the pre-master secret held in the Arrays structure.
• pmsLen the length of the pre-master secret.
• cr the client random.
• sr the server random.
• tls1_2 signifies that the version is at least tls version 1.2.
• hash_type signifies the hash type.

See:

• wc_PRF
• MakeTlsMasterSecret

Return:

• 0 on success
• BUFFER_E returned if there will be an error with the size of the buffer.
• MEMORY_E returned if a subroutine failed to allocate dynamic memory.

Example

WOLFSSL* ssl;

called in MakeTlsMasterSecret and retrieves the necessary
information as follows:

int MakeTlsMasterSecret(WOLFSSL* ssl){
int ret;
ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret, SECRET_LEN,
ssl->arrays->preMasterSecret, ssl->arrays->preMasterSz,
ssl->arrays->clientRandom, ssl->arrays->serverRandom,
IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
…
return ret;

}

function wolfSSL_DeriveTlsKeys

int wolfSSL_DeriveTlsKeys(
    unsigned char * key_data,
    word32 keyLen,
    const unsigned char * ms,
    word32 msLen,
    const unsigned char * sr,
    const unsigned char * cr,
    int tls1_2,
    int hash_type
)

An external facing wrapper to derive TLS Keys.

Parameters:

• key_data a byte pointer that is allocateded in DeriveTlsKeys and passed through to wc_PRF to hold the final hash.
• keyLen a word32 type that is derived in DeriveTlsKeys from the WOLFSSL structure’s specs member.
• ms a constant pointer type holding the master secret held in the arrays structure within the WOLFSSL structure.
• msLen a word32 type that holds the length of the master secret in an enumerated define, SECRET_LEN.
• sr a constant byte pointer to the serverRandom member of the arrays structure within the WOLFSSL structure.
• cr a constant byte pointer to the clientRandom member of the arrays structure within the WOLFSSL structure.
• tls1_2 an integer type returned from IsAtLeastTLSv1_2().
• hash_type an integer type held in the WOLFSSL structure.

See:

• wc_PRF
• DeriveTlsKeys
• IsAtLeastTLSv1_2

Return:

• 0 returned on success.
• BUFFER_E returned if the sum of labLen and seedLen (computes total size) exceeds the maximum size.
• MEMORY_E returned if the allocation of memory failed.

Example

int DeriveTlsKeys(WOLFSSL* ssl){
int ret;
…
ret = wolfSSL_DeriveTlsKeys(key_data, length, ssl->arrays->masterSecret,
SECRET_LEN, ssl->arrays->clientRandom,
IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
…
}

function wolfSSL_connect_ex

int wolfSSL_connect_ex(
    WOLFSSL * ssl,
    HandShakeCallBack hsCb,
    TimeoutCallBack toCb,
    WOLFSSL_TIMEVAL timeout
)

wolfSSL_connect_ex() is an extension that allows a HandShake Callback to be set. This can be useful in embedded systems for debugging support when a debugger isn’t available and sniffing is impractical. The HandShake Callback will be called whether or not a handshake error occurred. No dynamic memory is used since the maximum number of SSL packets is known. Packet names can be accessed through packetNames[]. The connect extension also allows a Timeout Callback to be set along with a timeout value. This is useful if the user doesn’t want to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks.

Parameters:

• none No parameters.

See: wolfSSL_accept_ex

Return:

• SSL_SUCCESS upon success.
• GETTIME_ERROR will be returned if gettimeofday() encountered an error.
• SETITIMER_ERROR will be returned if setitimer() encountered an error.
• SIGACT_ERROR will be returned if sigaction() encountered an error.
• SSL_FATAL_ERROR will be returned if the underlying SSL_connect() call encountered an error.

Example

none

function wolfSSL_accept_ex

int wolfSSL_accept_ex(
    WOLFSSL * ssl,
    HandShakeCallBacki hsCb,
    TimeoutCallBack toCb,
    WOLFSSL_TIMEVAL timeout
)

wolfSSL_accept_ex() is an extension that allows a HandShake Callback to be set. This can be useful in embedded systems for debugging support when a debugger isn’t available and sniffing is impractical. The HandShake Callback will be called whether or not a handshake error occurred. No dynamic memory is used since the maximum number of SSL packets is known. Packet names can be accessed through packetNames[]. The connect extension also allows a Timeout Callback to be set along with a timeout value. This is useful if the user doesn’t want to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks.

Parameters:

• none No parameters.

See: wolfSSL_connect_ex

Return:

• SSL_SUCCESS upon success.
• GETTIME_ERROR will be returned if gettimeofday() encountered an error.
• SETITIMER_ERROR will be returned if setitimer() encountered an error.
• SIGACT_ERROR will be returned if sigaction() encountered an error.
• SSL_FATAL_ERROR will be returned if the underlying SSL_accept() call encountered an error.

Example

none

function wolfSSL_BIO_set_fp

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

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_get_fp
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_BIO_get_fp

long wolfSSL_BIO_get_fp(
    WOLFSSL_BIO * bio,
    XFILE * fp
)

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

Parameters:

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

See:

• wolfSSL_BIO_new
• wolfSSL_BIO_s_mem
• wolfSSL_BIO_set_fp
• wolfSSL_BIO_free

Return:

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

Example

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

function wolfSSL_check_private_key

int wolfSSL_check_private_key(
    const WOLFSSL * ssl
)

This function checks that the private key is a match with the certificate being used.

Parameters:

• ssl WOLFSSL structure to check.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• SSL_SUCCESS On successfully match.
• SSL_FAILURE If an error case was encountered.
• <0 All error cases other than SSL_FAILURE are negative values.

Example

WOLFSSL* ssl;
int ret;
// create and set up ssl
ret  = wolfSSL_check_private_key(ssl);
// check ret value

function wolfSSL_X509_get_ext_by_NID

int wolfSSL_X509_get_ext_by_NID(
    const WOLFSSL_X509 * x509,
    int nid,
    int lastPos
)

This function looks for and returns the extension index matching the passed in NID value.

Parameters:

• x509 certificate to get parse through for extension.
• nid extension OID to be found.
• lastPos start search from extension after lastPos. Set to -1 initially.

Return:

• = 0 If successful the extension index is returned.

• -1 If extension is not found or error is encountered.

Example

const WOLFSSL_X509* x509;
int lastPos = -1;
int idx;

idx = wolfSSL_X509_get_ext_by_NID(x509, NID_basic_constraints, lastPos);

function wolfSSL_X509_get_ext_d2i

void * wolfSSL_X509_get_ext_d2i(
    const WOLFSSL_X509 * x509,
    int nid,
    int * c,
    int * idx
)

This function looks for and returns the extension matching the passed in NID value.

Parameters:

• x509 certificate to get parse through for extension.
• nid extension OID to be found.
• c if not NULL is set to -2 for multiple extensions found -1 if not found, 0 if found and not critical and 1 if found and critical.
• idx if NULL return first extension matched otherwise if not stored in x509 start at idx.

See: wolfSSL_sk_ASN1_OBJECT_free

Return:

• pointer If successful a STACK_OF(WOLFSSL_ASN1_OBJECT) pointer is returned.
• NULL If extension is not found or error is encountered.

Example

const WOLFSSL_X509* x509;
int c;
int idx = 0;
STACK_OF(WOLFSSL_ASN1_OBJECT)* sk;

sk = wolfSSL_X509_get_ext_d2i(x509, NID_basic_constraints, &c, &idx);
//check sk for NULL and then use it. sk needs freed after done.

function wolfSSL_X509_digest

int wolfSSL_X509_digest(
    const WOLFSSL_X509 * x509,
    const WOLFSSL_EVP_MD * digest,
    unsigned char * buf,
    unsigned int * len
)

This function returns the hash of the DER certificate.

Parameters:

• x509 certificate to get the hash of.
• digest the hash algorithm to use.
• buf buffer to hold hash.
• len length of buffer.

See: none

Return:

• SSL_SUCCESS On successfully creating a hash.
• SSL_FAILURE Returned on bad input or unsuccessful hash.

Example

WOLFSSL_X509* x509;
unsigned char buffer[64];
unsigned int bufferSz;
int ret;

ret = wolfSSL_X509_digest(x509, wolfSSL_EVP_sha256(), buffer, &bufferSz);
//check ret value

function wolfSSL_use_certificate

int wolfSSL_use_certificate(
    WOLFSSL * ssl,
    WOLFSSL_X509 * x509
)

his is used to set the certificate for WOLFSSL structure to use during a handshake.

Parameters:

• ssl WOLFSSL structure to set certificate in.
• x509 certificate to use.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• SSL_SUCCESS On successful setting argument.
• SSL_FAILURE If a NULL argument passed in.

Example

 WOLFSSL* ssl;
WOLFSSL_X509* x509
int ret;
// create ssl object and x509
ret  = wolfSSL_use_certificate(ssl, x509);
// check ret value

function wolfSSL_use_certificate_ASN1

int wolfSSL_use_certificate_ASN1(
    WOLFSSL * ssl,
    unsigned char * der,
    int derSz
)

This is used to set the certificate for WOLFSSL structure to use during a handshake. A DER formatted buffer is expected.

Parameters:

• ssl WOLFSSL structure to set certificate in.
• der DER certificate to use.
• derSz size of the DER buffer passed in.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• SSL_SUCCESS On successful setting argument.
• SSL_FAILURE If a NULL argument passed in.

Example

WOLFSSL* ssl;
unsigned char* der;
int derSz;
int ret;
// create ssl object and set DER variables
ret  = wolfSSL_use_certificate_ASN1(ssl, der, derSz);
// check ret value

function wolfSSL_use_PrivateKey

int wolfSSL_use_PrivateKey(
    WOLFSSL * ssl,
    WOLFSSL_EVP_PKEY * pkey
)

This is used to set the private key for the WOLFSSL structure.

Parameters:

• ssl WOLFSSL structure to set argument in.
• pkey private key to use.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• SSL_SUCCESS On successful setting argument.
• SSL_FAILURE If a NULL ssl passed in. All error cases will be negative values.

Example

WOLFSSL* ssl;
WOLFSSL_EVP_PKEY* pkey;
int ret;
// create ssl object and set up private key
ret  = wolfSSL_use_PrivateKey(ssl, pkey);
// check ret value

function wolfSSL_use_PrivateKey_ASN1

int wolfSSL_use_PrivateKey_ASN1(
    int pri,
    WOLFSSL * ssl,
    unsigned char * der,
    long derSz
)

This is used to set the private key for the WOLFSSL structure. A DER formatted key buffer is expected.

Parameters:

• pri type of private key.
• ssl WOLFSSL structure to set argument in.
• der buffer holding DER key.
• derSz size of der buffer.

See:

• wolfSSL_new
• wolfSSL_free
• wolfSSL_use_PrivateKey

Return:

• SSL_SUCCESS On successful setting parsing and setting the private key.
• SSL_FAILURE If an NULL ssl passed in. All error cases will be negative values.

Example

WOLFSSL* ssl;
unsigned char* pkey;
long pkeySz;
int ret;
// create ssl object and set up private key
ret  = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz);
// check ret value

function wolfSSL_use_RSAPrivateKey_ASN1

int wolfSSL_use_RSAPrivateKey_ASN1(
    WOLFSSL * ssl,
    unsigned char * der,
    long derSz
)

This is used to set the private key for the WOLFSSL structure. A DER formatted RSA key buffer is expected.

Parameters:

• ssl WOLFSSL structure to set argument in.
• der buffer holding DER key.
• derSz size of der buffer.

See:

• wolfSSL_new
• wolfSSL_free
• wolfSSL_use_PrivateKey

Return:

• SSL_SUCCESS On successful setting parsing and setting the private key.
• SSL_FAILURE If an NULL ssl passed in. All error cases will be negative values.

Example

WOLFSSL* ssl;
unsigned char* pkey;
long pkeySz;
int ret;
// create ssl object and set up RSA private key
ret  = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz);
// check ret value

function wolfSSL_DSA_dup_DH

WOLFSSL_DH * wolfSSL_DSA_dup_DH(
    const WOLFSSL_DSA * r
)

This function duplicates the parameters in dsa to a newly created WOLFSSL_DH structure.

Parameters:

• dsa WOLFSSL_DSA structure to duplicate.

See: none

Return:

• WOLFSSL_DH If duplicated returns WOLFSSL_DH structure
• NULL upon failure

Example

WOLFSSL_DH* dh;
WOLFSSL_DSA* dsa;
// set up dsa
dh = wolfSSL_DSA_dup_DH(dsa);

// check dh is not null

function wolfSSL_SESSION_get_master_key

int wolfSSL_SESSION_get_master_key(
    const WOLFSSL_SESSION * ses,
    unsigned char * out,
    int outSz
)

This is used to get the master key after completing a handshake.

Parameters:

• ses WOLFSSL_SESSION structure to get master secret buffer from.
• out buffer to hold data.
• outSz size of out buffer passed in. (if 0 function will return max buffer size needed)

See:

• wolfSSL_new
• wolfSSL_free

Return:

• 0 On successfully getting data returns a value greater than 0

• 0 If no random data buffer or an error state returns 0
• max If outSz passed in is 0 then the maximum buffer size needed is returned

Example

WOLFSSL_SESSION ssl;
unsigned char* buffer;
size_t bufferSz;
size_t ret;
// complete handshake and get session structure
bufferSz  = wolfSSL_SESSION_get_master_secret(ses, NULL, 0);
buffer = malloc(bufferSz);
ret  = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz);
// check ret value

function wolfSSL_SESSION_get_master_key_length

int wolfSSL_SESSION_get_master_key_length(
    const WOLFSSL_SESSION * ses
)

This is used to get the master secret key length.

Parameters:

• ses WOLFSSL_SESSION structure to get master secret buffer from.

See:

• wolfSSL_new
• wolfSSL_free

Return: size Returns master secret key size.

Example

WOLFSSL_SESSION ssl;
unsigned char* buffer;
size_t bufferSz;
size_t ret;
// complete handshake and get session structure
bufferSz  = wolfSSL_SESSION_get_master_secret_length(ses);
buffer = malloc(bufferSz);
// check ret value

function wolfSSL_CTX_set_cert_store

void wolfSSL_CTX_set_cert_store(
    WOLFSSL_CTX * ctx,
    WOLFSSL_X509_STORE * str
)

This is a setter function for the WOLFSSL_X509_STORE structure in ctx.

Parameters:

• ctx pointer to the WOLFSSL_CTX structure for setting cert store pointer.
• str pointer to the WOLFSSL_X509_STORE to set in ctx.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return: none No return.

Example

WOLFSSL_CTX ctx;
WOLFSSL_X509_STORE* st;
// setup ctx and st
st = wolfSSL_CTX_set_cert_store(ctx, st);
//use st

function wolfSSL_d2i_X509_bio

WOLFSSL_X509 * wolfSSL_d2i_X509_bio(
    WOLFSSL_BIO * bio,
    WOLFSSL_X509 ** x509
)

This function get the DER buffer from bio and converts it to a WOLFSSL_X509 structure.

Parameters:

• bio pointer to the WOLFSSL_BIO structure that has the DER certificate buffer.
• x509 pointer that get set to new WOLFSSL_X509 structure created.

See: none

Return:

• pointer returns a WOLFSSL_X509 structure pointer on success.
• Null returns NULL on failure

Example

WOLFSSL_BIO* bio;
WOLFSSL_X509* x509;
// load DER into bio
x509 = wolfSSL_d2i_X509_bio(bio, NULL);
Or
wolfSSL_d2i_X509_bio(bio, &x509);
// use x509 returned (check for NULL)

function wolfSSL_CTX_get_cert_store

WOLFSSL_X509_STORE * wolfSSL_CTX_get_cert_store(
    WOLFSSL_CTX * ctx
)

This is a getter function for the WOLFSSL_X509_STORE structure in ctx.

Parameters:

• ctx pointer to the WOLFSSL_CTX structure for getting cert store pointer.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free
• wolfSSL_CTX_set_cert_store

Return:

• WOLFSSL_X509_STORE* On successfully getting the pointer.
• NULL Returned if NULL arguments are passed in.

Example

WOLFSSL_CTX ctx;
WOLFSSL_X509_STORE* st;
// setup ctx
st = wolfSSL_CTX_get_cert_store(ctx);
//use st

function wolfSSL_BIO_ctrl_pending

size_t wolfSSL_BIO_ctrl_pending(
    WOLFSSL_BIO * b
)

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

Parameters:

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

See:

• wolfSSL_BIO_make_bio_pair
• wolfSSL_BIO_new

Return: >=0 number of pending bytes.

Example

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

function wolfSSL_get_server_random

size_t wolfSSL_get_server_random(
    const WOLFSSL * ssl,
    unsigned char * out,
    size_t outlen
)

This is used to get the random data sent by the server during the handshake.

Parameters:

• ssl WOLFSSL structure to get clients random data buffer from.
• out buffer to hold random data.
• outSz size of out buffer passed in. (if 0 function will return max buffer size needed)

See:

• wolfSSL_new
• wolfSSL_free

Return:

• 0 On successfully getting data returns a value greater than 0

• 0 If no random data buffer or an error state returns 0
• max If outSz passed in is 0 then the maximum buffer size needed is returned

Example

WOLFSSL ssl;
unsigned char* buffer;
size_t bufferSz;
size_t ret;
bufferSz  = wolfSSL_get_server_random(ssl, NULL, 0);
buffer = malloc(bufferSz);
ret  = wolfSSL_get_server_random(ssl, buffer, bufferSz);
// check ret value

function wolfSSL_get_client_random

size_t wolfSSL_get_client_random(
    const WOLFSSL * ssl,
    unsigned char * out,
    size_t outSz
)

This is used to get the random data sent by the client during the handshake.

Parameters:

• ssl WOLFSSL structure to get clients random data buffer from.
• out buffer to hold random data.
• outSz size of out buffer passed in. (if 0 function will return max buffer size needed)

See:

• wolfSSL_new
• wolfSSL_free

Return:

• 0 On successfully getting data returns a value greater than 0

• 0 If no random data buffer or an error state returns 0
• max If outSz passed in is 0 then the maximum buffer size needed is returned

Example

WOLFSSL ssl;
unsigned char* buffer;
size_t bufferSz;
size_t ret;
bufferSz  = wolfSSL_get_client_random(ssl, NULL, 0);
buffer = malloc(bufferSz);
ret  = wolfSSL_get_client_random(ssl, buffer, bufferSz);
// check ret value

function wolfSSL_CTX_get_default_passwd_cb

wc_pem_password_cb * wolfSSL_CTX_get_default_passwd_cb(
    WOLFSSL_CTX * ctx
)

This is a getter function for the password callback set in ctx.

Parameters:

• ctx WOLFSSL_CTX structure to get call back from.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return:

• func On success returns the callback function.
• NULL If ctx is NULL then NULL is returned.

Example

WOLFSSL_CTX* ctx;
wc_pem_password_cb cb;
// setup ctx
cb = wolfSSL_CTX_get_default_passwd_cb(ctx);
//use cb

function wolfSSL_CTX_get_default_passwd_cb_userdata

void * wolfSSL_CTX_get_default_passwd_cb_userdata(
    WOLFSSL_CTX * ctx
)

This is a getter function for the password callback user data set in ctx.

Parameters:

• ctx WOLFSSL_CTX structure to get user data from.

See:

• wolfSSL_CTX_new
• wolfSSL_CTX_free

Return:

• pointer On success returns the user data pointer.
• NULL If ctx is NULL then NULL is returned.

Example

WOLFSSL_CTX* ctx;
void* data;
// setup ctx
data = wolfSSL_CTX_get_default_passwd_cb(ctx);
//use data

function wolfSSL_PEM_read_bio_X509_AUX

WOLFSSL_X509 * wolfSSL_PEM_read_bio_X509_AUX(
    WOLFSSL_BIO * bp,
    WOLFSSL_X509 ** x,
    wc_pem_password_cb * cb,
    void * u
)

This function behaves the same as wolfSSL_PEM_read_bio_X509. AUX signifies containing extra information such as trusted/rejected use cases and friendly name for human readability.

Parameters:

• bp WOLFSSL_BIO structure to get PEM buffer from.
• x if setting WOLFSSL_X509 by function side effect.
• cb password callback.
• u NULL terminated user password.

See: wolfSSL_PEM_read_bio_X509

Return:

• WOLFSSL_X509 on successfully parsing the PEM buffer a WOLFSSL_X509 structure is returned.
• Null if failed to parse PEM buffer.

Example

WOLFSSL_BIO* bio;
WOLFSSL_X509* x509;
// setup bio
X509 = wolfSSL_PEM_read_bio_X509_AUX(bio, NULL, NULL, NULL);
//check x509 is not null and then use it

function wolfSSL_CTX_set_tmp_dh

long wolfSSL_CTX_set_tmp_dh(
    WOLFSSL_CTX * ctx,
    WOLFSSL_DH * dh
)

Initializes the WOLFSSL_CTX structure’s dh member with the Diffie-Hellman parameters.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
• dh a pointer to a WOLFSSL_DH structure.

See: wolfSSL_BN_bn2bin

Return:

• SSL_SUCCESS returned if the function executed successfully.
• BAD_FUNC_ARG returned if the ctx or dh structures are NULL.
• SSL_FATAL_ERROR returned if there was an error setting a structure value.
• MEMORY_E returned if their was a failure to allocate memory.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL_DH* dh;
…
return wolfSSL_CTX_set_tmp_dh(ctx, dh);

function wolfSSL_PEM_read_bio_DSAparams

WOLFSSL_DSA * wolfSSL_PEM_read_bio_DSAparams(
    WOLFSSL_BIO * bp,
    WOLFSSL_DSA ** x,
    wc_pem_password_cb * cb,
    void * u
)

This function get the DSA parameters from a PEM buffer in bio.

Parameters:

• bio pointer to the WOLFSSL_BIO structure for getting PEM memory pointer.
• x pointer to be set to new WOLFSSL_DSA structure.
• cb password callback function.
• u null terminated password string.

See: none

Return:

• WOLFSSL_DSA on successfully parsing the PEM buffer a WOLFSSL_DSA structure is created and returned.
• Null if failed to parse PEM buffer.

Example

WOLFSSL_BIO* bio;
WOLFSSL_DSA* dsa;
// setup bio
dsa = wolfSSL_PEM_read_bio_DSAparams(bio, NULL, NULL, NULL);

// check dsa is not NULL and then use dsa

function wolfSSL_ERR_peek_last_error

unsigned long wolfSSL_ERR_peek_last_error(
    void 
)

This function returns the absolute value of the last error from WOLFSSL_ERROR encountered.

Parameters:

• none No parameters.

See: wolfSSL_ERR_print_errors_fp

Return: error Returns absolute value of last error.

Example

unsigned long err;
...
err = wolfSSL_ERR_peek_last_error();
// inspect err value

function WOLF_STACK_OF

WOLF_STACK_OF(
    WOLFSSL_X509 
) const

This function gets the peer’s certificate chain.

Parameters:

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

See:

• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_subject_name
• wolfSSL_X509_get_isCA

Return:

• pointer returns a pointer to the peer’s Certificate stack.
• NULL returned if no peer certificate.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
wolfSSL_connect(ssl);
STACK_OF(WOLFSSL_X509)* chain = wolfSSL_get_peer_cert_chain(ssl);
ifchain){
    // You have a pointer to the peer certificate chain
}

function wolfSSL_CTX_clear_options

long wolfSSL_CTX_clear_options(
    WOLFSSL_CTX * ctx,
    long opt
)

This function resets option bits of WOLFSSL_CTX object.

Parameters:

• ctx pointer to the SSL context.

See:

• wolfSSL_CTX_new
• wolfSSL_new
• wolfSSL_free

Return: option new option bits

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);

function wolfSSL_set_jobject

int wolfSSL_set_jobject(
    WOLFSSL * ssl,
    void * objPtr
)

This function sets the jObjectRef member of the WOLFSSL structure.

Parameters:

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

See: wolfSSL_get_jobject

Return:

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

Example

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

function wolfSSL_get_jobject

void * wolfSSL_get_jobject(
    WOLFSSL * ssl
)

This function returns the jObjectRef member of the WOLFSSL structure.

Parameters:

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

See: wolfSSL_set_jobject

Return:

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

Example

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

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

function wolfSSL_set_msg_callback

int wolfSSL_set_msg_callback(
    WOLFSSL * ssl,
    SSL_Msg_Cb cb
)

This function sets a callback in the ssl. The callback is to observe handshake messages. NULL value of cb resets the callback.

Parameters:

• ssl WOLFSSL structure to set callback argument.

See: wolfSSL_set_msg_callback_arg

Return:

• SSL_SUCCESS On success.
• SSL_FAILURE If an NULL ssl passed in.

Example

static cb(int write_p, int version, int content_type,
const void *buf, size_t len, WOLFSSL *ssl, void *arg)
…
WOLFSSL* ssl;
ret  = wolfSSL_set_msg_callback(ssl, cb);
// check ret

function wolfSSL_set_msg_callback_arg

int wolfSSL_set_msg_callback_arg(
    WOLFSSL * ssl,
    void * arg
)

This function sets associated callback context value in the ssl. The value is handed over to the callback argument.

Parameters:

• ssl WOLFSSL structure to set callback argument.

See: wolfSSL_set_msg_callback

Return: none No return.

Example

static cb(int write_p, int version, int content_type,
const void *buf, size_t len, WOLFSSL *ssl, void *arg)
…
WOLFSSL* ssl;
ret  = wolfSSL_set_msg_callback(ssl, cb);
// check ret
wolfSSL_set_msg_callback(ssl, arg);

function wolfSSL_X509_get_next_altname

char * wolfSSL_X509_get_next_altname(
    WOLFSSL_X509 * 
)

This function returns the next, if any, altname from the peer certificate.

Parameters:

• cert a pointer to the wolfSSL_X509 structure.

See:

• wolfSSL_X509_get_issuer_name
• wolfSSL_X509_get_subject_name

Return:

• NULL if there is not a next altname.
• cert->altNamesNext->name from the WOLFSSL_X509 structure that is a string value from the altName list is returned if it exists.

Example

WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
                                                    DYNAMIC_TYPE_X509);
…
int x509NextAltName = wolfSSL_X509_get_next_altname(x509);
if(x509NextAltName == NULL){
        //There isn’t another alt name
}

function wolfSSL_X509_get_notBefore

WOLFSSL_ASN1_TIME * wolfSSL_X509_get_notBefore(
    WOLFSSL_X509 * 
)

The function checks to see if x509 is NULL and if it’s not, it returns the notBefore member of the x509 struct.

Parameters:

• x509 a pointer to the WOLFSSL_X509 struct.

See: wolfSSL_X509_get_notAfter

Return:

• pointer to struct with ASN1_TIME to the notBefore member of the x509 struct.
• NULL the function returns NULL if the x509 structure is NULL.

Example

WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,
DYNAMIC_TYPE_X509) ;
…
const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notBefore(x509);
if(notAfter == NULL){
        //The x509 object was NULL
}

function wolfSSL_connect

int wolfSSL_connect(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_get_error
• wolfSSL_accept

Return:

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

Example

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

function wolfSSL_send_hrr_cookie

int wolfSSL_send_hrr_cookie(
    WOLFSSL * ssl,
    const unsigned char * secret,
    unsigned int secretSz
)

This function is called on the server side to indicate that a HelloRetryRequest message must contain a Cookie and, in case of using protocol DTLS v1.3, that the handshake will always include a cookie exchange. Please note that when using protocol DTLS v1.3, the cookie exchange is enabled by default. The Cookie holds a hash of the current transcript so that another server process can handle the ClientHello in reply. The secret is used when generating the integrity check on the Cookie data.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• secret a pointer to a buffer holding the secret. Passing NULL indicates to generate a new random secret.
• secretSz Size of the secret in bytes. Passing 0 indicates to use the default size: WC_SHA256_DIGEST_SIZE (or WC_SHA_DIGEST_SIZE when SHA-256 not available).

See:

• wolfSSL_new
• wolfSSL_disable_hrr_cookie

Return:

• BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a client.
• WOLFSSL_SUCCESS if successful.
• MEMORY_ERROR if allocating dynamic memory for storing secret failed.
• Another -ve value on internal error.

Example

int ret;
WOLFSSL* ssl;
char secret[32];
...
ret = wolfSSL__send_hrr_cookie(ssl, secret, sizeof(secret));
if (ret != WOLFSSL_SUCCESS) {
    // failed to set use of Cookie and secret
}

function wolfSSL_disable_hrr_cookie

int wolfSSL_disable_hrr_cookie(
    WOLFSSL * ssl
)

This function is called on the server side to indicate that a HelloRetryRequest message must NOT contain a Cookie and that, if using protocol DTLS v1.3, a cookie exchange will not be included in the handshake. Please note that not doing a cookie exchange when using protocol DTLS v1.3 can make the server susceptible to DoS/Amplification attacks.

Parameters:

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

See: wolfSSL_send_hrr_cookie

Return:

• WOLFSSL_SUCCESS if successful
• BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3
• SIDE_ERROR if invoked on client

function wolfSSL_CTX_no_ticket_TLSv13

int wolfSSL_CTX_no_ticket_TLSv13(
    WOLFSSL_CTX * ctx
)

This function is called on the server to stop it from sending a resumption session ticket once the handshake is complete.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

See: wolfSSL_no_ticket_TLSv13

Return:

• BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a client.
• 0 if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_no_ticket_TLSv13(ctx);
if (ret != 0) {
    // failed to set no ticket
}

function wolfSSL_no_ticket_TLSv13

int wolfSSL_no_ticket_TLSv13(
    WOLFSSL * ssl
)

This function is called on the server to stop it from sending a resumption session ticket once the handshake is complete.

Parameters:

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

See: wolfSSL_CTX_no_ticket_TLSv13

Return:

• BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a client.
• 0 if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_no_ticket_TLSv13(ssl);
if (ret != 0) {
    // failed to set no ticket
}

function wolfSSL_CTX_no_dhe_psk

int wolfSSL_CTX_no_dhe_psk(
    WOLFSSL_CTX * ctx
)

This function is called on a TLS v1.3 wolfSSL context to disallow Diffie-Hellman (DH) style key exchanges when handshakes are using pre-shared keys for authentication.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

See: wolfSSL_no_dhe_psk

Return:

• BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
• 0 if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_no_dhe_psk(ctx);
if (ret != 0) {
    // failed to set no DHE for PSK handshakes
}

function wolfSSL_no_dhe_psk

int wolfSSL_no_dhe_psk(
    WOLFSSL * ssl
)

This function is called on a TLS v1.3 client or server wolfSSL to disallow Diffie-Hellman (DH) style key exchanges when handshakes are using pre-shared keys for authentication.

Parameters:

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

See: wolfSSL_CTX_no_dhe_psk

Return:

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

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_no_dhe_psk(ssl);
if (ret != 0) {
    // failed to set no DHE for PSK handshakes
}

function wolfSSL_update_keys

int wolfSSL_update_keys(
    WOLFSSL * ssl
)

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

Parameters:

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

See: wolfSSL_write

Return:

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

Example

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

function wolfSSL_key_update_response

int wolfSSL_key_update_response(
    WOLFSSL * ssl,
    int * required
)

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

Parameters:

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

See: wolfSSL_update_keys

Return:

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

Example

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

function wolfSSL_CTX_allow_post_handshake_auth

int wolfSSL_CTX_allow_post_handshake_auth(
    WOLFSSL_CTX * ctx
)

This function is called on a TLS v1.3 client wolfSSL context to allow a client certificate to be sent post handshake upon request from server. This is useful when connecting to a web server that has some pages that require client authentication and others that don't.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().

See:

• wolfSSL_allow_post_handshake_auth
• wolfSSL_request_certificate

Return:

• BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a server.
• 0 if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_allow_post_handshake_auth(ctx);
if (ret != 0) {
    // failed to allow post handshake authentication
}

function wolfSSL_allow_post_handshake_auth

int wolfSSL_allow_post_handshake_auth(
    WOLFSSL * ssl
)

This function is called on a TLS v1.3 client wolfSSL to allow a client certificate to be sent post handshake upon request from server. A Post-Handshake Client Authentication extension is sent in the ClientHello. This is useful when connecting to a web server that has some pages that require client authentication and others that don't.

Parameters:

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

See:

• wolfSSL_CTX_allow_post_handshake_auth
• wolfSSL_request_certificate

Return:

• BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a server.
• 0 if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_allow_post_handshake_auth(ssl);
if (ret != 0) {
    // failed to allow post handshake authentication
}

function wolfSSL_request_certificate

int wolfSSL_request_certificate(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_allow_post_handshake_auth
• wolfSSL_write

Return:

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

Example

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

function wolfSSL_CTX_set1_groups_list

int wolfSSL_CTX_set1_groups_list(
    WOLFSSL_CTX * ctx,
    char * list
)

This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• list a string that is a colon-delimited list of elliptic curve groups.

See:

• wolfSSL_set1_groups_list
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_UseKeyShare
• wolfSSL_preferred_group

Return:

• WOLFSSL_FAILURE if pointer parameters are NULL, there are more than WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not using TLS v1.3.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
const char* list = "P-384:P-256";
...
ret = wolfSSL_CTX_set1_groups_list(ctx, list);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_set1_groups_list

int wolfSSL_set1_groups_list(
    WOLFSSL * ssl,
    char * list
)

This function sets the list of elliptic curve groups to allow on a wolfSSL in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• list a string that is a colon separated list of key exchange groups.

See:

• wolfSSL_CTX_set1_groups_list
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_UseKeyShare
• wolfSSL_preferred_group

Return:

• WOLFSSL_FAILURE if pointer parameters are NULL, there are more than WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not using TLS v1.3.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
const char* list = "P-384:P-256";
...
ret = wolfSSL_CTX_set1_groups_list(ssl, list);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_preferred_group

int wolfSSL_preferred_group(
    WOLFSSL * ssl
)

This function returns the key exchange group the client prefers to use in the TLS v1.3 handshake. Call this function to after a handshake is complete to determine which group the server prefers so that this information can be used in future connections to pre-generate a key pair for key exchange.

Parameters:

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

See:

• wolfSSL_UseKeyShare
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_CTX_set1_groups_list
• wolfSSL_set1_groups_list

Return:

• BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
• SIDE_ERROR if called with a server.
• NOT_READY_ERROR if called before handshake is complete.
• Group identifier if successful.

Example

int ret;
int group;
WOLFSSL* ssl;
...
ret = wolfSSL_CTX_set1_groups_list(ssl)
if (ret < 0) {
    // failed to get group
}
group = ret;

function wolfSSL_CTX_set_groups

int wolfSSL_CTX_set_groups(
    WOLFSSL_CTX * ctx,
    int * groups,
    int count
)

This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• groups a list of key exchange groups by identifier.
• count the number of key exchange groups in groups.

See:

• wolfSSL_set_groups
• wolfSSL_UseKeyShare
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_CTX_set1_groups_list
• wolfSSL_set1_groups_list
• wolfSSL_preferred_group

Return:

• BAD_FUNC_ARG if a pointer parameter is null, the number of groups exceeds WOLFSSL_MAX_GROUP_COUNT or not using TLS v1.3.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
int count = 2;
...
ret = wolfSSL_CTX_set1_groups_list(ctx, groups, count);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_set_groups

int wolfSSL_set_groups(
    WOLFSSL * ssl,
    int * groups,
    int count
)

This function sets the list of elliptic curve groups to allow on a wolfSSL. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• groups a list of key exchange groups by identifier.
• count the number of key exchange groups in groups.

See:

• wolfSSL_CTX_set_groups
• wolfSSL_UseKeyShare
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_CTX_set1_groups_list
• wolfSSL_set1_groups_list
• wolfSSL_preferred_group

Return:

• BAD_FUNC_ARG if a pointer parameter is null, the number of groups exceeds WOLFSSL_MAX_GROUP_COUNT, any of the identifiers are unrecognized or not using TLS v1.3.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
int count = 2;
...
ret = wolfSSL_set_groups(ssl, groups, count);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_connect_TLSv13

int wolfSSL_connect_TLSv13(
    WOLFSSL * 
)

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

Parameters:

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

See:

• wolfSSL_get_error
• wolfSSL_connect
• wolfSSL_accept_TLSv13
• wolfSSL_accept

Return:

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

Example

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

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

function wolfSSL_accept_TLSv13

wolfSSL_accept_TLSv13(
    WOLFSSL * ssl
)

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

Parameters:

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

See:

• wolfSSL_get_error
• wolfSSL_connect_TLSv13
• wolfSSL_connect
• wolfSSL_accept_TLSv13
• wolfSSL_accept

Return:

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

Example

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

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

function wolfSSL_CTX_set_max_early_data

int wolfSSL_CTX_set_max_early_data(
    WOLFSSL_CTX * ctx,
    unsigned int sz
)

This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange using the wolfSSL context. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• sz the amount of early data to accept in bytes.

See:

• wolfSSL_set_max_early_data
• wolfSSL_write_early_data
• wolfSSL_read_early_data

Return:

• BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
• 0 if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_set_max_early_data(ctx, 128);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_set_max_early_data

int wolfSSL_set_max_early_data(
    WOLFSSL * ssl,
    unsigned int sz
)

This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• sz the amount of early data to accept from client in bytes.

See:

• wolfSSL_CTX_set_max_early_data
• wolfSSL_write_early_data
• wolfSSL_read_early_data

Return:

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

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_set_max_early_data(ssl, 128);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_write_early_data

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

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

Parameters:

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

See:

• wolfSSL_read_early_data
• wolfSSL_connect
• wolfSSL_connect_TLSv13

Return:

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

Example

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

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

function wolfSSL_read_early_data

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

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

Parameters:

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

See:

• wolfSSL_write_early_data
• wolfSSL_accept
• wolfSSL_accept_TLSv13

Return:

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

Example

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

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

function wolfSSL_CTX_set_psk_client_tls13_callback

void wolfSSL_CTX_set_psk_client_tls13_callback(
    WOLFSSL_CTX * ctx,
    wc_psk_client_tls13_callback cb
)

This function sets the Pre-Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.

See:

• wolfSSL_set_psk_client_tls13_callback
• wolfSSL_CTX_set_psk_server_tls13_callback
• wolfSSL_set_psk_server_tls13_callback

Example

WOLFSSL_CTX* ctx;
...
wolfSSL_CTX_set_psk_client_tls13_callback(ctx, my_psk_client_tls13_cb);

function wolfSSL_set_psk_client_tls13_callback

void wolfSSL_set_psk_client_tls13_callback(
    WOLFSSL * ssl,
    wc_psk_client_tls13_callback cb
)

This function sets the Pre-Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the options field in WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.

See:

• wolfSSL_CTX_set_psk_client_tls13_callback
• wolfSSL_CTX_set_psk_server_tls13_callback
• wolfSSL_set_psk_server_tls13_callback

Example

WOLFSSL* ssl;
...
wolfSSL_set_psk_client_tls13_callback(ssl, my_psk_client_tls13_cb);

function wolfSSL_CTX_set_psk_server_tls13_callback

void wolfSSL_CTX_set_psk_server_tls13_callback(
    WOLFSSL_CTX * ctx,
    wc_psk_server_tls13_callback cb
)

This function sets the Pre-Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the WOLFSSL_CTX structure.

Parameters:

• ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
• cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.

See:

• wolfSSL_CTX_set_psk_client_tls13_callback
• wolfSSL_set_psk_client_tls13_callback
• wolfSSL_set_psk_server_tls13_callback

Example

WOLFSSL_CTX* ctx;
...
wolfSSL_CTX_set_psk_server_tls13_callback(ctx, my_psk_client_tls13_cb);

function wolfSSL_set_psk_server_tls13_callback

void wolfSSL_set_psk_server_tls13_callback(
    WOLFSSL * ssl,
    wc_psk_server_tls13_callback cb
)

This function sets the Pre-Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the options field in WOLFSSL structure.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.

See:

• wolfSSL_CTX_set_psk_client_tls13_callback
• wolfSSL_set_psk_client_tls13_callback
• wolfSSL_CTX_set_psk_server_tls13_callback

Example

WOLFSSL* ssl;
...
wolfSSL_set_psk_server_tls13_callback(ssl, my_psk_server_tls13_cb);

function wolfSSL_UseKeyShare

int wolfSSL_UseKeyShare(
    WOLFSSL * ssl,
    word16 group
)

This function creates a key share entry from the group including generating a key pair. The KeyShare extension contains all the generated public keys for key exchange. If this function is called, then only the groups specified will be included. Call this function when a preferred group has been previously established for the server.

Parameters:

• ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
• group a key exchange group identifier.

See:

• wolfSSL_preferred_group
• wolfSSL_CTX_set1_groups_list
• wolfSSL_set1_groups_list
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_NoKeyShares

Return:

• BAD_FUNC_ARG if ssl is NULL.
• MEMORY_E when dynamic memory allocation fails.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_UseKeyShare(ssl, WOLFSSL_ECC_X25519);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set key share
}

function wolfSSL_NoKeyShares

int wolfSSL_NoKeyShares(
    WOLFSSL * ssl
)

This function is called to ensure no key shares are sent in the ClientHello. This will force the server to respond with a HelloRetryRequest if a key exchange is required in the handshake. Call this function when the expected key exchange group is not known and to avoid the generation of keys unnecessarily. Note that an extra round-trip will be required to complete the handshake when a key exchange is required.

Parameters:

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

See: wolfSSL_UseKeyShare

Return:

• BAD_FUNC_ARG if ssl is NULL.
• SIDE_ERROR if called with a server.
• WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
...
ret = wolfSSL_NoKeyShares(ssl);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set no key shares
}

function wolfTLSv1_3_server_method_ex

WOLFSSL_METHOD * wolfTLSv1_3_server_method_ex(
    void * heap
)

This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_3_server_method_ex(NULL);
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_3_client_method_ex

WOLFSSL_METHOD * wolfTLSv1_3_client_method_ex(
    void * heap
)

This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

Parameters:

• heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_3_client_method_ex(NULL);
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_3_server_method

WOLFSSL_METHOD * wolfTLSv1_3_server_method(
    void 
)

This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

See:

• wolfSSLv3_server_method
• wolfTLSv1_server_method
• wolfTLSv1_1_server_method
• wolfTLSv1_2_server_method
• wolfTLSv1_3_server_method_ex
• wolfDTLSv1_server_method
• wolfSSLv23_server_method
• wolfSSL_CTX_new

Return:

• If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_3_server_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_3_client_method

WOLFSSL_METHOD * wolfTLSv1_3_client_method(
    void 
)

This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().

See:

• wolfSSLv3_client_method
• wolfTLSv1_client_method
• wolfTLSv1_1_client_method
• wolfTLSv1_2_client_method
• wolfTLSv1_3_client_method_ex
• wolfDTLSv1_client_method
• wolfSSLv23_client_method
• wolfSSL_CTX_new

Return:

• If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure.
• FAIL If memory allocation fails when calling XMALLOC, the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM).

Example

#include <wolfssl/ssl.h>

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;

method = wolfTLSv1_3_client_method();
if (method == NULL) {
    // unable to get method
}

ctx = wolfSSL_CTX_new(method);
...

function wolfTLSv1_3_method_ex

WOLFSSL_METHOD * wolfTLSv1_3_method_ex(
    void * heap
)

This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).

Parameters:

• heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.

See:

• wolfSSL_new
• wolfSSL_free

Return:

• WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD pointer
• NULL Null if memory allocation error or failure to create method

Example

WOLFSSL* ctx;
ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
// check ret value

function wolfTLSv1_3_method

WOLFSSL_METHOD * wolfTLSv1_3_method(
    void 
)

This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).

See:

• wolfSSL_new
• wolfSSL_free

Return:

• WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD pointer
• NULL Null if memory allocation error or failure to create method

Example

WOLFSSL* ctx;
ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method());
// check ret value

function wolfSSL_CTX_set_ephemeral_key

int wolfSSL_CTX_set_ephemeral_key(
    WOLFSSL_CTX * ctx,
    int keyAlgo,
    const char * key,
    unsigned int keySz,
    int format
)

This function sets a fixed / static ephemeral key for testing only.

Parameters:

• ctx A WOLFSSL_CTX context pointer
• keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
• key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
• keySz key size (should be 0 for "key" arg is file path)
• format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM

See: wolfSSL_CTX_get_ephemeral_key

Return: 0 Key loaded successfully

function wolfSSL_set_ephemeral_key

int wolfSSL_set_ephemeral_key(
    WOLFSSL * ssl,
    int keyAlgo,
    const char * key,
    unsigned int keySz,
    int format
)

This function sets a fixed / static ephemeral key for testing only.

Parameters:

• ssl A WOLFSSL object pointer
• keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
• key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
• keySz key size (should be 0 for "key" arg is file path)
• format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM

See: wolfSSL_get_ephemeral_key

Return: 0 Key loaded successfully

function wolfSSL_CTX_get_ephemeral_key

int wolfSSL_CTX_get_ephemeral_key(
    WOLFSSL_CTX * ctx,
    int keyAlgo,
    const unsigned char ** key,
    unsigned int * keySz
)

This function returns pointer to loaded key as ASN.1/DER.

Parameters:

• ctx A WOLFSSL_CTX context pointer
• keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
• key key buffer pointer
• keySz key size pointer

See: wolfSSL_CTX_set_ephemeral_key

Return: 0 Key returned successfully

function wolfSSL_get_ephemeral_key

int wolfSSL_get_ephemeral_key(
    WOLFSSL * ssl,
    int keyAlgo,
    const unsigned char ** key,
    unsigned int * keySz
)

This function returns pointer to loaded key as ASN.1/DER.

Parameters:

• ssl A WOLFSSL object pointer
• keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
• key key buffer pointer
• keySz key size pointer

See: wolfSSL_set_ephemeral_key

Return: 0 Key returned successfully

function wolfSSL_RSA_sign_generic_padding

int wolfSSL_RSA_sign_generic_padding(
    int type,
    const unsigned char * m,
    unsigned int mLen,
    unsigned char * sigRet,
    unsigned int * sigLen,
    WOLFSSL_RSA * rsa,
    int flag,
    int padding
)

Sign a message with the chosen message digest, padding, and RSA key.

Parameters:

• type Hash NID
• m Message to sign. Most likely this will be the digest of the message to sign
• mLen Length of message to sign
• sigRet Output buffer
• sigLen On Input: length of sigRet buffer On Output: length of data written to sigRet
• rsa RSA key used to sign the input
• flag 1: Output the signature 0: Output the value that the unpadded signature should be compared to. Note: for RSA_PKCS1_PSS_PADDING the wc_RsaPSS_CheckPadding_ex function should be used to check the output of a Verify function.
• padding Padding to use. Only RSA_PKCS1_PSS_PADDING and RSA_PKCS1_PADDING are currently supported for signing.

Return: WOLFSSL_SUCCESS on success and c on error

function wolfSSL_dtls13_has_pending_msg

int wolfSSL_dtls13_has_pending_msg(
    WOLFSSL * ssl
)

checks if DTLSv1.3 stack has some messages sent but not yet acknowledged by the other peer

Parameters:

• ssl A WOLFSSL object pointer

Return: 1 if there are pending messages, 0 otherwise

function wolfSSL_SESSION_get_max_early_data

unsigned int wolfSSL_SESSION_get_max_early_data(
    const WOLFSSL_SESSION * s
)

Get the maximum size of Early Data from a session.

Parameters:

• s the WOLFSSL_SESSION instance.

See:

• wolfSSL_set_max_early_data
• wolfSSL_write_early_data
• wolfSSL_read_early_data

Return: the value of max_early_data that was configured in the WOLFSSL* the session was derived from.

function wolfSSL_CRYPTO_get_ex_new_index

int wolfSSL_CRYPTO_get_ex_new_index(
    int ,
    void * ,
    void * ,
    void * ,
    void * 
)

Get a new index for external data. This entry applies also for the following API:

Parameters:

• All input parameters are ignored. The callback functions are not supported with wolfSSL.

Return: The new index value to be used with the external data API for this object class.

• wolfSSL_CTX_get_ex_new_index
• wolfSSL_get_ex_new_index
• wolfSSL_SESSION_get_ex_new_index
• wolfSSL_X509_get_ex_new_index

function wolfSSL_CTX_set_client_cert_type

int wolfSSL_CTX_set_client_cert_type(
    WOLFSSL_CTX * ctx,
    const char * buf,
    int len
)

In case this function is called in a client side, set certificate types that can be sent to its peer. In case called in a server side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.

Parameters:

• ctx WOLFSSL_CTX object pointer
• buf A buffer where certificate types are stored
• len buf size in bytes (same as number of certificate types included) Example

int ret;
WOLFSSL_CTX* ctx;
char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
int len = sizeof(buf)/sizeof(char);
...

ret = wolfSSL_CTX_set_client_cert_type(ctx, buf, len);

See:

• wolfSSL_set_client_cert_type
• wolfSSL_CTX_set_server_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_get_negotiated_client_cert_type
• wolfSSL_get_negotiated_server_cert_type

Return:

• WOLFSSL_SUCCESS if cert types set successfully
• BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or a duplicate value is found in buf.

function wolfSSL_CTX_set_server_cert_type

int wolfSSL_CTX_set_server_cert_type(
    WOLFSSL_CTX * ctx,
    const char * buf,
    int len
)

In case this function is called in a server side, set certificate types that can be sent to its peer. In case called in a client side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.

Parameters:

• ctx WOLFSSL_CTX object pointer
• buf A buffer where certificate types are stored
• len buf size in bytes (same as number of certificate types included) Example

int ret;
WOLFSSL_CTX* ctx;
char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
int len = sizeof(buf)/sizeof(char);
...

ret = wolfSSL_CTX_set_server_cert_type(ctx, buf, len);

See:

• wolfSSL_set_client_cert_type
• wolfSSL_CTX_set_client_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_get_negotiated_client_cert_type
• wolfSSL_get_negotiated_server_cert_type

Return:

• WOLFSSL_SUCCESS if cert types set successfully
• BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or a duplicate value is found in buf.

function wolfSSL_set_client_cert_type

int wolfSSL_set_client_cert_type(
    WOLFSSL * ssl,
    const char * buf,
    int len
)

In case this function is called in a client side, set certificate types that can be sent to its peer. In case called in a server side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.

Parameters:

• ssl WOLFSSL object pointer
• buf A buffer where certificate types are stored
• len buf size in bytes (same as number of certificate types included) Example

int ret;
WOLFSSL* ssl;
char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
int len = sizeof(buf)/sizeof(char);
...

ret = wolfSSL_set_client_cert_type(ssl, buf, len);

See:

• wolfSSL_CTX_set_client_cert_type
• wolfSSL_CTX_set_server_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_get_negotiated_client_cert_type
• wolfSSL_get_negotiated_server_cert_type

Return:

• WOLFSSL_SUCCESS if cert types set successfully
• BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or a duplicate value is found in buf.

function wolfSSL_set_server_cert_type

int wolfSSL_set_server_cert_type(
    WOLFSSL * ssl,
    const char * buf,
    int len
)

In case this function is called in a server side, set certificate types that can be sent to its peer. In case called in a client side, set certificate types that can be acceptable from its peer. Put cert types in the buffer with prioritised order. To reset the settings to default, pass NULL for the buffer or pass zero for len. By default, certificate type is only X509. In case both side intend to send or accept "Raw public key" cert, WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.

Parameters:

• ctx WOLFSSL_CTX object pointer
• buf A buffer where certificate types are stored
• len buf size in bytes (same as number of certificate types included) Example

int ret;
WOLFSSL* ssl;
char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
int len = sizeof(buf)/sizeof(char);
...

ret = wolfSSL_set_server_cert_type(ssl, buf, len);

See:

• wolfSSL_set_client_cert_type
• wolfSSL_CTX_set_server_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_get_negotiated_client_cert_type
• wolfSSL_get_negotiated_server_cert_type

Return:

• WOLFSSL_SUCCESS if cert types set successfully
• BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or a duplicate value is found in buf.

function wolfSSL_get_negotiated_client_cert_type

int wolfSSL_get_negotiated_client_cert_type(
    WOLFSSL * ssl,
    int * tp
)

This function returns the result of the client certificate type negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is returned as the certificate type.

Parameters:

• ssl WOLFSSL object pointer
• tp A buffer where a certificate type is to be returned. One of three certificate types will be returned: WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.

See:

• wolfSSL_set_client_cert_type
• wolfSSL_CTX_set_client_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_CTX_set_server_cert_type
• wolfSSL_get_negotiated_server_cert_type

Return:

• WOLFSSL_SUCCESS if a negotiated certificate type could be got
• BAD_FUNC_ARG if NULL was passed for ctx or tp

Example

int ret;
WOLFSSL* ssl;
int tp;
...

ret = wolfSSL_get_negotiated_client_cert_type(ssl, &tp);

function wolfSSL_get_negotiated_server_cert_type

int wolfSSL_get_negotiated_server_cert_type(
    WOLFSSL * ssl,
    int * tp
)

This function returns the result of the server certificate type negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is returned as the certificate type.

Parameters:

• ssl WOLFSSL object pointer
• tp A buffer where a certificate type is to be returned. One of three certificate types will be returned: WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN. Example

  int ret;
  WOLFSSL* ssl;
  int tp;
　...

  ret = wolfSSL_get_negotiated_server_cert_type(ssl, &tp);

See:

• wolfSSL_set_client_cert_type
• wolfSSL_CTX_set_client_cert_type
• wolfSSL_set_server_cert_type
• wolfSSL_CTX_set_server_cert_type
• wolfSSL_get_negotiated_client_cert_type

Return:

• WOLFSSL_SUCCESS if a negotiated certificate type could be got
• BAD_FUNC_ARG if NULL was passed for ctx or tp

function wolfSSL_dtls_cid_use

int wolfSSL_dtls_cid_use(
    WOLFSSL * ssl
)

Enable use of ConnectionID extensions for the SSL object. See RFC 9146 and RFC 9147.

Parameters:

• ssl A WOLFSSL object pointer

See:

• wolfSSL_dtls_cid_is_enabled
• wolfSSL_dtls_cid_set
• wolfSSL_dtls_cid_get_rx_size
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx_size
• wolfSSL_dtls_cid_get_tx

Return: WOLFSSL_SUCCESS on success, error code otherwise

function wolfSSL_dtls_cid_is_enabled

int wolfSSL_dtls_cid_is_enabled(
    WOLFSSL * ssl
)

If invoked after the handshake is complete it checks if ConnectionID was successfully negotiated for the SSL object. See RFC 9146 and RFC 9147.

Parameters:

• ssl A WOLFSSL object pointer

See:

• wolfSSL_dtls_cid_use
• wolfSSL_dtls_cid_set
• wolfSSL_dtls_cid_get_rx_size
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx_size
• wolfSSL_dtls_cid_get_tx

Return: 1 if ConnectionID was correctly negotiated, 0 otherwise

function wolfSSL_dtls_cid_set

int wolfSSL_dtls_cid_set(
    WOLFSSL * ssl,
    unsigned char * cid,
    unsigned int size
)

Set the ConnectionID used by the other peer to send records in this connection. See RFC 9146 and RFC 9147. The ConnectionID must be at maximum DTLS_CID_MAX_SIZE, that is an tunable compile time define, and it can't never be bigger than 255 bytes.

Parameters:

• ssl A WOLFSSL object pointern
• cid the ConnectionID to be used
• size of the ConnectionID provided

See:

• wolfSSL_dtls_cid_use
• wolfSSL_dtls_cid_is_enabled
• wolfSSL_dtls_cid_get_rx_size
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx_size
• wolfSSL_dtls_cid_get_tx

Return: WOLFSSL_SUCCESS if ConnectionID was correctly set, error code otherwise

function wolfSSL_dtls_cid_get_rx_size

int wolfSSL_dtls_cid_get_rx_size(
    WOLFSSL * ssl,
    unsigned int * size
)

Get the size of the ConnectionID used by the other peer to send records in this connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.

Parameters:

• ssl A WOLFSSL object pointern
• size a pointer to an unsigned int where the size will be stored

See:

• wolfSSL_dtls_cid_use
• wolfSSL_dtls_cid_is_enabled
• wolfSSL_dtls_cid_set
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx_size
• wolfSSL_dtls_cid_get_tx

Return: WOLFSSL_SUCCESS if ConnectionID was correctly negotiated, error code otherwise

function wolfSSL_dtls_cid_get_rx

int wolfSSL_dtls_cid_get_rx(
    WOLFSSL * ssl,
    unsigned char * buffer,
    unsigned int bufferSz
)

Copy the ConnectionID used by the other peer to send records in this connection into the buffer pointed by the parameter buffer. See RFC 9146 and RFC.

1. The available space in the buffer need to be provided in bufferSz. WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code otherwise

sslA WOLFSSL object pointern

bufferA buffer where the ConnectionID will be copied

bufferSzavailable space in buffer

wolfSSL_dtls_cid_use

wolfSSL_dtls_cid_is_enabled

wolfSSL_dtls_cid_set

wolfSSL_dtls_cid_get_rx_size

wolfSSL_dtls_cid_get_tx_size

wolfSSL_dtls_cid_get_tx

function wolfSSL_dtls_cid_get_tx_size

int wolfSSL_dtls_cid_get_tx_size(
    WOLFSSL * ssl,
    unsigned int * size
)

Get the size of the ConnectionID used to send records in this connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.

Parameters:

• ssl A WOLFSSL object pointern
• size a pointer to an unsigned int where the size will be stored

See:

• wolfSSL_dtls_cid_use
• wolfSSL_dtls_cid_is_enabled
• wolfSSL_dtls_cid_set
• wolfSSL_dtls_cid_get_rx_size
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx

Return: WOLFSSL_SUCCESS if ConnectionID size was correctly stored, error code otherwise

function wolfSSL_dtls_cid_get_tx

int wolfSSL_dtls_cid_get_tx(
    WOLFSSL * ssl,
    unsigned char * buffer,
    unsigned int bufferSz
)

Copy the ConnectionID used when sending records in this connection into the buffer pointer by the parameter buffer. See RFC 9146 and RFC 9147. The available size need to be provided in bufferSz.

Parameters:

• ssl A WOLFSSL object pointern
• buffer A buffer where the ConnectionID will be copied
• bufferSz available space in buffer

See:

• wolfSSL_dtls_cid_use
• wolfSSL_dtls_cid_is_enabled
• wolfSSL_dtls_cid_set
• wolfSSL_dtls_cid_get_rx_size
• wolfSSL_dtls_cid_get_rx
• wolfSSL_dtls_cid_get_tx_size

Return: WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code otherwise

function wolfSSL_get_client_suites_sigalgs

int wolfSSL_get_client_suites_sigalgs(
    const WOLFSSL * ssl,
    const byte ** suites,
    word16 * suiteSz,
    const byte ** hashSigAlgo,
    word16 * hashSigAlgoSz
)

This function returns the raw list of ciphersuites and signature algorithms offered by the client. The lists are only stored and returned inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to be able to dynamically load certificates and keys based on the available ciphersuites and signature algorithms.

Parameters:

• ssl The WOLFSSL object to extract the lists from.
• optional suites Raw and unfiltered list of client ciphersuites
• optional suiteSz Size of suites in bytes
• optional hashSigAlgo Raw and unfiltered list of client signature algorithms
• optional hashSigAlgoSz Size of hashSigAlgo in bytes

See:

• wolfSSL_get_ciphersuite_info
• wolfSSL_get_sigalg_info

Return:

• WOLFSSL_SUCCESS when suites available
• WOLFSSL_FAILURE when suites not available

Example

int certCB(WOLFSSL* ssl, void* arg)
{
    const byte* suites = NULL;
    word16 suiteSz = 0;
    const byte* hashSigAlgo = NULL;
    word16 hashSigAlgoSz = 0;

    wolfSSL_get_client_suites_sigalgs(ssl, &suites, &suiteSz, &hashSigAlgo,
            &hashSigAlgoSz);

    // Choose certificate to load based on ciphersuites and sigalgs
}

WOLFSSL* ctx;
ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
wolfSSL_CTX_set_cert_cb(ctx, certCB, NULL);

function wolfSSL_get_ciphersuite_info

WOLFSSL_CIPHERSUITE_INFO wolfSSL_get_ciphersuite_info(
    byte first,
    byte second
)

This returns information about the ciphersuite directly from the raw ciphersuite bytes.

Parameters:

• first First byte of the ciphersuite
• second Second byte of the ciphersuite

See:

• wolfSSL_get_client_suites_sigalgs
• wolfSSL_get_sigalg_info

Return: WOLFSSL_CIPHERSUITE_INFO A struct containing information about the type of authentication used in the ciphersuite.

Example

WOLFSSL_CIPHERSUITE_INFO info =
        wolfSSL_get_ciphersuite_info(suites[0], suites[1]);
if (info.rsaAuth)
    haveRSA = 1;
else if (info.eccAuth)
    haveECC = 1;

function wolfSSL_get_sigalg_info

int wolfSSL_get_sigalg_info(
    byte first,
    byte second,
    int * hashAlgo,
    int * sigAlgo
)

This returns information about the hash and signature algorithm directly from the raw ciphersuite bytes.

Parameters:

• first First byte of the hash and signature algorithm
• second Second byte of the hash and signature algorithm
• hashAlgo The enum wc_HashType of the MAC algorithm
• sigAlgo The enum Key_Sum of the authentication algorithm

See:

• wolfSSL_get_client_suites_sigalgs
• wolfSSL_get_ciphersuite_info

Return:

• 0 when info was correctly set
• BAD_FUNC_ARG when either input parameters are NULL or the bytes are not a recognized sigalg suite

Example

enum wc_HashType hashAlgo;
enum Key_Sum sigAlgo;

wolfSSL_get_sigalg_info(hashSigAlgo[idx+0], hashSigAlgo[idx+1],
        &hashAlgo, &sigAlgo);

if (sigAlgo == RSAk || sigAlgo == RSAPSSk)
    haveRSA = 1;
else if (sigAlgo == ECDSAk)
    haveECC = 1;

Source code

WOLFSSL_METHOD *wolfDTLSv1_2_client_method_ex(void* heap);

WOLFSSL_METHOD *wolfSSLv23_method(void);

WOLFSSL_METHOD *wolfSSLv3_server_method(void);

WOLFSSL_METHOD *wolfSSLv3_client_method(void);

WOLFSSL_METHOD *wolfTLSv1_server_method(void);

WOLFSSL_METHOD *wolfTLSv1_client_method(void);

WOLFSSL_METHOD *wolfTLSv1_1_server_method(void);

WOLFSSL_METHOD *wolfTLSv1_1_client_method(void);

WOLFSSL_METHOD *wolfTLSv1_2_server_method(void);

WOLFSSL_METHOD *wolfTLSv1_2_client_method(void);

WOLFSSL_METHOD *wolfDTLSv1_client_method(void);

WOLFSSL_METHOD *wolfDTLSv1_server_method(void);
WOLFSSL_METHOD *wolfDTLSv1_3_server_method(void);
WOLFSSL_METHOD* wolfDTLSv1_3_client_method(void);
WOLFSSL_METHOD *wolfDTLS_server_method(void);
WOLFSSL_METHOD *wolfDTLS_client_method(void);
WOLFSSL_METHOD *wolfDTLSv1_2_server_method(void);

int wolfSSL_use_old_poly(WOLFSSL* ssl, int value);

int wolfSSL_dtls_import(WOLFSSL* ssl, unsigned char* buf,
                                                               unsigned int sz);


int wolfSSL_tls_import(WOLFSSL* ssl, const unsigned char* buf,
        unsigned int sz);

int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx,
                                                           wc_dtls_export func);

int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func);

int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf,
                                                              unsigned int* sz);

int wolfSSL_tls_export(WOLFSSL* ssl, unsigned char* buf,
        unsigned int* sz);

int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx,
                                            wolfSSL_method_func method,
                                            unsigned char* buf, unsigned int sz,
                                            int flag, int max);

int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx,
                                                 WOLFSSL_MEM_STATS* mem_stats);

int wolfSSL_is_static_memory(WOLFSSL* ssl,
                                            WOLFSSL_MEM_CONN_STATS* mem_stats);

int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX* ctx, const char* file,
                                     int format);

int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);

int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file,
                                                const char* path);

int wolfSSL_CTX_load_verify_locations_ex(WOLFSSL_CTX* ctx, const char* file,
                                         const char* path, unsigned int flags);

const char** wolfSSL_get_system_CA_dirs(word32* num);

int wolfSSL_CTX_load_system_CA_certs(WOLFSSL_CTX* ctx);

int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX* ctx, const char* file, int type);

int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *ctx,
                                                     const char *file);

int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);

long wolfSSL_get_verify_depth(WOLFSSL* ssl);

long wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX* ctx);

int wolfSSL_use_certificate_file(WOLFSSL* ssl, const char* file, int format);

int wolfSSL_use_PrivateKey_file(WOLFSSL* ssl, const char* file, int format);

int wolfSSL_use_certificate_chain_file(WOLFSSL* ssl, const char *file);

int wolfSSL_use_RSAPrivateKey_file(WOLFSSL* ssl, const char* file, int format);

int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX* ctx,
                                          const char* file, int format);

WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*);

WOLFSSL* wolfSSL_new(WOLFSSL_CTX*);

int  wolfSSL_set_fd(WOLFSSL* ssl, int fd);

int wolfSSL_set_dtls_fd_connected(WOLFSSL* ssl, int fd);

int wolfDTLS_SetChGoodCb(WOLFSSL* ssl, ClientHelloGoodCb cb, void* user_ctx);

char* wolfSSL_get_cipher_list(int priority);

int  wolfSSL_get_ciphers(char* buf, int len);

const char* wolfSSL_get_cipher_name(WOLFSSL* ssl);

int  wolfSSL_get_fd(const WOLFSSL*);

void wolfSSL_set_using_nonblock(WOLFSSL* ssl, int nonblock);

int  wolfSSL_get_using_nonblock(WOLFSSL*);

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

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

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

int  wolfSSL_accept(WOLFSSL*);

void wolfSSL_CTX_free(WOLFSSL_CTX*);

void wolfSSL_free(WOLFSSL*);

int  wolfSSL_shutdown(WOLFSSL*);

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

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

int  wolfSSL_get_error(WOLFSSL* ssl, int ret);

int  wolfSSL_get_alert_history(WOLFSSL* ssl, WOLFSSL_ALERT_HISTORY *h);

int        wolfSSL_set_session(WOLFSSL* ssl, WOLFSSL_SESSION* session);

WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);

void       wolfSSL_flush_sessions(WOLFSSL_CTX* ctx, long tm);

int        wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char* id,
                                         int len, int newSession);

int wolfSSL_GetSessionIndex(WOLFSSL* ssl);

int wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION* session);

    WOLFSSL_X509_CHAIN* wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION* session);

void wolfSSL_CTX_set_verify(WOLFSSL_CTX* ctx, int mode,
                                      VerifyCallback verify_callback);

void wolfSSL_set_verify(WOLFSSL* ssl, int mode, VerifyCallback verify_callback);

void wolfSSL_SetCertCbCtx(WOLFSSL* ssl, void* ctx);

void wolfSSL_CTX_SetCertCbCtx(WOLFSSL_CTX* ctx, void* userCtx);

int  wolfSSL_pending(WOLFSSL*);

void wolfSSL_load_error_strings(void);

int  wolfSSL_library_init(void);

int wolfSSL_SetDevId(WOLFSSL* ssl, int devId);

int wolfSSL_CTX_SetDevId(WOLFSSL_CTX* ctx, int devId);

int wolfSSL_CTX_GetDevId(WOLFSSL_CTX* ctx, WOLFSSL* ssl);

long wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX* ctx, long mode);

int  wolfSSL_set_session_secret_cb(WOLFSSL* ssl, SessionSecretCb cb, void* ctx);

int  wolfSSL_save_session_cache(const char* fname);

int  wolfSSL_restore_session_cache(const char* fname);

int  wolfSSL_memsave_session_cache(void* mem, int sz);

int  wolfSSL_memrestore_session_cache(const void* mem, int sz);

int  wolfSSL_get_session_cache_memsize(void);

int  wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX* ctx, const char* fname);

int  wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX* ctx, const char* fname);

int  wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX* ctx, void* mem, int sz, int* used);

int  wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX* ctx, const void* mem, int sz);

int  wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX* ctx);

int  wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX* ctx, const char* list);

int  wolfSSL_set_cipher_list(WOLFSSL* ssl, const char* list);

void wolfSSL_dtls_set_using_nonblock(WOLFSSL* ssl, int nonblock);
int  wolfSSL_dtls_get_using_nonblock(WOLFSSL* ssl);
int  wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl);
int  wolfSSL_dtls13_use_quick_timeout(WOLFSSL *ssl);
void  wolfSSL_dtls13_set_send_more_acks(WOLFSSL *ssl, int value);

int  wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int);

int  wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int);

int  wolfSSL_dtls_got_timeout(WOLFSSL* ssl);

int wolfSSL_dtls_retransmit(WOLFSSL* ssl);

int  wolfSSL_dtls(WOLFSSL* ssl);

int  wolfSSL_dtls_set_peer(WOLFSSL* ssl, void* peer, unsigned int peerSz);

int  wolfSSL_dtls_get_peer(WOLFSSL* ssl, void* peer, unsigned int* peerSz);

char* wolfSSL_ERR_error_string(unsigned long errNumber, char* data);

void  wolfSSL_ERR_error_string_n(unsigned long e, char* buf,
                                           unsigned long sz);

int  wolfSSL_get_shutdown(const WOLFSSL* ssl);

int  wolfSSL_session_reused(WOLFSSL* ssl);

int  wolfSSL_is_init_finished(WOLFSSL* ssl);

const char*  wolfSSL_get_version(WOLFSSL* ssl);

int  wolfSSL_get_current_cipher_suite(WOLFSSL* ssl);

WOLFSSL_CIPHER*  wolfSSL_get_current_cipher(WOLFSSL* ssl);

const char*  wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher);

const char*  wolfSSL_get_cipher(WOLFSSL*);

WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl);

WOLFSSL_METHOD* wolfSSLv23_client_method(void);

int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio,void* p);

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

int wolfSSL_BIO_set_close(WOLFSSL_BIO *b, long flag);

WOLFSSL_BIO_METHOD *wolfSSL_BIO_s_socket(void);

int  wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO *b, long size);

int  wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO *b1, WOLFSSL_BIO *b2);

int  wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *bio);

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

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

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

int  wolfSSL_BIO_reset(WOLFSSL_BIO *bio);

int  wolfSSL_BIO_seek(WOLFSSL_BIO *bio, int ofs);

int  wolfSSL_BIO_write_filename(WOLFSSL_BIO *bio, char *name);

long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO *bio, int v);

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

char*       wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME* name, char* in, int sz);

WOLFSSL_X509_NAME*  wolfSSL_X509_get_issuer_name(WOLFSSL_X509* cert);

WOLFSSL_X509_NAME*  wolfSSL_X509_get_subject_name(WOLFSSL_X509* cert);

int  wolfSSL_X509_get_isCA(WOLFSSL_X509* cert);

int wolfSSL_X509_NAME_get_text_by_NID(WOLFSSL_X509_NAME* name, int nid,
                                      char* buf, int len);

int wolfSSL_X509_get_signature_type(WOLFSSL_X509* cert);

void wolfSSL_X509_free(WOLFSSL_X509* x509);

int wolfSSL_X509_get_signature(WOLFSSL_X509* x509, unsigned char* buf, int* bufSz);

int wolfSSL_X509_STORE_add_cert(WOLFSSL_X509_STORE* store, WOLFSSL_X509* x509);

WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain(
                                                   WOLFSSL_X509_STORE_CTX* ctx);

int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store,
                                                            unsigned long flag);

const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509);

const byte* wolfSSL_X509_notAfter(WOLFSSL_X509* x509);

WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGER *ai,
                                       WOLFSSL_BIGNUM *bn);

long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX* ctx, WOLFSSL_X509* x509);

int  wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX* ctx);

int  wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX* ctx, int v);

long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX* ctx, void* arg);

long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(
        WOLFSSL_CTX* ctx, void* arg);

long wolfSSL_set_options(WOLFSSL *s, long op);

long wolfSSL_get_options(const WOLFSSL *ssl);

long wolfSSL_set_tlsext_debug_arg(WOLFSSL *ssl, void *arg);

long wolfSSL_set_tlsext_status_type(WOLFSSL *s, int type);

long wolfSSL_get_verify_result(const WOLFSSL *ssl);

void  wolfSSL_ERR_print_errors_fp(XFILE fp, int err);

void  wolfSSL_ERR_print_errors_cb (
        int (*cb)(const char *str, size_t len, void *u), void *u);

void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX* ctx,
                                                    wc_psk_client_callback cb);

void wolfSSL_set_psk_client_callback(WOLFSSL* ssl,
                                                    wc_psk_client_callback);

const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*);

const char* wolfSSL_get_psk_identity(const WOLFSSL*);

int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX* ctx, const char* hint);

int wolfSSL_use_psk_identity_hint(WOLFSSL* ssl, const char* hint);

void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX* ctx,
                                                    wc_psk_server_callback cb);

void wolfSSL_set_psk_server_callback(WOLFSSL* ssl,
                                                    wc_psk_server_callback cb);


int wolfSSL_set_psk_callback_ctx(WOLFSSL* ssl, void* psk_ctx);

int wolfSSL_CTX_set_psk_callback_ctx(WOLFSSL_CTX* ctx, void* psk_ctx);

void* wolfSSL_get_psk_callback_ctx(WOLFSSL* ssl);

void* wolfSSL_CTX_get_psk_callback_ctx(WOLFSSL_CTX* ctx);

int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*);

WOLFSSL_METHOD *wolfSSLv23_server_method(void);

int  wolfSSL_state(WOLFSSL* ssl);

WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl);

int wolfSSL_want_read(WOLFSSL*);

int wolfSSL_want_write(WOLFSSL*);

int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn);

int wolfSSL_Init(void);

int wolfSSL_Cleanup(void);

const char* wolfSSL_lib_version(void);

word32 wolfSSL_lib_version_hex(void);

int wolfSSL_negotiate(WOLFSSL* ssl);

int wolfSSL_set_compression(WOLFSSL* ssl);

int wolfSSL_set_timeout(WOLFSSL* ssl, unsigned int to);

int wolfSSL_CTX_set_timeout(WOLFSSL_CTX* ctx, unsigned int to);

WOLFSSL_X509_CHAIN* wolfSSL_get_peer_chain(WOLFSSL* ssl);

int  wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN* chain);

int  wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN* chain, int idx);

unsigned char* wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN* chain, int idx);

WOLFSSL_X509* wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN* chain, int idx);

int  wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN* chain, int idx,
                                unsigned char* buf, int inLen, int* outLen);

const unsigned char* wolfSSL_get_sessionID(const WOLFSSL_SESSION* s);

int  wolfSSL_X509_get_serial_number(WOLFSSL_X509* x509, unsigned char* in,
                                    int* inOutSz);

char*  wolfSSL_X509_get_subjectCN(WOLFSSL_X509*);

const unsigned char* wolfSSL_X509_get_der(WOLFSSL_X509* x509, int* outSz);

WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notAfter(WOLFSSL_X509*);

int wolfSSL_X509_version(WOLFSSL_X509*);

WOLFSSL_X509*
        wolfSSL_X509_d2i_fp(WOLFSSL_X509** x509, FILE* file);

WOLFSSL_X509*
    wolfSSL_X509_load_certificate_file(const char* fname, int format);

unsigned char*
           wolfSSL_X509_get_device_type(WOLFSSL_X509* x509, unsigned char* in,
                                        int* inOutSz);

unsigned char*
           wolfSSL_X509_get_hw_type(WOLFSSL_X509* x509, unsigned char* in,
                                    int* inOutSz);

unsigned char*
           wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509* x509,
                                             unsigned char* in, int* inOutSz);

int  wolfSSL_connect_cert(WOLFSSL* ssl);

WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio,
                                       WC_PKCS12** pkcs12);

WC_PKCS12* wolfSSL_i2d_PKCS12_bio(WOLFSSL_BIO* bio,
                                       WC_PKCS12* pkcs12);

int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw,
     WOLFSSL_EVP_PKEY** pkey, WOLFSSL_X509** cert, WOLF_STACK_OF(WOLFSSL_X509)** ca);

int  wolfSSL_SetTmpDH(WOLFSSL* ssl, const unsigned char* p, int pSz,
                                const unsigned char* g, int gSz);

int  wolfSSL_SetTmpDH_buffer(WOLFSSL* ssl, const unsigned char* b, long sz,
                                       int format);

int  wolfSSL_SetTmpDH_file(WOLFSSL* ssl, const char* f, int format);

int  wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX* ctx, const unsigned char* p,
                                    int pSz, const unsigned char* g, int gSz);

int  wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX* ctx, const unsigned char* b,
                                           long sz, int format);

int  wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX* ctx, const char* f,
                                             int format);

int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX* ctx, word16);

int wolfSSL_SetMinDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);

int wolfSSL_CTX_SetMaxDhKey_Sz(WOLFSSL_CTX* ctx, word16 keySz_bits);

int wolfSSL_SetMaxDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);

int wolfSSL_GetDhKey_Sz(WOLFSSL*);

int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX* ctx, short keySz);

int wolfSSL_SetMinRsaKey_Sz(WOLFSSL* ssl, short keySz);

int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX* ssl, short keySz);

int wolfSSL_SetMinEccKey_Sz(WOLFSSL* ssl, short keySz);

int wolfSSL_make_eap_keys(WOLFSSL* ssl, void* key, unsigned int len,
                                                             const char* label);

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

int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX*);


int wolfSSL_CTX_UnloadIntermediateCerts(WOLFSSL_CTX* ctx);

int wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX*);

int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
                                  long sz, int format);

int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
                                   long sz, int format);


int wolfSSL_CTX_load_verify_buffer_ex(WOLFSSL_CTX* ctx,
                                      const unsigned char* in, long sz,
                                      int format, int userChain, word32 flags);

int wolfSSL_CTX_load_verify_chain_buffer_format(WOLFSSL_CTX* ctx,
                                               const unsigned char* in,
                                               long sz, int format);

int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx,
                                       const unsigned char* in, long sz,
                                       int format);

int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX* ctx,
                                      const unsigned char* in, long sz,
                                      int format);

int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX* ctx,
                                             const unsigned char* in, long sz);

int wolfSSL_use_certificate_buffer(WOLFSSL* ssl, const unsigned char* in,
                                               long sz, int format);

int wolfSSL_use_PrivateKey_buffer(WOLFSSL* ssl, const unsigned char* in,
                                               long sz, int format);

int wolfSSL_use_certificate_chain_buffer(WOLFSSL* ssl,
                                         const unsigned char* in, long sz);

int wolfSSL_UnloadCertsKeys(WOLFSSL*);

int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX*);

int wolfSSL_set_group_messages(WOLFSSL*);

void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCtx);

int   wolfSSL_DTLS_SetCookieSecret(WOLFSSL* ssl,
                                               const unsigned char* secret,
                                               unsigned int secretSz);

WC_RNG* wolfSSL_GetRNG(WOLFSSL* ssl);

int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version);

int wolfSSL_SetMinVersion(WOLFSSL* ssl, int version);

int wolfSSL_GetObjectSize(void);  /* object size based on build */
int wolfSSL_GetOutputSize(WOLFSSL* ssl, int inSz);

int wolfSSL_GetMaxOutputSize(WOLFSSL*);

int wolfSSL_SetVersion(WOLFSSL* ssl, int version);

void  wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX* ctx, CallbackMacEncrypti cb);

void  wolfSSL_SetMacEncryptCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetMacEncryptCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX* ctx,
                                               CallbackDecryptVerify cb);

void  wolfSSL_SetDecryptVerifyCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetDecryptVerifyCtx(WOLFSSL* ssl);

const unsigned char* wolfSSL_GetMacSecret(WOLFSSL* ssl, int verify);

const unsigned char* wolfSSL_GetClientWriteKey(WOLFSSL*);

const unsigned char* wolfSSL_GetClientWriteIV(WOLFSSL*);

const unsigned char* wolfSSL_GetServerWriteKey(WOLFSSL*);

const unsigned char* wolfSSL_GetServerWriteIV(WOLFSSL*);

int                  wolfSSL_GetKeySize(WOLFSSL*);

int                  wolfSSL_GetIVSize(WOLFSSL*);

int                  wolfSSL_GetSide(WOLFSSL*);

int                  wolfSSL_IsTLSv1_1(WOLFSSL*);

int                  wolfSSL_GetBulkCipher(WOLFSSL*);

int                  wolfSSL_GetCipherBlockSize(WOLFSSL*);

int                  wolfSSL_GetAeadMacSize(WOLFSSL*);

int                  wolfSSL_GetHmacSize(WOLFSSL*);

int                  wolfSSL_GetHmacType(WOLFSSL*);

int                  wolfSSL_GetCipherType(WOLFSSL*);

int wolfSSL_SetTlsHmacInner(WOLFSSL* ssl, byte* inner,
                            word32 sz, int content, int verify);

void  wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX* ctx, CallbackEccSign cb);

void  wolfSSL_SetEccSignCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetEccSignCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetEccSignCtx(WOLFSSL_CTX* ctx, void *userCtx);

void* wolfSSL_CTX_GetEccSignCtx(WOLFSSL_CTX* ctx);

void  wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX* ctx, CallbackEccVerify cb);

void  wolfSSL_SetEccVerifyCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetEccVerifyCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetRsaSignCb(WOLFSSL_CTX* ctx, CallbackRsaSign cb);

void  wolfSSL_SetRsaSignCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetRsaSignCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX* ctx, CallbackRsaVerify cb);

void  wolfSSL_SetRsaVerifyCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetRsaVerifyCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX* ctx, CallbackRsaEnc cb);

void  wolfSSL_SetRsaEncCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetRsaEncCtx(WOLFSSL* ssl);

void  wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX* ctx, CallbackRsaDec cb);

void  wolfSSL_SetRsaDecCtx(WOLFSSL* ssl, void *ctx);

void* wolfSSL_GetRsaDecCtx(WOLFSSL* ssl);

void wolfSSL_CTX_SetCACb(WOLFSSL_CTX* ctx, CallbackCACache cb);

WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew_ex(void* heap);

WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew(void);

void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER*);

int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER* cm, const char* f,
                                                                 const char* d);

int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER* cm,
                                  const unsigned char* in, long sz, int format);

int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm);

int wolfSSL_CertManagerUnloadIntermediateCerts(WOLFSSL_CERT_MANAGER* cm);

int wolfSSL_CertManagerUnload_trust_peers(WOLFSSL_CERT_MANAGER* cm);

int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER* cm, const char* f,
                                                                    int format);

int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER* cm,
                                const unsigned char* buff, long sz, int format);

void wolfSSL_CertManagerSetVerify(WOLFSSL_CERT_MANAGER* cm,
                                                             VerifyCallback vc);

int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER* cm,
                                unsigned char* der, int sz);

int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER* cm,
                                                                   int options);

int wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANAGER*);

int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER* cm,
                               const char* path, int type, int monitor);

int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER* cm,
                                     const unsigned char* buff, long sz,
                                     int type);

int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER* cm,
                                 CbMissingCRL cb);

int wolfSSL_CertManagerSetCRLUpdate_Cb(WOLFSSL_CERT_MANAGER* cm,
                                       CbUpdateCRL cb);

int wolfSSL_CertManagerGetCRLInfo(WOLFSSL_CERT_MANAGER* cm, CrlInfo* info,
    const byte* buff, long sz, int type)


int wolfSSL_CertManagerFreeCRL(WOLFSSL_CERT_MANAGER* cm);

int wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER* cm,
                                 unsigned char* der, int sz);

int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER* cm,
                                                                   int options);

int wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER*);

int wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER* cm,
                                          const char* url);

int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER* cm,
                                  CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
                                  void* ioCbCtx);

int wolfSSL_CertManagerEnableOCSPStapling(
                                                      WOLFSSL_CERT_MANAGER* cm);

int wolfSSL_EnableCRL(WOLFSSL* ssl, int options);

int wolfSSL_DisableCRL(WOLFSSL* ssl);

int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, int monitor);

int wolfSSL_SetCRL_Cb(WOLFSSL* ssl, CbMissingCRL cb);

int wolfSSL_EnableOCSP(WOLFSSL* ssl, int options);

int wolfSSL_DisableOCSP(WOLFSSL*);

int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url);

int wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
                       void* ioCbCtx);

int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options);

int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx);

int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX* ctx, const char* path, int type, int monitor);

int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX* ctx, CbMissingCRL cb);

int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX* ctx, int options);

int wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX*);

int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX* ctx, const char* url);

int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX* ctx,
                           CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
                           void* ioCbCtx);

int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX*);

void wolfSSL_KeepArrays(WOLFSSL*);

void wolfSSL_FreeArrays(WOLFSSL*);

int wolfSSL_UseSNI(WOLFSSL* ssl, unsigned char type,
                                         const void* data, unsigned short size);

int wolfSSL_CTX_UseSNI(WOLFSSL_CTX* ctx, unsigned char type,
                                         const void* data, unsigned short size);

void wolfSSL_SNI_SetOptions(WOLFSSL* ssl, unsigned char type,
                                                         unsigned char options);

void wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX* ctx,
                                     unsigned char type, unsigned char options);

int wolfSSL_SNI_GetFromBuffer(
                 const unsigned char* clientHello, unsigned int helloSz,
                 unsigned char type, unsigned char* sni, unsigned int* inOutSz);

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

unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl,
                                               unsigned char type, void** data);

int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list,
                                unsigned int protocol_name_listSz,
                                unsigned char options);

int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name,
                                         unsigned short *size);

int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char **list,
                                             unsigned short *listSz);

int wolfSSL_UseMaxFragment(WOLFSSL* ssl, unsigned char mfl);

int wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX* ctx, unsigned char mfl);

int wolfSSL_UseTruncatedHMAC(WOLFSSL* ssl);

int wolfSSL_CTX_UseTruncatedHMAC(WOLFSSL_CTX* ctx);

int wolfSSL_UseOCSPStapling(WOLFSSL* ssl,
                              unsigned char status_type, unsigned char options);

int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx,
                              unsigned char status_type, unsigned char options);

int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl,
                              unsigned char status_type, unsigned char options);

int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx,
                              unsigned char status_type, unsigned char options);

int wolfSSL_UseSupportedCurve(WOLFSSL* ssl, word16 name);

int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx,
                                                           word16 name);

int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl);

int wolfSSL_Rehandshake(WOLFSSL* ssl);

int wolfSSL_UseSessionTicket(WOLFSSL* ssl);

int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx);

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

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

int wolfSSL_set_SessionTicket_cb(WOLFSSL* ssl,
                                 CallbackSessionTicket cb, void* ctx);

int wolfSSL_send_SessionTicket(WOLFSSL* ssl);

int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx,
                                            SessionTicketEncCb);

int wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX* ctx, int);

int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void*);

void* wolfSSL_CTX_get_TicketEncCtx(WOLFSSL_CTX* ctx);

int wolfSSL_SetHsDoneCb(WOLFSSL* ssl, HandShakeDoneCb cb, void* user_ctx);

int wolfSSL_PrintSessionStats(void);

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

int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, word32 msLen,
                               const unsigned char* pms, word32 pmsLen,
                               const unsigned char* cr, const unsigned char* sr,
                               int tls1_2, int hash_type);

int wolfSSL_DeriveTlsKeys(unsigned char* key_data, word32 keyLen,
                               const unsigned char* ms, word32 msLen,
                               const unsigned char* sr, const unsigned char* cr,
                               int tls1_2, int hash_type);

int wolfSSL_connect_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,
                       TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);

int wolfSSL_accept_ex(WOLFSSL* ssl, HandShakeCallBacki hsCb,
                      TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);

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

long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE* fp);

int wolfSSL_check_private_key(const WOLFSSL* ssl);

int wolfSSL_X509_get_ext_by_NID(const WOLFSSL_X509* x509,
                                             int nid, int lastPos);

void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509,
                                                     int nid, int* c, int* idx);

int wolfSSL_X509_digest(const WOLFSSL_X509* x509,
        const WOLFSSL_EVP_MD* digest, unsigned char* buf, unsigned int* len);

int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509);

int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der,
                                                                     int derSz);

int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey);

int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl,
                                            unsigned char* der, long derSz);

int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der,
                                                                long derSz);

WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r);

int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses,
        unsigned char* out, int outSz);

int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses);

void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx,
                                                       WOLFSSL_X509_STORE* str);

WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509);

WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx);

size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO *b);

size_t wolfSSL_get_server_random(const WOLFSSL *ssl,
                                             unsigned char *out, size_t outlen);

size_t wolfSSL_get_client_random(const WOLFSSL* ssl,
                                              unsigned char* out, size_t outSz);

wc_pem_password_cb* wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX*
                                                                  ctx);

void *wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX *ctx);

WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX
        (WOLFSSL_BIO *bp, WOLFSSL_X509 **x, wc_pem_password_cb *cb, void *u);

long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX* ctx, WOLFSSL_DH* dh);

WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp,
    WOLFSSL_DSA **x, wc_pem_password_cb *cb, void *u);

unsigned long wolfSSL_ERR_peek_last_error(void);

WOLF_STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFSSL*);

long wolfSSL_CTX_clear_options(WOLFSSL_CTX* ctx, long opt);

int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr);

void* wolfSSL_get_jobject(WOLFSSL* ssl);

int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb);

int wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void* arg);

char* wolfSSL_X509_get_next_altname(WOLFSSL_X509*);

WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notBefore(WOLFSSL_X509*);

int  wolfSSL_connect(WOLFSSL* ssl);

int  wolfSSL_send_hrr_cookie(WOLFSSL* ssl,
    const unsigned char* secret, unsigned int secretSz);

int wolfSSL_disable_hrr_cookie(WOLFSSL* ssl);

int  wolfSSL_CTX_no_ticket_TLSv13(WOLFSSL_CTX* ctx);

int  wolfSSL_no_ticket_TLSv13(WOLFSSL* ssl);

int  wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX* ctx);

int  wolfSSL_no_dhe_psk(WOLFSSL* ssl);

int  wolfSSL_update_keys(WOLFSSL* ssl);

int  wolfSSL_key_update_response(WOLFSSL* ssl, int* required);

int  wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX* ctx);

int  wolfSSL_allow_post_handshake_auth(WOLFSSL* ssl);

int  wolfSSL_request_certificate(WOLFSSL* ssl);

int  wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX *ctx, char *list);

int  wolfSSL_set1_groups_list(WOLFSSL *ssl, char *list);

int  wolfSSL_preferred_group(WOLFSSL* ssl);

int  wolfSSL_CTX_set_groups(WOLFSSL_CTX* ctx, int* groups,
    int count);

int  wolfSSL_set_groups(WOLFSSL* ssl, int* groups, int count);

int  wolfSSL_connect_TLSv13(WOLFSSL*);

wolfSSL_accept_TLSv13(WOLFSSL* ssl);

int  wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX* ctx,
    unsigned int sz);

int  wolfSSL_set_max_early_data(WOLFSSL* ssl, unsigned int sz);

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

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

void wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX* ctx,
    wc_psk_client_tls13_callback cb);

void wolfSSL_set_psk_client_tls13_callback(WOLFSSL* ssl,
    wc_psk_client_tls13_callback cb);

void wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX* ctx,
    wc_psk_server_tls13_callback cb);

void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl,
    wc_psk_server_tls13_callback cb);

int wolfSSL_UseKeyShare(WOLFSSL* ssl, word16 group);

int wolfSSL_NoKeyShares(WOLFSSL* ssl);

WOLFSSL_METHOD *wolfTLSv1_3_server_method_ex(void* heap);

WOLFSSL_METHOD *wolfTLSv1_3_client_method_ex(void* heap);

WOLFSSL_METHOD *wolfTLSv1_3_server_method(void);

WOLFSSL_METHOD *wolfTLSv1_3_client_method(void);

WOLFSSL_METHOD *wolfTLSv1_3_method_ex(void* heap);

WOLFSSL_METHOD *wolfTLSv1_3_method(void);

int wolfSSL_CTX_set_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo, const char* key, unsigned int keySz, int format);

int wolfSSL_set_ephemeral_key(WOLFSSL* ssl, int keyAlgo, const char* key, unsigned int keySz, int format);

int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
    const unsigned char** key, unsigned int* keySz);

int wolfSSL_get_ephemeral_key(WOLFSSL* ssl, int keyAlgo,
    const unsigned char** key, unsigned int* keySz);

int wolfSSL_RSA_sign_generic_padding(int type, const unsigned char* m,
                               unsigned int mLen, unsigned char* sigRet,
                               unsigned int* sigLen, WOLFSSL_RSA* rsa,
                               int flag, int padding);
int wolfSSL_dtls13_has_pending_msg(WOLFSSL *ssl);

unsigned int wolfSSL_SESSION_get_max_early_data(const WOLFSSL_SESSION *s);

int wolfSSL_CRYPTO_get_ex_new_index(int, void*, void*, void*, void*);

int wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);

int wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);

int wolfSSL_set_client_cert_type(WOLFSSL* ssl, const char* buf, int len);

int wolfSSL_set_server_cert_type(WOLFSSL* ssl, const char* buf, int len);

int wolfSSL_get_negotiated_client_cert_type(WOLFSSL* ssl, int* tp);

int wolfSSL_get_negotiated_server_cert_type(WOLFSSL* ssl, int* tp);

int wolfSSL_dtls_cid_use(WOLFSSL* ssl);

int wolfSSL_dtls_cid_is_enabled(WOLFSSL* ssl);

int wolfSSL_dtls_cid_set(WOLFSSL* ssl, unsigned char* cid,
    unsigned int size);

int wolfSSL_dtls_cid_get_rx_size(WOLFSSL* ssl,
    unsigned int* size);

int wolfSSL_dtls_cid_get_rx(WOLFSSL* ssl, unsigned char* buffer,
    unsigned int bufferSz);

int wolfSSL_dtls_cid_get_tx_size(WOLFSSL* ssl, unsigned int* size);

int wolfSSL_dtls_cid_get_tx(WOLFSSL* ssl, unsigned char* buffer,
    unsigned int bufferSz);

int wolfSSL_get_client_suites_sigalgs(const WOLFSSL* ssl,
        const byte** suites, word16* suiteSz,
        const byte** hashSigAlgo, word16* hashSigAlgoSz);

WOLFSSL_CIPHERSUITE_INFO wolfSSL_get_ciphersuite_info(byte first,
        byte second);

int wolfSSL_get_sigalg_info(byte first, byte second,
        int* hashAlgo, int* sigAlgo);

---

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