Rename config init/fini to alloc/free, add documentation for them.

13 files changed, 232 insertions, 43 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index c9ff2d5b..3c320bb1 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -148,9 +148,31 @@ The following functions are used to register a transport for use.
 | <<nng_inproc.adoc#,nng_inproc_register(3)>>|register inproc transport
 | <<nng_ipc.adoc#,nng_ipc_register(3)>>|register IPC transport
 | <<nng_tcp.adoc#,nng_tcp_register(3)>>|register TCP transport
+| <<nng_tls.adoc#,nng_tls_register(3)>>|register TLS transport
+| <<nng_ws.adoc#,nng_ws_register(3)>>|register WebSocket transport
+| <<nng_wss.adoc#,nng_wss_register(3)>>|register WebSocket Secure transport
 | <<nng_zerotier.adoc#,nng_zerotier_register(3)>>|register ZeroTier transport
 |===
 
+TLS Configuration Objects
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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_ca_cert#,nng_tls_config_ca_cert(3)>>|set certificate authority chain
+| <<nng_tls_config_cert#nng_tls_config_cert(3)>>|set own certificate
+| <<nng_tls_config_crl#nng_tls_config_crl(3)>>|set certificate revocation list
+| <<nng_tls_config_free#,nng_tls_config_free(3)>>}free TLS configuration
+| <<nng_tls_config_key#,nng_tls_config_key(3)>>|set private key
+| <<nng_tls_config_pass#nng_tls_config_pass(3)>>|set private key password
+| <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name
+|===
+
+
 SEE ALSO
 --------
 <<nng.adoc#,nng(7)>>
@@ -160,6 +182,7 @@ COPYRIGHT
 ---------
 
 Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] +
+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
diff --git a/docs/nng.adoc b/docs/nng.adoc
index d0fc5ee3..6eadc2ce 100644
--- a/docs/nng.adoc
+++ b/docs/nng.adoc
@@ -125,6 +125,7 @@ The library API is documented at <<libnng.adoc#,libnng(3)>>.
 
 SEE ALSO
 --------
+<<libnng.adoc#,libnng(3)>>
 <<nng_compat.adoc#,nng_compat(3)>>
 
 COPYRIGHT
diff --git a/docs/nng_tls.adoc b/docs/nng_tls.adoc
index a6737d01..acf71d7b 100644
--- a/docs/nng_tls.adoc
+++ b/docs/nng_tls.adoc
@@ -243,7 +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)>>
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>
 
 COPYRIGHT
 ---------
