7 files changed, 279 insertions, 3 deletions
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index f357d60a..b4d85fd1 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -1,5 +1,5 @@
 #
-# Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+# Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 # Copyright 2018 Capitar IT Group BV <info@capitar.com>
 # Copyright 2019 Devolutions <info@devolutions.net>
 #
@@ -337,6 +337,9 @@ if (NNG_ENABLE_DOC)
             nng_tls_config_hold
             nng_tls_config_own_cert
             nng_tls_config_server_name
+            nng_tls_engine_description
+            nng_tls_engine_fips_mode
+            nng_tls_engine_name
             )
 
     set(NNG_MAN5
@@ -365,6 +368,7 @@ if (NNG_ENABLE_DOC)
             nng_tcp_options
             nng_ipc_options
             nng_tls_config
+            nng_tls_engine
             nng_tls_options
             )
 
diff --git a/docs/man/nng_tls_config.5.adoc b/docs/man/nng_tls_config.5.adoc
index 8d3fee59..be49242a 100644
--- a/docs/man/nng_tls_config.5.adoc
+++ b/docs/man/nng_tls_config.5.adoc
@@ -1,6 +1,6 @@
 = nng_tls_config(5)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2019 Devolutions <devolutions.net>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -11,7 +11,7 @@
 
 == NAME
 
-nng_tls_config - message
+nng_tls_config - TLS configuration object
 
 == SYNOPSIS
 
