Functions
wolfSSL Context and Session Set Up

Functions

WOLFSSL_API WOLFSSL_METHODwolfSSLv23_method (void)
 This function returns a WOLFSSL_METHOD similar to wolfSSLv23_client_method except that it is not determined which side yet (server/client). More...
 
WOLFSSL_API WOLFSSL_METHODwolfSSLv3_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfSSLv3_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfTLSv1_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(). More...
 
WOLFSSL_API WOLFSSL_METHODwolfDTLSv1_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). More...
 
WOLFSSL_API WOLFSSL_METHODwolfDTLSv1_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). More...
 
WOLFSSL_API int wolfSSL_use_old_poly (WOLFSSL *, int)
 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. More...
 
WOLFSSL_API int wolfSSL_CTX_trust_peer_cert (WOLFSSL_CTX *, const char *, int)
 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. More...
 
WOLFSSL_API long wolfSSL_CTX_get_verify_depth (WOLFSSL_CTX *ctx)
 This function gets the certificate chaining depth using the CTX structure. More...
 
WOLFSSL_API WOLFSSL_CTXwolfSSL_CTX_new (WOLFSSL_METHOD *)
 This function creates a new SSL context, taking a desired SSL/TLS protocol method for input. More...
 
WOLFSSL_API WOLFSSLwolfSSL_new (WOLFSSL_CTX *)
 This function creates a new SSL session, taking an already created SSL context as input. More...
 
WOLFSSL_API int wolfSSL_set_fd (WOLFSSL *, int)
 This function assigns a file descriptor (fd) as the input/output facility for the SSL connection. Typically this will be a socket file descriptor. More...
 
WOLFSSL_API void wolfSSL_set_using_nonblock (WOLFSSL *, int)
 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. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API void wolfSSL_free (WOLFSSL *)
 This function frees an allocated wolfSSL object. More...
 
WOLFSSL_API int wolfSSL_set_session (WOLFSSL *, WOLFSSL_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_get_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. More...
 
WOLFSSL_API void wolfSSL_CTX_set_verify (WOLFSSL_CTX *, int, 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. More...
 
WOLFSSL_API void wolfSSL_set_verify (WOLFSSL *, int, 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. More...
 
WOLFSSL_API long wolfSSL_CTX_set_session_cache_mode (WOLFSSL_CTX *, long)
 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. More...
 
WOLFSSL_API int wolfSSL_CTX_memrestore_cert_cache (WOLFSSL_CTX *, const void *, int)
 This function restores the certificate cache from memory. More...
 
WOLFSSL_API int wolfSSL_CTX_set_cipher_list (WOLFSSL_CTX *, const char *)
 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) More...
 
WOLFSSL_API int wolfSSL_set_cipher_list (WOLFSSL *, const char *)
 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) More...
 
WOLFSSL_API int wolfSSL_dtls_set_timeout_init (WOLFSSL *ssl, int)
 This function sets the dtls timeout. More...
 
WOLFSSL_API WOLFSSL_SESSIONwolfSSL_get1_session (WOLFSSL *ssl)
 This function returns the WOLFSSL_SESSION from the WOLFSSL structure. More...
 
WOLFSSL_API WOLFSSL_METHODwolfSSLv23_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.2. 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.2. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API long wolfSSL_CTX_add_extra_chain_cert (WOLFSSL_CTX *, WOLFSSL_X509 *)
 This function adds the certificate to the internal chain being built in the WOLFSSL_CTX structure. More...
 
WOLFSSL_API int wolfSSL_CTX_get_read_ahead (WOLFSSL_CTX *)
 This function returns the get read ahead flag from a WOLFSSL_CTX structure. More...
 
WOLFSSL_API int wolfSSL_CTX_set_read_ahead (WOLFSSL_CTX *, int v)
 This function sets the read ahead flag in the WOLFSSL_CTX structure. More...
 
WOLFSSL_API long wolfSSL_CTX_set_tlsext_status_arg (WOLFSSL_CTX *, void *arg)
 This function sets the options argument to use with OCSP. More...
 
WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg (WOLFSSL_CTX *, void *arg)
 This function sets the optional argument to be passed to the PRF callback. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API long wolfSSL_get_options (const WOLFSSL *s)
 This function returns the current options mask. More...
 
WOLFSSL_API long wolfSSL_set_tlsext_debug_arg (WOLFSSL *s, void *arg)
 This is used to set the debug argument passed around. More...
 
WOLFSSL_API long wolfSSL_get_verify_result (const WOLFSSL *ssl)
 This is used to get the results after trying to verify the peer's certificate. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API WOLFSSL_METHODwolfSSLv23_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.2. 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(). More...
 
WOLFSSL_API int wolfSSL_state (WOLFSSL *ssl)
 This is used to get the internal error state of the WOLFSSL structure. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API int wolfSSL_set_timeout (WOLFSSL *, unsigned int)
 This function sets the SSL session timeout value in seconds. More...
 
WOLFSSL_API int wolfSSL_CTX_set_timeout (WOLFSSL_CTX *, unsigned int)
 This function sets the timeout value for SSL sessions, in seconds, for the specified SSL context. More...
 
WOLFSSL_API int wolfSSL_CTX_UnloadCAs (WOLFSSL_CTX *)
 This function unloads the CA signer list and frees the whole signer table. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API int wolfSSL_CTX_trust_peer_buffer (WOLFSSL_CTX *, const unsigned char *, long, int)
 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. More...
 
WOLFSSL_API int wolfSSL_CTX_set_group_messages (WOLFSSL_CTX *)
 This function turns on grouping of handshake messages where possible. More...
 
WOLFSSL_API int wolfSSL_set_group_messages (WOLFSSL *)
 This function turns on grouping of handshake messages where possible. More...
 
WOLFSSL_API 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). More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API int wolfSSL_UseALPN (WOLFSSL *ssl, char *protocol_name_list, unsigned int protocol_name_listSz, unsigned char options)
 Setup ALPN use for a wolfSSL session. More...
 