diff --git a/docs/nng_tls_config_alloc.adoc b/docs/nng_tls_config_alloc.adoc
new file mode 100644
index 00000000..4b41258f
--- /dev/null
+++ b/docs/nng_tls_config_alloc.adoc
@@ -0,0 +1,91 @@
+nng_tls_config_alloc(3)
+=======================
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Staysail Systems, Inc. <info@staysail.tech> \
+            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_alloc - allocate TLS configuration object
+
+SYNOPSIS
+--------
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+typedef enum nng_tls_mode {
+        NNG_TLS_MODE_CLIENT,
+        NNG_TLS_MODE_SERVER
+} nng_tls_mode;
+
+int nng_tls_config_alloc(nni_tls_config **cfgp, nng_tls_mode mode);
+-----------
+
+DESCRIPTION
+-----------
+
+The `nng_tls_config_alloc()` function creates a newly initialized
+TLS (Transport Layer Security, see
+https://tools.ietf.org/html/rfc5246[RFC 5246])
+configuration object.
+
+This object is initialized for use when acting as either a
+client (`NNG_TLS_MODE_CLIENT`) or as a server (`NNG_TLS_MODE_SERVER`).
+
+A TLS object can be further modified by functions that set the security
+keys used, peeer certificates, protocol policies, and so forth.
+
+A single TLS configuration object can be used with multiple TLS streams
+or services.  The underlying system uses reference counting to ensure
+that object is not inadvertently freed while in use.
+
+Also note that a TLS configuration object becomes "read-only" after it
+is first used with a service.  After this points, attempts to apply
+further changes to the configuration will result in `NNG_EBUSY`.
+
+
+RETURN VALUES
+-------------
+
+This function returns 0 on success, and non-zero otherwise.
+
+
+ERRORS
+------
+
+`NNG_ENOMEM`:: Insufficient memory is available to allocate the object.
+
+
+SEE ALSO
+--------
+
+<<nng_setopt#,nng_setopt(3)>>
+<<nng_strerror#,nng_strerror(3)>>
+<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>
+<<nng_tls_config_ca_cert#,nng_tls_config_ca_cert(3)>>
+<<nng_tls_config_cert#,nng_tls_config_cert(3)>>
+<<nng_tls_config_crl#,nng_tls_config_crl(3)>>
+<<nng_tls_config_free#,nng_tls_config_free(3)>>
+<<nng_tls_config_key#,nng_tls_config_key(3)>>
+<<nng_tls_config_pass#,nng_tls_config_pass(3)>>
+<<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>
+<<nng#,nng(7)>>
+
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:info@staysail.tech[Staysail Systems, Inc.]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].
diff --git a/docs/nng_tls_config_free.adoc b/docs/nng_tls_config_free.adoc
new file mode 100644
index 00000000..8e94e7f2
--- /dev/null
+++ b/docs/nng_tls_config_free.adoc
@@ -0,0 +1,61 @@
+nng_tls_config_alloc(3)
+=======================
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Staysail Systems, Inc. <info@staysail.tech> \
+            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_free - deallocate a TLS configuration object
+
+SYNOPSIS
+--------
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_tls_config_free(nni_tls_config *cfg);
+-----------
+
+DESCRIPTION
+-----------
+
+The `nng_tls_config_free()` decrements the reference count on a 
+TLS configuration object, and if the resulting reference count is zero,
+then deallocates the configuration object.
+
+RETURN VALUES
+-------------
+
+None.
+
+
+ERRORS
+------
+
+None.
+
+
+SEE ALSO
+--------
+
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>
+<<nng#,nng(7)>>
+
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:info@staysail.tech[Staysail Systems, Inc.]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].
diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc
index b6185757..66bcff67 100644
--- a/docs/nng_ws.adoc
+++ b/docs/nng_ws.adoc
@@ -169,7 +169,7 @@ This object is only available for `wss://` endpoints.
 SEE ALSO
 --------
 <<nng.adoc#,nng(7)>>
-<<nng_tls_init#,nng_tls_init(3)>>
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>
 
 COPYRIGHT
 ---------
diff --git a/src/nng.h b/src/nng.h
index f42bc1a5..31b56729 100644
--- a/src/nng.h
+++ b/src/nng.h
@@ -598,12 +598,14 @@ typedef enum nng_tls_auth_mode {
 	NNG_TLS_AUTH_MODE_REQUIRED = 2, // Verify cert, close if invalid
 } nng_tls_auth_mode;
 
-// nng_tls_config init creates a TLS configuration using
+// nng_tls_config_alloc creates a TLS configuration using
 // reasonable defaults.  This configuration can be shared
 // with multiple pipes or services/servers.
 NNG_DECL int nng_tls_config_init(nng_tls_config **, nng_tls_mode);
 
-NNG_DECL void nng_tls_config_fini(nng_tls_config *);
+// nng_tls_config_free drops the reference count on the TLS
+// configuration object, and if zero, deallocates it.
+NNG_DECL void nng_tls_config_free(nng_tls_config *);
 
 // nng_tls_config_server_name sets the server name.  This is
 // called by clients to set the name that the server supplied
