diff options
Diffstat (limited to 'deps/openssl/openssl/doc/ssl/DTLSv1_listen.pod')
| -rw-r--r-- | deps/openssl/openssl/doc/ssl/DTLSv1_listen.pod | 102 |
1 files changed, 0 insertions, 102 deletions
diff --git a/deps/openssl/openssl/doc/ssl/DTLSv1_listen.pod b/deps/openssl/openssl/doc/ssl/DTLSv1_listen.pod deleted file mode 100644 index a839d9fec1..0000000000 --- a/deps/openssl/openssl/doc/ssl/DTLSv1_listen.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -DTLSv1_listen - listen for incoming DTLS connections - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); - -=head1 DESCRIPTION - -DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is -received that does not contain a cookie, then DTLSv1_listen() responds with a -HelloVerifyRequest. If a ClientHello is received with a cookie that is verified -then control is returned to user code to enable the handshake to be completed -(for example by using SSL_accept()). - -=head1 NOTES - -Datagram based protocols can be susceptible to Denial of Service attacks. A -DTLS attacker could, for example, submit a series of handshake initiation -requests that cause the server to allocate state (and possibly perform -cryptographic operations) thus consuming server resources. The attacker could -also (with UDP) quite simply forge the source IP address in such an attack. - -As a counter measure to that DTLS includes 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 HelloVerifyRequest 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 DTLSv1_listen() function. The B<ssl> -parameter should be a newly allocated SSL object with its read and write BIOs -set, in the same way as might be done for a call to SSL_accept(). Typically the -read BIO will be in an "unconnected" state and thus capable of receiving -messages from any peer. - -When a ClientHello is received that contains a cookie that has been verified, -then DTLSv1_listen() will return with the B<ssl> parameter updated into a state -where the handshake can be continued by a call to (for example) SSL_accept(). -Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with -details of the peer that sent the ClientHello. If the underlying BIO is unable -to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not -support this), then B<*peer> will be cleared and the family set to AF_UNSPEC. -Typically user code is expected to "connect" the underlying socket to the peer -and continue the handshake in a connected state. - -Prior to calling DTLSv1_listen() user code must ensure that cookie generation -and verification callbacks have been set up using -SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() -respectively. - -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() -B<only> supports ClientHellos that fit inside a single datagram. - -=head1 RETURN VALUES - -From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance -the B<peer> value will be filled in and the B<ssl> object set up ready to -continue the handshake. - -A return value of 0 indicates a non-fatal error. This could (for -example) be because of non-blocking IO, 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. Any old errors on the -error queue will be cleared in the subsequent call. - -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. - -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. - -=head1 SEE ALSO - -L<SSL_get_error(3)>, L<SSL_accept(3)>, -L<ssl(3)>, L<bio(3)> - -=head1 HISTORY - -DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer" -also changed in OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut |