AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Document new semantics for static PSK configuration

Browse Source 
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
This commit is contained in:
Hanno Becker 2021-04-19 21:41:47 +01:00
parent 1cc91e7475
commit 946c925840
1 changed files with 30 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
include/mbedtls/ssl.h
View File

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