wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.13  TLS Extensions


The functions in this section are specific to supported TLS extensions.






CyaSSL_CTX_UseSNI


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CTX_UseSNI(CYASSL_CTX* ctx, unsigned char type, const void* data, unsigned short size);


Description:

This function enables the use of Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the SNI extension will be sent on ClientHello by CyaSSL clients and CyaSSL servers will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ctx is NULL

    * data is NULL

    * type is a unknown value. (see below)


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


type - indicates witch type of server name is been passed in data. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


data - pointer to the server name data.


size - size of the server name data.


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ret = CyaSSL_CTX_UseSNI(ctx, CYASSL_SNI_HOST_NAME, "www.yassl.com", strlen("www.yassl.com"));


if (ret != 0) {

    // sni usage failed

}


See Also:

CyaSSL_CTX_new

CyaSSL_UseSNI






CyaSSL_UseSNI


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_UseSNI(CYASSL* ssl, unsigned char type, const void* data, unsigned short size);


Description:

This function enables the use of Server Name Indication in the SSL object passed in the 'ssl' parameter. It means that the SNI extension will be sent on ClientHello by CyaSSL client and CyaSSL server will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ssl is NULL

    * data is NULL

    * type is a unknown value. (see below)


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


type - indicates witch type of server name is been passed in data. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


data - pointer to the server name data.


size - size of the server name data.


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseSNI(ssl, CYASSL_SNI_HOST_NAME, "www.yassl.com", strlen("www.yassl.com"));


if (ret != 0) {

    // sni usage failed

}


See Also:

CyaSSL_new

CyaSSL_CTX_UseSNI






CyaSSL_CTX_SNI_SetOptions


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_CTX_SNI_SetOptions(CYASSL_CTX* ctx, unsigned char type, unsigned char options);


Description:

This function is called on the server side to configure the behavior of the SSL sessions using Server Name Indication for SSL objects created from the SSL context passed in the 'ctx' parameter. The options are explained below.


Return Values:

This function does not have a return value.


Parameters:


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


type - indicates which type of server name is been passed in data. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


options - a bitwise semaphore with the chosen options. The available options are:

    enum {

        CYASSL_SNI_CONTINUE_ON_MISMATCH = 0x01,

        CYASSL_SNI_ANSWER_ON_MISMATCH   = 0x02

    };

   

Normally the server will abort the handshake by sending a fatal-level unrecognized_name(112) alert if the host name provided by the client mismatch with the servers.

   

CYASSL_SNI_CONTINUE_ON_MISMATCH - With this option set, the server will not send a SNI response instead of aborting the session.

   

CYASSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server will send a SNI response as if the host names match instead of aborting the session.


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ret = CyaSSL_CTX_UseSNI(ctx, 0, "www.yassl.com", strlen("www.yassl.com"));


if (ret != 0) {

    // sni usage failed

}


CyaSSL_CTX_SNI_SetOptions(ctx, CYASSL_SNI_HOST_NAME, CYASSL_SNI_CONTINUE_ON_MISMATCH);


See Also:

CyaSSL_CTX_new

CyaSSL_CTX_UseSNI

CyaSSL_SNI_SetOptions






CyaSSL_SNI_SetOptions


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_SNI_SetOptions(CYASSL_CTX* ctx, unsigned char type, unsigned char options);


Description:

This function is called on the server side to configure the behavior of the SSL session using Server Name Indication in the SSL object passed in the 'ssl' parameter. The options are explained below.


Return Values:

This function does not have a return value.


Parameters:


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


type - indicates which type of server name is been passed in data. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


options - a bitwise semaphore with the chosen options. The available options are:

    enum {

        CYASSL_SNI_CONTINUE_ON_MISMATCH = 0x01,

        CYASSL_SNI_ANSWER_ON_MISMATCH   = 0x02

    };

   

Normally the server will abort the handshake by sending a fatal-level unrecognized_name(112) alert if the host name provided by the client mismatch with the servers.

   

CYASSL_SNI_CONTINUE_ON_MISMATCH - With this option set, the server will not send a SNI response instead of aborting the session.

   

CYASSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server will send a SNI response as if the host names match instead of aborting the session.


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));


if (ret != 0) {

    // sni usage failed

}


CyaSSL_SNI_SetOptions(ssl, CYASSL_SNI_HOST_NAME, CYASSL_SNI_CONTINUE_ON_MISMATCH);


