From 0d01f90c1335701056a00536c40e6975abd289d3 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 21 Nov 2016 13:52:28 +0000 Subject: Import the DTLSv1_listen(3) manual from OpenSSL, excluding interface changes that don't apply to LibreSSL, except that i left the confusing discussion of RETURN VALUES completely unchanged, to warn users that this is a mess: OpenSSL first published this interface, then later changed its syntax and semantics in multiple ways. --- src/lib/libssl/man/DTLSv1_listen.3 | 186 +++++++++++++++++++++++++++++++++++++ src/lib/libssl/man/Makefile | 3 +- 2 files changed, 188 insertions(+), 1 deletion(-) create mode 100644 src/lib/libssl/man/DTLSv1_listen.3 (limited to 'src') diff --git a/src/lib/libssl/man/DTLSv1_listen.3 b/src/lib/libssl/man/DTLSv1_listen.3 new file mode 100644 index 0000000000..9ecd5589b3 --- /dev/null +++ b/src/lib/libssl/man/DTLSv1_listen.3 @@ -0,0 +1,186 @@ +.\" $OpenBSD: DTLSv1_listen.3,v 1.1 2016/11/21 13:52:28 schwarze Exp $ +.\" OpenSSL 7795475f Dec 18 13:18:31 2015 -0500 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: November 21 2016 $ +.Dt DTLSV1_LISTEN 3 +.Os +.Sh NAME +.Nm DTLSv1_listen +.Nd listen for incoming DTLS connections +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo DTLSv1_listen +.Fa "SSL *ssl" +.Fa "struct sockaddr *peer" +.Fc +.Sh DESCRIPTION +.Fn DTLSv1_listen +listens for new incoming DTLS connections. +If a ClientHello is received that does not contain a cookie, then +.Fn 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 +.Xr SSL_accept 3 ) . +.Pp +.Fn DTLSv1_listen +is currently implemented as a macro. +.Pp +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. +.Pp +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. +.Pp +OpenSSL implements this capability via the +.Fn DTLSv1_listen +function. +The +.Fa ssl +parameter should be a newly allocated +.Vt SSL +object with its read and write BIOs set, in the same way as might +be done for a call to +.Xr SSL_accept 3 . +Typically the read BIO will be in an "unconnected" state and thus +capable of receiving messages from any peer. +.Pp +When a ClientHello is received that contains a cookie that has been +verified, then +.Fn DTLSv1_listen +will return with the +.Fa ssl +parameter updated into a state where the handshake can be continued by a +call to (for example) +.Xr SSL_accept 3 . +Additionally the +.Vt struct sockaddr +pointed to by +.Fa peer +will be filled in with details of the peer that sent the ClientHello. +It is the calling code's responsibility to ensure that the +.Fa peer +location is sufficiently large to accommodate the addressing scheme in use. +For example this might be done by allocating space for a +.Vt struct sockaddr_storage +and casting the pointer to it to a +.Vt struct sockaddr * +for the call to +.Fn DTLSv1_listen . +Typically user code is expected to "connect" the underlying socket +to the peer and continue the handshake in a connected state. +.Pp +Prior to calling +.Fn DTLSv1_listen +user code must ensure that cookie generation and verification callbacks +have been set up using +.Fn SSL_CTX_set_cookie_generate_cb +and +.Fn SSL_CTX_set_cookie_verify_cb +respectively. +.Pp +Since +.Fn 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 +.Fn DTLSv1_listen +only supports ClientHellos that fit inside a single datagram. +.Sh RETURN VALUES +From OpenSSL 1.1.0 a return value of >= 1 indicates success. +In this instance the +.Fa peer +value will be filled in and the +.Fa ssl +object set up ready to continue the handshake. +.Pp +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 +.Fn DTLSv1_listen +in the event of a non-fatal error. +Any old errors on the error queue will be cleared in the subsequent +call. +.Pp +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. +.Pp +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. +.Sh SEE ALSO +.Xr BIO 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_get_error 3 +.Sh HISTORY +.Fn DTLSv1_listen +was added in OpenSSL 0.9.8. diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile index 76afab5718..f02d3da424 100644 --- a/src/lib/libssl/man/Makefile +++ b/src/lib/libssl/man/Makefile @@ -1,8 +1,9 @@ -# $OpenBSD: Makefile,v 1.36 2016/11/05 15:32:19 schwarze Exp $ +# $OpenBSD: Makefile,v 1.37 2016/11/21 13:52:28 schwarze Exp $ .include MAN = BIO_f_ssl.3 \ + DTLSv1_listen.3 \ SSL_CIPHER_get_name.3 \ SSL_COMP_add_compression_method.3 \ SSL_CTX_add_extra_chain_cert.3 \ -- cgit v1.2.3-55-g6feb