secure/lib/libcrypto/man/DTLSv1_listen.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "DTLSV1_LISTEN 3"
 136 .TH DTLSV1_LISTEN 3 "2019-02-26" "1.1.1b" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_stateless, DTLSv1_listen \&\- Statelessly listen for incoming connections
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_stateless(SSL *s);
 149 \& int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 \&\fBSSL_stateless()\fR statelessly listens for new incoming TLSv1.3 connections.
 154 \&\fBDTLSv1_listen()\fR statelessly listens for new incoming \s-1DTLS\s0 connections. If a
 155 ClientHello is received that does not contain a cookie, then they respond with a
 156 request for a new ClientHello that does contain a cookie. If a ClientHello is
 157 received with a cookie that is verified then the function returns in order to
 158 enable the handshake to be completed (for example by using \fBSSL_accept()\fR).
 159 .SH "NOTES"
 160 .IX Header "NOTES"
 161 Some transport protocols (such as \s-1UDP\s0) can be susceptible to amplification
 162 attacks. Unlike \s-1TCP\s0 there is no initial connection setup in \s-1UDP\s0 that
 163 validates that the client can actually receive messages on its advertised source
 164 address. An attacker could forge its source \s-1IP\s0 address and then send handshake
 165 initiation messages to the server. The server would then send its response to
 166 the forged source \s-1IP.\s0 If the response messages are larger than the original
 167 message then the amplification attack has succeeded.
 168 .PP
 169 If \s-1DTLS\s0 is used over \s-1UDP\s0 (or any datagram based protocol that does not validate
 170 the source \s-1IP\s0) then it is susceptible to this type of attack. TLSv1.3 is
 171 designed to operate over a stream-based transport protocol (such as \s-1TCP\s0).
 172 If \s-1TCP\s0 is being used then there is no need to use \fBSSL_stateless()\fR. However some
 173 stream-based transport protocols (e.g. \s-1QUIC\s0) may not validate the source
 174 address. In this case a TLSv1.3 application would be susceptible to this attack.
 175 .PP
 176 As a countermeasure to this issue TLSv1.3 and \s-1DTLS\s0 include a stateless cookie
 177 mechanism. The idea is that when a client attempts to connect to a server it
 178 sends a ClientHello message. The server responds with a HelloRetryRequest (in
 179 TLSv1.3) or a HelloVerifyRequest (in \s-1DTLS\s0) which contains a unique cookie. The
 180 client then resends the ClientHello, but this time includes the cookie in the
 181 message thus proving that the client is capable of receiving messages sent to
 182 that address. All of this can be done by the server without allocating any
 183 state, and thus without consuming expensive resources.
 184 .PP
 185 OpenSSL implements this capability via the \fBSSL_stateless()\fR and \fBDTLSv1_listen()\fR
 186 functions. The \fBssl\fR parameter should be a newly allocated \s-1SSL\s0 object with its
 187 read and write BIOs set, in the same way as might be done for a call to
 188 \&\fBSSL_accept()\fR. Typically, for \s-1DTLS,\s0 the read \s-1BIO\s0 will be in an \*(L"unconnected\*(R"
 189 state and thus capable of receiving messages from any peer.
 190 .PP
 191 When a ClientHello is received that contains a cookie that has been verified,
 192 then these functions will return with the \fBssl\fR parameter updated into a state
 193 where the handshake can be continued by a call to (for example) \fBSSL_accept()\fR.
 194 Additionally, for \fBDTLSv1_listen()\fR, the \fB\s-1BIO_ADDR\s0\fR pointed to by \fBpeer\fR will be
 195 filled in with details of the peer that sent the ClientHello. If the underlying
 196 \&\s-1BIO\s0 is unable to obtain the \fB\s-1BIO_ADDR\s0\fR of the peer (for example because the \s-1BIO\s0
 197 does not support this), then \fB*peer\fR will be cleared and the family set to
 198 \&\s-1AF_UNSPEC.\s0 Typically user code is expected to \*(L"connect\*(R" the underlying socket to
 199 the peer and continue the handshake in a connected state.
 200 .PP
 201 Prior to calling \fBDTLSv1_listen()\fR user code must ensure that cookie generation
 202 and verification callbacks have been set up using
 203 \&\fBSSL_CTX_set_cookie_generate_cb()\fR and \fBSSL_CTX_set_cookie_verify_cb()\fR
 204 respectively. For \fBSSL_stateless()\fR, \fBSSL_CTX_set_stateless_cookie_generate_cb()\fR
 205 and \fBSSL_CTX_set_stateless_cookie_verify_cb()\fR must be used instead.
 206 .PP
 207 Since \fBDTLSv1_listen()\fR operates entirely statelessly whilst processing incoming
 208 ClientHellos it is unable to process fragmented messages (since this would
 209 require the allocation of state). An implication of this is that \fBDTLSv1_listen()\fR
 210 \&\fBonly\fR supports ClientHellos that fit inside a single datagram.
 211 .PP
 212 For \fBSSL_stateless()\fR if an entire ClientHello message cannot be read without the
 213 \&\*(L"read\*(R" \s-1BIO\s0 becoming empty then the \fBSSL_stateless()\fR call will fail. It is the
 214 application's responsibility to ensure that data read from the \*(L"read\*(R" \s-1BIO\s0 during
 215 a single \fBSSL_stateless()\fR call is all from the same peer.
 216 .PP
 217 \&\fBSSL_stateless()\fR will fail (with a 0 return value) if some \s-1TLS\s0 version less than
 218 TLSv1.3 is used.
 219 .PP
 220 Both \fBSSL_stateless()\fR and \fBDTLSv1_listen()\fR will clear the error queue when they
 221 start.
 222 .SH "RETURN VALUES"
 223 .IX Header "RETURN VALUES"
 224 For \fBSSL_stateless()\fR a return value of 1 indicates success and the \fBssl\fR object
 225 will be set up ready to continue the handshake. A return value of 0 or \-1
 226 indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value
 227 of \-1 indicates any other error. User code may retry the \fBSSL_stateless()\fR call.
 228 .PP
 229 For \fBDTLSv1_listen()\fR a return value of >= 1 indicates success. The \fBssl\fR object
 230 will be set up ready to continue the handshake.  the \fBpeer\fR value will also be
 231 filled in.
 232 .PP
 233 A return value of 0 indicates a non-fatal error. This could (for
 234 example) be because of non-blocking \s-1IO,\s0 or some invalid message having been
 235 received from a peer. Errors may be placed on the OpenSSL error queue with
 236 further information if appropriate. Typically user code is expected to retry the
 237 call to \fBDTLSv1_listen()\fR in the event of a non-fatal error.
 238 .PP
 239 A return value of <0 indicates a fatal error. This could (for example) be
 240 because of a failure to allocate sufficient memory for the operation.
 241 .PP
 242 For \fBDTLSv1_listen()\fR, prior to OpenSSL 1.1.0, fatal and non-fatal errors both
 243 produce return codes <= 0 (in typical implementations user code treats all
 244 errors as non-fatal), whilst return codes >0 indicate success.
 245 .SH "SEE ALSO"
 246 .IX Header "SEE ALSO"
 247 \&\fBSSL_get_error\fR\|(3), \fBSSL_accept\fR\|(3),
 248 \&\fBssl\fR\|(7), \fBbio\fR\|(7)
 249 .SH "HISTORY"
 250 .IX Header "HISTORY"
 251 The \fBSSL_stateless()\fR function was added in OpenSSL 1.1.1.
 252 .PP
 253 The \fBDTLSv1_listen()\fR return codes were clarified in OpenSSL 1.1.0.
 254 The type of \*(L"peer\*(R" also changed in OpenSSL 1.1.0.
 255 .SH "COPYRIGHT"
 256 .IX Header "COPYRIGHT"
 257 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
 258 .PP
 259 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 260 this file except in compliance with the License.  You can obtain a copy
 261 in the file \s-1LICENSE\s0 in the source distribution or at
 262 <https://www.openssl.org/source/license.html>.