diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..b9f146808a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,35 @@ +--- +name: Bug report +about: To report a bug, please fill this form. +title: '' +labels: '' +assignees: '' + +--- + +### Summary + + + +### System information + +Mbed TLS version (number or commit id): +Operating system and version: +Configuration (if not default, please attach `config.h`): +Compiler and options (if you used a pre-built binary, please indicate how you obtained it): +Additional environment information: + +### Expected behavior + + + +### Actual behavior + + + +### Steps to reproduce + + + +### Additional information + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..63076f4057 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Mbed TLS security team + url: mailto:mbed-tls-security@lists.trustedfirmware.org + about: Report a security vulnerability. + - name: Mbed TLS mailing list + url: https://lists.trustedfirmware.org/mailman/listinfo/mbed-tls + about: Mbed TLS community support and general discussion. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000..3b515137b2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Enhancement request +about: To request an enhancement, please fill this form. +title: '' +labels: '' +assignees: '' + +--- + +### Suggested enhancement + + + +### Justification + +Mbed TLS needs this because + diff --git a/.github/issue_template.md b/.github/issue_template.md deleted file mode 100644 index 370066f486..0000000000 --- a/.github/issue_template.md +++ /dev/null @@ -1,46 +0,0 @@ -_Note:_ this is a template, please remove the parts that are not -applicable (these initial notes, and the "Bug" section for a Feature request -and vice-versa). - -**Note:** to report a security vulnerability, see -[SECURITY.md](../SECURITY.md). Please do not use github issues for -vulnerabilities. - -_Note:_ to get support, see [SUPPORT.md](../SUPPORT.md). Please do not use -github issues for questions. - ---------------------------------------------------------------- -### Description -- Type: Bug | Enhancement / Feature Request -- Priority: Blocker | Major | Minor - ---------------------------------------------------------------- -## Bug - -**OS** -Mbed OS|linux|windows| - -**mbed TLS build:** -Version: x.x.x or git commit id -OS version: x.x.x -Configuration: please attach config.h file where possible -Compiler and options (if you used a pre-built binary, please indicate how you obtained it): -Additional environment information: - -**Peer device TLS stack and version** -OpenSSL|GnuTls|Chrome|NSS(Firefox)|SecureChannel (IIS/Internet Explorer/Edge)|Other -Version: - -**Expected behavior** - -**Actual behavior** - -**Steps to reproduce** - ----------------------------------------------------------------- -## Enhancement / Feature Request - -**Suggested enhancement** - -**Justification - why does the library need this feature?** - diff --git a/.travis.yml b/.travis.yml index 542f705694..48faa4846c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -28,12 +28,6 @@ jobs: script: - tests/scripts/all.sh -k test_full_cmake_gcc_asan - - name: macOS - os: osx - compiler: clang - script: - - tests/scripts/all.sh -k test_default_out_of_box - - name: Windows os: windows before_install: diff --git a/BRANCHES.md b/BRANCHES.md index 8486ef0637..b9926ac9df 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -16,9 +16,10 @@ At any point in time, we have a number of maintained branches consisting of: these only get bug fixes and security fixes. We use [Semantic Versioning](https://semver.org/). In particular, we maintain -API compatibility in the `master` branch between major version changes. We -also maintain ABI compatibility within LTS branches; see the next section for -details. +API compatibility in the `master` branch across minor version changes (e.g. +the API of 3.(x+1) is backward compatible with 3.x). We only break API +compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain +ABI compatibility within LTS branches; see the next section for details. ## Backwards Compatibility @@ -28,11 +29,28 @@ undocumented features, then you should be able to re-compile it without modification with any later release x.y'.z' with the same major version number, and your code will still build, be secure, and work. -There are rare exceptions: code that was relying on something that became -insecure in the meantime (for example, crypto that was found to be weak) may -need to be changed. In case security comes in conflict with backwards -compatibility, we will put security first, but always attempt to provide a -compatibility option. +Note that new releases of Mbed TLS may extend the API. Here are some +examples of changes that are common in minor releases of Mbed TLS, and are +not considered API compatibility breaks: + +* Adding or reordering fields in a structure or union. +* Removing a field from a structure, unless the field is documented as public. +* Adding items to an enum. +* Returning an error code that was not previously documented for a function + when a new error condition arises. +* Changing which error code is returned in a case where multiple error + conditions apply. +* Changing the behavior of a function from failing to succeeding, when the + change is a reasonable extension of the current behavior, i.e. the + addition of a new feature. + +There are rare exceptions where we break API compatibility: code that was +relying on something that became insecure in the meantime (for example, +crypto that was found to be weak) may need to be changed. In case security +comes in conflict with backwards compatibility, we will put security first, +but always attempt to provide a compatibility option. + +## Long-time support branches For the LTS branches, additionally we try very hard to also maintain ABI compatibility (same definition as API except with re-linking instead of diff --git a/CMakeLists.txt b/CMakeLists.txt index f648f2299b..efe3cab65a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,9 @@ # mbedtls, mbedx509, mbedcrypto and apidoc targets. # -cmake_minimum_required(VERSION 2.8.12) +# We specify a minimum requirement of 3.10.2, but for now use 3.5.1 here +# until our infrastructure catches up. +cmake_minimum_required(VERSION 3.5.1) # https://cmake.org/cmake/help/latest/policy/CMP0011.html # Setting this policy is required in CMake >= 3.18.0, otherwise a warning is generated. The OLD diff --git a/ChangeLog b/ChangeLog index dc6e4515d2..ddaf3fd9f7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -22,7 +22,7 @@ API changes Various helpers and definitions available for use in alt implementations have been moved out of the include/ directory and into the library/ directory. The files concerned are ecp_internal.h and rsa_internal.h - which have also been renamed to ecp_alt.h and rsa_alt_helpers.h + which have also been renamed to ecp_internal_alt.h and rsa_alt_helpers.h respectively. * Move internal headers. Header files that were only meant for the library's internal use and diff --git a/ChangeLog.d/alt-context-relaxation.txt b/ChangeLog.d/alt-context-relaxation.txt new file mode 100644 index 0000000000..10fd476192 --- /dev/null +++ b/ChangeLog.d/alt-context-relaxation.txt @@ -0,0 +1,6 @@ +Features + * Alternative implementations of the AES, DHM, ECJPAKE, ECP, RSA and timing + modules had undocumented constraints on their context types. These + constraints have been relaxed. + See docs/architecture/alternative-implementations.md for the remaining + constraints. diff --git a/ChangeLog.d/dhm-fields.txt b/ChangeLog.d/dhm-fields.txt new file mode 100644 index 0000000000..4d5c751fba --- /dev/null +++ b/ChangeLog.d/dhm-fields.txt @@ -0,0 +1,9 @@ +Features + * The new functions mbedtls_dhm_get_len() and mbedtls_dhm_get_bitlen() + query the size of the modulus in a Diffie-Hellman context. + * The new function mbedtls_dhm_get_value() copy a field out of a + Diffie-Hellman context. + +API changes + * Instead of accessing the len field of a DHM context, which is no longer + supported, use the new function mbedtls_dhm_get_len() . diff --git a/ChangeLog.d/ecjpake-point_format.txt b/ChangeLog.d/ecjpake-point_format.txt new file mode 100644 index 0000000000..6e05b23393 --- /dev/null +++ b/ChangeLog.d/ecjpake-point_format.txt @@ -0,0 +1,4 @@ +Features + * Use the new function mbedtls_ecjpake_set_point_format() to select the + point format for ECJPAKE instead of accessing the point_format field + directly, which is no longer supported. diff --git a/ChangeLog.d/ecp_max_bits.txt b/ChangeLog.d/ecp_max_bits.txt new file mode 100644 index 0000000000..b952469196 --- /dev/null +++ b/ChangeLog.d/ecp_max_bits.txt @@ -0,0 +1,3 @@ +Removals + * MBEDTLS_ECP_MAX_BITS is no longer a configuration option because it is + now determined automatically based on supported curves. diff --git a/ChangeLog.d/fix-ssl-cf-hmac-alt.txt b/ChangeLog.d/fix-ssl-cf-hmac-alt.txt new file mode 100644 index 0000000000..57ffa02e2a --- /dev/null +++ b/ChangeLog.d/fix-ssl-cf-hmac-alt.txt @@ -0,0 +1,5 @@ +Bugfix + * Fix a regression introduced in 2.24.0 which broke (D)TLS CBC ciphersuites + (when the encrypt-then-MAC extension is not in use) with some ALT + implementations of the underlying hash (SHA-1, SHA-256, SHA-384), causing + the affected side to wrongly reject valid messages. Fixes #4118. diff --git a/ChangeLog.d/issue4083.txt b/ChangeLog.d/issue4083.txt new file mode 100644 index 0000000000..845733702f --- /dev/null +++ b/ChangeLog.d/issue4083.txt @@ -0,0 +1,4 @@ +Removals + * Remove the following functions: mbedtls_timing_self_test(), + mbedtls_hardclock_poll(), mbedtls_timing_hardclock() and + mbedtls_set_alarm(). Fixes #4083. diff --git a/ChangeLog.d/issue4084.txt b/ChangeLog.d/issue4084.txt new file mode 100644 index 0000000000..75273c1bdc --- /dev/null +++ b/ChangeLog.d/issue4084.txt @@ -0,0 +1,4 @@ +Removals + * Remove all support for MD2, MD4, RC4, Blowfish and XTEA. This removes the + corresponding modules and all their APIs and related configuration + options. Fixes #4084. diff --git a/ChangeLog.d/issue4212.txt b/ChangeLog.d/issue4212.txt new file mode 100644 index 0000000000..9e72ca9d77 --- /dev/null +++ b/ChangeLog.d/issue4212.txt @@ -0,0 +1,6 @@ +API changes + * In modules that implement cryptographic hash functions, many functions + mbedtls_xxx() now return int instead of void, and the corresponding + function mbedtls_xxx_ret() which was identical except for returning int + has been removed. This also concerns mbedtls_xxx_drbg_update(). See the + migration guide for more information. Fixes #4212. diff --git a/ChangeLog.d/issue4286.txt b/ChangeLog.d/issue4286.txt index 813b2ecfba..75d2f0928f 100644 --- a/ChangeLog.d/issue4286.txt +++ b/ChangeLog.d/issue4286.txt @@ -1,11 +1,10 @@ Removals - * Remove the TLS 1.0, TLS 1.1 and DTLS 1.0 support by removing the following - library constants: MBEDTLS_SSL_PROTO_TLS1, - MBEDTLS_SSL_PROTO_TLS1_1, MBEDTLS_SSL_CBC_RECORD_SPLITTING, - MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED, - MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED, - MBEDTLS_SSL_FALLBACK_SCSV, MBEDTLS_SSL_FALLBACK_SCSV_VALUE, - MBEDTLS_SSL_IS_FALLBACK, MBEDTLS_SSL_IS_NOT_FALLBACK, and functions: + * Remove support for TLS 1.0, TLS 1.1 and DTLS 1.0, as well as support for + CBC record splitting, fallback SCSV, and the ability to configure + ciphersuites per version, which are no longer relevant. This removes the + configuration options MBEDTLS_SSL_PROTO_TLS1, + MBEDTLS_SSL_PROTO_TLS1_1, MBEDTLS_SSL_CBC_RECORD_SPLITTING and + MBEDTLS_SSL_FALLBACK_SCSV as well as the functions mbedtls_ssl_conf_cbc_record_splitting(), - mbedtls_ssl_get_key_exchange_md_ssl_tls(), mbedtls_ssl_conf_fallback(). - Fixes #4286. + mbedtls_ssl_get_key_exchange_md_ssl_tls(), mbedtls_ssl_conf_fallback(), + and mbedtls_ssl_conf_ciphersuites_for_version(). Fixes #4286. diff --git a/ChangeLog.d/issue4313.txt b/ChangeLog.d/issue4313.txt new file mode 100644 index 0000000000..1fb61234be --- /dev/null +++ b/ChangeLog.d/issue4313.txt @@ -0,0 +1,4 @@ +Removals + * Remove the following macros: MBEDTLS_CHECK_PARAMS, + MBEDTLS_CHECK_PARAMS_ASSERT, MBEDTLS_PARAM_FAILED, + MBEDTLS_PARAM_FAILED_ALT. Fixes #4313. diff --git a/ChangeLog.d/issue4378.txt b/ChangeLog.d/issue4378.txt new file mode 100644 index 0000000000..9a7522b3ab --- /dev/null +++ b/ChangeLog.d/issue4378.txt @@ -0,0 +1,4 @@ +Removals + * Remove the MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION config.h + option. The mbedtls_x509_crt_parse_der_with_ext_cb() is the way to go for + migration path. Fixes #4378. diff --git a/ChangeLog.d/issue4398.txt b/ChangeLog.d/issue4398.txt new file mode 100644 index 0000000000..b7f241391e --- /dev/null +++ b/ChangeLog.d/issue4398.txt @@ -0,0 +1,3 @@ +API changes + * Replace MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE by a runtime + configuration function mbedtls_ssl_conf_preference_order(). Fixes #4398. diff --git a/ChangeLog.d/issue4405.txt b/ChangeLog.d/issue4405.txt new file mode 100644 index 0000000000..c36aefa154 --- /dev/null +++ b/ChangeLog.d/issue4405.txt @@ -0,0 +1,4 @@ +Removals + * Remove the MBEDTLS_X509_CHECK_KEY_USAGE and + MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE config.h options and let the code + behave as if they were always enabled. Fixes #4405. diff --git a/ChangeLog.d/mandatory-rng-param.txt b/ChangeLog.d/mandatory-rng-param.txt new file mode 100644 index 0000000000..39ee335339 --- /dev/null +++ b/ChangeLog.d/mandatory-rng-param.txt @@ -0,0 +1,14 @@ +API changes + * For all functions that take a random number generator (RNG) as a + 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 and RSA + sign and decrypt function; mbedtls_rsa_private(); the functions + in DHM and ECDH that compute the shared 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(). +Removals + * The configuration option MBEDTLS_ECP_NO_INTERNAL_RNG has been removed as + it no longer had any effect. diff --git a/ChangeLog.d/max-record-payload-api.txt b/ChangeLog.d/max-record-payload-api.txt new file mode 100644 index 0000000000..02b47e4e1b --- /dev/null +++ b/ChangeLog.d/max-record-payload-api.txt @@ -0,0 +1,9 @@ +API changes + * Remove the SSL APIs mbedtls_ssl_get_input_max_frag_len() and + mbedtls_ssl_get_output_max_frag_len(), and add a new API + mbedtls_ssl_get_max_in_record_payload(), complementing the existing + mbedtls_ssl_get_max_out_record_payload(). + Uses of mbedtls_ssl_get_input_max_frag_len() and + mbedtls_ssl_get_input_max_frag_len() should be replaced by + mbedtls_ssl_get_max_in_record_payload() and + mbedtls_ssl_get_max_out_record_payload(), respectively. diff --git a/ChangeLog.d/mbed-can-do-timing.txt b/ChangeLog.d/mbed-can-do-timing.txt new file mode 100644 index 0000000000..d83da02432 --- /dev/null +++ b/ChangeLog.d/mbed-can-do-timing.txt @@ -0,0 +1,3 @@ +Bugfix + * Remove outdated check-config.h check that prevented implementing the + timing module on Mbed OS. Fixes #4633. diff --git a/ChangeLog.d/psa_key_derivation-bad_workflow.txt b/ChangeLog.d/psa_key_derivation-bad_workflow.txt new file mode 100644 index 0000000000..7fd03e6c9e --- /dev/null +++ b/ChangeLog.d/psa_key_derivation-bad_workflow.txt @@ -0,0 +1,3 @@ +Bugfix + * Fix PSA_ALG_TLS12_PRF and PSA_ALG_TLS12_PSK_TO_MS being too permissive + about missing inputs. diff --git a/ChangeLog.d/remove-rsa-mode-parameter.txt b/ChangeLog.d/remove-rsa-mode-parameter.txt index 854dda34b2..2590d3a949 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/ChangeLog.d/rsa-padding.txt b/ChangeLog.d/rsa-padding.txt new file mode 100644 index 0000000000..5f9c11f717 --- /dev/null +++ b/ChangeLog.d/rsa-padding.txt @@ -0,0 +1,5 @@ +API changes + * mbedtls_rsa_init() now always selects the PKCS#1v1.5 encoding for an RSA + key. To use an RSA key with PSS or OAEP, call mbedtls_rsa_set_padding() + after initializing the context. mbedtls_rsa_set_padding() now returns an + error if its parameters are invalid. diff --git a/ChangeLog.d/tool-versions.txt b/ChangeLog.d/tool-versions.txt new file mode 100644 index 0000000000..b89b384aa3 --- /dev/null +++ b/ChangeLog.d/tool-versions.txt @@ -0,0 +1,4 @@ +Requirement changes + * Refresh the minimum supported versions of tools to build the + library. CMake versions older than 3.10.2 and Python older + than 3.6 are no longer supported. diff --git a/ChangeLog.d/winsock.txt b/ChangeLog.d/winsock.txt new file mode 100644 index 0000000000..0b42e691c2 --- /dev/null +++ b/ChangeLog.d/winsock.txt @@ -0,0 +1,4 @@ +Bugfix + * Fix mbedtls_net_poll() and mbedtls_net_recv_timeout() often failing with + MBEDTLS_ERR_NET_POLL_FAILED on Windows. Fixes #4465. + diff --git a/README.md b/README.md index 3f41a0d76d..78d3c30cfd 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Documentation for the Mbed TLS interfaces in the default library configuration i To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: -1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. We use version 1.8.11 but slightly older or more recent versions should work. +1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. 1. Run `make apidoc`. 1. Browse `apidoc/index.html` or `apidoc/modules.html`. @@ -39,7 +39,7 @@ There are currently three active build systems used within Mbed TLS releases: - GNU Make - CMake -- Microsoft Visual Studio (Microsoft Visual Studio 2013 or later) +- Microsoft Visual Studio The main systems used for development are CMake and GNU Make. Those systems are always complete and up-to-date. The others should reflect all changes present in the CMake and Make build system, although features may not be ported there automatically. @@ -49,10 +49,13 @@ The Make and CMake build systems create three libraries: libmbedcrypto, libmbedx You need the following tools to build the library with the provided makefiles: -* GNU Make or a build tool that CMake supports. -* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, IAR8 and Visual Studio 2013. More recent versions should work. Slightly older versions may work. -* Python 3 to generate the test code, and to generate sample programs in the development branch. +* GNU Make 3.82 or a build tool that CMake supports. +* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, IAR 8 and Visual Studio 2013. More recent versions should work. Slightly older versions may work. +* Python 3.6 to generate the test code, and to generate sample programs in the development branch. * Perl to run the tests, and to generate some source files in the development branch. +* CMake 3.10.2 or later (if using CMake). +* Microsoft Visual Studio 2013 or later (if using Visual Studio). +* Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work). ### Generated source files in the development branch diff --git a/configs/config-no-entropy.h b/configs/config-no-entropy.h index 09b3cf5e0a..7ca33c3816 100644 --- a/configs/config-no-entropy.h +++ b/configs/config-no-entropy.h @@ -49,8 +49,6 @@ #define MBEDTLS_PKCS1_V21 #define MBEDTLS_SELF_TEST #define MBEDTLS_VERSION_FEATURES -#define MBEDTLS_X509_CHECK_KEY_USAGE -#define MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE /* mbed TLS modules */ #define MBEDTLS_AES_C diff --git a/configs/config-suite-b.h b/configs/config-suite-b.h index 28e6443124..b62bdfabd0 100644 --- a/configs/config-suite-b.h +++ b/configs/config-suite-b.h @@ -84,8 +84,7 @@ #define MBEDTLS_AES_ROM_TABLES /* Save RAM by adjusting to our exact needs */ -#define MBEDTLS_ECP_MAX_BITS 384 -#define MBEDTLS_MPI_MAX_SIZE 48 // 384 bits is 48 bytes +#define MBEDTLS_MPI_MAX_SIZE 48 // 384-bit EC curve = 48 bytes /* Save RAM at the expense of speed, see ecp.h */ #define MBEDTLS_ECP_WINDOW_SIZE 2 diff --git a/configs/config-symmetric-only.h b/configs/config-symmetric-only.h index 29e77b52c9..5b10063277 100644 --- a/configs/config-symmetric-only.h +++ b/configs/config-symmetric-only.h @@ -47,11 +47,9 @@ /* Mbed Crypto modules */ #define MBEDTLS_AES_C -#define MBEDTLS_ARC4_C #define MBEDTLS_ASN1_PARSE_C #define MBEDTLS_ASN1_WRITE_C #define MBEDTLS_BASE64_C -#define MBEDTLS_BLOWFISH_C #define MBEDTLS_CAMELLIA_C #define MBEDTLS_ARIA_C #define MBEDTLS_CCM_C @@ -68,8 +66,6 @@ #define MBEDTLS_HMAC_DRBG_C #define MBEDTLS_NIST_KW_C #define MBEDTLS_MD_C -#define MBEDTLS_MD2_C -#define MBEDTLS_MD4_C #define MBEDTLS_MD5_C #define MBEDTLS_OID_C #define MBEDTLS_PEM_PARSE_C @@ -94,7 +90,6 @@ //#define MBEDTLS_THREADING_C #define MBEDTLS_TIMING_C #define MBEDTLS_VERSION_C -#define MBEDTLS_XTEA_C #include "mbedtls/config_psa.h" diff --git a/configs/config-thread.h b/configs/config-thread.h index bce9668fd0..c1937de80a 100644 --- a/configs/config-thread.h +++ b/configs/config-thread.h @@ -85,8 +85,7 @@ #define MBEDTLS_AES_ROM_TABLES /* Save RAM by adjusting to our exact needs */ -#define MBEDTLS_ECP_MAX_BITS 256 -#define MBEDTLS_MPI_MAX_SIZE 32 // 256 bits is 32 bytes +#define MBEDTLS_MPI_MAX_SIZE 32 // 256-bit EC curve = 32 bytes /* Save ROM and a few bytes of RAM by specifying our own ciphersuite list */ #define MBEDTLS_SSL_CIPHERSUITES MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8 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 0000000000..f6aba08b11 --- /dev/null +++ b/docs/3.0-migration-guide.d/mandatory-rng-param.md @@ -0,0 +1,40 @@ +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 and +RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM +and ECDH that compute the shared 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. + +Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` +configuration options) may have their own internal and are free to ignore the +`f_rng` argument but must allow users to pass one anyway. + +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/max-record-payload-api.md b/docs/3.0-migration-guide.d/max-record-payload-api.md new file mode 100644 index 0000000000..0b34915f40 --- /dev/null +++ b/docs/3.0-migration-guide.d/max-record-payload-api.md @@ -0,0 +1,11 @@ +Remove MaximumFragmentLength (MFL) query API +----------------------------------------------------------------- + +This affects users which use the MFL query APIs +`mbedtls_ssl_get_{input,output}_max_frag_len()` to +infer upper bounds on the plaintext size of incoming and +outgoing record. + +Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` +instead, which also provides such upper bounds but takes more factors +than just the MFL configuration into account. diff --git a/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md b/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md new file mode 100644 index 0000000000..fa61e274bd --- /dev/null +++ b/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md @@ -0,0 +1,9 @@ +Move part of timing module out of the library +-- + +The change affects users who use any of the following functions: +`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, +`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`. + +If you were relying on these functions, you'll now need to change to using your +platform's corresponding functions directly. 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 e400650dd0..d21d5ed85e 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. diff --git a/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md b/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md new file mode 100644 index 0000000000..a4a4895a8f --- /dev/null +++ b/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md @@ -0,0 +1,23 @@ +Remove the SSL API mbedtls_ssl_get_session_pointer() +----------------------------------------------------------------- + +This affects two classes of users: + +1. Users who manually inspect parts of the current session through + direct structure field access. + +2. Users of session resumption who query the current session + via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting + it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, + respectively. + +Migration paths: + +1. Mbed TLS 3.0 does not offer a migration path for the usecase 1: Like many + other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no + longer part of the public API in Mbed TLS 3.0, and direct structure field + access is no longer supported. Please see the corresponding migration guide. + +2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by + calls to `mbedtls_ssl_get_session()` as demonstrated in the example + program `programs/ssl/ssl_client2.c`. diff --git a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md new file mode 100644 index 0000000000..738fa81fd1 --- /dev/null +++ b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md @@ -0,0 +1,17 @@ +Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION +-------------------------------------------------------------------------- + +This change does not affect users of the default configuration; it only affect +users who enable this option. + +The X.509 standard says that implementations must reject critical extensions that +they don't recognize, and this is what Mbed TLS does by default. This option +allowed to continue parsing those certificates but didn't provide a convenient +way to handle those extensions. + +The migration path from that option is to use the +`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally +equivalent to `mbedtls_x509_crt_parse_der()`, and/or +`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every +unsupported certificate extension and additionally the "certificate policies" +extension if it contains any unsupported certificate policies. diff --git a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md new file mode 100644 index 0000000000..2acb3bfbe6 --- /dev/null +++ b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md @@ -0,0 +1,18 @@ +Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `config.h` +------------------------------------------------------------------- + +This change affects users who have chosen the configuration options to disable the +library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 +certificates. + +The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` +configuration options are removed and the X509 code now behaves as if they were +always enabled. It is consequently not possible anymore to disable at compile +time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509 +certificates. + +The verification of the `keyUsage` and `extendedKeyUsage` fields is important, +disabling it can cause security issues and it is thus not recommended. If the +verification is for some reason undesirable, it can still be disabled by means +of the verification callback function passed to `mbedtls_x509_crt_verify()` (see +the documentation of this function for more information). diff --git a/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md b/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md new file mode 100644 index 0000000000..d199f2f13f --- /dev/null +++ b/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md @@ -0,0 +1,8 @@ +Remove MD2, MD4, RC4, Blowfish and XTEA algorithms +-- + +This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. + +They are already niche or obsolete and most of them are weak or broken. For +those reasons possible users should consider switching to modern and safe +alternatives to be found in literature. diff --git a/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md b/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md index b18b3109d8..31c2ce8621 100644 --- a/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md +++ b/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md @@ -50,7 +50,9 @@ The function `mbedtls_ssl_conf_dh_param()` was removed. Please use `mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use -`mbedtls_ssl_get_output_max_frag_len()` instead. +`mbedtls_ssl_get_max_out_record_payload()` and +`mbedtls_ssl_get_max_in_record_payload()` +instead. Deprecated hex-encoded primes were removed from DHM --------------------------------------------------- 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..6f43aa37a8 --- /dev/null +++ b/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md @@ -0,0 +1,33 @@ +Remove MBEDTLS_CHECK_PARAMS option +---------------------------------- + +This change does not affect users who use the default configuration; it only +affects users who enabled that option. + +The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds +of “parameter validation”. It covered 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 was to call a function +`mbedtls_param_failed()` which the application had to provide. If this function +returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`. + +This feature was only used in some classic (non-PSA) cryptography modules. It was +not used in X.509, TLS or in PSA crypto, and it was not implemented in all +classic crypto modules. + +This feature has been removed. The library no longer checks for NULL pointers; +checks for enum-like arguments will be kept or re-introduced on a case-by-case +basis, but their presence will no longer be dependent on a compile-time option. + +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. diff --git a/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md b/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md index 4beebe240d..73d621f781 100644 --- a/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md +++ b/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md @@ -3,9 +3,25 @@ Remove suport for TLS 1.0, 1.1 and DTLS 1.0 This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols. -The versions of (D)TLS that are being removed are not as secure as the latest -versions. Keeping them in the library creates opportunities for misconfiguration +These versions have been deprecated by RFC 8996. +Keeping them in the library creates opportunities for misconfiguration and possibly downgrade attacks. More generally, more code means a larger attack surface, even if the code is supposedly not used. The migration path is to adopt the latest versions of the protocol. + +As a consequence of removing TLS 1.0, support for CBC record splitting was +also removed, as it was a work-around for a weakness in this particular +version. There is no migration path since the feature is no longer relevant. + +As a consequence of currently supporting only one version of (D)TLS (and in the +future 1.3 which will have a different version negociation mechanism), support +for fallback SCSV (RFC 7507) was also removed. There is no migration path as +it's no longer useful with TLS 1.2 and later. + +As a consequence of currently supporting only one version of (D)TLS (and in the +future 1.3 which will have a different concept of ciphersuites), support for +configuring ciphersuites separately for each version via +`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use +`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS +1.2; in the future a different API will be added for (D)TLS 1.3. diff --git a/docs/3.0-migration-guide.d/rename_the__ret_functions.md b/docs/3.0-migration-guide.d/rename_the__ret_functions.md new file mode 100644 index 0000000000..875164b25b --- /dev/null +++ b/docs/3.0-migration-guide.d/rename_the__ret_functions.md @@ -0,0 +1,43 @@ +Rename mbedtls_*_ret() cryptography functions whose deprecated variants +have been removed +----------------- + +This change affects users who were using the `mbedtls_*_ret()` cryptography +functions. + +Those functions were created based on now-deprecated functions according to a +requirement that a function needs to return a value. This change brings back the +original names of those functions. The renamed functions are: + +| name before this change | after the change | +|------------------------------|--------------------------| +| mbedtls_ctr_drbg_update_ret | mbedtls_ctr_drbg_update | +| mbedtls_hmac_drbg_update_ret | mbedtls_hmac_drbg_update | +| mbedtls_md5_starts_ret | mbedtls_md5_starts | +| mbedtls_md5_update_ret | mbedtls_md5_update | +| mbedtls_md5_finish_ret | mbedtls_md5_finish | +| mbedtls_md5_ret | mbedtls_md5 | +| mbedtls_ripemd160_starts_ret | mbedtls_ripemd160_starts | +| mbedtls_ripemd160_update_ret | mbedtls_ripemd160_update | +| mbedtls_ripemd160_finish_ret | mbedtls_ripemd160_finish | +| mbedtls_ripemd160_ret | mbedtls_ripemd160 | +| mbedtls_sha1_starts_ret | mbedtls_sha1_starts | +| mbedtls_sha1_update_ret | mbedtls_sha1_update | +| mbedtls_sha1_finish_ret | mbedtls_sha1_finish | +| mbedtls_sha1_ret | mbedtls_sha1 | +| mbedtls_sha256_starts_ret | mbedtls_sha256_starts | +| mbedtls_sha256_update_ret | mbedtls_sha256_update | +| mbedtls_sha256_finish_ret | mbedtls_sha256_finish | +| mbedtls_sha256_ret | mbedtls_sha256 | +| mbedtls_sha512_starts_ret | mbedtls_sha512_starts | +| mbedtls_sha512_update_ret | mbedtls_sha512_update | +| mbedtls_sha512_finish_ret | mbedtls_sha512_finish | +| mbedtls_sha512_ret | mbedtls_sha512 | + +To migrate to the this change the user can keep the `*_ret` names in their code +and include the `compat_2.x.h` header file which holds macros with proper +renaming or to rename those function in their code according to the list from +mentioned header file. + + + diff --git a/docs/3.0-migration-guide.d/rsa-padding.md b/docs/3.0-migration-guide.d/rsa-padding.md new file mode 100644 index 0000000000..f10ece6f8c --- /dev/null +++ b/docs/3.0-migration-guide.d/rsa-padding.md @@ -0,0 +1,29 @@ +Remove the padding parameters from mbedtls_rsa_init() +----------------------------------------------------- + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The function mbedtls_rsa_init() no longer supports selecting the PKCS#1 v2.1 +encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If +you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call +to mbedtls_rsa_init(), to call mbedtls_rsa_set_padding() to set it. + +To choose the padding type when initializing a context, instead of +```C + mbedtls_rsa_init(ctx, padding, hash_id); +``` +, use +```C + mbedtls_rsa_init(ctx); + mbedtls_rsa_set_padding(ctx, padding, hash_id); +``` + +To use PKCS#1 v1.5 padding, instead of +```C + mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); +``` +, just use +```C + mbedtls_rsa_init(ctx); +``` diff --git a/docs/3.0-migration-guide.d/ssl-ticket-api.md b/docs/3.0-migration-guide.d/ssl-ticket-api.md new file mode 100644 index 0000000000..23c53d671d --- /dev/null +++ b/docs/3.0-migration-guide.d/ssl-ticket-api.md @@ -0,0 +1,30 @@ +Modified semantics of mbedtls_ssl_{get,set}_session() +----------------------------------------------------------------- + +This affects users who call `mbedtls_ssl_get_session()` or +`mbedtls_ssl_set_session()` multiple times on the same SSL context +representing an established TLS 1.2 connection. +Those users will now observe the second call to fail with +`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. + +Migration path: +- Exporting the same TLS 1.2 connection multiple times via + `mbedtls_ssl_get_session()` leads to multiple copies of + the same session. This use of `mbedtls_ssl_get_session()` + is discouraged, and the following should be considered: + * If the various session copies are later loaded into + fresh SSL contexts via `mbedtls_ssl_set_session()`, + export via `mbedtls_ssl_get_session()` only once and + load the same session into different contexts via + `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()` + makes a copy of the session that's being loaded, this + is functionally equivalent. + * If the various session copies are later serialized + via `mbedtls_ssl_session_save()`, export and serialize + the session only once via `mbedtls_ssl_get_session()` and + `mbedtls_ssl_session_save()` and make copies of the raw + data instead. +- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x + is not useful since subsequent calls overwrite the effect of previous + calls. Applications achieve equivalent functional behaviour by + issuing only the very last call to `mbedtls_ssl_set_session()`. diff --git a/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md b/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md new file mode 100644 index 0000000000..6a6554dfb0 --- /dev/null +++ b/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md @@ -0,0 +1,14 @@ +Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option +-- + +This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE +option in the `config.h` + +This option has been removed and a new function with similar functionality has +been introduced into the SSL API. + +This new function `mbedtls_ssl_conf_preference_order()` can be used to +change the preferred order of ciphersuites on the server to those used on the client, +e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` +has the same effect as enabling the removed option. The default state is to use +the server order of suites. diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 2d031c6a4a..d0ba43d0f9 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -22,7 +22,7 @@ in order to match the new signature. Deprecated functions were removed from hashing modules ------------------------------------------------------ -Modules: MD2, MD4, MD5, SHA1, SHA256, SHA512, MD. +Modules: MD5, SHA1, SHA256, SHA512, MD. - The functions `mbedtls_xxx_starts()`, `mbedtls_xxx_update()`, `mbedtls_xxx_finish()` and `mbedtls_xxx()` were removed. Please use the @@ -59,7 +59,7 @@ were documented as internal, despite being in the public include directory. If you're providing alt implementations of ECP or RSA, you'll need to add our `library` directory to your include path when building your alt implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been -renamed to `ecp_alt.h` and `rsa_alt_helpers.h` respectively. +renamed to `ecp_internal_alt.h` and `rsa_alt_helpers.h` respectively. If you're a library user and used to rely on having access to a structure or function that's now in a private header, please reach out on the mailing list diff --git a/docs/architecture/alternative-implementations.md b/docs/architecture/alternative-implementations.md new file mode 100644 index 0000000000..7fe6332b47 --- /dev/null +++ b/docs/architecture/alternative-implementations.md @@ -0,0 +1,91 @@ +Alternative implementations of Mbed TLS functionality +===================================================== + +This document describes how parts of the Mbed TLS functionality can be replaced at compile time to integrate the library on a platform. + +This document is an overview. It is not exhaustive. Please consult the documentation of individual modules and read the library header files for more details. + +## Platform integration + +Mbed TLS works out of the box on Unix/Linux/POSIX-like systems and on Windows. On embedded platforms, you may need to customize some aspects of how Mbed TLS interacts with the underlying platform. This section discusses the main areas that can be configured. + +The platform module (`include/mbedtls/platform.h`) controls how Mbed TLS accesses standard library features such as memory management (`calloc`, `free`), `printf`, `exit`. You can define custom functions instead of the ones from the C standard library through `MBEDTLS_PLATFORM_XXX` options in the configuration file. Many options have two mechanisms: either define `MBEDTLS_PLATFORM_XXX_MACRO` to the name of a function to call instead of the standard function `xxx`, or define `MBEDTLS_PLATFORM_XXX_ALT` and [register an alternative implementation during the platform setup](#alternative-implementations-of-platform-functions). + +The storage of the non-volatile seed for random generation, enabled with `MBEDTLS_ENTROPY_NV_SEED`, is also controlled via the platform module. + +For timing functions, you can [declare an alternative implementation of the timing module](#module-alternative-implementations). + +On multithreaded platforms, [declare an alternative implementation of the threading module](#module-alternative-implementations). + +To configure entropy sources (hardware random generators), see the `MBEDTLS_ENTROPY_XXX` options in the configuration file. + +For networking, the `net_sockets` module does not currently support alternative implementations. If this module does not work on your platform, disable `MBEDTLS_NET_C` and use custom functions for TLS. + +If your platform has a cryptographic accelerator, you can use it via a [PSA driver](#psa-cryptography-drivers) or declare an [alternative implementation of the corresponding module(s)](#module-alternative-implementations) or [of specific functions](#function-alternative-implementations). PSA drivers will ultimately replace the alternative implementation mechanism, but alternative implementation will remain supported in at least all Mbed TLS versions of the form 3.x. The interface of PSA drivers is currently still experimental and subject to change. + +## PSA cryptography drivers + +On platforms where a hardware cryptographic engine is present, you can implement a driver for this engine in the PSA interface. Drivers are supported for cryptographic operations with transparent keys (keys available in cleartext), for cryptographic operations with opaque keys (keys that are only available inside the cryptographic engine), and for random generation. Calls to `psa_xxx` functions that perform cryptographic operations are directed to drivers instead of the built-in code as applicable. See the [PSA cryptography driver interface specification](docs/proposed/psa-driver-interface.md), the [Mbed TLS PSA driver developer guide](docs/proposed/psa-driver-developer-guide.md) and the [Mbed TLS PSA driver integration guide](docs/proposed/psa-driver-integration-guide.md) for more information. + +As of Mbed TLS 3.0, this interface is still experimental and subject to change, and not all operations support drivers yet. The configuration option `MBEDTLS_USE_PSA_CRYPTO` causes parts of the `mbedtls_xxx` API to use PSA crypto and therefore to support drivers, however it is not yet compatible with all drivers. + +## Module alternative implementations + +You can replace the code of some modules of Mbed TLS at compile time by a custom implementation. This is possible for low-level cryptography modules (symmetric algorithms, DHM, RSA, ECP, ECJPAKE) and for some platform-related modules (threading, timing). Such custom implementations are called “alternative implementations”, or “ALT implementations” for short. + +The general principle of an alternative implementation is: +* Enable `MBEDTLS_XXX_ALT` in the compile-time configuration where XXX is the module name. For example, `MBEDTLS_AES_ALT` for an implementation of the AES module. This is in addition to enabling `MBEDTLS_XXX_C`. +* Create a header file `xxx_alt.h` that defines the context type(s) used by the module. For example, `mbedtls_aes_context` for AES. +* Implement all the functions from the module, i.e. the functions declared in `include/mbedtls/xxx.h`. + +See https://tls.mbed.org/kb/development/hw_acc_guidelines for a more detailed guide. + +### Constraints on context types + +Generally, alternative implementations can define their context types to any C type except incomplete and array types (although they would normally be `struct` types). This section lists some known limitations where the context type needs to be a structure with certain fields. + +Where a context type needs to have a certain field, the field must have the same type and semantics as in the built-in implementation, but does not need to be at the same position in the structure. Furthermore, unless otherwise indicated, only read access is necessary: the field can be `const`, and modifications to it do not need to be supported. For example, if an alternative implementation of asymmetric cryptography uses a different representation of large integers, it is sufficient to provide a read-only copy of the fields listed here of type `mbedtls_mpi`. + +* AES: if `MBEDTLS_AESNI_C` or `MBEDTLS_PADLOCK_C` is enabled, `mbedtls_aes_context` must have the fields `nr` and `rk`. +* DHM: if `MBEDTLS_DEBUG_C` is enabled, `mbedtls_dhm_context` must have the fields `P`, `Q`, `G`, `GX`, `GY` and `K`. +* ECP: `mbedtls_ecp_group` must have the fields `id`, `P`, `A`, `B`, `G`, `N`, `pbits` and `nbits`. + * If `MBEDTLS_PK_PARSE_EC_EXTENDED` is enabled, those fields must be writable, and `mbedtls_ecp_point_read_binary()` must support a group structure where only `P`, `pbits`, `A` and `B` are set. + +It must be possible to move a context object in memory (except during the execution of a library function that takes this context as an argument). (This is necessary, for example, to support applications that populate a context on the stack of an inner function and then copy the context upwards through the call chain, or applications written in a language with automatic memory management that can move objects on the heap.) That is, call sequences like the following must work: +``` +mbedtls_xxx_context ctx1, ctx2; +mbedtls_xxx_init(&ctx1); +mbedtls_xxx_setup(&ctx1, …); +ctx2 = ctx1; +memset(&ctx1, 0, sizeof(ctx1)); +mbedtls_xxx_do_stuff(&ctx2, …); +mbedtls_xxx_free(&ctx2); +``` +In practice, this means that a pointer to a context or to a part of a context does not remain valid across function calls. Alternative implementations do not need to support copying of contexts: contexts can only be cloned through explicit `clone()` functions. + +## Function alternative implementations + +In some cases, it is possible to replace a single function or a small set of functions instead of [providing an alternative implementation of the whole module](#module-alternative-implementations). + +### Alternative implementations of cryptographic functions + +Options to replace individual functions of cryptographic modules generally have a name obtained by upper-casing the function name and appending `_ALT`. If the function name contains `_internal`, `_ext` or `_ret`, this is removed in the `_ALT` symbol. When the corresponding option is enabled, the built-in implementation of the function will not be compiled, and you must provide an alternative implementation at link time. + +For example, enable `MBEDTLS_AES_ENCRYPT_ALT` at compile time and provide your own implementation of `mbedtls_aes_encrypt()` to provide an accelerated implementation of AES encryption that is compatible with the built-in key schedule. If you wish to implement key schedule differently, you can also enable `MBEDTLS_AES_SETKEY_ENC_ALT` and implement `mbedtls_aes_setkey_enc()`. + +Another example: enable `MBEDTLS_SHA256_PROCESS_ALT` and implement `mbedtls_internal_sha256_process()` to provide an accelerated implementation of SHA-256 and SHA-224. + +Note that since alternative implementations of individual functions cooperate with the built-in implementation of other functions, you must use the same layout for context objects as the built-in implementation. If you want to use different context types, you need to [provide an alternative implementation of the whole module](#module-alternative-implementations). + +### Alternative implementations of platform functions + +Several platform functions can be reconfigured dynamically by following the process described here. To reconfigure how Mbed TLS calls the standard library function `xxx()`: + +* Define the symbol `MBEDTLS_PLATFORM_XXX_ALT` at compile time. +* During the initialization of your application, set the global variable `mbedtls_xxx` to an alternative implementation of `xxx()`. + +For example, to provide a custom `printf` function at run time, enable `MBEDTLS_PLATFORM_PRINTF_ALT` at compile time and assign to `mbedtls_printf` during the initialization of your application. + +Merely enabling `MBEDTLS_PLATFORM_XXX_ALT` does not change the behavior: by default, `mbedtls_xxx` points to the standard function `xxx`. + +Note that there are variations on the naming pattern. For example, some configurable functions are activated in pairs, such as `mbedtls_calloc` and `mbedtls_free` via `MBEDTLS_PLATFORM_MEMORY`. Consult the documentation of individual configuration options and of the platform module for details. diff --git a/doxygen/input/doc_encdec.h b/doxygen/input/doc_encdec.h index 46fb04fe38..96734bdd80 100644 --- a/doxygen/input/doc_encdec.h +++ b/doxygen/input/doc_encdec.h @@ -45,15 +45,11 @@ * - Symmetric: * - AES (see \c mbedtls_aes_crypt_ecb(), \c mbedtls_aes_crypt_cbc(), \c mbedtls_aes_crypt_cfb128() and * \c mbedtls_aes_crypt_ctr()). - * - ARCFOUR (see \c mbedtls_arc4_crypt()). - * - Blowfish / BF (see \c mbedtls_blowfish_crypt_ecb(), \c mbedtls_blowfish_crypt_cbc(), - * \c mbedtls_blowfish_crypt_cfb64() and \c mbedtls_blowfish_crypt_ctr()) * - Camellia (see \c mbedtls_camellia_crypt_ecb(), \c mbedtls_camellia_crypt_cbc(), * \c mbedtls_camellia_crypt_cfb128() and \c mbedtls_camellia_crypt_ctr()). * - DES/3DES (see \c mbedtls_des_crypt_ecb(), \c mbedtls_des_crypt_cbc(), \c mbedtls_des3_crypt_ecb() * and \c mbedtls_des3_crypt_cbc()). * - GCM (AES-GCM and CAMELLIA-GCM) (see \c mbedtls_gcm_init()) - * - XTEA (see \c mbedtls_xtea_crypt_ecb()). * - Asymmetric: * - Diffie-Hellman-Merkle (see \c mbedtls_dhm_read_public(), \c mbedtls_dhm_make_public() * and \c mbedtls_dhm_calc_secret()). diff --git a/doxygen/input/doc_hashing.h b/doxygen/input/doc_hashing.h index aaa0c7890d..931e6e928c 100644 --- a/doxygen/input/doc_hashing.h +++ b/doxygen/input/doc_hashing.h @@ -34,7 +34,7 @@ * \c mbedtls_md_setup()) * * The following hashing-algorithms are provided: - * - MD2, MD4, MD5 128-bit one-way hash functions by Ron Rivest. + * - MD5 128-bit one-way hash function by Ron Rivest. * - SHA-1, SHA-256, SHA-384/512 160-bit or more one-way hash functions by * NIST and NSA. * diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 0205dcfefd..dd84c2871d 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -1577,13 +1577,13 @@ ENABLE_PREPROCESSING = YES # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # pointed to by INCLUDE_PATH will be searched when a #include is found. @@ -1630,7 +1630,7 @@ PREDEFINED = WIN32 \ # Use the PREDEFINED tag if you want to use a different macro definition that # overrules the definition found in the source code. -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = MBEDTLS_PRIVATE # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then # doxygen's preprocessor will remove all references to function-like macros diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h index da741c8e81..e23b9ca94a 100644 --- a/include/mbedtls/aes.h +++ b/include/mbedtls/aes.h @@ -39,6 +39,7 @@ #ifndef MBEDTLS_AES_H #define MBEDTLS_AES_H +#include "mbedtls/private_access.h" #if !defined(MBEDTLS_CONFIG_FILE) #include "mbedtls/config.h" @@ -78,9 +79,9 @@ extern "C" { */ typedef struct mbedtls_aes_context { - int nr; /*!< The number of rounds. */ - uint32_t *rk; /*!< AES round keys. */ - uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can + int MBEDTLS_PRIVATE(nr); /*!< The number of rounds. */ + uint32_t *MBEDTLS_PRIVATE(rk); /*!< AES round keys. */ + uint32_t MBEDTLS_PRIVATE(buf)[68]; /*!< Unaligned data buffer. This buffer can hold 32 extra Bytes, which can be used for one of the following purposes: