lib/libssl/man/DTLSv1_listen.3

   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
  66 listens for new incoming DTLS connections.
  67 If a ClientHello is received that does not contain a cookie, then
  68 .Fn DTLSv1_listen
  69 responds with a HelloVerifyRequest.
  70 If a ClientHello is received with a cookie that is verified, then
  71 control is returned to user code to enable the handshake to be
  72 completed (for example by using
  73 .Xr SSL_accept 3 ) .
  74 .Pp
  75 .Fn DTLSv1_listen
  76 is currently implemented as a macro.
  77 .Pp
  78 Datagram based protocols can be susceptible to Denial of Service
  79 attacks.
  80 A DTLS attacker could, for example, submit a series of handshake
  81 initiation requests that cause the server to allocate state (and
  82 possibly perform cryptographic operations) thus consuming server
  83 resources.
  84 The attacker could also (with UDP) quite simply forge the source IP
  85 address in such an attack.
  86 .Pp
  87 As a counter measure to that DTLS includes a stateless cookie mechanism.
  88 The idea is that when a client attempts to connect to a server it sends
  89 a ClientHello message.
  90 The server responds with a HelloVerifyRequest which contains a unique
  91 cookie.
  92 The client then resends the ClientHello, but this time includes the
  93 cookie in the message thus proving that the client is capable of
  94 receiving messages sent to that address.
  95 All of this can be done by the server without allocating any state, and
  96 thus without consuming expensive resources.
  97 .Pp
  98 OpenSSL implements this capability via the
  99 .Fn DTLSv1_listen
 100 function.
 101 The
 102 .Fa ssl
 103 parameter should be a newly allocated
 104 .Vt SSL
 105 object with its read and write BIOs set, in the same way as might
 106 be done for a call to
 107 .Xr SSL_accept 3 .
 108 Typically the read BIO will be in an "unconnected" state and thus
 109 capable of receiving messages from any peer.
 110 .Pp
 111 When a ClientHello is received that contains a cookie that has been
 112 verified, then
 113 .Fn DTLSv1_listen
 114 will return with the
 115 .Fa ssl
 116 parameter updated into a state where the handshake can be continued by a
 117 call to (for example)
 118 .Xr SSL_accept 3 .
 119 Additionally the
 120 .Vt struct sockaddr
 121 pointed to by
 122 .Fa peer
 123 will be filled in with details of the peer that sent the ClientHello.
 124 It is the calling code's responsibility to ensure that the
 125 .Fa peer
 126 location is sufficiently large to accommodate the addressing scheme in use.
 127 For example this might be done by allocating space for a
 128 .Vt struct sockaddr_storage
 129 and casting the pointer to it to a
 130 .Vt struct sockaddr *
 131 for the call to
 132 .Fn DTLSv1_listen .
 133 Typically user code is expected to "connect" the underlying socket
 134 to the peer and continue the handshake in a connected state.
 135 .Pp
 136 Prior to calling
 137 .Fn DTLSv1_listen
 138 user code must ensure that cookie generation and verification callbacks
 139 have been set up using
 140 .Fn SSL_CTX_set_cookie_generate_cb
 141 and
 142 .Fn SSL_CTX_set_cookie_verify_cb
 143 respectively.
 144 .Pp
 145 Since
 146 .Fn DTLSv1_listen
 147 operates entirely statelessly whilst processing incoming ClientHellos,
 148 it is unable to process fragmented messages (since this would require
 149 the allocation of state).
 150 An implication of this is that
 151 .Fn DTLSv1_listen
 152 only supports ClientHellos that fit inside a single datagram.
 153 .Sh RETURN VALUES
 154 From OpenSSL 1.1.0 a return value of >= 1 indicates success.
 155 In this instance the
 156 .Fa peer
 157 value will be filled in and the
 158 .Fa ssl
 159 object set up ready to continue the handshake.
 160 .Pp
 161 A return value of 0 indicates a non-fatal error.
 162 This could (for example) be because of non-blocking IO, or some invalid
 163 message having been received from a peer.
 164 Errors may be placed on the OpenSSL error queue with further information
 165 if appropriate.
 166 Typically user code is expected to retry the call to
 167 .Fn DTLSv1_listen
 168 in the event of a non-fatal error.
 169 Any old errors on the error queue will be cleared in the subsequent
 170 call.
 171 .Pp
 172 A return value of <0 indicates a fatal error.
 173 This could (for example) be because of a failure to allocate sufficient
 174 memory for the operation.
 175 .Pp
 176 Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return
 177 codes <= 0 (in typical implementations user code treats all errors as
 178 non-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
 186 first appeared in OpenSSL 0.9.8m and has been available since
 187 .Ox 4.9 .