ChangeLog and migration guide added.
Signed-off-by: TRodziewicz <tomasz.rodziewicz@mobica.com>
diff --git a/ChangeLog.d/issue4313.txt b/ChangeLog.d/issue4313.txt
new file mode 100644
index 0000000..e240a12
--- /dev/null
+++ b/ChangeLog.d/issue4313.txt
@@ -0,0 +1,24 @@
+Removals
+ * Remove the following macros: MBEDTLS_CHECK_PARAMS,
+ MBEDTLS_CHECK_PARAMS_ASSERT, MBEDTLS_PARAM_FAILED, MBEDTLS_PARAM_FAILED_ALT,
+ TEST_INVALID_PARAM, TEST_INVALID_PARAM_RET, the following macros have been
+ inactivated MBEDTLS_INTERNAL_VALIDATE_RET and MBEDTLS_INTERNAL_VALIDATE,
+ structures: param_failed_ctx_t, mbedtls_test_param_failed_location_record_t,
+ functions: mbedtls_test_param_failed_get_location_record(),
+ mbedtls_test_param_failed_expect_call(),
+ mbedtls_test_param_failed_check_expected_call(),
+ mbedtls_test_param_failed_get_state_buf(),
+ mbedtls_test_param_failed_reset_state(),
+ mbedtls_param_failed(). Remove the following functions from all.sh:
+ component_test_check_params_functionality(),
+ component_test_check_params_without_platform(),
+ component_test_check_params_silent().
+ Remove the following test functions from test_suite_*.function files:
+ aes_check_params(), aria_invalid_param(), blowfish_invalid_param(),
+ camellia_invalid_param(), ccm_invalid_param(), chacha20_bad_params(),
+ chachapoly_bad_params(), cipher_invalid_param_conditional(),
+ dhm_invalid_params(), ecdh_invalid_param(), ecdsa_invalid_param(),
+ ecjpake_invalid_param(), ecp_invalid_param(), gcm_invalid_param(),
+ mpi_invalid_param(), invalid_parameters() (pk), poly1305_bad_params(),
+ rsa_invalid_param(), sha1_invalid_param(), sha256_invalid_param(),
+ sha512_invalid_param(). Fixes #4313.
diff --git a/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md b/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md
new file mode 100644
index 0000000..146b1c7
--- /dev/null
+++ b/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md
@@ -0,0 +1,49 @@
+Remove MBEDTLS_CHECK_PARAMS option
+----------------------------------
+
+This change affects the way of how parameters are validated.
+
+The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enables certain kinds of
+“parameter validation”. It covers two kinds of validations:
+
+- In some functions that require a valid pointer, “parameter validation” checks
+that the pointer is non-null. With the feature disabled, a null pointer is not
+treated differently from any other invalid pointer, and typically leads to a
+runtime crash. 90% of the uses of the feature are of this kind.
+- In some functions that take an enum-like argument, “parameter validation”
+checks that the value is a valid one. With the feature disabled, an invalid
+value causes a silent default to one of the valid values.
+
+The default reaction to a failed check is to call a function mbedtls_param_failed
+which the application must provide. If this function returns, its caller returns
+an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`.
+
+This feature is only used in some classic (non-PSA) cryptography modules. It is
+not used in X.509, TLS or in PSA crypto, and it has not been implemented in all
+classic crypto modules.
+
+Removal of `MBEDTLS_CHECK_PARAMS` and all dependent features means changing
+code that does something like this:
+```
+#if MBEDTLS_CHECK_PARAMS
+#define VALIDATE(cond) do {if(cond) return BAD_INPUT_DATA;} while (0)
+#else
+#define VALIDATE(cond) do {} while (0)
+#endif
+...
+VALIDATE(coin == HEADS || coin == TAILS);
+VALIDATE(data != NULL);
+if (coin == HEADS) heads();
+else tails();
+```
+to something like this:
+```
+if (coin == HEADS) heads();
+else if (coin == TAILS) tails();
+else return BAD_INPUT_DATA;
+```
+
+Validation of enum-like values is somewhat useful, but not extremely important,
+because the parameters concerned are usually constants in applications.
+
+For more information see issue #4313.