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.

1 files changed, 47 insertions, 0 deletions

diff --git a/src/nng.h b/src/nng.h
index 6c043e26..0653d533 100644
--- a/src/nng.h
+++ b/src/nng.h
@@ -368,6 +368,53 @@ enum nng_flag_enum {
 #define NNG_OPT_RECONNMINT "reconnect-time-min"
 #define NNG_OPT_RECONNMAXT "reconnect-time-max"
 
+// TLS options are only used when the underlying transport supports TLS.
+
+// NNG_OPT_TLS_CONFIG is a pointer to an nng_tls_config object.  Generally
+// this can used with endpoints, although once an endpoint is started, or
+// once a configuration is used, the value becomes read-only. Note that
+// when configuring the object, a hold is placed on the TLS configuration,
+// using a reference count.  When retrieving the object, no such hold is
+// placed, and so the caller must take care not to use the associated object
+// after the endpoint it is associated with is closed.
+#define NNG_OPT_TLS_CONFIG "tls-config"
+
+// NNG_OPT_TLS_AUTH_MODE is a write-only integer (int) option that specifies
+// whether peer authentication is needed.  The option can take one of the
+// values of NNG_TLS_AUTH_MODE_NONE, NNG_TLS_AUTH_MODE_OPTIONAL, or
+// NNG_TLS_AUTH_MODE_REQUIRED.  The default is typically NNG_TLS_AUTH_MODE_NONE
+// for listeners, and NNG_TLS_AUTH_MODE_REQUIRED for dialers. If set to
+// REQUIRED, then connections will be rejected if the peer cannot be verified.
+// If set to OPTIONAL, then a verification step takes place, but the connection
+// is still permitted.  (The result can be checked with NNG_OPT_TLS_VERIFIED).
+#define NNG_OPT_TLS_AUTH_MODE "tls-authmode"
+
+// NNG_OPT_TLS_CERT_KEY_FILE names a single file that contains a certificate
+// and key identifying the endpoint.  This is a write-only value.  This can be
+// set multiple times for times for different keys/certs corresponding to
+// different algorithms on listeners, whereas dialers only support one.  The
+// file must contain both cert and key as PEM blocks, and the key must
+// not be encrypted.  (If more flexibility is needed, use the TLS configuration
+// directly, via NNG_OPT_TLS_CONFIG.)
+#define NNG_OPT_TLS_CERT_KEY_FILE "tls-cert-key-file"
+
+// NNG_OPT_TLS_CA_FILE names a single file that contains certificate(s) for a
+// CA, and optionally CRLs, which are used to validate the peer's certificate.
+// This is a write-only value, but multiple CAs can be loaded by setting this
+// multiple times.
+#define NNG_OPT_TLS_CA_FILE "tls-ca-file"
+
+// NNG_OPT_TLS_SERVER_NAME is a write-only string that can typically be
+// set on dialers to check the CN of the server for a match.  This
+// can also affect SNI (server name indication).  It usually has no effect
+// on listeners.
+#define NNG_OPT_TLS_SERVER_NAME "tls-server-name"
+
+// NNG_OPT_TLS_VERIFIED returns a single integer, indicating whether the peer
+// has been verified (1) or not (0).  Typically this is read-only, and only
+// available for pipes.
+#define NNG_OPT_TLS_VERIFIED "tls-verified"
+
 // XXX: TBD: priorities, socket names, ipv4only
 
 // Statistics.  These are for informational purposes only, and subject