diff --git a/docs/man/nng_tls_config_version.3tls.adoc b/docs/man/nng_tls_config_version.3tls.adoc
new file mode 100644
index 00000000..5a42cb10
--- /dev/null
+++ b/docs/man/nng_tls_config_version.3tls.adoc
@@ -0,0 +1,85 @@
+= nng_tls_config_version(3tls)
+//
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document 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_version - configure TLS version
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tls/tls.h>
+
+typedef enum nng_tls_version {
+    NNG_TLS_1_0 = 0x301,
+    NNG_TLS_1_1 = 0x302,
+    NNG_TLS_1_2 = 0x303,
+    NNG_TLS_1_3 = 0x304
+} nng_tls_version;
+
+int nng_tls_config_version(nng_tls_config *cfg, nng_tls_version min, nng_tls_version max);
+----
+
+== DESCRIPTION
+
+The `nng_tls_config_version()` function configures the TLS version numbers that may be used when establishing TLS sessions using this configuration object.
+
+The actual set supported range will further be restricted by the versions that the
+xref:nng_tls_engine.5.adoc[TLS engine] supports.
+If the TLS engine cannot support any TLS version in the requested range, then `NNG_ENOTSUP` is returned.
+
+By default (if this function is not called), NNG will attempt to use both TLS v1.2 and TLS v1.3, provided that the TLS engine supports them.
+
+Clients and servers will generally negotiate for the highest mutually supported TLS version.
+
+TIP: As of this writing, we recommend setting the minimum to
+`NNG_TLS_1_2` (TLS v1.2) and the maximum to `NNG_TLS_1_3` (TLS v1.3).
+This gives the best security, while ensuring good interoperability.
+Nearly all modern TLS implementations support TLS v1.2.
+
+TIP: Support for TLS v1.3 is available via external TLS engines.
+
+NOTE: The cipher-suites supported by TLS v1.3 are different from earlier versions.
+Therefore it may be necessary to generate different certificates.
+
+== CAVEATS
+
+* SSL v2.0 and v3.0 are insecure, and not supported in NNG.
+
+* TLS v1.3 is not supported by the default _Mbed TLS_ engine at this time.
+
+* Some TLS engines may not support limiting the maximum version.
+
+* TLS v1.3 Zero Round Trip Time (0-RTT) is not supported in NNG.
+
+* Session resumption is not supported in NNG (for any TLS version).
+
+* TLS PSK support is not supported in NNG. (This is a limitation planned to be addressed.)
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_EINVAL`:: An invalid version was specified.
+`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified.
+`NNG_ENOTSUP`:: The TLS implementation cannot support any version in the requested range.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_strerror.3.adoc[nng_strerror(3)],
+xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)],
+xref:nng_tls_engine.5.adoc[nng_tls_engine(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_tls_engine.5.adoc b/docs/man/nng_tls_engine.5.adoc
new file mode 100644
index 00000000..9493117e
--- /dev/null
+++ b/docs/man/nng_tls_engine.5.adoc
@@ -0,0 +1,49 @@
+= nng_tls_engine(5)
+//
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document 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_engine - TLS engine implementation
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/supplemental/tls/tls.h>
+#include <nng/supplemental/tls/engine.h>
+
+typedef struct nng_tls_engine_s nng_tls_engine;
+----
+
+== DESCRIPTION
+
+The ((TLS engine)) API is provided for developers wishing to implement their
+own implementation of TLS, or to adapt a 3rd party TLS implementation to
+the work with NNG.
+
+Information about the existing TLS engine can be obtained from the functions
+xref:nng_tls_engine_name.3tls.adoc[`nng_tls_engine_name()`],
+xref:nng_tls_engine_description.3tls.adoc[`nng_tls_engine_description()`], and
+xref:nng_tls_engine_fips_mode.3tls.adoc[`nng_tls_engine_fips_mode()`] functions.
+
+At this time, there is no further documentation on implementing a TLS
+engine oneself, but existing source code may be a guide.
+The primary interfaces are located in the
+`<nng/supplemental/tls/engine.h>` header file.
+
+== SEE ALSO
+
+[.text-left]
+
+xref:nng_tls_engine_description.3tls.adoc[nng_tls_engine_description(3tls)],
+xref:nng_tls_engine_fips_mode.3tls.adoc[nng_tls_engine_fips_mode(3tls)],
+xref:nng_tls_engine_name.3tls.adoc[nng_tls_engine_name(3tls)],
+xref:nng_tls_config.5.adoc[nng_tls_config(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_tls_engine_description.3tls.adoc b/docs/man/nng_tls_engine_description.3tls.adoc
new file mode 100644
index 00000000..2b742d94
--- /dev/null
+++ b/docs/man/nng_tls_engine_description.3tls.adoc
@@ -0,0 +1,44 @@
+= nng_tls_engine_description(3tls)
+//
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document 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_engine_description - TLS engine description
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/supplemental/tls/tls.h>
+
+const char *nng_tls_engine_description(void);
+----
+
+== DESCRIPTION
+
+The `nng_tls_engine_description()` returns a short description for the current
+xref:tls_engine.5.adoc[TLS engine].
+If no engine is registered, then the empty string ("") is returned.
+This is principally useful for diagnostic purposes.
+
+== RETURN VALUES
+
+The description of the engine of the engine.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_tls_engine_name.3tls.adoc[nng_tls_engine_name(3tls)],
+xref:nng_tls_engine.5.adoc[nng_tls_engine(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_tls_engine_fips_mode.3tls.adoc b/docs/man/nng_tls_engine_fips_mode.3tls.adoc
new file mode 100644
index 00000000..68aaef2c
--- /dev/null
+++ b/docs/man/nng_tls_engine_fips_mode.3tls.adoc
@@ -0,0 +1,51 @@
+= nng_tls_fips_mode(3tls)
+//
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document 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_engine_fips_mode - TLS FIPS 140-2 mode indicator
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/supplemental/tls/tls.h>
+
+bool nng_tls_engine_fips_mode(void);
+----
+
+== DESCRIPTION
+
+The `nng_tls_engine_fips_mode()` returns `true` if the
+xref:tls_engine.5.adoc[TLS engine] is operating in FIPS 140-2 mode,
+and `false` otherwise.
+
+TIP: FIPS 140-2 references a United States standard for the use
+of cryptography in information processing systems.
+
+TIP: The default TLS engine does not support FIPS 140-2 mode, and
+will always return false.  Alternative implementations with such
+support may be available from commercial suppliers.
+
+NOTE: Generally the FIPS 140-2 mode cannot be changed after program startup.
+
+== RETURN VALUES
+
+True if the TLS engine is in FIPS 140-2 mode, false otherwise.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_tls_engine.5.adoc[nng_tls_engine(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_tls_engine_name.3tls.adoc b/docs/man/nng_tls_engine_name.3tls.adoc
new file mode 100644
index 00000000..6ba87ea9
--- /dev/null
+++ b/docs/man/nng_tls_engine_name.3tls.adoc
@@ -0,0 +1,43 @@
+= nng_tls_engine_name(3tls)
+//
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document 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_engine_name - TLS engine name
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/supplemental/tls/tls.h>
+
+const char *nng_tls_engine_name(void);
+----
+
+== DESCRIPTION
+
+The `nng_tls_engine_name()` returns a short name for the current
+xref:tls_engine.5.adoc[TLS engine].
+If no engine is registered, then the special name "none" is returned.
+
+== RETURN VALUES
+
+The name of the engine.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_tls_engine_description.3tls.adoc[nng_tls_engine_description(3tls)],
+xref:nng_tls_engine.5.adoc[nng_tls_engine(5)]
+xref:nng.7.adoc[nng(7)]