Merge remote-tracking branch 'upstream/development' into psa-m-aead-merge

Also fiixed the following merge problems:

crypto_struct.h   : Added MBEDTLS_PRIVATE to psa_aead_operation_s
                    members (merge conflict)
psa_crypto_aead.c : Added ciphertext_length to mbedtls_gcm_finish
                    call (change of API during development)

Signed-off-by: Paul Elliott <paul.elliott@arm.com>

.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 `mbedtls_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
+

.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.

.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 
+

.github/issue_template.md

@@ -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?**  
-

.gitignore

@@ -18,6 +18,7 @@ Testing
 Coverage
 *.gcno
 *.gcda
+coverage-summary.txt
 
 # generated by scripts/memory.sh
 massif-*

.travis.yml

@@ -14,6 +14,8 @@ jobs:
           - graphviz
           - gcc-arm-none-eabi
           - libnewlib-arm-none-eabi
+          - gcc-arm-linux-gnueabi
+          - libc6-dev-armel-cross
       language: python # Needed to get pip for Python 3
       python: 3.5 # version from Ubuntu 16.04
       install:
@@ -22,18 +24,12 @@ jobs:
         - tests/scripts/all.sh -k 'check_*'
         - tests/scripts/all.sh -k test_default_out_of_box
         - tests/scripts/all.sh -k test_ref_configs
-        - tests/scripts/all.sh -k build_arm_none_eabi_gcc_arm5vte build_arm_none_eabi_gcc_m0plus
+        - tests/scripts/all.sh -k build_arm_linux_gnueabi_gcc_arm5vte build_arm_none_eabi_gcc_m0plus
 
     - name: full configuration
       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:

3rdparty/CMakeLists.txt

@@ -1,17 +1,5 @@
-list (APPEND thirdparty_src)
+execute_process(COMMAND ${MBEDTLS_PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../scripts/config.py -f ${CMAKE_CURRENT_SOURCE_DIR}/../include/mbedtls/mbedtls_config.h get MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED RESULT_VARIABLE result)
-list (APPEND thirdparty_lib)
-list (APPEND thirdparty_inc_public)
-list (APPEND thirdparty_inc)
-list (APPEND thirdparty_def)
-
-execute_process(COMMAND ${MBEDTLS_PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../scripts/config.py -f ${CMAKE_CURRENT_SOURCE_DIR}/../include/mbedtls/config.h get MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED RESULT_VARIABLE result)
 
 if(${result} EQUAL 0)
     add_subdirectory(everest)
 endif()
-
-set(thirdparty_src ${thirdparty_src} PARENT_SCOPE)
-set(thirdparty_lib ${thirdparty_lib} PARENT_SCOPE)
-set(thirdparty_inc_public ${thirdparty_inc_public} PARENT_SCOPE)
-set(thirdparty_inc ${thirdparty_inc} PARENT_SCOPE)
-set(thirdparty_def ${thirdparty_def} PARENT_SCOPE)

3rdparty/everest/CMakeLists.txt

@@ -1,16 +1,15 @@
-list (APPEND everest_src)
+add_library(everest
-list (APPEND everest_inc_public)
+  library/everest.c
-list (APPEND everest_inc)
+  library/x25519.c
-list (APPEND everest_def)
+  library/Hacl_Curve25519_joined.c)
 
-set(everest_src
+target_include_directories(everest
-  ${CMAKE_CURRENT_SOURCE_DIR}/library/everest.c
+  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
-  ${CMAKE_CURRENT_SOURCE_DIR}/library/x25519.c
+         $<BUILD_INTERFACE:${MBEDTLS_DIR}/include>
-  ${CMAKE_CURRENT_SOURCE_DIR}/library/Hacl_Curve25519_joined.c
+         $<INSTALL_INTERFACE:include>
-)
+  PRIVATE include/everest
-
+          include/everest/kremlib
-list(APPEND everest_inc_public ${CMAKE_CURRENT_SOURCE_DIR}/include)
+          ${MBEDTLS_DIR}/library/)
-list(APPEND everest_inc ${CMAKE_CURRENT_SOURCE_DIR}/include/everest ${CMAKE_CURRENT_SOURCE_DIR}/include/everest/kremlib)
 
 if(INSTALL_MBEDTLS_HEADERS)
 
@@ -22,7 +21,7 @@ if(INSTALL_MBEDTLS_HEADERS)
 
 endif(INSTALL_MBEDTLS_HEADERS)
 
-set(thirdparty_src ${thirdparty_src} ${everest_src} PARENT_SCOPE)
+install(TARGETS everest
-set(thirdparty_inc_public ${thirdparty_inc_public} ${everest_inc_public} PARENT_SCOPE)
+  EXPORT MbedTLSTargets
-set(thirdparty_inc ${thirdparty_inc} ${everest_inc} PARENT_SCOPE)
+  DESTINATION ${LIB_INSTALL_DIR}
-set(thirdparty_def ${thirdparty_def} ${everest_def} PARENT_SCOPE)
+  PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ)

BRANCHES.md

@@ -6,7 +6,7 @@ At any point in time, we have a number of maintained branches consisting of:
   this always contains the latest release, including all publicly available
   security fixes.
 - The [`development`](https://github.com/ARMmbed/mbedtls/tree/development) branch:
-  this is where the next major version of Mbed TLS (version 3.0) is being
+  this is where the current major version of Mbed TLS (version 3.x) is being
   prepared. It has API changes that make it incompatible with Mbed TLS 2.x,
   as well as all the new features and bug fixes and security fixes.
 - The [`development_2.x`](https://github.com/ARMmbed/mbedtls/tree/development_2.x) branch:
@@ -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
+API compatibility in the `master` branch across minor version changes (e.g.
-also maintain ABI compatibility within LTS branches; see the next section for
+the API of 3.(x+1) is backward compatible with 3.x). We only break API
-details.
+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
+Note that new releases of Mbed TLS may extend the API. Here are some
-insecure in the meantime (for example, crypto that was found to be weak) may
+examples of changes that are common in minor releases of Mbed TLS, and are
-need to be changed. In case security comes in conflict with backwards
+not considered API compatibility breaks:
-compatibility, we will put security first, but always attempt to provide a
+
-compatibility option.
+* 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

CMakeLists.txt

@@ -16,7 +16,11 @@
 #   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)
+
+include(CMakePackageConfigHelpers)
 
 # 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
@@ -82,7 +86,7 @@ endif()
 if(MBEDTLS_PYTHON_EXECUTABLE)
 
     # If 128-bit keys are configured for CTR_DRBG, display an appropriate warning
-    execute_process(COMMAND ${MBEDTLS_PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/config.py -f ${CMAKE_CURRENT_SOURCE_DIR}/include/mbedtls/config.h get MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
+    execute_process(COMMAND ${MBEDTLS_PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/config.py -f ${CMAKE_CURRENT_SOURCE_DIR}/include/mbedtls/mbedtls_config.h get MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
                         RESULT_VARIABLE result)
     if(${result} EQUAL 0)
         message(WARNING ${CTR_DRBG_128_BIT_KEY_WARNING})
@@ -221,7 +225,6 @@ endif()
 add_subdirectory(include)
 
 add_subdirectory(3rdparty)
-list(APPEND libs ${thirdparty_lib})
 
 add_subdirectory(library)
 
@@ -300,3 +303,37 @@ if(ENABLE_TESTING)
                     ${CMAKE_CURRENT_BINARY_DIR}/DartConfiguration.tcl COPYONLY)
     endif()
 endif()
+
+configure_package_config_file(
+    "cmake/MbedTLSConfig.cmake.in"
+    "cmake/MbedTLSConfig.cmake"
+        INSTALL_DESTINATION "cmake")
+
+write_basic_package_version_file(
+    "cmake/MbedTLSConfigVersion.cmake"
+        COMPATIBILITY SameMajorVersion
+        VERSION 3.0.0)
+
+install(
+    FILES "${CMAKE_CURRENT_BINARY_DIR}/cmake/MbedTLSConfig.cmake"
+          "${CMAKE_CURRENT_BINARY_DIR}/cmake/MbedTLSConfigVersion.cmake"
+    DESTINATION "cmake")
+
+export(
+    EXPORT MbedTLSTargets
+    NAMESPACE MbedTLS::
+    FILE "cmake/MbedTLSTargets.cmake")
+
+install(
+    EXPORT MbedTLSTargets
+    NAMESPACE MbedTLS::
+    DESTINATION "cmake"
+    FILE "MbedTLSTargets.cmake")
+
+if(CMAKE_VERSION VERSION_GREATER 3.15 OR CMAKE_VERSION VERSION_EQUAL 3.15)
+    # Do not export the package by default
+    cmake_policy(SET CMP0090 NEW)
+
+    # Make this package visible to the system
+    export(PACKAGE MbedTLS)
+endif()

ChangeLog

@@ -1,6 +1,6 @@
 mbed TLS ChangeLog (Sorted per branch, date)
 
-= Mbed TLS 3.0.0 branch released 2021-xx-xx
+= Mbed TLS 3.0.0 branch released 2021-07-07
 
 API changes
    * Remove HAVEGE module.
@@ -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
@@ -32,18 +32,153 @@ API changes
    * Drop support for parsing SSLv2 ClientHello
      (MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO).
    * Drop support for SSLv3 (MBEDTLS_SSL_PROTO_SSL3).
-   * Drop support for compatibility with our own previous buggy
-     implementation of truncated HMAC (MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT).
    * Drop support for TLS record-level compression (MBEDTLS_ZLIB_SUPPORT).
    * Drop support for RC4 TLS ciphersuites.
    * Drop support for single-DES ciphersuites.
    * Drop support for MBEDTLS_SSL_HW_RECORD_ACCEL.
+   * Update AEAD output size macros to bring them in line with the PSA Crypto
+     API version 1.0 spec. This version of the spec parameterizes them on the
+     key type used, as well as the key bit-size in the case of
+     PSA_AEAD_TAG_LENGTH.
+   * Add configuration option MBEDTLS_X509_REMOVE_INFO which
+     removes the mbedtls_x509_*_info(), mbedtls_debug_print_crt()
+     as well as other functions and constants only used by
+     those functions. This reduces the code footprint by
+     several kB.
+   * Remove SSL error codes `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED`
+     and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` which are never
+     returned from the public SSL API.
+   * Remove `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` and return
+     `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead.
+   * The output parameter of mbedtls_sha512_finish, mbedtls_sha512,
+     mbedtls_sha256_finish and mbedtls_sha256 now has a pointer type
+     rather than array type. This removes spurious warnings in some compilers
+     when outputting a SHA-384 or SHA-224 hash into a buffer of exactly
+     the hash size.
+   * Remove the MBEDTLS_TEST_NULL_ENTROPY config option. Fixes #4388.
+   * The interface of the GCM module has changed to remove restrictions on
+     how the input to multipart operations is broken down. mbedtls_gcm_finish()
+     now takes extra output parameters for the last partial output block.
+     mbedtls_gcm_update() now takes extra parameters for the output length.
+     The software implementation always produces the full output at each
+     call to mbedtls_gcm_update(), but alternative implementations activated
+     by MBEDTLS_GCM_ALT may delay partial blocks to the next call to
+     mbedtls_gcm_update() or mbedtls_gcm_finish(). Furthermore, applications
+     no longer pass the associated data to mbedtls_gcm_starts(), but to the
+     new function mbedtls_gcm_update_ad().
+     These changes are backward compatible for users of the cipher API.
+   * Replace MBEDTLS_SHA512_NO_SHA384 config option with MBEDTLS_SHA384_C.
+     This separates config option enabling the SHA384 algorithm from option
+     enabling the SHA512 algorithm. Fixes #4034.
+   * Introduce MBEDTLS_SHA224_C.
+     This separates config option enabling the SHA224 algorithm from option
+     enabling SHA256.
+   * The getter and setter API of the SSL session cache (used for
+     session-ID based session resumption) has changed to that of
+     a key-value store with keys being session IDs and values
+     being opaque instances of `mbedtls_ssl_session`.
+   * Remove the mode parameter from RSA operation functions. Signature and
+     decryption functions now always use the private key and verification and
+     encryption use the public key. Verification functions also no longer have
+     RNG parameters.
+   * Modify semantics of `mbedtls_ssl_conf_[opaque_]psk()`:
+     In Mbed TLS 2.X, the API prescribes that later calls overwrite
+     the effect of earlier calls. In Mbed TLS 3.0, calling
+     `mbedtls_ssl_conf_[opaque_]psk()` more than once will fail,
+     leaving the PSK that was configured first intact.
+     Support for more than one PSK may be added in 3.X.
+   * The function mbedtls_x509write_csr_set_extension() has an extra parameter
+     which allows to mark an extension as critical. Fixes #4055.
+   * For multi-part AEAD operations with the cipher module, calling
+     mbedtls_cipher_finish() is now mandatory. Previously the documentation
+     was unclear on this point, and this function happened to never do
+     anything with the currently implemented AEADs, so in practice it was
+     possible to skip calling it, which is no longer supported.
+   * The option MBEDTLS_ECP_FIXED_POINT_OPTIM use pre-computed comb tables
+     instead of computing tables in runtime. Thus, this option now increase
+     code size, and it does not increase RAM usage in runtime anymore.
+   * 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.
+   * 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.
+   * Replace MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE by a runtime
+     configuration function mbedtls_ssl_conf_preference_order(). Fixes #4398.
+   * Instead of accessing the len field of a DHM context, which is no longer
+     supported, use the new function mbedtls_dhm_get_len() .
+   * 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.
+   * 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().
+   * mbedtls_ssl_conf_export_keys_ext_cb() and
+     mbedtls_ssl_conf_export_keys_cb() have been removed and
+     replaced by a new API mbedtls_ssl_set_export_keys_cb().
+     Raw keys and IVs are no longer passed to the callback.
+     Further, callbacks now receive an additional parameter
+     indicating the type of secret that's being exported,
+     paving the way for the larger number of secrets
+     in TLS 1.3. Finally, the key export callback and
+     context are now connection-specific.
+   * Signature functions in the RSA and PK modules now require the hash
+     length parameter to be the size of the hash input. For RSA signatures
+     other than raw PKCS#1 v1.5, this must match the output size of the
+     specified hash algorithm.
+   * The functions mbedtls_pk_sign(), mbedtls_pk_sign_restartable(),
+     mbedtls_ecdsa_write_signature() and
+     mbedtls_ecdsa_write_signature_restartable() now take an extra parameter
+     indicating the size of the output buffer for the signature.
+   * Implement one-shot cipher functions, psa_cipher_encrypt and
+     psa_cipher_decrypt, according to the PSA Crypto API 1.0.0
+     specification.
+   * Direct access to fields of structures declared in public headers is no
+     longer supported except for fields that are documented public. Use accessor
+     functions instead. For more information, see the migration guide entry
+     "Most structure fields are now private".
+   * mbedtls_ssl_get_session_pointer() has been removed, and
+     mbedtls_ssl_{set,get}_session() may now only be called once for any given
+     SSL context.
+
+Default behavior changes
+   * Enable by default the functionalities which have no reason to be disabled.
+     They are: ARIA block cipher, CMAC mode, elliptic curve J-PAKE library and
+     Key Wrapping mode as defined in NIST SP 800-38F. Fixes #4036.
+   * Some default policies for X.509 certificate verification and TLS have
+     changed: curves and hashes weaker than 255 bits are no longer accepted
+     by default. The default order in TLS now favors faster curves over larger
+     curves.
 
 Requirement changes
    * The library now uses the %zu format specifier with the printf() family of
      functions, so requires a toolchain that supports it. This change does not
      affect the maintained LTS branches, so when contributing changes please
      bear this in mind and do not add them to backported code.
+   * If you build the development version of Mbed TLS, rather than an official
+     release, some configuration-independent files are now generated at build
+     time rather than checked into source control. This includes some library
+     source files as well as the Visual Studio solution. Perl, Python 3 and a
+     C compiler for the host platform are required. See “Generated source files
+     in the development branch” in README.md for more information.
+   * 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.
 
 Removals
    * Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
@@ -51,7 +186,6 @@ Removals
      certificates signed with SHA-1 due to the known attacks against SHA-1.
      If needed, SHA-1 certificates can still be verified by using a custom
      verification profile.
-
    * Removed deprecated things in psa/crypto_compat.h. Fixes #4284
    * Removed deprecated functions from hashing modules. Fixes #4280.
    * Remove PKCS#11 library wrapper. PKCS#11 has limited functionality,
@@ -60,12 +194,133 @@ Removals
      More details on PCKS#11 wrapper removal can be found in the mailing list
      https://lists.trustedfirmware.org/pipermail/mbed-tls/2020-April/000024.html
    * Remove deprecated error codes. Fix #4283
+   * Remove MBEDTLS_ENABLE_WEAK_CIPHERSUITES configuration option. Fixes #4416.
+   * Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
+     compile-time option. This option has been inactive for a long time.
+     Please use the `lifetime` parameter of `mbedtls_ssl_ticket_setup()`
+     instead.
+   * Remove the following deprecated functions and constants of hex-encoded
+     primes based on RFC 5114 and RFC 3526 from library code and tests:
+     mbedtls_aes_encrypt(), mbedtls_aes_decrypt(), mbedtls_mpi_is_prime(),
+     mbedtls_cipher_auth_encrypt(), mbedtls_cipher_auth_decrypt(),
+     mbedtls_ctr_drbg_update(), mbedtls_hmac_drbg_update(),
+     mbedtls_ecdsa_write_signature_det(), mbedtls_ecdsa_sign_det(),
+     mbedtls_ssl_conf_dh_param(), mbedtls_ssl_get_max_frag_len(),
+     MBEDTLS_DHM_RFC5114_MODP_2048_P, MBEDTLS_DHM_RFC5114_MODP_2048_G,
+     MBEDTLS_DHM_RFC3526_MODP_2048_P, MBEDTLS_DHM_RFC3526_MODP_2048_G,
+     MBEDTLS_DHM_RFC3526_MODP_3072_P, MBEDTLS_DHM_RFC3526_MODP_3072_G,
+     MBEDTLS_DHM_RFC3526_MODP_4096_P, MBEDTLS_DHM_RFC3526_MODP_4096_G.
+     Remove the deprecated file: include/mbedtls/net.h. Fixes #4282.
+   * Remove MBEDTLS_SSL_MAX_CONTENT_LEN configuration option, since
+     MBEDTLS_SSL_IN_CONTENT_LEN and MBEDTLS_SSL_OUT_CONTENT_LEN replace
+     it. Fixes #4362.
+   * Remove the MBEDTLS_SSL_RECORD_CHECKING option and enable by default its
+     previous action. Fixes #4361.
+   * 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(),
+     and mbedtls_ssl_conf_ciphersuites_for_version(). Fixes #4286.
+   * The RSA module no longer supports private-key operations with the public
+     key and vice versa.
+   * Remove the MBEDTLS_SSL_DTLS_BADMAC_LIMIT config.h option. Fixes #4403.
+   * Remove all the 3DES ciphersuites:
+     MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA,
+     MBEDTLS_TLS_RSA_WITH_3DES_EDE_CBC_SHA. Remove the
+     MBEDTLS_REMOVE_3DES_CIPHERSUITES option which is no longer relevant.
+     Fixes #4367.
+   * Remove the MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3 option and let the code
+     behave as if it was always disabled. Fixes #4386.
+   * Remove MBEDTLS_ECDH_LEGACY_CONTEXT config option since this was purely for
+     backward compatibility which is no longer supported. Addresses #4404.
+   * Remove the following macros: MBEDTLS_CHECK_PARAMS,
+     MBEDTLS_CHECK_PARAMS_ASSERT, MBEDTLS_PARAM_FAILED,
+     MBEDTLS_PARAM_FAILED_ALT. Fixes #4313.
+   * 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.
+   * 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.
+   * MBEDTLS_ECP_MAX_BITS is no longer a configuration option because it is
+     now determined automatically based on supported curves.
+   * Remove the following functions: mbedtls_timing_self_test(),
+     mbedtls_hardclock_poll(), mbedtls_timing_hardclock() and
+     mbedtls_set_alarm(). Fixes #4083.
+   * The configuration option MBEDTLS_ECP_NO_INTERNAL_RNG has been removed as
+     it no longer had any effect.
+   * 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.
+   * Remove MBEDTLS_SSL_TRUNCATED_HMAC and also remove
+     MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT config option. Users are better served by
+     using a CCM-8 ciphersuite than a CBC ciphersuite with truncated HMAC.
+     See issue #4341 for more details.
+   * Remove the compile-time option
+     MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE.
 
 Features
    * Add mbedtls_rsa_rsassa_pss_sign_ext() function allowing to generate a
      signature with a specific salt length. This function allows to validate
      test cases provided in the NIST's CAVP test suite. Contributed by Cédric
      Meuter in PR #3183.
+   * Added support for built-in driver keys through the PSA opaque crypto
+     driver interface. Refer to the documentation of
+     MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS for more information.
+   * Implement psa_sign_message() and psa_verify_message().
+   * The multi-part GCM interface (mbedtls_gcm_update() or
+     mbedtls_cipher_update()) no longer requires the size of partial inputs to
+     be a multiple of 16.
+   * The multi-part GCM interface now supports chunked associated data through
+     multiple calls to mbedtls_gcm_update_ad().
+   * The new function mbedtls_mpi_random() generates a random value in a
+     given range uniformly.
+   * 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.
+   * 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.
+   * 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.
+   * Implement psa_mac_compute() and psa_mac_verify() as defined in the
+     PSA Cryptograpy API 1.0.0 specification.
+
+Security
+   * Fix a bias in the generation of finite-field Diffie-Hellman-Merkle (DHM)
+     private keys and of blinding values for DHM and elliptic curves (ECP)
+     computations. Reported by FlorianF89 in #4245.
+   * Fix a potential side channel vulnerability in ECDSA ephemeral key generation.
+     An adversary who is capable of very precise timing measurements could
+     learn partial information about the leading bits of the nonce used for the
+     signature, allowing the recovery of the private key after observing a
+     large number of signature operations. This completes a partial fix in
+     Mbed TLS 2.20.0.
+   * An adversary with access to precise enough information about memory
+     accesses (typically, an untrusted operating system attacking a secure
+     enclave) could recover an RSA private key after observing the victim
+     performing a single private-key operation. Found and reported by
+     Zili KOU, Wenjian HE, Sharad Sinha, and Wei ZHANG.
+   * An adversary with access to precise enough timing information (typically, a
+     co-located process) could recover a Curve25519 or Curve448 static ECDH key
+     after inputting a chosen public key and observing the victim performing the
+     corresponding private-key operation. Found and reported by Leila Batina,
+     Lukas Chmielewski, Björn Haase, Niels Samwel and Peter Schwabe.
 
 Bugfix
    * Fix premature fopen() call in mbedtls_entropy_write_seed_file which may
@@ -83,15 +338,132 @@ Bugfix
      in line with version 1.0.0 of the specification. Fix #4162.
    * Fix a bug in ECDSA that would cause it to fail when the hash is all-bits
      zero. Fixes #1792
-   * mbedtls_mpi_read_string on "-0" produced an MPI object that was not treated
+   * Fix some cases in the bignum module where the library constructed an
-     as equal to 0 in all cases. Fix it to produce the same object as "0".
+     unintended representation of the value 0 which was not processed
+     correctly by some bignum operations. This could happen when
+     mbedtls_mpi_read_string() was called on "-0", or when
+     mbedtls_mpi_mul_mpi() and mbedtls_mpi_mul_int() was called with one of
+     the arguments being negative and the other being 0. Fixes #4643.
+   * Fix a compilation error when MBEDTLS_ECP_RANDOMIZE_MXZ_ALT is
+     defined. Fixes #4217.
+   * Fix an incorrect error code when parsing a PKCS#8 private key.
+   * In a TLS client, enforce the Diffie-Hellman minimum parameter size
+     set with mbedtls_ssl_conf_dhm_min_bitlen() precisely. Before, the
+     minimum size was rounded down to the nearest multiple of 8.
+   * In library/net_sockets.c, _POSIX_C_SOURCE and _XOPEN_SOURCE are
+     defined to specific values.  If the code is used in a context
+     where these are already defined, this can result in a compilation
+     error.  Instead, assume that if they are defined, the values will
+     be adequate to build Mbed TLS.
+   * With MBEDTLS_PSA_CRYPTO_C disabled, some functions were getting built
+     nonetheless, resulting in undefined reference errors when building a
+     shared library. Reported by Guillermo Garcia M. in #4411.
+   * The cipher suite TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384 was not available
+     when SHA-1 was disabled and was offered when SHA-1 was enabled but SHA-384
+     was disabled. Fix the dependency. Fixes #4472.
+   * Do not offer SHA384 cipher suites when SHA-384 is disabled. Fixes #4499.
+   * Fix test suite code on platforms where int32_t is not int, such as
+     Arm Cortex-M. Fixes #4530.
+   * Fix some issues affecting MBEDTLS_ARIA_ALT implementations: a misplaced
+     directive in a header and a missing initialization in the self-test.
+   * Fix a missing initialization in the Camellia self-test, affecting
+     MBEDTLS_CAMELLIA_ALT implementations.
+   * Restore the ability to configure PSA via Mbed TLS options to support RSA
+     key pair operations but exclude RSA key generation. When MBEDTLS_GENPRIME
+     is not defined PSA will no longer attempt to use mbedtls_rsa_gen_key().
+     Fixes #4512.
+   * 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.
+   * Remove outdated check-config.h check that prevented implementing the
+     timing module on Mbed OS. Fixes #4633.
+   * Fix PSA_ALG_TLS12_PRF and PSA_ALG_TLS12_PSK_TO_MS being too permissive
+     about missing inputs.
+   * Fix mbedtls_net_poll() and mbedtls_net_recv_timeout() often failing with
+     MBEDTLS_ERR_NET_POLL_FAILED on Windows. Fixes #4465.
+   * Fix a resource leak in a test suite with an alternative AES
+     implementation. Fixes #4176.
+   * Fix a crash in mbedtls_mpi_debug_mpi on a bignum having 0 limbs. This
+     could notably be triggered by setting the TLS debug level to 3 or above
+     and using a Montgomery curve for the key exchange. Reported by lhuang04
+     in #4578. Fixes #4608.
+   * psa_verify_hash() was relying on implementation-specific behavior of
+     mbedtls_rsa_rsassa_pss_verify() and was causing failures in some _ALT
+     implementations. This reliance is now removed. Fixes #3990.
+   * Disallow inputs of length different from the corresponding hash when
+     signing or verifying with PSA_ALG_RSA_PSS (The PSA Crypto API mandates
+     that PSA_ALG_RSA_PSS uses the same hash throughout the algorithm.)
+   * Fix a null pointer dereference when mbedtls_mpi_exp_mod() was called with
+     A=0 represented with 0 limbs. Up to and including Mbed TLS 2.26, this bug
+     could not be triggered by code that constructed A with one of the
+     mbedtls_mpi_read_xxx functions (including in particular TLS code) since
+     those always built an mpi object with at least one limb.
+     Credit to OSS-Fuzz. Fixes #4641.
+   * Fix mbedtls_mpi_gcd(G,A,B) when the value of B is zero. This had no
+     effect on Mbed TLS's internal use of mbedtls_mpi_gcd(), but may affect
+     applications that call mbedtls_mpi_gcd() directly. Fixes #4642.
+   * The PSA API no longer allows the creation or destruction of keys with a
+     read-only lifetime. The persistence level PSA_KEY_PERSISTENCE_READ_ONLY
+     can now only be used as intended, for keys that cannot be modified through
+     normal use of the API.
+   * When MBEDTLS_PSA_CRYPTO_SPM is enabled, crypto_spe.h was not included
+     in all the right places. Include it from crypto_platform.h, which is
+     the natural place. Fixes #4649.
+   * Fix which alert is sent in some cases to conform to the
+     applicable RFC: on an invalid Finished message value, an
+     invalid max_fragment_length extension, or an
+     unsupported extension used by the server.
+   * Correct (change from 12 to 13 bytes) the value of the macro describing the
+     maximum nonce length returned by psa_aead_generate_nonce().
 
 Changes
    * Fix the setting of the read timeout in the DTLS sample programs.
    * Add extra printf compiler warning flags to builds.
    * Fix memsan build false positive in x509_crt.c with clang 11
-   * There is ongoing work for the next release (= Mbed TLS 3.0.0 branch to
+   * Alternative implementations of CMAC may now opt to not support 3DES as a
-     be released 2021-xx-xx), including various API-breaking changes.
+     CMAC block cipher, and still pass the CMAC self test.
+   * Remove the AES sample application programs/aes/aescrypt2 which shows
+     bad cryptographic practice. Fix #1906.
+   * Remove configs/config-psa-crypto.h, which no longer had any intended
+     differences from the default configuration, but had accidentally diverged.
+   * When building the test suites with GNU make, invoke python3 or python, not
+     python2, which is no longer supported upstream.
+   * fix build failure on MinGW toolchain when __USE_MING_ANSI_STDIO is on.
+     When that flag is on, standard GNU C printf format specifiers
+     should be used.
+   * Replace MBEDTLS_SSL_CID_PADDING_GRANULARITY and
+     MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY with a new single unified option
+     MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY. Fixes #4335.
+   * Reduce the default value of MBEDTLS_ECP_WINDOW_SIZE. This reduces RAM usage
+     during ECC operations at a negligible performance cost.
+   * mbedtls_mpi_read_binary(), mbedtls_mpi_read_binary_le() and
+     mbedtls_mpi_read_string() now construct an mbedtls_mpi object with 0 limbs
+     when their input has length 0. Note that this is an implementation detail
+     and can change at any time, so this change should be transparent, but it
+     may result in mbedtls_mpi_write_binary() or mbedtls_mpi_write_string()
+     now writing an empty string where it previously wrote one or more
+     zero digits when operating from values constructed with an mpi_read
+     function and some mpi operations.
+   * Add CMake package config generation for CMake projects consuming Mbed TLS.
+   * config.h has been split into build_info.h and mbedtls_config.h
+     build_info.h is intended to be included from C code directly, while
+     mbedtls_config.h is intended to be edited by end users wishing to
+     change the build configuration, and should generally only be included from
+     build_info.h.
+   * The handling of MBEDTLS_CONFIG_FILE has been moved into build_info.h.
+   * A config file version symbol, MBEDTLS_CONFIG_VERSION was introduced.
+     Defining it to a particular value will ensure that Mbed TLS interprets
+     the config file in a way that's compatible with the config file format
+     used by the Mbed TLS release whose MBEDTLS_VERSION_NUMBER has the same
+     value.
+     The only value supported by Mbed TLS 3.0.0 is 0x03000000.
+   * Various changes to which alert and/or error code may be returned
+   * during the TLS handshake.
+   * Implicitly add PSA_KEY_USAGE_SIGN_MESSAGE key usage policy flag when
+     PSA_KEY_USAGE_SIGN_HASH flag is set and PSA_KEY_USAGE_VERIFY_MESSAGE flag
+     when PSA_KEY_USAGE_VERIFY_HASH flag is set. This usage flag extension
+     is also applied when loading a key from storage.
 
 = mbed TLS 2.26.0 branch released 2021-03-08
 

ChangeLog.d/add-missing-parenthesis.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix a compilation error when MBEDTLS_ECP_RANDOMIZE_MXZ_ALT is
-     defined. Fixes #4217.

ChangeLog.d/aescrypt2.txt

@@ -1,3 +0,0 @@
-Changes
-   * Remove the AES sample application programs/aes/aescrypt2 which shows
-     bad cryptographic practice. Fix #1906.

ChangeLog.d/allow_alt_cmac_without_des.txt

@@ -1,3 +0,0 @@
-Changes
-   * Alternative implementations of CMAC may now opt to not support 3DES as a
-     CMAC block cipher, and still pass the CMAC self test.

ChangeLog.d/aria-alt.txt

@@ -1,5 +0,0 @@
-Bugfix
-   * Fix some issues affecting MBEDTLS_ARIA_ALT implementations: a misplaced
-     directive in a header and a missing initialization in the self-test.
-   * Fix a missing initialization in the Camellia self-test, affecting
-     MBEDTLS_CAMELLIA_ALT implementations.

ChangeLog.d/chunked_ccm.txt

@@ -0,0 +1,8 @@
+Changes
+   * Implement multi-part CCM API.
+     The multi-part functions: mbedtls_ccm_starts(), mbedtls_ccm_set_lengths(),
+     mbedtls_ccm_update_ad(), mbedtls_ccm_update(), mbedtls_ccm_finish()
+     were introduced in mbedTLS 3.0 release, however their implementation was
+     postponed until now.
+     Implemented functions support chunked data input for both CCM and CCM*
+     algorithms.

ChangeLog.d/cipher-delayed-output.txt

@@ -1,6 +0,0 @@
-API changes
-   * For multi-part AEAD operations with the cipher module, calling
-     mbedtls_cipher_finish() is now mandatory. Previously the documentation
-     was unclear on this point, and this function happened to never do
-     anything with the currently implemented AEADs, so in practice it was
-     possible to skip calling it, which is no longer supported.

ChangeLog.d/ciphersuite-sha1-sha384-guard.txt

@@ -1,4 +0,0 @@
-Bugfix
-   * The cipher suite TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384 was not available
-     when SHA-1 was disabled and was offered when SHA-1 was enabled but SHA-384
-     was disabled. Fix the dependency. Fixes #4472.

ChangeLog.d/ciphersuite-sha384-guard.txt

@@ -1,2 +0,0 @@
-Bugfix
-   * Do not offer SHA384 cipher suites when SHA-384 is disabled. Fixes #4499.

ChangeLog.d/dhm_min_bitlen.txt

@@ -1,4 +0,0 @@
-Bugfix
-   * In a TLS client, enforce the Diffie-Hellman minimum parameter size
-     set with mbedtls_ssl_conf_dhm_min_bitlen() precisely. Before, the
-     minimum size was rounded down to the nearest multiple of 8.

ChangeLog.d/fix-cipher-output-size-macros.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Prevent divide by zero if either of PSA_CIPHER_ENCRYPT_OUTPUT_SIZE() or
+     PSA_CIPHER_UPDATE_OUTPUT_SIZE() were called using an asymmetric key type.
+

ChangeLog.d/fix-mingw-build.txt

@@ -1,5 +0,0 @@
-Changes
-   * fix build failure on MinGW toolchain when __USE_MING_ANSI_STDIO is on.
-     When that flag is on, standard GNU C printf format specifiers
-     should be used.
-

ChangeLog.d/fix-pk-parse-key-error-code.txt

@@ -1,2 +0,0 @@
-Bugfix
-   * Fix an incorrect error code when parsing a PKCS#8 private key.

ChangeLog.d/gcm-update.txt

@@ -1,17 +0,0 @@
-API changes
-   * The interface of the GCM module has changed to remove restrictions on
-     how the input to multipart operations is broken down. mbedtls_gcm_finish()
-     now takes an extra output parameter for the last partial output block.
-     mbedtls_gcm_update() now takes extra parameters for the output length.
-     The software implementation always produces the full output at each
-     call to mbedtls_gcm_update(), but alternative implementations activated
-     by MBEDTLS_GCM_ALT may delay partial blocks to the next call to
-     mbedtls_gcm_update() or mbedtls_gcm_finish(). Furthermore, applications
-     no longer pass the associated data to mbedtls_gcm_starts(), but to the
-     new function mbedtls_gcm_update_ad().
-     These changes are backward compatible for users of the cipher API.
-
-Features
-   * The multi-part GCM interface (mbedtls_gcm_update() or
-     mbedtls_cipher_update()) no longer requires the size of partial inputs to
-     be a multiple of 16.

ChangeLog.d/host_test-int32.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix test suite code on platforms where int32_t is not int, such as
-     Arm Cortex-M. Fixes #4530.

ChangeLog.d/issue4036.txt

@@ -1,5 +0,0 @@
-Default behavior changes
-   * Enable by default the functionalities which have no reason to be disabled.
-     They are: ARIA block cipher, CMAC mode, elliptic curve J-PAKE library and
-     Key Wrapping mode as defined in NIST SP 800-38F. Fixes #4036.
-

ChangeLog.d/issue4055.txt

@@ -1,3 +0,0 @@
-API changes
-   * The function mbedtls_x509write_csr_set_extension() has an extra parameter
-     which allows to mark an extension as critical. Fixes #4055.

ChangeLog.d/issue4282.txt

@@ -1,13 +0,0 @@
-Removals
-   * Remove the following deprecated functions and constants of hex-encoded
-     primes based on RFC 5114 and RFC 3526 from library code and tests:
-     mbedtls_aes_encrypt(), mbedtls_aes_decrypt(), mbedtls_mpi_is_prime(),
-     mbedtls_cipher_auth_encrypt(), mbedtls_cipher_auth_decrypt(),
-     mbedtls_ctr_drbg_update(), mbedtls_hmac_drbg_update(),
-     mbedtls_ecdsa_write_signature_det(), mbedtls_ecdsa_sign_det(),
-     mbedtls_ssl_conf_dh_param(), mbedtls_ssl_get_max_frag_len(),
-     MBEDTLS_DHM_RFC5114_MODP_2048_P, MBEDTLS_DHM_RFC5114_MODP_2048_G,
-     MBEDTLS_DHM_RFC3526_MODP_2048_P, MBEDTLS_DHM_RFC3526_MODP_2048_G,
-     MBEDTLS_DHM_RFC3526_MODP_3072_P, MBEDTLS_DHM_RFC3526_MODP_3072_G,
-     MBEDTLS_DHM_RFC3526_MODP_4096_P, MBEDTLS_DHM_RFC3526_MODP_4096_G.
-     Remove the deprecated file: include/mbedtls/net.h. Fixes #4282.

ChangeLog.d/issue4286.txt

@@ -1,11 +0,0 @@
-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:
-     mbedtls_ssl_conf_cbc_record_splitting(),
-     mbedtls_ssl_get_key_exchange_md_ssl_tls(), mbedtls_ssl_conf_fallback().
-     Fixes #4286.

ChangeLog.d/issue4361.txt

@@ -1,3 +0,0 @@
-Removals
-   * Remove the MBEDTLS_SSL_RECORD_CHECKING option and enable by default its
-     previous action. Fixes #4361.

ChangeLog.d/issue4403.txt

@@ -1,2 +0,0 @@
-Removals
-   * Remove the MBEDTLS_SSL_DTLS_BADMAC_LIMIT config.h option. Fixes #4403.

ChangeLog.d/issue4630.txt

@@ -0,0 +1,2 @@
+Bugfix
+   * Stop using reserved identifiers as local variables. Fixes #4630.

ChangeLog.d/make-generate-tests-python.txt

@@ -1,3 +0,0 @@
-Changes
-   * When building the test suites with GNU make, invoke python3 or python, not
-     python2, which is no longer supported upstream.

ChangeLog.d/makefile-python-windows.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * The GNU makefiles invoke python3 in preference to python except on Windows.
+     The check was accidentally not performed when cross-compiling for Windows
+     on Linux. Fix this. Fixes #4774.

ChangeLog.d/muladdc-amd64-memory.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Fix missing constraints on x86_64 assembly code for bignum multiplication
+     that broke some bignum operations with (at least) Clang 12.
+     Fixes #4116, #4786, #4917.

ChangeLog.d/no-generated-files.txt

@@ -1,7 +0,0 @@
-Requirement changes
-   * If you build the development version of Mbed TLS, rather than an official
-     release, some configuration-independent files are now generated at build
-     time rather than checked into source control. This includes some library
-     source files as well as the Visual Studio solution. Perl, Python 3 and a
-     C compiler for the host platform are required. See “Generated source files
-     in the development branch” in README.md for more information.

ChangeLog.d/posix-define.txt

@@ -1,6 +0,0 @@
-Bugfix
-   * In library/net_sockets.c, _POSIX_C_SOURCE and _XOPEN_SOURCE are
-     defined to specific values.  If the code is used in a context
-     where these are already defined, this can result in a compilation
-     error.  Instead, assume that if they are defined, the values will
-     be adequate to build Mbed TLS.

ChangeLog.d/psa-aead-output-size-macros-1.0.txt

@@ -1,5 +0,0 @@
-API changes
-   * Update AEAD output size macros to bring them in line with the PSA Crypto
-     API version 1.0 spec. This version of the spec parameterizes them on the
-     key type used, as well as the key bit-size in the case of
-     PSA_AEAD_TAG_LENGTH.

ChangeLog.d/psa-builtin-keys-implementation.txt

@@ -1,4 +0,0 @@
-Features
-   * Added support for built-in driver keys through the PSA opaque crypto
-     driver interface. Refer to the documentation of
-     MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS for more information.

ChangeLog.d/psa-without-genprime-fix.txt

@@ -1,5 +0,0 @@
-Bugfix
-   * Restore the ability to configure PSA via Mbed TLS options to support RSA
-     key pair operations but exclude RSA key generation. When MBEDTLS_GENPRIME
-     is not defined PSA will no longer attempt to use mbedtls_rsa_gen_key().
-     Fixes #4512.

ChangeLog.d/psa_cipher_update_ecp.txt

@@ -0,0 +1,2 @@
+Bugfix
+   * Fix a parameter set but unused in psa_crypto_cipher.c. Fixes #4935.

ChangeLog.d/psa_curve448_key_support.txt

@@ -0,0 +1,3 @@
+Features
+   * Enable support for Curve448 via the PSA API. Contributed by
+     Archana Madhavan in #4626. Fixes #3399 and #4249.

ChangeLog.d/psa_sign_message.txt

@@ -1,2 +0,0 @@
-Features
-   * Implement psa_sign_message() and psa_verify_message().

ChangeLog.d/relaxed-psk-semantics.txt

@@ -1,7 +0,0 @@
-API changes
-    * Modify semantics of `mbedtls_ssl_conf_[opaque_]psk()`:
-      In Mbed TLS 2.X, the API prescribes that later calls overwrite
-      the effect of earlier calls. In Mbed TLS 3.0, calling
-      `mbedtls_ssl_conf_[opaque_]psk()` more than once will fail,
-      leaving the PSK that was configured first intact.
-      Support for more than one PSK may be added in 3.X.

ChangeLog.d/remove-config-psa-crypto.txt

@@ -1,3 +0,0 @@
-Changes
-   * Remove configs/config-psa-crypto.h, which no longer had any intended
-     differences from the default configuration, but had accidentally diverged.

ChangeLog.d/remove-enable-weak-ciphersuites.txt

@@ -1,2 +0,0 @@
-Removals
-   * Remove MBEDTLS_ENABLE_WEAK_CIPHERSUITES configuration option. Fixes #4416.

ChangeLog.d/remove-max-content-len.txt

@@ -1,4 +0,0 @@
-Removals
-   * Remove MBEDTLS_SSL_MAX_CONTENT_LEN configuration option, since
-     MBEDTLS_SSL_IN_CONTENT_LEN and MBEDTLS_SSL_OUT_CONTENT_LEN replace
-     it. Fixes #4362.

ChangeLog.d/remove-rsa-mode-parameter.txt

@@ -1,9 +0,0 @@
-Removals
-   * The RSA module no longer supports private-key operations with the public
-     key and vice versa.
-API changes
-   * Remove the mode parameter from RSA operation functions. Signature and
-     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.

ChangeLog.d/remove_null_entropy.txt

@@ -1,2 +0,0 @@
-API changes
-   * Remove the MBEDTLS_TEST_NULL_ENTROPY config option. Fixes #4388.

ChangeLog.d/rm-ticket-lifetime-option

@@ -1,5 +0,0 @@
-Removals
-   * Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
-     compile-time option. This option has been inactive for a long time.
-     Please use the `lifetime` parameter of `mbedtls_ssl_ticket_setup()`
-     instead.

ChangeLog.d/session-cache-api.txt

@@ -1,5 +0,0 @@
-API changes
-    * The getter and setter API of the SSL session cache (used for
-      session-ID based session resumption) has changed to that of
-      a key-value store with keys being session IDs and values
-      being opaque instances of `mbedtls_ssl_session`.

ChangeLog.d/session_export_private.txt

@@ -0,0 +1,5 @@
+Changes
+    * Explicitly mark the fields mbedtls_ssl_session.exported and
+      mbedtls_ssl_config.respect_cli_pref as private. This was an
+      oversight during the run-up to the release of Mbed TLS 3.0.
+      The fields were never intended to be public.

ChangeLog.d/sha224_sha384.txt

@@ -1,7 +0,0 @@
-API changes
-   * Replace MBEDTLS_SHA512_NO_SHA384 config option with MBEDTLS_SHA384_C.
-     This separates config option enabling the SHA384 algorithm from option
-     enabling the SHA512 algorithm. Fixes #4034.
-   * Introduce MBEDTLS_SHA224_C.
-     This separates config option enabling the SHA224 algorithm from option
-     enabling SHA256.

ChangeLog.d/sha512-output-type.txt

@@ -1,6 +0,0 @@
-API changes
-   * The output parameter of mbedtls_sha512_finish_ret, mbedtls_sha512_ret,
-     mbedtls_sha256_finish_ret and mbedtls_sha256_ret now has a pointer type
-     rather than array type. This removes spurious warnings in some compilers
-     when outputting a SHA-384 or SHA-224 hash into a buffer of exactly
-     the hash size.

ChangeLog.d/ssl-error-code-cleanup.txt

@@ -1,6 +0,0 @@
-API changes
-   * Remove SSL error codes `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED`
-     and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` which are never
-     returned from the public SSL API.
-   * Remove `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` and return
-     `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead.

ChangeLog.d/tls_ext_cid-config.txt

@@ -0,0 +1,3 @@
+Features
+   * The identifier of the CID TLS extension can be configured by defining
+     MBEDTLS_TLS_EXT_CID at compile time.

ChangeLog.d/undefined_reference_without_psa.txt

@@ -1,4 +0,0 @@
-Bugfix
-   * With MBEDTLS_PSA_CRYPTO_C disabled, some functions were getting built
-     nonetheless, resulting in undefined reference errors when building a
-     shared library. Reported by Guillermo Garcia M. in #4411.

ChangeLog.d/x509_remove_info.txt

@@ -1,6 +0,0 @@
-API changes
-   * Add configuration option MBEDTLS_X509_REMOVE_INFO which
-     removes the mbedtls_x509_*_info(), mbedtls_debug_print_crt()
-     as well as other functions and constants only used by
-     those functions. This reduces the code footprint by
-     several kB.

README.md

@@ -5,15 +5,10 @@ Mbed TLS is a C library that implements cryptographic primitives, X.509 certific
 
 Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). This is currently a preview for evaluation purposes only.
 
-Stability
----------
-
-**Warning: the [`development`](https://github.com/ARMmbed/mbedtls/tree/development) branch of Mbed TLS currently has an unstable API.** It is where work is happening on the next major release of Mbed TLS. Until Mbed TLS 3.0 is released, if you need a stable API, please use the branch [`development_2.x`](https://github.com/ARMmbed/mbedtls/tree/development_2.x) instead.
-
 Configuration
 -------------
 
-Mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully documented configuration file `include/mbedtls/config.h`, which is also the place where features can be selected. This file can be edited manually, or in a more programmatic way using the Python 3 script `scripts/config.py` (use `--help` for usage instructions).
+Mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully documented configuration file `include/mbedtls/mbedtls_config.h`, which is also the place where features can be selected. This file can be edited manually, or in a more programmatic way using the Python 3 script `scripts/config.py` (use `--help` for usage instructions).
 
 Compiler options can be set using conventional environment variables such as `CC` and `CFLAGS` when using the Make and CMake build system (see below).
 
@@ -26,7 +21,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 +34,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 +44,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.
+* 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, IAR8 and Visual Studio 2013. More recent versions should work. Slightly older versions may work.
+* 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 to generate the test code, and to generate sample programs in the development branch.
+* 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
 
@@ -181,6 +179,33 @@ Regarding variables, also note that if you set CFLAGS when invoking cmake,
 your value of CFLAGS doesn't override the content provided by cmake (depending
 on the build mode as seen above), it's merely prepended to it.
 
+#### Consuming Mbed TLS
+
+Mbed TLS provides a package config file for consumption as a dependency in other
+CMake projects. You can include Mbed TLS's CMake targets yourself with:
+
+    find_package(MbedTLS)
+
+If prompted, set `MbedTLS_DIR` to `${YOUR_MBEDTLS_INSTALL_DIR}/cmake`. This
+creates the following targets:
+
+- `MbedTLS::mbedcrypto` (Crypto library)
+- `MbedTLS::mbedtls` (TLS library)
+- `MbedTLS::mbedx509` (X509 library)
+
+You can then use these directly through `target_link_libraries()`:
+
+    add_executable(xyz)
+
+    target_link_libraries(xyz
+        PUBLIC MbedTLS::mbedtls
+               MbedTLS::mbedcrypto
+               MbedTLS::mbedx509)
+
+This will link the Mbed TLS libraries to your library or application, and add
+its include directories to your target (transitively, in the case of `PUBLIC` or
+`INTERFACE` link libraries).
+
 #### Mbed TLS as a subproject
 
 Mbed TLS supports being built as a CMake subproject. One can
@@ -212,7 +237,7 @@ For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, ad
 -   `tests/compat.sh` tests interoperability of every ciphersuite with other implementations.
 -   `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations.
 -   `tests/scripts/key-exchanges.pl` test builds in configurations with a single key exchange enabled
--   `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `config.h`, etc).
+-   `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc).
 
 Porting Mbed TLS
 ----------------
@@ -251,7 +276,7 @@ A browsable copy of the PSA Cryptography API documents is available on the [PSA
 Mbed TLS includes a reference implementation of the PSA Cryptography API.
 This implementation is not yet as mature as the rest of the library. Some parts of the code have not been reviewed as thoroughly, and some parts of the PSA implementation are not yet well optimized for code size.
 
-The X.509 and TLS code can use PSA cryptography for a limited subset of operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `config.h`.
+The X.509 and TLS code can use PSA cryptography for a limited subset of operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `mbedtls_config.h`.
 
 There are currently a few deviations where the library does not yet implement the latest version of the specification. Please refer to the [compliance issues on Github](https://github.com/ARMmbed/mbed-crypto/labels/compliance) for an up-to-date list.
 

cmake/MbedTLSConfig.cmake.in

@@ -0,0 +1,3 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/MbedTLSTargets.cmake")

configs/README.txt

@@ -4,12 +4,10 @@ The examples are generally focused on a particular usage case (eg, support for
 a restricted number of ciphersuites) and aim at minimizing resource usage for
 this target. They can be used as a basis for custom configurations.
 
-These files are complete replacements for the default config.h. To use one of
+These files are complete replacements for the default mbedtls_config.h. To use one of
 them, you can pick one of the following methods:
 
-1. Replace the default file include/mbedtls/config.h with the chosen one.
+1. Replace the default file include/mbedtls/mbedtls_config.h with the chosen one.
-   (Depending on your compiler, you may need to adjust the line with
-   #include "mbedtls/check_config.h" then.)
 
 2. Define MBEDTLS_CONFIG_FILE and adjust the include path accordingly.
    For example, using make:

configs/config-ccm-psk-tls1_2.h

@@ -29,8 +29,6 @@
  *
  * See README.txt for usage instructions.
  */
-#ifndef MBEDTLS_CONFIG_H
-#define MBEDTLS_CONFIG_H
 
 /* System support */
 //#define MBEDTLS_HAVE_TIME /* Optionally used in Hello messages */
@@ -85,7 +83,3 @@
  */
 #define MBEDTLS_SSL_IN_CONTENT_LEN             1024
 #define MBEDTLS_SSL_OUT_CONTENT_LEN             1024
-
-#include "mbedtls/check_config.h"
-
-#endif /* MBEDTLS_CONFIG_H */

configs/config-no-entropy.h

@@ -29,9 +29,6 @@
  * See README.txt for usage instructions.
  */
 
-#ifndef MBEDTLS_CONFIG_H
-#define MBEDTLS_CONFIG_H
-
 /* System support */
 #define MBEDTLS_HAVE_ASM
 #define MBEDTLS_HAVE_TIME
@@ -49,8 +46,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
@@ -88,7 +83,3 @@
 
 /* Miscellaneous options */
 #define MBEDTLS_AES_ROM_TABLES
-
-#include "mbedtls/check_config.h"
-
-#endif /* MBEDTLS_CONFIG_H */

configs/config-suite-b.h

@@ -33,9 +33,6 @@
  * See README.txt for usage instructions.
  */
 
-#ifndef MBEDTLS_CONFIG_H
-#define MBEDTLS_CONFIG_H
-
 /* System support */
 #define MBEDTLS_HAVE_ASM
 #define MBEDTLS_HAVE_TIME
@@ -84,8 +81,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-bit EC curve = 48 bytes
-#define MBEDTLS_MPI_MAX_SIZE    48 // 384 bits is 48 bytes
 
 /* Save RAM at the expense of speed, see ecp.h */
 #define MBEDTLS_ECP_WINDOW_SIZE        2
@@ -114,7 +110,3 @@
  */
 #define MBEDTLS_SSL_IN_CONTENT_LEN             1024
 #define MBEDTLS_SSL_OUT_CONTENT_LEN             1024
-
-#include "mbedtls/check_config.h"
-
-#endif /* MBEDTLS_CONFIG_H */

configs/config-symmetric-only.h

@@ -20,9 +20,6 @@
  *  limitations under the License.
  */
 
-#ifndef MBEDTLS_CONFIG_H
-#define MBEDTLS_CONFIG_H
-
 /* System support */
 //#define MBEDTLS_HAVE_ASM
 #define MBEDTLS_HAVE_TIME
@@ -47,11 +44,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 +63,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,10 +87,3 @@
 //#define MBEDTLS_THREADING_C
 #define MBEDTLS_TIMING_C
 #define MBEDTLS_VERSION_C
-#define MBEDTLS_XTEA_C
-
-#include "mbedtls/config_psa.h"
-
-#include "check_config.h"
-
-#endif /* MBEDTLS_CONFIG_H */

configs/config-thread.h

@@ -32,9 +32,6 @@
  * See README.txt for usage instructions.
  */
 
-#ifndef MBEDTLS_CONFIG_H
-#define MBEDTLS_CONFIG_H
-
 /* System support */
 #define MBEDTLS_HAVE_ASM
 
@@ -85,12 +82,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-bit EC curve = 32 bytes
-#define MBEDTLS_MPI_MAX_SIZE              32 // 256 bits is 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
-
-#include "mbedtls/check_config.h"
-
-#endif /* MBEDTLS_CONFIG_H */

docs/3.0-migration-guide.d/00README

@@ -1,27 +0,0 @@
-Please add your migration guide entries here. Until 3.0 is released, each PR
-that makes backwards-incompatible changes should add a file here, with the
-extension .md, a descriptive name and the following format:
-
----%<------%<------%<------%<------%<------%<------%<------%<---
-
-The change that was made
-------------------------
-
-Who exactly is affected: does this affect users of the default config, of a
-particular feature? Remember to contextualise.
-
-If I'm affected, what's my migration path? How should I change my code if this
-is an API change; if a feature was removed what are my alternatives?
-
----%<------%<------%<------%<------%<------%<------%<------%<---
-
-PRs that make multiple independent changes should include one entry for each
-changes or logical groups of changes. You can either add multiple files or put
-multiple entries in the same file.
-
-For examples, have a look a docs/3.0-migration-guide.md (which includes the
-top-level header and an intro before the list of entries).
-
-As part of release preparation, the entries in this directory will be appended
-to docs/3.0-migration-guide.md and then re-ordered and reviewed one last time.
-The file is then going to be moved to the version-independent docs repo.

docs/3.0-migration-guide.d/cipher-delayed-output.md

@@ -1,15 +0,0 @@
-Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations
-----------------------------------------------------------------------------
-
-This only affects people who use the cipher module to perform AEAD operations
-using the multi-part API.
-
-Previously, the documentation didn't state explicitly if it was OK to call
-`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after
-the last call to `mbedtls_cipher_update()` - that is, without calling
-`mbedtls_cipher_finish()` in-between. If you code was missing that call,
-please add it and be prepared to get as much as 15 bytes of output.
-
-Currently the output is always 0 bytes, but it may be more when alternative
-implementations of the underlying primitives are in use, or with future
-versions of the library.

docs/3.0-migration-guide.d/csr-add-critical-extension.md

@@ -1,9 +0,0 @@
-Change the API to allow adding critical extensions to CSRs
-------------------------------------------------------------------
-
-This affects applications that call the `mbedtls_x509write_csr_set_extension`
-function.
-
-The API is changed to include the parameter `critical` which allow to mark an
-extension included in a CSR as critical. To get the previous behaviour pass
-`0`.

docs/3.0-migration-guide.d/gcm-alt.md

@@ -1,10 +0,0 @@
-GCM interface changes: impact for alternative implementations
--------------------------------------------------------------
-
-The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows:
-
-* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times.
-* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes:
-    * Always return the partial output immediately, even if it does not consist of a whole number of blocks.
-    * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`.
-* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed.

docs/3.0-migration-guide.d/gcm-multipart.md

@@ -1,13 +0,0 @@
-GCM multipart interface: application changes
---------------------------------------------
-
-The GCM module now supports arbitrary chunked input in the multipart interface.
-This changes the interface for applications using the GCM module directly for multipart operations.
-Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes.
-
-* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data.
-* The current implementation has a limitation that `mbedtls_gcm_update_ad()` may only be called once. This limitation will be lifted shortly; watch https://github.com/ARMmbed/mbedtls/issues/4351 for updates.
-* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case:
-    * As long as the input remains block-aligned, the output length is exactly the input length, as before.
-    * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`.
-* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time.

docs/3.0-migration-guide.d/modify_SHA384_option_behaviour.md

@@ -1,12 +0,0 @@
-Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C
-------------------------------------------------------
-
-This does not affect users who use the default `config.h`.
-MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is
-enabled by default.
-
-If you were using a config file with both MBEDTLS_SHA512_C and
-MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384.
-If you were using a config file with MBEDTLS_SHA512_C and without
-MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add
-`#define MBEDTLS_SHA384_C` to your config file.

docs/3.0-migration-guide.d/relaxed-psk-semantics.md

@@ -1,18 +0,0 @@
-Relaxed semantics for PSK configuration
------------------------------------------------------------------
-
-This affects users which call the PSK configuration APIs
-`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
-multiple times on the same SSL configuration.
-
-In Mbed TLS 2.x, users would observe later calls overwriting
-the effect of earlier calls, with the prevailing PSK being
-the one that has been configured last. In Mbed TLS 3.0,
-calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times
-will return an error, leaving the first PSK intact.
-
-To achieve equivalent functionality when migrating to Mbed TLS 3.0,
-users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should
-remove all but the last call, so that only one call to _either_
-`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()`
-remains.

docs/3.0-migration-guide.d/remove-enable-weak-ciphersuites.md

@@ -1,12 +0,0 @@
-Remove the configuration to enable weak ciphersuites in SSL / TLS
------------------------------------------------------------------
-
-This does not affect users who use the default `config.h`, as this option was
-already off by default.
-
-If you were using a weak cipher, please switch to any of the modern,
-recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example)
-and if your peer doesn't support any, encourage them to upgrade their software.
-
-If you were using a ciphersuite without encryption, you just have to
-enable MBEDTLS_CIPHER_NULL_CIPHER now.

docs/3.0-migration-guide.d/remove-max-content-len.md

@@ -1,10 +0,0 @@
-Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option
--------------------------------------------------------------
-
-This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to
-set the maximum length of incoming and outgoing plaintext fragments,
-which can save memory by reducing the size of the TLS I/O buffers.
-
-This option is replaced by the more fine-grained options
-`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set
-the maximum incoming and outgoing plaintext fragment lengths, respectively.

docs/3.0-migration-guide.d/remove-null-entropy.md

@@ -1,11 +0,0 @@
-Remove the option to build the library without any entropy sources
-------------------------------------------------------------------
-
-This does not affect users who use the default `config.h`, as this option was
-already off by default.
-
-If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform
-doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED`
-and make sure your device is provisioned with a strong random seed.
-Alternatively, for testing purposes only, you can create and register a fake
-entropy function.

docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md

@@ -1,29 +0,0 @@
-Remove the mode parameter from RSA functions
---------------------------------------------
-
-This affects all users who use the RSA encryption, decryption, sign and
-verify APIs.
-
-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 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.
-
-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.

docs/3.0-migration-guide.d/remove_SSL_DTLS_BADMAC_LIMIT_option.md

@@ -1,11 +0,0 @@
-Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option
--------------------------------------------
-
-This change does not affect users who used the default `config.h`, as the option
-MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default.
-
-This option was a trade-off between functionality and code size: it allowed
-users who didn't need that feature to avoid paying the cost in code size, by
-disabling it.
-
-This option is no longer present, but its functionality is now always enabled.

docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md

@@ -1,72 +0,0 @@
-Deprecated functions were removed from AES
-------------------------------------------
-
-The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were
-removed.
-
-If you're simply using the AES module, you should be calling the higher-level
-functions `mbedtls_aes_crypt_xxx()`.
-
-If you're providing an alternative implementation using
-`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be
-replacing the removed functions with `mbedtls_internal_aes_encrypt()` and
-`mbedtls_internal_aes_decrypt()` respectively.
-
-Deprecated functions were removed from bignum
----------------------------------------------
-
-The function `mbedtls_mpi_is_prime()` was removed. Please use
-`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the
-number of Miller-Rabin rounds.
-
-Deprecated functions were removed from cipher
----------------------------------------------
-
-The functions `mbedtls_cipher_auth_encrypt()` and
-`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by
-`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()`
-respectively which additionally support key wrapping algorithms such as
-NIST_KW.
-
-Deprecated functions were removed from DRBGs
---------------------------------------------
-
-The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()`
-were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and
-`mbedtls_hmac_drbg_update_ret()` respectively.
-
-Deprecated functions were removed from ECDSA
---------------------------------------------
-
-The functions `mbedtls_ecdsa_write_signature_det()` and
-`mbedtls_ecdsa_sign_det()` were removed. They were superseded by
-`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()`
-respectively.
-
-Deprecated functions were removed from SSL
-------------------------------------------
-
-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.
-
-Deprecated hex-encoded primes were removed from DHM
----------------------------------------------------
-
-The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`,
-`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`,
-`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`,
-`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were
-removed. The primes from RFC 5114 are deprecated because their derivation is not
-documented and therefore their usage constitutes a security risk; they are fully
-removed from the library. Please use parameters from RFC3526 (still in the
-library, only in binary form) or RFC 7919 (also available in the library) or
-other trusted sources instead.
-
-Deprecated net.h file was removed
----------------------------------
-
-The file `include/mbedtls/net.h` was removed because its only function was to
-include `mbedtls/net_sockets.h` which now should be included directly.

docs/3.0-migration-guide.d/remove_ssl_record_checking.md

@@ -1,13 +0,0 @@
-Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default
---------------------------------------------------------------------------
-
-This change does not affect users who use the default config.h, as the
-option MBEDTLS_SSL_RECORD_CHECKING was already on by default.
-
-This option was added only to control compilation of one function,
-mbedtls_ssl_check_record(), which is only useful in some specific cases, so it
-was made optional to allow users who don't need it to save some code space.
-However, the same effect can be achieve by using link-time garbage collection.
-
-Users who changed the default setting of the option need to change the config/
-build system to remove that change.

docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md

@@ -1,11 +0,0 @@
-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
-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.

docs/3.0-migration-guide.d/separate_SHA224_from_SHA256.md

@@ -1,11 +0,0 @@
-Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C
------------------------------------------------------------------
-
-This does not affect users who use the default `config.h`. MBEDTLS_SHA256_C
-was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are
-enabled.
-
-If you were using custom config file with MBEDTLS_SHA256_C enabled, then
-you will need to add `#define MBEDTLS_SHA224_C` option your config.
-Current version of the library does not support enabling MBEDTLS_SHA256_C
-without MBEDTLS_SHA224_C.

docs/3.0-migration-guide.d/session-cache-api.md

@@ -1,28 +0,0 @@
-Session Cache API Change
------------------------------------------------------------------
-
-This affects users who use `mbedtls_ssl_conf_session_cache()`
-to configure a custom session cache implementation different
-from the one Mbed TLS implements in `library/ssl_cache.c`.
-
-Those users will need to modify the API of their session cache
-implementation to that of a key-value store with keys being
-session IDs and values being instances of `mbedtls_ssl_session`:
-
-```
-typedef int mbedtls_ssl_cache_get_t( void *data,
-                                     unsigned char const *session_id,
-                                     size_t session_id_len,
-                                     mbedtls_ssl_session *session );
-typedef int mbedtls_ssl_cache_set_t( void *data,
-                                     unsigned char const *session_id,
-                                     size_t session_id_len,
-                                     const mbedtls_ssl_session *session );
-```
-
-Since the structure of `mbedtls_ssl_session` is no longer public from 3.0
-onwards, portable session cache implementations must not access fields of
-`mbedtls_ssl_session`. See the corresponding migration guide. Users that
-find themselves unable to migrate their session cache functionality without
-accessing fields of `mbedtls_ssl_session` should describe their usecase
-on the Mbed TLS mailing list.

docs/3.0-migration-guide.d/sha512-output-type.md

@@ -1,8 +0,0 @@
-SHA-512 and SHA-256 output type change
---------------------------
-
-The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer.
-
-This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer.
-
-Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly.

docs/3.0-migration-guide.d/ssl-error-code-cleanup.md

@@ -1,20 +0,0 @@
-Removal of some SSL error codes
------------------------------------------------------------------
-
-This affects users manually checking for the following error codes:
-- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED`
-- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
-- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE`
-
-Migration paths:
-- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
-  should never be returned from Mbed TLS, and there is no need to check for it.
-  Users should simply remove manual checks for those codes, and let the Mbed TLS
-  team know if -- contrary to the team's understanding -- there is in fact a situation
-  where one of them was ever returned.
-- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and
-  `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate
-  is too large to fit into the output buffers. Users should check for
-  `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their
-  own certificate against the configured size of the output buffer to understand if
-  the error is due to an overly large certificate.

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.

docs/architecture/testing/psa-storage-format-testing.md

@@ -20,16 +20,22 @@ An alternative, semi-direct approach consists of generating test data under vers
 
 ### Save-and-compare approach
 
-Importing and saving a key is deterministic. Therefore we can ensure the stability of the storage format by creating test cases under a version V of Mbed TLS, where the test case parameters include both the parameters to pass to key creation and the expected state of the storage after the key is created. The test case creates a key as indicated by the parameters, then compares the actual state of the storage with the expected state. In addition, the test case also loads the key and checks that it has the expected data and metadata.
+Importing and saving a key is deterministic. Therefore we can ensure the stability of the storage format by creating test cases under a version V of Mbed TLS, where the test case parameters include both the parameters to pass to key creation and the expected state of the storage after the key is created. The test case creates a key as indicated by the parameters, then compares the actual state of the storage with the expected state.
+
+In addition, the test case also loads the key and checks that it has the expected data and metadata. Import-and-save testing and load-and-check testing can be split into separate test functions with the same payloads.
 
 If the test passes with version V, this means that the test data is consistent with what the implementation does. When the test later runs under version W ≥ V, it creates and reads back a storage state which is known to be identical to the state that V would have produced. Thus, this approach validates that W can read storage states created by V.
 
+Note that it is the combination of import-and-save passing on version V and load-and-check passing on version W with the same data that proves that version W can read back what version V wrote. From the perspective of a particular version of the library, the import-and-save tests guarantee forward compatibility while the load-and-check tests guarantee backward compatibility.
+
 Use a similar approach for files other than keys where possible and relevant.
 
 ### Keeping up with storage format evolution
 
 Test cases should normally not be removed from the code base: if something has worked before, it should keep working in future versions, so we should keep testing it.
 
+This cannot be enforced solely by looking at a single version of Mbed TLS, since there would be no indication that more test cases used to exist. It can only be enforced through review of library changes. The review may be assisted by a tool that compares the old and the new version, in the same way that `abi-check.py` compares the library's API and ABI.
+
 If the way certain keys are stored changes, and we don't deliberately decide to stop supporting old keys (which should only be done by retiring a version of the storage format), then we should keep the corresponding test cases in load-only mode: create a file with the expected content, load it and check the data that it contains.
 
 ## Storage architecture overview
@@ -65,13 +71,18 @@ Method: Create a key with certain metadata with `psa_import_key`. Read the file
 
 Objective: ensure that the coverage is sufficient to have assurance that all keys are stored correctly. This requires a sufficient selection of key types, sizes, policies, etc.
 
-In particular, the tests must validate that each `PSA_xxx` constant that is stored in a key is covered by at least once test case:
+In particular, the tests must validate that each `PSA_xxx` constant that is stored in a key is covered by at least one test case:
 
+* Lifetimes: `PSA_KEY_LIFETIME_xxx`, `PSA_KEY_PERSISTENCE_xxx`, `PSA_KEY_LOCATION_xxx`.
 * Usage flags: `PSA_KEY_USAGE_xxx`.
 * Algorithms in policies: `PSA_ALG_xxx`.
 * Key types: `PSA_KEY_TYPE_xxx`, `PSA_ECC_FAMILY_xxx`, `PSA_DH_FAMILY_xxx`.
 
-Method: Each test case creates a key with `psa_import_key`, purges it from memory, then reads it back and exercises it. Generate test cases automatically based on an enumeration of available constants and some knowledge of what attributes (sizes, algorithms, …) and content to use for keys of a certain type. Note that the generated test cases will be checked into the repository (generating test cases at runtime would not allow us to test the stability of the format, only that a given version is internally consistent).
+In addition, the coverage of key material must ensure that any variation in key representation is detected. See [“Considerations on key material representations”](#Considerations-on-key-material-representations) for considerations regarding key types.
+
+Method: Each test case creates a key with `psa_import_key`, purges it from memory, then reads it back and exercises it.
+
+Generate test cases automatically based on an enumeration of available constants and some knowledge of what attributes (sizes, algorithms, …) and content to use for keys of a certain type.
 
 ### Testing with alternative lifetime values
 
@@ -80,7 +91,20 @@ Objective: have test coverage for lifetimes other than the default persistent li
 Method:
 
 * For alternative locations: have tests conditional on the presence of a driver for that location.
-* For alternative persistence levels: TODO
+* For alternative persistence levels: have load-and-check tests for supported persistence levels. We may also want to have negative tests ensuring that keys with a not-supported persistence level are not accidentally created.
+
+### Considerations on key material representations
+
+The risks of incompatibilities in key representations depends on the key type and on the presence of drivers. Compatibility of and with drivers is currently out of scope of this document.
+
+Some types only have one plausible representation. Others admit alternative plausible representations (different encodings, or non-canonical representations).
+Here are some areas to watch for, with an identified risk of incompatibilities.
+
+* HMAC keys longer than the block size: pre-hashed or not?
+* DES keys: was parity enforced?
+* RSA keys: can invalid DER encodings (e.g. leading zeros, ignored sign bit) have been stored?
+* RSA private keys: can invalid CRT parameters have been stored?
+* Montgomery private keys: were they stored in masked form?
 
 ## Random generator state
 

docs/architecture/testing/test-framework.md

@@ -51,7 +51,7 @@ The outcome file is in a CSV format using `;` (semicolon) as the delimiter and n
 The outcome file has 6 fields:
 
 * **Platform**: a description of the platform, e.g. `Linux-x86_64` or `Linux-x86_64-gcc7-msan`.
-* **Configuration**: a unique description of the configuration (`config.h`).
+* **Configuration**: a unique description of the configuration (`mbedtls_config.h`).
 * **Test suite**: `test_suite_xxx` or `ssl-opt`.
 * **Test case**: the description of the test case.
 * **Result**: one of `PASS`, `SKIP` or `FAIL`.

docs/architecture/tls13-experimental.md

@@ -15,7 +15,7 @@ MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL
 This macro will likely be renamed to `MBEDTLS_SSL_PROTO_TLS1_3` once a minimal viable
 implementation of the TLS 1.3 protocol is available.
 
-See the [documentation of `MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL`](../../include/mbedtls/config.h)
+See the [documentation of `MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL`](../../include/mbedtls/mbedtls_config.h)
 for more information.
 
 Status

docs/proposed/psa-conditional-inclusion-c.md

@@ -15,7 +15,7 @@ The present document proposes a way for an application using the PSA cryptograph
 
 ### Conditional inclusion of legacy cryptography modules
 
-Mbed TLS offers a way to select which cryptographic mechanisms are included in a build through its configuration file (`config.h`). This mechanism is based on two main sets of symbols: `MBEDTLS_xxx_C` controls the availability of the mechanism to the application, and `MBEDTLS_xxx_ALT` controls the availability of an alternative implementation, so the software implementation is only included if `MBEDTLS_xxx_C` is defined but not `MBEDTLS_xxx_ALT`.
+Mbed TLS offers a way to select which cryptographic mechanisms are included in a build through its configuration file (`mbedtls_config.h`). This mechanism is based on two main sets of symbols: `MBEDTLS_xxx_C` controls the availability of the mechanism to the application, and `MBEDTLS_xxx_ALT` controls the availability of an alternative implementation, so the software implementation is only included if `MBEDTLS_xxx_C` is defined but not `MBEDTLS_xxx_ALT`.
 
 ### PSA evolution
 
@@ -51,10 +51,10 @@ The current model is difficult to adapt to the PSA interface for several reasons
 
 The PSA Crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` describes the feature that the symbol enables. The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below.
 
-The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/config.h` determines whether `psa/crypto_config.h` is used.
+The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/mbedtls_config.h` determines whether `psa/crypto_config.h` is used.
 
 * If `MBEDTLS_PSA_CRYPTO_CONFIG` is unset, which is the default at least in Mbed TLS 2.x versions, things are as they are today: the PSA subsystem includes generic code unconditionally, and includes support for specific mechanisms conditionally based on the existing `MBEDTLS_xxx_` symbols.
-* If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA Crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`.
+* If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA Crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/mbedtls_config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`.
 
 ### PSA Crypto configuration symbols
 
@@ -123,17 +123,17 @@ These symbols are not part of the public interface of Mbed TLS towards applicati
 
 #### New-style definition of configuration symbols
 
-When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols.
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/mbedtls_config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols.
 
 `mbedtls/config_psa.h` includes `psa/crypto_config.h`, the user-editable file that defines application requirements.
 
 #### Old-style definition of configuration symbols
 
-When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, the new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`).
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/mbedtls_config.h`. Furthermore, the new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`).
 
 The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that's specific to a given cryptographic mechanism. In Mbed TLS itself, code under `MBEDTLS_USE_PSA_CRYPTO` and conditional compilation guards in tests and sample programs need `PSA_WANT_xxx`.
 
-Since some existing applications use a handwritten `mbedtls/config.h` or an edited copy of `mbedtls/config.h` from an earlier version of Mbed TLS, `mbedtls/config_psa.h` must be included via an already existing header that is not `mbedtls/config.h`, so it is included via `psa/crypto.h` (for example from `psa/crypto_platform.h`).
+Since some existing applications use a handwritten `mbedtls/mbedtls_config.h` or an edited copy of `mbedtls/mbedtls_config.h` from an earlier version of Mbed TLS, `mbedtls/config_psa.h` must be included via an already existing header that is not `mbedtls/mbedtls_config.h`, so it is included via `psa/crypto.h` (for example from `psa/crypto_platform.h`).
 
 #### Summary of definitions of configuration symbols
 
@@ -145,13 +145,13 @@ The following table summarizes where symbols are defined depending on the config
 * (D) indicates a symbol that is deduced from other symbols by code that ships with Mbed TLS.
 * (G) indicates a symbol that is generated from driver descriptions.
 
-| Symbols                   | With `MBEDTLS_PSA_CRYPTO_CONFIG` | Without `MBEDTLS_PSA_CRYPTO_CONFIG` |
+| Symbols                   | With `MBEDTLS_PSA_CRYPTO_CONFIG`  | Without `MBEDTLS_PSA_CRYPTO_CONFIG` |
-| ------------------------- | -------------------------------- | ----------------------------------- |
+| ------------------------- | --------------------------------- | ----------------------------------- |
-| `MBEDTLS_xxx_C`           | `mbedtls/config.h` (U) or        | `mbedtls/config.h` (U)              |
+| `MBEDTLS_xxx_C`           | `mbedtls/mbedtls_config.h` (U) or | `mbedtls/mbedtls_config.h` (U)      |
-|                           | `mbedtls/config_psa.h` (D)       |                                     |
+|                           | `mbedtls/config_psa.h` (D)        |                                     |
-| `PSA_WANT_xxx`            | `psa/crypto_config.h` (U)        | `mbedtls/config_psa.h` (D)          |
+| `PSA_WANT_xxx`            | `psa/crypto_config.h` (U)         | `mbedtls/config_psa.h` (D)          |
-| `MBEDTLS_PSA_BUILTIN_xxx` | `mbedtls/config_psa.h` (D)       | `mbedtls/config_psa.h` (D)          |
+| `MBEDTLS_PSA_BUILTIN_xxx` | `mbedtls/config_psa.h` (D)        | `mbedtls/config_psa.h` (D)          |
-| `MBEDTLS_PSA_ACCEL_xxx`   | `mbedtls/crypto_drivers.h` (G)   | N/A                                 |
+| `MBEDTLS_PSA_ACCEL_xxx`   | `mbedtls/crypto_drivers.h` (G)    | N/A                                 |
 
 #### Visibility of internal symbols
 

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()).

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.
  *

doxygen/input/doc_mainpage.h

@@ -22,7 +22,7 @@
  */
 
 /**
- * @mainpage mbed TLS v2.26.0 source code documentation
+ * @mainpage mbed TLS v3.0.0 source code documentation
  *
  * This documentation describes the internal structure of mbed TLS.  It was
  * automatically generated from specially formatted comment blocks in

doxygen/mbedtls.doxyfile

@@ -28,7 +28,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "mbed TLS v2.26.0"
+PROJECT_NAME           = "mbed TLS v3.0.0"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -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

include/CMakeLists.txt

@@ -15,7 +15,7 @@ if(INSTALL_MBEDTLS_HEADERS)
 
 endif(INSTALL_MBEDTLS_HEADERS)
 
-# Make config.h available in an out-of-source build. ssl-opt.sh requires it.
+# Make mbedtls_config.h available in an out-of-source build. ssl-opt.sh requires it.
 if (ENABLE_TESTING AND NOT ${CMAKE_CURRENT_BINARY_DIR} STREQUAL ${CMAKE_CURRENT_SOURCE_DIR})
     link_to_source(mbedtls)
     link_to_source(psa)

include/mbedtls/aes.h

@@ -39,12 +39,9 @@
 
 #ifndef MBEDTLS_AES_H
 #define MBEDTLS_AES_H
+#include "mbedtls/private_access.h"
 
-#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/build_info.h"
-#include "mbedtls/config.h"
-#else
-#include MBEDTLS_CONFIG_FILE
-#endif
 
 #include <stddef.h>
 #include <stdint.h>
@@ -54,11 +51,14 @@
 #define MBEDTLS_AES_DECRYPT     0 /**< AES decryption. */
 
 /* Error codes in range 0x0020-0x0022 */
-#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */
+/** Invalid key length. */
-#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022  /**< Invalid data input length. */
+#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020
+/** Invalid data input length. */
+#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022
 
 /* Error codes in range 0x0021-0x0025 */
-#define MBEDTLS_ERR_AES_BAD_INPUT_DATA                    -0x0021  /**< Invalid input data. */
+/** Invalid input data. */
+#define MBEDTLS_ERR_AES_BAD_INPUT_DATA                    -0x0021
 
 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
     !defined(inline) && !defined(__cplusplus)
@@ -78,9 +78,9 @@ extern "C" {
  */
 typedef struct mbedtls_aes_context
 {
-    int nr;                     /*!< The number of rounds. */
+    int MBEDTLS_PRIVATE(nr);                     /*!< The number of rounds. */
-    uint32_t *rk;               /*!< AES round keys. */
+    uint32_t *MBEDTLS_PRIVATE(rk);               /*!< AES round keys. */
-    uint32_t buf[68];           /*!< Unaligned data buffer. This buffer can
+    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:
                                      <ul><li>Alignment if VIA padlock is
@@ -97,9 +97,9 @@ mbedtls_aes_context;
  */
 typedef struct mbedtls_aes_xts_context
 {
-    mbedtls_aes_context crypt; /*!< The AES context to use for AES block
+    mbedtls_aes_context MBEDTLS_PRIVATE(crypt); /*!< The AES context to use for AES block
                                         encryption or decryption. */
-    mbedtls_aes_context tweak; /*!< The AES context used for tweak
+    mbedtls_aes_context MBEDTLS_PRIVATE(tweak); /*!< The AES context used for tweak
                                         computation. */
 } mbedtls_aes_xts_context;
 #endif /* MBEDTLS_CIPHER_MODE_XTS */

include/mbedtls/arc4.h

@@ -1,141 +0,0 @@
-/**
- * \file arc4.h
- *
- * \brief The ARCFOUR stream cipher
- *
- * \warning   ARC4 is considered a weak cipher and its use constitutes a
- *            security risk. We recommend considering stronger ciphers instead.
- */
-/*
- *  Copyright The Mbed TLS Contributors
- *  SPDX-License-Identifier: Apache-2.0
- *
- *  Licensed under the Apache License, Version 2.0 (the "License"); you may
- *  not use this file except in compliance with the License.
- *  You may obtain a copy of the License at
- *
- *  http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
- *
- */
-#ifndef MBEDTLS_ARC4_H
-#define MBEDTLS_ARC4_H
-
-#if !defined(MBEDTLS_CONFIG_FILE)
-#include "mbedtls/config.h"
-#else
-#include MBEDTLS_CONFIG_FILE
-#endif
-
-#include <stddef.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#if !defined(MBEDTLS_ARC4_ALT)
-// Regular implementation
-//
-
-/**
- * \brief     ARC4 context structure
- *
- * \warning   ARC4 is considered a weak cipher and its use constitutes a
- *            security risk. We recommend considering stronger ciphers instead.
- *
- */
-typedef struct mbedtls_arc4_context
-{
-    int x;                      /*!< permutation index */
-    int y;                      /*!< permutation index */
-    unsigned char m[256];       /*!< permutation table */
-}
-mbedtls_arc4_context;
-
-#else  /* MBEDTLS_ARC4_ALT */
-#include "arc4_alt.h"
-#endif /* MBEDTLS_ARC4_ALT */
-
-/**
- * \brief          Initialize ARC4 context
- *
- * \param ctx      ARC4 context to be initialized
- *
- * \warning        ARC4 is considered a weak cipher and its use constitutes a
- *                 security risk. We recommend considering stronger ciphers
- *                 instead.
- *
- */
-void mbedtls_arc4_init( mbedtls_arc4_context *ctx );
-
-/**
- * \brief          Clear ARC4 context
- *
- * \param ctx      ARC4 context to be cleared
- *
- * \warning        ARC4 is considered a weak cipher and its use constitutes a
- *                 security risk. We recommend considering stronger ciphers
- *                 instead.
- *
- */
-void mbedtls_arc4_free( mbedtls_arc4_context *ctx );
-
-/**
- * \brief          ARC4 key schedule
- *
- * \param ctx      ARC4 context to be setup
- * \param key      the secret key
- * \param keylen   length of the key, in bytes
- *
- * \warning        ARC4 is considered a weak cipher and its use constitutes a
- *                 security risk. We recommend considering stronger ciphers
- *                 instead.
- *
- */
-void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key,
-                 unsigned int keylen );
-
-/**
- * \brief          ARC4 cipher function
- *
- * \param ctx      ARC4 context
- * \param length   length of the input data
- * \param input    buffer holding the input data
- * \param output   buffer for the output data
- *
- * \return         0 if successful
- *
- * \warning        ARC4 is considered a weak cipher and its use constitutes a
- *                 security risk. We recommend considering stronger ciphers
- *                 instead.
- *
- */
-int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
-                unsigned char *output );
-
-#if defined(MBEDTLS_SELF_TEST)
-
-/**
- * \brief          Checkup routine
- *
- * \return         0 if successful, or 1 if the test failed
- *
- * \warning        ARC4 is considered a weak cipher and its use constitutes a
- *                 security risk. We recommend considering stronger ciphers
- *                 instead.
- *
- */
-int mbedtls_arc4_self_test( int verbose );
-
-#endif /* MBEDTLS_SELF_TEST */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* arc4.h */

include/mbedtls/aria.h

@@ -28,12 +28,9 @@
 
 #ifndef MBEDTLS_ARIA_H
 #define MBEDTLS_ARIA_H
+#include "mbedtls/private_access.h"
 
-#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/build_info.h"
-#include "mbedtls/config.h"
-#else
-#include MBEDTLS_CONFIG_FILE
-#endif
 
 #include <stddef.h>
 #include <stdint.h>
@@ -47,9 +44,11 @@
 #define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maxiumum number of rounds in ARIA. */
 #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
 
-#define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C /**< Bad input data. */
+/** Bad input data. */
+#define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C
 
-#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
+/** Invalid data input length. */
+#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E
 
 #ifdef __cplusplus
 extern "C" {
@@ -64,9 +63,9 @@ extern "C" {
  */
 typedef struct mbedtls_aria_context
 {
-    unsigned char nr;           /*!< The number of rounds (12, 14 or 16) */
+    unsigned char MBEDTLS_PRIVATE(nr);           /*!< The number of rounds (12, 14 or 16) */
     /*! The ARIA round keys. */
-    uint32_t rk[MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];
+    uint32_t MBEDTLS_PRIVATE(rk)[MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];
 }
 mbedtls_aria_context;
 

include/mbedtls/asn1.h

@@ -21,12 +21,9 @@
  */
 #ifndef MBEDTLS_ASN1_H
 #define MBEDTLS_ASN1_H
+#include "mbedtls/private_access.h"
 
-#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/build_info.h"
-#include "mbedtls/config.h"
-#else
-#include MBEDTLS_CONFIG_FILE
-#endif
 
 #include <stddef.h>
 
@@ -46,13 +43,20 @@
  * ASN1 is a standard to specify data structures.
  * \{
  */
-#define MBEDTLS_ERR_ASN1_OUT_OF_DATA                      -0x0060  /**< Out of data when parsing an ASN1 data structure. */
+/** Out of data when parsing an ASN1 data structure. */
-#define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG                   -0x0062  /**< ASN1 tag was of an unexpected value. */
+#define MBEDTLS_ERR_ASN1_OUT_OF_DATA                      -0x0060
-#define MBEDTLS_ERR_ASN1_INVALID_LENGTH                   -0x0064  /**< Error when trying to determine the length or invalid length. */
+/** ASN1 tag was of an unexpected value. */
-#define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH                  -0x0066  /**< Actual length differs from expected length. */
+#define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG                   -0x0062
-#define MBEDTLS_ERR_ASN1_INVALID_DATA                     -0x0068  /**< Data is invalid. */
+/** Error when trying to determine the length or invalid length. */
-#define MBEDTLS_ERR_ASN1_ALLOC_FAILED                     -0x006A  /**< Memory allocation failed */
+#define MBEDTLS_ERR_ASN1_INVALID_LENGTH                   -0x0064
-#define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL                    -0x006C  /**< Buffer too small when writing ASN.1 data structure. */
+/** Actual length differs from expected length. */
+#define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH                  -0x0066
+/** Data is invalid. */
+#define MBEDTLS_ERR_ASN1_INVALID_DATA                     -0x0068
+/** Memory allocation failed */
+#define MBEDTLS_ERR_ASN1_ALLOC_FAILED                     -0x006A
+/** Buffer too small when writing ASN.1 data structure. */
+#define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL                    -0x006C
 
 /* \} name */
 
@@ -148,9 +152,9 @@ extern "C" {
  */
 typedef struct mbedtls_asn1_buf
 {
-    int tag;                /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
+    int MBEDTLS_PRIVATE(tag);                /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
-    size_t len;             /**< ASN1 length, in octets. */
+    size_t MBEDTLS_PRIVATE(len);             /**< ASN1 length, in octets. */
-    unsigned char *p;       /**< ASN1 data, e.g. in ASCII. */
+    unsigned char *MBEDTLS_PRIVATE(p);       /**< ASN1 data, e.g. in ASCII. */
 }
 mbedtls_asn1_buf;
 
@@ -159,9 +163,9 @@ mbedtls_asn1_buf;
  */
 typedef struct mbedtls_asn1_bitstring
 {
-    size_t len;                 /**< ASN1 length, in octets. */
+    size_t MBEDTLS_PRIVATE(len);                 /**< ASN1 length, in octets. */
-    unsigned char unused_bits;  /**< Number of unused bits at the end of the string */
+    unsigned char MBEDTLS_PRIVATE(unused_bits);  /**< Number of unused bits at the end of the string */
-    unsigned char *p;           /**< Raw ASN1 data for the bit string */
+    unsigned char *MBEDTLS_PRIVATE(p);           /**< Raw ASN1 data for the bit string */
 }
 mbedtls_asn1_bitstring;
 
@@ -170,8 +174,8 @@ mbedtls_asn1_bitstring;
  */
 typedef struct mbedtls_asn1_sequence
 {
-    mbedtls_asn1_buf buf;                   /**< Buffer containing the given ASN.1 item. */
+    mbedtls_asn1_buf MBEDTLS_PRIVATE(buf);                   /**< Buffer containing the given ASN.1 item. */
-    struct mbedtls_asn1_sequence *next;    /**< The next entry in the sequence. */
+    struct mbedtls_asn1_sequence *MBEDTLS_PRIVATE(next);    /**< The next entry in the sequence. */
 }
 mbedtls_asn1_sequence;
 
@@ -180,10 +184,10 @@ mbedtls_asn1_sequence;
  */
 typedef struct mbedtls_asn1_named_data
 {
-    mbedtls_asn1_buf oid;                   /**< The object identifier. */
+    mbedtls_asn1_buf MBEDTLS_PRIVATE(oid);                   /**< The object identifier. */
-    mbedtls_asn1_buf val;                   /**< The named value. */
+    mbedtls_asn1_buf MBEDTLS_PRIVATE(val);                   /**< The named value. */
-    struct mbedtls_asn1_named_data *next;  /**< The next entry in the sequence. */
+    struct mbedtls_asn1_named_data *MBEDTLS_PRIVATE(next);  /**< The next entry in the sequence. */
-    unsigned char next_merged;      /**< Merge next item into the current one? */
+    unsigned char MBEDTLS_PRIVATE(next_merged);      /**< Merge next item into the current one? */
 }
 mbedtls_asn1_named_data;