From 946c92584047c50240d69877a878c436cbf0c173 Mon Sep 17 00:00:00 2001
From: Hanno Becker <hanno.becker@arm.com>
Date: Mon, 19 Apr 2021 21:41:47 +0100
Subject: [PATCH] Document new semantics for static PSK configuration

Signed-off-by: Hanno Becker <hanno.becker@arm.com>
---
 include/mbedtls/ssl.h | 50 ++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 20 deletions(-)

diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 2350910756..f9a5970e15 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2693,8 +2693,8 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
 
 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED)
 /**
- * \brief          Configure a pre-shared key (PSK) and identity
- *                 to be used in PSK-based ciphersuites.
+ * \brief          Configure one or more pre-shared keys (PSKs) and their
+ *                 identities to be used in PSK-based ciphersuites.
  *
  * \note           This is mainly useful for clients. Servers will usually
  *                 want to use \c mbedtls_ssl_conf_psk_cb() instead.
@@ -2702,13 +2702,6 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
  * \note           A PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback
  *                 takes precedence over a PSK configured by this function.
  *
- * \warning        Currently, clients can only register a single pre-shared key.
- *                 Calling this function or mbedtls_ssl_conf_psk_opaque() more
- *                 than once will overwrite values configured in previous calls.
- *                 Support for setting multiple PSKs on clients and selecting
- *                 one based on the identity hint is not a planned feature,
- *                 but feedback is welcomed.
- *
  * \param conf     The SSL configuration to register the PSK with.
  * \param psk      The pointer to the pre-shared key to use.
  * \param psk_len  The length of the pre-shared key in bytes.
@@ -2720,8 +2713,20 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
  *                 hence need not be preserved by the caller for the lifetime
  *                 of the SSL configuration.
  *
+ * \note           While this function may be called multiple times to
+ *                 register multiple PSKs, the number of supported PSKs
+ *                 is implementation-defined. Once the limit is reached,
+ *                 this function fails, maintaining the PSKs previously
+ *                 configured and ignoring the excess request.
+ *                 This behavior is in contrast to Mbed TLS 2.x, where
+ *                 later invocations would overwrite the effect of earlier
+ *                 calls.
+ *
  * \return         \c 0 if successful.
- * \return         An \c MBEDTLS_ERR_SSL_XXX error code on failure.
+ * \return         #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
+ *                 can be configured. In this case, the SSL configuration
+ *                 remains usable, but the PSK has not been configured.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
                 const unsigned char *psk, size_t psk_len,
@@ -2729,8 +2734,8 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
 /**
- * \brief          Configure an opaque pre-shared key (PSK) and identity
- *                 to be used in PSK-based ciphersuites.
+ * \brief          Configure one or more opaque pre-shared keys (PSKs) and
+ *                 their identities to be used in PSK-based ciphersuites.
  *
  * \note           This is mainly useful for clients. Servers will usually
  *                 want to use \c mbedtls_ssl_conf_psk_cb() instead.
@@ -2739,13 +2744,6 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
  *                 the PSK callback takes precedence over an opaque PSK
  *                 configured by this function.
  *
- * \warning        Currently, clients can only register a single pre-shared key.
- *                 Calling this function or mbedtls_ssl_conf_psk() more than
- *                 once will overwrite values configured in previous calls.
- *                 Support for setting multiple PSKs on clients and selecting
- *                 one based on the identity hint is not a planned feature,
- *                 but feedback is welcomed.
- *
  * \param conf     The SSL configuration to register the PSK with.
  * \param psk      The identifier of the key slot holding the PSK.
  *                 Until \p conf is destroyed or this function is successfully
@@ -2761,8 +2759,20 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
  *                 not be preserved by the caller for the lifetime of the
  *                 SSL configuration.
  *
+ * \note           While this function may be called multiple times to
+ *                 register multiple PSKs, the number of supported PSKs
+ *                 is implementation-defined. Once the limit is reached,
+ *                 this function fails, maintaining the PSKs previously
+ *                 configured and ignoring the excess request.
+ *                 This behavior is in contrast to Mbed TLS 2.x, where
+ *                 later invocations would overwrite the effect of earlier
+ *                 calls.
+ *
  * \return         \c 0 if successful.
- * \return         An \c MBEDTLS_ERR_SSL_XXX error code on failure.
+ * \return         #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
+ *                 can be configured. In this case, the SSL configuration
+ *                 remains usable, but the PSK has not been configured.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,
                                  psa_key_id_t psk,