wolfSSL Context and Session Set Up

Functions

	Name
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).
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_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.
long	wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX * ctx) This function gets the certificate chaining depth using the CTX structure.
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.
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.
void	wolfSSL_CTX_free(WOLFSSL_CTX * 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 * ssl) This function frees an allocated wolfSSL object.
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.
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.
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_CTX_memrestore_cert_cache(WOLFSSL_CTX * ctx, const void * mem, int sz) This function restores the certificate cache from memory.
int	wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX * ctx, const char * list) This function sets the cipher suite list for a given WOLFSSL_CTX. The list becomes the default cipher suite list for any new WOLFSSL sessions created from the context, and the order in the string is the local preference order from highest to lowest. Each call replaces the previous list. The list is a null-terminated, colon-delimited text string of suite names and/or OpenSSL-style group keywords, for example "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-SHA256".
int	wolfSSL_set_cipher_list(WOLFSSL * ssl, const char * list) This function sets the cipher suite list for a given WOLFSSL session. The list format and the set of recognized suite names and keywords are identical to those documented for wolfSSL_CTX_set_cipher_list(); refer to that function for the full keyword/suite tables and required build options. Each call replaces the previous list on the session.
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 timeout) This function sets the dtls timeout.
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.
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_CTX_set_options(WOLFSSL_CTX * ctx, long opt) This function ORs the bits in `opt` into the options mask of the given WOLFSSL_CTX. The options mask is inherited by every WOLFSSL session later created from this context. Bits are accumulated — to remove an option, use wolfSSL_CTX_clear_options(). The OpenSSL-style "SSL_OP_" macros are aliases for the corresponding "WOLFSSL_OP_" values; either spelling may be used.
long	wolfSSL_set_options(WOLFSSL * s, long op) This function ORs the bits in `op` into the options mask of the given WOLFSSL session. The set of recognized "SSL_OP_" / "WOLFSSL_OP_" flags is identical to that documented for wolfSSL_CTX_set_options(); refer to that function for the full options table and the build-option requirements of individual flags. Flags inherited from the parent WOLFSSL_CTX remain set; setting SSL_OP_NO_TLSv1_3 here lowers the session's negotiated minor version to TLS 1.2.
long	wolfSSL_get_options(const WOLFSSL * s) This function returns the current options mask.
long	wolfSSL_set_tlsext_debug_arg(WOLFSSL * s, void * arg) This is used to set the debug argument passed around.
long	wolfSSL_get_verify_result(const WOLFSSL * ssl) This is used to get the results after trying to verify the peer's certificate.
int	wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX * 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.
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_check_ip_address(WOLFSSL * ssl, const char * ipaddr) Calling this function before wolfSSL_connect() or wolfSSL_accept() adds an IP-address identity check against the peer certificate SAN iPAddress entries.
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.
int	wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX * 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 * 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_set_group_messages(WOLFSSL_CTX * ctx) This function turns on grouping of handshake messages where possible.
int	wolfSSL_set_group_messages(WOLFSSL * ssl) This function turns on grouping of handshake messages where possible.
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_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.
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_CTX_UseSessionTicket(WOLFSSL_CTX * ctx) This function sets wolfSSL context to use a session ticket.
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_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, const 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_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_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_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.
long	wolfSSL_CTX_clear_options(WOLFSSL_CTX * ctx, long opt) This function resets option bits of WOLFSSL_CTX object.
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.
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_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_CTX_set1_sigalgs_list(WOLFSSL_CTX * ctx, const char * list) This function sets the list of signature algorithms to allow on a wolfSSL context in order of preference. The list is a null_terminated text string and a colon_delimited list, where each element is of the form "+" (for example "RSA_PSS+SHA256:ECDSA+SHA384"). The Edwards-curve algorithms "ED25519" and "ED448" are written without a digest suffix, since the hash is implied by the algorithm. The previous list stored in the context is replaced.
int	wolfSSL_set1_sigalgs_list(WOLFSSL * ssl, const char * list) This function sets the list of signature algorithms to allow on a wolfSSL session in order of preference. The list format and the set of recognized public_key and digest tokens are identical to those documented for wolfSSL_CTX_set1_sigalgs_list(); refer to that function for the full token tables and TLS 1.3 caveats. The previous list stored in the session is replaced.
int	wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX * ctx, const char * list) This function sets the list of key_exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL context in order of preference. The list is a null_terminated, colon_delimited text string of group names, for example "P_384:P_256:X25519". Call this function to set the key_exchange parameters used with TLS v1.3 connections (the function is compiled in only when HAVE_ECC, WOLFSSL_TLS13, and HAVE_SUPPORTED_CURVES are defined).
int	wolfSSL_set1_groups_list(WOLFSSL * ssl, const char * list) This function sets the list of key_exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL session in order of preference. The list format and the set of recognized group names are identical to those documented for wolfSSL_CTX_set1_groups_list(); refer to that function for the full token tables and required build options.
int	wolfSSL_CTX_set_groups(WOLFSSL_CTX * ctx, int * groups, int count) This function sets the list of key_exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL context in order of preference. The list is an array of named_group identifiers (see the table below) and `count` is the number of identifiers in the array. Use this function to set the key-exchange parameters used by TLS v1.3 connections; the order of the array becomes the local KeyShare preference order.
int	wolfSSL_set_groups(WOLFSSL * ssl, int * groups, int count) This function sets the list of key_exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL session in order of preference. The array format and the set of recognized identifiers are identical to those documented for wolfSSL_CTX_set_groups(); refer to that function for the full identifier table and required build options.
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. The default value is zero: per RFC 8446 Appendix E.5, TLS implementations "MUST NOT enable 0_RTT (either sending or accepting) unless specifically requested by the application." Servers must call this function (or the per_SSL equivalent) with a non-zero value to opt in. 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.
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_CTX_set_cert_with_extern_psk(WOLFSSL_CTX * ctx, int state) Enable or disable TLS 1.3 certificate authentication with external PSK (RFC8773bis) on a context.
int	wolfSSL_set_cert_with_extern_psk(WOLFSSL * ssl, int state) Enable or disable TLS 1.3 certificate authentication with external PSK (RFC8773bis) on a connection.
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_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_CTX_clear_group_messages(WOLFSSL_CTX * ctx) Disables handshake message grouping for the given WOLFSSL_CTX context.
int	wolfSSL_clear_group_messages(WOLFSSL * ssl) Disables handshake message grouping for the given WOLFSSL object.
int	wolfSSL_get_scr_check_enabled(const WOLFSSL * ssl) Gets the state of the secure renegotiation (SCR) check requirement.
int	wolfSSL_set_scr_check_enabled(WOLFSSL * ssl, byte enabled) Sets the state of the secure renegotiation (SCR) check requirement.
void *	wolfSSL_GetCookieCtx(WOLFSSL * ssl) This function returns the IOCB_CookieCtx member of the WOLFSSL structure.
int	wolfSSL_SetIO_ISOTP(WOLFSSL * ssl, isotp_wolfssl_ctx * ctx, can_recv_fn recv_fn, can_send_fn send_fn, can_delay_fn delay_fn, word32 receive_delay, char * receive_buffer, int receive_buffer_size, void * arg) This function sets up the ISO-TP context if wolfSSL, for use when wolfSSL is compiled with WOLFSSL_ISOTP.
void	wolfSSL_SSLDisableRead(WOLFSSL * ssl) This function disables reading from the IO layer.
void	wolfSSL_SSLEnableRead(WOLFSSL * ssl) This function enables reading from the IO layer. Reading is enabled by default and should be used to undo wolfSSL_SSLDisableRead();.

