diff --git a/ChangeLog.d/relaxed-psk-semantics.txt b/ChangeLog.d/relaxed-psk-semantics.txt index a5063c9d8e..d9d922be13 100644 --- a/ChangeLog.d/relaxed-psk-semantics.txt +++ b/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 - statically configured PSK. In Mbed TLS 3.X, multiple invocations of - `mbedtls_ssl_conf_[opaque_]psk()` can be attempted to register - multiple PSKs. Once an implementation-defined limit of PSKs - is reached, the functions ignore the request to add - further PSKs and fail non-fatally. + the effect of earlier calls. In Mbed TLS 3.0, calling + `mbedtls_ssl_conf_[opaque_]psk()` more than once will fail, + leaving the PSK intact that was configured first. Support + for more than one PSK may be added in 3.X. diff --git a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md index 5af2b61089..fa38ac331b 100644 --- a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md +++ b/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. diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 57d2085e63..3fab9f8765 100644 --- a/include/mbedtls/ssl.h +++ b/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 - * to register multiple PSKs. The number of supported PSKs - * is version-specific (see below for the current limit). - * 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. - * - * \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. + * Only one PSK can be registered, through either + * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). + * If you attempt to register more than one PSK, this function + * fails, though this may change in future versions, which + * may add support for multiple PSKs. * * \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 - * remains usable, but the PSK has not been configured. + * can be configured. In this case, the old PSK(s) remain intact. * \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 - * to register multiple PSKs. The number of supported PSKs - * is version-specific (see below for the current limit). - * 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. - * - * \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. + * Only one PSK can be registered, through either + * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). + * If you attempt to register more than one PSK, this function + * fails, though this may change in future versions, which + * may add support for multiple PSKs. * * \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 - * remains usable, but the PSK has not been configured. + * can be configured. In this case, the old PSK(s) remain intact. * \return Another negative error code on other kinds of failure. */ int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,