WOLFSSL_API int wolfSSL_CTX_UseSessionTicket (WOLFSSL_CTX *ctx)
 This function sets wolfSSL context to use a session ticket. More...
 
WOLFSSL_API int wolfSSL_UseSupportedQSH (WOLFSSL *ssl, unsigned short name)
 This function sets the ssl session to use supported QSH provided by name. More...
 
WOLFSSL_API int wolfSSL_check_private_key (const WOLFSSL *ssl)
 This function checks that the private key is a match with the certificate being used. More...
 
WOLFSSL_API int wolfSSL_use_certificate (WOLFSSL *ssl, WOLFSSL_X509 *x509)
 his is used to set the certificate for WOLFSSL structure to use during a handshake. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API int wolfSSL_SESSION_get_master_key_length (const WOLFSSL_SESSION *ses)
 This is used to get the master secret key length. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API WOLFSSL_X509_STOREwolfSSL_CTX_get_cert_store (WOLFSSL_CTX *ctx)
 This is a getter function for the WOLFSSL_X509_STORE structure in ctx. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API pem_password_cb * wolfSSL_CTX_get_default_passwd_cb (WOLFSSL_CTX *ctx)
 This is a getter function for the password callback set in ctx. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API long wolfSSL_CTX_clear_options (WOLFSSL_CTX *, long)
 This function resets option bits of WOLFSSL_CTX object. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API 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. More...
 
WOLFSSL_API void * wolfSSL_GetCookieCtx (WOLFSSL *ssl)
 This function returns the IOCB_CookieCtx member of the WOLFSSL structure. More...
 

Detailed Description

Function Documentation

◆ wolfDTLSv1_client_method()

WOLFSSL_API 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).

Returns
* 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).
Parameters
noneNo parameters.

Example

if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_client_method
wolfTLSv1_client_method
wolfTLSv1_1_client_method
wolfTLSv1_2_client_method
wolfSSLv23_client_method
wolfSSL_CTX_new

◆ wolfDTLSv1_server_method()

WOLFSSL_API 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).

Returns
* 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).
Parameters
noneNo parameters.

Example

if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_server_method
wolfTLSv1_server_method
wolfTLSv1_1_server_method
wolfTLSv1_2_server_method
wolfSSLv23_server_method
wolfSSL_CTX_new

◆ wolfSSL_ASN1_INTEGER_to_BN()

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

Returns
pointer On successfully copying the WOLFSSL_ASN1_INTEGER value a WOLFSSL_BIGNUM pointer is returned.
Null upon failure.
Parameters
aiWOLFSSL_ASN1_INTEGER structure to copy from.
bnif 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.

Example

WOLFSSL_BIGNUM* bn;
// create ai
// 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
See also
none

◆ wolfSSL_check_domain_name()

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

Returns
SSL_SUCCESS upon success.
SSL_FAILURE will be returned if a memory error was encountered.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
dndomain name to check against the peer certificate when received.

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
}
See also
none

◆ wolfSSL_check_private_key()

WOLFSSL_API int wolfSSL_check_private_key ( const WOLFSSL ssl)

This function checks that the private key is a match with the certificate being used.

Returns
SSL_SUCCESS On successfully match.
SSL_FAILURE If an error case was encountered.
<0 All error cases other than SSL_FAILURE are negative values.
Parameters
sslWOLFSSL structure to check.