Functions Documentation

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 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_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:

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_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:

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_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. This function frees the passed in WOLFSSL_METHOD struct on failure.

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:

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:

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().
cb ClientHelloGoodCb callback function pointer.
user_ctx pointer to user context to be passed to callback.

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_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:

Return: none No return.

Example

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

function wolfSSL_CTX_free

void wolfSSL_CTX_free(
    WOLFSSL_CTX * 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:

Return: none No return.

Example

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

function wolfSSL_free

void wolfSSL_free(
    WOLFSSL * ssl
)

This function frees an allocated wolfSSL object.

Parameters:

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

See:

Return: none No return.

Example

#include <wolfssl/ssl.h>

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

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_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_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:

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_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_set_cipher_list

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

This function sets the cipher suite list for a given WOLFSSL_CTX. The list becomes the default cipher suite list for any new WOLFSSL sessions created from the context, and the order in the string is the local preference order from highest to lowest. Each call replaces the previous list. The list is a null-terminated, colon-delimited text string of suite names and/or OpenSSL-style group keywords, for example "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-SHA256".

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 and/or keywords to use with the specified SSL context.

See:

Return:

WOLFSSL_SUCCESS will be returned upon successful function completion.
WOLFSSL_FAILURE will be returned on failure.

Each token in the colon-delimited list is one of the following:

A specific cipher suite name. wolfSSL accepts both its own short name and the IANA name (when WOLFSSL_NO_ERROR_STRINGS is not defined). For example "ECDHE-RSA-AES128-GCM-SHA256" and "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" are equivalent. The complete authoritative list of accepted names lives in the cipher_names[] array in src/internal.c; programs may also enumerate the suites compiled into the current build at runtime via wolfSSL_get_ciphers().
An OpenSSL-compatible keyword that selects a family of suites or toggles a class on/off (see the keyword table below). Some keywords require OPENSSL_EXTRA or OPENSSL_ALL to be defined.
A negated keyword "!keyword" to disallow a class (requires OPENSSL_EXTRA or OPENSSL_ALL). For example "HIGH:!aNULL".

A "+" operator (e.g. "ECDHE+AESGCM") is recognized only to extract the leading public-key family token ("ECDHE", "RSA" or "DHE"); trailing parts after "+" are ignored by wolfSSL. To intersect with a specific cipher use the explicit suite name instead.

OpenSSL-compatible group keywords:

Keyword	Effect	Required build option
DEFAULT / ALL	Include all built suites; "ALL" also enables anonymous (aNULL)	OPENSSL_EXTRA / OPENSSL_ALL (also accepted as the entire string with no other tokens)
HIGH	All suites except static, anonymous, and NULL ciphers	OPENSSL_EXTRA / OPENSSL_ALL (also accepted as the entire string with no other tokens)
LOW / MEDIUM	Accepted but do not restrict by bit size; behave as "RSA"	OPENSSL_EXTRA / OPENSSL_ALL
aNULL	Anonymous (no authentication) suites	OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_ANON
eNULL / NULL	Null encryption suites	OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_NULL_CIPHER
kDH	Static DH key exchange	OPENSSL_EXTRA / OPENSSL_ALL
DHE / EDH	Ephemeral DH key exchange	OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_DH
ECDHE / EECDH	Ephemeral ECDH key exchange	OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_ECC
kRSA / RSA	Static RSA key exchange	OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_RSA
PSK	Pre-shared-key suites	OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_PSK
DSS	Silently ignored — wolfSSL has no DSA ciphersuites	OPENSSL_EXTRA / OPENSSL_ALL
EXP / EXPORT	Silently ignored — export-grade ciphers are not supported	OPENSSL_EXTRA / OPENSSL_ALL
AES128 / SHA1 / RC4	When negated ("!AES128", etc.), disable that class	WOLFSSL_SYS_CRYPTO_POLICY
@SECLEVEL=n	Set OpenSSL-compatible security level	WOLFSSL_SYS_CRYPTO_POLICY

Representative TLS 1.3 cipher suite names (each guarded by its own BUILD_* macro; most are enabled automatically by –enable-tls13):

Name (wolfSSL)	IANA name	Required build option
TLS13-AES128-GCM-SHA256	TLS_AES_128_GCM_SHA256	BUILD_TLS_AES_128_GCM_SHA256 (default with TLS 1.3)
TLS13-AES256-GCM-SHA384	TLS_AES_256_GCM_SHA384	BUILD_TLS_AES_256_GCM_SHA384
TLS13-CHACHA20-POLY1305-SHA256	TLS_CHACHA20_POLY1305_SHA256	BUILD_TLS_CHACHA20_POLY1305_SHA256 (HAVE_CHACHA + HAVE_POLY1305)
TLS13-AES128-CCM-SHA256	TLS_AES_128_CCM_SHA256	BUILD_TLS_AES_128_CCM_SHA256 (HAVE_AESCCM)
TLS13-AES128-CCM-8-SHA256	TLS_AES_128_CCM_8_SHA256	BUILD_TLS_AES_128_CCM_8_SHA256 (HAVE_AESCCM)
TLS13-SM4-GCM-SM3	TLS_SM4_GCM_SM3	BUILD_TLS_SM4_GCM_SM3 (WOLFSSL_SM4_GCM + WOLFSSL_SM3)
TLS13-SM4-CCM-SM3	TLS_SM4_CCM_SM3	BUILD_TLS_SM4_CCM_SM3 (WOLFSSL_SM4_CCM + WOLFSSL_SM3)
TLS13-SHA256-SHA256	TLS_SHA256_SHA256	BUILD_TLS_SHA256_SHA256 (integrity-only)
TLS13-SHA384-SHA384	TLS_SHA384_SHA384	BUILD_TLS_SHA384_SHA384

Representative TLS 1.2 cipher suite name families (each individual suite is guarded by its own BUILD_* macro derived from the IANA name; the common build-option requirements are summarized below):

Name family / example	Typical requirements
ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305	HAVE_ECC, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305)
ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305	HAVE_ECC, !NO_RSA, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305)
DHE-RSA-AES128-GCM-SHA256, DHE-RSA-AES256-GCM-SHA384, DHE-RSA-CHACHA20-POLY1305	!NO_DH, !NO_RSA, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305)
AES128-SHA, AES256-SHA, AES128-SHA256, AES256-SHA256, AES128-GCM-SHA256, AES256-GCM-SHA384 (static-RSA)	!NO_RSA, !NO_AES_CBC and/or HAVE_AESGCM
DES-CBC3-SHA, RC4-SHA, RC4-MD5	Legacy: !NO_DES3 / !NO_RC4, !NO_OLD_TLS
NULL-SHA, NULL-SHA256, NULL-MD5	HAVE_NULL_CIPHER
PSK-AES128-CBC-SHA256, PSK-AES256-GCM-SHA384, ECDHE-PSK-AES128-CBC-SHA256, DHE-PSK-AES256-GCM-SHA384	!NO_PSK (HAVE_ECC for ECDHE-PSK, !NO_DH for DHE-PSK)
ADH-AES128-SHA, ADH-AES256-SHA	HAVE_ANON
ECDHE-ECDSA-SM4-GCM-SM3, ECDHE-ECDSA-SM4-CCM-SM3	WOLFSSL_SM2, WOLFSSL_SM3, WOLFSSL_SM4_GCM/WOLFSSL_SM4_CCM

Notes:

TLS 1.3 suite names and TLS 1.2 suite names may be mixed in the same list; wolfSSL groups them by version internally.
For DTLS, RC4-based stream ciphers in the list are silently dropped.
When set as the literal whole-string "DEFAULT", "ALL", "HIGH", or the empty string, wolfSSL installs its built-in default suite list and returns success without parsing further tokens.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_cipher_list(ctx,
    "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
    "DHE-RSA-AES256-SHA256");
if (ret != WOLFSSL_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 the cipher suite list for a given WOLFSSL session. The list format and the set of recognized suite names and keywords are identical to those documented for wolfSSL_CTX_set_cipher_list(); refer to that function for the full keyword/suite tables and required build options. Each call replaces the previous list on the session.

Parameters:

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

See:

Return:

WOLFSSL_SUCCESS will be returned upon successful function completion.
WOLFSSL_FAILURE will be returned on failure.

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_cipher_list(ssl,
    "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
    "DHE-RSA-AES256-SHA256");
if (ret != WOLFSSL_SUCCESS) {
    // failed to set cipher suite list
}

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:

function wolfSSL_dtls_set_timeout_init

int wolfSSL_dtls_set_timeout_init(
    WOLFSSL * ssl,
    int timeout
)

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:

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_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:

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_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:

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:

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:

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.
ctx The WOLFSSL_CTX object.
arg The user argument to pass to the callback.

See:

Return:

SSL_FAILURE If ctx or it’s cert manager is NULL.
SSL_SUCCESS If successfully set.
SSL_SUCCESS on success, SSL_FAILURE otherwise.

Sets the argument to be passed to the OCSP status callback.

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:

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_CTX_set_options

long wolfSSL_CTX_set_options(
    WOLFSSL_CTX * ctx,
    long opt
)

This function ORs the bits in opt into the options mask of the given WOLFSSL_CTX. The options mask is inherited by every WOLFSSL session later created from this context. Bits are accumulated — to remove an option, use wolfSSL_CTX_clear_options(). The OpenSSL-style "SSL_OP_" macros are aliases for the corresponding "WOLFSSL_OP_" values; either spelling may be used.

Parameters:

ctx WOLFSSL_CTX structure on which to set the options mask.
opt the bitmask of SSL_OP_ / WOLFSSL_OP_ flags to OR into the current mask.

See:

Return:

BAD_FUNC_ARG if ctx is NULL.
The updated options mask value stored in ctx on success.

Effective options:

Macro	Effect
SSL_OP_NO_SSLv2	Disable SSLv2 (wolfSSL never supports SSLv2; flag is accepted for OpenSSL compatibility)
SSL_OP_NO_SSLv3	Disable SSLv3
SSL_OP_NO_TLSv1	Disable TLS 1.0
SSL_OP_NO_TLSv1_1	Disable TLS 1.1
SSL_OP_NO_TLSv1_2	Disable TLS 1.2
SSL_OP_NO_TLSv1_3	Disable TLS 1.3 (requires WOLFSSL_TLS13)
SSL_OP_NO_COMPRESSION	Disable record-layer compression (no-op unless HAVE_LIBZ)
SSL_OP_NO_TICKET	Disable RFC 5077 session tickets (TLS 1.2 only; TLS 1.3 ignores this flag); requires HAVE_SESSION_TICKET and (OPENSSL_EXTRA or HAVE_WEBSERVER or WOLFSSL_WPAS_SMALL)
SSL_OP_NO_RENEGOTIATION	Reject peer-initiated renegotiation
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION	Disable session resumption on renegotiation
SSL_OP_COOKIE_EXCHANGE	Enable HelloVerifyRequest cookie exchange (default-on for DTLS)
SSL_OP_NO_QUERY_MTU	DTLS: do not query the path MTU
SSL_OP_CIPHER_SERVER_PREFERENCE	Server uses its own cipher preference order rather than the client's
SSL_OP_SINGLE_DH_USE	Generate a fresh DH key for every handshake
SSL_OP_SINGLE_ECDH_USE	Generate a fresh ECDH key for every handshake
SSL_OP_EPHEMERAL_RSA	Use ephemeral RSA (legacy, accepted for OpenSSL compatibility)
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS	Do not insert empty fragments before a record (CBC BEAST workaround)
SSL_OP_PKCS1_CHECK_1 / _2	Accepted for OpenSSL compatibility
SSL_OP_LEGACY_SERVER_CONNECT	Always allow legacy (unsafe) initial connect; defined as 0 — no effect (requires the openssl/ssl.h compatibility header)

Convenience macros and bug-workaround flags (all members of SSL_OP_ALL, accepted for OpenSSL compatibility but otherwise no-ops in wolfSSL):

SSL_OP_ALL (bitwise OR of all bug-workaround flags below)
SSL_OP_MICROSOFT_SESS_ID_BUG
SSL_OP_NETSCAPE_CHALLENGE_BUG
SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
SSL_OP_MSIE_SSLV2_RSA_PADDING
SSL_OP_SSLEAY_080_CLIENT_DH_BUG
SSL_OP_TLS_D5_BUG
SSL_OP_TLS_BLOCK_PADDING_BUG
SSL_OP_TLS_ROLLBACK_BUG
SSL_OP_NETSCAPE_CA_DN_BUG
SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG

Convenience composite:

SSL_OP_NO_SSL_MASK = SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 | SSL_OP_NO_TLSv1_2 | SSL_OP_NO_TLSv1_3

Example

WOLFSSL_CTX* ctx;
long mask;
mask = wolfSSL_CTX_set_options(ctx,
    SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 |
    SSL_OP_NO_COMPRESSION | SSL_OP_CIPHER_SERVER_PREFERENCE);
// 'mask' now reflects the accumulated options stored in ctx

function wolfSSL_set_options

long wolfSSL_set_options(
    WOLFSSL * s,
    long op
)

This function ORs the bits in op into the options mask of the given WOLFSSL session. The set of recognized "SSL_OP_" / "WOLFSSL_OP_" flags is identical to that documented for wolfSSL_CTX_set_options(); refer to that function for the full options table and the build-option requirements of individual flags. Flags inherited from the parent WOLFSSL_CTX remain set; setting SSL_OP_NO_TLSv1_3 here lowers the session's negotiated minor version to TLS 1.2.

Parameters:

s WOLFSSL session on which to set the options mask.
op the bitmask of SSL_OP_ / WOLFSSL_OP_ flags to OR into the current mask.

See:

Return: The updated options mask value stored in s on success, or 0 if s is NULL.

Example

WOLFSSL* ssl;
long mask;
mask = wolfSSL_set_options(ssl, SSL_OP_NO_TLSv1_3);
// 'mask' now reflects the accumulated options stored in ssl

function wolfSSL_get_options

long wolfSSL_get_options(
    const WOLFSSL * s
)

This function returns the current options mask.

Parameters:

s WOLFSSL structure to get options mask from.

See:

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 * s,
    void * arg
)

This is used to set the debug argument passed around.

Parameters:

s WOLFSSL structure to set argument in.
arg argument to use.

See:

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_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:

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_CTX_allow_anon_cipher

int wolfSSL_CTX_allow_anon_cipher(
    WOLFSSL_CTX * 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:

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:

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_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_check_ip_address

int wolfSSL_check_ip_address(
    WOLFSSL * ssl,
    const char * ipaddr
)

Calling this function before wolfSSL_connect() or wolfSSL_accept() adds an IP-address identity check against the peer certificate SAN iPAddress entries.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
ipaddr NULL-terminated ASCII IP address string to verify against the peer certificate.

See: wolfSSL_check_domain_name

Return:

SSL_SUCCESS upon success.
SSL_FAILURE if parameters are invalid or memory allocation fails.

Example

int ret = 0;
WOLFSSL* ssl;
const char* ip = "127.0.0.1";
...

ret = wolfSSL_check_ip_address(ssl, ip);
if (ret != SSL_SUCCESS) {
   // failed to enable IP check
}

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:

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:

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_CTX_UnloadCAs

int wolfSSL_CTX_UnloadCAs(
    WOLFSSL_CTX * 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:

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 * 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:

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:

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_set_group_messages

int wolfSSL_CTX_set_group_messages(
    WOLFSSL_CTX * ctx
)

This function turns on grouping of handshake messages where possible.

Parameters:

ctx pointer to the SSL context, created with wolfSSL_CTX_new().
ctx Pointer to the WOLFSSL_CTX structure.

See:

Return:

SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.
WOLFSSL_SUCCESS on success.
BAD_FUNC_ARG if ctx is NULL.

Enables handshake message grouping for the given WOLFSSL_CTX context.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_group_messages(ctx);
if (ret != SSL_SUCCESS) {
    // failed to set handshake message grouping
}

This function turns on handshake message grouping for all SSL objects created from the specified context.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
wolfSSL_CTX_set_group_messages(ctx);

function wolfSSL_set_group_messages

int wolfSSL_set_group_messages(
    WOLFSSL * ssl
)

This function turns on grouping of handshake messages where possible.

Parameters:

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

See:

Return:

SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.
WOLFSSL_SUCCESS on success.
BAD_FUNC_ARG if ssl is NULL.

Enables handshake message grouping for the given WOLFSSL object.

Example

WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_group_messages(ssl);
if (ret != SSL_SUCCESS) {
// failed to set handshake message grouping
}

This function turns on handshake message grouping for the specified SSL object.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
wolfSSL_set_group_messages(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_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_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_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_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:

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_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:

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,
    const 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:

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_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:

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:

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:

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_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:

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_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:

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:

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:

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:

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_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:

Return: option new option bits

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);

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_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:

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_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:

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:

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_CTX_set1_sigalgs_list

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

This function sets the list of signature algorithms to allow on a wolfSSL context in order of preference. The list is a null-terminated text string and a colon-delimited list, where each element is of the form "+" (for example "RSA-PSS+SHA256:ECDSA+SHA384"). The Edwards-curve algorithms "ED25519" and "ED448" are written without a digest suffix, since the hash is implied by the algorithm. The previous list stored in the context is replaced.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
list a colon-delimited list of "+" elements (or "ED25519" / "ED448" without a digest).

See:

Return:

WOLFSSL_SUCCESS if successful.
WOLFSSL_FAILURE if a pointer parameter is NULL, allocation of the suites structure fails, or any token in the list is not recognized or not supported by the current build.

Recognized public-key tokens and digest tokens, together with the build options that must be enabled for each token to be accepted, are listed in the tables below.

Public-key tokens:

Token	Required build option
RSA	!NO_RSA
RSA-PSS / PSS	!NO_RSA and WC_RSA_PSS
ECDSA	HAVE_ECC
ED25519	HAVE_ED25519 (no digest suffix)
ED448	HAVE_ED448 (no digest suffix)
DSA	!NO_DSA
SM2	WOLFSSL_SM2 and WOLFSSL_SM3 (digest is SM3)

Digest tokens:

Token	Required build option
SHA256	!NO_SHA256
SHA384	WOLFSSL_SHA384
SHA512	WOLFSSL_SHA512
SHA224	WOLFSSL_SHA224
SM3	WOLFSSL_SM3
SHA1	!NO_SHA, plus !NO_OLD_TLS or WOLFSSL_ALLOW_TLS_SHA1

Notes for TLS 1.3: per RFC 8446, RSA PKCS#1 v1.5, DSA, SHA-1, and SHA-224 cannot be used as handshake signatures and will be filtered out at negotiation time even if listed. Specifying "RSA-PSS+SHAxxx" causes both the rsa_pss_rsae_shaxxx and rsa_pss_pss_shaxxx schemes to be added. Brainpool ECDSA signature schemes (RFC 8734) cannot be selected through this string interface; they are negotiated automatically when HAVE_ECC_BRAINPOOL is enabled.

Example

int ret;
WOLFSSL_CTX* ctx;
const char* list = "RSA-PSS+SHA256:ECDSA+SHA384:ED25519";
...
ret = wolfSSL_CTX_set1_sigalgs_list(ctx, list);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set signature algorithm list
}

function wolfSSL_set1_sigalgs_list

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

This function sets the list of signature algorithms to allow on a wolfSSL session in order of preference. The list format and the set of recognized public-key and digest tokens are identical to those documented for wolfSSL_CTX_set1_sigalgs_list(); refer to that function for the full token tables and TLS 1.3 caveats. The previous list stored in the session is replaced.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
list a colon-delimited list of "+" elements (or "ED25519" / "ED448" without a digest).

See:

Return:

WOLFSSL_SUCCESS if successful.
WOLFSSL_FAILURE if a pointer parameter is NULL, allocation of the suites structure fails, or any token in the list is not recognized or not supported by the current build.

Example

int ret;
WOLFSSL* ssl;
const char* list = "RSA-PSS+SHA256:ECDSA+SHA384:ED25519";
...
ret = wolfSSL_set1_sigalgs_list(ssl, list);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set signature algorithm list
}

