fixes #206 Want NNG_OPT_TLS_VERIFIED option

It is useful to have support for validating that a peer *was*
verified, especially in the presence of optional validation.
We have added a property that does this, NNG_OPT_TLS_VERIFIED.

Further, all the old NNG_OPT_WSS_TLS_* property names have also been
renamed to generic NNG_OPT_TLS property names, which have been
moved to nng.h to facilitate reuse and sharing, with the comments
moved and corrected as well.

Finally, the man pages have been updated, with substantial
improvements to the nng_ws man page in particular.

6 files changed, 45 insertions, 3 deletions

diff --git a/src/supplemental/http/http.c b/src/supplemental/http/http.c
index 229a4a99..43db1d15 100644
--- a/src/supplemental/http/http.c
+++ b/src/supplemental/http/http.c
@@ -40,6 +40,7 @@ typedef struct nni_http_tran {
 	void (*h_write)(void *, nni_aio *);
 	int (*h_sock_addr)(void *, nni_sockaddr *);
 	int (*h_peer_addr)(void *, nni_sockaddr *);
+	bool (*h_verified)(void *);
 	void (*h_close)(void *);
 	void (*h_fini)(void *);
 } nni_http_tran;
@@ -55,6 +56,7 @@ struct nni_http {
 	void (*wr)(void *, nni_aio *);
 	int (*sock_addr)(void *, nni_sockaddr *);
 	int (*peer_addr)(void *, nni_sockaddr *);
+	bool (*verified)(void *);
 	void (*close)(void *);
 	void (*fini)(void *);
 
@@ -610,6 +612,17 @@ nni_http_peer_addr(nni_http *http, nni_sockaddr *sa)
 	return (rv);
 }
 
