1DTLSV1_LISTEN(3ossl)                OpenSSL               DTLSV1_LISTEN(3ossl)
2
3
4

NAME

6       SSL_stateless, DTLSv1_listen - Statelessly listen for incoming
7       connections
8

SYNOPSIS

10        #include <openssl/ssl.h>
11
12        int SSL_stateless(SSL *s);
13        int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
14

DESCRIPTION

16       SSL_stateless() statelessly listens for new incoming TLSv1.3
17       connections.  DTLSv1_listen() statelessly listens for new incoming DTLS
18       connections. If a ClientHello is received that does not contain a
19       cookie, then they respond with a request for a new ClientHello that
20       does contain a cookie. If a ClientHello is received with a cookie that
21       is verified then the function returns in order to enable the handshake
22       to be completed (for example by using SSL_accept()).
23

NOTES

25       Some transport protocols (such as UDP) can be susceptible to
26       amplification attacks. Unlike TCP there is no initial connection setup
27       in UDP that validates that the client can actually receive messages on
28       its advertised source address. An attacker could forge its source IP
29       address and then send handshake initiation messages to the server. The
30       server would then send its response to the forged source IP. If the
31       response messages are larger than the original message then the
32       amplification attack has succeeded.
33
34       If DTLS is used over UDP (or any datagram based protocol that does not
35       validate the source IP) then it is susceptible to this type of attack.
36       TLSv1.3 is designed to operate over a stream-based transport protocol
37       (such as TCP).  If TCP is being used then there is no need to use
38       SSL_stateless(). However, some stream-based transport protocols (e.g.
39       QUIC) may not validate the source address. In this case a TLSv1.3
40       application would be susceptible to this attack.
41
42       As a countermeasure to this issue TLSv1.3 and DTLS include a stateless
43       cookie mechanism. The idea is that when a client attempts to connect to
44       a server it sends a ClientHello message. The server responds with a
45       HelloRetryRequest (in TLSv1.3) or a HelloVerifyRequest (in DTLS) which
46       contains a unique cookie. The client then resends the ClientHello, but
47       this time includes the cookie in the message thus proving that the
48       client is capable of receiving messages sent to that address. All of
49       this can be done by the server without allocating any state, and thus
50       without consuming expensive resources.
51
52       OpenSSL implements this capability via the SSL_stateless() and
53       DTLSv1_listen() functions. The ssl parameter should be a newly
54       allocated SSL object with its read and write BIOs set, in the same way
55       as might be done for a call to SSL_accept(). Typically, for DTLS, the
56       read BIO will be in an "unconnected" state and thus capable of
57       receiving messages from any peer.
58
59       When a ClientHello is received that contains a cookie that has been
60       verified, then these functions will return with the ssl parameter
61       updated into a state where the handshake can be continued by a call to
62       (for example) SSL_accept().  Additionally, for DTLSv1_listen(), the
63       BIO_ADDR pointed to by peer will be filled in with details of the peer
64       that sent the ClientHello. If the underlying BIO is unable to obtain
65       the BIO_ADDR of the peer (for example because the BIO does not support
66       this), then *peer will be cleared and the family set to AF_UNSPEC.
67       Typically user code is expected to "connect" the underlying socket to
68       the peer and continue the handshake in a connected state.
69
70       Warning: It is essential that the calling code connects the underlying
71       socket to the peer after making use of DTLSv1_listen(). In the typical
72       case where BIO_s_datagram(3) is used, the peer address is updated when
73       receiving a datagram on an unconnected socket. If the socket is not
74       connected, it can receive datagrams from any host on the network, which
75       will cause subsequent outgoing datagrams transmitted by DTLS to be
76       transmitted to that host. In other words, failing to call BIO_connect()
77       or a similar OS-specific function on a socket means that any host on
78       the network can cause outgoing DTLS traffic to be redirected to it by
79       sending a datagram to the socket in question. This does not break the
80       cryptographic protections of DTLS but may facilitate a denial-of-
81       service attack or allow unencrypted information in the DTLS handshake
82       to be learned by an attacker. This is due to the historical design of
83       BIO_s_datagram(3); see BIO_s_datagram(3) for details on this issue.
84
85       Once a socket has been connected, BIO_ctrl_set_connected(3) should be
86       used to inform the BIO that the socket is to be used in connected mode.
87
88       Prior to calling DTLSv1_listen() user code must ensure that cookie
89       generation and verification callbacks have been set up using
90       SSL_CTX_set_cookie_generate_cb(3) and SSL_CTX_set_cookie_verify_cb(3)
91       respectively. For SSL_stateless(),
92       SSL_CTX_set_stateless_cookie_generate_cb(3) and
93       SSL_CTX_set_stateless_cookie_verify_cb(3) must be used instead.
94
95       Since DTLSv1_listen() operates entirely statelessly whilst processing
96       incoming ClientHellos it is unable to process fragmented messages
97       (since this would require the allocation of state). An implication of
98       this is that DTLSv1_listen() only supports ClientHellos that fit inside
99       a single datagram.
100
101       For SSL_stateless() if an entire ClientHello message cannot be read
102       without the "read" BIO becoming empty then the SSL_stateless() call
103       will fail. It is the application's responsibility to ensure that data
104       read from the "read" BIO during a single SSL_stateless() call is all
105       from the same peer.
106
107       SSL_stateless() will fail (with a 0 return value) if some TLS version
108       less than TLSv1.3 is used.
109
110       Both SSL_stateless() and DTLSv1_listen() will clear the error queue
111       when they start.
112

RETURN VALUES

114       For SSL_stateless() a return value of 1 indicates success and the ssl
115       object will be set up ready to continue the handshake. A return value
116       of 0 or -1 indicates failure. If the value is 0 then a
117       HelloRetryRequest was sent. A value of -1 indicates any other error.
118       User code may retry the SSL_stateless() call.
119
120       For DTLSv1_listen() a return value of >= 1 indicates success. The ssl
121       object will be set up ready to continue the handshake.  the peer value
122       will also be filled in.
123
124       A return value of 0 indicates a non-fatal error. This could (for
125       example) be because of nonblocking IO, or some invalid message having
126       been received from a peer. Errors may be placed on the OpenSSL error
127       queue with further information if appropriate. Typically user code is
128       expected to retry the call to DTLSv1_listen() in the event of a non-
129       fatal error.
130
131       A return value of <0 indicates a fatal error. This could (for example)
132       be because of a failure to allocate sufficient memory for the
133       operation.
134
135       For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors
136       both produce return codes <= 0 (in typical implementations user code
137       treats all errors as non-fatal), whilst return codes >0 indicate
138       success.
139

SEE ALSO

141       SSL_CTX_set_cookie_generate_cb(3), SSL_CTX_set_cookie_verify_cb(3),
142       SSL_CTX_set_stateless_cookie_generate_cb(3),
143       SSL_CTX_set_stateless_cookie_verify_cb(3), SSL_get_error(3),
144       SSL_accept(3), ssl(7), bio(7)
145

HISTORY

147       The SSL_stateless() function was added in OpenSSL 1.1.1.
148
149       The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0.  The
150       type of "peer" also changed in OpenSSL 1.1.0.
151
153       Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.
154
155       Licensed under the Apache License 2.0 (the "License").  You may not use
156       this file except in compliance with the License.  You can obtain a copy
157       in the file LICENSE in the source distribution or at
158       <https://www.openssl.org/source/license.html>.
159
160
161
1623.1.1                             2023-08-31              DTLSV1_LISTEN(3ossl)
Impressum