Description:
-----------

This patch adds experimental DTLS support to nginx stream module.
Please report any feedback to nginx mailing list.


Prerequisites:
-------------

nginx version: mainline 1.13.0
Minimal OpenSSL version: 1.0.2

Recommended OpenSSL version: 1.1
(multiple improvements in DTLS here, DTLS 1.2 support)

Installation instructions:
-------------------------

1. Obtain nginx sources for the mainline branch:

$ wget http://nginx.org/download/nginx-1.13.0.tar.gz

2. Unpack sources and apply the patch:

$ tar xvf nginx-1.13.0.tar.gz
$ cd nginx-1.13.0
$ patch -p1 -i ../nginx-1.13.0-dtls-experimental.diff

3. Build nginx with stream and "stream ssl" modules support, and
   debug enabled:

$ ./configure --with-stream --with-stream_ssl_module --with-debug

$ make

Configuration:
-------------

With the patch, the "listen" directive in the "stream" block now accepts
both "udp" and "ssl" parameters.

The "ssl_protocols" and "proxy_ssl_protocols" directives now accept "DTLSv1"
and "DTLSv1.2" parameters that enable support of corresponding protocols.

DTLS termination:
----------------

stream {
    # please enable debug log
    error_log logs/error.log debug;

    server {
        # add 'udp' and 'ssl' simultaneously to the listen directive
        listen 127.0.0.1:4443 udp ssl;

        # enable DTLSv1 or DTLSv1.2 or both protocols
        ssl_protocols DTLSv1;

        # set up other SSL options as usually
        ssl_certificate ...;
        ssl_certificate_key ...;

        proxy_pass ...;
    }
}

Testing:
-------

Using the "openssl s_client" command you should be able to contact your
non-encrypted UDP backend (for example, netcat):

$ openssl s_client -dtls1 -connect 127.0.0.1:4443 -debug


DTLS to backends:
----------------

stream {
    # please enable debug log
    error_log logs/error.log debug;

    server {
        listen 127.0.0.1:5555 udp;

        # enable SSL to proxy
        proxy_ssl on;
        # enable DTLSv1 or DTLSv1.2 or both protocols
        proxy_ssl_protocols DTLSv1;

        # set up other proxy SSL options as usually
        proxy_ssl_certificate ...;
        proxy_ssl_certificate_key ...;

        # the backend is a DTLS server
        proxy_pass 127.0.0.1:4433;
    }
}

You can start simple DTLS backend server using the "openssl s_server" command:

$ openssl s_server -cert localhost.crt -key localhost.key -dtls1 -accept 4433

============
KNOWN ISSUES
============

1. (D)TLS is a stream protocol, i.e. there are no message boundaries, so
there is NO guaranteed correspondence between the number of DTLS UDP packets
on input and the number of packets sent to backend.

2. There is a race between accepting first packet and creating a per-client
socket used to maintain a session.  When using multiple workers, some
packets may be delivered to worker other than that which started a session
resulting in extra delay (DTLS client is expected to retry after a timeout).