lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-07-29 11:41:15 +03:00
Code 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
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) #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED)
/** /**
* \brief Configure a pre-shared key (PSK) and identity * \brief Configure one or more pre-shared keys (PSKs) and their
* to be used in PSK-based ciphersuites. * identities to be used in PSK-based ciphersuites.
* *
* \note This is mainly useful for clients. Servers will usually * \note This is mainly useful for clients. Servers will usually
* want to use \c mbedtls_ssl_conf_psk_cb() instead. * 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 * \note A PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback
* takes precedence over a PSK configured by this function. * 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 conf The SSL configuration to register the PSK with.
* \param psk The pointer to the pre-shared key to use. * \param psk The pointer to the pre-shared key to use.
* \param psk_len The length of the pre-shared key in bytes. * \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 * hence need not be preserved by the caller for the lifetime
* of the SSL configuration. * 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 \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, int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
const unsigned char *psk, size_t psk_len, 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) #if defined(MBEDTLS_USE_PSA_CRYPTO)
/** /**
* \brief Configure an opaque pre-shared key (PSK) and identity * \brief Configure one or more opaque pre-shared keys (PSKs) and
* to be used in PSK-based ciphersuites. * their identities to be used in PSK-based ciphersuites.
* *
* \note This is mainly useful for clients. Servers will usually * \note This is mainly useful for clients. Servers will usually
* want to use \c mbedtls_ssl_conf_psk_cb() instead. * 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 * the PSK callback takes precedence over an opaque PSK
* configured by this function. * 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 conf The SSL configuration to register the PSK with.
* \param psk The identifier of the key slot holding the PSK. * \param psk The identifier of the key slot holding the PSK.
* Until \p conf is destroyed or this function is successfully * 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 * not be preserved by the caller for the lifetime of the
* SSL configuration. * 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 \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, int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,
psa_key_id_t psk, psa_key_id_t psk,