+bool
+nni_http_tls_verified(nni_http *http)
+{
+	bool rv;
+
+	nni_mtx_lock(&http->mtx);
+	rv = http->closed ? false : http->verified(http->sock);
+	nni_mtx_unlock(&http->mtx);
+	return (rv);
+}
+
 void
 nni_http_fini(nni_http *http)
 {
@@ -655,6 +668,7 @@ http_init(nni_http **httpp, nni_http_tran *tran, void *data)
 	http->fini      = tran->h_fini;
 	http->sock_addr = tran->h_sock_addr;
 	http->peer_addr = tran->h_peer_addr;
+	http->verified  = tran->h_verified;
 
 	if (((rv = nni_aio_init(&http->wr_aio, http_wr_cb, http)) != 0) ||
 	    ((rv = nni_aio_init(&http->rd_aio, http_rd_cb, http)) != 0)) {
@@ -667,6 +681,13 @@ http_init(nni_http **httpp, nni_http_tran *tran, void *data)
 	return (0);
 }
 
+static bool
+nni_http_verified_tcp(void *arg)
+{
+	NNI_ARG_UNUSED(arg);
+	return (false);
+}
+
 static nni_http_tran http_tcp_ops = {
 	.h_read      = (void *) nni_plat_tcp_pipe_recv,
 	.h_write     = (void *) nni_plat_tcp_pipe_send,
@@ -674,6 +695,7 @@ static nni_http_tran http_tcp_ops = {
 	.h_fini      = (void *) nni_plat_tcp_pipe_fini,
 	.h_sock_addr = (void *) nni_plat_tcp_pipe_sockname,
 	.h_peer_addr = (void *) nni_plat_tcp_pipe_peername,
+	.h_verified  = nni_http_verified_tcp,
 };
 
 int
@@ -690,6 +712,7 @@ static nni_http_tran http_tls_ops = {
 	.h_fini      = (void *) nni_tls_fini,
 	.h_sock_addr = (void *) nni_tls_sockname,
 	.h_peer_addr = (void *) nni_tls_peername,
+	.h_verified  = (void *) nni_tls_verified,
 };
 
 int
diff --git a/src/supplemental/http/http.h b/src/supplemental/http/http.h
index 06394fdd..47c8d654 100644
--- a/src/supplemental/http/http.h
+++ b/src/supplemental/http/http.h
@@ -156,6 +156,9 @@ extern void nni_http_write_full(nni_http *, nni_aio *);
 extern int  nni_http_sock_addr(nni_http *, nni_sockaddr *);
 extern int  nni_http_peer_addr(nni_http *, nni_sockaddr *);
 
+// nni_tls_http_verified returns true if the peer has been verified using TLS.
+extern bool nni_http_tls_verified(nni_http *);
+
 typedef struct nni_http_server nni_http_server;
 
 typedef struct {
diff --git a/src/supplemental/tls/mbedtls/tls.c b/src/supplemental/tls/mbedtls/tls.c
index 4e846f98..7b959b2b 100644
--- a/src/supplemental/tls/mbedtls/tls.c
+++ b/src/supplemental/tls/mbedtls/tls.c
@@ -751,13 +751,13 @@ nni_tls_ciphersuite_name(nni_tls *tp)
 	return (mbedtls_ssl_get_ciphersuite(&tp->ctx));
 }
 
-int
+bool
 nni_tls_verified(nni_tls *tp)
 {
 	int rv;
 
 	rv = mbedtls_ssl_get_verify_result(&tp->ctx);
-	return (rv ? 1 : 0);
+	return (rv ? true : false);
 }
 
 int
diff --git a/src/supplemental/tls/tls.h b/src/supplemental/tls/tls.h
index 5fde50b4..57b552d7 100644
--- a/src/supplemental/tls/tls.h
+++ b/src/supplemental/tls/tls.h
@@ -11,6 +11,8 @@
 #ifndef NNG_SUPPLEMENTAL_TLS_TLS_H
 #define NNG_SUPPLEMENTAL_TLS_TLS_H
 
+#include <stdbool.h>
+
 // nni_tls represents the context for a single TLS stream.
 typedef struct nni_tls nni_tls;
 
@@ -41,7 +43,7 @@ extern int  nni_tls_peername(nni_tls *, nni_sockaddr *);
 // verify.  (During the handshake phase, the peer is not verified, so this
 // might return false if executed too soon.  The verification status will
 // be accurate once the handshake is finished, however.
-extern int nni_tls_verified(nni_tls *);
+extern bool nni_tls_verified(nni_tls *);
 
 // nni_tls_ciphersuite_name returns the name of the ciphersuite in use.
 extern const char *nni_tls_ciphersuite_name(nni_tls *);
diff --git a/src/supplemental/websocket/websocket.c b/src/supplemental/websocket/websocket.c
index fe4f002f..514cf22d 100644
--- a/src/supplemental/websocket/websocket.c
+++ b/src/supplemental/websocket/websocket.c
@@ -1072,6 +1072,17 @@ nni_ws_response_headers(nni_ws *ws)
 	return (ws->reshdrs);
 }
 
+bool
+nni_ws_tls_verified(nni_ws *ws)
+{
+	bool rv;
+
+	nni_mtx_lock(&ws->mtx);
+	rv = nni_http_tls_verified(ws->http);
+	nni_mtx_unlock(&ws->mtx);
+	return (rv);
+}
+
 static void
 ws_fini(void *arg)
 {
diff --git a/src/supplemental/websocket/websocket.h b/src/supplemental/websocket/websocket.h
index 9a52f78c..ddd09b72 100644
--- a/src/supplemental/websocket/websocket.h
+++ b/src/supplemental/websocket/websocket.h
@@ -11,6 +11,8 @@
 #ifndef NNG_SUPPLEMENTAL_WEBSOCKET_WEBSOCKET_H
 #define NNG_SUPPLEMENTAL_WEBSOCKET_WEBSOCKET_H
 
+#include <stdbool.h>
+
 // Pre-defined types for some prototypes.  These are from other subsystems.
 typedef struct nni_http_req nni_http_req;
 typedef struct nni_http_res nni_http_res;
@@ -63,6 +65,7 @@ extern void          nni_ws_close_error(nni_ws *, uint16_t);
 extern void          nni_ws_fini(nni_ws *);
 extern const char *  nni_ws_response_headers(nni_ws *);
 extern const char *  nni_ws_request_headers(nni_ws *);
+extern bool          nni_ws_tls_verified(nni_ws *);
 
 // The implementation will send periodic PINGs, and respond with PONGs.