wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.3  Context and Session Setup


The functions in this section have to do with creating and setting up SSL/TLS context objects (WOLFSSL_CTX) and SSL/TLS session objects (WOLFSSL).






CyaSSLv3_client_method


Synopsis:

#include <cyassl/ssl.h>


CYASSL_METHOD *CyaSSLv3_client_method(void);


Description:

The CyaSSLv3_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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:


This function has no parameters.


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaSSLv3_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaTLSv1_client_method

CyaTLSv1_1_client_method

CyaTLSv1_2_client_method

CyaDTLSv1_client_method

CyaSSLv23_client_method

CyaSSL_CTX_new






CyaSSLv3_server_method


Synopsis:

#include <cyassl/ssl.h>


CYASSL_METHOD *CyaSSLv3_server_method(void);


Description:

The CyaSSLv3_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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:


This function has no parameters.


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaSSLv3_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaTLSv1_server_method

CyaTLSv1_1_server_method

CyaTLSv1_2_server_method

CyaDTLSv1_server_method

CyaSSLv23_server_method

CyaSSL_CTX_new






CyaSSLv23_client_method


Synopsis:

#include <cyassl/ssl.h>


CYASSL_METHOD *CyaSSLv23_client_method(void);


Description:

The CyaSSLv23_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Both CyaSSL 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 CyaSSLv23_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.


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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:


This function has no parameters.


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaSSLv23_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_client_method

CyaTLSv1_client_method

CyaTLSv1_1_client_method

CyaTLSv1_2_client_method

CyaDTLSv1_client_method

CyaSSL_CTX_new






CyaSSLv23_server_method


Synopsis:

#include <cyassl/ssl.h>


CYASSL_METHOD *CyaSSLv23_server_method(void);


Description:

The CyaSSLv23_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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:


This function has no parameters.


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaSSLv23_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_server_method

CyaTLSv1_server_method

CyaTLSv1_1_server_method

CyaTLSv1_2_server_method

CyaDTLSv1_server_method

CyaSSL_CTX_new






CyaTLSv1_client_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_client_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_client_method

CyaTLSv1_1_client_method

CyaTLSv1_2_client_method

CyaDTLSv1_client_method

CyaSSLv23_client_method

CyaSSL_CTX_new






CyaTLSv1_server_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_server_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_server_method

CyaTLSv1_1_server_method

CyaTLSv1_2_server_method

CyaDTLSv1_server_method

CyaSSLv23_server_method

CyaSSL_CTX_new






CyaTLSv1_1_client_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_1_client_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_1_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_client_method

CyaTLSv1_client_method

CyaTLSv1_2_client_method

CyaDTLSv1_client_method

CyaSSLv23_client_method

CyaSSL_CTX_new






CyaTLSv1_1_server_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_1_server_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_1_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_server_method

CyaTLSv1_server_method

CyaTLSv1_2_server_method

CyaDTLSv1_server_method

CyaSSLv23_server_method

CyaSSL_CTX_new






CyaTLSv1_2_client_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_2_client_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_2_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_client_method

CyaTLSv1_client_method

CyaTLSv1_1_client_method

CyaDTLSv1_client_method

CyaSSLv23_client_method

CyaSSL_CTX_new






CyaTLSv1_2_server_method


Synopsis:

CYASSL_METHOD *CyaTLSv1_2_server_method(void);


Description:

The CyaTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaTLSv1_2_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_server_method

CyaTLSv1_server_method

CyaTLSv1_1_server_method

CyaDTLSv1_server_method

CyaSSLv23_server_method

CyaSSL_CTX_new






CyaDTLSv1_client_method


Synopsis:

CYASSL_METHOD *CyaDTLSv1_client_method(void);


Description:

The CyaDTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


This function is only available when CyaSSL has been compiled with DTLS support (--enable-dtls, or by defining CYASSL_DTLS).


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaDTLSv1_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_client_method

CyaTLSv1_client_method

CyaTLSv1_1_client_method

CyaTLSv1_2_client_method

CyaSSLv23_client_method

CyaSSL_CTX_new






CyaDTLSv1_server_method


Synopsis:

#include <cyassl/ssl.h>


CYASSL_METHOD *CyaDTLSv1_server_method(void);


Description:

The CyaDTLSv1_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 CYASSL_METHOD structure to be used when creating the SSL/TLS context with CyaSSL_CTX_new().