Example

WOLFSSL* ssl;
int ret;
// create and set up ssl
// check ret value
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_CTX_add_extra_chain_cert()

WOLFSSL_API long wolfSSL_CTX_add_extra_chain_cert ( WOLFSSL_CTX ,
WOLFSSL_X509  
)

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

Returns
SSL_SUCCESS after successfully adding the certificate.
SSL_FAILURE if failing to add the certificate to the chain.
Parameters
ctxWOLFSSL_CTX structure to add certificate to.
x509certificate to add to the chain.

Example

int ret;
// create ctx
// check ret value
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_allow_anon_cipher()

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

Returns
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.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example

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

◆ wolfSSL_CTX_clear_options()

WOLFSSL_API long wolfSSL_CTX_clear_options ( WOLFSSL_CTX ,
long   
)

This function resets option bits of WOLFSSL_CTX object.

Returns
option new option bits
Parameters
ctxpointer to the SSL context.

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);
See also
wolfSSL_CTX_new
wolfSSL_new
wolfSSL_free

◆ wolfSSL_CTX_free()

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

Returns
none No return.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_free(ctx);
See also
wolfSSL_CTX_new
wolfSSL_new
wolfSSL_free

◆ wolfSSL_CTX_get_cert_store()

WOLFSSL_API WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store ( WOLFSSL_CTX ctx)

This is a getter function for the WOLFSSL_X509_STORE structure in ctx.

Returns
WOLFSSL_X509_STORE* On successfully getting the pointer.
NULL Returned if NULL arguments are passed in.
Parameters
ctxpointer to the WOLFSSL_CTX structure for getting cert store pointer.

Example

// setup ctx
//use st
See also
wolfSSL_CTX_new
wolfSSL_CTX_free
wolfSSL_CTX_set_cert_store

◆ wolfSSL_CTX_get_default_passwd_cb()

WOLFSSL_API pem_password_cb* wolfSSL_CTX_get_default_passwd_cb ( WOLFSSL_CTX ctx)

This is a getter function for the password callback set in ctx.

Returns
func On success returns the callback function.
NULL If ctx is NULL then NULL is returned.
Parameters
ctxWOLFSSL_CTX structure to get call back from.

Example

pem_password_cb cb;
// setup ctx
//use cb
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_get_default_passwd_cb_userdata()

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

Returns
pointer On success returns the user data pointer.
NULL If ctx is NULL then NULL is returned.
Parameters
ctxWOLFSSL_CTX structure to get user data from.

Example

void* data;
// setup ctx
//use data
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_get_read_ahead()

WOLFSSL_API int wolfSSL_CTX_get_read_ahead ( WOLFSSL_CTX )

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

Returns
flag On success returns the read ahead flag.
SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
Parameters
ctxWOLFSSL_CTX structure to get read ahead flag from.

Example

int flag;
// setup ctx
//check flag
See also
wolfSSL_CTX_new
wolfSSL_CTX_free
wolfSSL_CTX_set_read_ahead

◆ wolfSSL_CTX_get_verify_depth()

WOLFSSL_API long wolfSSL_CTX_get_verify_depth ( WOLFSSL_CTX ctx)

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

Returns
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.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example

WOLFSSL_METHOD method; // protocol method
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
if(ret == EXPECTED){
// You have the expected value
} else {
// Handle an unexpected depth
}
See also
wolfSSL_CTX_use_certificate_chain_file
wolfSSL_get_verify_depth

◆ wolfSSL_CTX_memrestore_cert_cache()

WOLFSSL_API int wolfSSL_CTX_memrestore_cert_cache ( WOLFSSL_CTX ,
const void *  ,
int   
)

This function restores the certificate cache from memory.

Returns
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.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
mema void pointer with a value that will be restored to the certificate cache.
szan int type that represents the size of the mem parameter.

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
}
See also
CM_MemRestoreCertCache

◆ wolfSSL_CTX_new()

WOLFSSL_API WOLFSSL_CTX* wolfSSL_CTX_new ( WOLFSSL_METHOD )

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

Returns
pointer If successful the call will return a pointer to the newly-created WOLFSSL_CTX.
NULL upon failure.
Parameters
methodpointer 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.

Example

WOLFSSL_CTX* ctx = 0;
WOLFSSL_METHOD* method = 0;
if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
if (ctx == NULL) {
// context creation failed
}
See also
wolfSSL_new

◆ wolfSSL_CTX_set_cert_store()

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

Returns
none No return.
Parameters
ctxpointer to the WOLFSSL_CTX structure for setting cert store pointer.
strpointer to the WOLFSSL_X509_STORE to set in ctx.

