Change wording in documentation of PSK configuration

Signed-off-by: Hanno Becker <hanno.becker@arm.com>

ChangeLog.d/relaxed-psk-semantics.txt

@@ -1,9 +1,7 @@
 API changes
     * Modify semantics of `mbedtls_ssl_conf_[opaque_]psk()`:
       In Mbed TLS 2.X, the API prescribes that later calls overwrite
-      the effect of earlier calls, implying that there can be at most one
+      the effect of earlier calls. In Mbed TLS 3.0, calling
-      statically configured PSK. In Mbed TLS 3.X, multiple invocations of
+      `mbedtls_ssl_conf_[opaque_]psk()` more than once will fail,
-      `mbedtls_ssl_conf_[opaque_]psk()` can be attempted to register
+      leaving the PSK intact that was configured first. Support
-      multiple PSKs. Once an implementation-defined limit of PSKs
+      for more than one PSK may be added in 3.X.
-      is reached, the functions ignore the request to add
-      further PSKs and fail non-fatally.

docs/3.0-migration-guide.d/relaxed-psk-semantics.md

@@ -7,17 +7,12 @@ multiple times on the same SSL configuration.
 
 In Mbed TLS 2.x, users would observe later calls overwriting
 the effect of earlier calls, with the prevailing PSK being
-the one that has been configured last.
+the one that has been configured last. In Mbed TLS 3.0,
+calling `mbedtls_conf_[opaque_]psk()` multiple times
+will return an error, leaving the first PSK intact.
 
 To achieve equivalent functionality when migrating to Mbed TLS 3.0,
 users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should
 remove all but the last call, so that only one call to _either_
 `mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()`
 remains.
-
-However, if the _intent_ of the multiple calls to
-`mbedtls_ssl_conf_[opaque_]psk()` was to offer multiple PSKs, then
-users should _keep_ all calls and only check for the expected
-non-fatal failure code `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`
-indicating that no more PSKs could be buffered by the
-implementation.

include/mbedtls/ssl.h

@@ -2693,20 +2693,14 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
 
 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED)
 /**
- * \brief          Configure one or more pre-shared keys (PSKs) and their
+ * \brief          Configure pre-shared keys (PSKs) and their
  *                 identities to be used in PSK-based ciphersuites.
  *
- *                 This function may be called multiple times to attempt
+ *                 Only one PSK can be registered, through either
- *                 to register multiple PSKs. The number of supported PSKs
+ *                 mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque().
- *                 is version-specific (see below for the current limit).
+ *                 If you attempt to register more than one PSK, this function
- *                 Once the limit is reached, this function fails, maintaining
+ *                 fails, though this may change in future versions, which
- *                 the PSKs previously configured and ignoring the excess request.
+ *                 may add support for multiple PSKs.
- *                 This behavior is in contrast to Mbed TLS 2.x, where later
- *                 invocations would overwrite the effect of earlier calls.
- *
- * \note           Currently, the library supports only support a single PSK,
- *                 but this limit is not part of the API and may change in
- *                 future minor versions.
  *
  * \note           This is mainly useful for clients. Servers will usually
  *                 want to use \c mbedtls_ssl_conf_psk_cb() instead.
@@ -2727,8 +2721,7 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
  *
  * \return         \c 0 if successful.
  * \return         #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
- *                 can be configured. In this case, the SSL configuration
+ *                 can be configured. In this case, the old PSK(s) remain intact.
- *                 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,
@@ -2740,17 +2733,11 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
  * \brief          Configure one or more opaque pre-shared keys (PSKs) and
  *                 their identities to be used in PSK-based ciphersuites.
  *
- *                 This function may be called multiple times to attempt
+ *                 Only one PSK can be registered, through either
- *                 to register multiple PSKs. The number of supported PSKs
+ *                 mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque().
- *                 is version-specific (see below for the current limit).
+ *                 If you attempt to register more than one PSK, this function
- *                 Once the limit is reached, this function fails, maintaining
+ *                 fails, though this may change in future versions, which
- *                 the PSKs previously configured and ignoring the excess request.
+ *                 may add support for multiple PSKs.
- *                 This behavior is in contrast to Mbed TLS 2.x, where later
- *                 invocations would overwrite the effect of earlier calls.
- *
- * \note           Currently, the library supports only support a single PSK,
- *                 but this limit is not part of the API and may change in
- *                 future minor versions.
  *
  * \note           This is mainly useful for clients. Servers will usually
  *                 want to use \c mbedtls_ssl_conf_psk_cb() instead.
@@ -2776,8 +2763,7 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
  *
  * \return         \c 0 if successful.
  * \return         #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
- *                 can be configured. In this case, the SSL configuration
+ *                 can be configured. In this case, the old PSK(s) remain intact.
- *                 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,