]>
Commit | Line | Data |
---|---|---|
ca7256fb MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | DTLSv1_listen - listen for incoming DTLS connections. | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int DTLSv1_listen(SSL *ssl, struct sockaddr *peer); | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
15 | DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is | |
16 | received that does not contain a cookie, then DTLSv1_listen() responds with a | |
17 | HelloVerifyRequest. If a ClientHello is received with a cookie that is verified | |
18 | then control is returned to user code to enable the handshake to be completed | |
19 | (for example by using SSL_accept()). | |
20 | ||
21 | =head1 NOTES | |
22 | ||
23 | Datagram based protocols can be susceptible to Denial of Service attacks. A | |
24 | DTLS attacker could, for example, submit a series of handshake initiation | |
25 | requests that cause the server to allocate state (and possibly perform | |
26 | cryptographic operations) thus consuming server resources. The attacker could | |
27 | also (with UDP) quite simply forge the source IP address in such an attack. | |
28 | ||
29 | As a counter measure to that DTLS includes a stateless cookie mechanism. The | |
30 | idea is that when a client attempts to connect to a server it sends a | |
31 | ClientHello message. The server responds with a HelloVerifyRequest which | |
32 | contains a unique cookie. The client then resends the ClientHello, but this time | |
33 | includes the cookie in the message thus proving that the client is capable of | |
34 | receiving messages sent to that address. All of this can be done by the server | |
35 | without allocating any state, and thus without consuming expensive resources. | |
36 | ||
37 | OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl> | |
38 | parameter should be a newly allocated SSL object with its read and write BIOs | |
39 | set, in the same way as might be done for a call to SSL_accept(). Typically the | |
40 | read BIO will be in an "unconnected" state and thus capable of receiving | |
41 | messages from any peer. | |
42 | ||
43 | When a ClientHello is received that contains a cookie that has been verified, | |
44 | then DTLSv1_listen() will return with the B<ssl> parameter updated into a state | |
45 | where the handshake can be continued by a call to (for example) SSL_accept(). | |
46 | Additionally the B<struct sockaddr> location pointed to by B<peer> will be | |
468f043e MC |
47 | filled in with details of the peer that sent the ClientHello. It is the calling |
48 | code's responsibility to ensure that the B<peer> location is sufficiently large | |
49 | to accommodate the addressing scheme in use. For example this might be done by | |
50 | allocating space for a struct sockaddr_storage and casting the pointer to it to | |
51 | a struct sockaddr * for the call to DTLSv1_listen(). Typically user code is | |
52 | expected to "connect" the underlying socket to the peer and continue the | |
ca7256fb MC |
53 | handshake in a connected state. |
54 | ||
55 | Prior to calling DTLSv1_listen() user code must ensure that cookie generation | |
56 | and verification callbacks have been set up using | |
57 | SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() | |
58 | respectively. | |
59 | ||
60 | Since DTLSv1_listen() operates entirely statelessly whilst processing incoming | |
61 | ClientHellos it is unable to process fragmented messages (since this would | |
62 | require the allocation of state). An implication of this is that DTLSv1_listen() | |
63 | B<only> supports ClientHellos that fit inside a single datagram. | |
64 | ||
65 | =head1 RETURN VALUES | |
66 | ||
67 | From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance | |
68 | the B<peer> value will be filled in and the B<ssl> object set up ready to | |
69 | continue the handshake. | |
70 | ||
71 | A return value of 0 indicates a non-fatal error. This could (for | |
72 | example) be because of non-blocking IO, or some invalid message having been | |
73 | received from a peer. Errors may be placed on the OpenSSL error queue with | |
74 | further information if appropriate. Typically user code is expected to retry the | |
75 | call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the | |
76 | error queue will be cleared in the subsequent call. | |
77 | ||
78 | A return value of <0 indicates a fatal error. This could (for example) be | |
79 | because of a failure to allocate sufficient memory for the operation. | |
80 | ||
81 | Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes | |
82 | <= 0 (in typical implementations user code treats all errors as non-fatal), | |
83 | whilst return codes >0 indicate success. | |
84 | ||
85 | =head1 SEE ALSO | |
86 | ||
87 | L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, | |
88 | L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> | |
89 | ||
90 | =head1 HISTORY | |
91 | ||
a528d4f0 | 92 | DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. |
ca7256fb MC |
93 | |
94 | =cut |