info gnutls

C.2 Datagram TLS API

The prototypes for the following functions lie in ‘gnutls/dtls.h’.

gnutls_dtls_cookie_send

Function: 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)

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

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.

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

Since: 3.0.0

gnutls_dtls_cookie_verify

Function: 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)

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.

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() ;

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

Since: 3.0.0

gnutls_dtls_get_data_mtu

Function: unsigned int gnutls_dtls_get_data_mtu (gnutls_session_t session)

session: is a gnutls_session_t structure.

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

Returns: the maximum allowed transfer unit.

Since: 3.0.0

gnutls_dtls_get_mtu

Function: unsigned int gnutls_dtls_get_mtu (gnutls_session_t session)

session: is a gnutls_session_t structure.

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.

Returns: the set maximum transfer unit.

Since: 3.0.0

gnutls_dtls_prestate_set

Function: void gnutls_dtls_prestate_set (gnutls_session_t session, gnutls_dtls_prestate_st* prestate)

session: a new session

prestate: contains the client’s prestate

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

Since: 3.0.0

gnutls_dtls_set_mtu

Function: void gnutls_dtls_set_mtu (gnutls_session_t session, unsigned int mtu)

session: is a gnutls_session_t structure.

mtu: The maximum transfer unit of the interface

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

Since: 3.0.0

gnutls_dtls_set_timeouts

Function: void gnutls_dtls_set_timeouts (gnutls_session_t session, unsigned int retrans_timeout, unsigned int total_timeout)

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.

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 .

Since: 3.0.0

gnutls_record_get_discarded

Function: unsigned int gnutls_record_get_discarded (gnutls_session_t session)

session: is a gnutls_session_t structure.

Returns the number of discarded packets in a DTLS connection.

Returns: The number of discarded packets.

Since: 3.0.0

This document was generated on January 21, 2012 using texi2html 5.0.