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 * ) This function frees an allocated WOLFSSL_CTX object. This function decrements the CTX reference count and only frees the context when the reference count has reached 0.
void	wolfSSL_free(WOLFSSL * ) This function frees an allocated wolfSSL object.
int	wolfSSL_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 cipher suite list for a given WOLFSSL_CTX. This cipher suite list becomes the default list for any new SSL sessions (WOLFSSL) created using this context. The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the specific SSL context to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256" Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)
int	wolfSSL_set_cipher_list(WOLFSSL * ssl, const char * list) This function sets cipher suite list for a given WOLFSSL object (SSL session). The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_set_cipher_list() resets the cipher suite list for the specific SSL session to the provided list each time the function is called. The cipher suite list, list, is a null_terminated text string, and a colon_delimited list. For example, one value for list may be "DHE_RSA_AES256_SHA256:DHE_RSA_AES128_SHA256:AES256_SHA256". Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)
void	wolfSSL_dtls13_set_send_more_acks(WOLFSSL * ssl, int value) This function sets whether the library should send ACKs to the other peer immediately when detecting disruption or not. Sending ACKs immediately assures minimum latency but it may consume more bandwidth than necessary. If the application manages the timer by itself and this option is set to 0 then application code can use wolfSSL_dtls13_use_quick_timeout() to determine if it should setup a quicker timeout to send those delayed ACKs.
int	wolfSSL_dtls_set_timeout_init(WOLFSSL * ssl, int ) This function sets the dtls timeout.
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_set_options(WOLFSSL * s, long op) This function sets the options mask in the ssl. Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE, SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_COMPRESSION.
long	wolfSSL_get_options(const WOLFSSL * ssl) This function returns the current options mask.
long	wolfSSL_set_tlsext_debug_arg(WOLFSSL * ssl, void * arg) This is used to set the debug argument passed around.
long	wolfSSL_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 * ) 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_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 * ) This function unloads the CA signer list and frees the whole signer table.
int	wolfSSL_CTX_UnloadIntermediateCerts(WOLFSSL_CTX * ctx) This function unloads intermediate certificates added to the CA signer list and frees them.
int	wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX * ) This function is used to unload all previously loaded trusted peer certificates. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT.
int	wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX * ctx, const unsigned char * in, long sz, int format) This function loads a certificate to use for verifying a peer when performing a TLS/SSL handshake. The peer certificate sent during the handshake is compared by using the SKID when available and the signature. If these two things do not match then any loaded CAs are used. Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from a buffer instead of a file. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage.
int	wolfSSL_CTX_set_group_messages(WOLFSSL_CTX * ) This function turns on grouping of handshake messages where possible.
int	wolfSSL_set_group_messages(WOLFSSL * ) This function turns on grouping of handshake messages where possible.
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, 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_groups_list(WOLFSSL_CTX * ctx, char * list) This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_set1_groups_list(WOLFSSL * ssl, char * list) This function sets the list of elliptic curve groups to allow on a wolfSSL in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_CTX_set_groups(WOLFSSL_CTX * ctx, int * groups, int count) This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_set_groups(WOLFSSL * ssl, int * groups, int count) This function sets the list of elliptic curve groups to allow on a wolfSSL. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.
int	wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX * ctx, unsigned int sz) This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange using the wolfSSL context. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.
int	wolfSSL_set_max_early_data(WOLFSSL * ssl, unsigned int sz) This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.
void	wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX * ctx, wc_psk_client_tls13_callback cb) This function sets the Pre_Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_client_tls13_callback(WOLFSSL * ssl, wc_psk_client_tls13_callback cb) This function sets the Pre_Shared Key (PSK) client side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the client_psk_tls13_cb member of the options field in WOLFSSL structure.
void	wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX * ctx, wc_psk_server_tls13_callback cb) This function sets the Pre_Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the WOLFSSL_CTX structure.
void	wolfSSL_set_psk_server_tls13_callback(WOLFSSL * ssl, wc_psk_server_tls13_callback cb) This function sets the Pre_Shared Key (PSK) server side callback for TLS v1.3 connections. The callback is used to find a PSK identity and return its key and the name of the cipher to use for the handshake. The function sets the server_psk_tls13_cb member of the options field in WOLFSSL structure.
int	wolfSSL_UseKeyShare(WOLFSSL * ssl, word16 group) This function creates a key share entry from the group including generating a key pair. The KeyShare extension contains all the generated public keys for key exchange. If this function is called, then only the groups specified will be included. Call this function when a preferred group has been previously established for the server.
int	wolfSSL_NoKeyShares(WOLFSSL * ssl) This function is called to ensure no key shares are sent in the ClientHello. This will force the server to respond with a HelloRetryRequest if a key exchange is required in the handshake. Call this function when the expected key exchange group is not known and to avoid the generation of keys unnecessarily. Note that an extra round-trip will be required to complete the handshake when a key exchange is required.
WOLFSSL_METHOD *	wolfTLSv1_3_server_method_ex(void * heap) This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_client_method_ex(void * heap) This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_server_method(void ) This function is used to indicate that the application is a server and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_client_method(void ) This function is used to indicate that the application is a client and will only support the TLS 1.3 protocol. This function allocates memory for and initializes a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
WOLFSSL_METHOD *	wolfTLSv1_3_method_ex(void * heap) This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).
WOLFSSL_METHOD *	wolfTLSv1_3_method(void ) This function returns a WOLFSSL_METHOD similar to wolfTLSv1_3_client_method except that it is not determined which side yet (server/client).
int	wolfSSL_CTX_set_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.
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.

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.

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().
fd file descriptor to use with SSL/TLS connection.

