From 217b8159da89ee63bcffb4f4e9a7d5925a48afc3 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 1 Oct 2019 18:39:45 +0200 Subject: [PATCH] Use standard terminology to describe the personalization string NIST and many other sources call it a "personalization string", and certainly not "device-specific identifiers" which is actually somewhat misleading since this is just one of many things that might go into a personalization string. --- include/mbedtls/ctr_drbg.h | 11 +++++------ include/mbedtls/hmac_drbg.h | 12 +++++++----- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h index a8294f8cc..a31ec88aa 100644 --- a/include/mbedtls/ctr_drbg.h +++ b/include/mbedtls/ctr_drbg.h @@ -204,7 +204,7 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx ); * \p f_entropy is always called with a buffer size equal to the entropy * length described in the documentation of mbedtls_ctr_drbg_set_entropy_len(). * - * Personalization data can be provided in addition to the more generic + * You can provide a personalization string in addition to the * entropy source, to make this instantiation as unique as possible. * * \note The _seed_material_ value passed to the derivation @@ -232,11 +232,10 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx ); * \p p_entropy context, the buffer to fill, and the * length of the buffer. * \param p_entropy The entropy context to pass to \p f_entropy. - * \param custom Personalization data, that is device-specific - * identifiers. This can be \c NULL, in which case the - * personalization data is empty regardless of the value - * of \p len. - * \param len The length of the personalization data. + * \param custom The personalization string. + * This can be \c NULL, in which case the personalization + * string is empty regardless of the value of \p len. + * \param len The length of the personalization string. * This must be at most * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT * - #MBEDTLS_CTR_DRBG_ENTROPY_LEN. diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h index 12f863fed..496baa08d 100644 --- a/include/mbedtls/hmac_drbg.h +++ b/include/mbedtls/hmac_drbg.h @@ -129,6 +129,9 @@ void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx ); * with mbedtls_entropy_init() (which registers the platform's default * entropy sources). * + * You can provide a personalization string in addition to the + * entropy source, to make this instantiation as unique as possible. + * * \note By default, the security strength as defined by NIST is: * - 128 bits if \p md_info is SHA-1; * - 192 bits if \p md_info is SHA-224; @@ -154,11 +157,10 @@ void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx ); * \p p_entropy context, the buffer to fill, and the * length of the buffer. * \param p_entropy The entropy context to pass to \p f_entropy. - * \param custom Personalization data, that is device-specific - * identifiers. This can be \c NULL, in which case the - * personalization data is empty regardless of the value - * of \p len. - * \param len The length of the personalization data. + * \param custom The personalization string. + * This can be \c NULL, in which case the personalization + * string is empty regardless of the value of \p len. + * \param len The length of the personalization string. * This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT * and also at most * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len * 3 / 2