From 6a50035b242b972c1d9b659ba63e037a0a8afe71 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore 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_tls.adoc | 12 ++++++++++++ docs/nng_ws.adoc | 20 ++++++++++++++++++++ 2 files changed, 32 insertions(+) (limited to 'docs') 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 -------- <> +<> 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 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 -------- <> +<> COPYRIGHT --------- -- cgit v1.2.3-70-g09d2