See: wolfSSL_set_dtls_fd_connected

Return:

SSL_SUCCESS upon success.
BAD_FUNC_ARG upon failure.

Example

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

}

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

function wolfSSL_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 * 
)

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

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 cipher suite list for a given WOLFSSL_CTX. This cipher suite list becomes the default list for any new SSL sessions (WOLFSSL) created using this context. The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the specific SSL context to the provided list each time the function is called. The cipher suite list, list, is a null-terminated text string, and a colon-delimited list. For example, one value for list may be "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256" Valid cipher values are the full name values from the cipher_names[] array in src/internal.c (for a definite list of valid cipher values check src/internal.c)

Parameters:

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

See:

Return:

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

Example

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

function wolfSSL_set_cipher_list

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

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

Parameters:

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

See:

Return:

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

Example

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

function wolfSSL_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 
)

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.

See:

Return:

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

Example

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

//check ret value

function wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg

long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(
    WOLFSSL_CTX * ctx,
    void * arg
)

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

Parameters:

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

See:

Return:

SSL_FAILURE If ctx is NULL.
SSL_SUCCESS If successfully set.

Example

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

function wolfSSL_set_options

long wolfSSL_set_options(
    WOLFSSL * s,
    long op
)

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

Parameters:

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

See:

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

Example

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

function wolfSSL_get_options

long wolfSSL_get_options(
    const WOLFSSL * ssl
)

This function returns the current options mask.

Parameters:

ssl WOLFSSL structure to get options mask from.

See:

Return: val Returns the mask value stored in ssl.

Example

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

function wolfSSL_set_tlsext_debug_arg

long wolfSSL_set_tlsext_debug_arg(
    WOLFSSL * ssl,
    void * arg
)

This is used to set the debug argument passed around.

Parameters:

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

See:

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

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

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

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

This function turns on grouping of handshake messages where possible.

Parameters:

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

See:

Return:

SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.

Example

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

function wolfSSL_set_group_messages

int wolfSSL_set_group_messages(
    WOLFSSL * 
)

This function turns on grouping of handshake messages where possible.

Parameters:

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

See:

Return:

SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.

Example

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

function wolfSSL_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,
    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_groups_list

int wolfSSL_CTX_set1_groups_list(
    WOLFSSL_CTX * ctx,
    char * list
)

This function sets the list of elliptic curve groups to allow on a wolfSSL context in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
list a string that is a colon-delimited list of elliptic curve groups.

See:

Return:

WOLFSSL_FAILURE if pointer parameters are NULL, there are more than WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not using TLS v1.3.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
const char* list = "P-384:P-256";
...
ret = wolfSSL_CTX_set1_groups_list(ctx, list);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_set1_groups_list

int wolfSSL_set1_groups_list(
    WOLFSSL * ssl,
    char * list
)

This function sets the list of elliptic curve groups to allow on a wolfSSL in order of preference. The list is a null-terminated text string, and a colon-delimited list. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
list a string that is a colon separated list of key exchange groups.

See:

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 elliptic curve groups to allow on a wolfSSL context in order of preference. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
groups a list of key exchange groups by identifier.
count the number of key exchange groups in groups.

See:

Return:

BAD_FUNC_ARG if a pointer parameter is null, the number of groups exceeds WOLFSSL_MAX_GROUP_COUNT or not using TLS v1.3.
WOLFSSL_SUCCESS if successful.

Example

int ret;
WOLFSSL_CTX* ctx;
int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
int count = 2;
...
ret = wolfSSL_CTX_set1_groups_list(ctx, groups, count);
if (ret != WOLFSSL_SUCCESS) {
    // failed to set group list
}

function wolfSSL_set_groups

int wolfSSL_set_groups(
    WOLFSSL * ssl,
    int * groups,
    int count
)

This function sets the list of elliptic curve groups to allow on a wolfSSL. The list is an array of group identifiers with the number of identifiers specified in count. Call this function to set the key exchange elliptic curve parameters to use with the TLS v1.3 connections.

Parameters:

ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
groups a list of key exchange groups by identifier.
count the number of key exchange groups in groups.

See:

Return:

BAD_FUNC_ARG if a pointer parameter is null, the number of groups exceeds WOLFSSL_MAX_GROUP_COUNT, any of the identifiers are unrecognized or not using TLS v1.3.
WOLFSSL_SUCCESS if successful.

Example

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

function wolfSSL_CTX_set_max_early_data

int wolfSSL_CTX_set_max_early_data(
    WOLFSSL_CTX * ctx,
    unsigned int sz
)

This function sets the maximum amount of early data that a TLS v1.3 client or server is willing to exchange using the wolfSSL context. Call this function to limit the amount of early data to process to mitigate replay attacks. Early data is protected by keys derived from those of the connection that the session ticket was sent and therefore will be the same every time a session ticket is used in resumption. The value is included in the session ticket for resumption. A server value of zero indicates no early data is to be sent by client using session tickets. A client value of zero indicates that the client will not send any early data. It is recommended that the number of early data bytes be kept as low as practically possible in the application.

Parameters:

ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new().
sz the amount of early data to accept in bytes.

See:

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

See:

wolfSSL_SetCookieCtx
wolfSSL_CTX_SetGenCookie

Return:

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

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
}

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

Updated on 2024-11-21 at 01:17:07 +0000