Example

// setup ctx and st
//use st
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_set_cipher_list()

WOLFSSL_API int wolfSSL_CTX_set_cipher_list ( WOLFSSL_CTX ,
const char *   
)

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)

Returns
SSL_SUCCESS will be returned upon successful function completion.
SSL_FAILURE will be returned on failure.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
listnull-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL context.

Example

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

◆ wolfSSL_CTX_set_group_messages()

WOLFSSL_API int wolfSSL_CTX_set_group_messages ( WOLFSSL_CTX )

This function turns on grouping of handshake messages where possible.

Returns
SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().

Example

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

◆ wolfSSL_CTX_set_read_ahead()

WOLFSSL_API int wolfSSL_CTX_set_read_ahead ( WOLFSSL_CTX ,
int  v 
)

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

Returns
SSL_SUCCESS If ctx read ahead flag set.
SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
Parameters
ctxWOLFSSL_CTX structure to set read ahead flag.

Example

int flag;
int ret;
// setup ctx
ret = wolfSSL_CTX_set_read_ahead(ctx, flag);
// check return value
See also
wolfSSL_CTX_new
wolfSSL_CTX_free
wolfSSL_CTX_get_read_ahead

◆ wolfSSL_CTX_set_session_cache_mode()

WOLFSSL_API long wolfSSL_CTX_set_session_cache_mode ( WOLFSSL_CTX ,
long   
)

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.

Returns
SSL_SUCCESS will be returned upon success.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
modemodifier used to change behavior of the session cache.

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
}
See also
wolfSSL_flush_sessions
wolfSSL_get_session
wolfSSL_set_session
wolfSSL_get_sessionID
wolfSSL_CTX_set_timeout

◆ wolfSSL_CTX_set_timeout()

WOLFSSL_API int wolfSSL_CTX_set_timeout ( WOLFSSL_CTX ,
unsigned  int 
)

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

Returns
SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned when the input context (ctx) is null.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
tosession timeout value in seconds.

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_timeout(ctx, 500);
if (ret != SSL_SUCCESS) {
// failed to set session timeout value
}
See also
wolfSSL_flush_sessions
wolfSSL_get_session
wolfSSL_set_session
wolfSSL_get_sessionID
wolfSSL_CTX_set_session_cache_mode

◆ wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg()

WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg ( WOLFSSL_CTX ,
void *  arg 
)

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

Returns
SSL_FAILURE If ctx is NULL.
SSL_SUCCESS If successfully set.
Parameters
ctxWOLFSSL_CTX structure to set user argument.
arguser argument.

Example

void* data;
int ret;
// setup ctx
ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data);
//check ret value
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_set_tlsext_status_arg()

WOLFSSL_API long wolfSSL_CTX_set_tlsext_status_arg ( WOLFSSL_CTX ,
void *  arg 
)

This function sets the options argument to use with OCSP.

Returns
SSL_FAILURE If ctx or it’s cert manager is NULL.
SSL_SUCCESS If successfully set.
Parameters
ctxWOLFSSL_CTX structure to set user argument.
arguser argument.

Example

void* data;
int ret;
// setup ctx
//check ret value
See also
wolfSSL_CTX_new
wolfSSL_CTX_free

◆ wolfSSL_CTX_set_verify()

WOLFSSL_API void wolfSSL_CTX_set_verify ( WOLFSSL_CTX ,
int  ,
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.

Returns
none No return.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
modesession timeout value in seconds
verify_callbackcallback to be called when verification fails. If no callback is desired, the NULL pointer can be used for verify_callback.

Example

WOLFSSL_CTX* ctx = 0;
...
wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_PEER |
SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);
See also
wolfSSL_set_verify

◆ wolfSSL_CTX_SetMinVersion()

WOLFSSL_API 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).

Returns
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.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
versionan 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.

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
}
See also
SetMinVersionHelper

◆ wolfSSL_CTX_trust_peer_buffer()

WOLFSSL_API int wolfSSL_CTX_trust_peer_buffer ( WOLFSSL_CTX ,
const unsigned char *  ,
long  ,
int   
)

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.

Returns
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.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
bufferpointer to the buffer containing certificates.
szlength of the buffer input.
typetype of certificate being loaded i.e. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Example

int ret = 0;
...
ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz,
SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
// error loading trusted peer cert
}
...
See also
wolfSSL_CTX_load_verify_buffer
wolfSSL_CTX_use_certificate_file
wolfSSL_CTX_use_PrivateKey_file
wolfSSL_CTX_use_NTRUPrivateKey_file
wolfSSL_CTX_use_certificate_chain_file
wolfSSL_CTX_trust_peer_cert
wolfSSL_CTX_Unload_trust_peers
wolfSSL_use_certificate_file
wolfSSL_use_PrivateKey_file
wolfSSL_use_certificate_chain_file

