dtls

dtls

Synopsis

#define             GNUTLS_COOKIE_KEY_SIZE
void                gnutls_dtls_set_timeouts            (gnutls_session_t session,
                                                         unsigned int retrans_timeout,
                                                         unsigned int total_timeout);
unsigned int        gnutls_dtls_get_mtu                 (gnutls_session_t session);
unsigned int        gnutls_dtls_get_data_mtu            (gnutls_session_t session);
void                gnutls_dtls_set_mtu                 (gnutls_session_t session,
                                                         unsigned int mtu);
int                 gnutls_dtls_cookie_send             (gnutls_datum_t *key,
                                                         void *client_data,
                                                         size_t client_data_size,
                                                         gnutls_dtls_prestate_st *prestate,
                                                         gnutls_transport_ptr_t ptr,
                                                         gnutls_push_func push_func);
int                 gnutls_dtls_cookie_verify           (gnutls_datum_t *key,
                                                         void *client_data,
                                                         size_t client_data_size,
                                                         void *_msg,
                                                         size_t msg_size,
                                                         gnutls_dtls_prestate_st *prestate);
void                gnutls_dtls_prestate_set            (gnutls_session_t session,
                                                         gnutls_dtls_prestate_st *prestate);
unsigned int        gnutls_record_get_discarded         (gnutls_session_t session);

Description

Details

GNUTLS_COOKIE_KEY_SIZE

#define GNUTLS_COOKIE_KEY_SIZE 16


gnutls_dtls_set_timeouts ()

void                gnutls_dtls_set_timeouts            (gnutls_session_t session,
                                                         unsigned int retrans_timeout,
                                                         unsigned int total_timeout);

This function will set the timeouts required for the DTLS handshake protocol. The retransmission timeout is the time after which a message from the peer is not received, the previous messages will be retransmitted. The total timeout is the time after which the handshake will be aborted with GNUTLS_E_TIMEDOUT.

The DTLS protocol recommends the values of 1 sec and 60 seconds respectively.

If the retransmission timeout is zero then the handshake will operate in a non-blocking way, i.e., return GNUTLS_E_AGAIN.

session :

is a gnutls_session_t structure.

retrans_timeout :

The time at which a retransmission will occur in milliseconds

total_timeout :

The time at which the connection will be aborted, in milliseconds.

Since 3.0.0


gnutls_dtls_get_mtu ()

unsigned int        gnutls_dtls_get_mtu                 (gnutls_session_t session);

This function will return the MTU size as set with gnutls_dtls_set_mtu(). This is not the actual MTU of data you can transmit. Use gnutls_dtls_get_data_mtu() for that reason.

session :

is a gnutls_session_t structure.

Returns :

the set maximum transfer unit.

Since 3.0.0


gnutls_dtls_get_data_mtu ()

unsigned int        gnutls_dtls_get_data_mtu            (gnutls_session_t session);

This function will return the actual maximum transfer unit for application data. I.e. DTLS headers are subtracted from the actual MTU.

session :

is a gnutls_session_t structure.

Returns :

the maximum allowed transfer unit.

Since 3.0.0


gnutls_dtls_set_mtu ()

void                gnutls_dtls_set_mtu                 (gnutls_session_t session,
                                                         unsigned int mtu);

This function will set the maximum transfer unit of the interface that DTLS packets are expected to leave from.

session :

is a gnutls_session_t structure.

mtu :

The maximum transfer unit of the interface

Since 3.0.0


gnutls_dtls_cookie_send ()

int                 gnutls_dtls_cookie_send             (gnutls_datum_t *key,
                                                         void *client_data,
                                                         size_t client_data_size,
                                                         gnutls_dtls_prestate_st *prestate,
                                                         gnutls_transport_ptr_t ptr,
                                                         gnutls_push_func push_func);

This function can be used to prevent denial of service attacks to a DTLS server by requiring the client to reply using a cookie sent by this function. That way it can be ensured that a client we allocated resources for (i.e. gnutls_session_t) is the one that the original incoming packet was originated from.

key :

is a random key to be used at cookie generation

client_data :

contains data identifying the client (i.e. address)

client_data_size :

The size of client's data

prestate :

The previous cookie returned by gnutls_dtls_cookie_verify()

ptr :

A transport pointer to be used by push_func

push_func :

A function that will be used to reply

Returns :

the number of bytes sent, or a negative error code.

Since 3.0.0


gnutls_dtls_cookie_verify ()

int                 gnutls_dtls_cookie_verify           (gnutls_datum_t *key,
                                                         void *client_data,
                                                         size_t client_data_size,
                                                         void *_msg,
                                                         size_t msg_size,
                                                         gnutls_dtls_prestate_st *prestate);

This function will verify an incoming message for a valid cookie. If a valid cookie is returned then it should be associated with the session using gnutls_dtls_prestate_set();

key :

is a random key to be used at cookie generation

client_data :

contains data identifying the client (i.e. address)

client_data_size :

The size of client's data

_msg :

An incoming message that initiates a connection.

msg_size :

The size of the message.

prestate :

The cookie of this client.

Returns :

GNUTLS_E_SUCCESS (0) on success, or a negative error code.

Since 3.0.0


gnutls_dtls_prestate_set ()

void                gnutls_dtls_prestate_set            (gnutls_session_t session,
                                                         gnutls_dtls_prestate_st *prestate);

This function will associate the prestate acquired by the cookie authentication with the client, with the newly established session.

session :

a new session

prestate :

contains the client's prestate

Since 3.0.0


gnutls_record_get_discarded ()

unsigned int        gnutls_record_get_discarded         (gnutls_session_t session);

Returns the number of discarded packets in a DTLS connection.

session :

is a gnutls_session_t structure.

Returns :

The number of discarded packets.

Since 3.0.0