1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_stateless, 6e71b7053SJung-uk KimDTLSv1_listen 7e71b7053SJung-uk Kim- Statelessly listen for incoming connections 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim=head1 SYNOPSIS 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim #include <openssl/ssl.h> 12e71b7053SJung-uk Kim 13e71b7053SJung-uk Kim int SSL_stateless(SSL *s); 14e71b7053SJung-uk Kim int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim=head1 DESCRIPTION 17e71b7053SJung-uk Kim 18e71b7053SJung-uk KimSSL_stateless() statelessly listens for new incoming TLSv1.3 connections. 19e71b7053SJung-uk KimDTLSv1_listen() statelessly listens for new incoming DTLS connections. If a 20e71b7053SJung-uk KimClientHello is received that does not contain a cookie, then they respond with a 21e71b7053SJung-uk Kimrequest for a new ClientHello that does contain a cookie. If a ClientHello is 22e71b7053SJung-uk Kimreceived with a cookie that is verified then the function returns in order to 23e71b7053SJung-uk Kimenable the handshake to be completed (for example by using SSL_accept()). 24e71b7053SJung-uk Kim 25e71b7053SJung-uk Kim=head1 NOTES 26e71b7053SJung-uk Kim 27e71b7053SJung-uk KimSome transport protocols (such as UDP) can be susceptible to amplification 28e71b7053SJung-uk Kimattacks. Unlike TCP there is no initial connection setup in UDP that 29e71b7053SJung-uk Kimvalidates that the client can actually receive messages on its advertised source 30e71b7053SJung-uk Kimaddress. An attacker could forge its source IP address and then send handshake 31e71b7053SJung-uk Kiminitiation messages to the server. The server would then send its response to 32e71b7053SJung-uk Kimthe forged source IP. If the response messages are larger than the original 33e71b7053SJung-uk Kimmessage then the amplification attack has succeeded. 34e71b7053SJung-uk Kim 35e71b7053SJung-uk KimIf DTLS is used over UDP (or any datagram based protocol that does not validate 36e71b7053SJung-uk Kimthe source IP) then it is susceptible to this type of attack. TLSv1.3 is 37e71b7053SJung-uk Kimdesigned to operate over a stream-based transport protocol (such as TCP). 3858f35182SJung-uk KimIf TCP is being used then there is no need to use SSL_stateless(). However, some 39e71b7053SJung-uk Kimstream-based transport protocols (e.g. QUIC) may not validate the source 40e71b7053SJung-uk Kimaddress. In this case a TLSv1.3 application would be susceptible to this attack. 41e71b7053SJung-uk Kim 42e71b7053SJung-uk KimAs a countermeasure to this issue TLSv1.3 and DTLS include a stateless cookie 43e71b7053SJung-uk Kimmechanism. The idea is that when a client attempts to connect to a server it 44e71b7053SJung-uk Kimsends a ClientHello message. The server responds with a HelloRetryRequest (in 45e71b7053SJung-uk KimTLSv1.3) or a HelloVerifyRequest (in DTLS) which contains a unique cookie. The 46e71b7053SJung-uk Kimclient then resends the ClientHello, but this time includes the cookie in the 47e71b7053SJung-uk Kimmessage thus proving that the client is capable of receiving messages sent to 48e71b7053SJung-uk Kimthat address. All of this can be done by the server without allocating any 49e71b7053SJung-uk Kimstate, and thus without consuming expensive resources. 50e71b7053SJung-uk Kim 51e71b7053SJung-uk KimOpenSSL implements this capability via the SSL_stateless() and DTLSv1_listen() 52e71b7053SJung-uk Kimfunctions. The B<ssl> parameter should be a newly allocated SSL object with its 53e71b7053SJung-uk Kimread and write BIOs set, in the same way as might be done for a call to 54e71b7053SJung-uk KimSSL_accept(). Typically, for DTLS, the read BIO will be in an "unconnected" 55e71b7053SJung-uk Kimstate and thus capable of receiving messages from any peer. 56e71b7053SJung-uk Kim 57e71b7053SJung-uk KimWhen a ClientHello is received that contains a cookie that has been verified, 58e71b7053SJung-uk Kimthen these functions will return with the B<ssl> parameter updated into a state 59e71b7053SJung-uk Kimwhere the handshake can be continued by a call to (for example) SSL_accept(). 60e71b7053SJung-uk KimAdditionally, for DTLSv1_listen(), the B<BIO_ADDR> pointed to by B<peer> will be 61e71b7053SJung-uk Kimfilled in with details of the peer that sent the ClientHello. If the underlying 62e71b7053SJung-uk KimBIO is unable to obtain the B<BIO_ADDR> of the peer (for example because the BIO 63e71b7053SJung-uk Kimdoes not support this), then B<*peer> will be cleared and the family set to 64e71b7053SJung-uk KimAF_UNSPEC. Typically user code is expected to "connect" the underlying socket to 65e71b7053SJung-uk Kimthe peer and continue the handshake in a connected state. 66e71b7053SJung-uk Kim 67*b077aed3SPierre ProncheryWarning: It is essential that the calling code connects the underlying socket to 68*b077aed3SPierre Proncherythe peer after making use of DTLSv1_listen(). In the typical case where 69*b077aed3SPierre ProncheryL<BIO_s_datagram(3)> is used, the peer address is updated when receiving a 70*b077aed3SPierre Proncherydatagram on an unconnected socket. If the socket is not connected, it can 71*b077aed3SPierre Proncheryreceive datagrams from any host on the network, which will cause subsequent 72*b077aed3SPierre Proncheryoutgoing datagrams transmitted by DTLS to be transmitted to that host. In other 73*b077aed3SPierre Proncherywords, failing to call BIO_connect() or a similar OS-specific function on a 74*b077aed3SPierre Proncherysocket means that any host on the network can cause outgoing DTLS traffic to be 75*b077aed3SPierre Proncheryredirected to it by sending a datagram to the socket in question. This does not 76*b077aed3SPierre Proncherybreak the cryptographic protections of DTLS but may facilitate a 77*b077aed3SPierre Proncherydenial-of-service attack or allow unencrypted information in the DTLS handshake 78*b077aed3SPierre Proncheryto be learned by an attacker. This is due to the historical design of 79*b077aed3SPierre ProncheryL<BIO_s_datagram(3)>; see L<BIO_s_datagram(3)> for details on this issue. 80*b077aed3SPierre Pronchery 81*b077aed3SPierre ProncheryOnce a socket has been connected, L<BIO_ctrl_set_connected(3)> should be used to 82*b077aed3SPierre Proncheryinform the BIO that the socket is to be used in connected mode. 83*b077aed3SPierre Pronchery 84e71b7053SJung-uk KimPrior to calling DTLSv1_listen() user code must ensure that cookie generation 85e71b7053SJung-uk Kimand verification callbacks have been set up using 8617f01e99SJung-uk KimL<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)> 8717f01e99SJung-uk Kimrespectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)> 8817f01e99SJung-uk Kimand L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead. 89e71b7053SJung-uk Kim 90e71b7053SJung-uk KimSince DTLSv1_listen() operates entirely statelessly whilst processing incoming 91e71b7053SJung-uk KimClientHellos it is unable to process fragmented messages (since this would 92e71b7053SJung-uk Kimrequire the allocation of state). An implication of this is that DTLSv1_listen() 93e71b7053SJung-uk KimB<only> supports ClientHellos that fit inside a single datagram. 94e71b7053SJung-uk Kim 95e71b7053SJung-uk KimFor SSL_stateless() if an entire ClientHello message cannot be read without the 96e71b7053SJung-uk Kim"read" BIO becoming empty then the SSL_stateless() call will fail. It is the 97e71b7053SJung-uk Kimapplication's responsibility to ensure that data read from the "read" BIO during 98e71b7053SJung-uk Kima single SSL_stateless() call is all from the same peer. 99e71b7053SJung-uk Kim 100e71b7053SJung-uk KimSSL_stateless() will fail (with a 0 return value) if some TLS version less than 101e71b7053SJung-uk KimTLSv1.3 is used. 102e71b7053SJung-uk Kim 103e71b7053SJung-uk KimBoth SSL_stateless() and DTLSv1_listen() will clear the error queue when they 104e71b7053SJung-uk Kimstart. 105e71b7053SJung-uk Kim 106e71b7053SJung-uk Kim=head1 RETURN VALUES 107e71b7053SJung-uk Kim 108e71b7053SJung-uk KimFor SSL_stateless() a return value of 1 indicates success and the B<ssl> object 109e71b7053SJung-uk Kimwill be set up ready to continue the handshake. A return value of 0 or -1 110e71b7053SJung-uk Kimindicates failure. If the value is 0 then a HelloRetryRequest was sent. A value 111e71b7053SJung-uk Kimof -1 indicates any other error. User code may retry the SSL_stateless() call. 112e71b7053SJung-uk Kim 113e71b7053SJung-uk KimFor DTLSv1_listen() a return value of >= 1 indicates success. The B<ssl> object 114e71b7053SJung-uk Kimwill be set up ready to continue the handshake. the B<peer> value will also be 115e71b7053SJung-uk Kimfilled in. 116e71b7053SJung-uk Kim 117e71b7053SJung-uk KimA return value of 0 indicates a non-fatal error. This could (for 11858f35182SJung-uk Kimexample) be because of nonblocking IO, or some invalid message having been 119e71b7053SJung-uk Kimreceived from a peer. Errors may be placed on the OpenSSL error queue with 120e71b7053SJung-uk Kimfurther information if appropriate. Typically user code is expected to retry the 121e71b7053SJung-uk Kimcall to DTLSv1_listen() in the event of a non-fatal error. 122e71b7053SJung-uk Kim 123e71b7053SJung-uk KimA return value of <0 indicates a fatal error. This could (for example) be 124e71b7053SJung-uk Kimbecause of a failure to allocate sufficient memory for the operation. 125e71b7053SJung-uk Kim 126e71b7053SJung-uk KimFor DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both 127e71b7053SJung-uk Kimproduce return codes <= 0 (in typical implementations user code treats all 128e71b7053SJung-uk Kimerrors as non-fatal), whilst return codes >0 indicate success. 129e71b7053SJung-uk Kim 130e71b7053SJung-uk Kim=head1 SEE ALSO 131e71b7053SJung-uk Kim 13217f01e99SJung-uk KimL<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>, 13317f01e99SJung-uk KimL<SSL_CTX_set_stateless_cookie_generate_cb(3)>, 13417f01e99SJung-uk KimL<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>, 13517f01e99SJung-uk KimL<SSL_accept(3)>, L<ssl(7)>, L<bio(7)> 136e71b7053SJung-uk Kim 137e71b7053SJung-uk Kim=head1 HISTORY 138e71b7053SJung-uk Kim 1396935a639SJung-uk KimThe SSL_stateless() function was added in OpenSSL 1.1.1. 140e71b7053SJung-uk Kim 1416935a639SJung-uk KimThe DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. 1426935a639SJung-uk KimThe type of "peer" also changed in OpenSSL 1.1.0. 143e71b7053SJung-uk Kim 144e71b7053SJung-uk Kim=head1 COPYRIGHT 145e71b7053SJung-uk Kim 146*b077aed3SPierre ProncheryCopyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved. 147e71b7053SJung-uk Kim 148*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 149e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 150e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 151e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 152e71b7053SJung-uk Kim 153e71b7053SJung-uk Kim=cut 154