doc/dtls-api.texi

   1
   2 @subheading gnutls_dtls_cookie_send
   3 @anchor{gnutls_dtls_cookie_send}
   4 @deftypefun {int} {gnutls_dtls_cookie_send} (gnutls_datum_t* @var{key}, void* @var{client_data}, size_t @var{client_data_size}, gnutls_dtls_prestate_st* @var{prestate}, gnutls_transport_ptr_t @var{ptr}, gnutls_push_func @var{push_func})
   5 @var{key}: is a random key to be used at cookie generation
   6
   7 @var{client_data}: contains data identifying the client (i.e. address)
   8
   9 @var{client_data_size}: The size of client's data
  10
  11 @var{prestate}: The previous cookie returned by @code{gnutls_dtls_cookie_verify()}
  12
  13 @var{ptr}: A transport pointer to be used by  @code{push_func}
  14
  15 @var{push_func}: A function that will be used to reply
  16
  17 This function can be used to prevent denial of service
  18 attacks to a DTLS server by requiring the client to
  19 reply using a cookie sent by this function. That way
  20 it can be ensured that a client we allocated resources
  21 for (i.e. @code{gnutls_session_t} ) is the one that the
  22 original incoming packet was originated from.
  23
  24 @strong{Returns:} the number of bytes sent, or a negative error code.
  25
  26 @strong{Since:} 3.0
  27 @end deftypefun
  28
  29 @subheading gnutls_dtls_cookie_verify
  30 @anchor{gnutls_dtls_cookie_verify}
  31 @deftypefun {int} {gnutls_dtls_cookie_verify} (gnutls_datum_t* @var{key}, void* @var{client_data}, size_t @var{client_data_size}, void* @var{_msg}, size_t @var{msg_size}, gnutls_dtls_prestate_st* @var{prestate})
  32 @var{key}: is a random key to be used at cookie generation
  33
  34 @var{client_data}: contains data identifying the client (i.e. address)
  35
  36 @var{client_data_size}: The size of client's data
  37
  38 @var{_msg}: An incoming message that initiates a connection.
  39
  40 @var{msg_size}: The size of the message.
  41
  42 @var{prestate}: The cookie of this client.
  43
  44 This function will verify an incoming message for
  45 a valid cookie. If a valid cookie is returned then
  46 it should be associated with the session using
  47 @code{gnutls_dtls_prestate_set()} ;
  48
  49 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success, or a negative error code.
  50
  51 @strong{Since:} 3.0
  52 @end deftypefun
  53
  54 @subheading gnutls_dtls_get_data_mtu
  55 @anchor{gnutls_dtls_get_data_mtu}
  56 @deftypefun {unsigned int} {gnutls_dtls_get_data_mtu} (gnutls_session_t @var{session})
  57 @var{session}: is a @code{gnutls_session_t}  structure.
  58
  59 This function will return the actual maximum transfer unit for
  60 application data. I.e. DTLS headers are subtracted from the
  61 actual MTU.
  62
  63 @strong{Returns:} the maximum allowed transfer unit.
  64
  65 @strong{Since:} 3.0
  66 @end deftypefun
  67
  68 @subheading gnutls_dtls_get_mtu
  69 @anchor{gnutls_dtls_get_mtu}
  70 @deftypefun {unsigned int} {gnutls_dtls_get_mtu} (gnutls_session_t @var{session})
  71 @var{session}: is a @code{gnutls_session_t}  structure.
  72
  73 This function will return the MTU size as set with
  74 @code{gnutls_dtls_set_mtu()} . This is not the actual MTU
  75 of data you can transmit. Use @code{gnutls_dtls_get_data_mtu()}
  76 for that reason.
  77
  78 @strong{Returns:} the set maximum transfer unit.
  79
  80 @strong{Since:} 3.0
  81 @end deftypefun
  82
  83 @subheading gnutls_dtls_get_timeout
  84 @anchor{gnutls_dtls_get_timeout}
  85 @deftypefun {unsigned int} {gnutls_dtls_get_timeout} (gnutls_session_t @var{session})
  86 @var{session}: is a @code{gnutls_session_t}  structure.
  87
  88 This function will return the milliseconds remaining
  89 for a retransmission of the previously sent handshake
  90 message. This function is useful when DTLS is used in
  91 non-blocking mode, to estimate when to call @code{gnutls_handshake()}
  92 if no packets have been received.
  93
  94 @strong{Returns:} the remaining time in milliseconds.
  95
  96 @strong{Since:} 3.0
  97 @end deftypefun
  98
  99 @subheading gnutls_dtls_prestate_set
 100 @anchor{gnutls_dtls_prestate_set}
 101 @deftypefun {void} {gnutls_dtls_prestate_set} (gnutls_session_t @var{session}, gnutls_dtls_prestate_st* @var{prestate})
 102 @var{session}: a new session
 103
 104 @var{prestate}: contains the client's prestate
 105
 106 This function will associate the prestate acquired by
 107 the cookie authentication with the client, with the newly
 108 established session.
 109
 110 @strong{Since:} 3.0
 111 @end deftypefun
 112
 113 @subheading gnutls_dtls_set_data_mtu
 114 @anchor{gnutls_dtls_set_data_mtu}
 115 @deftypefun {int} {gnutls_dtls_set_data_mtu} (gnutls_session_t @var{session}, unsigned int @var{mtu})
 116 @var{session}: is a @code{gnutls_session_t}  structure.
 117
 118 @var{mtu}: The maximum unencrypted transfer unit of the session
 119
 120 This function will set the maximum size of the *unencrypted* records
 121 which will be sent over a DTLS session. It is equivalent to calculating
 122 the DTLS packet overhead with the current encryption parameters, and
 123 calling @code{gnutls_dtls_set_mtu()}  with that value. In particular, this means
 124 that you may need to call this function again after any negotiation or
 125 renegotiation, in order to ensure that the MTU is still sufficient to
 126 account for the new protocol overhead.
 127
 128 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success, or a negative error code.
 129
 130 @strong{Since:} 3.1
 131 @end deftypefun
 132
 133 @subheading gnutls_dtls_set_mtu
 134 @anchor{gnutls_dtls_set_mtu}
 135 @deftypefun {void} {gnutls_dtls_set_mtu} (gnutls_session_t @var{session}, unsigned int @var{mtu})
 136 @var{session}: is a @code{gnutls_session_t}  structure.
 137
 138 @var{mtu}: The maximum transfer unit of the transport
 139
 140 This function will set the maximum transfer unit of the transport
 141 that DTLS packets are sent over. Note that this should exclude
 142 the IP (or IPv6) and UDP headers. So for DTLS over IPv6 on an
 143 Ethenet device with MTU 1500, the DTLS MTU set with this function
 144 would be 1500 - 40 (IPV6 header) - 8 (UDP header) = 1452.
 145
 146 @strong{Since:} 3.0
 147 @end deftypefun
 148
 149 @subheading gnutls_dtls_set_timeouts
 150 @anchor{gnutls_dtls_set_timeouts}
 151 @deftypefun {void} {gnutls_dtls_set_timeouts} (gnutls_session_t @var{session}, unsigned int @var{retrans_timeout}, unsigned int @var{total_timeout})
 152 @var{session}: is a @code{gnutls_session_t}  structure.
 153
 154 @var{retrans_timeout}: The time at which a retransmission will occur in milliseconds
 155
 156 @var{total_timeout}: The time at which the connection will be aborted, in milliseconds.
 157
 158 This function will set the timeouts required for the DTLS handshake
 159 protocol. The retransmission timeout is the time after which a
 160 message from the peer is not received, the previous messages will
 161 be retransmitted. The total timeout is the time after which the
 162 handshake will be aborted with @code{GNUTLS_E_TIMEDOUT} .
 163
 164 The DTLS protocol recommends the values of 1 sec and 60 seconds
 165 respectively.
 166
 167 If the retransmission timeout is zero then the handshake will operate
 168 in a non-blocking way, i.e., return @code{GNUTLS_E_AGAIN} .
 169
 170 @strong{Since:} 3.0
 171 @end deftypefun
 172
 173 @subheading gnutls_record_get_discarded
 174 @anchor{gnutls_record_get_discarded}
 175 @deftypefun {unsigned int} {gnutls_record_get_discarded} (gnutls_session_t @var{session})
 176 @var{session}: is a @code{gnutls_session_t}  structure.
 177
 178 Returns the number of discarded packets in a
 179 DTLS connection.
 180
 181 @strong{Returns:} The number of discarded packets.
 182
 183 @strong{Since:} 3.0
 184 @end deftypefun
 185