This function is only available when CyaSSL has been compiled with DTLS support (--enable-dtls, or by defining CYASSL_DTLS).


Return Values:

If successful, the call will return a pointer to the newly created CYASSL_METHOD structure.  


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


Example:


CYASSL_METHOD* method;

CYASSL_CTX* ctx;


method = CyaDTLSv1_server_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

...


See Also:

CyaSSLv3_server_method

CyaTLSv1_server_method

CyaTLSv1_1_server_method

CyaTLSv1_2_server_method

CyaSSLv23_server_method

CyaSSL_CTX_new






CyaSSL_new


Synopsis:

#include <cyassl/ssl.h>


CYASSL* CyaSSL_new(CYASSL_CTX* ctx);


Description:

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


Return Values:

If successful the call will return a pointer to the newly-created CYASSL structure.  Upon failure, NULL will be returned.


Parameters:


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


Example:


CYASSL*     ssl = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);

if (ctx == NULL) {

// context creation failed

}


ssl = CyaSSL_new(ctx);

if (ssl == NULL) {

// SSL object creation failed

}


See Also:

CyaSSL_CTX_new






CyaSSL_free


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_free(CYASSL* ssl);


Description:

This function frees an allocated CYASSL object.


Return Values:

No return values are used for this function.


Parameters:


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


Example:


CYASSL* ssl = 0;

...

CyaSSL_free(ssl);


See Also:

CyaSSL_CTX_new

CyaSSL_new

CyaSSL_CTX_free






CyaSSL_CTX_new


Synopsis:

CYASSL_CTX* CyaSSL_CTX_new(CYASSL_METHOD* method);


Description:

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


Return Values:

If successful the call will return a pointer to the newly-created CYASSL_CTX.  Upon failure, NULL will be returned.


Parameters:


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


Example:


CYASSL_CTX*    ctx    = 0;

CYASSL_METHOD* method = 0;


method = CyaSSLv3_client_method();

if (method == NULL) {

// unable to get method

}


ctx = CyaSSL_CTX_new(method);

if (ctx == NULL) {

// context creation failed

}


See Also:

CyaSSL_new






CyaSSL_CTX_free


Synopsis:

void CyaSSL_CTX_free(CYASSL_CTX* ctx);


Description:

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


Return Values:

No return values are used for this function.


Parameters:


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


Example:


CYASSL_CTX* ctx = 0;

...

CyaSSL_CTX_free(ctx);


See Also:

CyaSSL_CTX_new

CyaSSL_new

CyaSSL_free







CyaSSL_SetVersion


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_SetVersion(CYASSL* ssl, int version);


Description:

