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