@@ -619,7 +621,7 @@ NNG_DECL int nng_tls_config_server_name(nng_tls_config *, const char *);
 // format.
 NNG_DECL int nng_tls_config_ca_cert(nng_tls_config *, const uint8_t *, size_t);
 
-// nng_tls_config_clr loads a certificate revocation list.  Again, these
+// nng_tls_config_crl loads a certificate revocation list.  Again, these
 // are in X.509 format (either PEM or DER).
 NNG_DECL int nng_tls_config_crl(nng_tls_config *, const uint8_t *, size_t);
 
@@ -636,11 +638,6 @@ NNG_DECL int nng_tls_config_key(nng_tls_config *, const uint8_t *, size_t);
 // private keys that are encrypted.
 NNG_DECL int nng_tls_config_pass(nng_tls_config *, const char *);
 
-// nng_tls_config_validate_peer is used to enable validation of the peer
-// and it's certificate.  If disabled, the peer's certificate will still
-// be available, but may not be valid.
-NNG_DECL int nng_tls_config_validate_peer(nng_tls_config *, bool);
-
 // nng_tls_config_auth_mode is used to configure the authentication mode use.
 // The default is that servers have this off (i.e. no client authentication)
 // and clients have it on (they verify the server), which matches typical
diff --git a/src/supplemental/http/client.c b/src/supplemental/http/client.c
index 4bb517ce..b1794f93 100644
--- a/src/supplemental/http/client.c
+++ b/src/supplemental/http/client.c
@@ -89,7 +89,7 @@ nni_http_client_fini(nni_http_client *c)
 	nni_mtx_fini(&c->mtx);
 #ifdef NNG_SUPP_TLS
 	if (c->tls != NULL) {
-		nng_tls_config_fini(c->tls);
+		nni_tls_config_fini(c->tls);
 	}
 #endif
 	NNI_FREE_STRUCT(c);
@@ -134,7 +134,7 @@ nni_http_client_set_tls(nni_http_client *c, nng_tls_config *tls)
 	}
 	nni_mtx_unlock(&c->mtx);
 	if (old != NULL) {
-		nng_tls_config_fini(old);
+		nni_tls_config_fini(old);
 	}
 	return (0);
 }
diff --git a/src/supplemental/http/server.c b/src/supplemental/http/server.c
index ba74a138..0f2b1369 100644
--- a/src/supplemental/http/server.c
+++ b/src/supplemental/http/server.c
@@ -609,7 +609,7 @@ http_server_fini(nni_http_server *s)
 	nni_mtx_unlock(&s->mtx);
 #ifdef NNG_SUPP_TLS
 	if (s->tls != NULL) {
-		nng_tls_config_fini(s->tls);
+		nni_tls_config_fini(s->tls);
 	}
 #endif
 	nni_aio_fini(s->accaio);
@@ -1108,7 +1108,7 @@ nni_http_server_set_tls(nni_http_server *s, nng_tls_config *tcfg)
 	}
 	nni_mtx_unlock(&s->mtx);
 	if (old) {
-		nng_tls_config_fini(old);
+		nni_tls_config_fini(old);
 	}
 	return (0);
 }
diff --git a/src/supplemental/tls/mbedtls/tls.c b/src/supplemental/tls/mbedtls/tls.c
index 3bbf4a33..5c92d7d9 100644
--- a/src/supplemental/tls/mbedtls/tls.c
+++ b/src/supplemental/tls/mbedtls/tls.c
@@ -157,7 +157,7 @@ nni_tls_random(void *arg, unsigned char *buf, size_t sz)
 }
 
 void
-nng_tls_config_fini(nng_tls_config *cfg)
+nni_tls_config_fini(nng_tls_config *cfg)
 {
 	nni_tls_certkey *ck;
 
@@ -199,7 +199,7 @@ nng_tls_config_fini(nng_tls_config *cfg)
 }
 
 int
