fixes #1846 Add support for TLS PSK

This also adds an SP layer transport test for TLS, based on the TCP
test but with some additions; this test does not cover all the edge
cases for TLS, but it does at least show how to use it.

3 files changed, 68 insertions, 1 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index e839b0d6..6db3318f 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -346,6 +346,7 @@ if (NNG_ENABLE_DOC)
             nng_tls_config_free
             nng_tls_config_hold
             nng_tls_config_own_cert
+            nng_tls_config_psk
             nng_tls_config_server_name
             nng_tls_engine_description
             nng_tls_engine_fips_mode
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 3e2900aa..8d006ba8 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -1,6 +1,6 @@
 = libnng(3)
 //
-// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2019 Devolutions <info@devolutions.net>
 // Copyright 2020 Dirac Research <robert.bielik@dirac.com>
@@ -471,6 +471,7 @@ with TLS support.
 |xref:nng_tls_config_ca_chain.3tls.adoc[nng_tls_config_ca_chain()]|set certificate authority chain
 |xref:nng_tls_config_ca_file.3tls.adoc[nng_tls_config_ca_file()]|load certificate authority from file
 |xref:nng_tls_config_cert_key_file.3tls.adoc[nng_tls_config_cert_key_file()]|load own certificate and key from file
+|xref:nng_tls_config_psk.3tls.adoc[nng_tls_config_psk()]|set pre-shared key and identity
 |xref:nng_tls_config_own_cert.3tls.adoc[nng_tls_config_own_cert()]|set own certificate and key
 |xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free()]|free TLS configuration
 |xref:nng_tls_config_server_name.3tls.adoc[nng_tls_config_server_name()]|set remote server name
diff --git a/docs/man/nng_tls_config_psk.3tls.adoc b/docs/man/nng_tls_config_psk.3tls.adoc
new file mode 100644
index 00000000..47c9613a
--- /dev/null
+++ b/docs/man/nng_tls_config_psk.3tls.adoc
@@ -0,0 +1,65 @@
+= nng_tls_config_psk(3tls)
+//
+// Copyright 2024 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_psk - configure pre-shared keys (PSK) for TLS
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tls/tls.h>
+
+int nng_tls_config_psk(nng_tls_config *cfg, const char *identity,
+    const uint8_t *key, size_t key_len);
+----
+
+== DESCRIPTION
+
+The `nng_tls_config_psk()` function configures a pre-shared secret to use for TLS connections.
+
+Client mode configurations can call this just once, to set their own _identity_
+and a single _key_ of __key_len__ bytes in size.
+
+Server mode configurations can call this multiple times,
+and servers will look up the appropriate key to use when a client connects.
+
+The _identity_ may be thought of at some level as a public value like a user name,
+and the _key_ of course is the confidential material used to establish keys.
+Both parties my have the same values for _identity_, _key_, and __key_len__.
+
+Implementations may impose limits on whether this functionality is supported, as well
+as limitations on the length of keys or identities, but generally key lengths of up
+to 32 bytes as well as identities of up to 64 bytes will be supported wherever PSK
+configurations are present.
+
+Note that while some implementations may allow arbitrary byte patterns in the identity,
+this implementation does not support embedded zero bytes, and assumes that the values
+are printable (for logging).
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified.
+`NNG_EINVAL`:: Invalid parameters were supplied.
+
+== 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.7.adoc[nng(7)]