◆ wolfSSL_CTX_trust_peer_cert()

WOLFSSL_API int wolfSSL_CTX_trust_peer_cert ( WOLFSSL_CTX ,
const char *  ,
int   
)

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.

Returns
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.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().
filepointer to name of the file containing certificates
typetype of certificate being loaded ie SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

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
}
...
See also
wolfSSL_CTX_load_verify_buffer
wolfSSL_CTX_use_certificate_file
wolfSSL_CTX_use_PrivateKey_file
wolfSSL_CTX_use_NTRUPrivateKey_file
wolfSSL_CTX_use_certificate_chain_file
wolfSSL_CTX_trust_peer_buffer
wolfSSL_CTX_Unload_trust_peers
wolfSSL_use_certificate_file
wolfSSL_use_PrivateKey_file
wolfSSL_use_certificate_chain_file

◆ wolfSSL_CTX_Unload_trust_peers()

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

Returns
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.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().

Example

int ret = 0;
...
if (ret != SSL_SUCCESS) {
// error unloading trusted peer certs
}
...
See also
wolfSSL_CTX_trust_peer_buffer
wolfSSL_CTX_trust_peer_cert

◆ wolfSSL_CTX_UnloadCAs()

WOLFSSL_API int wolfSSL_CTX_UnloadCAs ( WOLFSSL_CTX )

This function unloads the CA signer list and frees the whole signer table.

Returns
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.
Parameters
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().

Example

WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
// The function did not unload CAs
}
See also
wolfSSL_CertManagerUnloadCAs
LockMutex
FreeSignerTable
UnlockMutex

◆ wolfSSL_CTX_UseSessionTicket()

WOLFSSL_API int wolfSSL_CTX_UseSessionTicket ( WOLFSSL_CTX ctx)

This function sets wolfSSL context to use a session ticket.

Returns
SSL_SUCCESS Function executed successfully.
BAD_FUNC_ARG Returned if ctx is null.
MEMORY_E Error allocating memory in internal function.
Parameters
ctxThe WOLFSSL_CTX structure to use.

Example

WOLFSSL_METHOD method = // Some wolfSSL method ;
ctx = wolfSSL_CTX_new(method);
if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS)
{
// Error setting session ticket
}
See also
TLSX_UseSessionTicket

◆ wolfSSL_dtls_set_timeout_init()

WOLFSSL_API int wolfSSL_dtls_set_timeout_init ( WOLFSSL ssl,
int   
)

This function sets the dtls timeout.

Returns
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.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
timeoutan int type that will be set to the dtls_timeout_init member of the WOLFSSL structure.

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
WOLFSSL* ssl = wolfSSL_new(ctx);
int timeout = TIMEOUT;
...
// the dtls timeout was set
} else {
// Failed to set DTLS timeout.
}
See also
wolfSSL_dtls_set_timeout_max
wolfSSL_dtls_got_timeout

◆ wolfSSL_free()

WOLFSSL_API void wolfSSL_free ( WOLFSSL )

This function frees an allocated wolfSSL object.

Returns
none No return.
Parameters
sslpointer to the SSL object, created with wolfSSL_new().

Example

#include <wolfssl/ssl.h>
WOLFSSL* ssl = 0;
...
wolfSSL_free(ssl);
See also
wolfSSL_CTX_new
wolfSSL_new
wolfSSL_CTX_free

◆ wolfSSL_get1_session()

WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get1_session ( WOLFSSL ssl)

This function returns the WOLFSSL_SESSION from the WOLFSSL structure.

Returns
WOLFSSL_SESSION On success return session pointer.
NULL on failure returns NULL.
Parameters
sslWOLFSSL structure to get session from.

Example

WOLFSSL* ssl;
// attempt/complete handshake
// check ses information
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_get_client_random()

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

Returns
>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
Parameters
sslWOLFSSL structure to get clients random data buffer from.
outbuffer to hold random data.
outSzsize of out buffer passed in. (if 0 function will return max buffer size needed)

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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_get_options()

WOLFSSL_API long wolfSSL_get_options ( const WOLFSSL s)

This function returns the current options mask.

Returns
val Returns the mask value stored in ssl.
Parameters
sslWOLFSSL structure to get options mask from.

Example

WOLFSSL* ssl;
unsigned long mask;
mask = wolfSSL_get_options(ssl);
// check mask
See also
wolfSSL_new
wolfSSL_free
wolfSSL_set_options