-nng_tls_config_init(nng_tls_config **cpp, enum nng_tls_mode mode)
+nni_tls_config_init(nng_tls_config **cpp, enum nng_tls_mode mode)
 {
 	nng_tls_config *cfg;
 	int             rv;
@@ -227,7 +227,7 @@ nng_tls_config_init(nng_tls_config **cpp, enum nng_tls_mode mode)
 	rv = mbedtls_ssl_config_defaults(&cfg->cfg_ctx, sslmode,
 	    MBEDTLS_SSL_TRANSPORT_STREAM, MBEDTLS_SSL_PRESET_DEFAULT);
 	if (rv != 0) {
-		nng_tls_config_fini(cfg);
+		nni_tls_config_fini(cfg);
 		return (rv);
 	}
 
@@ -242,7 +242,7 @@ nng_tls_config_init(nng_tls_config **cpp, enum nng_tls_mode mode)
 	rv = mbedtls_ctr_drbg_seed(
 	    &cfg->rng_ctx, nni_tls_get_entropy, NULL, NULL, 0);
 	if (rv != 0) {
-		nng_tls_config_fini(cfg);
+		nni_tls_config_fini(cfg);
 		return (rv);
 	}
 #endif
@@ -284,7 +284,7 @@ nni_tls_fini(nni_tls *tp)
 	nni_free(tp->sendbuf, NNG_TLS_MAX_RECV_SIZE);
 	if (tp->cfg != NULL) {
 		// release the hold we got on it
-		nng_tls_config_fini(tp->cfg);
+		nni_tls_config_fini(tp->cfg);
 	}
 	NNI_FREE_STRUCT(tp);
 }
@@ -1065,3 +1065,15 @@ err:
 	nni_free(tmp, len);
 	return (rv);
 }
+
+int
+nng_tls_config_alloc(nng_tls_config **cfgp, nng_tls_mode mode)
+{
+	return (nni_tls_config_init(cfgp, mode));
+}
+
+int
+nng_tls_config_free(nng_tls_config *cfg)
+{
+	nni_tls_config_fini(cfg);
+}
\ No newline at end of file
diff --git a/src/supplemental/tls/tls.h b/src/supplemental/tls/tls.h
index 0c9e791f..8175854d 100644
--- a/src/supplemental/tls/tls.h
+++ b/src/supplemental/tls/tls.h
@@ -14,6 +14,14 @@
 // nni_tls represents the context for a single TLS stream.
 typedef struct nni_tls nni_tls;
 
+// nni_tls_config_init creates a new TLS configuration object.
+// The object is created with a reference count of one.
+extern int nni_tls_config_init(nng_tls_config **, nng_tls_mode);
+
+// nni_tls_config_fini drops the reference on the configuration
+// object, deallocating if this was the last reference.
+extern void nni_tls_config_fini(nng_tls_config *);
+
 // nni_tls_config_hold is used to get a hold on the config
 // object, preventing it from being released inadvertently.
 // The hold is released with a call to nng_tls_config_fini().
diff --git a/tests/tls.c b/tests/tls.c
index 70b22fea..fe8aea1e 100644
--- a/tests/tls.c
+++ b/tests/tls.c
@@ -110,7 +110,7 @@ init_dialer_tls(trantest *tt, nng_dialer d)
 	nng_tls_config *cfg;
 	int             rv;
 
