fixes #201 TLS configuration should support files for certificates and keys

This adds support for configuration of TLS websockets using the files
for keys, certificates, and CRLs.  Significant changes to the websocket,
TLS, and HTTP layers were made here.  We now expect TLS configuration to
be tied to the HTTP layer, and the HTTP code creates default configuration
objects based on the URL supplied.  (HTTP dialers and listeners are now
created with a URL rather than a sockaddr, giving them access to the scheme
as well.)

We fixed several bugs affecting TLS validation, and added a test suite
that confirms that validation works as it should.  We also fixed an orphaned
socket during HTTP negotiation, responsible for an occasional assertion
error if the http handshake does not complete successfully.  Finally several
use-after-free races were closed.

TLS layer changes include reporting of handshake failures using newly
created "standard" error codes for peer authentication and cryptographic
failures.

The use of the '*' wild card in URLs at bind time is no longer supported
for websocket at least.

Documentation updates for all this are in place as well.

7 files changed, 207 insertions, 21 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index d232dfe3..e5fd24ec 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -161,10 +161,12 @@ The following functions are used to manipulate TLS configuration objects.
 
 [cols="1,4"]
 |===
-| <<nng_tls_config_auth_alloc#nng_tls_config_alloc(3)>>|allocate TLS configuration
-| <<nng_tls_config_auth_mode#nng_tls_config_auth_mode(3)>>|set authentication mode
+| <<nng_tls_config_auth_alloc#,nng_tls_config_alloc(3)>>|allocate TLS configuration
+| <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>|set authentication mode
 | <<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>|set certificate authority chain
-| <<nng_tls_config_own_cert#nng_tls_config_own)cert(3)>>|set own certificate and key
+| <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>|load certificate authority from file
+| <<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file_cert(3)>>|load own certificate and key from file
+| <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>|set own certificate and key
 | <<nng_tls_config_free#,nng_tls_config_free(3)>>}free TLS configuration
 | <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name
 |===
diff --git a/docs/nng_tls_config_auth_mode.adoc b/docs/nng_tls_config_auth_mode.adoc
index fc4f9cfd..e07a6a41 100644
--- a/docs/nng_tls_config_auth_mode.adoc
+++ b/docs/nng_tls_config_auth_mode.adoc
@@ -73,8 +73,8 @@ SEE ALSO
 
 <<nng_strerror#,nng_strerror(3)>>,
 <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
-<<nng_tls_config_ca_cert#,nng_tls_config_ca_cert(3)>>,
-<<nng_tls_config_crl#,nng_tls_config_crl(3)>>,
+<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>,
+<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>,
 <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>,
 <<nng#,nng(7)>>
 
diff --git a/docs/nng_tls_config_ca_chain.adoc b/docs/nng_tls_config_ca_chain.adoc
index 2888c032..dcf29a65 100644
--- a/docs/nng_tls_config_ca_chain.adoc
+++ b/docs/nng_tls_config_ca_chain.adoc
@@ -25,24 +25,23 @@ SYNOPSIS
 #include <nng/nng.h>
 
 int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain,
-    const char *crl)
+    const char *crl);
 -----------
 
 DESCRIPTION
 -----------
 
 The `nng_tls_config_ca_chain()` function configures a certificate or
-certificate chain to be used when validating peers using the configuragion
+certificate chain to be used when validating peers using the configuration
 'cfg'.
 
-NOTE: This function *must* be called when the TLS authentication mode SYNOPSIS
-`NNG_TLS_AUTH_MODE_REQUIRED` or `NNG_TLS_AUTH_MODE_OPTIONAL`.  It will have
-no effect if the authentication mode is `NNG_TLS_AUTH_MODE_NONE`.
+NOTE: Certificates *must* be configured when using the authentication mode
+`NNG_TLS_AUTH_MODE_REQUIRED`.
 
 TIP: This function may be called multiple times, to add additional chains
 to a configuration, without affecting those added previously.
 
-The certificates located in 'chain' must be a NUL terminated C string in
+The certificates located in 'chain' must be a zero-terminated C string in
 https://tools.ietf.org/html/rfc7468[PEM] format.  Multiple certificates may
 appear concatenated together, with the leaf certificate listed first.
 together.
@@ -68,6 +67,7 @@ SEE ALSO
 <<nng_strerror#,nng_strerror(3)>>,
 <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
 <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>,
+<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>,
 <<nng#,nng(7)>>
 
 