◆ wolfSSL_get_server_random()

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

Returns
>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
Parameters
sslWOLFSSL structure to get clients random data buffer from.
outbuffer to hold random data.
outSzsize of out buffer passed in. (if 0 function will return max buffer size needed)

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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_get_verify_result()

WOLFSSL_API long wolfSSL_get_verify_result ( const WOLFSSL ssl)

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

Returns
X509_V_OK On successful verification.
SSL_FAILURE If an NULL ssl passed in.
Parameters
sslWOLFSSL structure to get verification results from.

Example

WOLFSSL* ssl;
long ret;
// attempt/complete handshake
// check ret value
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_GetCookieCtx()

WOLFSSL_API void* wolfSSL_GetCookieCtx ( WOLFSSL ssl)

This function returns the IOCB_CookieCtx member of the WOLFSSL structure.

Returns
pointer The function returns a void pointer value stored in the IOCB_CookieCtx.
NULL if the WOLFSSL struct is NULL
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().

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
}
See also
wolfSSL_SetCookieCtx
wolfSSL_CTX_SetGenCookie

◆ wolfSSL_new()

WOLFSSL_API WOLFSSL* wolfSSL_new ( WOLFSSL_CTX )

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

Returns
* If successful the call will return a pointer to the newly-created wolfSSL structure.
NULL Upon failure.
Parameters
ctxpointer to the SSL context, created with wolfSSL_CTX_new().

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
}
See also
wolfSSL_CTX_new

◆ wolfSSL_SESSION_get_master_key()

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

Returns
>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
Parameters
sesWOLFSSL_SESSION structure to get master secret buffer from.
outbuffer to hold data.
outSzsize of out buffer passed in. (if 0 function will return max buffer size needed)

Example

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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_SESSION_get_master_key_length()

WOLFSSL_API int wolfSSL_SESSION_get_master_key_length ( const WOLFSSL_SESSION ses)

This is used to get the master secret key length.

Returns
size Returns master secret key size.
Parameters
sesWOLFSSL_SESSION structure to get master secret buffer from.

Example

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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_set_cipher_list()

WOLFSSL_API int wolfSSL_set_cipher_list ( WOLFSSL ,
const char *   
)

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)

Returns
SSL_SUCCESS will be returned upon successful function completion.
SSL_FAILURE will be returned on failure.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().
listnull-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL session.

Example

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

◆ wolfSSL_set_compression()

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

Returns
SSL_SUCCESS upon success.
NOT_COMPILED_IN will be returned if compression support wasn’t built into the library.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().

Example

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

◆ wolfSSL_set_fd()

WOLFSSL_API int wolfSSL_set_fd ( WOLFSSL ,
int   
)

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

Returns
SSL_SUCCESS upon success.
Bad_FUNC_ARG upon failure.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().
fdfile descriptor to use with SSL/TLS connection.

Example

int sockfd;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_fd(ssl, sockfd);
if (ret != SSL_SUCCESS) {
// failed to set SSL file descriptor
}
See also
wolfSSL_CTX_SetIOSend
wolfSSL_CTX_SetIORecv
wolfSSL_SetIOReadCtx
wolfSSL_SetIOWriteCtx

◆ wolfSSL_set_group_messages()

WOLFSSL_API int wolfSSL_set_group_messages ( WOLFSSL )

This function turns on grouping of handshake messages where possible.

Returns
SSL_SUCCESS will be returned upon success.
BAD_FUNC_ARG will be returned if the input context is null.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().

Example

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

◆ wolfSSL_set_msg_callback()

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

Returns
SSL_SUCCESS On success.
SSL_FAILURE If an NULL ssl passed in.
Parameters
sslWOLFSSL structure to set callback argument.

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
See also
wolfSSL_set_msg_callback_arg

◆ wolfSSL_set_msg_callback_arg()

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

Returns
none No return.
Parameters
sslWOLFSSL structure to set callback argument.

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
See also
wolfSSL_set_msg_callback

◆ wolfSSL_set_options()

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

Returns
val Returns the updated options mask value stored in ssl.
Parameters
sWOLFSSL structure to set options mask.
opThis 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

Example

WOLFSSL* ssl;
unsigned long mask;
mask = SSL_OP_NO_TLSv1
mask = wolfSSL_set_options(ssl, mask);
// check mask
See also
wolfSSL_new
wolfSSL_free
wolfSSL_get_options

◆ wolfSSL_set_session()

