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.

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

docs/man/libnng.3.adoc

@@ -1,6 +1,6 @@
 = libnng(3)
 //
-// Copyright 2023 Staysail Systems, Inc. <[email protected]>
+// Copyright 2024 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 // Copyright 2019 Devolutions <[email protected]>
 // Copyright 2020 Dirac Research <[email protected]>
@@ -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

docs/man/nng_tls_config_psk.3tls.adoc

@@ -0,0 +1,65 @@
+= nng_tls_config_psk(3tls)
+//
+// Copyright 2024 Staysail Systems, Inc. <[email protected]>
+//
+// 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)]

include/nng/supplemental/tls/engine.h

@@ -1,5 +1,5 @@
 //
-// Copyright 2020 Staysail Systems, Inc. <[email protected]>
+// Copyright 2024 Staysail Systems, Inc. <[email protected]>
 //
 // This software is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -150,6 +150,12 @@ typedef struct nng_tls_engine_config_ops_s {
 	int (*own_cert)(
 	    nng_tls_engine_config *, const char *, const char *, const char *);
 
+	// psk configures a PSK identity and key.  This can be called
+	// once for clients, or multiple times for servers.  However, not all
+	// implementations support multiple PSKs for a server.
+	int (*psk)(
+	    nng_tls_engine_config *, const char *, const uint8_t *, size_t);
+
 	// version configures the minimum and maximum TLS versions.  The
 	// engine should default to supporting TLS1.0 through 1.2, and
 	// optionally 1.3 if it can.  The engine should restrict the
@@ -163,8 +169,9 @@ typedef struct nng_tls_engine_config_ops_s {
 
 typedef enum nng_tls_engine_version_e {
 	NNG_TLS_ENGINE_V0      = 0,
-	NNG_TLS_ENGINE_V1      = 1,
-	NNG_TLS_ENGINE_VERSION = NNG_TLS_ENGINE_V1,
+	NNG_TLS_ENGINE_V1      = 1, // adds FIPS, TLS 1.3 support
+	NNG_TLS_ENGINE_V2      = 2, // adds PSK support
+	NNG_TLS_ENGINE_VERSION = NNG_TLS_ENGINE_V2,
 } nng_tls_engine_version;
 
 typedef struct nng_tls_engine_s {

include/nng/supplemental/tls/tls.h

@@ -1,5 +1,5 @@
 //
-// Copyright 2020 Staysail Systems, Inc. <[email protected]>
+// Copyright 2024 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
 // This software is supplied under the terms of the MIT License, a
@@ -18,6 +18,8 @@ extern "C" {
 #include <stddef.h>
 #include <stdint.h>
 
+#include <nng/nng.h>
+
 // Note that TLS functions may be stubbed out if TLS is not enabled in
 // the build.
 
@@ -116,6 +118,14 @@ NNG_DECL int nng_tls_config_ca_file(nng_tls_config *, const char *);
 NNG_DECL int nng_tls_config_cert_key_file(
     nng_tls_config *, const char *, const char *);
 
+// nng_tls_config_psk_identity is used to pass TLS PSK parameters.  The
+// identity, and an associated key.  Clients can only do this once.
+// Servers can do it multiple times, potentially, to provide for different
+// keys for different client identities.  There is no way to remove these
+// from a configuration.
+NNG_DECL int nng_tls_config_psk(
+    nng_tls_config *, const char *, const uint8_t *, size_t);
+
 // Configure supported TLS version.  By default we usually restrict
 // ourselves to TLS 1.2 and newer.  We do not support older versions.
 // If the implementation cannot support any version (for example if

src/sp/transport/tls/CMakeLists.txt

@@ -1,5 +1,5 @@
 #
-# Copyright 2020 Staysail Systems, Inc. <[email protected]>
+# Copyright 2024 Staysail Systems, Inc. <[email protected]>
 # Copyright 2018 Capitar IT Group BV <[email protected]>
 #
 # This software is supplied under the terms of the MIT License, a
@@ -13,4 +13,5 @@ nng_directory(tls)
 
 nng_sources_if(NNG_TRANSPORT_TLS tls.c)
 nng_headers_if(NNG_TRANSPORT_TLS nng/transport/tls/tls.h)
-nng_defines_if(NNG_TRANSPORT_TLS NNG_TRANSPORT_TLS)
+nng_defines_if(NNG_TRANSPORT_TLS NNG_TRANSPORT_TLS)
+nng_test_if(NNG_TRANSPORT_TLS tls_tran_test)