mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-02-25 00:39:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Change wording in documentation of PSK configuration

Browse Source 
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
This commit is contained in:
Hanno Becker 2021-05-28 05:25:46 +01:00
parent c49d15fded
commit 196739b478
3 changed files with 20 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
ChangeLog.d/relaxed-psk-semantics.txt
View File

@ -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.

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

@ -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.

40
include/mbedtls/ssl.h
View File

@ -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,