diff --git a/docs/nng_tls_config_ca_file.adoc b/docs/nng_tls_config_ca_file.adoc
new file mode 100644
index 00000000..32679fc1
--- /dev/null
+++ b/docs/nng_tls_config_ca_file.adoc
@@ -0,0 +1,78 @@
+nng_tls_config_ca_file(3)
+=========================
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \
+            Copyright 2018 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_config_ca_file - load certificate authority from file
+
+SYNOPSIS
+--------
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_tls_config_ca_file(nni_tls_config *cfg, const char *path);
+-----------
+
+DESCRIPTION
+-----------
+
+The `nng_tls_config_ca_file()` function configures the certificate authority
+certificate chain and optional revocation list by loading the certificates
+(and revocation list if present) from a single named file. The file must
+at least one X.509 certificate in https://tools.ietf.org/html/rfc7468[PEM]
+format, and may contain multiple such certificates, as well as zero or
+more PEM CRL objects.  This information is used to validate certificates
+that are presented by peers, when using the configuration 'cfg'.
+
+NOTE: Certificates *must* be configured when using the authentication mode
+`NNG_TLS_AUTH_MODE_REQUIRED`.
+
+TIP: This function may be called multiple times, to add additional chains
+to a configuration, without affecting those added previously.
+
+RETURN VALUES
+-------------
+
+This function returns 0 on success, and non-zero otherwise.
+
+ERRORS
+------
+
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_EBUSY`:: The configuration 'cfg' is already in use, and cannot be modified.
+`NNG_EINVAL`:: The contents of 'path' are invalid or did not contain a valid PEM certificate.
+`NNG_ENOENT`:: The file 'path' does not exist.
+`NNG_EPERM`:: The file 'path' is not readable.
+
+SEE ALSO
+--------
+
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>,
+<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>,
+<<nng#,nng(7)>>
+
+
+COPYRIGHT
+---------
+
+Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] +
+Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/MIT[MIT License].
diff --git a/docs/nng_tls_config_cert_key_file.adoc b/docs/nng_tls_config_cert_key_file.adoc
new file mode 100644
index 00000000..9745d442
--- /dev/null
+++ b/docs/nng_tls_config_cert_key_file.adoc
@@ -0,0 +1,83 @@
+nng_tls_config_cert_key_file(3)
+===============================
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \
+            Copyright 2018 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_config_cert_key_file - load own certificate and key from file
+
+SYNOPSIS
+--------
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_tls_config_cert_key_file(nni_tls_config *cfg, const char *path,
+    const char *pass);
+-----------
+
+DESCRIPTION
+-----------
+
+The `nng_tls_config_cert_key_file()` function loads a certificate (or
+certificate chain) and a private key from the file named by 'path'.
+
+The file must contain both the https://tools.ietf.org/html/rfc7468[PEM]
+encoded certificate and associated private key, which will be used when
+establishing TLS sessions using 'cfg'.  It may contain additional certificates
+leading to a validation chain, with the leaf certificate first.
+There is no need to include the self-signed root, as the peer
+will need to have that already in order to perform it's own validation.
+
+The private key may be encrypted with a password, in which can be supplied in
+'pass'.  The value NULL should be supplied for 'pass' if the key is not
+encrypted.
+
+On servers, it is possible to call this function multiple times for the
+same configuration.  This can be useful for specifying different parameters
+to be used for different cryptographic algorithms.
+
+
+RETURN VALUES
+-------------
+
+This function returns 0 on success, and non-zero otherwise.
+
+ERRORS
+------
+
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_EBUSY`:: The configuration 'cfg' is already in use, and cannot be modified.
+`NNG_EINVAL`:: The contents of 'path' are invalid.
+`NNG_ENOENT`:: The file named by 'path' does not exist.
+`NNG_EPERM`:: The file named by 'path' cannot be opened.
+
+SEE ALSO
+--------
+
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>,
+<<nng#,nng(7)>>
+
+
+COPYRIGHT
+---------
+
+Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] +
+Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/MIT[MIT License].
diff --git a/docs/nng_tls_config_own_cert.adoc b/docs/nng_tls_config_own_cert.adoc
index 485e44ca..dd8f7362 100644
--- a/docs/nng_tls_config_own_cert.adoc
+++ b/docs/nng_tls_config_own_cert.adoc
@@ -67,6 +67,7 @@ SEE ALSO
 
 <<nng_strerror#,nng_strerror(3)>>,
 <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file(3)>>,
 <<nng#,nng(7)>>
 
 
diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc
index 0afb417e..d36062ab 100644
--- a/docs/nng_ws.adoc
+++ b/docs/nng_ws.adoc
@@ -81,16 +81,12 @@ usually.footnote:[This is a bug and will likely be fixed in the future.]
 NOTE: The value specified as the host, if any, will also be used
 in the `Host:` HTTP header during HTTP negotiation.
 
-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. `ws://0.0.0.0:9999`
-  2. `ws://*:9999`
-  3. `ws://:9999`
+To listen to all ports on the system, the host name may be elided from
+the URL on the listener.  This will wind up listening to all interfaces
+on the system, with possible caveats for IPv4 and IPv6 depending on what
+the underlying system supports.  (On most modern systems it will map to the
+special IPv6 address `::`, and both IPv4 and IPv6 connections will be
+permitted, with IPv4 addresses mapped to IPv6 addresses.)
 
 Socket Address
 ~~~~~~~~~~~~~~
@@ -159,6 +155,32 @@ 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.
 
+`NNG_OPT_WSS_TLS_CA_FILE`::
+
+This is a write-only option used to load certificates associated
+associated private key from a file.  The value is a C string
+containing the path name of the file.  The file itself must contain
+https://tools.ietf.org/html/rfc7468[PEM] format objects for one or more
+X.509 certificates.  It may also contain certificate revocation list (CRL)
+objects well.  Note that attempts to call this will fail if the
+configuration associated with the underlying endpoint
+is already in use.  This option is only available for `wss://` endpoints.
+
+`NNG_OPT_WSS_TLS_CERT_KEY_FILE`::
+
+This is a write-only option used to load the local certificate and
+associated private key from a file.  The value is a C string
+containing the path name of the file.  The file itself must contain PEM
+format objects for the X.509 certificate and private key.  Multiple
+certificates may be listed in the file, to provide a validation chain,
+with the leaf certificate listed first, and subsequent certificates listed
+afterwards.  Note that attempts to call this will fail if the
+configuration associated with the underlying endpoint
+is already in use.  This option is only available for `wss://` endpoints.
+The private key must not be encrypted.  (Use the `NNG_OPT_WSS_TLS_CONFIG`
+option to get the underlying TLS configuration if more advanced
+configuration is needed.)
+
 // 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),