WOLFSSL_API int wolfSSL_set_session ( WOLFSSL ,
WOLFSSL_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_get_session(), which returns a pointer to the session. Later, the application should create a new WOLFSSL object and assign the saved session with wolfSSL_set_session(). At this point, the application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default.

Returns
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.
Parameters
sslpointer to the SSL object, created with wolfSSL_new().
sessionpointer to the WOLFSSL_SESSION used to set the session for ssl.

Example

int ret = 0;
WOLFSSL* ssl = 0;
WOLFSSL_SESSION* session;
...
ret = wolfSSL_get_session(ssl, session);
if (ret != SSL_SUCCESS) {
// failed to set the SSL session
}
...
See also
wolfSSL_get_session

◆ wolfSSL_set_timeout()

WOLFSSL_API int wolfSSL_set_timeout ( WOLFSSL ,
unsigned  int 
)

This function sets the SSL session timeout value in seconds.

Returns
SSL_SUCCESS will be returned upon successfully setting the session.
BAD_FUNC_ARG will be returned if ssl is NULL.
Parameters
sslpointer to the SSL object, created with wolfSSL_new().
tovalue, in seconds, used to set the SSL session timeout.

Example

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_timeout(ssl, 500);
if (ret != SSL_SUCCESS) {
// failed to set session timeout value
}
...
See also
wolfSSL_get_session
wolfSSL_set_session

◆ wolfSSL_set_tlsext_debug_arg()

WOLFSSL_API long wolfSSL_set_tlsext_debug_arg ( WOLFSSL s,
void *  arg 
)

This is used to set the debug argument passed around.

Returns
SSL_SUCCESS On successful setting argument.
SSL_FAILURE If an NULL ssl passed in.
Parameters
sslWOLFSSL structure to set argument in.
argargument to use.

Example

WOLFSSL* ssl;
void* args;
int ret;
// create ssl object
// check ret value
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_set_using_nonblock()

WOLFSSL_API void wolfSSL_set_using_nonblock ( WOLFSSL ,
int   
)

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.

Returns
none No return.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().
nonblockvalue used to set non-blocking flag on WOLFSSL object. Use 1 to specify non-blocking, otherwise 0.

Example

WOLFSSL* ssl = 0;
...
wolfSSL_set_using_nonblock(ssl, 1);
See also
wolfSSL_get_using_nonblock
wolfSSL_dtls_got_timeout
wolfSSL_dtls_get_current_timeout

◆ wolfSSL_set_verify()

WOLFSSL_API void wolfSSL_set_verify ( WOLFSSL ,
int  ,
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.

Returns
none No return.
Parameters
sslpointer to the SSL session, created with wolfSSL_new().
modesession timeout value in seconds.
verify_callbackcallback to be called when verification fails. If no callback is desired, the NULL pointer can be used for verify_callback.

Example

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

◆ wolfSSL_SetVersion()

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

Returns
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.
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
versionSSL/TLS protocol version. Possible values include WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1);
if (ret != SSL_SUCCESS) {
// failed to set SSL session protocol version
}
See also
wolfSSL_CTX_new

◆ wolfSSL_state()

WOLFSSL_API int wolfSSL_state ( WOLFSSL ssl)

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

Returns
wolfssl_error returns ssl error state, usualy 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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_use_certificate()

WOLFSSL_API int wolfSSL_use_certificate ( WOLFSSL ssl,
WOLFSSL_X509 x509 
)

his is used to set the certificate for WOLFSSL structure to use during a handshake.

Returns
SSL_SUCCESS On successful setting argument.
SSL_FAILURE If a NULL argument passed in.
Parameters
sslWOLFSSL structure to set certificate in.
x509certificate to use.

Example

WOLFSSL* ssl;
int ret;
// create ssl object and x509
ret = wolfSSL_use_certificate(ssl, x509);
// check ret value
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_use_certificate_ASN1()

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

Returns
SSL_SUCCESS On successful setting argument.
SSL_FAILURE If a NULL argument passed in.
Parameters
sslWOLFSSL structure to set certificate in.
derDER certificate to use.
derSzsize of the DER buffer 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
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSL_use_old_poly()

WOLFSSL_API int wolfSSL_use_old_poly ( WOLFSSL ,
int   
)

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.

Returns
0 upon success
Parameters
ssla pointer to a WOLFSSL structure, created using wolfSSL_new().
valuewhether 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.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_old_poly(ssl, 1);
if (ret != 0) {
// failed to set poly1305 AEAD version
}
See also
none

◆ wolfSSL_UseALPN()

WOLFSSL_API int wolfSSL_UseALPN ( WOLFSSL ssl,
char *  protocol_name_list,
unsigned int  protocol_name_listSz,
unsigned char  options 
)

Setup ALPN use for a wolfSSL session.

Returns
SSL_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.
Parameters
sslThe wolfSSL session to use.
protocol_name_listList of protocol names to use. Comma delimited string is required.
protocol_name_listSzSize of the list of protocol names.
optionsWOLFSSL_ALPN_CONTINUE_ON_MISMATCH or WOLFSSL_ALPN_FAILED_ON_MISMATCH.

Example

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) != SSL_SUCCESS)
{
// Error setting session ticket
}
See also
TLSX_UseALPN

