From 6a50035b242b972c1d9b659ba63e037a0a8afe71 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Fri, 29 Dec 2017 14:21:20 -0800
Subject: 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.
---
 docs/nng_ws.adoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

(limited to 'docs/nng_ws.adoc')

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
 ---------
-- 
cgit v1.2.3-70-g09d2