See Also:

CyaSSL_new

CyaSSL_UseSNI

CyaSSL_CTX_SNI_SetOptions





CyaSSL_SNI_GetRequest


Synopsis:

#include <cyassl/ssl.h>


unsigned short CyaSSL_SNI_GetRequest(CYASSL *ssl, unsigned char type, void** data);


Description:

This function is called on the server side to retrieve the Server Name Indication provided by the client in a SSL session.


Return Values:

The size of the provided SNI data.


Parameters:


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


type - indicates which type of server name is been retrieved in data. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


data - pointer to the data provided by the client.


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));


if (ret != 0) {

    // sni usage failed

}


if (CyaSSL_accept(ssl) == SSL_SUCCESS) {

    void *data = NULL;

    unsigned short size = CyaSSL_SNI_GetRequest(ssl, 0, &data);

}


See Also:

CyaSSL_UseSNI

CyaSSL_CTX_UseSNI





CyaSSL_SNI_GetFromBuffer


Synopsis:

#include <cyassl/ssl.h>


CYASSL_API int CyaSSL_SNI_GetFromBuffer(const unsigned char* buffer, unsigned int bufferSz, unsigned char type, unsigned char* sni, unsigned int* inOutSz);


Description:

This function is called on the server side to retrieve the Server Name Indication provided by the client from the Client Hello message sent by the client to start a session. It does not requires context or session setup to retrieve the SNI.


Return Values:

If successful the call will return SSL_SUCCESS;

If there is no SNI extension in the client hello, the call will return 0.


BAD_FUNC_ARG is the error that will be returned in one of this cases:

    * buffer is NULL

    * bufferSz <= 0

    * sni is NULL

    * inOutSz is NULL or <= 0


BUFFER_ERROR is the error returned when there is a malformed Client Hello message.


INCOMPLETE_DATA is the error returned when there is not enough data to complete the extraction.


Parameters:


buffer - pointer to the data provided by the client (Client Hello).


bufferSz - size of the Client Hello message.


type - indicates which type of server name is been retrieved from the buffer. The known types are:

    enum {

        CYASSL_SNI_HOST_NAME = 0

    };


sni - pointer to where the output is going to be stored.


inOutSz - pointer to the output size, this value will be updated to MIN("SNI's length", inOutSz).


Example:


unsigned char buffer[1024] = {0};

unsigned char result[32]   = {0};

int           length       = 32;


// read Client Hello to buffer...


ret = CyaSSL_SNI_GetFromBuffer(buffer, sizeof(buffer), 0, result, &length));


if (ret != SSL_SUCCESS) {

    // sni retrieve failed

}


See Also:

CyaSSL_UseSNI

CyaSSL_CTX_UseSNI

CyaSSL_SNI_GetRequest






CyaSSL_CTX_UseMaxFragment


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CTX_UseMaxFragment(CYASSL_CTX* ctx, unsigned char mfl);


Description:

This function is called on the client side to enable the use of Maximum Fragment Length for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by CyaSSL clients.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ctx is NULL

    * mfl is out of range.


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


mfl - indicates witch is the Maximum Fragment Length requested for the session. The available options are:

    enum {

        CYASSL_MFL_2_9  = 1, /*  512 bytes */

        CYASSL_MFL_2_10 = 2, /* 1024 bytes */

        CYASSL_MFL_2_11 = 3, /* 2048 bytes */

        CYASSL_MFL_2_12 = 4, /* 4096 bytes */

        CYASSL_MFL_2_13 = 5  /* 8192 bytes *//* CyaSSL ONLY!!! */

    };


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ret = CyaSSL_CTX_UseMaxFragment(ctx, CYASSL_MFL_2_11);


if (ret != 0) {

    // max fragment usage failed

}


See Also:

CyaSSL_CTX_new

CyaSSL_UseMaxFragment






CyaSSL_UseMaxFragment


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_UseMaxFragment(CYASSL* ssl, unsigned char mfl);


Description:

This function is called on the client side to enable the use of Maximum Fragment Length in the SSL object passed in the 'ssl' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by CyaSSL clients.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ssl is NULL

    * mfl is out of range.


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


mfl - indicates witch is the Maximum Fragment Length requested for the session. The available options are:

    enum {

        CYASSL_MFL_2_9  = 1, /*  512 bytes */

        CYASSL_MFL_2_10 = 2, /* 1024 bytes */

        CYASSL_MFL_2_11 = 3, /* 2048 bytes */

        CYASSL_MFL_2_12 = 4, /* 4096 bytes */

        CYASSL_MFL_2_13 = 5  /* 8192 bytes *//* CyaSSL ONLY!!! */

    };


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseMaxFragment(ssl, CYASSL_MFL_2_11);


if (ret != 0) {

    // max fragment usage failed

}


See Also:

CyaSSL_new

CyaSSL_CTX_UseMaxFragment






CyaSSL_CTX_UseTruncatedHMAC


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CTX_UseTruncatedHMAC(CYASSL_CTX* ctx);


Description:

This function is called on the client side to enable the use of Truncated HMAC for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by CyaSSL clients.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ctx is NULL


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ret = CyaSSL_CTX_UseTruncatedHMAC(ctx);


if (ret != 0) {

    // truncated HMAC usage failed

}


See Also:

CyaSSL_CTX_new

CyaSSL_UseMaxFragment






CyaSSL_UseTruncatedHMAC


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_UseTruncatedHMAC(CYASSL* ssl);


Description:

This function is called on the client side to enable the use of Truncated HMAC in the SSL object passed in the 'ssl' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by CyaSSL clients.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ssl is NULL


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseTruncatedHMAC(ssl);


if (ret != 0) {

    // truncated HMAC usage failed

}


See Also:

CyaSSL_new

CyaSSL_CTX_UseMaxFragment






CyaSSL_CTX_UseSupportedCurve


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CTX_UseSupportedCurve(CYASSL_CTX* ctx, unsigned short name);


Description:

This function is called on the client side to enable the use of Supported Elliptic Curves Extension for SSL objects created from the SSL context passed in the 'ctx' parameter. It means that the supported curves enabled will be sent on ClientHello by CyaSSL clients. This function can be called more than one time to enable multiple curves.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ctx is NULL

    * name is a unknown value. (see below)


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


name - indicates which curve will be supported for the session. The available options are:

    enum {

            CYASSL_ECC_SECP160R1 = 0x10,

            CYASSL_ECC_SECP192R1 = 0x13,

            CYASSL_ECC_SECP224R1 = 0x15,

            CYASSL_ECC_SECP256R1 = 0x17,

            CYASSL_ECC_SECP384R1 = 0x18,

            CYASSL_ECC_SECP521R1 = 0x19

    };


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ret = CyaSSL_CTX_UseSupportedCurve(ctx, CYASSL_ECC_SECP256R1);


if (ret != 0) {

    // Elliptic Curve Extension usage failed

}


See Also:

CyaSSL_CTX_new

CyaSSL_UseSupportedCurve






CyaSSL_UseSupportedCurve


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_UseSupportedCurve(CYASSL* ssl, unsigned short name);


Description:

This function is called on the client side to enable the use of Supported Elliptic Curves Extension in the SSL object passed in the 'ssl' parameter. It means that the supported curves enabled will be sent on ClientHello by CyaSSL clients. This function can be called more than one time to enable multiple curves.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned in one of these cases:

    * ssl is NULL

    * name is a unknown value. (see below)


MEMORY_E is the error returned when there is not enough memory.


Parameters:


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


name - indicates witch curve will be supported for the session. The available options are:

    enum {

            CYASSL_ECC_SECP160R1 = 0x10,

            CYASSL_ECC_SECP192R1 = 0x13,

            CYASSL_ECC_SECP224R1 = 0x15,

            CYASSL_ECC_SECP256R1 = 0x17,

            CYASSL_ECC_SECP384R1 = 0x18,

            CYASSL_ECC_SECP521R1 = 0x19

    };


Example:


int ret = 0;

CYASSL_CTX* ctx = 0;

CYASSL* ssl = 0;


ctx = CyaSSL_CTX_new(method);


if (ctx == NULL) {

    // context creation failed

}


ssl = CyaSSL_new(ctx);


if (ssl == NULL) {

    // ssl creation failed

}


ret = CyaSSL_UseSupportedCurve(ssl, CYASSL_ECC_SECP256R1);


if (ret != 0) {

    // Elliptic Curve Extension usage failed

}


See Also:

CyaSSL_new

CyaSSL_CTX_UseSupportedCurve





 

Questions? +1 (425) 245-8247