Summary
-------

Define an API for Datagram Transport Layer Security (DTLS) version 1.0
([RFC 4347][rfc4347]) and 1.2 ([RFC 6347][rfc6347]).

[rfc4347]: http://tools.ietf.org/html/rfc4347
[rfc6347]: http://tools.ietf.org/html/rfc6347


Non-Goals
---------

  1. It is not a goal to support transport-specific interfaces (for
     example, DTLS for `DatagramSocket`).

  2. It is not a goal to support PMTU discovery.


Success Metrics
---------------

The implementation, in both client and server modes, must interoperate
successfully with at least two other DTLS implementations.


Motivation
----------

It is important to support DTLS to satisfy secure-transport requirements
for the increasing number of datagram-compatible applications.
[RFC 4347][rfc4347] lists a number of reasons why TLS is not sufficient for
these types of applications:

  - "TLS is the most widely deployed protocol for securing network
    traffic. ... However, TLS must run over a reliable transport
    channel---typically TCP.  It therefore cannot be used to secure
    unreliable datagram traffic."

  - "... an increasing number of application layer protocols have been
    designed that use UDP transport.  In particular, protocols such as
    the Session Initiation Protocol (SIP) and electronic gaming protocols
    are increasingly popular."

  - "In many cases, the most desirable way to secure client/server
    applications would be to use TLS; However, the requirement for
    datagram semantics automatically prohibits use of TLS.  Thus, a
    datagram-compatible variant of TLS is very desirable."

Protocols that support DTLS include, but are not limited, to:

  - [RFC 5238][rfc5238], Datagram Transport Layer Security (DTLS) over
    the Datagram Congestion Control Protocol (DCCP)

  - [RFC 6083][rfc6083], Datagram Transport Layer Security (DTLS) for
    Stream Control Transmission Protocol (SCTP)

  - [RFC 5764][rfc5764], Datagram Transport Layer Security (DTLS)
    Extension to Establish Keys for the Secure Real-time Transport
    Protocol (SRTP)

  - [RFC 7252][rfc7252], Constrained Application Protocol (CoAP)

Google Chrome and Firefox now support DTLS-SRTP for Web Real-Time
Communication (WebRTC).  DTLS version 1.0 and 1.2 are supported by the
major TLS vendors and implementations including OpenSSL, GnuTLS, and
Microsoft SChannel.


Description
-----------

We expect the DTLS API and implementation to be fairly small.  The new
API should be transport-independent and similar to
`javax.net.ssl.SSLEngine`.  Further details on the API will be added here
as the work progresses.  Some initial design considerations are as
follows:

  1. The DTLS API and implementation will not manage read timeouts.  It
     will be the responsibility of the application to determine an
     appropriate timeout value and when and how to trigger the timeout
     event.

  2. A new API will likely be added to set the maximum application
     datagram size (PMTU minus the DTLS per-record overhead).  If the
     size is not specified explicitly, however, then the DTLS
     implementation should adjust the size automatically.  If a fragment
     is lost two or three times, the implementation may reduce the size
     of the maximum application datagram size until it is small enough.

  3. The DTLS implementation should consume or produce at most one TLS
     record for each unwrap or wrap operation, so that the record can be
     delivered in the datagram layer individually or can be reassembled
     more easily if the delivery is out of order.

  4. It is the application's responsibility to assemble the out-of-order
     application data accordingly if necessary. The DTLS API should
     provide access to the application data in each DTLS message.


[rfc5238]: http://tools.ietf.org/html/rfc5238
[rfc5764]: http://tools.ietf.org/html/rfc5764
[rfc6083]: http://tools.ietf.org/html/rfc6083
[rfc7252]: http://tools.ietf.org/html/rfc7252