function wolfSSL_CTX_set1_groups_list

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

This function sets the list of key-exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL context in order of preference. The list is a null-terminated, colon-delimited text string of group names, for example "P-384:P-256:X25519". Call this function to set the key-exchange parameters used with TLS v1.3 connections (the function is compiled in only when HAVE_ECC, WOLFSSL_TLS13, and HAVE_SUPPORTED_CURVES are defined).

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
list a string that is a colon-delimited list of key-exchange group names.

See:

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.

Recognized group names and the build options each one requires are listed below. Names are matched case-sensitively against the table.

NIST / SEC curves (require HAVE_ECC):

Name	Curve / Group
P-160	secp160r1
P-160-2	secp160r2
P-192	secp192r1 (prime192v1)
P-224	secp224r1
P-256	secp256r1 (prime256v1) — also accepted as "prime256v1" / "secp256r1"
P-384	secp384r1 — also accepted as "secp384r1"
P-521	secp521r1 — also accepted as "secp521r1"
K-160	secp160k1
K-192	secp192k1
K-224	secp224k1
K-256	secp256k1

Brainpool curves (require HAVE_ECC plus WOLFSSL_CUSTOM_CURVES and HAVE_ECC_BRAINPOOL — typically enabled by –enable-ecccustcurves=all):

Name	Curve
B-256	brainpoolP256r1
B-384	brainpoolP384r1
B-512	brainpoolP512r1

Edwards / Montgomery curves:

Name	Required build option
X25519	HAVE_CURVE25519
X448	HAVE_CURVE448

