Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "DTLSV1_LISTEN 3ossl"
way too many mistakes in technical documents.
If \s-1DTLS\s0 is used over \s-1UDP\s0 (or any datagram based protocol that does not validate the source \s-1IP\s0) then it is susceptible to this type of attack. TLSv1.3 is designed to operate over a stream-based transport protocol (such as \s-1TCP\s0). If \s-1TCP\s0 is being used then there is no need to use SSL_stateless(). However, some stream-based transport protocols (e.g. \s-1QUIC\s0) may not validate the source address. In this case a TLSv1.3 application would be susceptible to this attack.
As a countermeasure to this issue TLSv1.3 and \s-1DTLS\s0 include a stateless cookie mechanism. The idea is that when a client attempts to connect to a server it sends a ClientHello message. The server responds with a HelloRetryRequest (in TLSv1.3) or a HelloVerifyRequest (in \s-1DTLS\s0) which contains a unique cookie. The client then resends the ClientHello, but this time includes the cookie in the message thus proving that the client is capable of receiving messages sent to that address. All of this can be done by the server without allocating any state, and thus without consuming expensive resources.
OpenSSL implements this capability via the SSL_stateless() and DTLSv1_listen() functions. The ssl parameter should be a newly allocated \s-1SSL\s0 object with its read and write BIOs set, in the same way as might be done for a call to \fBSSL_accept(). Typically, for \s-1DTLS,\s0 the read \s-1BIO\s0 will be in an \*(L"unconnected\*(R" state and thus capable of receiving messages from any peer.
When a ClientHello is received that contains a cookie that has been verified, then these functions will return with the ssl parameter updated into a state where the handshake can be continued by a call to (for example) SSL_accept(). Additionally, for DTLSv1_listen(), the \s-1BIO_ADDR\s0 pointed to by peer will be filled in with details of the peer that sent the ClientHello. If the underlying \s-1BIO\s0 is unable to obtain the \s-1BIO_ADDR\s0 of the peer (for example because the \s-1BIO\s0 does not support this), then *peer will be cleared and the family set to \s-1AF_UNSPEC.\s0 Typically user code is expected to \*(L"connect\*(R" the underlying socket to the peer and continue the handshake in a connected state.
Warning: It is essential that the calling code connects the underlying socket to the peer after making use of DTLSv1_listen(). In the typical case where \fBBIO_s_datagram\|(3) is used, the peer address is updated when receiving a datagram on an unconnected socket. If the socket is not connected, it can receive datagrams from any host on the network, which will cause subsequent outgoing datagrams transmitted by \s-1DTLS\s0 to be transmitted to that host. In other words, failing to call BIO_connect() or a similar OS-specific function on a socket means that any host on the network can cause outgoing \s-1DTLS\s0 traffic to be redirected to it by sending a datagram to the socket in question. This does not break the cryptographic protections of \s-1DTLS\s0 but may facilitate a denial-of-service attack or allow unencrypted information in the \s-1DTLS\s0 handshake to be learned by an attacker. This is due to the historical design of \fBBIO_s_datagram\|(3); see BIO_s_datagram\|(3) for details on this issue.
Once a socket has been connected, BIO_ctrl_set_connected\|(3) should be used to inform the \s-1BIO\s0 that the socket is to be used in connected mode.
Prior to calling DTLSv1_listen() user code must ensure that cookie generation and verification callbacks have been set up using \fBSSL_CTX_set_cookie_generate_cb\|(3) and SSL_CTX_set_cookie_verify_cb\|(3) respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb\|(3) and SSL_CTX_set_stateless_cookie_verify_cb\|(3) must be used instead.
Since DTLSv1_listen() operates entirely statelessly whilst processing incoming ClientHellos it is unable to process fragmented messages (since this would require the allocation of state). An implication of this is that DTLSv1_listen() \fBonly supports ClientHellos that fit inside a single datagram.
For SSL_stateless() if an entire ClientHello message cannot be read without the \*(L"read\*(R" \s-1BIO\s0 becoming empty then the SSL_stateless() call will fail. It is the application's responsibility to ensure that data read from the \*(L"read\*(R" \s-1BIO\s0 during a single SSL_stateless() call is all from the same peer.
\fBSSL_stateless() will fail (with a 0 return value) if some \s-1TLS\s0 version less than TLSv1.3 is used.
Both SSL_stateless() and DTLSv1_listen() will clear the error queue when they start.
For DTLSv1_listen() a return value of >= 1 indicates success. The ssl object will be set up ready to continue the handshake. the peer value will also be filled in.
A return value of 0 indicates a non-fatal error. This could (for example) be because of nonblocking \s-1IO,\s0 or some invalid message having been received from a peer. Errors may be placed on the OpenSSL error queue with further information if appropriate. Typically user code is expected to retry the call to DTLSv1_listen() in the event of a non-fatal error.
A return value of <0 indicates a fatal error. This could (for example) be because of a failure to allocate sufficient memory for the operation.
For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both produce return codes <= 0 (in typical implementations user code treats all errors as non-fatal), whilst return codes >0 indicate success.
The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of \*(L"peer\*(R" also changed in OpenSSL 1.1.0.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.