doc/man3/DTLSv1_listen.pod

   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, BIO_ADDR *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<BIO_ADDR> pointed to by B<peer> will be filled in with
  47 details of the peer that sent the ClientHello. If the underlying BIO is unable
  48 to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not
  49 support this), then B<*peer> will be cleared and the family set to AF_UNSPEC.
  50 Typically user code is expected to "connect" the underlying socket to the peer
  51 and continue the handshake in a connected state.
  52
  53 Prior to calling DTLSv1_listen() user code must ensure that cookie generation
  54 and verification callbacks have been set up using
  55 SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
  56 respectively.
  57
  58 Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
  59 ClientHellos it is unable to process fragmented messages (since this would
  60 require the allocation of state). An implication of this is that DTLSv1_listen()
  61 B<only> supports ClientHellos that fit inside a single datagram.
  62
  63 =head1 RETURN VALUES
  64
  65 From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance
  66 the B<peer> value will be filled in and the B<ssl> object set up ready to
  67 continue the handshake.
  68
  69 A return value of 0 indicates a non-fatal error. This could (for
  70 example) be because of non-blocking IO, or some invalid message having been
  71 received from a peer. Errors may be placed on the OpenSSL error queue with
  72 further information if appropriate. Typically user code is expected to retry the
  73 call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the
  74 error queue will be cleared in the subsequent call.
  75
  76 A return value of <0 indicates a fatal error. This could (for example) be
  77 because of a failure to allocate sufficient memory for the operation.
  78
  79 Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes
  80 <= 0 (in typical implementations user code treats all errors as non-fatal),
  81 whilst return codes >0 indicate success.
  82
  83 =head1 SEE ALSO
  84
  85 L<SSL_get_error(3)>, L<SSL_accept(3)>,
  86 L<ssl(3)>, L<bio(3)>
  87
  88 =head1 HISTORY
  89
  90 DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer"
  91 also changed in OpenSSL 1.1.0.
  92
  93 =head1 COPYRIGHT
  94
  95 Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
  96
  97 Licensed under the OpenSSL license (the "License").  You may not use
  98 this file except in compliance with the License.  You can obtain a copy
  99 in the file LICENSE in the source distribution or at
 100 L<https://www.openssl.org/source/license.html>.
 101
 102 =cut