dtls: GnuTLS API Reference Manual

## dtls dtls |

## Functions

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

## Types and Values

#define | GNUTLS_COOKIE_KEY_SIZE

## Description

## Functions

### 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_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 structure. |

#### Returns

the maximum allowed transfer unit.

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

#### Returns

the set maximum transfer unit.

Since: 3.0

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

#### Returns

the remaining time in milliseconds.

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_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 structure. |
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_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 Ethenet 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 structure. |
mtu | The maximum transfer unit of the transport |

Since: 3.0

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

To disable retransmissions set a `retrans_timeout` larger than the `total_timeout` .

#### Parameters

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

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

#### Returns

The number of discarded packets.

Since: 3.0

## Types and Values

### GNUTLS_COOKIE_KEY_SIZE

    #define GNUTLS_COOKIE_KEY_SIZE 16