SM2 (requires WOLFSSL_SM2):

Name	Group
SM2	sm2p256v1
sm2p256v1	sm2p256v1 (alias)

ML-KEM (post-quantum) groups (require WOLFSSL_HAVE_MLKEM and !WOLFSSL_NO_ML_KEM):

Name
ML_KEM_512
ML_KEM_768
ML_KEM_1024

ML-KEM hybrid groups additionally require HAVE_ECC together with either WOLFSSL_WC_MLKEM or HAVE_LIBOQS, and WOLFSSL_PQC_HYBRIDS (or WOLFSSL_EXTRA_PQC_HYBRIDS for the "extra" set):

Name	Hybrid flag set
SecP256r1MLKEM768	WOLFSSL_PQC_HYBRIDS
SecP384r1MLKEM1024	WOLFSSL_PQC_HYBRIDS
X25519MLKEM768	WOLFSSL_PQC_HYBRIDS
SecP256r1MLKEM512	WOLFSSL_EXTRA_PQC_HYBRIDS
SecP384r1MLKEM768	WOLFSSL_EXTRA_PQC_HYBRIDS
SecP521r1MLKEM1024	WOLFSSL_EXTRA_PQC_HYBRIDS
X25519MLKEM512	WOLFSSL_EXTRA_PQC_HYBRIDS
X448MLKEM768	WOLFSSL_EXTRA_PQC_HYBRIDS

Legacy Kyber groups (require WOLFSSL_MLKEM_KYBER; hybrids additionally require HAVE_ECC together with WOLFSSL_WC_MLKEM or HAVE_LIBOQS):

Name
KYBER_LEVEL1
KYBER_LEVEL3
KYBER_LEVEL5
P256_KYBER_LEVEL1
P256_KYBER_LEVEL3
P384_KYBER_LEVEL3
P521_KYBER_LEVEL5
X25519_KYBER_LEVEL1
X25519_KYBER_LEVEL3
X448_KYBER_LEVEL3

In addition to the names above, when HAVE_FIPS and HAVE_SELFTEST are not defined, any curve name registered with wolfCrypt (looked up via wc_ecc_get_curve_idx_from_name(), e.g. "brainpoolP256r1") is also accepted.

The order of the names in the list is preserved and used as the local preference order for KeyShare selection in TLS 1.3.

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,
    const char * list
)

This function sets the list of key-exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL session in order of preference. The list format and the set of recognized group names are identical to those documented for wolfSSL_CTX_set1_groups_list(); refer to that function for the full token tables and required build options.

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:

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_CTX_set_groups

int wolfSSL_CTX_set_groups(
    WOLFSSL_CTX * ctx,
    int * groups,
    int count
)

This function sets the list of key-exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL context in order of preference. The list is an array of named-group identifiers (see the table below) and count is the number of identifiers in the array. Use this function to set the key-exchange parameters used by TLS v1.3 connections; the order of the array becomes the local KeyShare preference order.

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 identifiers in groups (must not exceed WOLFSSL_MAX_GROUP_COUNT).

See:

Return:

BAD_FUNC_ARG if a pointer parameter is NULL, count exceeds WOLFSSL_MAX_GROUP_COUNT, or the underlying method is not a TLS method.
WOLFSSL_SUCCESS if successful.

Recognized identifiers and the build options each one requires are listed below. The identifiers are defined in the anonymous enum in .

NIST / SEC curves (require HAVE_ECC):

Identifier	Curve / Group
WOLFSSL_ECC_SECP160K1	secp160k1
WOLFSSL_ECC_SECP160R1	secp160r1
WOLFSSL_ECC_SECP160R2	secp160r2
WOLFSSL_ECC_SECP192K1	secp192k1
WOLFSSL_ECC_SECP192R1	secp192r1 (prime192v1)
WOLFSSL_ECC_SECP224K1	secp224k1
WOLFSSL_ECC_SECP224R1	secp224r1
WOLFSSL_ECC_SECP256K1	secp256k1
WOLFSSL_ECC_SECP256R1	secp256r1 (prime256v1)
WOLFSSL_ECC_SECP384R1	secp384r1
WOLFSSL_ECC_SECP521R1	secp521r1

Brainpool curves (require HAVE_ECC plus WOLFSSL_CUSTOM_CURVES and HAVE_ECC_BRAINPOOL — typically enabled by –enable-ecccustcurves=all):

Identifier	Curve	Notes
WOLFSSL_ECC_BRAINPOOLP256R1	brainpoolP256r1	TLS 1.2 group ID 26
WOLFSSL_ECC_BRAINPOOLP384R1	brainpoolP384r1	TLS 1.2 group ID 27
WOLFSSL_ECC_BRAINPOOLP512R1	brainpoolP512r1	TLS 1.2 group ID 28
WOLFSSL_ECC_BRAINPOOLP256R1TLS13	brainpoolP256r1	RFC 8734 TLS 1.3 ID
WOLFSSL_ECC_BRAINPOOLP384R1TLS13	brainpoolP384r1	RFC 8734 TLS 1.3 ID
WOLFSSL_ECC_BRAINPOOLP512R1TLS13	brainpoolP512r1	RFC 8734 TLS 1.3 ID

Edwards / Montgomery curves:

Identifier	Required build option
WOLFSSL_ECC_X25519	HAVE_CURVE25519
WOLFSSL_ECC_X448	HAVE_CURVE448

SM2 (requires WOLFSSL_SM2):

Identifier	Group
WOLFSSL_ECC_SM2P256V1	sm2p256v1

Finite-field DH (RFC 7919) groups (require HAVE_FFDHE and the matching HAVE_FFDHE_NNNN macro for each size):

Identifier	Group
WOLFSSL_FFDHE_2048	ffdhe2048
WOLFSSL_FFDHE_3072	ffdhe3072
WOLFSSL_FFDHE_4096	ffdhe4096
WOLFSSL_FFDHE_6144	ffdhe6144
WOLFSSL_FFDHE_8192	ffdhe8192

