From 946c92584047c50240d69877a878c436cbf0c173 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 19 Apr 2021 21:41:47 +0100 Subject: [PATCH 1/9] Document new semantics for static PSK configuration Signed-off-by: Hanno Becker --- 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, From 2ed3dced8fb26fd25e8598b08ed64aeef3488a1f Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 19 Apr 2021 21:59:14 +0100 Subject: [PATCH 2/9] Implement new semantics for static PSK configuration Signed-off-by: Hanno Becker --- library/ssl_tls.c | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/library/ssl_tls.c b/library/ssl_tls.c index 8946c236a8..21cef9f785 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -4005,6 +4005,19 @@ int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl, #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED) +static int ssl_conf_psk_is_configured( mbedtls_ssl_config const *conf ) +{ +#if defined(MBEDTLS_USE_PSA_CRYPTO) + if( !mbedtls_svc_key_id_is_null( conf->psk_opaque ) ) + return( 1 ); +#endif /* MBEDTLS_USE_PSA_CRYPTO */ + + if( conf->psk != NULL ) + return( 1 ); + + return( 0 ); +} + static void ssl_conf_remove_psk( mbedtls_ssl_config *conf ) { /* Remove reference to existing PSK, if any. */ @@ -4070,8 +4083,10 @@ int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf, const unsigned char *psk_identity, size_t psk_identity_len ) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; - /* Remove opaque/raw PSK + PSK Identity */ - ssl_conf_remove_psk( conf ); + + /* We currently only support one PSK, raw or opaque. */ + if( ssl_conf_psk_is_configured( conf ) ) + return( MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); /* Check and set raw PSK */ if( psk == NULL ) @@ -4139,8 +4154,10 @@ int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf, size_t psk_identity_len ) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; - /* Clear opaque/raw PSK + PSK Identity, if present. */ - ssl_conf_remove_psk( conf ); + + /* We currently only support one PSK, raw or opaque. */ + if( ssl_conf_psk_is_configured( conf ) ) + return( MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); /* Check and set opaque PSK */ if( mbedtls_svc_key_id_is_null( psk ) ) From 6667ffdd867c180939aeae698f35b401cf7c7ac4 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 19 Apr 2021 21:59:22 +0100 Subject: [PATCH 3/9] Test new semantics for static PSK configuration Signed-off-by: Hanno Becker --- tests/suites/test_suite_ssl.data | 12 +++ tests/suites/test_suite_ssl.function | 108 +++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/tests/suites/test_suite_ssl.data b/tests/suites/test_suite_ssl.data index e59c9055f7..0cfcd497ad 100644 --- a/tests/suites/test_suite_ssl.data +++ b/tests/suites/test_suite_ssl.data @@ -1,3 +1,15 @@ +Attempt to register multiple PSKs +test_multiple_psks: + +Attempt to register multiple PSKS, incl. opaque PSK, #0 +test_multiple_psks_opaque:0 + +Attempt to register multiple PSKs, incl. opaque PSK, #1 +test_multiple_psks_opaque:1 + +Attempt to register multiple PSKs, incl. opaque PSK, #2 +test_multiple_psks_opaque:2 + Test calback buffer sanity test_callback_buffer_sanity: diff --git a/tests/suites/test_suite_ssl.function b/tests/suites/test_suite_ssl.function index 2f59afea4f..e07de88a7c 100644 --- a/tests/suites/test_suite_ssl.function +++ b/tests/suites/test_suite_ssl.function @@ -8,6 +8,8 @@ #include #include "test/certs.h" +#include + #include #include @@ -4535,3 +4537,109 @@ exit: mbedtls_free( src ); } /* END_CASE */ + +/* BEGIN_CASE depends_on:MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED */ +void test_multiple_psks() +{ + unsigned char psk0[10] = { 0 }; + unsigned char psk0_identity[] = { 'f', 'o', 'o' }; + + unsigned char psk1[10] = { 0 }; + unsigned char psk1_identity[] = { 'b', 'a', 'r' }; + + mbedtls_ssl_config conf; + + mbedtls_ssl_config_init( &conf ); + + TEST_ASSERT( mbedtls_ssl_conf_psk( &conf, + psk0, sizeof( psk0 ), + psk0_identity, sizeof( psk0_identity ) ) == 0 ); + TEST_ASSERT( mbedtls_ssl_conf_psk( &conf, + psk1, sizeof( psk1 ), + psk1_identity, sizeof( psk1_identity ) ) == + MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); + +exit: + + mbedtls_ssl_config_free( &conf ); +} +/* END_CASE */ + +/* BEGIN_CASE depends_on:MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED:MBEDTLS_USE_PSA_CRYPTO */ +void test_multiple_psks_opaque( int mode ) +{ + /* + * Mode 0: Raw PSK, then opaque PSK + * Mode 1: Opaque PSK, then raw PSK + * Mode 2: 2x opaque PSK + */ + + unsigned char psk0_raw[10] = { 0 }; + unsigned char psk0_raw_identity[] = { 'f', 'o', 'o' }; + + psa_key_id_t psk0_opaque = (psa_key_id_t) 1; + unsigned char psk0_opaque_identity[] = { 'f', 'o', 'o' }; + + unsigned char psk1_raw[10] = { 0 }; + unsigned char psk1_raw_identity[] = { 'b', 'a', 'r' }; + + psa_key_id_t psk1_opaque = (psa_key_id_t) 2; + unsigned char psk1_opaque_identity[] = { 'b', 'a', 'r' }; + + mbedtls_ssl_config conf; + + USE_PSA_INIT( ); + mbedtls_ssl_config_init( &conf ); + + switch( mode ) + { + case 0: + + TEST_ASSERT( mbedtls_ssl_conf_psk( &conf, + psk0_raw, sizeof( psk0_raw ), + psk0_raw_identity, sizeof( psk0_raw_identity ) ) + == 0 ); + TEST_ASSERT( mbedtls_ssl_conf_psk_opaque( &conf, + psk1_opaque, + psk1_opaque_identity, sizeof( psk1_opaque_identity ) ) + == MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); + break; + + case 1: + + TEST_ASSERT( mbedtls_ssl_conf_psk_opaque( &conf, + psk0_opaque, + psk0_opaque_identity, sizeof( psk0_opaque_identity ) ) + == 0 ); + TEST_ASSERT( mbedtls_ssl_conf_psk( &conf, + psk1_raw, sizeof( psk1_raw ), + psk1_raw_identity, sizeof( psk1_raw_identity ) ) + == MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); + + break; + + case 2: + + TEST_ASSERT( mbedtls_ssl_conf_psk_opaque( &conf, + psk0_opaque, + psk0_opaque_identity, sizeof( psk0_opaque_identity ) ) + == 0 ); + TEST_ASSERT( mbedtls_ssl_conf_psk_opaque( &conf, + psk1_opaque, + psk1_opaque_identity, sizeof( psk1_opaque_identity ) ) + == MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE ); + + break; + + default: + TEST_ASSERT( 0 ); + break; + } + +exit: + + mbedtls_ssl_config_free( &conf ); + USE_PSA_DONE( ); + +} +/* END_CASE */ From 67e49a627d5d22b5ed67a593200b48f4654c032b Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 14 May 2021 20:02:42 +0100 Subject: [PATCH 4/9] Add migration guide Signed-off-by: Hanno Becker --- .../relaxed-psk-semantics.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/3.0-migration-guide.d/relaxed-psk-semantics.md diff --git a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md new file mode 100644 index 0000000000..5af2b61089 --- /dev/null +++ b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md @@ -0,0 +1,23 @@ +Relaxed semantics for PSK configuration +----------------------------------------------------------------- + +This affects users which call the PSK configuration APIs +`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()` +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. + +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. From 90671489183d81633a03594f10461b06e52e0679 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 14 May 2021 20:12:36 +0100 Subject: [PATCH 5/9] Add ChangeLog entry Signed-off-by: Hanno Becker --- ChangeLog.d/relaxed-psk-semantics.txt | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 ChangeLog.d/relaxed-psk-semantics.txt diff --git a/ChangeLog.d/relaxed-psk-semantics.txt b/ChangeLog.d/relaxed-psk-semantics.txt new file mode 100644 index 0000000000..a5063c9d8e --- /dev/null +++ b/ChangeLog.d/relaxed-psk-semantics.txt @@ -0,0 +1,9 @@ +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. From c49d15fdedb40ff3948a946221eb4e3121f0b058 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Sun, 23 May 2021 05:41:21 +0100 Subject: [PATCH 6/9] Use 'version-specific' instead of 'implementation-defined' in API Signed-off-by: Hanno Becker --- include/mbedtls/ssl.h | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index f9a5970e15..57d2085e63 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -2696,6 +2696,18 @@ int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf, * \brief Configure one or more 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. + * * \note This is mainly useful for clients. Servers will usually * want to use \c mbedtls_ssl_conf_psk_cb() instead. * @@ -2713,15 +2725,6 @@ 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 #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs * can be configured. In this case, the SSL configuration @@ -2737,6 +2740,18 @@ 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. + * * \note This is mainly useful for clients. Servers will usually * want to use \c mbedtls_ssl_conf_psk_cb() instead. * @@ -2759,15 +2774,6 @@ 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 #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs * can be configured. In this case, the SSL configuration From 196739b478937feb02a79d058840d123f93fa6d9 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 28 May 2021 05:25:46 +0100 Subject: [PATCH 7/9] Change wording in documentation of PSK configuration Signed-off-by: Hanno Becker --- ChangeLog.d/relaxed-psk-semantics.txt | 10 ++--- .../relaxed-psk-semantics.md | 11 ++--- include/mbedtls/ssl.h | 40 ++++++------------- 3 files changed, 20 insertions(+), 41 deletions(-) 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, From 934ab00f774322ecce2e4082101be7098a1257be Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 28 May 2021 09:52:54 +0100 Subject: [PATCH 8/9] Minor improvement of ChangeLog wording Signed-off-by: Hanno Becker --- ChangeLog.d/relaxed-psk-semantics.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ChangeLog.d/relaxed-psk-semantics.txt b/ChangeLog.d/relaxed-psk-semantics.txt index d9d922be13..418ff6fcb7 100644 --- a/ChangeLog.d/relaxed-psk-semantics.txt +++ b/ChangeLog.d/relaxed-psk-semantics.txt @@ -3,5 +3,5 @@ API changes In Mbed TLS 2.X, the API prescribes that later calls overwrite 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. + leaving the PSK that was configured first intact. + Support for more than one PSK may be added in 3.X. From 2bec09c113427a433a987d770a38dcdb560e9af3 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 28 May 2021 09:54:31 +0100 Subject: [PATCH 9/9] Fix typo in migration guide Signed-off-by: Hanno Becker --- docs/3.0-migration-guide.d/relaxed-psk-semantics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fa38ac331b..6b0e794757 100644 --- a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md +++ b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md @@ -8,7 +8,7 @@ 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. In Mbed TLS 3.0, -calling `mbedtls_conf_[opaque_]psk()` multiple times +calling `mbedtls_ssl_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,