From e6e51aab55fd002ddc89f5b1b2579f768c6eb606 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 15 Jun 2021 11:29:26 +0200 Subject: [PATCH] Add ChangeLog and migration guide entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merge part of the RSA entries into this one, as I think it's easier for users to have all similar changes in one place regardless of whether they were introduce in the same PR or not. Signed-off-by: Manuel Pégourié-Gonnard --- ChangeLog.d/mandatory-rng-param.txt | 12 +++++++ ChangeLog.d/remove-rsa-mode-parameter.txt | 1 - .../mandatory-rng-param.md | 36 +++++++++++++++++++ .../remove-rsa-mode-parameter.md | 8 ----- 4 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 ChangeLog.d/mandatory-rng-param.txt create mode 100644 docs/3.0-migration-guide.d/mandatory-rng-param.md diff --git a/ChangeLog.d/mandatory-rng-param.txt b/ChangeLog.d/mandatory-rng-param.txt new file mode 100644 index 000000000..4e04248fa --- /dev/null +++ b/ChangeLog.d/mandatory-rng-param.txt @@ -0,0 +1,12 @@ +API changes + * For all functions that take an RNG parameter, this parameter is now + mandatory (that is, NULL is not an acceptable value). Functions which + previously accepted NULL and now reject it are: the X.509 CRT and CSR + writing functions; the PK sign and decrypt function; the RSA encrypt, + decrypt, sign and private functions; the function in DHM and ECDH that + compute the share secret; the scalar multiplication functions in ECP. + * The following functions now require an RNG parameter: + mbedtls_ecp_check_pub_priv(), mbedtls_pk_check_pair(), + mbedtls_pk_parse_key(), mbedtls_pk_parse_keyfile(). + * The configuration option MBEDTLS_ECP_NO_INTERNAL_RNG has been removed as + it no longer had any effect. diff --git a/ChangeLog.d/remove-rsa-mode-parameter.txt b/ChangeLog.d/remove-rsa-mode-parameter.txt index 854dda34b..2590d3a94 100644 --- a/ChangeLog.d/remove-rsa-mode-parameter.txt +++ b/ChangeLog.d/remove-rsa-mode-parameter.txt @@ -6,4 +6,3 @@ API changes decryption functions now always use the private key and verification and encryption use the public key. Verification functions also no longer have RNG parameters. - * The RNG is now mandatory for all private-key RSA operations. diff --git a/docs/3.0-migration-guide.d/mandatory-rng-param.md b/docs/3.0-migration-guide.d/mandatory-rng-param.md new file mode 100644 index 000000000..3cbc35695 --- /dev/null +++ b/docs/3.0-migration-guide.d/mandatory-rng-param.md @@ -0,0 +1,36 @@ +The RNG parameter is now mandatory for all functions that accept one +-------------------------------------------------------------------- + +This change affects all users who called a function accepting a `f_rng` +parameter with `NULL` as the value of this argument; this is no longer +supported. + +The changed functions are: the X.509 CRT and CSR writing functions; the PK +sign and decrypt function; the RSA encrypt, decrypt, sign and private +functions; the functions in DHM and ECDH that compute the share secret; the +scalar multiplication functions in ECP. + +You now need to pass a properly seeded, cryptographically secure RNG to all +functions that accept a `f_rng` parameter. It is of course still possible to +pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a +context. + +Some functions gained an RNG parameter +-------------------------------------- + +This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, +`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and +`mbedtls_pk_parse_keyfile()`. + +You now need to pass a properly seeded, cryptographically secure RNG when +calling these functions. It is used for blinding, a counter-measure against +side-channel attacks. + +The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed +------------------------------------------------------------------ + +This doesn't affect users of the default configuration; it only affects people +who were explicitly setting this option. + +This was a trade-off between code size and counter-measures; it is no longer +relevant as the counter-measure is now always on at no cost in code size. diff --git a/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md b/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md index e400650dd..d21d5ed85 100644 --- a/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md +++ b/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md @@ -19,11 +19,3 @@ RSA verification functions also no longer take random generator arguments (this was only needed when using a private key). This affects all applications using the RSA verify functions. -RNG is now mandatory in all RSA private key operations ------------------------------------------------------- - -The random generator is now mandatory for blinding in all RSA private-key -operations (`mbedtls_rsa_private`, `mbedtls_rsa_xxx_sign`, -`mbedtls_rsa_xxx_decrypt`) as well as for encryption -(`mbedtls_rsa_xxx_encrypt`). This means that passing a null `f_rng` is no longer -supported.