Merge remote-tracking branch 'tls/development' into development
Resolve conflicts by performing the following operations:
- Reject changes related to building a crypto submodule, since Mbed
Crypto is the crypto submodule.
- Reject X.509, NET, and SSL changes.
- Reject changes to README, as Mbed Crypto is a different project from
Mbed TLS, with a different README.
- Avoid adding mention of ssl-opt.sh in a comment near some modified
code in include/CMakeLists.txt (around where ENABLE_TESTING as added).
- Align config.pl in Mbed TLS with config.pl in Mbed Crypto where PSA
options are concerned, to make future merging easier. There is no
reason for the two to be different in this regard, now that Mbed TLS
always depends on Mbed Crypto. Remaining differences are only the
PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER option and the absence of X.509,
NET, and SSL related options in Mbed Crypto's config.pl.
- Align config.h in Mbed Crypto with Mbed TLS's copy, with a few notable
exceptions:
- Leave CMAC on by default.
- Leave storage on by default (including ITS emulation).
- Avoid documenting the PSA Crypto API as is in beta stage in
documentation for MBEDTLS_PSA_CRYPTO_C.
The only remaining differences are a lack of X.509, NET, and SSL
options in Mbed Crypto's config.h, as well as an additional
Mbed-Crypto-specific PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER option.
Documentation for the check params feature and related macros is also
updated to match Mbed TLS's description.
- Reject tests/data_files/Makefile changes to generate DER versions of
CRTs and keys, as none of those are used by Mbed Crypto tests.
- Add the "no PEM and no filesystem" test to all.sh, without ssl-opt.sh
run, as Mbed Crypto doesn't have ssl-opt.sh. Also remove use of PSA
Crypto storage and ITS emulation, since those depend on filesystem
support.
- Reject addition of test when no ciphersuites have MAC to all.sh, as
the option being tested, MBEDTLS_SSL_SOME_MODES_USE_MAC, is not
present in Mbed Crypto.
- Use baremetal config in all.sh, as Mbed Crypto's baremetal
configuration does exclude the net module (as it doesn't exist in Mbed
Crypto)
- Reject cmake_subproject_build changes, continuing to link only
libmbedcrypto.
- Reject changes to visualc and associated templates. Mbed Crypto
doesn't need additional logic to handle submodule-sourced headers.
- Avoid adding fuzzers from Mbed TLS. The only relevant fuzzers are the
privkey and pubkey fuzzers, but non-trivial work would be required to
integrate those into Mbed Crypto (more than is comfortable in a merge
commit).
- Reject addition of Docker wrappers for compat.sh and ssl-opt.sh, as
those are not present in Mbed Crypto.
- Remove calls to SSL-related scripts from basic-in-docker.sh
Fix test errors by performing the following:
- Avoid using a link that Doxygen can't seem to resolve in Mbed Crypto,
but can resolve in Mbed TLS. In documentation for
MBEDTLS_CHECK_PARAMS, don't attempt to link to MBEDTLS_PARAM_FAILED.
* origin/development: (339 commits)
Do not build fuzz on windows
No booleans and import config
Removing space before opening parenthesis
Style corrections
Syntax fix
Fixes warnings from MSVC
Add a linker flag to enable gcov in basic-build-test.sh
Update crypto submodule to a revision with the HAVEGE header changes
Test with MBEDTLS_ECP_RESTARTABLE
Allow TODO in code
Use the docstring in the command line help
Split _abi_compliance_command into smaller functions
Record the commits that were compared
Document how to build the typical argument for -s
Allow running /somewhere/else/path/to/abi_check.py
tests: Limit each log to 10 GiB
Warn if VLAs are used
Remove redundant compiler flag
Consistently spell -Wextra
Fix parsing issue when int parameter is in base 16
...
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index e795bb8..9476bd1 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -277,28 +277,52 @@
* For example, when a function accepts as input a pointer to a buffer that may
* contain untrusted data, and its documentation mentions that this pointer
* must not be NULL:
- * - the pointer is checked to be non-NULL only if this option is enabled
- * - the content of the buffer is always validated
+ * - The pointer is checked to be non-NULL only if this option is enabled.
+ * - The content of the buffer is always validated.
*
* When this flag is defined, if a library function receives a parameter that
- * is invalid, it will:
- * - invoke the macro MBEDTLS_PARAM_FAILED() which by default expands to a
- * call to the function mbedtls_param_failed()
- * - immediately return (with a specific error code unless the function
- * returns void and can't communicate an error).
+ * is invalid:
+ * 1. The function will invoke the macro MBEDTLS_PARAM_FAILED().
+ * 2. If MBEDTLS_PARAM_FAILED() did not terminate the program, the function
+ * will immediately return. If the function returns an Mbed TLS error code,
+ * the error code in this case is MBEDTLS_ERR_xxx_BAD_INPUT_DATA.
*
- * When defining this flag, you also need to:
- * - either provide a definition of the function mbedtls_param_failed() in
- * your application (see platform_util.h for its prototype) as the library
- * calls that function, but does not provide a default definition for it,
- * - or provide a different definition of the macro MBEDTLS_PARAM_FAILED()
- * below if the above mechanism is not flexible enough to suit your needs.
- * See the documentation of this macro later in this file.
+ * When defining this flag, you also need to arrange a definition for
+ * MBEDTLS_PARAM_FAILED(). You can do this by any of the following methods:
+ * - By default, the library defines MBEDTLS_PARAM_FAILED() to call a
+ * function mbedtls_param_failed(), but the library does not define this
+ * function. If you do not make any other arrangements, you must provide
+ * the function mbedtls_param_failed() in your application.
+ * See `platform_util.h` for its prototype.
+ * - If you enable the macro #MBEDTLS_CHECK_PARAMS_ASSERT, then the
+ * library defines MBEDTLS_PARAM_FAILED(\c cond) to be `assert(cond)`.
+ * You can still supply an alternative definition of
+ * MBEDTLS_PARAM_FAILED(), which may call `assert`.
+ * - If you define a macro MBEDTLS_PARAM_FAILED() before including `config.h`
+ * or you uncomment the definition of MBEDTLS_PARAM_FAILED() in `config.h`,
+ * the library will call the macro that you defined and will not supply
+ * its own version. Note that if MBEDTLS_PARAM_FAILED() calls `assert`,
+ * you need to enable #MBEDTLS_CHECK_PARAMS_ASSERT so that library source
+ * files include `<assert.h>`.
*
* Uncomment to enable validation of application-controlled parameters.
*/
//#define MBEDTLS_CHECK_PARAMS
+/**
+ * \def MBEDTLS_CHECK_PARAMS_ASSERT
+ *
+ * Allow MBEDTLS_PARAM_FAILED() to call `assert`, and make it default to
+ * `assert`. This macro is only used if #MBEDTLS_CHECK_PARAMS is defined.
+ *
+ * If this macro is not defined, then MBEDTLS_PARAM_FAILED() defaults to
+ * calling a function mbedtls_param_failed(). See the documentation of
+ * #MBEDTLS_CHECK_PARAMS for details.
+ *
+ * Uncomment to allow MBEDTLS_PARAM_FAILED() to call `assert`.
+ */
+//#define MBEDTLS_CHECK_PARAMS_ASSERT
+
/* \} name SECTION: System support */
/**
@@ -1007,18 +1031,27 @@
/**
* \def MBEDTLS_USE_PSA_CRYPTO
*
- * Make the X.509 and TLS library use PSA for cryptographic operations, see
- * #MBEDTLS_PSA_CRYPTO_C.
+ * Make the X.509 and TLS library use PSA for cryptographic operations, and
+ * enable new APIs for using keys handled by PSA Crypto.
*
- * Note: this option is still in progress, the full X.509 and TLS modules are
- * not covered yet, but parts that are not ported to PSA yet will still work
- * as usual, so enabling this option should not break backwards compatibility.
+ * \note Development of this option is currently in progress, and parts of Mbed
+ * TLS's X.509 and TLS modules are not ported to PSA yet. However, these parts
+ * will still continue to work as usual, so enabling this option should not
+ * break backwards compatibility.
*
- * \warning Support for PSA is still an experimental feature.
- * Any public API that depends on this option may change
- * at any time until this warning is removed.
+ * \warning Support for PSA is still an experimental feature.
+ * Any public API that depends on this option may change
+ * at any time until this warning is removed.
+ *
+ * \warning This option enables new Mbed TLS APIs that are dependent on the
+ * PSA Crypto API, so can't come with the same stability guarantees as the
+ * rest of the Mbed TLS APIs. You're welcome to experiment with them, but for
+ * now, access to these APIs is opt-in (via enabling the present option), in
+ * order to clearly differentiate them from the stable Mbed TLS APIs.
*
* Requires: MBEDTLS_PSA_CRYPTO_C.
+ *
+ * Uncomment this to enable internal use of PSA Crypto and new associated APIs.
*/
//#define MBEDTLS_USE_PSA_CRYPTO
@@ -1702,6 +1735,10 @@
*
* Enable the Platform Security Architecture cryptography API.
*
+ * \warning The PSA Crypto API is still beta status. While you're welcome to
+ * experiment using it, incompatible API changes are still possible, and some
+ * parts may not have reached the same quality as the rest of Mbed TLS yet.
+ *
* Module: library/psa_crypto.c
*
* Requires: MBEDTLS_CTR_DRBG_C, MBEDTLS_ENTROPY_C
@@ -1951,6 +1988,42 @@
//#define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */
/**
+ * \brief This macro is invoked by the library when an invalid parameter
+ * is detected that is only checked with #MBEDTLS_CHECK_PARAMS
+ * (see the documentation of that option for context).
+ *
+ * When you leave this undefined here, the library provides
+ * a default definition. If the macro #MBEDTLS_CHECK_PARAMS_ASSERT
+ * is defined, the default definition is `assert(cond)`,
+ * otherwise the default definition calls a function
+ * mbedtls_param_failed(). This function is declared in
+ * `platform_util.h` for the benefit of the library, but
+ * you need to define in your application.
+ *
+ * When you define this here, this replaces the default
+ * definition in platform_util.h (which no longer declares the
+ * function mbedtls_param_failed()) and it is your responsibility
+ * to make sure this macro expands to something suitable (in
+ * particular, that all the necessary declarations are visible
+ * from within the library - you can ensure that by providing
+ * them in this file next to the macro definition).
+ * If you define this macro to call `assert`, also define
+ * #MBEDTLS_CHECK_PARAMS_ASSERT so that library source files
+ * include `<assert.h>`.
+ *
+ * Note that you may define this macro to expand to nothing, in
+ * which case you don't have to worry about declarations or
+ * definitions. However, you will then be notified about invalid
+ * parameters only in non-void functions, and void function will
+ * just silently return early on invalid parameters, which
+ * partially negates the benefits of enabling
+ * #MBEDTLS_CHECK_PARAMS in the first place, so is discouraged.
+ *
+ * \param cond The expression that should evaluate to true, but doesn't.
+ */
+//#define MBEDTLS_PARAM_FAILED( cond ) assert( cond )
+
+/**
* Uncomment the macro to let mbed TLS use your alternate implementation of
* mbedtls_platform_zeroize(). This replaces the default implementation in
* platform_util.c.