1DTLSV1_LISTEN(3) OpenSSL DTLSV1_LISTEN(3)
2
6 SSL_stateless, DTLSv1_listen - Statelessly listen for incoming
7 connections
8
10 #include <openssl/ssl.h>
11 int SSL_stateless(SSL *s);
13 int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
14
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
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 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 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 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 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 Prior to calling DTLSv1_listen() user code must ensure that cookie
71 generation and verification callbacks have been set up using
72 SSL_CTX_set_cookie_generate_cb(3) and SSL_CTX_set_cookie_verify_cb(3)
73 respectively. For SSL_stateless(),
74 SSL_CTX_set_stateless_cookie_generate_cb(3) and
75 SSL_CTX_set_stateless_cookie_verify_cb(3) must be used instead.
76 Since DTLSv1_listen() operates entirely statelessly whilst processing
78 incoming ClientHellos it is unable to process fragmented messages
79 (since this would require the allocation of state). An implication of
80 this is that DTLSv1_listen() only supports ClientHellos that fit inside
81 a single datagram.
82 For SSL_stateless() if an entire ClientHello message cannot be read
84 without the "read" BIO becoming empty then the SSL_stateless() call
85 will fail. It is the application's responsibility to ensure that data
86 read from the "read" BIO during a single SSL_stateless() call is all
87 from the same peer.
88 SSL_stateless() will fail (with a 0 return value) if some TLS version
90 less than TLSv1.3 is used.
91 Both SSL_stateless() and DTLSv1_listen() will clear the error queue
93 when they start.
94
96 For SSL_stateless() a return value of 1 indicates success and the ssl
97 object will be set up ready to continue the handshake. A return value
98 of 0 or -1 indicates failure. If the value is 0 then a
99 HelloRetryRequest was sent. A value of -1 indicates any other error.
100 User code may retry the SSL_stateless() call.
101 For DTLSv1_listen() a return value of >= 1 indicates success. The ssl
103 object will be set up ready to continue the handshake. the peer value
104 will also be filled in.
105 A return value of 0 indicates a non-fatal error. This could (for
107 example) be because of nonblocking IO, or some invalid message having
108 been received from a peer. Errors may be placed on the OpenSSL error
109 queue with further information if appropriate. Typically user code is
110 expected to retry the call to DTLSv1_listen() in the event of a non-
111 fatal error.
112 A return value of <0 indicates a fatal error. This could (for example)
114 be because of a failure to allocate sufficient memory for the
115 operation.
116 For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors
118 both produce return codes <= 0 (in typical implementations user code
119 treats all errors as non-fatal), whilst return codes >0 indicate
120 success.
121
123 SSL_CTX_set_cookie_generate_cb(3), SSL_CTX_set_cookie_verify_cb(3),
124 SSL_CTX_set_stateless_cookie_generate_cb(3),
125 SSL_CTX_set_stateless_cookie_verify_cb(3), SSL_get_error(3),
126 SSL_accept(3), ssl(7), bio(7)
127
129 The SSL_stateless() function was added in OpenSSL 1.1.1.
130 The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The
132 type of "peer" also changed in OpenSSL 1.1.0.
133
135 Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
136 Licensed under the OpenSSL license (the "License"). You may not use
138 this file except in compliance with the License. You can obtain a copy
139 in the file LICENSE in the source distribution or at
140 <https://www.openssl.org/source/license.html>.
1411.1.1q 2022-07-21 DTLSV1_LISTEN(3)