◆ wolfSSL_UseSupportedQSH()

WOLFSSL_API int wolfSSL_UseSupportedQSH ( WOLFSSL ssl,
unsigned short  name 
)

This function sets the ssl session to use supported QSH provided by name.

Returns
SSL_SUCCESS Successfully set supported QSH.
BAD_FUNC_ARG ssl is null or name is invalid.
MEMORY_E Error allocating memory for operation.
Parameters
sslPointer to ssl session to use.
nameName of a supported QSH. Valid names are WOLFSSL_NTRU_EESS439, WOLFSSL_NTRU_EESS593, or WOLFSSL_NTRU_EESS743.

Example

WOLFSSL* ssl;
WOLFSSL_METHOD method = // Some wolfSSL method ;
ctx = wolfSSL_CTX_new(method);
ssl = wolfSSL_new(ctx);
word16 qsh_name = WOLFSSL_NTRU_EESS439;
if(wolfSSL_UseSupportedQSH(ssl,qsh_name) != SSL_SUCCESS)
{
// Error setting QSH
}
See also
TLSX_UseQSHScheme

◆ wolfSSLv23_client_method()

WOLFSSL_API 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.2. 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.2.

Returns
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).
Parameters
noneNo parameters

Example

if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_client_method
wolfTLSv1_client_method
wolfTLSv1_1_client_method
wolfTLSv1_2_client_method
wolfDTLSv1_client_method
wolfSSL_CTX_new

◆ wolfSSLv23_method()

WOLFSSL_API 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).

Returns
WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD pointer
NULL Null if memory allocation error or failure to create method
Parameters
noneNo parameters.

Example

WOLFSSL* ctx;
// check ret value
See also
wolfSSL_new
wolfSSL_free

◆ wolfSSLv23_server_method()

WOLFSSL_API 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.2. 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().

Returns
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).
Parameters
noneNo parameters

Example

if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_server_method
wolfTLSv1_server_method
wolfTLSv1_1_server_method
wolfTLSv1_2_server_method
wolfDTLSv1_server_method
wolfSSL_CTX_new

◆ wolfSSLv3_client_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfTLSv1_client_method
wolfTLSv1_1_client_method
wolfTLSv1_2_client_method
wolfDTLSv1_client_method
wolfSSLv23_client_method
wolfSSL_CTX_new

◆ wolfSSLv3_server_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfTLSv1_server_method
wolfTLSv1_1_server_method
wolfTLSv1_2_server_method
wolfDTLSv1_server_method
wolfSSLv23_server_method
wolfSSL_CTX_new

◆ wolfTLSv1_1_client_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_client_method
wolfTLSv1_client_method
wolfTLSv1_2_client_method
wolfDTLSv1_client_method
wolfSSLv23_client_method
wolfSSL_CTX_new

◆ wolfTLSv1_1_server_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_server_method
wolfTLSv1_server_method
wolfTLSv1_2_server_method
wolfDTLSv1_server_method
wolfSSLv23_server_method
wolfSSL_CTX_new

◆ wolfTLSv1_2_client_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_client_method
wolfTLSv1_client_method
wolfTLSv1_1_client_method
wolfDTLSv1_client_method
wolfSSLv23_client_method
wolfSSL_CTX_new

◆ wolfTLSv1_2_server_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
// unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_server_method
wolfTLSv1_server_method
wolfTLSv1_1_server_method
wolfDTLSv1_server_method
wolfSSLv23_server_method
wolfSSL_CTX_new

◆ wolfTLSv1_client_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_client_method
wolfTLSv1_1_client_method
wolfTLSv1_2_client_method
wolfDTLSv1_client_method
wolfSSLv23_client_method
wolfSSL_CTX_new

◆ wolfTLSv1_server_method()

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

Returns
* 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).
Parameters
noneNo parameters.

Example

#include <wolfssl/ssl.h>
if (method == NULL) {
unable to get method
}
ctx = wolfSSL_CTX_new(method);
...
See also
wolfSSLv3_server_method
wolfTLSv1_1_server_method
wolfTLSv1_2_server_method
wolfDTLSv1_server_method
wolfSSLv23_server_method
wolfSSL_CTX_new