secure/lib/libcrypto/man/DTLSv1_listen.3

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