fixes #166 Websocket TLS mapping

This introduces the wss:// scheme, which is available and works like
the ws:// scheme if TLS is enabled in the library.

The library modularization is refactored somewhat, to make it easier
to use.  There is now a single NNG_ENABLE_TLS that enables TLS support
under the hood.

This also adds a new option for the TLS transport, NNG_OPT_TLS_CONFIG
(and a similar one for WSS, NNG_OPT_TLS_WSS_CONFIG) that offer access
to the underlying TLS configuration object, which now has a public API
to go with it as well.

Note that it is also possible to use pure HTTPS using the *private*
API, which will be exposed in a public form soon.

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/nng_tls.adoc b/docs/nng_tls.adoc
index e6eafdd5..a6737d01 100644
--- a/docs/nng_tls.adoc
+++ b/docs/nng_tls.adoc
@@ -157,6 +157,17 @@ Transport Options
 The following transport options are available. Note that
 setting these must be done before the transport is started.
 
+`NNG_OPT_TLS_CONFIG`::
+
+This option is used to set or obtain the TLS configuration
+object (type `nng_tls_config *`), which is passed as a pointer.
+Setting this option adds a reference to the object; obtaining the
+object pointer does not.  (Therefore when retrieving this option,
+care must be taken not to access it after the endpoint is closed.)
+
+Note that configuration object is not modifiable once it has been
+used in a running TLS stream.
+
 `NNG_OPT_TLS_CA_CERT`::
 
 This is a write-only binay object containing a certificate
@@ -232,6 +243,7 @@ if the `NNG_OPT_TLS_AUTH_MODE` option is set to
 SEE ALSO
 --------
 <<nng.adoc#,nng(7)>>
+<<nng_tls_init#,nng_tls_init(3)>>
 
 COPYRIGHT
 ---------
diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc
index 8073e158..b6185757 100644
--- a/docs/nng_ws.adoc
+++ b/docs/nng_ws.adoc
@@ -25,6 +25,7 @@ SYNOPSIS
 #include <nng/transport/websocket/ws.h>
 
 int nng_ws_register(void);
+int nng_wss_register(void);
 ----------
 
 DESCRIPTION
@@ -46,6 +47,11 @@ register the transport by calling `nng_ws_register`.  This function
 returns zero on success, or an nng error value if the transport
 cannot be initialized for any reason.
 
+If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) 
+can be used as well, but the secure transport may have to be registered using
+the `nng_wss_register` function.  (Note that this function will not be
+present if TLS support was not enabled in the library.)
+
 URI Format
 ~~~~~~~~~~
 
@@ -57,6 +63,10 @@ a path of `/` is assumed.)
 For example, the URI `ws://localhost/app/pubsub` would use
 port 80 on localhost, with the path `/app/pubsub`.
 
+Secure WebSockets (if enabled) use the scheme `wss://`, and the default
+TCP port number of 443.  Otherwise the format is the same as for regular
+WebSockets.
+
 When specifying IPv6 addresses, the address must be enclosed in
 square brackets (`[]`) to avoid confusion with the final colon
 separating the port.
@@ -141,6 +151,15 @@ by CRLF sequences, that can be used to add furthe headers to the
 HTTP response sent when connecting.  This option can be set on listeners,
 and retrieved from pipes.
 
+`NNG_OPT_WSS_TLS_CONFIG`::
+
+This option is used on an endpoint to access the underlying TLS
+configuration object.  The value is of type `nng_tls_config *`.
+Note that attempts to set this object may fail on a listener if
+the server is already running.  Furthermore, attempts to modify the
+configuration object will fail if it is already in active use.
+This object is only available for `wss://` endpoints.
+
 // We should also look at a hook mechanism for listeners. Probably this could
 // look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer
 // along the lines of int hook(void *, char *req_headers, char **res_headers),
@@ -150,6 +169,7 @@ and retrieved from pipes.
 SEE ALSO
 --------
 <<nng.adoc#,nng(7)>>
+<<nng_tls_init#,nng_tls_init(3)>>
 
 COPYRIGHT
 ---------