fixes #3 TLS transport

This introduces a new transport (compatible with the TLS
transport from mangos), using TLS v1.2.

To use the new transport, you must have the mbed TLS library
available on your system (Xenial libmbedtls-dev).  You can use
version 2.x or newer -- 1.3.x and PolarSSL versions are not
supported.

You enable the TLS transport with -DNNG_TRANSPORT_TLS=ON in the CMake
configuration.

You must configure the server certificate by default, and this can only
be done using nng options.  See the nng_tls man page for details.

This work is experimental, and was made possible by Capitar IT Group BV,
and Staysail Systems, Inc.

1 files changed, 242 insertions, 0 deletions

diff --git a/docs/nng_tls.adoc b/docs/nng_tls.adoc
new file mode 100644
index 00000000..34221f6b
--- /dev/null
+++ b/docs/nng_tls.adoc
@@ -0,0 +1,242 @@
+nng_tls(7)
+==========
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
+            Copyright 2017 Staysail Systems, Inc. <info@staysail.tech> \
+            Copyright 2017 Capitar IT Group BV <info@capitar.com> \
+            This software is supplied under the terms of the MIT License, a \
+            copy of which should be located in the distribution where this \
+            file was obtained (LICENSE.txt).  A copy of the license may also \
+            be found online at https://opensource.org/licenses/MIT.
+
+NAME
+----
+nng_tls - TLS transport for nng
+
+SYNOPSIS
+--------
+
+[source,c]
+----------
+#include <nng/transport/tls/tls.h>
+
+int nng_tls_register(void);
+----------
+
+DESCRIPTION
+-----------
+
+The _nng_tls_ transport provides communication support between
+_nng_ sockets across a TCP/IP network using 
+https://tools.ietf.org/html/rfc5246[TLS v1.2] on top of
+https://tools.ietf.org/html/rfc793[TCP].  Both IPv4 and IPv6
+are supported when the underlying platform also supports it.
+
+The protocol details are documented in
+http://nanomsg.org/rfcs/sp-tls-v1.html[TLS Mapping for Scalability Protocols].
+
+Registration
+~~~~~~~~~~~~
+
+Depending upon how the library was built, it may be necessary to
+register the transport by calling `nng_tls_register`.  This function
+returns zero on success, or an nng error value if the transport
+cannot be initialized for any reason.
+
+Availability
+~~~~~~~~~~~~
+
+The _tls_ transport depends on the use of an external library.
+As of this writing, https://tls.mbed.org/[mbed TLS] is required.
+
+TIP: Applications may need to add this library (or libraries) to
+their link line, particularly when using a statically built
+_nng_ library.
+
+NOTE: The mbed TLS library uses different licensing terms than
+_nng_ itself; as of this writing it is offered under either
+https://opensource.org/licenses/Apache-2.0[Apache License 2.0] or
+https://opensource.org/licenses/gpl-license[GNU GPL] terms.
+You are responsible for understanding and adhering to the
+license terms of any libraries you make use of.
+
+URI Format
+~~~~~~~~~~
+
+This transport uses URIs using the scheme `tls://`, followed by
+an IP address or hostname, followed by a colon and finally a
+TCP port number.  For example, to contact port 4433 on the localhost
+either of the following URIs could be used: `tls://127.0.0.1:4433` or
+`tcp://localhost:4433`.
+
+When specifying IPv6 addresses, the address must be enclosed in
+square brackets (`[]`) to avoid confusion with the final colon
+separating the port.
+
+For example, the same port 4433 on the IPv6 loopback address ('::1') would
+be specified as `tcp://[::1]:4433`.
+
+NOTE: When using symbolic names, the name is resolved when the
+name is first used. _nng_ won't become aware of changes in the
+name resolution until restart,
+usually.footnote:[This is a bug and will likely be fixed in the future.]
+
+TIP: Certificate validation generally works when using names
+rather than IP addresses. This transport automatically
+uses the name supplied in the URL when validating the
+certificate supplied by the server.
+
+The special value of 0 (`INADDR_ANY`) can be used for a listener
+to indicate that it should listen on all interfaces on the host.
+A short-hand for this form is to either omit the address, or specify
+the asterisk (`*`) character.  For example, the following three
+URIs are all equivalent, and could be used to listen to port 9999
+on the host:
+
+  1. `tls://0.0.0.0:9999`
+  2. `tls://*:9999`
+  3. `tls://:9999`
+
+The entire URI must be less than `NNG_MAXADDRLEN` bytes long.
+
+Socket Address
+~~~~~~~~~~~~~~
+
+When using an `nng_sockaddr` structure, the actual structure is either
+of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6).
+These are `struct` types with the following definitions:
+
+[source,c]
+--------
+#define NNG_AF_INET    3 <1>
+#define NNG_AF_INET6   4
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... <2>
+    uint16_t sa_family;                 // must be NNG_AF_INET
+    uint16_t sa_port;                   // TCP port number
+    uint32_t sa_addr;
+    // ...
+} nng_sockaddr_in;
+
+typedef struct {
+    // ... <2>
+    uint16_t sa_family;                 // must be NNG_AF_INET6
+    uint16_t sa_port;                   // TCP port number
+    uint8_t  sa_addr[16];
+    // ...
+} nng_sockaddr_in6;
+--------
+<1> The values of these macros may change, so applications
+should avoid depending upon their values and instead use them symbolically.
+<2> Other members may be present, but only those listed here
+are suitable for application use.
+
+The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`.
+The `sa_port` and `sa_addr` are the TCP port number and address, both in
+network byte order (most significant byte is first).
+
+X.509 Formats
+~~~~~~~~~~~~~
+
+The _tls_ transport supports certificates and key material provided
+in either PEM or DER encoding.  When using PEM format data, the
+encoding must be at the start of the data, with no intervening
+content.  Furthermore, PEM encoded objects may have a terminating
+NUL byte, which will be ignored if present.
+
+Transport Options
+~~~~~~~~~~~~~~~~~
+
+The following transport options are available. Note that
+setting these must be done before the transport is started.
+
+`NNG_OPT_TLS_CA_CERT`::
+
+This is a write-only binay object containing a certificate
+chain, consisting of one or more X.509 certificates encoded in
+either PEM or DER format.  These certificates are used to
+validate the peer.  If multiple certificates are presented,
+they must be in the same format.
+
+`NNG_OPT_TLS_CRL`::
+
+This is a write-only CRL (revocation list) in X.509 format,
+specifying certificates which may not be used.
+
+`NNG_OPT_TLS_CERT`::
+
+This is an X.509 certificate containing the peers
+own public credentials.  For servers, this option may be supplied
+multiple times, in order to specify multiple certificates
+in order to offer different algorithms.  Clients can only
+have a single certificate.
+
+`NNG_OPT_TLS_PRIVATE_KEY`::
+
+This is an encoded private key, corresponding to the most
+recently established certificate.
+
+`NNG_OPT_TLS_PRIVATE_KEY_PASSWORD`::
+
+This is a string (NUL byte terminated) used to decrypt the
+most recently supplied private key, if the private key
+is encrypted.  (If the private key is not encrypted, then
+this option need not be supplied.) 
+
+`NNG_OPT_TLS_AUTH_MODE`::
+
+This is a write only integer, indicating whether the
+peer should be authenticated.  It can take one of the
+following values:
++
+[cols="1,2"]
+|===
+
+| `nng_tls_auth_mode_none`
+| No authentication of the peer is performed.
+
+| `nng_tls_auth_mode_optional`
+| The peer certificate is checked if presented, but is not required to be valid or present.
+
+| `nng_tls_auth_mode_required`
+| The peer certificate must be present and valid.
+|===
++
+The default is `nng_tls_auth_mode_required` for
+clients (meaning the server must present a valid
+certificate) and `nng_tls_auth_mode_none` for
+servers (meaning any client may connect).
++
+TIP: For TLS client authentication, set this to
+`nng_auth_mode_required` and set the value
+of `NNG_OPT_TLS_CA_CERT` to a certificate corresponding
+to your own Certificate Authority.
+
+`NNG_OPT_TLS_AUTH_VERIFIED`::
+
+This is a read-only boolean option available only for
+pipes, indicating whether the peer certificate was
+valdiated or not.  This is only set when the pipe
+has completed the handshake with the peer (which always
+occurs before exchanging data), and will only be set
+if the `NNG_OPT_TLS_AUTH_MODE` option is set to
+`nng_tls_auth_mode_optional` or `nng_tls_auth_mode_required`.
+
+SEE ALSO
+--------
+<<nng.adoc#,nng(7)>>
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:info@staysail.tech[Staysail Systems, Inc.] +
+Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].