This function sets the SSL/TLS protocol version for the specified SSL session (CYASSL 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 (CyaSSL_CTX_new()) method type.


Return Values:

If successful the call will return SSL_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 CYASSL structure, created using CyaSSL_new().


version - SSL/TLS protocol version.  Possible values include CYASSL_SSLV3, CYASSL_TLSV1, CYASSL_TLSV1_1, CYASSL_TLSV1_2.


Example:


int ret = 0;

CYASSL* ssl;

...


ret = CyaSSL_SetVersion(ssl, CYASSL_TLSV1);

if (ret != SSL_SUCCESS) {

// failed to set SSL session protocol version
}


See Also:

CyaSSL_CTX_new






CyaSSL_check_domain_name


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_check_domain_name(CYASSL* ssl, const char* dn);


Description:

CyaSSL by default checks the peer certificate for a valid date range and a verified signature.  Calling this function before CyaSSL_connect() or CyaSSL_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.


Return Values:

If successful the call will return SSL_SUCCESS.


SSL_FAILURE will be returned if a memory error was encountered.


Parameters:


ssl - a pointer to a CYASSL structure, created using CyaSSL_new().


dn - domain name to check against the peer certificate when received.


Example:


int ret = 0;

CYASSL* ssl;

char* domain = (char*) “www.yassl.com”;

...


ret = CyaSSL_check_domain_name(ssl, domain);

if (ret != SSL_SUCCESS) {

// failed to enable domain name check
}


See Also:

NA






CyaSSL_set_cipher_list


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_set_cipher_list(CYASSL* ssl, const char* list);


Description:

This function sets cipher suite list for a given CYASSL object (SSL session).  The ciphers in the list should be sorted in order of preference from highest to lowest.  Each call to CyaSSL_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:


RC4-SHA

RC4-MD5

DES-CBC3-SHA

AES128-SHA

AES256-SHA

NULL-SHA

NULL-SHA256

DHE-RSA-AES128-SHA

DHE-RSA-AES256-SHA

PSK-AES128-CBC-SHA256

PSK-AES128-CBC-SHA

PSK-AES256-CBC-SHA

PSK-NULL-SHA256

PSK-NULL-SHA

HC128-MD5

HC128-SHA

RABBIT-SHA

NTRU-RC4-SHA

NTRU-DES-CBC3-SHA

NTRU-AES128-SHA

NTRU-AES256-SHA

ECDHE-RSA-AES128-SHA

ECDHE-RSA-AES256-SHA

ECDHE-ECDSA-AES128-SHA

ECDHE-ECDSA-AES256-SHA

ECDHE-RSA-RC4-SHA

ECDHE-RSA-DES-CBC3-SHA

ECDHE-ECDSA-RC4-SHA

ECDHE-ECDSA-DES-CBC3-SHA

AES128-SHA256

AES256-SHA256

DHE-RSA-AES128-SHA256

DHE-RSA-AES256-SHA256

ECDH-RSA-AES128-SHA

ECDH-RSA-AES256-SHA

ECDH-ECDSA-AES128-SHA

ECDH-ECDSA-AES256-SHA

ECDH-RSA-RC4-SHA

ECDH-RSA-DES-CBC3-SHA

ECDH-ECDSA-RC4-SHA

ECDH-ECDSA-DES-CBC3-SHA

AES128-GCM-SHA256

AES256-GCM-SHA384

DHE-RSA-AES128-GCM-SHA256

DHE-RSA-AES256-GCM-SHA384

ECDHE-RSA-AES128-GCM-SHA256

ECDHE-RSA-AES256-GCM-SHA384

ECDHE-ECDSA-AES128-GCM-SHA256

ECDHE-ECDSA-AES256-GCM-SHA384

ECDH-RSA-AES128-GCM-SHA256

ECDH-RSA-AES256-GCM-SHA384

ECDH-ECDSA-AES128-GCM-SHA256

ECDH-ECDSA-AES256-GCM-SHA384


Return Values:


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


Parameters:


ssl - pointer to the SSL session, created with CyaSSL_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;

CYASSL* ssl = 0;

...

ret = CyaSSL_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:

CyaSSL_CTX_set_cipher_list

CyaSSL_new






CyaSSL_CTX_set_cipher_list


Synopsis:

int  CyaSSL_CTX_set_cipher_list(CYASSL_CTX* ctx, const char* list);


Description:

This function sets cipher suite list for a given CYASSL_CTX.  This cipher suite list becomes the default list for any new SSL sessions (CYASSL) created using this context.  The ciphers in the list should be sorted in order of preference from highest to lowest.  Each call to CyaSSL_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:


RC4-SHA

RC4-MD5

DES-CBC3-SHA

AES128-SHA

AES256-SHA

NULL-SHA

NULL-SHA256

DHE-RSA-AES128-SHA

DHE-RSA-AES256-SHA

PSK-AES128-CBC-SHA256

PSK-AES128-CBC-SHA

PSK-AES256-CBC-SHA

PSK-NULL-SHA256

PSK-NULL-SHA

HC128-MD5

HC128-SHA

RABBIT-SHA

NTRU-RC4-SHA

NTRU-DES-CBC3-SHA

NTRU-AES128-SHA

NTRU-AES256-SHA

ECDHE-RSA-AES128-SHA

ECDHE-RSA-AES256-SHA

ECDHE-ECDSA-AES128-SHA

ECDHE-ECDSA-AES256-SHA

ECDHE-RSA-RC4-SHA

ECDHE-RSA-DES-CBC3-SHA

ECDHE-ECDSA-RC4-SHA

ECDHE-ECDSA-DES-CBC3-SHA

AES128-SHA256

AES256-SHA256

DHE-RSA-AES128-SHA256

DHE-RSA-AES256-SHA256

ECDH-RSA-AES128-SHA

ECDH-RSA-AES256-SHA

ECDH-ECDSA-AES128-SHA

ECDH-ECDSA-AES256-SHA

ECDH-RSA-RC4-SHA

ECDH-RSA-DES-CBC3-SHA

ECDH-ECDSA-RC4-SHA

ECDH-ECDSA-DES-CBC3-SHA

AES128-GCM-SHA256

AES256-GCM-SHA384

DHE-RSA-AES128-GCM-SHA256

DHE-RSA-AES256-GCM-SHA384

ECDHE-RSA-AES128-GCM-SHA256

ECDHE-RSA-AES256-GCM-SHA384

ECDHE-ECDSA-AES128-GCM-SHA256

ECDHE-ECDSA-AES256-GCM-SHA384

ECDH-RSA-AES128-GCM-SHA256

ECDH-RSA-AES256-GCM-SHA384

ECDH-ECDSA-AES128-GCM-SHA256

ECDH-ECDSA-AES256-GCM-SHA384


Return Values:


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


Parameters:


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


list - null-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL context.


Example:


CYASSL_CTX* ctx = 0;

...

ret = CyaSSL_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:

CyaSSL_set_cipher_list

CyaSSL_CTX_new






CyaSSL_set_compression


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_set_compression(CYASSL* ssl);


Description:

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.


Return Values:

If successful the call will return 0.


NOT_COMPILED_IN will be returned if compression support wasn’t built into the library.


Parameters:


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


Example:


int ret = 0;

CYASSL* ssl = 0;

...

ret = CyaSSL_set_compression(ssl);

if (ret == 0) {

// successfully enabled compression for SSL session

}


See Also:

NA






CyaSSL_set_fd


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_set_fd(CYASSL* ssl, int fd);


Description:

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


Return Values:

If successful the call will return SSL_SUCCESS, otherwise, SSL_FAILURE will be returned.


Parameters:


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


fd - file descriptor to use with SSL/TLS connection.


Example:


int sockfd;

CYASSL* ssl = 0;

...


ret = CyaSSL_set_fd(ssl, sockfd);

if (ret != SSL_SUCCESS) {

// failed to set SSL file descriptor

}


See Also:

CyaSSL_SetIOSend

CyaSSL_SetIORecv

CyaSSL_SetIOReadCtx

CyaSSL_SetIOWriteCtx






CyaSSL_set_group_messages


Synopsis:

int CyaSSL_set_group_messages(CYASSL* ssl);


Description:

This function turns on grouping of handshake messages where possible.


Return Values:


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


Example:


CYASSL* ssl = 0;

...

ret = CyaSSL_set_group_messages(ssl);

if (ret != SSL_SUCCESS) {

// failed to set handshake message grouping

}


See Also:

CyaSSL_CTX_set_group_messages

CyaSSL_new






CyaSSL_CTX_set_group_messages


Synopsis:

int CyaSSL_CTX_set_group_messages(CYASSL_CTX* ctx);


Description:

This function turns on grouping of handshake messages where possible.


Return Values:


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


Example:


CYASSL_CTX* ctx = 0;

...

ret = CyaSSL_CTX_set_group_messages(ctx);

if (ret != SSL_SUCCESS) {

// failed to set handshake message grouping

}


See Also:

CyaSSL_set_group_messages

CyaSSL_CTX_new






CyaSSL_set_session


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_set_session(CYASSL* ssl, CYASSL_SESSION* session);


Description:

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 CyaSSL_shutdown() with your session object, an application should save the session ID from the object with a call to CyaSSL_get_session(), which returns a pointer to the session.  Later, the application should create a new CYASSL object and assign the saved session with CyaSSL_set_session().  At this point, the application may call CyaSSL_connect() and CyaSSL will try to resume the session.  The CyaSSL server code allows session resumption by default.


Return Values:


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


session - pointer to the CYASSL_SESSION used to set the session for ssl.


Example:


int ret = 0;

CYASSL* ssl = 0;

CYASSL_SESSION* session;

...


ret = CyaSSL_get_session(ssl, session);

if (ret != SSL_SUCCESS) {

// failed to set the SSL session

}

...


See Also:

CyaSSL_get_session






CyaSSL_CTX_set_session_cache_mode


Synopsis:

long CyaSSL_CTX_set_session_cache_mode(CYASSL_CTX* ctx, long mode);


Description:

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

  1. - disable session caching.  Session caching is turned on by default.


SSL_SESS_CACHE_NO_AUTO_CLEAR

  1. - Disable auto-flushing of the session cache.  Auto-flushing is turned on by default.


Return Values:


SSL_SUCCESS will be returned upon success.


Parameters:


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


mode - modifier used to change behavior of the session cache.


Example:


CYASSL_CTX* ctx = 0;

...

ret = CyaSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);

