Document new semantics for static PSK configuration
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 2350910..f9a5970 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2693,8 +2693,8 @@
#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 @@
* \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 @@
* 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 @@
#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 @@
* 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 @@
* 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,