1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
.\" $OpenBSD: DTLSv1_listen.3,v 1.4 2018/03/27 17:35:50 schwarze Exp $
.\" OpenSSL 7795475f Dec 18 13:18:31 2015 -0500
.\"
.\" This file was written by Matt Caswell <matt@openssl.org>.
.\" 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: March 27 2018 $
.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_new 3 ,
.Xr ssl 3 ,
.Xr SSL_accept 3 ,
.Xr SSL_get_error 3
.Sh HISTORY
.Fn DTLSv1_listen
first appeared in OpenSSL 0.9.8m and has been available since
.Ox 4.9 .
|