if (ret != SSL_SUCCESS) {

// failed to turn SSL session caching off

}


See Also:

CyaSSL_flush_sessions

CyaSSL_get_session

CyaSSL_set_session

CyaSSL_get_sessionID

CyaSSL_CTX_set_timeout






CyaSSL_set_timeout


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_set_timeout(CYASSL* ssl, unsigned int to);


Description:

This function sets the SSL session timeout value in seconds.


Return Values:


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


to - value, in seconds, used to set the SSL session timeout.


Example:


int ret = 0;

CYASSL* ssl = 0;

...


ret = CyaSSL_set_timeout(ssl, 500);

if (ret != SSL_SUCCESS) {

// failed to set session timeout value

}

...


See Also:

CyaSSL_get_session

CyaSSL_set_session






CyaSSL_CTX_set_timeout


Synopsis:

int CyaSSL_CTX_set_timeout(CYASSL_CTX* ctx, unsigned int to);


Description:

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


Return Values:


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


to - session timeout value in seconds


Example:


CYASSL_CTX*    ctx    = 0;

...

ret = CyaSSL_CTX_set_timeout(ctx, 500);

if (ret != SSL_SUCCESS) {

// failed to set session timeout value

}


See Also:

CyaSSL_flush_sessions

CyaSSL_get_session

