Corrections to ChangeLog and Migration guide
Corrections to address wording of ChangeLog
and Migration guide.
Signed-off-by: Thomas Daubney <thomas.daubney@arm.com>
diff --git a/ChangeLog.d/remove-rsa-mode-parameter.txt b/ChangeLog.d/remove-rsa-mode-parameter.txt
index b7c6f32..6b32f65 100644
--- a/ChangeLog.d/remove-rsa-mode-parameter.txt
+++ b/ChangeLog.d/remove-rsa-mode-parameter.txt
@@ -1,6 +1,15 @@
+Removals
+ * The RSA module no longer supports private-key operations with the public
+ key and vice versa. This change only affects applications which use the
+ wrong mode. In this case the wrong mode is to use mode=MBEDTLS_RSA_PUBLIC
+ with decryption and signing functions and mode=MBEDTLS_RSA_PRIVATE with
+ encryption and verification functions. Addresses issue #4278.
API changes
* Remove mode parameter from RSA functions. All encryption,
decryption, sign and verify functions are affected. Also
removes the RNG parameters from the RSA verify functions.
Existing user code which utilises these RSA functions must
- remove the mode parameter. Fixes #4278.
+ remove the mode parameter.
+ * RNG is now mandatory for all private-key RSA operations. Existing user code
+ which does not use an RNG with private-key RSA functions must now be
+ updated to do so.
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 2a849a3..e400650 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
@@ -4,20 +4,26 @@
This affects all users who use the RSA encryption, decryption, sign and
verify APIs.
-You must delete the mode parameter from your RSA function calls.
-Using the correct mode is now the default behaviour. Encryption
-and verification functions are now equivalent to their 2.x
-counterparts with mode=MBEDTLS_RSA_PUBLIC. Decryption and signing
-functions are now equivalent to their 2.x counterparts with
-mode=MBEDTLS_RSA_PRIVATE. Note that the constants
-MBEDTLS_RSA_PUBLIC and MBEDTLS_RSA_PRIVATE have been removed in 3.0.
+The RSA module no longer supports private-key operations with the public key or
+vice versa. As a consequence, RSA operation functions no longer have a mode
+parameter. If you were calling RSA operations with the normal mode (public key
+for verification or encryption, private key for signature or decryption), remove
+the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling
+RSA operations with the wrong mode, which rarely makes sense from a security
+perspective, this is no longer supported.
-Remove the RNG parameter from RSA functions
---------------------------------------------
+Remove the RNG parameter from RSA verify functions
+--------------------------------------------------
-This affects all users who use the RSA verify functions.
+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.
-If you were using the RNG parameters then you must remove
-them from your function calls. Since using the wrong mode
-is no longer supported, the RNG parameters namely f_rng
-and p_rng are no longer needed.
+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.
