dtls: GnuTLS API Reference Manual

## dtls dtls |

## Functions

void | gnutls_dtls_set_timeouts ()
unsigned int | gnutls_dtls_get_mtu ()
unsigned int | gnutls_dtls_get_data_mtu ()
void | gnutls_dtls_set_mtu ()
int | gnutls_dtls_set_data_mtu ()
unsigned int | gnutls_dtls_get_timeout ()
int | gnutls_dtls_cookie_send ()
int | gnutls_dtls_cookie_verify ()
void | gnutls_dtls_prestate_set ()
unsigned int | gnutls_record_get_discarded ()

## Types and Values

#define | GNUTLS_COOKIE_KEY_SIZE
| gnutls_dtls_prestate_st

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