CyaSSL_set_session

CyaSSL_get_sessionID

CyaSSL_CTX_set_session_cache_mode






CyaSSL_set_using_nonblock


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_set_using_nonblock(CYASSL* ssl, int nonblock);


Description:

This function informs the CYASSL object that the underlying I/O is non-blocking.


After an application creates a CYASSL object, if it will be used with a non-blocking socket, call CyaSSL_set_using_nonblock() on it. This lets the CYASSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.


Return Values:


This function does not have a return value.


Parameters:


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


nonblock - value used to set non-blocking flag on CYASSL object.  Use 1 to specify non-blocking, otherwise 0.


Example:


CYASSL* ssl = 0;

...


CyaSSL_set_using_nonblock(ssl, 1);


See Also:

CyaSSL_get_using_nonblock

CyaSSL_dtls_got_timeout

CyaSSL_dtls_get_current_timeout






CyaSSL_set_verify


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_set_verify(CYASSL* ssl, int mode, VerifyCallback verify_callback);


typedef int (*VerifyCallback)(int, CYASSL_X509_STORE_CTX*);


Description:

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


  1. Client mode:  the client will not verify the certificate received from the server and the handshake will continue as normal.


  2. Server mode:  the server will not send a certificate request to the client.  As such, client verification will not be enabled.


SSL_VERIFY_PEER


  1. Client mode:  the client will verify the certificate received from the server during the handshake.  This is turned on by default in CyaSSL, therefore, using this option has no effect.


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


  1. Client mode:  no effect when used on the client side.


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


Return Values:


This function has no return value.


Parameters:


ssl - pointer to the SSL session, created with CyaSSL_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:


CYASSL* ssl = 0;

...


CyaSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);


See Also:

CyaSSL_CTX_set_verify






CyaSSL_CTX_set_verify


Synopsis:

void CyaSSL_CTX_set_verify(CYASSL_CTX* ctx, int mode,

                                                      VerifyCallback verify_callback);


typedef int (*VerifyCallback)(int, CYASSL_X509_STORE_CTX*);


Description:

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


  1. Client mode:  the client will not verify the certificate received from the server and the handshake will continue as normal.


  2. Server mode:  the server will not send a certificate request to the client.  As such, client verification will not be enabled.


SSL_VERIFY_PEER


  1. Client mode:  the client will verify the certificate received from the server during the handshake.  This is turned on by default in CyaSSL, therefore, using this option has no effect.


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


  1. Client mode:  no effect when used on the client side.


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


Return Values:


This function has no return value.


Parameters:


ctx - pointer to the SSL context, created with CyaSSL_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:


CYASSL_CTX*    ctx    = 0;

...

CyaSSL_CTX_set_verify(ctx, SSL_VERIFY_PEER |

                     SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);


See Also:

CyaSSL_set_verify





 

Questions? +1 (425) 245-8247