diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | docs/man/libnng.3.adoc | 3 | ||||
| -rw-r--r-- | docs/man/nng_tls_config_psk.3tls.adoc | 65 |
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)] |