ML-KEM (post-quantum) groups (require HAVE_PQC, WOLFSSL_HAVE_MLKEM and !WOLFSSL_NO_ML_KEM):

Identifier
WOLFSSL_ML_KEM_512
WOLFSSL_ML_KEM_768
WOLFSSL_ML_KEM_1024

ML-KEM hybrid groups additionally require HAVE_ECC together with either WOLFSSL_WC_MLKEM or HAVE_LIBOQS, and WOLFSSL_PQC_HYBRIDS (or WOLFSSL_EXTRA_PQC_HYBRIDS for the "extra" set):

Identifier	Hybrid flag set
WOLFSSL_SECP256R1MLKEM768	WOLFSSL_PQC_HYBRIDS
WOLFSSL_X25519MLKEM768	WOLFSSL_PQC_HYBRIDS
WOLFSSL_SECP384R1MLKEM1024	WOLFSSL_PQC_HYBRIDS
WOLFSSL_SECP256R1MLKEM512	WOLFSSL_EXTRA_PQC_HYBRIDS
WOLFSSL_SECP384R1MLKEM768	WOLFSSL_EXTRA_PQC_HYBRIDS
WOLFSSL_SECP521R1MLKEM1024	WOLFSSL_EXTRA_PQC_HYBRIDS
WOLFSSL_X25519MLKEM512	WOLFSSL_EXTRA_PQC_HYBRIDS
WOLFSSL_X448MLKEM768	WOLFSSL_EXTRA_PQC_HYBRIDS

Legacy Kyber groups (require HAVE_PQC and WOLFSSL_MLKEM_KYBER; hybrids additionally require HAVE_ECC together with WOLFSSL_WC_MLKEM or HAVE_LIBOQS):

Identifier
WOLFSSL_KYBER_LEVEL1
WOLFSSL_KYBER_LEVEL3
WOLFSSL_KYBER_LEVEL5
WOLFSSL_P256_KYBER_LEVEL1
WOLFSSL_P256_KYBER_LEVEL3
WOLFSSL_P384_KYBER_LEVEL3
WOLFSSL_P521_KYBER_LEVEL5
WOLFSSL_X25519_KYBER_LEVEL1
WOLFSSL_X25519_KYBER_LEVEL3
WOLFSSL_X448_KYBER_LEVEL3

Example

int ret;
WOLFSSL_CTX* ctx;
int groups[] = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
int count = sizeof(groups) / sizeof(groups[0]);
...
ret = wolfSSL_CTX_set_groups(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 key-exchange groups (named elliptic curves and KEMs) to allow on a wolfSSL session in order of preference. The array format and the set of recognized identifiers are identical to those documented for wolfSSL_CTX_set_groups(); refer to that function for the full identifier table and required build options.

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 identifiers in groups (must not exceed WOLFSSL_MAX_GROUP_COUNT).

See:

Return:

BAD_FUNC_ARG if a pointer parameter is NULL, count exceeds WOLFSSL_MAX_GROUP_COUNT, any of the identifiers are unrecognized, or the underlying method is not a TLS method.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL* ssl;
int groups[] = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
int count = sizeof(groups) / sizeof(groups[0]);
...
ret = wolfSSL_set_groups(ssl, groups, count);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

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. The default value is zero: per RFC 8446 Appendix E.5, TLS implementations "MUST NOT enable 0-RTT (either sending or accepting) unless specifically requested by the application." Servers must call this function (or the per-SSL equivalent) with a non-zero value to opt in. 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:

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:

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_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:

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:

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:

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:

Example

WOLFSSL* ssl;
...
wolfSSL_set_psk_server_tls13_callback(ssl, my_psk_server_tls13_cb);

function wolfSSL_CTX_set_cert_with_extern_psk

int wolfSSL_CTX_set_cert_with_extern_psk(
    WOLFSSL_CTX * ctx,
    int state
)

Enable or disable TLS 1.3 certificate authentication with external PSK (RFC8773bis) on a context.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
state 0 to disable, non-zero to enable.

See:

Return:

WOLFSSL_SUCCESS on success.
WOLFSSL_FAILURE when ctx is NULL.

When enabled, wolfSSL advertises and accepts the tls_cert_with_extern_psk extension for TLS 1.3 handshakes using external PSKs. Any non-zero state value enables the feature and zero disables it.

Availability:

Built with --enable-tls13 --enable-psk --enable-cert-with-extern-psk
Or with WOLFSSL_TLS13 and WOLFSSL_CERT_WITH_EXTERN_PSK defined

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method());
if (wolfSSL_CTX_set_cert_with_extern_psk(ctx, 1) != WOLFSSL_SUCCESS) {
    /* handle error */
}

function wolfSSL_set_cert_with_extern_psk

int wolfSSL_set_cert_with_extern_psk(
    WOLFSSL * ssl,
    int state
)

Enable or disable TLS 1.3 certificate authentication with external PSK (RFC8773bis) on a connection.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
state 0 to disable, non-zero to enable.

See:

Return:

WOLFSSL_SUCCESS on success.
WOLFSSL_FAILURE when ssl is NULL.

This call applies to a single WOLFSSL object. Any non-zero state value enables the feature and zero disables it.

Availability:

Built with --enable-tls13 --enable-psk --enable-cert-with-extern-psk
Or with WOLFSSL_TLS13 and WOLFSSL_CERT_WITH_EXTERN_PSK defined

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
if (wolfSSL_set_cert_with_extern_psk(ssl, 1) != WOLFSSL_SUCCESS) {
    /* handle error */
}

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:

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:

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:

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:

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:

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:

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:

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_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:

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:

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:

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:

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_CTX_clear_group_messages

int wolfSSL_CTX_clear_group_messages(
    WOLFSSL_CTX * ctx
)

Disables handshake message grouping for the given WOLFSSL_CTX context.

Parameters:

ctx Pointer to the WOLFSSL_CTX structure.

See:

