doc/man3/DTLSv1_listen.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_stateless,
   6 DTLSv1_listen
   7 - Statelessly listen for incoming connections
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  int SSL_stateless(SSL *s);
  14  int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
  15
  16 =head1 DESCRIPTION
  17
  18 SSL_stateless() statelessly listens for new incoming TLSv1.3 connections.
  19 DTLSv1_listen() statelessly listens for new incoming DTLS connections. If a
  20 ClientHello is received that does not contain a cookie, then they respond with a
  21 request for a new ClientHello that does contain a cookie. If a ClientHello is
  22 received with a cookie that is verified then the function returns in order to
  23 enable the handshake to be completed (for example by using SSL_accept()).
  24
  25 =head1 NOTES
  26
  27 Some transport protocols (such as UDP) can be susceptible to amplification
  28 attacks. Unlike TCP there is no initial connection setup in UDP that
  29 validates that the client can actually receive messages on its advertised source
  30 address. An attacker could forge its source IP address and then send handshake
  31 initiation messages to the server. The server would then send its response to
  32 the forged source IP. If the response messages are larger than the original
  33 message then the amplification attack has succeeded.
  34
  35 If DTLS is used over UDP (or any datagram based protocol that does not validate
  36 the source IP) then it is susceptible to this type of attack. TLSv1.3 is
  37 designed to operate over a stream-based transport protocol (such as TCP).
  38 If TCP is being used then there is no need to use SSL_stateless(). However, some
  39 stream-based transport protocols (e.g. QUIC) may not validate the source
  40 address. In this case a TLSv1.3 application would be susceptible to this attack.
  41
  42 As a countermeasure to this issue TLSv1.3 and DTLS include a stateless cookie
  43 mechanism. The idea is that when a client attempts to connect to a server it
  44 sends a ClientHello message. The server responds with a HelloRetryRequest (in
  45 TLSv1.3) or a HelloVerifyRequest (in DTLS) which contains a unique cookie. The
  46 client then resends the ClientHello, but this time includes the cookie in the
  47 message thus proving that the client is capable of receiving messages sent to
  48 that address. All of this can be done by the server without allocating any
  49 state, and thus without consuming expensive resources.
  50
  51 OpenSSL implements this capability via the SSL_stateless() and DTLSv1_listen()
  52 functions. The B<ssl> parameter should be a newly allocated SSL object with its
  53 read and write BIOs set, in the same way as might be done for a call to
  54 SSL_accept(). Typically, for DTLS, the read BIO will be in an "unconnected"
  55 state and thus capable of receiving messages from any peer.
  56
  57 When a ClientHello is received that contains a cookie that has been verified,
  58 then these functions will return with the B<ssl> parameter updated into a state
  59 where the handshake can be continued by a call to (for example) SSL_accept().
  60 Additionally, for DTLSv1_listen(), the B<BIO_ADDR> pointed to by B<peer> will be
  61 filled in with details of the peer that sent the ClientHello. If the underlying
  62 BIO is unable to obtain the B<BIO_ADDR> of the peer (for example because the BIO
  63 does not support this), then B<*peer> will be cleared and the family set to
  64 AF_UNSPEC. Typically user code is expected to "connect" the underlying socket to
  65 the peer and continue the handshake in a connected state.
  66
  67 Warning: It is essential that the calling code connects the underlying socket to
  68 the peer after making use of DTLSv1_listen(). In the typical case where
  69 L<BIO_s_datagram(3)> is used, the peer address is updated when receiving a
  70 datagram on an unconnected socket. If the socket is not connected, it can
  71 receive datagrams from any host on the network, which will cause subsequent
  72 outgoing datagrams transmitted by DTLS to be transmitted to that host. In other
  73 words, failing to call BIO_connect() or a similar OS-specific function on a
  74 socket means that any host on the network can cause outgoing DTLS traffic to be
  75 redirected to it by sending a datagram to the socket in question. This does not
  76 break the cryptographic protections of DTLS but may facilitate a
  77 denial-of-service attack or allow unencrypted information in the DTLS handshake
  78 to be learned by an attacker. This is due to the historical design of
  79 L<BIO_s_datagram(3)>; see L<BIO_s_datagram(3)> for details on this issue.
  80
  81 Once a socket has been connected, L<BIO_ctrl_set_connected(3)> should be used to
  82 inform the BIO that the socket is to be used in connected mode.
  83
  84 Prior to calling DTLSv1_listen() user code must ensure that cookie generation
  85 and verification callbacks have been set up using
  86 L<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)>
  87 respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)>
  88 and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead.
  89
  90 Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
  91 ClientHellos it is unable to process fragmented messages (since this would
  92 require the allocation of state). An implication of this is that DTLSv1_listen()
  93 B<only> supports ClientHellos that fit inside a single datagram.
  94
  95 For SSL_stateless() if an entire ClientHello message cannot be read without the
  96 "read" BIO becoming empty then the SSL_stateless() call will fail. It is the
  97 application's responsibility to ensure that data read from the "read" BIO during
  98 a single SSL_stateless() call is all from the same peer.
  99
 100 SSL_stateless() will fail (with a 0 return value) if some TLS version less than
 101 TLSv1.3 is used.
 102
 103 Both SSL_stateless() and DTLSv1_listen() will clear the error queue when they
 104 start.
 105
 106 SSL_stateless() cannot be used with QUIC SSL objects and returns an error if
 107 called on such an object.
 108
 109 =head1 RETURN VALUES
 110
 111 For SSL_stateless() a return value of 1 indicates success and the B<ssl> object
 112 will be set up ready to continue the handshake. A return value of 0 or -1
 113 indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value
 114 of -1 indicates any other error. User code may retry the SSL_stateless() call.
 115
 116 For DTLSv1_listen() a return value of >= 1 indicates success. The B<ssl> object
 117 will be set up ready to continue the handshake.  the B<peer> value will also be
 118 filled in.
 119
 120 A return value of 0 indicates a non-fatal error. This could (for
 121 example) be because of nonblocking IO, or some invalid message having been
 122 received from a peer. Errors may be placed on the OpenSSL error queue with
 123 further information if appropriate. Typically user code is expected to retry the
 124 call to DTLSv1_listen() in the event of a non-fatal error.
 125
 126 A return value of <0 indicates a fatal error. This could (for example) be
 127 because of a failure to allocate sufficient memory for the operation.
 128
 129 For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both
 130 produce return codes <= 0 (in typical implementations user code treats all
 131 errors as non-fatal), whilst return codes >0 indicate success.
 132
 133 =head1 SEE ALSO
 134
 135 L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>,
 136 L<SSL_CTX_set_stateless_cookie_generate_cb(3)>,
 137 L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>,
 138 L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>
 139
 140 =head1 HISTORY
 141
 142 The SSL_stateless() function was added in OpenSSL 1.1.1.
 143
 144 The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0.
 145 The type of "peer" also changed in OpenSSL 1.1.0.
 146
 147 =head1 COPYRIGHT
 148
 149 Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.
 150
 151 Licensed under the Apache License 2.0 (the "License").  You may not use
 152 this file except in compliance with the License.  You can obtain a copy
 153 in the file LICENSE in the source distribution or at
 154 L<https://www.openssl.org/source/license.html>.
 155
 156 =cut