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