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 67Warning: It is essential that the calling code connects the underlying socket to 68the peer after making use of DTLSv1_listen(). In the typical case where 69L<BIO_s_datagram(3)> is used, the peer address is updated when receiving a 70datagram on an unconnected socket. If the socket is not connected, it can 71receive datagrams from any host on the network, which will cause subsequent 72outgoing datagrams transmitted by DTLS to be transmitted to that host. In other 73words, failing to call BIO_connect() or a similar OS-specific function on a 74socket means that any host on the network can cause outgoing DTLS traffic to be 75redirected to it by sending a datagram to the socket in question. This does not 76break the cryptographic protections of DTLS but may facilitate a 77denial-of-service attack or allow unencrypted information in the DTLS handshake 78to be learned by an attacker. This is due to the historical design of 79L<BIO_s_datagram(3)>; see L<BIO_s_datagram(3)> for details on this issue. 80 81Once a socket has been connected, L<BIO_ctrl_set_connected(3)> should be used to 82inform the BIO that the socket is to be used in connected mode. 83 84Prior to calling DTLSv1_listen() user code must ensure that cookie generation 85and verification callbacks have been set up using 86L<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)> 87respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)> 88and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead. 89 90Since DTLSv1_listen() operates entirely statelessly whilst processing incoming 91ClientHellos it is unable to process fragmented messages (since this would 92require the allocation of state). An implication of this is that DTLSv1_listen() 93B<only> supports ClientHellos that fit inside a single datagram. 94 95For 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 97application's responsibility to ensure that data read from the "read" BIO during 98a single SSL_stateless() call is all from the same peer. 99 100SSL_stateless() will fail (with a 0 return value) if some TLS version less than 101TLSv1.3 is used. 102 103Both SSL_stateless() and DTLSv1_listen() will clear the error queue when they 104start. 105 106SSL_stateless() cannot be used with QUIC SSL objects and returns an error if 107called on such an object. 108 109=head1 RETURN VALUES 110 111For SSL_stateless() a return value of 1 indicates success and the B<ssl> object 112will be set up ready to continue the handshake. A return value of 0 or -1 113indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value 114of -1 indicates any other error. User code may retry the SSL_stateless() call. 115 116For DTLSv1_listen() a return value of >= 1 indicates success. The B<ssl> object 117will be set up ready to continue the handshake. the B<peer> value will also be 118filled in. 119 120A return value of 0 indicates a non-fatal error. This could (for 121example) be because of nonblocking IO, or some invalid message having been 122received from a peer. Errors may be placed on the OpenSSL error queue with 123further information if appropriate. Typically user code is expected to retry the 124call to DTLSv1_listen() in the event of a non-fatal error. 125 126A return value of <0 indicates a fatal error. This could (for example) be 127because of a failure to allocate sufficient memory for the operation. 128 129For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both 130produce return codes <= 0 (in typical implementations user code treats all 131errors as non-fatal), whilst return codes >0 indicate success. 132 133=head1 SEE ALSO 134 135L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>, 136L<SSL_CTX_set_stateless_cookie_generate_cb(3)>, 137L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>, 138L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)> 139 140=head1 HISTORY 141 142The SSL_stateless() function was added in OpenSSL 1.1.1. 143 144The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. 145The type of "peer" also changed in OpenSSL 1.1.0. 146 147=head1 COPYRIGHT 148 149Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved. 150 151Licensed under the Apache License 2.0 (the "License"). You may not use 152this file except in compliance with the License. You can obtain a copy 153in the file LICENSE in the source distribution or at 154L<https://www.openssl.org/source/license.html>. 155 156=cut 157
