1.\" $OpenBSD: DTLSv1_listen.3,v 1.4 2018/03/27 17:35:50 schwarze Exp $ 2.\" OpenSSL 7795475f Dec 18 13:18:31 2015 -0500 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: March 27 2018 $ 52.Dt DTLSV1_LISTEN 3 53.Os 54.Sh NAME 55.Nm DTLSv1_listen 56.Nd listen for incoming DTLS connections 57.Sh SYNOPSIS 58.In openssl/ssl.h 59.Ft int 60.Fo DTLSv1_listen 61.Fa "SSL *ssl" 62.Fa "struct sockaddr *peer" 63.Fc 64.Sh DESCRIPTION 65.Fn DTLSv1_listen 66listens for new incoming DTLS connections. 67If a ClientHello is received that does not contain a cookie, then 68.Fn DTLSv1_listen 69responds with a HelloVerifyRequest. 70If a ClientHello is received with a cookie that is verified, then 71control is returned to user code to enable the handshake to be 72completed (for example by using 73.Xr SSL_accept 3 ) . 74.Pp 75.Fn DTLSv1_listen 76is currently implemented as a macro. 77.Pp 78Datagram based protocols can be susceptible to Denial of Service 79attacks. 80A DTLS attacker could, for example, submit a series of handshake 81initiation requests that cause the server to allocate state (and 82possibly perform cryptographic operations) thus consuming server 83resources. 84The attacker could also (with UDP) quite simply forge the source IP 85address in such an attack. 86.Pp 87As a counter measure to that DTLS includes a stateless cookie mechanism. 88The idea is that when a client attempts to connect to a server it sends 89a ClientHello message. 90The server responds with a HelloVerifyRequest which contains a unique 91cookie. 92The client then resends the ClientHello, but this time includes the 93cookie in the message thus proving that the client is capable of 94receiving messages sent to that address. 95All of this can be done by the server without allocating any state, and 96thus without consuming expensive resources. 97.Pp 98OpenSSL implements this capability via the 99.Fn DTLSv1_listen 100function. 101The 102.Fa ssl 103parameter should be a newly allocated 104.Vt SSL 105object with its read and write BIOs set, in the same way as might 106be done for a call to 107.Xr SSL_accept 3 . 108Typically the read BIO will be in an "unconnected" state and thus 109capable of receiving messages from any peer. 110.Pp 111When a ClientHello is received that contains a cookie that has been 112verified, then 113.Fn DTLSv1_listen 114will return with the 115.Fa ssl 116parameter updated into a state where the handshake can be continued by a 117call to (for example) 118.Xr SSL_accept 3 . 119Additionally the 120.Vt struct sockaddr 121pointed to by 122.Fa peer 123will be filled in with details of the peer that sent the ClientHello. 124It is the calling code's responsibility to ensure that the 125.Fa peer 126location is sufficiently large to accommodate the addressing scheme in use. 127For example this might be done by allocating space for a 128.Vt struct sockaddr_storage 129and casting the pointer to it to a 130.Vt struct sockaddr * 131for the call to 132.Fn DTLSv1_listen . 133Typically user code is expected to "connect" the underlying socket 134to the peer and continue the handshake in a connected state. 135.Pp 136Prior to calling 137.Fn DTLSv1_listen 138user code must ensure that cookie generation and verification callbacks 139have been set up using 140.Fn SSL_CTX_set_cookie_generate_cb 141and 142.Fn SSL_CTX_set_cookie_verify_cb 143respectively. 144.Pp 145Since 146.Fn DTLSv1_listen 147operates entirely statelessly whilst processing incoming ClientHellos, 148it is unable to process fragmented messages (since this would require 149the allocation of state). 150An implication of this is that 151.Fn DTLSv1_listen 152only supports ClientHellos that fit inside a single datagram. 153.Sh RETURN VALUES 154From OpenSSL 1.1.0 a return value of >= 1 indicates success. 155In this instance the 156.Fa peer 157value will be filled in and the 158.Fa ssl 159object set up ready to continue the handshake. 160.Pp 161A return value of 0 indicates a non-fatal error. 162This could (for example) be because of non-blocking IO, or some invalid 163message having been received from a peer. 164Errors may be placed on the OpenSSL error queue with further information 165if appropriate. 166Typically user code is expected to retry the call to 167.Fn DTLSv1_listen 168in the event of a non-fatal error. 169Any old errors on the error queue will be cleared in the subsequent 170call. 171.Pp 172A return value of <0 indicates a fatal error. 173This could (for example) be because of a failure to allocate sufficient 174memory for the operation. 175.Pp 176Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return 177codes <= 0 (in typical implementations user code treats all errors as 178non-fatal), whilst return codes >0 indicate success. 179.Sh SEE ALSO 180.Xr BIO_new 3 , 181.Xr ssl 3 , 182.Xr SSL_accept 3 , 183.Xr SSL_get_error 3 184.Sh HISTORY 185.Fn DTLSv1_listen 186first appeared in OpenSSL 0.9.8m and has been available since 187.Ox 4.9 . 188