dtls

dtls

Functions

Types and Values

Description

Functions

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, and these are the default values.

To disable retransmissions set a retrans_timeout larger than the total_timeout .

Parameters

session

is a gnutls_session_t type.

 

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


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.

Parameters

session

is a gnutls_session_t type.

 

Returns

the set maximum transfer unit.

Since: 3.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 which is set using gnutls_dtls_set_mtu().

Parameters

session

is a gnutls_session_t type.

 

Returns

the maximum allowed transfer unit.

Since: 3.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 transport that DTLS packets are sent over. Note that this should exclude the IP (or IPv6) and UDP headers. So for DTLS over IPv6 on an Ethernet device with MTU 1500, the DTLS MTU set with this function would be 1500 - 40 (IPV6 header) - 8 (UDP header) = 1452.

Parameters

session

is a gnutls_session_t type.

 

mtu

The maximum transfer unit of the transport

 

Since: 3.0


gnutls_dtls_set_data_mtu ()

int
gnutls_dtls_set_data_mtu (gnutls_session_t session,
                          unsigned int mtu);

This function will set the maximum size of the *unencrypted* records which will be sent over a DTLS session. It is equivalent to calculating the DTLS packet overhead with the current encryption parameters, and calling gnutls_dtls_set_mtu() with that value. In particular, this means that you may need to call this function again after any negotiation or renegotiation, in order to ensure that the MTU is still sufficient to account for the new protocol overhead.

In most cases you only need to call gnutls_dtls_set_mtu() with the maximum MTU of your transport layer.

Parameters

session

is a gnutls_session_t type.

 

mtu

The maximum unencrypted transfer unit of the session

 

Returns

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

Since: 3.1


gnutls_dtls_get_timeout ()

unsigned int
gnutls_dtls_get_timeout (gnutls_session_t session);

This function will return the milliseconds remaining for a retransmission of the previously sent handshake message. This function is useful when DTLS is used in non-blocking mode, to estimate when to call gnutls_handshake() if no packets have been received.

Parameters

session

is a gnutls_session_t type.

 

Returns

the remaining time in milliseconds.

Since: 3.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.

This function must be called at the first incoming packet, prior to allocating any resources and must be succeeded by gnutls_dtls_cookie_verify().

Parameters

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


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 the received message for a valid cookie. If a valid cookie is returned then it should be associated with the session using gnutls_dtls_prestate_set();

This function must be called after gnutls_dtls_cookie_send().

Parameters

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


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.

This functions must be called after a successful gnutls_dtls_cookie_verify() and should be succeeded by the actual DTLS handshake using gnutls_handshake().

Parameters

session

a new session

 

prestate

contains the client's prestate

 

Since: 3.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.

Parameters

session

is a gnutls_session_t type.

 

Returns

The number of discarded packets.

Since: 3.0

Types and Values

GNUTLS_COOKIE_KEY_SIZE

#define GNUTLS_COOKIE_KEY_SIZE 16


gnutls_dtls_prestate_st

typedef struct {
	unsigned int record_seq;
	unsigned int hsk_read_seq;
	unsigned int hsk_write_seq;
} gnutls_dtls_prestate_st;

DTLS cookie prestate struct. This is usually never modified by the application, it is used to carry the cookie data between gnutls_dtls_cookie_send(), gnutls_dtls_cookie_verify() and gnutls_dtls_prestate_set().

Members

unsigned int record_seq;

record sequence number

 

unsigned int hsk_read_seq;

handshake read sequence number

 

unsigned int hsk_write_seq;

handshake write sequence number