-	if ((rv = nng_tls_config_init(&cfg, NNG_TLS_MODE_CLIENT)) != 0) {
+	if ((rv = nng_tls_config_alloc(&cfg, NNG_TLS_MODE_CLIENT)) != 0) {
 		return (rv);
 	}
 	if ((rv = nng_tls_config_ca_cert(
@@ -124,7 +124,7 @@ init_dialer_tls(trantest *tt, nng_dialer d)
 	rv = nng_dialer_setopt_ptr(d, NNG_OPT_TLS_CONFIG, cfg);
 
 out:
-	nng_tls_config_fini(cfg);
+	nng_tls_config_free(cfg);
 	return (rv);
 }
 
@@ -134,25 +134,23 @@ init_listener_tls(trantest *tt, nng_listener l)
 	nng_tls_config *cfg;
 	int             rv;
 
-	if ((rv = nng_tls_config_init(&cfg, NNG_TLS_MODE_SERVER)) != 0) {
+	if ((rv = nng_tls_config_alloc(&cfg, NNG_TLS_MODE_SERVER)) != 0) {
 		return (rv);
 	}
 	if ((rv = nng_tls_config_cert(
 	         cfg, (void *) server_cert, sizeof(server_cert))) != 0) {
-		nng_tls_config_fini(cfg);
-		return (rv);
+		goto out;
 	}
 	if ((rv = nng_tls_config_key(
 	         cfg, (void *) server_key, sizeof(server_key))) != 0) {
-		nng_tls_config_fini(cfg);
-		return (rv);
+		goto out;
 	}
 
 	if ((rv = nng_listener_setopt_ptr(l, NNG_OPT_TLS_CONFIG, cfg)) != 0) {
-		nng_tls_config_fini(cfg);
-		return (rv);
+		goto out;
 	}
-	nng_tls_config_fini(cfg);
+out:
+	nng_tls_config_free(cfg);
 	return (0);
 }
 
diff --git a/tests/wss.c b/tests/wss.c
index 2f701117..151b4287 100644
--- a/tests/wss.c
+++ b/tests/wss.c
@@ -141,7 +141,7 @@ init_dialer_wss(trantest *tt, nng_dialer d)
 	nng_tls_config *cfg;
 	int             rv;
 
-	if ((rv = nng_tls_config_init(&cfg, NNG_TLS_MODE_CLIENT)) != 0) {
+	if ((rv = nng_tls_config_alloc(&cfg, NNG_TLS_MODE_CLIENT)) != 0) {
 		return (rv);
 	}
 	if ((rv = nng_tls_config_ca_cert(
@@ -155,7 +155,7 @@ init_dialer_wss(trantest *tt, nng_dialer d)
 	rv = nng_dialer_setopt_ptr(d, NNG_OPT_WSS_TLS_CONFIG, cfg);
 
 out:
-	nng_tls_config_fini(cfg);
+	nng_tls_config_free(cfg);
 	return (rv);
 }
 
@@ -165,31 +165,29 @@ init_listener_wss(trantest *tt, nng_listener l)
 	nng_tls_config *cfg;
 	int             rv;
 
-	if ((rv = nng_tls_config_init(&cfg, NNG_TLS_MODE_SERVER)) != 0) {
+	if ((rv = nng_tls_config_alloc(&cfg, NNG_TLS_MODE_SERVER)) != 0) {
 		return (rv);
 	}
 	if ((rv = nng_tls_config_cert(
 	         cfg, (void *) server_cert, sizeof(server_cert))) != 0) {
-		nng_tls_config_fini(cfg);
-		return (rv);
+		goto out;
 	}
 	if ((rv = nng_tls_config_key(
 	         cfg, (void *) server_key, sizeof(server_key))) != 0) {
-		nng_tls_config_fini(cfg);
-		return (rv);
+		goto out;
 	}
 
 	if ((rv = nng_listener_setopt_ptr(l, NNG_OPT_WSS_TLS_CONFIG, cfg)) !=
 	    0) {
-		// We can wind up with EBUSY from the server
-		// already running.
-		if (rv != NNG_EBUSY) {
-			nng_tls_config_fini(cfg);
-			return (rv);
+		// We can wind up with EBUSY from the server already running.
+		if (rv == NNG_EBUSY) {
+			rv = 0;
 		}
 	}
-	nng_tls_config_fini(cfg);
-	return (0);
+
+out:
+	nng_tls_config_free(cfg);
+	return (rv);
 }
 
 TestMain("WebSocket Secure (TLS) Transport", {