diff --git a/ChangeLog.d/issue4313.txt b/ChangeLog.d/issue4313.txt new file mode 100644 index 0000000000..e240a124da --- /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 0000000000..146b1c7592 --- /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.