Return:

WOLFSSL_SUCCESS on success.
BAD_FUNC_ARG if ctx is NULL.

This function turns off handshake message grouping for all SSL objects created from the specified context.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
wolfSSL_CTX_clear_group_messages(ctx);

function wolfSSL_clear_group_messages

int wolfSSL_clear_group_messages(
    WOLFSSL * ssl
)

Disables handshake message grouping for the given WOLFSSL object.

Parameters:

ssl Pointer to the WOLFSSL structure.

See:

Return:

WOLFSSL_SUCCESS on success.
BAD_FUNC_ARG if ssl is NULL.

This function turns off handshake message grouping for the specified SSL object.

Example

WOLFSSL* ssl = wolfSSL_new(ctx);
wolfSSL_clear_group_messages(ssl);

function wolfSSL_get_scr_check_enabled

int wolfSSL_get_scr_check_enabled(
    const WOLFSSL * ssl
)

Gets the state of the secure renegotiation (SCR) check requirement.

Parameters:

ssl Pointer to the WOLFSSL structure, created with wolfSSL_new().

See: wolfSSL_set_scr_check_enabled

Return:

1 if the SCR check is enabled.
0 if the SCR check is disabled.
BAD_FUNC_ARG if ssl is NULL.

This function returns whether the client requires the server to acknowledge the secure renegotiation extension and enable secure renegotiation when sending it from the client. When enabled, the client will generate a fatal handshake_failure alert if the server does not acknowledge the extension in the ServerHello message, as required by RFC 9325.

Example

WOLFSSL* ssl;
int enabled;

ssl = wolfSSL_new(ctx);
enabled = wolfSSL_get_scr_check_enabled(ssl);
if (enabled) {
    // SCR check is enabled
}

function wolfSSL_set_scr_check_enabled

int wolfSSL_set_scr_check_enabled(
    WOLFSSL * ssl,
    byte enabled
)

Sets the state of the secure renegotiation (SCR) check requirement.

Parameters:

ssl Pointer to the WOLFSSL structure, created with wolfSSL_new().
enabled Non-zero to enable the SCR check, zero to disable it.

See: wolfSSL_get_scr_check_enabled

Return:

WOLFSSL_SUCCESS on success.
BAD_FUNC_ARG if ssl is NULL.

This function enables or disables the requirement for the server to acknowledge the secure renegotiation extension and enable secure renegotiation when sending it from the client. When enabled, the client will generate a fatal handshake_failure alert if the server does not acknowledge the extension in the ServerHello message, as required by RFC 9325.

Example

WOLFSSL* ssl;
int ret;

ssl = wolfSSL_new(ctx);
ret = wolfSSL_set_scr_check_enabled(ssl, 1);
if (ret != WOLFSSL_SUCCESS) {
    // Error setting SCR check
}

function wolfSSL_GetCookieCtx

void * wolfSSL_GetCookieCtx(
    WOLFSSL * ssl
)

This function returns the IOCB_CookieCtx member of the WOLFSSL structure.

Parameters:

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

See:

Return:

pointer The function returns a void pointer value stored in the IOCB_CookieCtx.
NULL if the WOLFSSL struct is NULL
Cookie context pointer

Gets cookie context for DTLS.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
void* cookie;
...
cookie = wolfSSL_GetCookieCtx(ssl);
if(cookie != NULL){
// You have the cookie
}

Example

WOLFSSL* ssl;
void* ctx = wolfSSL_GetCookieCtx(ssl);

function wolfSSL_SetIO_ISOTP

int wolfSSL_SetIO_ISOTP(
    WOLFSSL * ssl,
    isotp_wolfssl_ctx * ctx,
    can_recv_fn recv_fn,
    can_send_fn send_fn,
    can_delay_fn delay_fn,
    word32 receive_delay,
    char * receive_buffer,
    int receive_buffer_size,
    void * arg
)

This function sets up the ISO-TP context if wolfSSL, for use when wolfSSL is compiled with WOLFSSL_ISOTP.

Parameters:

ssl the wolfSSL context
ctx a user created ISOTP context which this function initializes
recv_fn a user CAN bus receive callback
send_fn a user CAN bus send callback
delay_fn a user microsecond granularity delay function
receive_delay a set amount of microseconds to delay each CAN bus packet
receive_buffer a user supplied buffer to receive data, recommended that is allocated to ISOTP_DEFAULT_BUFFER_SIZE bytes
receive_buffer_size - The size of receive_buffer
arg an arbitrary pointer sent to recv_fn and send_fn

Return: 0 on success, WOLFSSL_CBIO_ERR_GENERAL on failure

Example

struct can_info can_con_info;
isotp_wolfssl_ctx isotp_ctx;
char *receive_buffer = malloc(ISOTP_DEFAULT_BUFFER_SIZE);
WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
WOLFSSL* ssl = wolfSSL_new(ctx);
...
wolfSSL_SetIO_ISOTP(ssl, &isotp_ctx, can_receive, can_send, can_delay, 0,
        receive_buffer, ISOTP_DEFAULT_BUFFER_SIZE, &can_con_info);

function wolfSSL_SSLDisableRead

void wolfSSL_SSLDisableRead(
    WOLFSSL * ssl
)

This function disables reading from the IO layer.

Parameters:

ssl the wolfSSL context

See:

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
WOLFSSL* ssl = wolfSSL_new(ctx);
wolfSSL_SSLDisableRead(ssl);

function wolfSSL_SSLEnableRead

void wolfSSL_SSLEnableRead(
    WOLFSSL * ssl
)

This function enables reading from the IO layer. Reading is enabled by default and should be used to undo wolfSSL_SSLDisableRead();.

Parameters:

ssl the wolfSSL context

See:

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
WOLFSSL* ssl = wolfSSL_new(ctx);
wolfSSL_SSLDisableRead(ssl);
...
wolfSSL_SSLEnableRead(ssl);

Updated on 2026-05-14 at 11:44:48 +0000