wolfSSL Context and Session Set Up

Functions
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).
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().
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().
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().
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().
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().
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().
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().
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().
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).
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).
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.
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.
WOLFSSL_API long	wolfSSL_CTX_get_verify_depth (WOLFSSL_CTX *ctx)
	This function gets the certificate chaining depth using the CTX structure.
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.
WOLFSSL_API WOLFSSL *	wolfSSL_new (WOLFSSL_CTX *)
	This function creates a new SSL session, taking an already created SSL context as input.
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.
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.
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.
WOLFSSL_API void	wolfSSL_free (WOLFSSL *)
	This function frees an allocated wolfSSL object.
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.
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.
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.
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.
WOLFSSL_API int	wolfSSL_CTX_memrestore_cert_cache (WOLFSSL_CTX *, const void *, int)
	This function restores the certificate cache from memory.
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)
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)
WOLFSSL_API int	wolfSSL_dtls_set_timeout_init (WOLFSSL *ssl, int)
	This function sets the dtls timeout.
WOLFSSL_API WOLFSSL_SESSION *	wolfSSL_get1_session (WOLFSSL *ssl)
	This function returns the WOLFSSL_SESSION from the WOLFSSL structure.
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.
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.
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.
WOLFSSL_API int	wolfSSL_CTX_get_read_ahead (WOLFSSL_CTX *)
	This function returns the get read ahead flag from a WOLFSSL_CTX structure.
WOLFSSL_API int	wolfSSL_CTX_set_read_ahead (WOLFSSL_CTX *, int v)
	This function sets the read ahead flag in the WOLFSSL_CTX structure.
WOLFSSL_API long	wolfSSL_CTX_set_tlsext_status_arg (WOLFSSL_CTX *, void *arg)
	This function sets the options argument to use with OCSP.
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.
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.
WOLFSSL_API long	wolfSSL_get_options (const WOLFSSL *s)
	This function returns the current options mask.
WOLFSSL_API long	wolfSSL_set_tlsext_debug_arg (WOLFSSL *s, void *arg)
	This is used to set the debug argument passed around.
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.
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.
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().
WOLFSSL_API int	wolfSSL_state (WOLFSSL *ssl)
	This is used to get the internal error state of the WOLFSSL structure.
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.
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.
WOLFSSL_API int	wolfSSL_set_timeout (WOLFSSL *, unsigned int)
	This function sets the SSL session timeout value in seconds.
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.
WOLFSSL_API int	wolfSSL_CTX_UnloadCAs (WOLFSSL_CTX *)
	This function unloads the CA signer list and frees the whole signer table.
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.
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.
WOLFSSL_API int	wolfSSL_CTX_set_group_messages (WOLFSSL_CTX *)
	This function turns on grouping of handshake messages where possible.
WOLFSSL_API int	wolfSSL_set_group_messages (WOLFSSL *)
	This function turns on grouping of handshake messages where possible.
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).
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.
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.
WOLFSSL_API int	wolfSSL_CTX_UseSessionTicket (WOLFSSL_CTX *ctx)
	This function sets wolfSSL context to use a session ticket.
WOLFSSL_API int	wolfSSL_UseSupportedQSH (WOLFSSL *ssl, unsigned short name)
	This function sets the ssl session to use supported QSH provided by name.
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.
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.
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.
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.
WOLFSSL_API int	wolfSSL_SESSION_get_master_key_length (const WOLFSSL_SESSION *ses)
	This is used to get the master secret key length.
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.
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.
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.
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.
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.
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.
WOLFSSL_API long	wolfSSL_CTX_clear_options (WOLFSSL_CTX *, long)
	This function resets option bits of WOLFSSL_CTX object.
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.
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.
WOLFSSL_API void *	wolfSSL_GetCookieCtx (WOLFSSL *ssl)
	This function returns the IOCB_CookieCtx member of the WOLFSSL structure.

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

none	No parameters.

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;
 
method = wolfDTLSv1_client_method();
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

none	No parameters.

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;
 
method = wolfDTLSv1_server_method();
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

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.

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

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

ssl	a pointer to a WOLFSSL structure, created using wolfSSL_new().
dn	domain 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

ssl	WOLFSSL structure to check.

Example

WOLFSSL* ssl;
int ret;
// create and set up ssl
ret  = wolfSSL_check_private_key(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 *	ctx,
		WOLFSSL_X509 *	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

ctx	WOLFSSL_CTX structure to add certificate to.
x509	certificate to add 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

See also

wolfSSL_CTX_new

wolfSSL_CTX_free

wolfSSL_CTX_allow_anon_cipher()

WOLFSSL_API int wolfSSL_CTX_allow_anon_cipher

(

WOLFSSL_CTX *

ctx

)

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

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

ctx	a 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){
    wolfSSL_CTX_allow_anon_cipher(ctx);
    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 *	ctx,
		long	opt )

This function resets option bits of WOLFSSL_CTX object.

Returns

option new option bits

Parameters

ctx	pointer 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 *

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

ctx	pointer 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

ctx	pointer to the WOLFSSL_CTX structure for getting cert store pointer.

Example

WOLFSSL_CTX ctx;
WOLFSSL_X509_STORE* st;
// setup ctx
st = wolfSSL_CTX_get_cert_store(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

ctx	WOLFSSL_CTX structure to get call back from.

Example

WOLFSSL_CTX* ctx;
pem_password_cb cb;
// setup ctx
cb = wolfSSL_CTX_get_default_passwd_cb(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

ctx	WOLFSSL_CTX structure to get user data from.

Example

WOLFSSL_CTX* ctx;
void* data;
// setup ctx
data = wolfSSL_CTX_get_default_passwd_cb(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 *

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

ctx	WOLFSSL_CTX structure to get read ahead flag from.

Example

WOLFSSL_CTX* ctx;
int flag;
// setup ctx
flag = wolfSSL_CTX_get_read_ahead(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

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

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
}

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 *	ctx,
		const void *	mem,
		int	sz )

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

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.

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 *

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

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.

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
}

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

ctx	pointer to the WOLFSSL_CTX structure for setting cert store pointer.
str	pointer to the WOLFSSL_X509_STORE to set in ctx.

Example

WOLFSSL_CTX ctx;
WOLFSSL_X509_STORE* st;
// setup ctx and st
st = wolfSSL_CTX_set_cert_store(ctx, 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 *	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)

Returns

SSL_SUCCESS will be returned upon successful function completion.

SSL_FAILURE will be returned on failure.

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.

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
}

See also

wolfSSL_set_cipher_list

wolfSSL_CTX_new

wolfSSL_CTX_set_group_messages()

WOLFSSL_API int wolfSSL_CTX_set_group_messages

(

WOLFSSL_CTX *

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

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

Example

WOLFSSL_CTX* ctx = 0;
...
ret = wolfSSL_CTX_set_group_messages(ctx);
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 *	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

ctx	WOLFSSL_CTX structure to set read ahead flag.

Example

WOLFSSL_CTX* ctx;
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 *	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.

Returns

SSL_SUCCESS will be returned upon success.

Parameters

ctx	pointer to the SSL context, created with wolfSSL_CTX_new().
mode	modifier 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 *	ctx,
		unsigned int	to )

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

ctx	pointer to the SSL context, created with wolfSSL_CTX_new().
to	session 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 *	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

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

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

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

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

Example

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

See also

wolfSSL_CTX_new

wolfSSL_CTX_free

wolfSSL_CTX_set_verify()

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

Returns

none No return.

Parameters

ctx	pointer to the SSL context, created with wolfSSL_CTX_new().
mode	session timeout value in seconds
verify_callback	callback 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

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.

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

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

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.

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

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

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

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.

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 *

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

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

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_Unload_trust_peers(ctx);
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 *

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

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

Example

WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
…
if(!wolfSSL_CTX_UnloadCAs(ctx)){
    // 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

ctx	The WOLFSSL_CTX structure to use.

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
}

See also

TLSX_UseSessionTicket

wolfSSL_dtls_set_timeout_init()

WOLFSSL_API int wolfSSL_dtls_set_timeout_init	(	WOLFSSL *	ssl,
		int	timeout )

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

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.

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

See also

wolfSSL_dtls_set_timeout_max

wolfSSL_dtls_got_timeout

wolfSSL_free()

WOLFSSL_API void wolfSSL_free

(

WOLFSSL *

ssl

)

This function frees an allocated wolfSSL object.

Returns

none No return.

Parameters

ssl	pointer 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

ssl	WOLFSSL structure to get session from.

Example

WOLFSSL* ssl;
WOLFSSL_SESSION* ses;
// attempt/complete handshake
ses  = wolfSSL_get1_session(ssl);
// 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

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)

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

ssl	WOLFSSL 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

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)

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

ssl	WOLFSSL structure to get verification results from.

Example

WOLFSSL* ssl;
long ret;
// attempt/complete handshake
ret  = wolfSSL_get_verify_result(ssl);
// 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

ssl	a 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 *

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

ctx	pointer 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

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)

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

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

ses	WOLFSSL_SESSION structure to get master secret buffer from.

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

See also

wolfSSL_new

wolfSSL_free

wolfSSL_set_cipher_list()

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

Returns

SSL_SUCCESS will be returned upon successful function completion.

SSL_FAILURE will be returned on failure.

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.

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
}

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

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

Example

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

See also

none

wolfSSL_set_fd()

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

Returns

SSL_SUCCESS upon success.

Bad_FUNC_ARG upon failure.

Parameters

ssl	pointer to the SSL session, created with wolfSSL_new().
fd	file 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 *

ssl

)

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

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

Example

WOLFSSL* ssl = 0;
...
ret = wolfSSL_set_group_messages(ssl);
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

ssl	WOLFSSL 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

ssl	WOLFSSL 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
wolfSSL_set_msg_callback(ssl, arg);

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

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

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

ssl	pointer to the SSL object, created with wolfSSL_new().
session	pointer 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 *	ssl,
		unsigned int	to )

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

ssl	pointer to the SSL object, created with wolfSSL_new().
to	value, 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

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

Example

WOLFSSL* ssl;
void* args;
int ret;
// create ssl object
ret  = wolfSSL_set_tlsext_debug_arg(ssl, args);
// 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

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.

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

Returns

none No return.

Parameters

ssl	pointer to the SSL session, created with wolfSSL_new().
mode	session timeout value in seconds.
verify_callback	callback 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

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.

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

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

ssl	WOLFSSL structure to set certificate in.
x509	certificate to use.

Example

 WOLFSSL* ssl;
WOLFSSL_X509* x509
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

ssl	WOLFSSL structure to set certificate in.
der	DER certificate to use.
derSz	size 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 *	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.

Returns

0 upon success

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.

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

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.

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) != 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

ssl	Pointer to ssl session to use.
name	Name of a supported QSH. Valid names are WOLFSSL_NTRU_EESS439, WOLFSSL_NTRU_EESS593, or WOLFSSL_NTRU_EESS743.

Example

wolfSSL_Init();
WOLFSSL_CTX* ctx;
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

none	No parameters

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;
method = wolfSSLv23_client_method();
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

none	No parameters.

Example

WOLFSSL* ctx;
ctx  = wolfSSL_CTX_new(wolfSSLv23_method());
// 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

none	No parameters

Example

WOLFSSL_METHOD* method;
WOLFSSL_CTX* ctx;
 
method = wolfSSLv23_server_method();
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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

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

none	No parameters.

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

See also

wolfSSLv3_server_method

wolfTLSv1_1_server_method

wolfTLSv1_2_server_method

wolfDTLSv1_server_method

wolfSSLv23_server_method

wolfSSL_CTX_new