Merge branch 'Mbed-TLS:development' into codegen_1.1

.travis.yml

@@ -54,7 +54,7 @@ after_failure:
 env:
   global:
     - SEED=1
-    - secure: "FrI5d2s+ckckC17T66c8jm2jV6i2DkBPU5nyWzwbedjmEBeocREfQLd/x8yKpPzLDz7ghOvr+/GQvsPPn0dVkGlNzm3Q+hGHc/ujnASuUtGrcuMM+0ALnJ3k4rFr9xEvjJeWb4SmhJO5UCAZYvTItW4k7+bj9L+R6lt3TzQbXzg="
+    - secure: "JECCru6HASpKZ0OLfHh8f/KXhKkdrCwjquZghd/qbA4ksxsWImjR7KEPERcaPndXEilzhDbKwuFvJiQX2duVgTGoq745YGhLZIjzo1i8tySkceCVd48P8WceYGz+F/bmY7r+m6fFNuxDSoGGSVeA4Lnjvmm8PFUP45YodDV9no4="
 
 install:
   - $PYTHON scripts/min_requirements.py

3rdparty/everest/CMakeLists.txt

@@ -23,5 +23,5 @@ endif(INSTALL_MBEDTLS_HEADERS)
 
 install(TARGETS everest
   EXPORT MbedTLSTargets
-  DESTINATION ${LIB_INSTALL_DIR}
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}
   PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ)

3rdparty/everest/README.md

@@ -2,4 +2,4 @@ The files in this directory stem from [Project Everest](https://project-everest.
 
 This is a formally verified implementation of Curve25519-based handshakes. The C code is automatically derived from the (verified) [original implementation](https://github.com/project-everest/hacl-star/tree/master/code/curve25519) in the [F* language](https://github.com/fstarlang/fstar) by [KreMLin](https://github.com/fstarlang/kremlin). In addition to the improved safety and security of the implementation, it is also significantly faster than the default implementation of Curve25519 in mbedTLS.
 
-The caveat is that not all platforms are supported, although the version in `everest/library/legacy` should work on most systems. The main issue is that some platforms do not provide a 128-bit integer type and KreMLin therefore has to use additional (also verified) code to simulate them, resulting in less of a performance gain overall. Explictly supported platforms are currently `x86` and `x86_64` using gcc or clang, and Visual C (2010 and later).
+The caveat is that not all platforms are supported, although the version in `everest/library/legacy` should work on most systems. The main issue is that some platforms do not provide a 128-bit integer type and KreMLin therefore has to use additional (also verified) code to simulate them, resulting in less of a performance gain overall. Explicitly supported platforms are currently `x86` and `x86_64` using gcc or clang, and Visual C (2010 and later).

3rdparty/everest/include/everest/everest.h

@@ -96,7 +96,7 @@ int mbedtls_everest_make_params( mbedtls_ecdh_context_everest *ctx, size_t *olen
                                  void *p_rng );
 
 /**
- * \brief           This function parses and processes a TLS ServerKeyExhange
+ * \brief           This function parses and processes a TLS ServerKeyExchange
  *                  payload.
  *
  *                  This is the first function used by a TLS client for ECDHE
@@ -116,7 +116,7 @@ int mbedtls_everest_read_params( mbedtls_ecdh_context_everest *ctx,
                                  const unsigned char **buf, const unsigned char *end );
 
 /**
- * \brief           This function parses and processes a TLS ServerKeyExhange
+ * \brief           This function parses and processes a TLS ServerKeyExchange
  *                  payload.
  *
  *                  This is the first function used by a TLS client for ECDHE

3rdparty/everest/library/Hacl_Curve25519_joined.c

@@ -18,6 +18,15 @@
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
  */
+#ifndef _BSD_SOURCE
+/* Required to get htole64() from gcc/glibc's endian.h (older systems)
+ * when we compile with -std=c99 */
+#define _BSD_SOURCE
+#endif
+#ifndef _DEFAULT_SOURCE
+/* (modern version of _BSD_SOURCE) */
+#define _DEFAULT_SOURCE
+#endif
 
 #include "common.h"
 

BRANCHES.md

@@ -2,24 +2,19 @@
 
 At any point in time, we have a number of maintained branches, currently consisting of:
 
-- The [`master`](https://github.com/ARMmbed/mbedtls/tree/master) branch:
+- The [`master`](https://github.com/Mbed-TLS/mbedtls/tree/master) branch:
   this always contains the latest release, including all publicly available
   security fixes.
-- The [`development`](https://github.com/ARMmbed/mbedtls/tree/development) branch:
+- The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch:
   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.
 - One or more long-time support (LTS) branches: these only get bug fixes and
   security fixes. Currently, the only supported LTS branch is:
-  [`mbedtls-2.28`](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.28).
+  [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28).
-- For a short time we also have the previous LTS, which has recently ended its
-  support period,
-  [`mbedtls-2.16`](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.16).
-  This branch will move into the `archive` namespace around the time of
-  the next release.
 
 We retain a number of historical branches, whose names are prefixed by `archive/`,
-such as [`archive/mbedtls-2.7`](https://github.com/ARMmbed/mbedtls/tree/archive/mbedtls-2.7).
+such as [`archive/mbedtls-2.7`](https://github.com/Mbed-TLS/mbedtls/tree/archive/mbedtls-2.7).
 These branches will not receive any changes or updates.
 
 We use [Semantic Versioning](https://semver.org/). In particular, we maintain
@@ -28,7 +23,7 @@ the API of 3.(x+1) is backward compatible with 3.x). We only break API
 compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain
 ABI compatibility within LTS branches; see the next section for details.
 
-## Backwards Compatibility
+## Backwards Compatibility for application code
 
 We maintain API compatibility in released versions of Mbed TLS. If you have
 code that's working and secure with Mbed TLS x.y.z and does not rely on
@@ -36,6 +31,14 @@ 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.
 
+Note that this guarantee only applies if you either use the default
+compile-time configuration (`mbedtls/mbedtls_config.h`) or the same modified
+compile-time configuration. Changing compile-time configuration options can
+result in an incompatible API or ABI, although features will generally not
+affect unrelated features (for example, enabling or disabling a
+cryptographic algorithm does not break code that does not use that
+algorithm).
+
 Note that new releases of Mbed TLS may extend the API. Here are some
 examples of changes that are common in minor releases of Mbed TLS, and are
 not considered API compatibility breaks:
@@ -57,6 +60,25 @@ 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.
 
+## Backward compatibility for the key store
+
+We maintain backward compatibility with previous versions of the
+PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the
+storage backend (PSA ITS implementation) is configured in a compatible way.
+We intend to maintain this backward compatibility throughout a major version
+of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read
+keys written under any Mbed TLS 3.x with x <= y).
+
+Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x
+LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y)
+may require the use of an upgrade tool.
+
+Note that this guarantee does not currently fully extend to drivers, which
+are an experimental feature. We intend to maintain compatibility with the
+basic use of drivers from Mbed TLS 2.28.0 onwards, even if driver APIs
+change. However, for more experimental parts of the driver interface, such
+as the use of driver state, we do not yet guarantee backward compatibility.
+
 ## Long-time support branches
 
 For the LTS branches, additionally we try very hard to also maintain ABI
@@ -75,10 +97,10 @@ CONTRIBUTING](CONTRIBUTING.md#backwards-compatibility).
 
 The following branches are currently maintained:
 
-- [master](https://github.com/ARMmbed/mbedtls/tree/master)
+- [master](https://github.com/Mbed-TLS/mbedtls/tree/master)
-- [`development`](https://github.com/ARMmbed/mbedtls/)
+- [`development`](https://github.com/Mbed-TLS/mbedtls/)
-- [`mbedtls-2.28`](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.28)
+- [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28)
  maintained until at least the end of 2024, see
-  <https://github.com/ARMmbed/mbedtls/releases/tag/v2.28.0>.
+  <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.0>.
 
 Users are urged to always use the latest version of a maintained branch.

BUGS.md

@@ -1,6 +1,6 @@
 ## Known issues
 
-Known issues in Mbed TLS are [tracked on GitHub](https://github.com/ARMmbed/mbedtls/issues).
+Known issues in Mbed TLS are [tracked on GitHub](https://github.com/Mbed-TLS/mbedtls/issues).
 
 ## Reporting a bug
 
@@ -9,12 +9,12 @@ If you think you've found a bug in Mbed TLS, please follow these steps:
 1. Make sure you're using the latest version of a
    [maintained branch](BRANCHES.md): `master`, `development`,
    or a long-time support branch.
-2. Check [GitHub](https://github.com/ARMmbed/mbedtls/issues) to see if
+2. Check [GitHub](https://github.com/Mbed-TLS/mbedtls/issues) to see if
    your issue has already been reported. If not, …
 3. If the issue is a security risk (for example: buffer overflow,
    data leak), please report it confidentially as described in
    [`SECURITY.md`](SECURITY.md). If not, …
-4. Please [create an issue on on GitHub](https://github.com/ARMmbed/mbedtls/issues).
+4. Please [create an issue on on GitHub](https://github.com/Mbed-TLS/mbedtls/issues).
 
 Please do not use GitHub for support questions. If you want to know
 how to do something with Mbed TLS, please see [`SUPPORT.md`](SUPPORT.md) for available documentation and support channels.

CMakeLists.txt

@@ -6,9 +6,9 @@
 #     command but rather at the target level using the
 #     target_include_directories command. That way, it is easier to guarantee
 #     that targets are built using the proper list of include directories.
-#   + Use the PUBLIC and PRIVATE keywords to specifiy the scope of include
+#   + Use the PUBLIC and PRIVATE keywords to specify the scope of include
 #     directories. That way, a target linking to a library (using the
-#     target_link_librairies command) inherits from the library PUBLIC include
+#     target_link_libraries command) inherits from the library PUBLIC include
 #     directories and not from the PRIVATE ones.
 # - MBEDTLS_TARGET_PREFIX: CMake targets are designed to be alterable by calling
 #   CMake in order to avoid target name clashes, via the use of
@@ -39,6 +39,8 @@ else()
     project("mbed TLS" C)
 endif()
 
+include(GNUInstallDirs)
+
 # Determine if mbed TLS is being built as a subproject using add_subdirectory()
 if(NOT DEFINED MBEDTLS_AS_SUBPROJECT)
   set(MBEDTLS_AS_SUBPROJECT ON)
@@ -54,7 +56,7 @@ option(ENABLE_PROGRAMS "Build mbed TLS programs." ON)
 
 option(UNSAFE_BUILD "Allow unsafe builds. These builds ARE NOT SECURE." OFF)
 option(MBEDTLS_FATAL_WARNINGS "Compiler warnings treated as errors" ON)
-if(WIN32)
+if(CMAKE_HOST_WIN32)
     option(GEN_FILES "Generate the auto-generated files as needed" OFF)
 else()
     option(GEN_FILES "Generate the auto-generated files as needed" ON)
@@ -129,7 +131,10 @@ function(link_to_source base_name)
         set(target "${CMAKE_CURRENT_SOURCE_DIR}/${base_name}")
     endif()
 
-    if (NOT EXISTS ${link})
+    # Linking to non-existent file is not desirable. At best you will have a
+    # dangling link, but when building in tree, this can create a symbolic link
+    # to itself.
+    if (EXISTS ${target} AND NOT EXISTS ${link})
         if (CMAKE_HOST_UNIX)
             set(command ln -s ${target} ${link})
         else()
@@ -170,6 +175,9 @@ string(REGEX MATCH "Clang" CMAKE_COMPILER_IS_CLANG "${CMAKE_C_COMPILER_ID}")
 
 include(CheckCCompilerFlag)
 
+set(CMAKE_C_EXTENSIONS OFF)
+set(CMAKE_C_STANDARD 99)
+
 if(CMAKE_COMPILER_IS_GNU)
     # some warnings we want are not available with old GCC versions
     # note: starting with CMake 2.8 we could use CMAKE_C_COMPILER_VERSION
@@ -219,7 +227,7 @@ if(CMAKE_COMPILER_IS_CLANG)
 endif(CMAKE_COMPILER_IS_CLANG)
 
 if(CMAKE_COMPILER_IS_IAR)
-    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts --warnings_are_errors -Ohz")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts -Ohz")
 endif(CMAKE_COMPILER_IS_IAR)
 
 if(CMAKE_COMPILER_IS_MSVC)
@@ -240,6 +248,10 @@ if(MBEDTLS_FATAL_WARNINGS)
             set(CMAKE_C_FLAGS_ASANDBG "${CMAKE_C_FLAGS_ASANDBG} -Wno-error=cpp")
         endif(UNSAFE_BUILD)
     endif(CMAKE_COMPILER_IS_CLANG OR CMAKE_COMPILER_IS_GNU)
+
+    if (CMAKE_COMPILER_IS_IAR)
+        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warning_are_errors")
+    endif(CMAKE_COMPILER_IS_IAR)
 endif(MBEDTLS_FATAL_WARNINGS)
 
 if(CMAKE_BUILD_TYPE STREQUAL "Coverage")
@@ -249,8 +261,7 @@ if(CMAKE_BUILD_TYPE STREQUAL "Coverage")
 endif(CMAKE_BUILD_TYPE STREQUAL "Coverage")
 
 if(LIB_INSTALL_DIR)
-else()
+    set(CMAKE_INSTALL_LIBDIR "${LIB_INSTALL_DIR}")
-    set(LIB_INSTALL_DIR lib)
 endif()
 
 add_subdirectory(include)
@@ -344,7 +355,7 @@ if(NOT DISABLE_PACKAGE_CONFIG_AND_INSTALL)
     write_basic_package_version_file(
         "cmake/MbedTLSConfigVersion.cmake"
             COMPATIBILITY SameMajorVersion
-            VERSION 3.1.0)
+            VERSION 3.2.1)
 
     install(
         FILES "${CMAKE_CURRENT_BINARY_DIR}/cmake/MbedTLSConfig.cmake"

CONTRIBUTING.md

@@ -14,13 +14,11 @@ Coding Standards
 
 Making a Contribution
 ---------------------
-1. [Check for open issues](https://github.com/ARMmbed/mbedtls/issues) or [start a discussion](https://lists.trustedfirmware.org/mailman3/lists/mbed-tls.lists.trustedfirmware.org) around a feature idea or a bug.
+1. [Check for open issues](https://github.com/Mbed-TLS/mbedtls/issues) or [start a discussion](https://lists.trustedfirmware.org/mailman3/lists/mbed-tls.lists.trustedfirmware.org) around a feature idea or a bug.
-1. Fork the [Mbed TLS repository on GitHub](https://github.com/ARMmbed/mbedtls) to start making your changes. As a general rule, you should use the ["development" branch](https://github.com/ARMmbed/mbedtls/tree/development) as a basis.
+1. Fork the [Mbed TLS repository on GitHub](https://github.com/Mbed-TLS/mbedtls) to start making your changes. As a general rule, you should use the ["development" branch](https://github.com/Mbed-TLS/mbedtls/tree/development) as a basis.
 1. Write a test which shows that the bug was fixed or that the feature works as expected.
 1. Send a pull request (PR) and work with us until it gets merged and published. Contributions may need some modifications, so a few rounds of review and fixing may be necessary. We will include your name in the ChangeLog :)
 1. For quick merging, the contribution should be short, and concentrated on a single feature or topic. The larger the contribution is, the longer it would take to review it and merge it.
-1. All new files should include the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) standard license header where possible.
-1. Ensure that each commit has at least one `Signed-off-by:` line from the committer. If anyone else contributes to the commit, they should also add their own `Signed-off-by:` line. By adding this line, contributor(s) certify that the contribution is made under the terms of the [Developer Certificate of Origin](dco.txt). The contribution licensing is described in the [License section of the README](README.md#License).
 
 Backwards Compatibility
 -----------------------
@@ -47,15 +45,11 @@ When backporting to these branches please observe the following rules:
 1. All bug fixes that correct a defect that is also present in an LTS branch must be backported to that LTS branch. If a bug fix introduces a change to the API such as a new function, the fix should be reworked to avoid the API change. API changes without very strong justification are unlikely to be accepted.
 1. If a contribution is a new feature or enhancement, no backporting is required. Exceptions to this may be additional test cases or quality improvements such as changes to build or test scripts.
 
-It would be highly appreciated if contributions are backported to LTS branches in addition to the [development branch](https://github.com/ARMmbed/mbedtls/tree/development) by contributors.
+It would be highly appreciated if contributions are backported to LTS branches in addition to the [development branch](https://github.com/Mbed-TLS/mbedtls/tree/development) by contributors.
 
 The list of maintained branches can be found in the [Current Branches section
 of BRANCHES.md](BRANCHES.md#current-branches).
 
-The only currently maintained LTS branch is:
-1. [mbedtls-2.16](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.16)
-
-
 Tests
 -----
 As mentioned, tests that show the correctness of the feature or bug fix should be added to the pull request, if no such tests exist.
@@ -72,7 +66,7 @@ Continuous Integration Tests
 ----------------------------
 Once a PR has been made, the Continuous Integration (CI) tests are triggered and run. You should follow the result of the CI tests, and fix failures.
 
-It is advised to enable the [githooks scripts](https://github.com/ARMmbed/mbedtls/tree/development/tests/git-scripts) prior to pushing your changes, for catching some of the issues as early as possible.
+It is advised to enable the [githooks scripts](https://github.com/Mbed-TLS/mbedtls/tree/development/tests/git-scripts) prior to pushing your changes, for catching some of the issues as early as possible.
 
 Documentation
 -------------
@@ -82,4 +76,13 @@ Mbed TLS is well documented, but if you think documentation is needed, speak out
 1. Complex parts in the code should include comments.
 1. If needed, a Readme file is advised.
 1. If a [Knowledge Base (KB)](https://tls.mbed.org/kb) article should be added, write this as a comment in the PR description.
-1. A [ChangeLog](https://github.com/ARMmbed/mbedtls/blob/development/ChangeLog.d/00README.md) entry should be added for this contribution.
+1. A [ChangeLog](https://github.com/Mbed-TLS/mbedtls/blob/development/ChangeLog.d/00README.md) entry should be added for this contribution.
+
+License and Copyright
+---------------------
+
+All new files should include the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) standard license header where possible. For licensing details, please see the [License section of the README](README.md#License).
+
+The copyright on contributions is retained by the original authors of the code. Where possible for new files, this should be noted in a comment at the top of the file in the form: "Copyright The Mbed TLS Contributors".
+
+When contributing code to us, the committer and all authors are required to make the submission under the terms of the [Developer Certificate of Origin](dco.txt), confirming that the code submitted can (legally) become part of the project, and be subject to the same Apache 2.0 license. This is done by including the standard Git `Signed-off-by:` line in every commit message. If more than one person contributed to the commit, they should also add their own `Signed-off-by:` line.

ChangeLog

@@ -1,4 +1,279 @@
-mbed TLS ChangeLog (Sorted per branch, date)
+Mbed TLS ChangeLog (Sorted per branch, date)
+
+= Mbed TLS 3.2.1 branch released 2022-07-12
+
+Bugfix
+   *  Re-add missing generated file library/ssl_debug_helpers_generated.c
+
+= Mbed TLS 3.2.0 branch released 2022-07-11
+
+Default behavior changes
+   * mbedtls_cipher_set_iv will now fail with ChaCha20 and ChaCha20+Poly1305
+     for IV lengths other than 12. The library was silently overwriting this
+     length with 12, but did not inform the caller about it. Fixes #4301.
+
+Requirement changes
+   * The library will no longer compile out of the box on a platform without
+     setbuf(). If your platform does not have setbuf(), you can configure an
+     alternative function by enabling MBEDTLS_PLATFORM_SETBUF_ALT or
+     MBEDTLS_PLATFORM_SETBUF_MACRO.
+
+New deprecations
+   * Deprecate mbedtls_ssl_conf_max_version() and
+     mbedtls_ssl_conf_min_version() in favor of
+     mbedtls_ssl_conf_max_tls_version() and
+     mbedtls_ssl_conf_min_tls_version().
+   * Deprecate mbedtls_cipher_setup_psa(). Use psa_aead_xxx() or
+     psa_cipher_xxx() directly instead.
+   * Secure element drivers enabled by MBEDTLS_PSA_CRYPTO_SE_C are deprecated.
+     This was intended as an experimental feature, but had not been explicitly
+     documented as such. Use opaque drivers with the interface enabled by
+     MBEDTLS_PSA_CRYPTO_DRIVERS instead.
+   * Deprecate mbedtls_ssl_conf_sig_hashes() in favor of the more generic
+     mbedtls_ssl_conf_sig_algs(). Signature algorithms for the TLS 1.2 and
+     TLS 1.3 handshake should now be configured with
+     mbedtls_ssl_conf_sig_algs().
+
+Features
+   * Add accessor to obtain ciphersuite id from ssl context.
+   * Add accessors to get members from ciphersuite info.
+   * Add mbedtls_ssl_ticket_rotate() for external ticket rotation.
+   * Add accessor to get the raw buffer pointer from a PEM context.
+   * The structures mbedtls_ssl_config and mbedtls_ssl_context now store
+     a piece of user data which is reserved for the application. The user
+     data can be either a pointer or an integer.
+   * Add an accessor function to get the configuration associated with
+     an SSL context.
+   * Add a function to access the protocol version from an SSL context in a
+     form that's easy to compare. Fixes #5407.
+   * Add function mbedtls_md_info_from_ctx() to recall the message digest
+     information that was used to set up a message digest context.
+   * Add ALPN support in TLS 1.3 clients.
+   * Add server certificate selection callback near end of Client Hello.
+     Register callback with mbedtls_ssl_conf_cert_cb().
+   * Provide mechanism to reset handshake cert list by calling
+     mbedtls_ssl_set_hs_own_cert() with NULL value for own_cert param.
+   * Add accessor mbedtls_ssl_get_hs_sni() to retrieve SNI from within
+     cert callback (mbedtls_ssl_conf_cert_cb()) during handshake.
+   * The X.509 module now uses PSA hash acceleration if present.
+   * Add support for psa crypto key derivation for elliptic curve
+     keys. Fixes #3260.
+   * Add function mbedtls_timing_get_final_delay() to access the private
+     final delay field in an mbedtls_timing_delay_context, as requested in
+     #5183.
+    * Add mbedtls_pk_sign_ext() which allows generating RSA-PSS signatures when
+      PSA Crypto is enabled.
+   * Add function mbedtls_ecp_export() to export ECP key pair parameters.
+     Fixes #4838.
+   * Add function mbedtls_ssl_is_handshake_over() to enable querying if the SSL
+     Handshake has completed or not, and thus whether to continue calling
+     mbedtls_ssl_handshake_step(), requested in #4383.
+   * Add the function mbedtls_ssl_get_own_cid() to access our own connection id
+     within mbedtls_ssl_context, as requested in #5184.
+   * Introduce mbedtls_ssl_hs_cb_t typedef for use with
+     mbedtls_ssl_conf_cert_cb() and perhaps future callbacks
+     during TLS handshake.
+   * Add functions mbedtls_ssl_conf_max_tls_version() and
+     mbedtls_ssl_conf_min_tls_version() that use a single value to specify
+     the protocol version.
+    * Extend the existing PSA_ALG_TLS12_PSK_TO_MS() algorithm to support
+      mixed-PSK. Add an optional input PSA_KEY_DERIVATION_INPUT_OTHER_SECRET
+      holding the other secret.
+   * When MBEDTLS_PSA_CRYPTO_CONFIG is enabled, you may list the PSA crypto
+     feature requirements in the file named by the new macro
+     MBEDTLS_PSA_CRYPTO_CONFIG_FILE instead of the default psa/crypto_config.h.
+     Furthermore you may name an additional file to include after the main
+     file with the macro MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE.
+   * Add the function mbedtls_x509_crt_has_ext_type() to access the ext types
+     field within mbedtls_x509_crt context, as requested in #5585.
+   * Add HKDF-Expand and HKDF-Extract as separate algorithms in the PSA API.
+   * Add support for the ARMv8 SHA-2 acceleration instructions when building
+     for Aarch64.
+   * Add support for authentication of TLS 1.3 clients by TLS 1.3 servers.
+   * Add support for server HelloRetryRequest message. The TLS 1.3 client is
+     now capable of negotiating another shared secret if the one sent in its
+     first ClientHello was not suitable to the server.
+   * Add support for client-side TLS version negotiation. If both TLS 1.2 and
+     TLS 1.3 protocols are enabled in the build of Mbed TLS, the TLS client now
+     negotiates TLS 1.3 or TLS 1.2 with TLS servers.
+   * Enable building of Mbed TLS with TLS 1.3 protocol support but without TLS
+     1.2 protocol support.
+   * Mbed TLS provides an implementation of a TLS 1.3 server (ephemeral key
+     establishment only). See docs/architecture/tls13-support.md for a
+     description of the support. The MBEDTLS_SSL_PROTO_TLS1_3 and
+     MBEDTLS_SSL_SRV_C configuration options control this.
+   * Add accessors to configure DN hints for certificate request:
+     mbedtls_ssl_conf_dn_hints() and mbedtls_ssl_set_hs_dn_hints()
+   * The configuration option MBEDTLS_USE_PSA_CRYPTO, which previously
+     affected only a limited subset of crypto operations in TLS, X.509 and PK,
+     now causes most of them to be done using PSA Crypto; see
+     docs/use-psa-crypto.md for the list of exceptions.
+   * The function mbedtls_pk_setup_opaque() now supports RSA key pairs as well.
+     Opaque keys can now be used everywhere a private key is expected in the
+     TLS and X.509 modules.
+   * Opaque pre-shared keys for TLS, provisioned with
+     mbedtls_ssl_conf_psk_opaque() or mbedtls_ssl_set_hs_psk_opaque(), which
+     previously only worked for "pure" PSK key exchange, now can also be used
+     for the "mixed" PSK key exchanges as well: ECDHE-PSK, DHE-PSK, RSA-PSK.
+   * cmake now detects if it is being built as a sub-project, and in that case
+     disables the target export/installation and package configuration.
+   * Make USE_PSA_CRYPTO compatible with KEY_ID_ENCODES_OWNER. Fixes #5259.
+   * Add example programs cipher_aead_demo.c, md_hmac_demo.c, aead_demo.c
+     and hmac_demo.c, which use PSA and the md/cipher interfaces side
+     by side in order to illustrate how the operation is performed in PSA.
+     Addresses #5208.
+
+Security
+   * Zeroize dynamically-allocated buffers used by the PSA Crypto key storage
+     module before freeing them. These buffers contain secret key material, and
+     could thus potentially leak the key through freed heap.
+   * Fix potential memory leak inside mbedtls_ssl_cache_set() with
+     an invalid session id length.
+   * Add the platform function mbedtls_setbuf() to allow buffering to be
+     disabled on stdio files, to stop secrets loaded from said files being
+     potentially left in memory after file operations. Reported by
+     Glenn Strauss.
+   * Fix a potential heap buffer overread in TLS 1.2 server-side when
+     MBEDTLS_USE_PSA_CRYPTO is enabled, an opaque key (created with
+     mbedtls_pk_setup_opaque()) is provisioned, and a static ECDH ciphersuite
+     is selected. This may result in an application crash or potentially an
+     information leak.
+   * Fix a buffer overread in DTLS ClientHello parsing in servers with
+     MBEDTLS_SSL_DTLS_CLIENT_PORT_REUSE enabled. An unauthenticated client
+     or a man-in-the-middle could cause a DTLS server to read up to 255 bytes
+     after the end of the SSL input buffer. The buffer overread only happens
+     when MBEDTLS_SSL_IN_CONTENT_LEN is less than a threshold that depends on
+     the exact configuration: 258 bytes if using mbedtls_ssl_cookie_check(),
+     and possibly up to 571 bytes with a custom cookie check function.
+     Reported by the Cybeats PSI Team.
+    * Fix a buffer overread in TLS 1.3 Certificate parsing. An unauthenticated
+      client or server could cause an MbedTLS server or client to overread up
+      to 64 kBytes of data and potentially overread the input buffer by that
+      amount minus the size of the input buffer. As overread data undergoes
+      various checks, the likelihood of reaching the boundary of the input
+      buffer is rather small but increases as its size
+      MBEDTLS_SSL_IN_CONTENT_LEN decreases.
+   * Fix check of certificate key usage in TLS 1.3. The usage of the public key
+     provided by a client or server certificate for authentication was not
+     checked properly when validating the certificate. This could cause a
+     client or server to be able to authenticate itself through a certificate
+     to an Mbed TLS TLS 1.3 server or client while it does not own a proper
+     certificate to do so.
+
+Bugfix
+   * Declare or use PSA_WANT_ALG_CCM_STAR_NO_TAG following the general
+     pattern for PSA_WANT_xxx symbols. Previously you had to specify
+     PSA_WANT_ALG_CCM for PSA_ALG_CCM_STAR_NO_TAG.
+   * Fix a memory leak if mbedtls_ssl_config_defaults() is called twice.
+   * Fixed swap of client and server random bytes when exporting them alongside
+     TLS 1.3 handshake and application traffic secret.
+   * Fix several bugs (warnings, compiler and linker errors, test failures)
+     in reduced configurations when MBEDTLS_USE_PSA_CRYPTO is enabled.
+   * Fix a bug in (D)TLS curve negotiation: when MBEDTLS_USE_PSA_CRYPTO was
+     enabled and an ECDHE-ECDSA or ECDHE-RSA key exchange was used, the
+     client would fail to check that the curve selected by the server for
+     ECDHE was indeed one that was offered. As a result, the client would
+     accept any curve that it supported, even if that curve was not allowed
+     according to its configuration. Fixes #5291.
+   * The TLS 1.3 implementation is now compatible with the
+     MBEDTLS_USE_PSA_CRYPTO configuration option.
+   * Fix unit tests that used 0 as the file UID. This failed on some
+     implementations of PSA ITS. Fixes #3838.
+   * Fix mbedtls_ssl_get_version() not reporting TLSv1.3. Fixes #5406.
+   * Fix API violation in mbedtls_md_process() test by adding a call to
+     mbedtls_md_starts(). Fixes #2227.
+   * Fix compile errors when MBEDTLS_HAVE_TIME is not defined. Add tests
+     to catch bad uses of time.h.
+   * Fix a race condition in out-of-source builds with CMake when generated data
+     files are already present. Fixes #5374.
+   * Fix the library search path when building a shared library with CMake
+     on Windows.
+   * Fix bug in the alert sending function mbedtls_ssl_send_alert_message()
+     potentially leading to corrupted alert messages being sent in case
+     the function needs to be re-called after initially returning
+     MBEDTLS_SSL_WANT_WRITE. Fixes #1916.
+   * In configurations with MBEDTLS_SSL_DTLS_CONNECTION_ID enabled but not
+     MBEDTLS_DEBUG_C, DTLS handshakes using CID would crash due to a null
+     pointer dereference. Fix this. Fixes #3998.
+     The fix was released, but not announced, in Mbed TLS 3.1.0.
+   * Fix incorrect documentation of mbedtls_x509_crt_profile. The previous
+     documentation stated that the `allowed_pks` field applies to signatures
+     only, but in fact it does apply to the public key type of the end entity
+     certificate, too. Fixes #1992.
+   * Fix undefined behavior in mbedtls_asn1_find_named_data(), where val is
+     not NULL and val_len is zero.
+   * Fix compilation error with mingw32. Fixed by Cameron Cawley in #4211.
+   * Fix compilation error when using C++ Builder on Windows. Reported by
+     Miroslav Mastny in #4015.
+   * psa_raw_key_agreement() now returns PSA_ERROR_BUFFER_TOO_SMALL when
+     applicable. Fixes #5735.
+   * Fix a bug in the x25519 example program where the removal of
+     MBEDTLS_ECDH_LEGACY_CONTEXT caused the program not to run. Fixes #4901 and
+     #3191.
+   * Fix a TLS 1.3 handshake failure when the peer Finished message has not
+     been received yet when we first try to fetch it.
+   * Encode X.509 dates before 1/1/2000 as UTCTime rather than
+     GeneralizedTime. Fixes #5465.
+   * Add mbedtls_x509_dn_get_next function to return the next relative DN in
+     an X509 name, to allow walking the name list. Fixes #5431.
+    * Fix order value of curve x448.
+   * Fix string representation of DNs when outputting values containing commas
+     and other special characters, conforming to RFC 1779. Fixes #769.
+   * Silence a warning from GCC 12 in the selftest program. Fixes #5974.
+   * Fix check_config.h to check that we have MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+     when MBEDTLS_SSL_PROTO_TLS1_3 is specified, and make this and other
+     dependencies explicit in the documentation. Fixes #5610.
+   * Fix mbedtls_asn1_write_mpi() writing an incorrect encoding of 0.
+   * Fix a TLS 1.3 handshake failure when the first attempt to send the client
+     Finished message on the network cannot be satisfied. Fixes #5499.
+   * Fix resource leaks in mbedtls_pk_parse_public_key() in low
+     memory conditions.
+   * Fix server connection identifier setting for outgoing encrypted records
+     on DTLS 1.2 session resumption. After DTLS 1.2 session resumption with
+     connection identifier, the Mbed TLS client now properly sends the server
+     connection identifier in encrypted record headers. Fix #5872.
+   * Fix a null pointer dereference when performing some operations on zero
+     represented with 0 limbs (specifically mbedtls_mpi_mod_int() dividing
+     by 2, and mbedtls_mpi_write_string() in base 2).
+   * Fix record sizes larger than 16384 being sometimes accepted despite being
+     non-compliant. This could not lead to a buffer overflow. In particular,
+     application data size was already checked correctly.
+   * Fix MBEDTLS_SVC_KEY_ID_GET_KEY_ID() and MBEDTLS_SVC_KEY_ID_GET_OWNER_ID()
+     which have been broken, resulting in compilation errors, since Mbed TLS
+     3.0.
+   * Ensure that TLS 1.2 ciphersuite/certificate and key selection takes into
+     account not just the type of the key (RSA vs EC) but also what it can
+     actually do. Resolves #5831.
+   * Fix CMake windows host detection, especially when cross compiling.
+   * Fix an error in make where the absence of a generated file caused
+     make to break on a clean checkout. Fixes #5340.
+   * Work around an MSVC ARM64 compiler bug causing incorrect behaviour
+     in mbedtls_mpi_exp_mod(). Reported by Tautvydas Žilys in #5467.
+   * Removed the prompt to exit from all windows build programs that was causing
+     issues in CI/CD environments.
+
+Changes
+   * The file library/psa_crypto_driver_wrappers.c is now generated
+     from a template. In the future, the generation will support
+     driver descriptions. For the time being, to customize this file,
+     see docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
+   * Return PSA_ERROR_INVALID_ARGUMENT if the algorithm passed to one-shot
+     AEAD functions is not an AEAD algorithm. This aligns them with the
+     multipart functions, and the PSA Crypto API 1.1 specification.
+   * In mbedtls_pk_parse_key(), if no password is provided, don't allocate a
+     temporary variable on the heap. Suggested by Sergey Kanatov in #5304.
+   * Assume source files are in UTF-8 when using MSVC with CMake.
+   * Fix runtime library install location when building with CMake and MinGW.
+     DLLs are now installed in the bin directory instead of lib.
+   * cmake: Use GnuInstallDirs to customize install directories
+     Replace custom LIB_INSTALL_DIR variable with standard CMAKE_INSTALL_LIBDIR
+     variable. For backward compatibility, set CMAKE_INSTALL_LIBDIR if
+     LIB_INSTALL_DIR is set.
+   * Add a CMake option that enables static linking of the runtime library
+     in Microsoft Visual C++ compiler. Contributed by Microplankton.
+   * In CMake builds, add aliases for libraries so that the normal MbedTLS::*
+     targets work when MbedTLS is built as a subdirectory. This allows the
+     use of FetchContent, as requested in #5688.
 
 = mbed TLS 3.1.0 branch released 2021-12-17
 

ChangeLog.d/Driver_wrapper_codegen_1.0.txt

@@ -1,5 +0,0 @@
-Changes
-   * The file library/psa_crypto_driver_wrappers.c is now generated
-     from a template. In the future, the generation will support
-     driver descriptions. For the time being, to customize this file,
-     see docs/proposed/psa-driver-wrappers-codegen-migration-guide.md

ChangeLog.d/MD-X.509-hashing.txt

@@ -1,2 +0,0 @@
-Features
-   * The X.509 module now uses PSA hash acceleration if present.

ChangeLog.d/PSA-test-suites-NOT-using-UID-0.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix unit tests that used 0 as the file UID. This failed on some
-     implementations of PSA ITS. Fixes #3838.

ChangeLog.d/add-mbedtls_md_starts-to-mbedtls_md_process-test.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix API violation in mbedtls_md_process() test by adding a call to
-     mbedtls_md_starts(). Fixes #2227.

ChangeLog.d/add-rsa-pss-rsae-support-for-tls12.txt

@@ -0,0 +1,8 @@
+Features
+   * When GnuTLS/Openssl server is configured in TLS 1.2 mode with a certificate
+     declaring an RSA public key and Mbed TLS is configured in hybrid mode, if
+     `rsa_pss_rsae_*` algorithms are before `rsa_pkcs1_*` ones in this list then
+     the GnuTLS/Openssl server chooses an `rsa_pss_rsae_*` signature algorithm
+     for its signature in the key exchange message. As Mbed TLS 1.2 does not
+     support them, the handshake fails. Add `rsa_pss_rsae_*` support for TLS 1.2
+     to resolve the compitablity issue.

ChangeLog.d/bn_mul-fix-x86-pic-compilation-for-gcc-4.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Fix a long-standing build failure when building x86 PIC code with old
+     gcc (4.x). The code will be slower, but will compile. We do however
+     recommend upgrading to a more recent compiler instead. Fixes #1910.

ChangeLog.d/chacha20_invalid_iv_len_fix.txt

@@ -1,4 +0,0 @@
-Default behavior changes
-   * mbedtls_cipher_set_iv will now fail with ChaCha20 and ChaCha20+Poly1305
-     for IV lengths other than 12. The library was silently overwriting this
-     length with 12, but did not inform the caller about it. Fixes #4301.

ChangeLog.d/cmake_msvc_utf8.txt

@@ -1,2 +0,0 @@
-Changes
-   * Assume source files are in UTF-8 when using MSVC with CMake.

ChangeLog.d/extend-query_compile_time_config-to-psa_want.txt

@@ -0,0 +1,2 @@
+Changes
+   * Add the ability to query PSA_WANT_xxx macros to query_compile_time_config

ChangeLog.d/fix-aes-shallow-copying.txt

@@ -0,0 +1,2 @@
+Bugfix
+   * Refactor mbedtls_aes_context to support shallow-copying. Fixes #2147.

ChangeLog.d/fix-ctr-drbg-may-free-invalid-aes-context.txt

@@ -0,0 +1,4 @@
+Bugfix
+    * Fix mbedtls_ctr_drbg_free() on an initialized but unseeded context. When
+      MBEDTLS_AES_ALT is enabled, it could call mbedtls_aes_free() on an
+      uninitialized context.

ChangeLog.d/fix_build_error_for_mbedtls_deprecated_removed.txt

@@ -0,0 +1,3 @@
+Bugfix
+    * Fix build error due to missing prototype
+      warning when MBEDTLS_DEPRECATED_REMOVED is enabled

ChangeLog.d/fix_cmake_gen_files

@@ -0,0 +1,3 @@
+Bugfix
+   * Fix an issue in releases with GEN_FILES turned off whereby missing
+     generated files could be turned into symlinks to themselves.

ChangeLog.d/fix_cmake_using_iar_toolchain.txt

@@ -0,0 +1,3 @@
+Bugfix
+   * Fixed an issue that cause compile error using CMake IAR toolchain.
+     Fixes #5964.

ChangeLog.d/fix_psa_crypto_cipher_h_include.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Use double quotes to include private header file psa_crypto_cipher.h.
+     Fixes 'file not found with <angled> include' error
+     when building with Xcode.

ChangeLog.d/mbedtls_pem_get_der.txt

@@ -1,2 +0,0 @@
-Features
-   * Add accessor to get the raw buffer pointer from a PEM context.

ChangeLog.d/mbedtls_ssl_cert_cb.txt

@@ -1,7 +0,0 @@
-Features
-   * Add server certificate selection callback near end of Client Hello.
-     Register callback with mbedtls_ssl_conf_cert_cb().
-   * Provide mechanism to reset handshake cert list by calling
-     mbedtls_ssl_set_hs_own_cert() with NULL value for own_cert param.
-   * Add accessor mbedtls_ssl_get_hs_sni() to retrieve SNI from within
-     cert callback (mbedtls_ssl_conf_cert_cb()) during handshake.

ChangeLog.d/mbedtls_ssl_comfig_defaults-memleak.txt

@@ -1,2 +0,0 @@
-Bugfix
-   * Fix memory leak if mbedtls_ssl_config_defaults() call is repeated

ChangeLog.d/mbedtls_ssl_get_ciphersuite_id.txt

@@ -1,3 +0,0 @@
-Features
-   * Add accessor to obtain ciphersuite id from ssl context.
-   * Add accessors to get members from ciphersuite info.

ChangeLog.d/mbedtls_ssl_ticket_rotate.txt

@@ -1,2 +0,0 @@
-Features
-   * Add mbedtls_ssl_ticket_rotate() for external ticket rotation.

ChangeLog.d/mbedtls_ssl_tls13_client.txt

@@ -1,4 +0,0 @@
-Features
-   * Add ALPN support in tls13 client. Client is able to write ALPN extension
-     in client hello, and able to parse the response from server encrypted
-     extension.

ChangeLog.d/md_info_from_ctx.txt

@@ -1,3 +0,0 @@
-Features
-   * Add a function to extract message digest information from a message
-     digest context.

ChangeLog.d/muladdc_microblaze.txt

@@ -0,0 +1,3 @@
+Bugfix
+   * Fix support for little-endian Microblaze when MBEDTLS_HAVE_ASM is defined.
+     Contributed by Kazuyuki Kimura to fix #2020.

ChangeLog.d/nonversioned-library-soname.txt

@@ -0,0 +1,5 @@
+Features
+   * make: enable building unversioned shared library, with e.g.:
+     "SHARED=1 SOEXT_TLS=so SOEXT_X509=so SOEXT_CRYPTO=so make lib"
+     resulting in library names like "libmbedtls.so" rather than
+     "libmbedcrypto.so.11".

ChangeLog.d/pkparse-pkcs8-unencrypted-no-alloc.txt

@@ -1,3 +0,0 @@
-Changes
-   * In mbedtls_pk_parse_key(), if no password is provided, don't allocate a
-     temporary variable on the heap. Suggested by Sergey Kanatov in #5304.

ChangeLog.d/psa_aead_singleshot_error.txt

@@ -1,4 +0,0 @@
-Changes
-   * Return PSA_ERROR_INVALID_ARGUMENT if the algorithm passed to singleshot
-     AEAD functions is not an AEAD algorithm. This aligns them with the
-     multipart functions, and the PSA Crypto API 1.1 spec.

ChangeLog.d/psa_crypto_key_derivation_for_ECC_keys.txt

@@ -1,3 +0,0 @@
-Features
-   * Add support for psa crypto key derivation for elliptic curve
-     keys. Fixes #3260.

ChangeLog.d/psa_crypto_pake.txt

@@ -0,0 +1,4 @@
+Features
+    * Expose the EC J-PAKE functionality through the Draft PSA PAKE Crypto API.
+      Only the ECC primitive with secp256r1 curve and SHA-256 hash algorithm
+      are supported in this implementation.

ChangeLog.d/psa_crypto_reduced_configs.txt

@@ -1,5 +0,0 @@
-Changes
-   * Automatically enable MBEDTLS_PK_WRITE_C if MBEDTLS_PK_C and
-     MBEDTLS_USE_PSA_CRYPTO are enabled. This is due to ecdsa_verify_wrap
-     requirements, but will also probably be needed by RSA soon, hence the
-     broader PK_C requirement.

ChangeLog.d/psa_crypto_reduced_configs_bugs.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix several bugs (warnings, compiler and linker errors, test failures)
-     in reduced configurations when MBEDTLS_USE_PSA_CRYPTO is enabled.

ChangeLog.d/raw-agreement-destroy-missing.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Add missing key slot destruction calls when a raw key agreement or
-     a public key export fails in ssl_write_client_key_exchange.

ChangeLog.d/remove_ssl_session_compression.txt

@@ -0,0 +1,5 @@
+Removals
+   * Remove compression property from SSL session struct.
+     MBEDTLS_SSL_COMPRESS_NULL is now the only supported
+     compression option and can be used for compatibility
+     reasons. Changes requested in #4223.

ChangeLog.d/ssl_context-user_data.txt

@@ -1,6 +0,0 @@
-Features
-   * The structures mbedtls_ssl_config and mbedtls_ssl_context now store
-     a piece of user data which is reserved for the application. The user
-     data can be either a pointer or an integer.
-   * Add an accessor function to get the configuration associated with
-     an SSL context.

ChangeLog.d/ssl_context-version_number.txt

@@ -1,3 +0,0 @@
-Features
-   * Add a function to access the protocol version from an SSL context in a
-     form that's easy to compare. Fixes #5407.

ChangeLog.d/ssl_get_version_1_3.txt

@@ -1,2 +0,0 @@
-Bugfix
-   * Fix mbedtls_ssl_get_version() not reporting TLSv1.3. Fixes #5406.

ChangeLog.d/tls13_and_use_psa_crypto.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * The TLS 1.3 implementation is now compatible with the
-     MBEDTLS_USE_PSA_CRYPTO configuration option.

ChangeLog.d/tls13_f_export_keys.txt

@@ -1,3 +0,0 @@
-Bugfix
-   * Fixed swap of client and server random bytes when exporting them alongside
-     TLS 1.3 handshake and application traffic secret.

ChangeLog.d/use-psa-ecdhe-curve.txt

@@ -1,7 +0,0 @@
-Bugfix
-   * Fix a bug in (D)TLS curve negotiation: when MBEDTLS_USE_PSA_CRYPTO was
-     enabled and an ECDHE-ECDSA or ECDHE-RSA key exchange was used, the
-     client would fail to check that the curve selected by the server for
-     ECDHE was indeed one that was offered. As a result, the client would
-     accept any curve that it supported, even if that curve was not allowed
-     according to its configuration.

ChangeLog.d/x509-broken-symlink-handling.txt

@@ -0,0 +1,5 @@
+Bugfix
+   * Fix handling of broken symlinks when loading certificates using
+     mbedtls_x509_crt_parse_path(). Instead of returning an error as soon as a
+     broken link is encountered, skip the broken link and continue parsing
+     other certificate files. Contributed by Eduardo Silva in #2602.

ChangeLog.d/zeroize_key_buffers_before_free.txt

@@ -1,4 +0,0 @@
-Security
-   * Zeroize dynamically-allocated buffers used by the PSA Crypto key storage
-     module before freeing them. These buffers contain secret key material, and
-     could thus potentially leak the key through freed heap.

README.md

@@ -286,11 +286,9 @@ A browsable copy of the PSA Cryptography API documents is available on the [PSA
 ### PSA implementation in Mbed TLS
 
 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.
+However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms.
 
-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`.
+The X.509 and TLS code can use PSA cryptography for most operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `mbedtls_config.h`. Note that TLS 1.3 uses PSA cryptography for most operations regardless of this option. See `docs/use-psa-crypto.md` for details.
-
-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.
 
 ### Upcoming features
 
@@ -315,5 +313,5 @@ Contact
 -------
 
 * To report a security vulnerability in Mbed TLS, please email <mbed-tls-security@lists.trustedfirmware.org>. For more information, see [`SECURITY.md`](SECURITY.md).
-* To report a bug or request a feature in Mbed TLS, please [file an issue on GitHub](https://github.com/ARMmbed/mbedtls/issues/new/choose).
+* To report a bug or request a feature in Mbed TLS, please [file an issue on GitHub](https://github.com/Mbed-TLS/mbedtls/issues/new/choose).
 * Please see [`SUPPORT.md`](SUPPORT.md) for other channels for discussion and support about Mbed TLS.

SECURITY.md

@@ -1,4 +1,4 @@
-## Reporting Vulneratibilities
+## Reporting Vulnerabilities
 
 If you think you have found an Mbed TLS security vulnerability, then please
 send an email to the security team at
@@ -6,7 +6,7 @@ send an email to the security team at
 
 ## Security Incident Handling Process
 
-Our security process is detailled in our
+Our security process is detailed in our
 [security
 center](https://developer.trustedfirmware.org/w/mbed-tls/security-center/).
 

configs/config-ccm-psk-dtls1_2.h

@@ -0,0 +1,108 @@
+/**
+ * \file config-ccm-psk-dtls1_2.h
+ *
+ * \brief Small configuration for DTLS 1.2 with PSK and AES-CCM ciphersuites
+ */
+/*
+ *  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.
+ */
+/*
+ * Minimal configuration for DTLS 1.2 with PSK and AES-CCM ciphersuites
+ *
+ * Distinguishing features:
+ * - Optimized for small code size, low bandwidth (on an unreliable transport),
+ *   and low RAM usage.
+ * - No asymmetric cryptography (no certificates, no Diffie-Hellman key
+ *   exchange).
+ * - Fully modern and secure (provided the pre-shared keys are generated and
+ *   stored securely).
+ * - Very low record overhead with CCM-8.
+ * - Includes several optional DTLS features typically used in IoT.
+ *
+ * See README.txt for usage instructions.
+ */
+
+/* System support */
+//#define MBEDTLS_HAVE_TIME /* Optionally used in Hello messages */
+/* Other MBEDTLS_HAVE_XXX flags irrelevant for this configuration */
+
+/* Mbed TLS modules */
+#define MBEDTLS_AES_C
+#define MBEDTLS_CCM_C
+#define MBEDTLS_CIPHER_C
+#define MBEDTLS_CTR_DRBG_C
+#define MBEDTLS_ENTROPY_C
+#define MBEDTLS_MD_C
+#define MBEDTLS_NET_C
+/* The library does not currently support enabling SHA-224 without SHA-256.
+ * A future version of the library will have this option disabled
+ * by default. */
+#define MBEDTLS_SHA224_C
+#define MBEDTLS_SHA256_C
+#define MBEDTLS_SSL_CLI_C
+#define MBEDTLS_SSL_COOKIE_C
+#define MBEDTLS_SSL_SRV_C
+#define MBEDTLS_SSL_TLS_C
+#define MBEDTLS_TIMING_C
+
+/* TLS protocol feature support */
+#define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
+#define MBEDTLS_SSL_PROTO_TLS1_2
+#define MBEDTLS_SSL_PROTO_DTLS
+#define MBEDTLS_SSL_DTLS_ANTI_REPLAY
+#define MBEDTLS_SSL_DTLS_CLIENT_PORT_REUSE
+#define MBEDTLS_SSL_DTLS_CONNECTION_ID
+#define MBEDTLS_SSL_DTLS_HELLO_VERIFY
+#define MBEDTLS_SSL_MAX_FRAGMENT_LENGTH
+
+/*
+ * Use only CCM_8 ciphersuites, and
+ * save ROM and a few bytes of RAM by specifying our own ciphersuite list
+ */
+#define MBEDTLS_SSL_CIPHERSUITES                        \
+        MBEDTLS_TLS_PSK_WITH_AES_256_CCM_8,             \
+        MBEDTLS_TLS_PSK_WITH_AES_128_CCM_8
+
+/*
+ * Save RAM at the expense of interoperability: do this only if you control
+ * both ends of the connection!  (See comments in "mbedtls/ssl.h".)
+ * The optimal size here depends on the typical size of records.
+ */
+#define MBEDTLS_SSL_IN_CONTENT_LEN              256
+#define MBEDTLS_SSL_OUT_CONTENT_LEN             256
+
+/* Save RAM at the expense of ROM */
+#define MBEDTLS_AES_ROM_TABLES
+
+/* Save some RAM by adjusting to your exact needs */
+#define MBEDTLS_PSK_MAX_LEN    16 /* 128-bits keys are generally enough */
+
+/*
+ * You should adjust this to the exact number of sources you're using: default
+ * is the "platform_entropy_poll" source, but you may want to add other ones
+ * Minimum is 2 for the entropy test suite.
+ */
+#define MBEDTLS_ENTROPY_MAX_SOURCES 2
+
+/* These defines are present so that the config modifying scripts can enable
+ * them during tests/scripts/test-ref-configs.pl */
+//#define MBEDTLS_USE_PSA_CRYPTO
+//#define MBEDTLS_PSA_CRYPTO_C
+
+/* Error messages and TLS debugging traces
+ * (huge code size increase, needed for tests/ssl-opt.sh) */
+//#define MBEDTLS_DEBUG_C
+//#define MBEDTLS_ERROR_C

configs/config-ccm-psk-tls1_2.h

@@ -21,11 +21,15 @@
  */
 /*
  * Minimal configuration for TLS 1.2 with PSK and AES-CCM ciphersuites
+ *
  * Distinguishing features:
- * - no bignum, no PK, no X509
+ * - Optimized for small code size, low bandwidth (on a reliable transport),
- * - fully modern and secure (provided the pre-shared keys have high entropy)
+ *   and low RAM usage.
- * - very low record overhead with CCM-8
+ * - No asymmetric cryptography (no certificates, no Diffie-Hellman key
- * - optimized for low RAM usage
+ *   exchange).
+ * - Fully modern and secure (provided the pre-shared keys are generated and
+ *   stored securely).
+ * - Very low record overhead with CCM-8.
  *
  * See README.txt for usage instructions.
  */
@@ -34,11 +38,7 @@
 //#define MBEDTLS_HAVE_TIME /* Optionally used in Hello messages */
 /* Other MBEDTLS_HAVE_XXX flags irrelevant for this configuration */
 
-/* mbed TLS feature support */
+/* Mbed TLS modules */
-#define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
-#define MBEDTLS_SSL_PROTO_TLS1_2
-
-/* mbed TLS modules */
 #define MBEDTLS_AES_C
 #define MBEDTLS_CCM_C
 #define MBEDTLS_CIPHER_C
@@ -55,18 +55,9 @@
 #define MBEDTLS_SSL_SRV_C
 #define MBEDTLS_SSL_TLS_C
 
-/* Save RAM at the expense of ROM */
+/* TLS protocol feature support */
-#define MBEDTLS_AES_ROM_TABLES
+#define MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
-
+#define MBEDTLS_SSL_PROTO_TLS1_2
-/* Save some RAM by adjusting to your exact needs */
-#define MBEDTLS_PSK_MAX_LEN    16 /* 128-bits keys are generally enough */
-
-/*
- * You should adjust this to the exact number of sources you're using: default
- * is the "platform_entropy_poll" source, but you may want to add other ones
- * Minimum is 2 for the entropy test suite.
- */
-#define MBEDTLS_ENTROPY_MAX_SOURCES 2
 
 /*
  * Use only CCM_8 ciphersuites, and
@@ -81,10 +72,28 @@
  * both ends of the connection!  (See comments in "mbedtls/ssl.h".)
  * The optimal size here depends on the typical size of records.
  */
-#define MBEDTLS_SSL_IN_CONTENT_LEN             1024
+#define MBEDTLS_SSL_IN_CONTENT_LEN              1024
 #define MBEDTLS_SSL_OUT_CONTENT_LEN             1024
 
+/* Save RAM at the expense of ROM */
+#define MBEDTLS_AES_ROM_TABLES
+
+/* Save some RAM by adjusting to your exact needs */
+#define MBEDTLS_PSK_MAX_LEN    16 /* 128-bits keys are generally enough */
+
+/*
+ * You should adjust this to the exact number of sources you're using: default
+ * is the "platform_entropy_poll" source, but you may want to add other ones
+ * Minimum is 2 for the entropy test suite.
+ */
+#define MBEDTLS_ENTROPY_MAX_SOURCES 2
+
 /* These defines are present so that the config modifying scripts can enable
  * them during tests/scripts/test-ref-configs.pl */
 //#define MBEDTLS_USE_PSA_CRYPTO
 //#define MBEDTLS_PSA_CRYPTO_C
+
+/* Error messages and TLS debugging traces
+ * (huge code size increase, needed for tests/ssl-opt.sh) */
+//#define MBEDTLS_DEBUG_C
+//#define MBEDTLS_ERROR_C

configs/config-no-entropy.h

@@ -21,7 +21,7 @@
  */
 /*
  * Minimal configuration of features that do not require an entropy source
- * Distinguishing reatures:
+ * Distinguishing features:
  * - no entropy module
  * - no TLS protocol implementation available due to absence of an entropy
  *   source

configs/config-suite-b.h

@@ -104,7 +104,7 @@
 
 /*
  * Save RAM at the expense of interoperability: do this only if you control
- * both ends of the connection!  (See coments in "mbedtls/ssl.h".)
+ * both ends of the connection!  (See comments in "mbedtls/ssl.h".)
  * The minimum size here depends on the certificate chain used as well as the
  * typical size of records.
  */
@@ -115,3 +115,8 @@
  * them during tests/scripts/test-ref-configs.pl */
 //#define MBEDTLS_USE_PSA_CRYPTO
 //#define MBEDTLS_PSA_CRYPTO_C
+
+/* Error messages and TLS debugging traces
+ * (huge code size increase, needed for tests/ssl-opt.sh) */
+//#define MBEDTLS_DEBUG_C
+//#define MBEDTLS_ERROR_C

docs/3.0-migration-guide.md

@@ -2,7 +2,7 @@
 
 This guide details the steps required to migrate from Mbed TLS version 2.x to
 Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
-compatibility with previous versions, so users (and alt implementors) might
+compatibility with previous versions, so users (and alt implementers) might
 need to change their own code in order to make it work with Mbed TLS 3.0.
 
 Here's the list of breaking changes; each entry should help you answer these
@@ -13,7 +13,28 @@ The changes are detailed below, and include:
 - Removal of many insecure or obsolete features
 - Tidying up of configuration options (including removing some less useful options).
 - Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const.
-- Removal of functions previously marked as deprecated.
+- Removal of functions, macros, and types previously marked as deprecated.
+
+Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation.
+
+
+## Accessing the Mbed TLS 2.x documentation
+
+For features previously marked as deprecated, Mbed TLS 2.x documentation may
+explain how to upgrade, and should be referred to when migrating code. Where a
+migration path is not provided in prior documentation, changes made and the
+upgrade steps required will be explained later in this guide.
+
+It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release.
+So to generate the documentation, checkout the `mbedtls-2.28` branch and follow
+the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation).
+Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code.
+
+For some deprecated functions, 2.x documentation will suggest using a variant
+suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most
+of these variants have been renamed without the suffix. The section
+[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed)
+has further detail on which functions this applies to.
 
 
 ## General changes
@@ -48,7 +69,7 @@ Attempting to access a private field directly will result in a compilation error
 
 If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls_<MODULE>_{get,set}_<FIELD>` or `mbedtls_<MODULE>_<STRUCTURE>_{get,set}_<FIELD>`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string.
 
-If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.).
+If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.).
 
 As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS.
 
@@ -157,7 +178,7 @@ The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_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
+removed from the library. Please use parameters from RFC 3526 (still in the
 library, only in binary form) or RFC 7919 (also available in the library) or
 other trusted sources instead.
 
@@ -248,22 +269,29 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f
 
 ### Deprecated error codes for hardware failures were removed
 
-- The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules
+- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules
   were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
   instead.
+- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed;
+  `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead.
 - The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
   were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
 
+### Deprecated error codes for invalid input data were removed
+
+- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia
+  modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead.
+
 ### Remove the mode parameter from RSA functions
 
-This affects all users who use the RSA encryption, decryption, sign and
+This affects all users who use the RSA encrypt, decrypt, 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
+the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_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.
 
@@ -334,7 +362,7 @@ the RSA verify functions.
 
 ### Remove the padding parameters from `mbedtls_rsa_init()`
 
-This affects all users who use the RSA encryption, decryption, sign and
+This affects all users who use the RSA encrypt, decrypt, sign and
 verify APIs.
 
 The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1
@@ -552,13 +580,13 @@ extension if it contains any unsupported certificate policies.
 ### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h`
 
 This change affects users who have chosen the configuration options to disable the
-library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509
+library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
 certificates.
 
 The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE`
-configuration options are removed and the X509 code now behaves as if they were
+configuration options are removed and the X.509 code now behaves as if they were
 always enabled. It is consequently not possible anymore to disable at compile
-time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509
+time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
 certificates.
 
 The verification of the `keyUsage` and `extendedKeyUsage` fields is important,
@@ -772,7 +800,7 @@ than just the MFL configuration into account.
 ### Relaxed semantics for PSK configuration
 
 This affects users which call the PSK configuration APIs
-`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
+`mbedtls_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

docs/architecture/mbed-crypto-storage-specification.md

@@ -112,7 +112,7 @@ Information about each key is stored in a dedicated file designated by the key i
 The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-1.0.0).
 
 * Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value.
-* PSA service integration: the key file name is `(uint32_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
+* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
 
 ### Key file format for 1.0.0
 
@@ -120,7 +120,11 @@ The layout is identical to [0.1.0](#key-file-format-for-0.1.0) so far. However n
 
 ### Nonvolatile random seed file format for 1.0.0
 
-[Identical to 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
+The nonvolatile random seed file contains a seed for the random generator. If present, it is rewritten at each boot as part of the random generator initialization.
+
+The file format is just the seed as a byte string with no metadata or encoding of any kind.
+
+This is unchanged since [the feature was introduced in Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
 
 ### File namespace on a PSA platform for 1.0.0
 
@@ -167,7 +171,21 @@ Tags: mbedcrypto-1.1.0
 Released in early June 2019. <br>
 Integrated in Mbed OS 5.13.
 
-Identical to [1.0.0](#mbed-crypto-1.0.0) except for some changes in the key file format.
+Changes since [1.0.0](#mbed-crypto-1.0.0):
+
+* The stdio backend for storage has been replaced by an implementation of [PSA ITS over stdio](#file-namespace-on-stdio-for-1.1.0).
+* [Some changes in the key file format](#key-file-format-for-1.1.0).
+
+### File namespace on stdio for 1.1.0
+
+Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
+
+An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
+
+* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
+* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a non-key file (currently: only the [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0)). The contents of the file are:
+    * Magic header (8 bytes): `"PSA\0ITS\0"`
+    * File contents.
 
 ### Key file format for 1.1.0
 
@@ -314,3 +332,134 @@ The layout of a key file is:
     * For an opaque key (unified driver interface): driver-specific opaque key blob.
     * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness.
 * Any trailing data is rejected on load.
+
+Mbed TLS 2.25.0
+---------------
+
+Tags: `mbedtls-2.25.0`, `mbedtls-2.26.0`, `mbedtls-2.27.0`, `mbedtls-2.28.0`, `mbedtls-3.0.0`, `mbedtls-3.1.0`
+
+First released in December 2020.
+
+Note: this is the first version that is officially supported. The version number is still 0.
+
+Backward compatibility commitments: we promise backward compatibility for stored keys when Mbed TLS is upgraded from x to y if x >= 2.25 and y < 4. See [`BRANCHES.md`](../../BRANCHES.md) for more details.
+
+Supported integrations:
+
+* [PSA platform](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)
+* [library using PSA ITS](#file-namespace-on-its-as-a-library-on-mbed-tls-2.25.0)
+* [library using C stdio](#file-namespace-on-stdio-for-mbed-tls-2.25.0)
+
+Supported features:
+
+* [Persistent keys](#key-file-format-for-mbed-tls-2.25.0) designated by a [key identifier and owner](#key-names-for-mbed-tls-2.25.0). Keys can be:
+    * Transparent, stored in the export format.
+    * Opaque, using the unified driver interface with statically registered drivers (`MBEDTLS_PSA_CRYPTO_DRIVERS`). The driver determines the content of the opaque key blob.
+    * Opaque, using the deprecated secure element interface with dynamically registered drivers (`MBEDTLS_PSA_CRYPTO_SE_C`). The driver picks a slot number which is stored in the place of the key material.
+* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0) on ITS only.
+
+### Changes introduced in Mbed TLS 2.25.0
+
+* The numerical encodings of `psa_key_type_t`, `psa_key_usage_t` and `psa_algorithm_t` have changed.
+
+### File namespace on a PSA platform on Mbed TLS 2.25.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+Assumption: the owner identifier is a nonzero value of type `int32_t`.
+
+* Files 0 through 0xfffeffff: unused.
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
+* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0). The upper 32 bits determine the owner.
+
+### File namespace on ITS as a library on Mbed TLS 2.25.0
+
+Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0).
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0).
+* Files 0x100000000 through 0xffffffffffffffff: unused.
+
+### File namespace on stdio for Mbed TLS 2.25.0
+
+Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
+
+An undocumented build-time configuration value `PSA_ITS_STORAGE_PREFIX` allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
+
+* `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present.
+* `sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)`: a key or non-key file. The `key_id` in the name is the 64-bit file identifier, which is the [key identifier](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a [non-key file](#non-key-files-on-mbed-tls-2.25.0). The contents of the file are:
+    * Magic header (8 bytes): `"PSA\0ITS\0"`
+    * File contents.
+
+### Key names for Mbed TLS 2.25.0
+
+Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (`psa_key_id_t`). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (`psa_key_id_t`) from the key owner point of view.
+
+The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-mbed-tls-2.25.0).
+
+* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value which must be in the range 0x00000001..0x3fffffff (`PSA_KEY_ID_USER_MIN`..`PSA_KEY_ID_USER_MAX`).
+* PSA service integration: the key file name is `(uint64_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
+
+### Key file format for Mbed TLS 2.25.0
+
+All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`.
+* version (4 bytes): 0.
+* lifetime (4 bytes): `psa_key_lifetime_t` value.
+* type (2 bytes): `psa_key_type_t` value.
+* bits (2 bytes): `psa_key_bits_t` value.
+* policy usage flags (4 bytes): `psa_key_usage_t` value.
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
+* key material length (4 bytes).
+* key material:
+    * For a transparent key: output of `psa_export_key`.
+    * For an opaque key (unified driver interface): driver-specific opaque key blob.
+    * For an opaque key (key in a dynamic secure element): slot number (8 bytes), in platform endianness.
+* Any trailing data is rejected on load.
+
+### Non-key files on Mbed TLS 2.25.0
+
+File identifiers that are outside the range of persistent key identifiers are reserved for internal use by the library. The only identifiers currently in use have the owner id (top 32 bits) set to 0.
+
+* Files 0xfffffe02 through 0xfffffeff (`PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime`): dynamic secure element driver storage. The content of the file is the secure element driver's persistent data.
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0).
+* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-mbed-tls-2.25.0).
+* Other files are unused and reserved for future use.
+
+### Nonvolatile random seed file format for Mbed TLS 2.25.0
+
+[Identical to Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0).
+
+### Transaction file format for Mbed TLS 2.25.0
+
+The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
+
+All integers are encoded in platform endianness.
+
+All currently existing transactions concern a key in a dynamic secure element.
+
+The layout of a transaction file is:
+
+* type (2 bytes): the [transaction type](#transaction-types-on-mbed-tls-2.25.0).
+* unused (2 bytes)
+* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element.
+* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver.
+* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0)).
+
+#### Transaction types on Mbed TLS 2.25.0
+
+* 0x0001: key creation. The following locations may or may not contain data about the key that is being created:
+    * The slot in the secure element designated by the slot number.
+    * The file containing the key metadata designated by the key identifier.
+    * The driver persistent data.
+* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed:
+    * The slot in the secure element designated by the slot number.
+    * The file containing the key metadata designated by the key identifier.
+    * The driver persistent data.

docs/architecture/psa-crypto-implementation-structure.md

@@ -1,4 +1,4 @@
-PSA Cryptograpy API implementation and PSA driver interface
+PSA Cryptography API implementation and PSA driver interface
 ===========================================================
 
 ## Introduction

docs/architecture/psa-migration/outcome-analysis.sh

@@ -0,0 +1,116 @@
+#!/bin/sh
+
+# This script runs tests in various revisions and configurations and analyses
+# the results in order to highlight any difference in the set of tests skipped
+# in the test suites of interest.
+#
+# It can be used to ensure the testing criteria mentioned in strategy.md,
+# end of section "Supporting builds with drivers without the software
+# implementation" are met, namely:
+#
+# - the sets of tests skipped in the default config and the full config must be
+#   the same before and after the PR that implements step 3;
+# - the set of tests skipped in the driver-only build is the same as in an
+#   equivalent software-based configuration, or the difference is small enough,
+#   justified, and a github issue is created to track it.
+#
+# WARNING: this script checks out a commit other than the head of the current
+# branch; it checks out the current branch again when running successfully,
+# but while the script is running, or if it terminates early in error, you
+# should be aware that you might be at a different commit than expected.
+#
+# NOTE: This is only an example/template script, you should make a copy and
+# edit it to suit your needs. The part that needs editing is at the top.
+#
+# Also, you can comment out parts that don't need to be re-done when
+# re-running this script (for example "get numbers before this PR").
+
+# ----- BEGIN edit this -----
+# The component in all.sh that builds and tests with drivers.
+DRIVER_COMPONENT=test_psa_crypto_config_accel_hash_use_psa
+# A similar configuration to that of the component, except without drivers,
+# for comparison.
+reference_config () {
+    scripts/config.py set MBEDTLS_USE_PSA_CRYPTO
+    scripts/config.py unset MBEDTLS_PKCS1_V21
+    scripts/config.py unset MBEDTLS_X509_RSASSA_PSS_SUPPORT
+    scripts/config.py unset MBEDTLS_ECDSA_DETERMINISTIC
+}
+# Space-separated list of test suites of interest.
+SUITES="rsa pkcs1_v15 pk pkparse pkwrite"
+# ----- END edit this -----
+
+set -eu
+
+cleanup() {
+    make clean
+    git checkout -- include/mbedtls/mbedtls_config.h include/psa/crypto_config.h
+}
+
+record() {
+    export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-$1.csv"
+    rm -f $MBEDTLS_TEST_OUTCOME_FILE
+    make check
+}
+
+# save current HEAD
+HEAD=$(git branch --show-current)
+
+# get the numbers before this PR for default and full
+cleanup
+git checkout $(git merge-base HEAD development)
+record "before-default"
+
+cleanup
+scripts/config.py full
+record "before-full"
+
+# get the numbers now for default and full
+cleanup
+git checkout $HEAD
+record "after-default"
+
+cleanup
+scripts/config.py full
+record "after-full"
+
+# get the numbers now for driver-only and reference
+cleanup
+reference_config
+record "reference"
+
+cleanup
+export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-drivers.csv"
+tests/scripts/all.sh -k test_psa_crypto_config_accel_hash_use_psa
+
+# analysis
+
+compare_suite () {
+    ref="outcome-$1.csv"
+    new="outcome-$2.csv"
+    suite="$3"
+
+    pattern_suite=";test_suite_$suite;"
+    total=$(grep -c "$pattern_suite" "$ref")
+    sed_cmd="s/^.*$pattern_suite\(.*\);SKIP.*/\1/p"
+    sed -n "$sed_cmd" "$ref" > skipped-ref
+    sed -n "$sed_cmd" "$new" > skipped-new
+    nb_ref=$(wc -l <skipped-ref)
+    nb_new=$(wc -l <skipped-new)
+
+    printf "%12s: total %3d; skipped %3d -> %3d\n" \
+            $suite      $total       $nb_ref $nb_new
+    diff skipped-ref skipped-new | grep '^> ' || true
+    rm skipped-ref skipped-new
+}
+
+compare_builds () {
+    printf "\n*** Comparing $1 -> $2 ***\n"
+    for suite in $SUITES; do
+        compare_suite "$1" "$2" "$suite"
+    done
+}
+
+compare_builds before-default after-default
+compare_builds before-full after-full
+compare_builds reference drivers

docs/architecture/psa-migration/psa-limitations.md

@@ -14,8 +14,8 @@ Limitations relevant for G1 (performing crypto operations)
 Restartable ECC operations
 --------------------------
 
-There is currently no support for that in PSA at all. API design, as well as
+There is currently no support for that in PSA at all, but it will be added at
-implementation, would be non-trivial.
+some point, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18816849>.
 
 Currently, `MBEDTLS_USE_PSA_CRYPTO` is simply incompatible with
 `MBEDTLS_ECP_RESTARTABLE`.
@@ -27,12 +27,12 @@ PSA Crypto has an API for FFDH, but it's not implemented in Mbed TLS yet.
 (Regarding FFDH, see the next section as well.) See issue [3261][ffdh] on
 github.
 
-[ffdh]: https://github.com/ARMmbed/mbedtls/issues/3261
+[ffdh]: https://github.com/Mbed-TLS/mbedtls/issues/3261
 
 PSA Crypto has an experimental API for EC J-PAKE, but it's not implemented in
 Mbed TLS yet. See the [EC J-PAKE follow-up EPIC][ecjp] on github.
 
-[ecjp]: https://github.com/orgs/ARMmbed/projects/18#column-15836385
+[ecjp]: https://github.com/orgs/Mbed-TLS/projects/1#column-17950140
 
 Arbitrary parameters for FFDH
 -----------------------------
@@ -60,16 +60,25 @@ There are several options here:
 
 1. Implement support for custom FFDH parameters in PSA Crypto: this would pose
    non-trivial API design problem, but most importantly seems backwards, as
-the crypto community is moving away from custom FFDH parameters.
+the crypto community is moving away from custom FFDH parameters. (Could be
+done any time.)
 2. Drop the DHE-RSA and DHE-PSK key exchanges in TLS 1.2 when moving to PSA.
-3. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it
+   (For people who want some algorithmic variety in case ECC collapses, FFDH
-   when moving to PSA. We can modify our server so that it only selects a DHE
+would still be available in TLS 1.3, just not in 1.2.) (Can only be done in
-   ciphersuite if the client offered name FFDH groups; unfortunately
+4.0 or another major version.)
+3. Variant of the precedent: only drop client-side support. Server-side is
+   easy to support in terms of API/protocol, as the server picks the
+parameters: we just need remove the existing `mbedtls_ssl_conf_dh_param_xxx()`
+APIs and tell people to use `mbedtls_ssl_conf_groups()` instead. (Can only be
+done in 4.0 or another major version.)
+4. Implement RFC 7919, support DHE-RSA and DHE-PSK only in conjunction with it
+   when moving to PSA. Server-side would work as above; unfortunately
 client-side the only option is to offer named groups and break the handshake
 if the server didn't take on our offer. This is not fully satisfying, but is
 perhaps the least unsatisfying option in terms of result; it's also probably
 the one that requires the most work, but it would deliver value beyond PSA
-migration by implementing RFC 7919.
+migration by implementing RFC 7919. (Implementing RFC 7919 could be done any
+time; making it mandatory can only be done in 4.0 or another major version.)
 
 RSA-PSS parameters
 ------------------
@@ -84,7 +93,7 @@ the hash algorithm potentially used to hash the message being signed:
   - most commonly MGF1, which in turn is parametrized by a hash algorithm
 - a salt length
 - a trailer field - the value is fixed to 0xBC by PKCS#1 v2.1, but was left
-  configurable in the original scheme; 0xBC is used everywhere in pratice.
+  configurable in the original scheme; 0xBC is used everywhere in practice.
 
 Both the existing `mbedtls_` API and the PSA API support only MGF1 as the
 generation function (and only 0xBC as the trailer field), but there are
@@ -162,7 +171,7 @@ match a limitation of the PSA API.
 
 It is unclear what parameters people use in practice. It looks like by default
 OpenSSL picks saltlen = keylen - hashlen - 2 (tested with openssl 1.1.1f).
-The `certool` command provided by GnuTLS seems to be picking saltlen = hashlen
+The `certtool` command provided by GnuTLS seems to be picking saltlen = hashlen
 by default (tested with GnuTLS 3.6.13). FIPS 186-4 requires 0 <= saltlen <=
 hashlen.
 
@@ -294,7 +303,7 @@ server9.req.sha512
          Mask Algorithm: mgf1 with sha512
           Salt Length: 0x3E
 
-These CSRss are signed with a 2048-bit key. It appears that they are
+These CSRs are signed with a 2048-bit key. It appears that they are
 all using saltlen = keylen - hashlen - 2.
 
 ### Possible courses of action
@@ -308,87 +317,13 @@ is about X.509 signature verification. Options include:
    saltlen happens to match hashlen, and falling back to `ANY_SALT` otherwise.
 Same issue as with the previous point, except more contained.
 3. Reject all certificates with saltlen != hashlen. This includes all
-   certificates generate with OpenSSL using the default parameters, so it's
+   certificates generated with OpenSSL using the default parameters, so it's
 probably not acceptable.
 4. Request an extension to the PSA Crypto API and use one of the above options
    in the meantime. Such an extension seems inconvenient and not motivated by
 strong security arguments, so it's unclear whether it would be accepted.
 
-HKDF: Expand not exposed on its own (TLS 1.3)
----------------------------------------------
-
-The HKDF function uses and Extract-then-Expand approch, that is:
-
-        HKDF(x, ...) = HKDF-Expand(HKDF-Extract(x, ...), ...)
-
-Only the full HKDF function is safe in general, however there are cases when
-one case safely use the individual Extract and Expand; the TLS 1.3 key
-schedule does so. Specifically, looking at the [hierarchy of secrets][13hs]
-is seems that Expand and Extract are always chained, so that this hierarchy
-can be implemented using only the full HKDF. However, looking at the
-derivation of traffic keys (7.3) and the update mechanism (7.2) it appears
-that calls to HKDF-Expand are iterated without any intermediated call to
-HKDF-Extract : that is, the traffic keys are computed as
-
-        HKDF-Expand(HKDF-Expand(HKDF-Extract(...)))
-
-(with possibly more than two Expands in a row with update).
-
-[13hs]: https://datatracker.ietf.org/doc/html/rfc8446#page-93
-
-In the short term (early 2022), we'll work around that by re-implementing HKDF
-in `ssl_tls13_keys.c` based on the `psa_mac_` APIs (for HMAC).
-
-In the long term, it is desirable to extend the PSA API. See
-https://github.com/ARM-software/psa-crypto-api/issues/539
-
 Limitations relevant for G2 (isolation of long-term secrets)
 ============================================================
 
-Custom key derivations for mixed-PSK handshake
+Currently none.
-----------------------------------------------
-
-Currently, `MBEDTLS_USE_PSA_CRYPTO` enables the new configuration function
-`mbedtls_ssl_conf_psk_opaque()` which allows a PSA-held key to be used for the
-(pure) `PSK` key exchange in TLS 1.2. This requires that the derivation of the
-Master Secret (MS) be done on the PSA side. To support this, an algorithm
-family `PSA_ALG_TLS12_PSK_TO_MS(hash_alg)` was added to PSA Crypto.
-
-If we want to support key isolation for the "mixed PSK" key exchanges:
-DHE-PSK, RSA-PSK, ECDHE-PSK, where the PSK is concatenated with the result of
-a DH key agreement (resp. RSA decryption) to form the pre-master secret (PMS)
-from which the MS is derived. If the value of the PSK is to remain hidden, we
-need the derivation PSK + secondary secret -> MS to be implemented as an
-ad-hoc PSA key derivation algorithm.
-
-Adding this new, TLS-specific, key derivation algorithm to PSA Crypto should
-be no harder than it was to add `PSA_ALG_TLS12_PSK_TO_MS()` but still requires
-an extension to PSA Crypto.
-
-Note: looking at RFCs 4279 and 5489, it appears that the structure of the PMS
-is always the same: 2-byte length of the secondary secret, secondary secret,
-2-byte length of the PSK, PSK. So, a single key derivation algorithm should be
-able to cover the 3 key exchanges DHE-PSK, RSA-PSK and ECDHE-PSK. (That's a
-minor gain: adding 3 algorithms would not be a blocker anyway.)
-
-Note: if later we want to also isolate short-term secret (G3), the "secondary
-secret" (output of DHE/ECDHE key agreement or RSA decryption) could be a
-candidate. This wouldn't be a problem as the PSA key derivation API always
-allows inputs from key slots. (Tangent: the hard part in isolating the result
-of RSA decryption would be still checking that is has the correct format:
-48 bytes, the first two matching the TLS version - note that this is timing
-sensitive.)
-
-HKDF: Expand not exposed on its own (TLS 1.3)
----------------------------------------------
-
-See the section with the same name in the G1 part above for background.
-
-The work-around mentioned there works well enough just for acceleration, but
-is not sufficient for key isolation or generally proper key management (it
-requires marking keys are usable for HMAC while they should only be used for
-key derivation).
-
-The obvious long-term solution is to make HKDF-Expand available as a new KDF
-(in addition to the full HKDF) in PSA (with appropriate warnings in the
-documentation).

docs/architecture/psa-migration/strategy.md

@@ -12,19 +12,14 @@ G3. Allow isolation of short-term secrets (for example, TLS session keys).
 G4. Have a clean, unified API for Crypto (retire the legacy API).
 G5. Code size: compile out our implementation when a driver is available.
 
-Currently, some parts of (G1) and (G2) are implemented when
+As of Mbed TLS 3.2, most of (G1) and all of (G2) is implemented when
 `MBEDTLS_USE_PSA_CRYPTO` is enabled. For (G2) to take effect, the application
-needs to be changed to use new APIs.
+needs to be changed to use new APIs. For a more detailed account of what's
+implemented, see `docs/use-psa-crypto.md`, where new APIs are about (G2), and
+internal changes implement (G1).
 
 Generally speaking, the numbering above doesn't mean that each goal requires
-the preceding ones to be completed, for example G2-G5 could be done in any
+the preceding ones to be completed.
-order; however they all either depend on G1 or are just much more convenient
-if G1 is done before (note that this is not a dependency on G1 being complete,
-it's more like each bit of G2-G5 is helped by some specific bit in G1).
-
-So, a solid intermediate goal would be to complete (G1) when
-`MBEDTLS_USA_PSA_CRYPTO` is enabled - that is, all crypto operations in X.509
-and TLS would be done via the PSA Crypto API.
 
 Compile-time options
 ====================
@@ -36,37 +31,37 @@ We currently have two compile-time options that are relevant to the migration:
 - `MBEDTLS_USE_PSA_CRYPTO` - disabled by default (enabled in "full" config),
   controls usage of PSA Crypto APIs to perform operations in X.509 and TLS
 (G1 above), as well as the availability of some new APIs (G2 above).
+- `PSA_CRYPTO_CONFIG` - disabled by default, supports builds with drivers and
+  without the corresponding software implementation (G5 above).
 
 The reasons why `MBEDTLS_USE_PSA_CRYPTO` is optional and disabled by default
 are:
 - it's incompatible with `MBEDTLS_ECP_RESTARTABLE`;
-- historical: used to be incompatible
-  `MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` (fixed early 2022, see
-    <https://github.com/ARMmbed/mbedtls/issues/5259>);
-- it does not work well with `MBEDTLS_PSA_CRYPTO_CONFIG` (could compile with
-  both of them, but then `MBEDTLS_PSA_CRYPTO_CONFIG` won't have the desired
-effect)
 - to avoid a hard/default dependency of TLS, X.509 and PK on
   `MBEDTLS_PSA_CRYPTO_C`, for backward compatibility reasons:
-  - when `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
+  - When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
-    `psa_crypto_init()` before TLS/X.509 uses PSA functions
+    `psa_crypto_init()` before TLS/X.509 uses PSA functions. (This prevents us
-  - `MBEDTLS_PSA_CRYPTO_C` has a hard depend on `MBEDTLS_ENTROPY_C ||
+from even enabling the option by default.)
+  - `MBEDTLS_PSA_CRYPTO_C` has a hard dependency on `MBEDTLS_ENTROPY_C ||
     MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` but it's
-    currently possible to compilte TLS and X.509 without any of the options.
+    currently possible to compile TLS and X.509 without any of the options.
     Also, we can't just auto-enable `MBEDTLS_ENTROPY_C` as it doesn't build
     out of the box on all platforms, and even less
     `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` as it requires a user-provided RNG
     function.
 
-The downside of this approach is that until we feel ready to make
+The downside of this approach is that until we are able to make
 `MBDEDTLS_USE_PSA_CRYPTO` non-optional (always enabled), we have to maintain
 two versions of some parts of the code: one using PSA, the other using the
 legacy APIs. However, see next section for strategies that can lower that
 cost. The rest of this section explains the reasons for the
 incompatibilities mentioned above.
 
-In the medium term (writing this in early 2020), we're going to look for ways
+At the time of writing (early 2022) it is unclear what could be done about the
-to make `MBEDTLS_USE_PSA_CRYPTO` non-optional (always enabled).
+backward compatibility issues, and in particular if the cost of implementing
+solutions to these problems would be higher or lower than the cost of
+maintaining dual code paths until the next major version. (Note: these
+solutions would probably also solve other problems at the same time.)
 
 ### `MBEDTLS_ECP_RESTARTABLE`
 
@@ -76,51 +71,19 @@ Crypto does not support restartable operations, there's a clear conflict: the
 TLS and X.509 layers can't both use only PSA APIs and get restartable
 behaviour.
 
-Supporting this in PSA is on our roadmap (it's been requested). But it's way
+Supporting this in PSA is on our roadmap and currently planned for end of
-below generalizing support for `MBEDTLS_USE_PSA_CRYPTO` for “mainstream” use
+2022, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18883250>.
-cases on our priority list. So in the medium term `MBEDTLS_ECP_RESTARTABLE` is
-incompatible with `MBEDTLS_USE_PSA_CRYPTO`.
 
-Note: it is possible to make the options compatible at build time simply by
+It will then require follow-up work to make use of the new PSA API in
-deciding that when `USE_PSA_CRYPTO` is enabled, PSA APIs are used except if
+PK/X.509/TLS in all places where we currently allow restartable operations.
-restartable behaviour was requested at run-time (in addition to enabling
-`MBEDTLS_ECP_RESTARTABLE` in the build).
 
-### `MBEDTLS_PSA_CRYPTO_CONFIG`
+### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` always on
-
-(This section taken from a comment by Gilles.)
-
-X509 and TLS code use `MBEDTLS_xxx` macros to decide whether an algorithm is
-supported. This doesn't make `MBEDTLS_USE_PSA_CRYPTO` incompatible with
-`MBEDTLS_PSA_CRYPTO_CONFIG` per se, but it makes it incompatible with most
-useful uses of `MBEDTLS_PSA_CRYPTO_CONFIG`. The point of
-`MBEDTLS_PSA_CRYPTO_CONFIG` is to be able to build a library with support for
-an algorithm through a PSA driver only, without building the software
-implementation of that algorithm. But then the TLS code would consider the
-algorithm unavailable.
-
-This is tracked in https://github.com/ARMmbed/mbedtls/issues/3674 and
-https://github.com/ARMmbed/mbedtls/issues/3677. But now that I look at it with
-fresh eyes, I don't think the approach we were planning to use would actually
-works. This needs more design effort.
-
-This is something we need to support eventually, and several partners want it.
-I don't know what the priority is for `MBEDTLS_USE_PSA_CRYPTO` between
-improving driver support and covering more of the protocol. It seems to me
-that it'll be less work overall to first implement a good architecture for
-`MBEDTLS_USE_PSA_CRYPTO + MBEDTLS_PSA_CRYPTO_CONFIG` and then extend to more
-protocol features, because implementing that architecture will require changes
-to the existing code and the less code there is at this point the better,
-whereas extending to more protocol features will require the same amount of
-work either way.
-
-### Backward compatibility issues with making it always on
 
 1. Existing applications may not be calling `psa_crypto_init()` before using
    TLS, X.509 or PK. We can try to work around that by calling (the relevant
 part of) it ourselves under the hood as needed, but that would likely require
 splitting init between the parts that can fail and the parts that can't (see
-https://github.com/ARM-software/psa-crypto-api/pull/536 for that).
+<https://github.com/ARM-software/psa-crypto-api/pull/536> for that).
 2. It's currently not possible to enable `MBEDTLS_PSA_CRYPTO_C` in
    configurations that don't have `MBEDTLS_ENTROPY_C`, and we can't just
 auto-enable the latter, as it won't build or work out of the box on all
@@ -138,7 +101,7 @@ available in entropy-less builds. (Then code using those functions still needs
 to have one version using it, for entropy-less builds, and one version using
 the standard function, for driver support in build with entropy.)
 
-See https://github.com/ARMmbed/mbedtls/issues/5156
+See <https://github.com/Mbed-TLS/mbedtls/issues/5156>.
 
 Taking advantage of the existing abstractions layers - or not
 =============================================================
@@ -174,9 +137,8 @@ crypto API.
 - Downside: tricky to implement if the PSA implementation is currently done on
   top of that layer (dependency loop).
 
-This strategy is currently (late 2021) used for ECDSA signature
+This strategy is currently (early 2022) used for all operations in the PK
-verification in the PK layer, and could be extended to all operations in the
+layer.
-PK layer.
 
 This strategy is not very well suited to the Cipher layer, as the PSA
 implementation is currently done on top of that layer.
@@ -184,9 +146,9 @@ implementation is currently done on top of that layer.
 This strategy will probably be used for some time for the PK layer, while we
 figure out what the future of that layer is: parts of it (parse/write, ECDSA
 signatures in the format that X.509 & TLS want) are not covered by PSA, so
-they will need to keep existing in some way. Also the PK layer is also a good
+they will need to keep existing in some way. (Also, the PK layer is a good
 place for dispatching to either PSA or `mbedtls_xxx_restartable` while that
-part is not covered by PSA yet.
+part is not covered by PSA yet, if we decide to do that.)
 
 Replace calls for each operation
 --------------------------------
@@ -199,10 +161,8 @@ Replace calls for each operation
   code size.
 - Downside: TLS/X.509 code has to be done for each operation.
 
-This strategy is currently (late 2021) used for the MD layer. (Currently only
+This strategy is currently (early 2022) used for the MD layer and the Cipher
-a subset of calling places, but will be extended to all of them.)
+layer.
-
-In the future (early 2022) we're going to use it for the Cipher layer as well.
 
 Opt-in use of PSA from the abstraction layer
 --------------------------------------------
@@ -225,20 +185,16 @@ function also allows for key isolation (the key is only held by PSA,
 supporting both G1 and G2 in that area), and one without isolation (the key is
 still stored outside of PSA most of the time, supporting only G1).
 
-This strategy, with support for key isolation, is currently (end of 2021) used for ECDSA
+This strategy, with support for key isolation, is currently (early 2022) used for
-signature generation in the PK layer - see `mbedtls_pk_setup_opaque()`. This
+private-key operations in the PK layer - see `mbedtls_pk_setup_opaque()`. This
 allows use of PSA-held private ECDSA keys in TLS and X.509 with no change to
-the TLS/X.509 code, but a contained change in the application. If could be
+the TLS/X.509 code, but a contained change in the application.
-extended to other private key operations in the PK layer, which is the plan as
-of early 2022.
 
-This strategy, without key isolation, is also currently used in the Cipher
+This strategy, without key isolation, was also previously used (until 3.1
-layer - see `mbedtls_cipher_setup_psa()`. This allows use of PSA for cipher
+included) in the Cipher layer - see `mbedtls_cipher_setup_psa()`. This allowed
-operations in TLS with no change to the application code, and a
+use of PSA for cipher operations in TLS with no change to the application
-contained change in TLS code. (It currently only supports a subset of
+code, and a contained change in TLS code. (It only supported a subset of
-ciphers.) However, we'll move to the "Replace calls for each operation"
+ciphers.)
-strategy (early 2022), in the hope of being able to build without this layer
-in order to save some code size in the future.
 
 Note: for private key operations in the PK layer, both the "silent" and the
 "opt-in" strategy can apply, and can complement each other, as one provides
@@ -249,15 +205,188 @@ support for drivers, but fails to provide isolation support.
 Summary
 -------
 
-Strategies currently used with each abstraction layer:
+Strategies currently (early 2022) used with each abstraction layer:
 
 - PK (for G1): silently call PSA
 - PK (for G2): opt-in use of PSA (new key type)
-- Cipher (G1):
+- Cipher (G1): replace calls at each call site
-  - late 2021: opt-in use of PSA (new setup function)
-  - early 2022: moving to "replace calls at each call site"
 - MD (G1): replace calls at each call site
 
+
+Supporting builds with drivers without the software implementation
+==================================================================
+
+This section presents a plan towards G5: save code size by compiling out our
+software implementation when a driver is available.
+
+Additionally, we want to save code size by compiling out the
+abstractions layers that we are not using when `MBEDTLS_USE_PSA_CRYPTO` is
+enabled (see previous section): MD and Cipher.
+
+Let's expand a bit on the definition of the goal: in such a configuration
+(driver used, software implementation and abstraction layer compiled out),
+we want:
+
+a. the library to build in a reasonably-complete configuration,
+b. with all tests passing,
+c. and no more tests skipped than the same configuration with software
+   implementation.
+
+Criterion (c) ensures not only test coverage, but that driver-based builds are
+at feature parity with software-based builds.
+
+We can roughly divide the work needed to get there in the following steps:
+
+0. Have a working driver interface for the algorithms we want to replace.
+1. Have users of these algorithms call to PSA, not the legacy API, for all
+   operations. (This is G1, and for PK, X.509 and TLS this is controlled by
+   `MBEDTLS_USE_PSA_CRYPTO`.) This needs to be done in the library and tests.
+2. Have users of these algorithms not depend on the legacy API for information
+   management (getting a size for a given algorithm, etc.)
+3. Adapt compile-time guards used to query availability of a given algorithm;
+   this needs to be done in the library (for crypto operations and data) and
+tests.
+
+Note: the first two steps enable use of drivers, but not by themselves removal
+of the software implementation.
+
+Note: the fact that step 1 is not achieved for all of libmbedcrypto (see
+below) is the reason why criterion (a) has "a reasonably-complete
+configuration", to allow working around internal crypto dependencies when
+working on other parts such as X.509 and TLS - for example, a configuration
+without RSA PKCS#1 v2.1 still allows reasonable use of X.509 and TLS.
+
+Note: this is a conceptual division that will sometimes translate to how the
+work is divided into PRs, sometimes not. For example, in situations where it's
+not possible to achieve good test coverage at the end of step 1 or step 2, it
+is preferable to group with the next step(s) in the same PR until good test
+coverage can be reached.
+
+**Status as of Mbed TLS 3.2:**
+
+- Step 0 is achieved for most algorithms, with only a few gaps remaining.
+- Step 1 is achieved for most of PK, X.509, and TLS when
+  `MBEDTLS_USE_PSA_CRYPTO` is enabled with only a few gaps remaining (see
+  docs/use-psa-crypto.md).
+- Step 1 is not achieved for a lot of the crypto library including the PSA
+  core. For example, `entropy.c` calls the legacy API
+  `mbedtls_sha256` (or `mbedtls_sha512` optionally); `hmac_drbg.c` calls the
+  legacy API `mbedtls_md` and `ctr_drbg.c` calls the legacy API `mbedtls_aes`;
+  the PSA core depends on the entropy module and at least one of the DRBG
+  modules (unless `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` is used). Further, several
+  crypto modules have similar issues, for example RSA PKCS#1 v2.1 calls
+  `mbedtls_md` directly.
+- Step 2 is achieved for most of X.509 and TLS (same gaps as step 1) when
+  `MBEDTLS_USE_PSA_CRYPTO` is enabled - this was tasks like #5795, #5796,
+  #5797. It is being done in PK and RSA PKCS#1 v1.5 by PR #6065.
+- Step 3 was mostly not started at all before 3.2; it is being done for PK by
+  PR #6065.
+
+**Strategy for step 1:**
+
+Regarding PK, X.509, and TLS, this is mostly achieved with only a few gaps.
+(The strategy was outlined in the previous section.)
+
+Regarding libmbedcrypto, outside of the RNG subsystem, for modules that
+currently depend on other legacy crypto modules, this can be achieved without
+backwards compatibility issues, by using the software implementation if
+available, and "falling back" to PSA only if it's not. The compile-time
+dependency changes from the current one (say, `MD_C` or `AES_C`) to "the
+previous dependency OR PSA Crypto with needed algorithms". When building
+without software implementation, users need to call `psa_crypto_init()` before
+calling any function from these modules. This condition does not constitute a
+break of backwards compatibility, as it was previously impossible to build in
+those configurations, and in configurations were the build was possible,
+application code keeps working unchanged. An work-in-progress example of
+applying this strategy, for RSA PKCS#1 v2.1, is here:
+<https://github.com/Mbed-TLS/mbedtls/pull/6141>
+
+There is a problem with the modules used for the PSA RNG, as currently the RNG
+is initialized before drivers and the key store. This part will need further
+study, but in the meantime we can proceed with everything that's not the
+entropy module of one of the DRBG modules, and that does not depend on one of
+those modules.
+
+**Strategy for step 2:**
+
+The most satisfying situation here is when we can just use the PSA Crypto API
+for information management as well. However sometimes it may not be
+convenient, for example in parts of the code that accept old-style identifiers
+(such as `mbedtls_md_type_t`) in their API and can't assume PSA to be
+compiled in (such as `rsa.c`).
+
+It is suggested that, as a temporary solution until we clean this up
+later when removing the legacy API including its identifiers (G4), we may
+occasionally use ad-hoc internal functions, such as the ones introduced by PR
+6065 in `library/hash_info.[ch]`.
+
+An alternative would be to have two different code paths depending on whether
+`MBEDTLS_PSA_CRYPTO_C` is defined or not. However this is not great for
+readability or testability.
+
+**Strategy for step 3:**
+
+There are currently two (complementary) ways for crypto-using code to check if a
+particular algorithm is supported: using `MBEDTLS_xxx` macros, and using
+`PSA_WANT_xxx` macros. For example, PSA-based code that want to use SHA-256
+will check for `PSA_WANT_ALG_SHA_256`, while legacy-based code that wants to
+use SHA-256 will check for `MBEDTLS_SHA256_C` if using the `mbedtls_sha256`
+API, or for `MBEDTLS_MD_C && MBEDTLS_SHA256_C` if using the `mbedtls_md` API.
+
+Code that obeys `MBEDTLS_USE_PSA_CRYPTO` will want to use one of the two
+dependencies above depending on whether `MBEDTLS_USE_PSA_CRYPTO` is defined:
+if it is, the code want the algorithm available in PSA, otherwise, it wants it
+available via the legacy API(s) is it using (MD and/or low-level).
+
+The strategy for steps 1 and 2 above will introduce new situations: code that
+currently compute hashes using MD (resp. a low-level hash module) will gain
+the ability to "fall back" to using PSA if the legacy dependency isn't
+available. Data related to a certain hash (OID, sizes, translations) should
+only be included in the build if it is possible to use that hash in some way.
+
+In order to cater to these new needs, new families of macros are introduced in
+`library/legacy_or_psa.h`, see its documentation for details.
+
+It should be noted that there are currently:
+- too many different ways of computing a hash (low-level, MD, PSA);
+- too many different ways to configure the library that influence which of
+  these ways is available and will be used (`MBEDTLS_USE_PSA_CRYPTO`,
+`MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls_config.h` + `psa/crypto_config.h`).
+
+As a result, we need more families of dependency macros than we'd like to.
+This is a temporary situation until we move to a place where everything is
+based on PSA Crypto. In the meantime, long and explicit names where chosen for
+the new macros in the hope of avoiding confusion.
+
+Executing step 3 will mostly consist of using the right dependency macros in
+the right places (once the previous steps are done).
+
+**Note on testing**
+
+Since supporting driver-only builds is not about adding features, but about
+supporting existing features in new types of builds, testing will not involve
+adding cases to the test suites, but instead adding new components in `all.sh`
+that build and run tests in newly-supported configurations. For example, if
+we're making some part of the library work with hashes provided only by
+drivers when `MBEDTLS_USE_PSA_CRYPTO` is defined, there should be a place in
+`all.sh` that builds and run tests in such a configuration.
+
+There is however a risk, especially in step 3 where we change how dependencies
+are expressed (sometimes in bulk), to get things wrong in a way that would
+result in more tests being skipped, which is easy to miss. Care must be
+taken to ensure this does not happen. The following criteria can be used:
+
+- the sets of tests skipped in the default config and the full config must be
+  the same before and after the PR that implements step 3;
+- the set of tests skipped in the driver-only build is the same as in an
+  equivalent software-based configuration, or the difference is small enough,
+  justified, and a github issue is created to track it.
+
+Note that the favourable case is when the number of tests skipped is 0 in the
+driver-only build. In other cases, analysis of the outcome files is needed,
+see the example script `outcome-analysis.sh` in the same directory.
+
+
 Migrating away from the legacy API
 ==================================
 
@@ -267,7 +396,7 @@ mainly as they relate to choices in previous stages.
 The role of the PK/Cipher/MD APIs in user migration
 ---------------------------------------------------
 
-We're currently taking advantage of the existing PK and Cipher layers in order
+We're currently taking advantage of the existing PK layer in order
 to reduce the number of places where library code needs to be changed. It's
 only natural to consider using the same strategy (with the PK, MD and Cipher
 layers) for facilitating migration of application code.
@@ -281,7 +410,7 @@ The most favourable case is if we can have a zero-cost abstraction (no
 runtime, RAM usage or code size penalty), for example just a bunch of
 `#define`s, essentially mapping `mbedtls_` APIs to their `psa_` equivalent.
 
-Unfortunately that's unlikely fully work. For example, the MD layer uses the
+Unfortunately that's unlikely to fully work. For example, the MD layer uses the
 same context type for hashes and HMACs, while the PSA API (rightfully) has
 distinct operation types. Similarly, the Cipher layer uses the same context
 type for unauthenticated and AEAD ciphers, which again the PSA API
@@ -360,7 +489,7 @@ would need a way to easily extract the PSA key ID from the PK context.
 
 2. APIs the accept list of identifiers: for example
    `mbedtls_ssl_conf_curves()` taking a list of `mbedtls_ecp_group_id`s. This
-could be changed to accept a list of pairs (`psa_ecc_familiy_t`, size) but we
+could be changed to accept a list of pairs (`psa_ecc_family_t`, size) but we
 should probably take this opportunity to move to a identifier independent from
 the underlying crypto implementation and use TLS-specific identifiers instead
 (based on IANA values or custom enums), as is currently done in the new
@@ -373,5 +502,5 @@ An question that needs careful consideration when we come around to removing
 the low-level crypto APIs and making PK, MD and Cipher optional compatibility
 layers is to be sure to preserve testing quality. A lot of the existing test
 cases use the low level crypto APIs; we would need to either keep using that
-API for tests, or manually migrated test to the PSA Crypto API. Perhaps a
+API for tests, or manually migrate tests to the PSA Crypto API. Perhaps a
 combination of both, perhaps evolving gradually over time.

docs/architecture/psa-migration/tasks-g2.md

@@ -1,80 +0,0 @@
-This document is temporary; it lists tasks to achieve G2 as described in
-`strategy.md` while the strategy is being reviewed - once that's done,
-corresponding github issues will be created and this document removed.
-
-For all of the tasks here, specific testing (integration and unit test depending
-on the task) is required, see `testing.md`.
-
-RSA Signature operations
-========================
-
-In PK
------
-
-### Modify existing `PK_OPAQUE` type to allow for RSA keys
-
-- the following must work and be tested: `mbedtls_pk_get_type()`,
-  `mbedtls_pk_get_name()`, `mbedtls_pk_get_bitlen()`, `mbedtls_pk_get_len()`,
-`mbedtls_pk_can_do()`.
-- most likely adapt `pk_psa_genkey()` in `test_suite_pk.function`.
-- all other function (sign, verify, encrypt, decrypt, check pair, debug) will
-  return `MBEDTLS_ERR_PK_TYPE_MISMATCH` and this will be tested too.
-
-### Modify `mbedtls_pk_wrap_as_opaque()` to work with RSA.
-
-- OK to have policy hardcoded on signing with PKCS1v1.5, or allow more if
-  available at this time
-
-### Modify `mbedtls_pk_write_pubkey_der()` to work with RSA-opaque.
-
-- OK to just test that a generated key (with `pk_psa_genkey()`) can be
-  written, without checking for correctness of the result - this will be
-tested as part of another task
-
-### Make `mbedtls_pk_sign()` work with RSA-opaque.
-
-- testing may extend `pk_psa_sign()` in `test_suite_pk_function` by adding
-  selector for ECDSA/RSA.
-
-In X.509
---------
-
-### Test using RSA-opaque for CSR generation
-
-- similar to what's already done with ECDSA-opaque
-
-### Test using opaque keys for Certificate generation
-
-- similar to what's done with testing CSR generation
-- should test both RSA and ECDSA as ECDSA is not tested yet
-- might require slight code adaptations, even if unlikely
-
-
-In TLS
-------
-
-### Test using RSA-opaque for TLS client auth
-
-- similar to what's already done with ECDSA-opaque
-
-### Test using RSA-opaque for TLS server auth
-
-- similar to what's already done with ECDSA-opaque
-- key exchanges: ECDHE-RSA and DHE-RSA
-
-RSA decrypt
-===========
-
-### Extend `PK_OPAQUE` to allow RSA decryption (PKCS1 v1.5)
-
-### Test using that in TLS for RSA and RSA-PSK key exchange.
-
-Support opaque PSKs for "mixed-PSK" key exchanges
-=================================================
-
-See `PSA-limitations.md`.
-
-Possible split:
-- one task to extend PSA (see `PSA-limitations.md`)
-- then one task per handshake: DHE-PSK, ECDHE-PSK, RSA-PSK (with tests for
-  each)

docs/architecture/psa-migration/testing.md

@@ -21,11 +21,11 @@ they should be when `MBEDTLS_USE_PSA_CRYPTO` is enabled.
 However, when it comes to TLS, we also have the option of using debug messages
 to confirm which code path is taken. This is generally unnecessary, except when
 a decision is made at run-time about whether to use the PSA or legacy code
-path. For example, for record protection, currently some ciphers are supported
+path. (For example, for record protection, previously (until 3.1), some ciphers were supported
-via PSA while some others aren't, with a run-time fallback. In this case, it's
+via PSA while some others weren't, with a run-time fallback. In this case, it's
 good to have a debug message checked by the test case to confirm that the
 right decision was made at run-time, i. e. that we didn't use the fallback for
-ciphers that are supposed to be supported.
+ciphers that are supposed to be supported.)
 
 
 New APIs meant for application use
@@ -54,9 +54,8 @@ In that case, we want:
     (We should have the same server-side.)
   - in `test_suite_x509write` we have a new test function
     `x509_csr_check_opaque()` checking integration of the new API with the
-    existing `mbedtls_x509write_csr_set_key()`.
+    existing `mbedtls_x509write_csr_set_key()`. (And also
-    (We should have something similar for
+    `mbedtls_x509write_crt_set_issuer_key()` since #5710.)
-    `mbedtls_x509write_crt_set_issuer_key()`.)
 
 For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, testing in
 `test_suite_ssl` was historically not possible, so we only have testing in
@@ -65,8 +64,9 @@ For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, testing in
 New APIs meant for internal use
 -------------------------------
 
-For example, `mbedtls_cipher_setup_psa()` is meant to be used by the TLS
+For example, `mbedtls_cipher_setup_psa()` (no longer used, soon to be
-layer, but probably not directly by applications.
+deprecated - #5261) was meant to be used by the TLS layer, but probably not
+directly by applications.
 
 In that case, we want:
 

docs/architecture/testing/driver-interface-test-strategy.md

@@ -87,7 +87,7 @@ Creating or removing a key in a secure element involves multiple storage modific
 * This must be done for each possible flow, including error cases (e.g. a key creation that fails midway due to `OUT_OF_MEMORY`).
 * The recovery during `psa_crypto_init` can itself be interrupted. Test those interruptions too.
 * Two things need to be tested: the key that is being created or destroyed, and the driver's persistent storage.
-* Check both that the storage has the expected content (this can be done by e.g. using a key that is supposed to be present) and does not have any unexpected content (for keys, this can be done by checking that `psa_open_key` fails with `PSA_ERRROR_DOES_NOT_EXIST`).
+* Check both that the storage has the expected content (this can be done by e.g. using a key that is supposed to be present) and does not have any unexpected content (for keys, this can be done by checking that `psa_open_key` fails with `PSA_ERROR_DOES_NOT_EXIST`).
 
 This requires instrumenting the storage implementation, either to force it to fail at each point or to record successive storage states and replay each of them. Each `psa_its_xxx` function call is assumed to be atomic.
 

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

@@ -40,7 +40,7 @@ If the way certain keys are stored changes, and we don't deliberately decide to
 
 ## Storage architecture overview
 
-The PSA subsystem provides storage on top of the PSA trusted storage interface. The state of the storage is a mapping from file identifer (a 64-bit number) to file content (a byte array). These files include:
+The PSA subsystem provides storage on top of the PSA trusted storage interface. The state of the storage is a mapping from file identifier (a 64-bit number) to file content (a byte array). These files include:
 
 * [Key files](#key-storage) (files containing one key's metadata and, except for some secure element keys, key material).
 * The [random generator injected seed or state file](#random-generator-state) (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`).

docs/architecture/tls13-support.md

@@ -4,8 +4,8 @@ TLS 1.3 support
 Overview
 --------
 
-Mbed TLS provides a minimum viable implementation of the TLS 1.3 protocol
+Mbed TLS provides a partial implementation of the TLS 1.3 protocol defined in
-defined in the "MVP definition" section below. The TLS 1.3 support enablement
+the "Support description" section below. The TLS 1.3 support enablement
 is controlled by the MBEDTLS_SSL_PROTO_TLS1_3 configuration option.
 
 The development of the TLS 1.3 protocol is based on the TLS 1.3 prototype
@@ -16,38 +16,22 @@ development branch into the prototype. The section "Prototype upstreaming
 status" below describes what remains to be upstreamed.
 
 
-MVP definition
+Support description
---------------
+-------------------
 
 - Overview
 
-  - The TLS 1.3 MVP implements only the client side of the protocol.
+  - Mbed TLS implements both the client and the server side of the TLS 1.3
+    protocol.
 
-  - The TLS 1.3 MVP supports ECDHE key establishment.
+  - Mbed TLS supports ECDHE key establishment.
 
-  - The TLS 1.3 MVP does not support DHE key establishment.
+  - Mbed TLS does not support DHE key establishment.
 
-  - The TLS 1.3 MVP does not support pre-shared keys, including any form of
+  - Mbed TLS does not support pre-shared keys, including any form of
     session resumption. This implies that it does not support sending early
     data (0-RTT data).
 
-  - The TLS 1.3 MVP supports the authentication of the server by the client
-    but does not support authentication of the client by the server. In terms
-    of TLS 1.3 authentication messages, this means that the TLS 1.3 MVP
-    supports the processing of the Certificate and CertificateVerify messages
-    but not of the CertificateRequest message.
-
-  - The TLS 1.3 MVP does not support the handling of server HelloRetryRequest
-    message. In practice, this means that the handshake will fail if the MVP
-    does not provide in its ClientHello the shared secret associated to the
-    group selected by the server for key establishement. For more information,
-    see the comment associated to the `key_share` extension below.
-
-  - If the TLS 1.3 MVP receives a HelloRetryRequest or a CertificateRequest
-    message, it aborts the handshake with an handshake_failure closure alert
-    and the `mbedtls_ssl_handshake()` returns in error with the
-    `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` error code.
-
 - Supported cipher suites: depends on the library configuration. Potentially
   all of them:
   TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256,
@@ -55,94 +39,72 @@ MVP definition
 
 - Supported ClientHello extensions:
 
-  | Extension                    |   MVP   | Prototype (1) |
+  | Extension                    | Support |
-  | ---------------------------- | ------- | ------------- |
+  | ---------------------------- | ------- |
-  | server_name                  | YES     | YES           |
+  | server_name                  | YES     |
-  | max_fragment_length          | no      | YES           |
+  | max_fragment_length          | no      |
-  | status_request               | no      | no            |
+  | status_request               | no      |
-  | supported_groups             | YES     | YES           |
+  | supported_groups             | YES     |
-  | signature_algorithms         | YES     | YES           |
+  | signature_algorithms         | YES     |
-  | use_srtp                     | no      | no            |
+  | use_srtp                     | no      |
-  | heartbeat                    | no      | no            |
+  | heartbeat                    | no      |
-  | apln                         | no      | YES           |
+  | apln                         | YES     |
-  | signed_certificate_timestamp | no      | no            |
+  | signed_certificate_timestamp | no      |
-  | client_certificate_type      | no      | no            |
+  | client_certificate_type      | no      |
-  | server_certificate_type      | no      | no            |
+  | server_certificate_type      | no      |
-  | padding                      | no      | no            |
+  | padding                      | no      |
-  | key_share                    | YES (2) | YES           |
+  | key_share                    | YES     |
-  | pre_shared_key               | no      | YES           |
+  | pre_shared_key               | no      |
-  | psk_key_exchange_modes       | no      | YES           |
+  | psk_key_exchange_modes       | no      |
-  | early_data                   | no      | YES           |
+  | early_data                   | no      |
-  | cookie                       | no      | YES           |
+  | cookie                       | no      |
-  | supported_versions           | YES (3) | YES           |
+  | supported_versions           | YES     |
-  | certificate_authorities      | no      | no            |
+  | certificate_authorities      | no      |
-  | post_handshake_auth          | no      | no            |
+  | post_handshake_auth          | no      |
-  | signature_algorithms_cert    | no      | no            |
+  | signature_algorithms_cert    | no      |
 
-  (1) This is just for comparison.
-
-  (2) The MVP sends only one shared secret corresponding to the configured
-      preferred group. This could end up with connection failure if the
-      server does not support our preferred curve, as the MVP does not implement
-      HelloRetryRequest. The preferred group is the group of the first curve in
-      the list of allowed curves as defined by the configuration. The allowed
-      curves are by default ordered as follows: `x25519`, `secp256r1`,
-      `secp384r1` and finally `secp521r1`. Note that, in the absence of an
-      application profile standard specifying otherwise, section 9.1 of the
-      specification rather promotes curve `secp256r1` to be supported over
-      curve `x25519`. The MVP would, however, rather keep the preference order
-      currently promoted by Mbed TLS as this applies to TLS 1.2 as well, and
-      changing the order only for TLS1.3 would be potentially difficult.
-      In the unlikely event a server does not support curve `x25519` but does
-      support curve `secp256r1`, curve `secp256r1` can be set as the preferred
-      curve through the `mbedtls_ssl_conf_curves()` API.
-
-  (3) The MVP proposes only TLS 1.3 and does not support version negotiation.
-      Out-of-protocol fallback is supported though if the Mbed TLS library
-      has been built to support both TLS 1.3 and TLS 1.2: just set the
-      maximum of the minor version of the SSL configuration to
-      MBEDTLS_SSL_MINOR_VERSION_3 (`mbedtls_ssl_conf_min_version()` API) and
-      re-initiate a server handshake.
 
 - Supported groups: depends on the library configuration.
-  Potentially all ECDHE groups but x448:
+  Potentially all ECDHE groups:
-  secp256r1, x25519, secp384r1 and secp521r1.
+  secp256r1, x25519, secp384r1, x448 and secp521r1.
 
   Finite field groups (DHE) are not supported.
 
 - Supported signature algorithms (both for certificates and CertificateVerify):
   depends on the library configuration.
   Potentially:
-  rsa_pkcs1_sha256, rsa_pss_rsae_sha256, ecdsa_secp256r1_sha256,
+  ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512,
-  ecdsa_secp384r1_sha384 and ecdsa_secp521r1_sha512.
+  rsa_pkcs1_sha256, rsa_pkcs1_sha384, rsa_pkcs1_sha512, rsa_pss_rsae_sha256,
+  rsa_pss_rsae_sha384 and rsa_pss_rsae_sha512.
 
   Note that in absence of an application profile standard specifying otherwise
-  the three first ones in the list above are mandatory (see section 9.1 of the
+  rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are
-  specification).
+  mandatory (see section 9.1 of the specification).
 
 - Supported versions:
 
-  - TLS 1.2 and TLS 1.3 but version negotiation is not supported.
+  - TLS 1.2 and TLS 1.3 with version negotiation on the client side, not server
+    side.
 
-  - TLS 1.3 cannot be enabled in the build (MBEDTLS_SSL_PROTO_TLS1_3
+  - TLS 1.2 and TLS 1.3 can be enabled in the build independently of each
-    configuration option) without TLS 1.2 (MBEDTLS_SSL_PROTO_TLS1_2 configuration
+    other.
-    option).
-
-  - TLS 1.2 can be enabled in the build independently of TLS 1.3.
 
   - If both TLS 1.3 and TLS 1.2 are enabled at build time, only one of them can
-    be configured at runtime via `mbedtls_ssl_conf_{min,max}_version`. Otherwise,
+    be configured at runtime via `mbedtls_ssl_conf_{min,max}_tls_version` for a
-    `mbedtls_ssl_setup` will raise `MBEDTLS_ERR_SSL_BAD_CONFIG` error.
+    server endpoint. Otherwise, `mbedtls_ssl_setup` will raise
+    `MBEDTLS_ERR_SSL_BAD_CONFIG` error.
 
 - Compatibility with existing SSL/TLS build options:
 
-  The TLS 1.3 MVP is compatible with all TLS 1.2 configuration options in the
+  The TLS 1.3 implementation is compatible with nearly all TLS 1.2
-  sense that when enabling the TLS 1.3 MVP in the library there is no need to
+  configuration options in the sense that when enabling TLS 1.3 in the library
-  modify the configuration for TLS 1.2. The MBEDTLS_USE_PSA_CRYPTO configuration
+  there is rarely any need to modify the configuration from that used for
-  option is an exception though, the TLS 1.3 MVP is not compatible with it.
+  TLS 1.2. There are two exceptions though: the TLS 1.3 implementation requires
+  MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options
+  must be enabled.
 
-  Mbed TLS SSL/TLS related features are not supported or not applicable to the
+  Most of the Mbed TLS SSL/TLS related options are not supported or not
-  TLS 1.3 MVP:
+  applicable to the TLS 1.3 implementation:
 
   | Mbed TLS configuration option            | Support |
   | ---------------------------------------- | ------- |
@@ -152,13 +114,12 @@ MVP definition
   | MBEDTLS_SSL_DEBUG_ALL                    | no      |
   | MBEDTLS_SSL_ENCRYPT_THEN_MAC             | n/a     |
   | MBEDTLS_SSL_EXTENDED_MASTER_SECRET       | n/a     |
-  | MBEDTLS_SSL_KEEP_PEER_CERTIFICATE        | no      |
+  | MBEDTLS_SSL_KEEP_PEER_CERTIFICATE        | no (1)  |
   | MBEDTLS_SSL_RENEGOTIATION                | n/a     |
   | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH          | no      |
   |                                          |         |
   | MBEDTLS_SSL_SESSION_TICKETS              | no      |
-  | MBEDTLS_SSL_EXPORT_KEYS                  | no (1)  |
+  | MBEDTLS_SSL_SERVER_NAME_INDICATION       | yes     |
-  | MBEDTLS_SSL_SERVER_NAME_INDICATION       | no      |
   | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH       | no      |
   |                                          |         |
   | MBEDTLS_ECP_RESTARTABLE                  | no      |
@@ -176,35 +137,20 @@ MVP definition
   | MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED    | n/a     |
   | MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED     | n/a     |
   |                                          |         |
-  | MBEDTLS_USE_PSA_CRYPTO                   | no      |
+  | MBEDTLS_PSA_CRYPTO_C                     | no (1)  |
+  | MBEDTLS_USE_PSA_CRYPTO                   | yes     |
 
-  (1) Some support has already been upstreamed but it is incomplete.
+  (1) These options must remain in their default state of enabled.
   (2) Key exchange configuration options for TLS 1.3 will likely to be
       organized around the notion of key exchange mode along the line
       of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL
       runtime configuration macros.
 
-- Quality considerations
-  - Standard Mbed TLS review bar
-  - Interoperability testing with OpenSSL and GnuTLS. Test with all the
-    cipher suites and signature algorithms supported by OpenSSL/GnuTLS server.
-  - Negative testing against OpenSSL/GnuTLS servers with which the
-    handshake fails due to incompatibility with the capabilities of the
-    MVP: TLS 1.2 or 1.1 server, server sending an HelloRetryRequest message in
-    response to the MVP ClientHello, server sending a CertificateRequest
-    message ...
-
 
 Prototype upstreaming status
 ----------------------------
 
-The following summarizes which parts of the TLS 1.3 prototype remain to be
+The following parts of the TLS 1.3 prototype remain to be upstreamed:
-upstreamed:
-
-- Ephemeral only handshake on client side: client authentication,
-  HelloRetryRequest support, version negotiation.
-
-- Ephemeral only handshake server side.
 
 - Pre-shared keys, session resumption and 0-RTT data (both client and server
   side).
@@ -324,7 +270,7 @@ TLS 1.3 specific coding rules:
     ```
 
   - To mitigate what happened here
-    (https://github.com/ARMmbed/mbedtls/pull/4882#discussion_r701704527) from
+    (https://github.com/Mbed-TLS/mbedtls/pull/4882#discussion_r701704527) from
     happening again, use always a local variable named `p` for the reading
     pointer in functions parsing TLS 1.3 data, and for the writing pointer in
     functions writing data into an output buffer and only that variable. The
@@ -388,10 +334,10 @@ General coding rules:
 
     Example:
     ```
-    int mbedtls_ssl_tls13_start_handshake_msg( mbedtls_ssl_context *ssl,
+    int mbedtls_ssl_start_handshake_msg( mbedtls_ssl_context *ssl,
-                                               unsigned hs_type,
+                                         unsigned hs_type,
-                                               unsigned char **buf,
+                                         unsigned char **buf,
-                                               size_t *buf_len );
+                                         size_t *buf_len );
     ```
 
   - When a function's parameters span several lines, group related parameters
@@ -400,12 +346,110 @@ General coding rules:
     For example, prefer:
 
     ```
-    mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type,
+    mbedtls_ssl_start_handshake_msg( ssl, hs_type,
-                                           buf, buf_len );
+                                     buf, buf_len );
     ```
     over
     ```
-    mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type, buf,
+    mbedtls_ssl_start_handshake_msg( ssl, hs_type, buf,
-                                           buf_len );
+                                     buf_len );
     ```
     even if it fits.
+
+
+Overview of handshake code organization
+---------------------------------------
+
+The TLS 1.3 handshake protocol is implemented as a state machine. The
+functions `mbedtls_ssl_tls13_handshake_{client,server}_step` are the top level
+functions of that implementation. They are implemented as a switch over all the
+possible states of the state machine.
+
+Most of the states are either dedicated to the processing or writing of an
+handshake message.
+
+The implementation does not go systematically through all states as this would
+result in too many checks of whether something needs to be done or not in a
+given state to be duplicated across several state handlers. For example, on
+client side, the states related to certificate parsing and validation are
+bypassed if the handshake is based on a pre-shared key and thus does not
+involve certificates.
+
+On the contrary, the implementation goes systematically though some states
+even if they could be bypassed if it helps in minimizing when and where inbound
+and outbound keys are updated. The `MBEDTLS_SSL_CLIENT_CERTIFICATE` state on
+client side is a example of that.
+
+The names of the handlers processing/writing an handshake message are
+prefixed with `(mbedtls_)ssl_tls13_{process,write}`. To ease the maintenance and
+reduce the risk of bugs, the code of the message processing and writing
+handlers is split into a sequence of stages.
+
+The sending of data to the peer only occurs in `mbedtls_ssl_handshake_step`
+between the calls to the handlers and as a consequence handlers do not have to
+care about the MBEDTLS_ERR_SSL_WANT_WRITE error code. Furthermore, all pending
+data are flushed before to call the next handler. That way, handlers do not
+have to worry about pending data when changing outbound keys.
+
+### Message processing handlers
+For message processing handlers, the stages are:
+
+* coordination stage: check if the state should be bypassed. This stage is
+optional. The check is either purely based on the reading of the value of some
+fields of the SSL context or based on the reading of the type of the next
+message. The latter occurs when it is not known what the next handshake message
+will be, an example of that on client side being if we are going to receive a
+CertificateRequest message or not. The intent is, apart from the next record
+reading to not modify the SSL context as this stage may be repeated if the
+next handshake message has not been received yet.
+
+* fetching stage: at this stage we are sure of the type of the handshake
+message we must receive next and we try to fetch it. If we did not go through
+a coordination stage involving the next record type reading, the next
+handshake message may not have been received yet, the handler returns with
+`MBEDTLS_ERR_SSL_WANT_READ` without changing the current state and it will be
+called again later.
+
+* pre-processing stage: prepare the SSL context for the message parsing. This
+stage is optional. Any processing that must be done before the parsing of the
+message or that can be done to simplify the parsing code. Some simple and
+partial parsing of the handshake message may append at that stage like in the
+ServerHello message pre-processing.
+
+* parsing stage: parse the message and restrict as much as possible any
+update of the SSL context. The idea of the pre-processing/parsing/post-processing
+organization is to concentrate solely on the parsing in the parsing function to
+reduce the size of its code and to simplify it.
+
+* post-processing stage: following the parsing, further update of the SSL
+context to prepare for the next incoming and outgoing messages. This stage is
+optional. For example, secret and key computations occur at this stage, as well
+as handshake messages checksum update.
+
+* state change: the state change is done in the main state handler to ease the
+navigation of the state machine transitions.
+
+
+### Message writing handlers
+For message writing handlers, the stages are:
+
+* coordination stage: check if the state should be bypassed. This stage is
+optional. The check is based on the value of some fields of the SSL context.
+
+* preparation stage: prepare for the message writing. This stage is optional.
+Any processing that must be done before the writing of the message or that can
+be done to simplify the writing code.
+
+* writing stage: write the message and restrict as much as possible any update
+of the SSL context. The idea of the preparation/writing/finalization
+organization is to concentrate solely on the writing in the writing function to
+reduce the size of its code and simplify it.
+
+* finalization stage: following the writing, further update of the SSL
+context to prepare for the next incoming and outgoing messages. This stage is
+optional. For example, handshake secret and key computation occur at that
+stage (ServerHello writing finalization), switching to handshake keys for
+outbound message on server side as well.
+
+* state change: the state change is done in the main state handler to ease
+the navigation of the state machine transitions.

docs/proposed/psa-driver-interface.md

@@ -241,7 +241,7 @@ The entry points that implement each step of a multi-part operation are grouped
 1. The core calls the `xxx_setup` entry point for this operation family. If this fails, the core destroys the operation context object without calling any other driver entry point on it.
 1. The core calls other entry points that manipulate the operation context object, respecting the constraints.
 1. If any entry point fails, the core calls the driver's `xxx_abort` entry point for this operation family, then destroys the operation context object without calling any other driver entry point on it.
-1. If a “finish” entry point fails, the core destroys the operation context object without calling any other driver entry point on it. The finish entry points are: *prefix*`_mac_sign_finish`, *prefix*`_mac_verify_finish`, *prefix*`_cipher_fnish`, *prefix*`_aead_finish`, *prefix*`_aead_verify`.
+1. If a “finish” entry point fails, the core destroys the operation context object without calling any other driver entry point on it. The finish entry points are: *prefix*`_mac_sign_finish`, *prefix*`_mac_verify_finish`, *prefix*`_cipher_finish`, *prefix*`_aead_finish`, *prefix*`_aead_verify`.
 
 If a driver implements a multi-part operation but not the corresponding single-part operation, the core calls the driver's multipart operation entry points to perform the single-part operation.
 

docs/proposed/psa-driver-wrappers-codegen-migration-guide.md

@@ -1,5 +1,5 @@
-Migrating to an auto genrated psa_crypto_driver_wrappers.c file
+Migrating to an auto generated psa_crypto_driver_wrappers.c file
-===============================================================
+================================================================
 
 **This is a specification of work in progress. The implementation is not yet merged into Mbed TLS.**
 
@@ -8,7 +8,7 @@ It is meant to give the library user migration guidelines while the Mbed TLS pro
 
 ## Introduction
 
-The design of the Driver Wrappers code generation is based on the design proposal https://github.com/ARMmbed/mbedtls/pull/5067
+The design of the Driver Wrappers code generation is based on the design proposal https://github.com/Mbed-TLS/mbedtls/pull/5067
 During the process of implementation there might be minor variations wrt versioning and broader implementation specific ideas, but the design remains the same.
 
 ## Prerequisites
@@ -21,7 +21,7 @@ Python3, Jinja2 rev 2.10.1 and jsonschema rev 3.2.0
 
 ### What's critical for a migrating user
 
-The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver descrioption JSON file(s).
+The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver description JSON file(s).
 
 While that is the larger goal, for version 1.1 here's what's changed
 

docs/use-psa-crypto.md

@@ -1,107 +1,80 @@
 This document describes the compile-time configuration option
-`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective, more specifically its
+`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
-current effects as well as the parts that aren't covered yet.
 
-Current effects
+This option makes the X.509 and TLS library use PSA for cryptographic
-===============
+operations, and enables new APIs for using keys handled by PSA Crypto.
 
-General limitations
+General considerations
--------------------
+----------------------
 
-Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
+**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
-`MBEDTLS_ECP_RESTARTABLE` and
+`MBEDTLS_ECP_RESTARTABLE` to be disabled.
-`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled.
 
-Effect: `MBEDTLS_USE_PSA_CRYPTO` has no effect on TLS 1.3 for which PSA
+**Application code:** when this option is enabled, you need to call
-cryptography is mandatory.
+`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
+module.
 
-Stability: any API that's only available when `MBEDTLS_USE_PSA_CRYPTO` is
+**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
-defined is considered experimental and may change in incompatible ways at any
+are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the
-time. Said otherwise, these APIs are explicitly excluded from the usual API
+TLS 1.3 code that are common with TLS 1.2, however, follow this option;
-stability promises.
+currently this is the record protection code, computation of the running
+handshake hash, and X.509. You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you
+want TLS 1.3 to use PSA everywhere.
 
 New APIs / API extensions
 -------------------------
 
-Some of these APIs are meant for the application to use in place of
-pre-existing APIs, in order to get access to the benefits; in the sub-sections
-below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that
-this requires changes to the application code for the (X.509 and) TLS layers
-to pick up the improvements.
-
-Some of these APIs are mostly meant for internal use by the TLS (and X.509)
-layers; they are indicated below by "Use in (X.509 and) TLS: automatic",
-meaning that no changes to the application code are required for the TLS (and
-X.509) layers to pick up the improvements.
-
 ### PSA-held (opaque) keys in the PK layer
 
-There is a new API function `mbedtls_pk_setup_opaque()` that can be used to
+**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
-wrap a PSA keypair into a PK context. The key can be used for private-key
+wrap a PSA key pair into a PK context. The key can be used for private-key
 operations and its public part can be exported.
 
-Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
+**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers.
 
-Limitations: only for private keys, only ECC. (That is, only ECDSA signature
+**Limitations:** can only wrap a key pair, can only use it for private key
-generation. Note: currently this will use randomized ECDSA while Mbed TLS uses
+operations. (That is, signature generation, and for RSA decryption too.)
-deterministic ECDSA by default.) The following operations are not supported
+Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses
+deterministic ECDSA by default. The following operations are not supported
 with a context set this way, while they would be available with a normal
-`ECKEY` context: `mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`,
+context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key
-`mbedtls_pk_debug()`.
+operations.
 
-Use in X.509 and TLS: opt-in. The application needs to construct the PK context
+**Use in X.509 and TLS:** opt-in. The application needs to construct the PK context
 using the new API in order to get the benefits; it can then pass the
 resulting context to the following existing APIs:
 
 - `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
-  key together with a certificate for ECDSA-based key exchanges (note: while
+  key together with a certificate for certificate-based key exchanges;
-this is supported on both sides, it's currently only tested client-side);
 - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
-  request).
+  request);
-
+- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
-In the TLS and X.509 API, there's one other function which accepts a keypair
-as a PK context: `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque
-contexts here probably works but is so far untested.
 
 ### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
 
-There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and
+**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and
 `mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
 register a PSA key for use with a PSK key exchange.
 
-Benefits: isolation of long-term secrets.
+**Benefits:** isolation of long-term secrets.
 
-Limitations: the key can only be used with "pure"
+**Limitations:** none.
-PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the
-exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of
-the user to make sure that when provisioning an opaque pre-shared key, the
-only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key
-exchanges will result in a handshake failure with the handshake function
-returning `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`.
 
-Use in TLS: opt-in. The application needs to register the key using the new
+**Use in TLS:** opt-in. The application needs to register the key using one of
-APIs to get the benefits.
+the new APIs to get the benefits.
 
 ### PSA-based operations in the Cipher layer
 
 There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
 that will call PSA to store the key and perform the operations.
 
-Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets
+This function only worked for a small number of ciphers. It is now deprecated
-(still generated outside of PSA, but then held by PSA).
+and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions
+directly instead.
 
-Limitations: the key is still passed in the clear by the application. The
+**Warning:** This function will be removed in a future version of Mbed TLS. If
-multi-part APIs are not supported, only the one-shot APIs. The only modes
+you are using it and would like us to keep it, please let us know about your
-supported are ECB, CBC without padding, GCM and CCM (this excludes stream
+use case.
-ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria,
-Camellia, and ChachaPoly). (Note: ECB is currently not tested.) (Note: it is
-possible to perform multiple one-shot operations with the same context;
-however this is not unit-tested, only tested via usage in TLS.)
-
-Use in TLS: automatic. Used when the cipher and mode is supported (with
-gracious fallback to the legacy API otherwise) in all places where a cipher is
-used. There are two such places: in `ssl_tls.c` for record protection, and in
-`ssl_ticket.c` for protecting tickets we issue.
 
 Internal changes
 ----------------
@@ -109,89 +82,34 @@ Internal changes
 All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
 is enabled, no change required on the application side.
 
-### TLS: cipher operations based on PSA
+### TLS: most crypto operations based on PSA
 
-See "PSA-based operations in the Cipher layer" above.
+Current exceptions:
 
-### PK layer: ECDSA verification based on PSA
+- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED` is defined)
+- finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
+  DHE-PSK)
 
-Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature
+Other than the above exceptions, all crypto operations are based on PSA when
-verification.
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
 
-Benefits: use of PSA Crypto drivers.
+### X.509: most crypto operations based on PSA
 
-Use in TLS and X.509: in all places where an ECDSA signature is verified.
+Current exception:
 
-### TLS: ECDHE computation based on PSA
+- verification of RSA-PSS signatures with a salt length that is different from
+  the hash length.
 
-Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
+Other than the above exception, all crypto operations are based on PSA when
-computation of the ECDHE key exchange is done by PSA.
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
 
-Limitations: client-side only, ECDHE-PSK not covered
+### PK layer: most crypto operations based on PSA
 
-Benefits: use of PSA Crypto drivers.
+Current exception:
 
-### TLS: handshake hashes and PRF computed with PSA
+- verification of RSA-PSS signatures with a salt length that is different from
+  the hash length, or with an MGF hash that's different from the message hash.
 
-Scope: with TLS 1.2, the following are computed with PSA:
+Other than the above exception, all crypto operations are based on PSA when
-- the running handshake hashes;
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
-- the hash of the ServerKeyExchange part that is signed;
-- the `verify_data` part of the Finished message;
-- the TLS PRF.
 
-Benefits: use of PSA Crypto drivers.
-
-### X.509: some hashes computed with PSA
-
-Scope: the following hashes are computed with PSA:
-- when verifying a certificate chain, hash of the child for verifying the
-  parent's signature;
-- when writing a CSR, hash of the request for self-signing the request.
-
-Benefits: use of PSA Crypto drivers.
-
-Parts that are not covered yet
-==============================
-
-This is only a high-level overview, grouped by theme
-
-TLS: key exchanges / asymmetric crypto
---------------------------------------
-
-The following key exchanges are not covered at all:
-
-- RSA
-- DHE-RSA
-- DHE-PSK
-- RSA-PSK
-- ECDHE-PSK
-- ECDH-RSA
-- ECDH-ECDSA
-- ECJPAKE
-
-The following key exchanges are only partially covered:
-
-- ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE
-  operation isn't either
-- ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA
-  signature generation is only covered if using `mbedtls_pk_setup_opaque()`.)
-
-PSK if covered when the application uses `mbedtls_ssl_conf_psk_opaque()` or
-`mbedtls_ssl_set_hs_psk_opaque()`.
-
-TLS: symmetric crypto
----------------------
-
-- some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent
-  fallback to the legacy APIs)
-- the HMAC part of the CBC and NULL ciphersuites
-- the HMAC computation in `ssl_cookie.c`
-
-X.509
------
-
-- most hash operations are still done via the legacy API, except the few that
-  are documented above as using PSA
-- RSA PKCS#1 v1.5 signature generation (from PSA-held keys)
-- RSA PKCS#1 v1.5 signature verification
-- RSA-PSS signature verification

doxygen/input/doc_mainpage.h

@@ -22,7 +22,7 @@
  */
 
 /**
- * @mainpage mbed TLS v3.1.0 source code documentation
+ * @mainpage mbed TLS v3.2.1 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

@@ -1,4 +1,4 @@
-PROJECT_NAME           = "mbed TLS v3.1.0"
+PROJECT_NAME           = "mbed TLS v3.2.1"
 OUTPUT_DIRECTORY       = ../apidoc/
 FULL_PATH_NAMES        = NO
 OPTIMIZE_OUTPUT_FOR_C  = YES

include/mbedtls/aes.h

@@ -80,7 +80,8 @@ extern "C" {
 typedef struct mbedtls_aes_context
 {
     int MBEDTLS_PRIVATE(nr);                     /*!< The number of rounds. */
-    uint32_t *MBEDTLS_PRIVATE(rk);               /*!< AES round keys. */
+    size_t MBEDTLS_PRIVATE(rk_offset);           /*!< The offset in array elements to AES
+                                     round keys in the buffer. */
     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:
@@ -553,7 +554,7 @@ int mbedtls_aes_crypt_ofb( mbedtls_aes_context *ctx,
  *             for example, with 96-bit random nonces, you should not encrypt
  *             more than 2**32 messages with the same key.
  *
- *             Note that for both stategies, sizes are measured in blocks and
+ *             Note that for both strategies, sizes are measured in blocks and
  *             that an AES block is 16 bytes.
  *
  * \warning    Upon return, \p stream_block contains sensitive data. Its

include/mbedtls/aria.h

@@ -41,7 +41,7 @@
 #define MBEDTLS_ARIA_DECRYPT     0 /**< ARIA decryption. */
 
 #define MBEDTLS_ARIA_BLOCKSIZE   16 /**< ARIA block size in bytes. */
-#define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maxiumum number of rounds in ARIA. */
+#define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maximum number of rounds in ARIA. */
 #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
 
 /** Bad input data. */
@@ -306,7 +306,7 @@ int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
  *             for example, with 96-bit random nonces, you should not encrypt
  *             more than 2**32 messages with the same key.
  *
- *             Note that for both stategies, sizes are measured in blocks and
+ *             Note that for both strategies, sizes are measured in blocks and
  *             that an ARIA block is 16 bytes.
  *
  * \warning    Upon return, \p stream_block contains sensitive data. Its

include/mbedtls/asn1.h

@@ -228,7 +228,7 @@ mbedtls_asn1_named_data;
  * \return      0 if successful.
  * \return      #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
  *              would end beyond \p end.
- * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
+ * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
  */
 int mbedtls_asn1_get_len( unsigned char **p,
                           const unsigned char *end,
@@ -253,7 +253,7 @@ int mbedtls_asn1_get_len( unsigned char **p,
  *              with the requested tag.
  * \return      #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
  *              would end beyond \p end.
- * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
+ * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
  */
 int mbedtls_asn1_get_tag( unsigned char **p,
                           const unsigned char *end,

include/mbedtls/asn1write.h

@@ -86,7 +86,7 @@ int mbedtls_asn1_write_raw_buffer( unsigned char **p, const unsigned char *start
 
 #if defined(MBEDTLS_BIGNUM_C)
 /**
- * \brief           Write a arbitrary-precision number (#MBEDTLS_ASN1_INTEGER)
+ * \brief           Write an arbitrary-precision number (#MBEDTLS_ASN1_INTEGER)
  *                  in ASN.1 format.
  *
  * \note            This function works backwards in data buffer.

include/mbedtls/bignum.h

@@ -277,7 +277,7 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
  * \param Y        The MPI to be assigned from. This must point to an
  *                 initialized MPI.
  * \param assign   The condition deciding whether to perform the
- *                 assignment or not. Possible values:
+ *                 assignment or not. Must be either 0 or 1:
  *                 * \c 1: Perform the assignment `X = Y`.
  *                 * \c 0: Keep the original value of \p X.
  *
@@ -288,6 +288,10 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
  *                 information through branch prediction and/or memory access
  *                 patterns analysis).
  *
+ * \warning        If \p assign is neither 0 nor 1, the result of this function
+ *                 is indeterminate, and the resulting value in \p X might be
+ *                 neither its original value nor the value in \p Y.
+ *
  * \return         \c 0 if successful.
  * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
  * \return         Another negative error code on other kinds of failure.
@@ -300,24 +304,28 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned
  *
  * \param X        The first MPI. This must be initialized.
  * \param Y        The second MPI. This must be initialized.
- * \param assign   The condition deciding whether to perform
+ * \param swap     The condition deciding whether to perform
- *                 the swap or not. Possible values:
+ *                 the swap or not. Must be either 0 or 1:
  *                 * \c 1: Swap the values of \p X and \p Y.
  *                 * \c 0: Keep the original values of \p X and \p Y.
  *
  * \note           This function is equivalent to
- *                      if( assign ) mbedtls_mpi_swap( X, Y );
+ *                      if( swap ) mbedtls_mpi_swap( X, Y );
  *                 except that it avoids leaking any information about whether
- *                 the assignment was done or not (the above code may leak
+ *                 the swap was done or not (the above code may leak
  *                 information through branch prediction and/or memory access
  *                 patterns analysis).
  *
+ * \warning        If \p swap is neither 0 nor 1, the result of this function
+ *                 is indeterminate, and both \p X and \p Y might end up with
+ *                 values different to either of the original ones.
+ *
  * \return         \c 0 if successful.
  * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
  * \return         Another negative error code on other kinds of failure.
  *
  */
-int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign );
+int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char swap );
 
 /**
  * \brief          Store integer value in MPI.
@@ -955,7 +963,7 @@ int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
  *                 generate yourself and that are supposed to be prime, then
  *                 \p rounds should be at least the half of the security
  *                 strength of the cryptographic algorithm. On the other hand,
- *                 if \p X is chosen uniformly or non-adversially (as is the
+ *                 if \p X is chosen uniformly or non-adversarially (as is the
  *                 case when mbedtls_mpi_gen_prime calls this function), then
  *                 \p rounds can be much lower.
  *

include/mbedtls/build_info.h

@@ -37,17 +37,17 @@
  * Major, Minor, Patchlevel
  */
 #define MBEDTLS_VERSION_MAJOR  3
-#define MBEDTLS_VERSION_MINOR  1
+#define MBEDTLS_VERSION_MINOR  2
-#define MBEDTLS_VERSION_PATCH  0
+#define MBEDTLS_VERSION_PATCH  1
 
 /**
  * The single version number has the following structure:
  *    MMNNPP00
  *    Major version | Minor version | Patch version
  */
-#define MBEDTLS_VERSION_NUMBER         0x03010000
+#define MBEDTLS_VERSION_NUMBER         0x03020100
-#define MBEDTLS_VERSION_STRING         "3.1.0"
+#define MBEDTLS_VERSION_STRING         "3.2.1"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 3.1.0"
+#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 3.2.1"
 
 #if defined(_MSC_VER) && !defined(_CRT_SECURE_NO_DEPRECATE)
 #define _CRT_SECURE_NO_DEPRECATE 1
@@ -77,7 +77,11 @@
 #if defined(MBEDTLS_PK_C) && defined(MBEDTLS_USE_PSA_CRYPTO)
 #define MBEDTLS_PK_WRITE_C
 #endif
-#if defined(MBEDTLS_PSA_CRYPTO_CONFIG)
+
+/* Make sure all configuration symbols are set before including check_config.h,
+ * even the ones that are calculated programmatically. */
+#if defined(MBEDTLS_PSA_CRYPTO_CONFIG) /* PSA_WANT_xxx influences MBEDTLS_xxx */ || \
+    defined(MBEDTLS_PSA_CRYPTO_C) /* MBEDTLS_xxx influences PSA_WANT_xxx */
 #include "mbedtls/config_psa.h"
 #endif
 

include/mbedtls/camellia.h

@@ -262,7 +262,7 @@ int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
  *             encrypted: for example, with 96-bit random nonces, you should
  *             not encrypt more than 2**32 messages with the same key.
  *
- *             Note that for both stategies, sizes are measured in blocks and
+ *             Note that for both strategies, sizes are measured in blocks and
  *             that a CAMELLIA block is \c 16 Bytes.
  *
  * \warning    Upon return, \p stream_block contains sensitive data. Its

include/mbedtls/chachapoly.h

@@ -158,7 +158,7 @@ int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
  *                  and bound to a key.
  * \param nonce     The nonce/IV to use for the message.
- *                  This must be a redable buffer of length \c 12 Bytes.
+ *                  This must be a readable buffer of length \c 12 Bytes.
  * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
  *                  #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
  *

include/mbedtls/check_config.h

@@ -76,7 +76,7 @@
 #endif
 
 #if defined(MBEDTLS_CMAC_C) && \
-    !defined(MBEDTLS_AES_C) && !defined(MBEDTLS_DES_C)
+    ( !defined(MBEDTLS_CIPHER_C ) || ( !defined(MBEDTLS_AES_C) && !defined(MBEDTLS_DES_C) ) )
 #error "MBEDTLS_CMAC_C defined, but not all prerequisites"
 #endif
 
@@ -108,7 +108,8 @@
 #endif
 
 #if defined(MBEDTLS_ECJPAKE_C) &&           \
-    ( !defined(MBEDTLS_ECP_C) || !defined(MBEDTLS_MD_C) )
+    ( !defined(MBEDTLS_ECP_C) ||            \
+      !( defined(MBEDTLS_MD_C) || defined(MBEDTLS_PSA_CRYPTO_C) ) )
 #error "MBEDTLS_ECJPAKE_C defined, but not all prerequisites"
 #endif
 
@@ -146,11 +147,27 @@
 #endif
 
 #if defined(MBEDTLS_PK_PARSE_C) && !defined(MBEDTLS_ASN1_PARSE_C)
-#error "MBEDTLS_PK_PARSE_C defined, but not all prerequesites"
+#error "MBEDTLS_PK_PARSE_C defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_PKCS5_C) && !defined(MBEDTLS_MD_C)
+#if defined(MBEDTLS_PKCS12_C) && !defined(MBEDTLS_CIPHER_C)
-#error "MBEDTLS_PKCS5_C defined, but not all prerequesites"
+#error "MBEDTLS_PKCS12_C defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PKCS5_C) && \
+    ( !( defined(MBEDTLS_MD_C) || defined(MBEDTLS_PSA_CRYPTO_C) ) || \
+        !defined(MBEDTLS_CIPHER_C) )
+#error "MBEDTLS_PKCS5_C defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PKCS12_C) && \
+    !( defined(MBEDTLS_MD_C) || defined(MBEDTLS_PSA_CRYPTO_C) )
+#error "MBEDTLS_PKCS12_C defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PKCS1_V21) && \
+    !( defined(MBEDTLS_MD_C) || defined(MBEDTLS_PSA_CRYPTO_C) )
+#error "MBEDTLS_PKCS1_V21 defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_ENTROPY_C) && (!defined(MBEDTLS_SHA512_C) &&      \
@@ -316,17 +333,28 @@
 #error "!MBEDTLS_SSL_KEEP_PEER_CERTIFICATE requires MBEDTLS_SHA512_C, MBEDTLS_SHA256_C or MBEDTLS_SHA1_C"
 #endif
 
+#if defined(MBEDTLS_MD_C) && !( \
+    defined(MBEDTLS_MD5_C) || \
+    defined(MBEDTLS_RIPEMD160_C) || \
+    defined(MBEDTLS_SHA1_C) || \
+    defined(MBEDTLS_SHA224_C) || \
+    defined(MBEDTLS_SHA256_C) || \
+    defined(MBEDTLS_SHA384_C) || \
+    defined(MBEDTLS_SHA512_C) )
+#error "MBEDTLS_MD_C defined, but not all prerequisites"
+#endif
+
 #if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) &&                          \
     ( !defined(MBEDTLS_PLATFORM_C) || !defined(MBEDTLS_PLATFORM_MEMORY) )
 #error "MBEDTLS_MEMORY_BUFFER_ALLOC_C defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_MEMORY_BACKTRACE) && !defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C)
-#error "MBEDTLS_MEMORY_BACKTRACE defined, but not all prerequesites"
+#error "MBEDTLS_MEMORY_BACKTRACE defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_MEMORY_DEBUG) && !defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C)
-#error "MBEDTLS_MEMORY_DEBUG defined, but not all prerequesites"
+#error "MBEDTLS_MEMORY_DEBUG defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_PADLOCK_C) && !defined(MBEDTLS_HAVE_ASM)
@@ -342,7 +370,7 @@
 #endif
 
 #if defined(MBEDTLS_PK_C) && \
-    ( !defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_ECP_C) )
+    !defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_ECP_C)
 #error "MBEDTLS_PK_C defined, but not all prerequisites"
 #endif
 
@@ -368,6 +396,20 @@
 #error "MBEDTLS_PLATFORM_EXIT_MACRO and MBEDTLS_PLATFORM_STD_EXIT/MBEDTLS_PLATFORM_EXIT_ALT cannot be defined simultaneously"
 #endif
 
+#if defined(MBEDTLS_PLATFORM_SETBUF_ALT) && !defined(MBEDTLS_PLATFORM_C)
+#error "MBEDTLS_PLATFORM_SETBUF_ALT defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PLATFORM_SETBUF_MACRO) && !defined(MBEDTLS_PLATFORM_C)
+#error "MBEDTLS_PLATFORM_SETBUF_MACRO defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PLATFORM_SETBUF_MACRO) &&\
+    ( defined(MBEDTLS_PLATFORM_STD_SETBUF) ||\
+        defined(MBEDTLS_PLATFORM_SETBUF_ALT) )
+#error "MBEDTLS_PLATFORM_SETBUF_MACRO and MBEDTLS_PLATFORM_STD_SETBUF/MBEDTLS_PLATFORM_SETBUF_ALT cannot be defined simultaneously"
+#endif
+
 #if defined(MBEDTLS_PLATFORM_TIME_ALT) &&\
     ( !defined(MBEDTLS_PLATFORM_C) ||\
         !defined(MBEDTLS_HAVE_TIME) )
@@ -550,6 +592,10 @@
 #error "MBEDTLS_PSA_CRYPTO_C defined, but not all prerequisites (missing RNG)"
 #endif
 
+#if defined(MBEDTLS_PSA_CRYPTO_C) && !defined(MBEDTLS_CIPHER_C )
+#error "MBEDTLS_PSA_CRYPTO_C defined, but not all prerequisites"
+#endif
+
 #if defined(MBEDTLS_PSA_CRYPTO_SPM) && !defined(MBEDTLS_PSA_CRYPTO_C)
 #error "MBEDTLS_PSA_CRYPTO_SPM defined, but not all prerequisites"
 #endif
@@ -560,6 +606,14 @@
 #error "MBEDTLS_PSA_CRYPTO_SE_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
+#if defined(MBEDTLS_DEPRECATED_REMOVED)
+#error "MBEDTLS_PSA_CRYPTO_SE_C is deprecated and will be removed in a future version of Mbed TLS"
+#elif defined(MBEDTLS_DEPRECATED_WARNING)
+#warning "MBEDTLS_PSA_CRYPTO_SE_C is deprecated and will be removed in a future version of Mbed TLS"
+#endif
+#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
+
 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) &&            \
     ! defined(MBEDTLS_PSA_CRYPTO_C)
 #error "MBEDTLS_PSA_CRYPTO_STORAGE_C defined, but not all prerequisites"
@@ -605,6 +659,61 @@
 #error "MBEDTLS_SHA384_C defined without MBEDTLS_SHA512_C"
 #endif
 
+#if defined(MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT) && \
+    defined(MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY)
+#error "Must only define one of MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#endif
+
+#if defined(MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT) || \
+    defined(MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY)
+#if !defined(MBEDTLS_SHA512_C)
+#error "MBEDTLS_SHA512_USE_A64_CRYPTO_* defined without MBEDTLS_SHA512_C"
+#endif
+#if defined(MBEDTLS_SHA512_ALT) || defined(MBEDTLS_SHA512_PROCESS_ALT)
+#error "MBEDTLS_SHA512_*ALT can't be used with MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#endif
+/*
+ * Best performance comes from most recent compilers, with intrinsics and -O3.
+ * Must compile with -march=armv8.2-a+sha3, but we can't detect armv8.2-a, and
+ * can't always detect __ARM_FEATURE_SHA512 (notably clang 7-12).
+ *
+ * GCC < 8 won't work at all (lacks the sha512 instructions)
+ * GCC >= 8 uses intrinsics, sets __ARM_FEATURE_SHA512
+ *
+ * Clang < 7 won't work at all (lacks the sha512 instructions)
+ * Clang 7-12 don't have intrinsics (but we work around that with inline
+ *            assembler) or __ARM_FEATURE_SHA512
+ * Clang == 13.0.0 same as clang 12 (only seen on macOS)
+ * Clang >= 13.0.1 has __ARM_FEATURE_SHA512 and intrinsics
+ */
+#if defined(__aarch64__) && !defined(__ARM_FEATURE_SHA512)
+   /* Test Clang first, as it defines __GNUC__ */
+#  if defined(__clang__)
+#    if __clang_major__ < 7
+#      error "A more recent Clang is required for MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#    elif __clang_major__ < 13 || \
+         (__clang_major__ == 13 && __clang_minor__ == 0 && __clang_patchlevel__ == 0)
+       /* We implement the intrinsics with inline assembler, so don't error */
+#    else
+#      error "Must use minimum -march=armv8.2-a+sha3 for MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#    endif
+#  elif defined(__GNUC__)
+#    if __GNUC__ < 8
+#      error "A more recent GCC is required for MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#    else
+#      error "Must use minimum -march=armv8.2-a+sha3 for MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#    endif
+#  else
+#    error "Only GCC and Clang supported for MBEDTLS_SHA512_USE_A64_CRYPTO_*"
+#  endif
+#endif
+
+#endif /* MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT || MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY */
+
+#if defined(MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY) && !defined(__aarch64__)
+#error "MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY defined on non-Aarch64 system"
+#endif
+
 #if defined(MBEDTLS_SHA224_C) && !defined(MBEDTLS_SHA256_C)
 #error "MBEDTLS_SHA224_C defined without MBEDTLS_SHA256_C"
 #endif
@@ -613,23 +722,64 @@
 #error "MBEDTLS_SHA256_C defined without MBEDTLS_SHA224_C"
 #endif
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_2) && ( !defined(MBEDTLS_SHA1_C) &&     \
+#if defined(MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT) && \
-    !defined(MBEDTLS_SHA256_C) && !defined(MBEDTLS_SHA512_C) )
+    defined(MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY)
+#error "Must only define one of MBEDTLS_SHA256_USE_A64_CRYPTO_*"
+#endif
+
+#if defined(MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT) || \
+    defined(MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY)
+#if !defined(MBEDTLS_SHA256_C)
+#error "MBEDTLS_SHA256_USE_A64_CRYPTO_* defined without MBEDTLS_SHA256_C"
+#endif
+#if defined(MBEDTLS_SHA256_ALT) || defined(MBEDTLS_SHA256_PROCESS_ALT)
+#error "MBEDTLS_SHA256_*ALT can't be used with MBEDTLS_SHA256_USE_A64_CRYPTO_*"
+#endif
+#if defined(__aarch64__) && !defined(__ARM_FEATURE_CRYPTO)
+#error "Must use minimum -march=armv8-a+crypto for MBEDTLS_SHA256_USE_A64_CRYPTO_*"
+#endif
+#endif
+
+#if defined(MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY) && \
+    !defined(__aarch64__) && !defined(_M_ARM64)
+#error "MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY defined on non-Aarch64 system"
+#endif
+
+#if defined(MBEDTLS_SSL_PROTO_TLS1_2) && !defined(MBEDTLS_USE_PSA_CRYPTO) && \
+    !( defined(MBEDTLS_SHA1_C) || defined(MBEDTLS_SHA256_C) || defined(MBEDTLS_SHA512_C) )
 #error "MBEDTLS_SSL_PROTO_TLS1_2 defined, but not all prerequisites"
 #endif
 
-/*
+/* TLS 1.3 requires separate HKDF parts from PSA */
- * HKDF is mandatory for TLS 1.3.
- * Otherwise support for at least one ciphersuite mandates either SHA_256 or
- * SHA_384.
- */
 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && \
-    ( ( !defined(MBEDTLS_HKDF_C) ) || \
+        !( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_HKDF_EXTRACT) && defined(PSA_WANT_ALG_HKDF_EXPAND) )
-      ( !defined(MBEDTLS_SHA256_C) && !defined(MBEDTLS_SHA384_C) ) || \
-      ( !defined(MBEDTLS_PSA_CRYPTO_C) ) )
 #error "MBEDTLS_SSL_PROTO_TLS1_3 defined, but not all prerequisites"
 #endif
 
+/* TLS 1.3 requires at least one ciphersuite, so at least SHA-256 or SHA-384 */
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
+/* We always need at least one of the hashes via PSA (for use with HKDF) */
+#if !( defined(PSA_WANT_ALG_SHA_256) || defined(PSA_WANT_ALG_SHA_384) )
+#error "MBEDTLS_SSL_PROTO_TLS1_3 defined, but not all prerequisites"
+#endif /* !(PSA_WANT_ALG_SHA_256 || PSA_WANT_ALG_SHA_384) */
+#if !defined(MBEDTLS_USE_PSA_CRYPTO)
+/* When USE_PSA_CRYPTO is not defined, we also need SHA-256 or SHA-384 via the
+ * legacy interface, including via the MD layer, for the parts of the code
+ * that are shared with TLS 1.2 (running handshake hash). */
+#if !defined(MBEDTLS_MD_C) || \
+    !( defined(MBEDTLS_SHA256_C) || defined(MBEDTLS_SHA384_C) )
+#error "MBEDTLS_SSL_PROTO_TLS1_3 defined, but not all prerequisites"
+#endif /* !MBEDTLS_MD_C || !(MBEDTLS_SHA256_C || MBEDTLS_SHA384_C) */
+#endif /* !MBEDTLS_USE_PSA_CRYPTO */
+#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
+
+/*
+ * The current implementation of TLS 1.3 requires MBEDTLS_SSL_KEEP_PEER_CERTIFICATE.
+ */
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+#error "MBEDTLS_SSL_PROTO_TLS1_3 defined without MBEDTLS_SSL_KEEP_PEER_CERTIFICATE"
+#endif
+
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) &&                                    \
     !(defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED) ||                          \
       defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED) ||                      \
@@ -656,7 +806,7 @@
 #endif
 
 #if defined(MBEDTLS_SSL_TLS_C) && ( !defined(MBEDTLS_CIPHER_C) ||     \
-    !defined(MBEDTLS_MD_C) )
+    ( !defined(MBEDTLS_MD_C) && !defined(MBEDTLS_USE_PSA_CRYPTO) ) )
 #error "MBEDTLS_SSL_TLS_C defined, but not all prerequisites"
 #endif
 
@@ -702,18 +852,24 @@
 
 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) &&   \
     !defined(MBEDTLS_SSL_PROTO_TLS1_2)
-#error "MBEDTLS_SSL_ENCRYPT_THEN_MAC defined, but not all prerequsites"
+#error "MBEDTLS_SSL_ENCRYPT_THEN_MAC defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET) && \
     !defined(MBEDTLS_SSL_PROTO_TLS1_2)
-#error "MBEDTLS_SSL_EXTENDED_MASTER_SECRET defined, but not all prerequsites"
+#error "MBEDTLS_SSL_EXTENDED_MASTER_SECRET defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_SSL_TICKET_C) && !defined(MBEDTLS_CIPHER_C)
+#if defined(MBEDTLS_SSL_TICKET_C) && ( !defined(MBEDTLS_CIPHER_C) && \
+                                       !defined(MBEDTLS_USE_PSA_CRYPTO) )
 #error "MBEDTLS_SSL_TICKET_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH) && \
+    MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH >= 256
+#error "MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH must be less than 256"
+#endif
+
 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) && \
         !defined(MBEDTLS_X509_CRT_PARSE_C)
 #error "MBEDTLS_SSL_SERVER_NAME_INDICATION defined, but not all prerequisites"
@@ -747,14 +903,16 @@
 #endif
 
 #if defined(MBEDTLS_X509_USE_C) && ( !defined(MBEDTLS_BIGNUM_C) ||  \
-    !defined(MBEDTLS_OID_C) || !defined(MBEDTLS_ASN1_PARSE_C) ||      \
+    !defined(MBEDTLS_OID_C) || !defined(MBEDTLS_ASN1_PARSE_C) ||    \
-    !defined(MBEDTLS_PK_PARSE_C) )
+    !defined(MBEDTLS_PK_PARSE_C) ||                                 \
+    ( !defined(MBEDTLS_MD_C) && !defined(MBEDTLS_USE_PSA_CRYPTO) ) )
 #error "MBEDTLS_X509_USE_C defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_X509_CREATE_C) && ( !defined(MBEDTLS_BIGNUM_C) ||  \
     !defined(MBEDTLS_OID_C) || !defined(MBEDTLS_ASN1_WRITE_C) ||       \
-    !defined(MBEDTLS_PK_WRITE_C) )
+    !defined(MBEDTLS_PK_PARSE_C) ||                                    \
+    ( !defined(MBEDTLS_MD_C) && !defined(MBEDTLS_USE_PSA_CRYPTO) ) )
 #error "MBEDTLS_X509_CREATE_C defined, but not all prerequisites"
 #endif
 
@@ -801,23 +959,23 @@
  * cause a build to succeed but with features removed. */
 
 #if defined(MBEDTLS_HAVEGE_C) //no-check-names
-#error "MBEDTLS_HAVEGE_C was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/2599"
+#error "MBEDTLS_HAVEGE_C was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/2599"
 #endif
 
 #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL) //no-check-names
-#error "MBEDTLS_SSL_HW_RECORD_ACCEL was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4031"
+#error "MBEDTLS_SSL_HW_RECORD_ACCEL was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4031"
 #endif
 
 #if defined(MBEDTLS_SSL_PROTO_SSL3) //no-check-names
-#error "MBEDTLS_SSL_PROTO_SSL3 (SSL v3.0 support) was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4031"
+#error "MBEDTLS_SSL_PROTO_SSL3 (SSL v3.0 support) was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4031"
 #endif
 
 #if defined(MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO) //no-check-names
-#error "MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO (SSL v2 ClientHello support) was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4031"
+#error "MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO (SSL v2 ClientHello support) was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4031"
 #endif
 
 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT) //no-check-names
-#error "MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT (compatibility with the buggy implementation of truncated HMAC in Mbed TLS up to 2.7) was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4031"
+#error "MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT (compatibility with the buggy implementation of truncated HMAC in Mbed TLS up to 2.7) was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4031"
 #endif
 
 #if defined(MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES) //no-check-names
@@ -825,23 +983,23 @@
 #endif
 
 #if defined(MBEDTLS_ZLIB_SUPPORT) //no-check-names
-#error "MBEDTLS_ZLIB_SUPPORT was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4031"
+#error "MBEDTLS_ZLIB_SUPPORT was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4031"
 #endif
 
 #if defined(MBEDTLS_CHECK_PARAMS) //no-check-names
-#error "MBEDTLS_CHECK_PARAMS was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4313"
+#error "MBEDTLS_CHECK_PARAMS was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4313"
 #endif
 
 #if defined(MBEDTLS_SSL_CID_PADDING_GRANULARITY) //no-check-names
-#error "MBEDTLS_SSL_CID_PADDING_GRANULARITY was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4335"
+#error "MBEDTLS_SSL_CID_PADDING_GRANULARITY was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4335"
 #endif
 
 #if defined(MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY) //no-check-names
-#error "MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4335"
+#error "MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4335"
 #endif
 
 #if defined(MBEDTLS_SSL_TRUNCATED_HMAC) //no-check-names
-#error "MBEDTLS_SSL_TRUNCATED_HMAC was removed in Mbed TLS 3.0. See https://github.com/ARMmbed/mbedtls/issues/4341"
+#error "MBEDTLS_SSL_TRUNCATED_HMAC was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4341"
 #endif
 
 /*

include/mbedtls/cipher.h

@@ -630,10 +630,16 @@ int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx,
                           const mbedtls_cipher_info_t *cipher_info );
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 /**
  * \brief               This function initializes a cipher context for
  *                      PSA-based use with the given cipher primitive.
  *
+ * \deprecated          This function is deprecated and will be removed in a
+ *                      future version of the library.
+ *                      Please use psa_aead_xxx() / psa_cipher_xxx() directly
+ *                      instead.
+ *
  * \note                See #MBEDTLS_USE_PSA_CRYPTO for information on PSA.
  *
  * \param ctx           The context to initialize. May not be \c NULL.
@@ -651,9 +657,9 @@ int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx,
  * \return              #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
  *                      cipher-specific context fails.
  */
-int mbedtls_cipher_setup_psa( mbedtls_cipher_context_t *ctx,
+int MBEDTLS_DEPRECATED mbedtls_cipher_setup_psa( mbedtls_cipher_context_t *ctx,
-                              const mbedtls_cipher_info_t *cipher_info,
+    const mbedtls_cipher_info_t *cipher_info, size_t taglen );
-                              size_t taglen );
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
 /**
@@ -844,6 +850,12 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx,
  * \note            Some ciphers do not use IVs nor nonce. For these
  *                  ciphers, this function has no effect.
  *
+ * \note            For #MBEDTLS_CIPHER_CHACHA20, the nonce length must
+ *                  be 12, and the initial counter value is 0.
+ *
+ * \note            For #MBEDTLS_CIPHER_CHACHA20_POLY1305, the nonce length
+ *                  must be 12.
+ *
  * \param ctx       The generic cipher context. This must be initialized and
  *                  bound to a cipher information structure.
  * \param iv        The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This

include/mbedtls/config_psa.h

@@ -31,9 +31,17 @@
 #define MBEDTLS_CONFIG_PSA_H
 
 #if defined(MBEDTLS_PSA_CRYPTO_CONFIG)
+#if defined(MBEDTLS_PSA_CRYPTO_CONFIG_FILE)
+#include MBEDTLS_PSA_CRYPTO_CONFIG_FILE
+#else
 #include "psa/crypto_config.h"
+#endif
 #endif /* defined(MBEDTLS_PSA_CRYPTO_CONFIG) */
 
+#if defined(MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE)
+#include MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -50,6 +58,12 @@ extern "C" {
 #define PSA_WANT_ALG_ECDSA_ANY PSA_WANT_ALG_ECDSA
 #endif
 
+#if defined(PSA_WANT_ALG_CCM_STAR_NO_TAG) && !defined(PSA_WANT_ALG_CCM)
+#define PSA_WANT_ALG_CCM PSA_WANT_ALG_CCM_STAR_NO_TAG
+#elif !defined(PSA_WANT_ALG_CCM_STAR_NO_TAG) && defined(PSA_WANT_ALG_CCM)
+#define PSA_WANT_ALG_CCM_STAR_NO_TAG PSA_WANT_ALG_CCM
+#endif
+
 #if defined(PSA_WANT_ALG_RSA_PKCS1V15_SIGN_RAW) && !defined(PSA_WANT_ALG_RSA_PKCS1V15_SIGN)
 #define PSA_WANT_ALG_RSA_PKCS1V15_SIGN PSA_WANT_ALG_RSA_PKCS1V15_SIGN_RAW
 #elif !defined(PSA_WANT_ALG_RSA_PKCS1V15_SIGN_RAW) && defined(PSA_WANT_ALG_RSA_PKCS1V15_SIGN)
@@ -107,6 +121,20 @@ extern "C" {
 #endif /* !MBEDTLS_PSA_ACCEL_ALG_HKDF */
 #endif /* PSA_WANT_ALG_HKDF */
 
+#if defined(PSA_WANT_ALG_HKDF_EXTRACT)
+#if !defined(MBEDTLS_PSA_ACCEL_ALG_HKDF_EXTRACT)
+#define MBEDTLS_PSA_BUILTIN_ALG_HMAC 1
+#define MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXTRACT 1
+#endif /* !MBEDTLS_PSA_ACCEL_ALG_HKDF_EXTRACT */
+#endif /* PSA_WANT_ALG_HKDF_EXTRACT */
+
+#if defined(PSA_WANT_ALG_HKDF_EXPAND)
+#if !defined(MBEDTLS_PSA_ACCEL_ALG_HKDF_EXPAND)
+#define MBEDTLS_PSA_BUILTIN_ALG_HMAC 1
+#define MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXPAND 1
+#endif /* !MBEDTLS_PSA_ACCEL_ALG_HKDF_EXPAND */
+#endif /* PSA_WANT_ALG_HKDF_EXPAND */
+
 #if defined(PSA_WANT_ALG_HMAC)
 #if !defined(MBEDTLS_PSA_ACCEL_ALG_HMAC)
 #define MBEDTLS_PSA_BUILTIN_ALG_HMAC 1
@@ -118,6 +146,15 @@ extern "C" {
 #define MBEDTLS_MD5_C
 #endif
 
+#if defined(PSA_WANT_ALG_JPAKE)
+#define MBEDTLS_PSA_BUILTIN_PAKE 1
+#define MBEDTLS_PSA_BUILTIN_ALG_JPAKE 1
+#define MBEDTLS_ECP_DP_SECP256R1_ENABLED
+#define MBEDTLS_BIGNUM_C
+#define MBEDTLS_ECP_C
+#define MBEDTLS_ECJPAKE_C
+#endif /* PSA_WANT_ALG_JPAKE */
+
 #if defined(PSA_WANT_ALG_RIPEMD160) && !defined(MBEDTLS_PSA_ACCEL_ALG_RIPEMD160)
 #define MBEDTLS_PSA_BUILTIN_ALG_RIPEMD160 1
 #define MBEDTLS_RIPEMD160_C
@@ -130,7 +167,6 @@ extern "C" {
 #define MBEDTLS_BIGNUM_C
 #define MBEDTLS_OID_C
 #define MBEDTLS_PKCS1_V21
-#define MBEDTLS_MD_C
 #endif /* !MBEDTLS_PSA_ACCEL_ALG_RSA_OAEP */
 #endif /* PSA_WANT_ALG_RSA_OAEP */
 
@@ -151,7 +187,6 @@ extern "C" {
 #define MBEDTLS_BIGNUM_C
 #define MBEDTLS_OID_C
 #define MBEDTLS_PKCS1_V15
-#define MBEDTLS_MD_C
 #endif /* !MBEDTLS_PSA_ACCEL_ALG_RSA_PKCS1V15_SIGN */
 #endif /* PSA_WANT_ALG_RSA_PKCS1V15_SIGN */
 
@@ -162,7 +197,6 @@ extern "C" {
 #define MBEDTLS_BIGNUM_C
 #define MBEDTLS_OID_C
 #define MBEDTLS_PKCS1_V21
-#define MBEDTLS_MD_C
 #endif /* !MBEDTLS_PSA_ACCEL_ALG_RSA_PSS */
 #endif /* PSA_WANT_ALG_RSA_PSS */
 
@@ -254,7 +288,6 @@ extern "C" {
 #if (defined(PSA_WANT_ALG_CTR) && !defined(MBEDTLS_PSA_ACCEL_ALG_CTR)) || \
     (defined(PSA_WANT_ALG_CFB) && !defined(MBEDTLS_PSA_ACCEL_ALG_CFB)) || \
     (defined(PSA_WANT_ALG_OFB) && !defined(MBEDTLS_PSA_ACCEL_ALG_OFB)) || \
-    (defined(PSA_WANT_ALG_XTS) && !defined(MBEDTLS_PSA_ACCEL_ALG_XTS)) || \
     defined(PSA_WANT_ALG_ECB_NO_PADDING) || \
     (defined(PSA_WANT_ALG_CBC_NO_PADDING) && \
      !defined(MBEDTLS_PSA_ACCEL_ALG_CBC_NO_PADDING)) || \
@@ -376,15 +409,8 @@ extern "C" {
 #endif
 #endif /* PSA_WANT_ALG_OFB */
 
-#if defined(PSA_WANT_ALG_XTS)
+#if defined(PSA_WANT_ALG_ECB_NO_PADDING) &&     \
-#if !defined(MBEDTLS_PSA_ACCEL_ALG_XTS) || \
+    !defined(MBEDTLS_PSA_ACCEL_ALG_ECB_NO_PADDING)
-    defined(PSA_HAVE_SOFT_BLOCK_CIPHER)
-#define MBEDTLS_PSA_BUILTIN_ALG_XTS 1
-#define MBEDTLS_CIPHER_MODE_XTS
-#endif
-#endif /* PSA_WANT_ALG_XTS */
-
-#if defined(PSA_WANT_ALG_ECB_NO_PADDING)
 #define MBEDTLS_PSA_BUILTIN_ALG_ECB_NO_PADDING 1
 #endif
 
@@ -411,6 +437,7 @@ extern "C" {
     defined(PSA_HAVE_SOFT_KEY_TYPE_ARIA) || \
     defined(PSA_HAVE_SOFT_KEY_TYPE_CAMELLIA)
 #define MBEDTLS_PSA_BUILTIN_ALG_CCM 1
+#define MBEDTLS_PSA_BUILTIN_ALG_CCM_STAR_NO_TAG 1
 #define MBEDTLS_CCM_C
 #endif
 #endif /* PSA_WANT_ALG_CCM */
@@ -429,6 +456,8 @@ extern "C" {
 #if !defined(MBEDTLS_PSA_ACCEL_ALG_CHACHA20_POLY1305)
 #if defined(PSA_WANT_KEY_TYPE_CHACHA20)
 #define MBEDTLS_CHACHAPOLY_C
+#define MBEDTLS_CHACHA20_C
+#define MBEDTLS_POLY1305_C
 #define MBEDTLS_PSA_BUILTIN_ALG_CHACHA20_POLY1305 1
 #endif /* PSA_WANT_KEY_TYPE_CHACHA20 */
 #endif /* !MBEDTLS_PSA_ACCEL_ALG_CHACHA20_POLY1305 */
@@ -515,7 +544,7 @@ extern "C" {
 #if !defined(MBEDTLS_PSA_ACCEL_ECC_SECP_K1_224)
 /*
  * SECP224K1 is buggy via the PSA API in Mbed TLS
- * (https://github.com/ARMmbed/mbedtls/issues/3541).
+ * (https://github.com/Mbed-TLS/mbedtls/issues/3541).
  */
 #error "SECP224K1 is buggy via the PSA API in Mbed TLS."
 #define MBEDTLS_ECP_DP_SECP224K1_ENABLED
@@ -545,7 +574,9 @@ extern "C" {
 
 #if defined(MBEDTLS_CCM_C)
 #define MBEDTLS_PSA_BUILTIN_ALG_CCM 1
+#define MBEDTLS_PSA_BUILTIN_ALG_CCM_STAR_NO_TAG 1
 #define PSA_WANT_ALG_CCM 1
+#define PSA_WANT_ALG_CCM_STAR_NO_TAG 1
 #endif /* MBEDTLS_CCM_C */
 
 #if defined(MBEDTLS_CMAC_C)
@@ -583,17 +614,26 @@ extern "C" {
 #define PSA_WANT_ALG_GCM 1
 #endif /* MBEDTLS_GCM_C */
 
+/* Enable PSA HKDF algorithm if mbedtls HKDF is supported.
+ * PSA HKDF EXTRACT and PSA HKDF EXPAND have minimal cost when
+ * PSA HKDF is enabled, so enable both algorithms together
+ * with PSA HKDF. */
 #if defined(MBEDTLS_HKDF_C)
 #define MBEDTLS_PSA_BUILTIN_ALG_HMAC 1
 #define PSA_WANT_ALG_HMAC 1
 #define MBEDTLS_PSA_BUILTIN_ALG_HKDF 1
 #define PSA_WANT_ALG_HKDF 1
+#define MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXTRACT 1
+#define PSA_WANT_ALG_HKDF_EXTRACT 1
+#define MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXPAND 1
+#define PSA_WANT_ALG_HKDF_EXPAND 1
 #endif /* MBEDTLS_HKDF_C */
 
-#if defined(MBEDTLS_MD_C)
 #define MBEDTLS_PSA_BUILTIN_ALG_HMAC 1
 #define PSA_WANT_ALG_HMAC 1
 #define PSA_WANT_KEY_TYPE_HMAC
+
+#if defined(MBEDTLS_MD_C)
 #define MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF 1
 #define PSA_WANT_ALG_TLS12_PRF 1
 #define MBEDTLS_PSA_BUILTIN_ALG_TLS12_PSK_TO_MS 1
@@ -605,6 +645,12 @@ extern "C" {
 #define PSA_WANT_ALG_MD5 1
 #endif
 
+#if defined(MBEDTLS_ECJPAKE_C)
+#define MBEDTLS_PSA_BUILTIN_PAKE 1
+#define MBEDTLS_PSA_BUILTIN_ALG_JPAKE 1
+#define PSA_WANT_ALG_JPAKE 1
+#endif
+
 #if defined(MBEDTLS_RIPEMD160_C)
 #define MBEDTLS_PSA_BUILTIN_ALG_RIPEMD160 1
 #define PSA_WANT_ALG_RIPEMD160 1
@@ -716,11 +762,6 @@ extern "C" {
 #define PSA_WANT_ALG_OFB 1
 #endif
 
-#if defined(MBEDTLS_CIPHER_MODE_XTS)
-#define MBEDTLS_PSA_BUILTIN_ALG_XTS 1
-#define PSA_WANT_ALG_XTS 1
-#endif
-
 #if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
 #define MBEDTLS_PSA_BUILTIN_ECC_BRAINPOOL_P_R1_256 1
 #define PSA_WANT_ECC_BRAINPOOL_P_R1_256
@@ -776,7 +817,7 @@ extern "C" {
 #define PSA_WANT_ECC_SECP_K1_192
 #endif
 
-/* SECP224K1 is buggy via the PSA API (https://github.com/ARMmbed/mbedtls/issues/3541) */
+/* SECP224K1 is buggy via the PSA API (https://github.com/Mbed-TLS/mbedtls/issues/3541) */
 #if 0 && defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
 #define MBEDTLS_PSA_BUILTIN_ECC_SECP_K1_224 1
 #define PSA_WANT_ECC_SECP_K1_224

include/mbedtls/debug.h

@@ -139,7 +139,7 @@ extern "C" {
  *          discarded.
  *          (Default value: 0 = No debug )
  *
- * \param threshold     theshold level of messages to filter on. Messages at a
+ * \param threshold     threshold level of messages to filter on. Messages at a
  *                      higher level will be discarded.
  *                          - Debug levels
  *                              - 0 No debug

include/mbedtls/ecjpake.h

@@ -65,12 +65,12 @@ typedef enum {
  * (KeyExchange) as defined by the Thread spec.
  *
  * In order to benefit from this symmetry, we choose a different naming
- * convetion from the Thread v1.0 spec. Correspondance is indicated in the
+ * convention from the Thread v1.0 spec. Correspondence is indicated in the
  * description as a pair C: client name, S: server name
  */
 typedef struct mbedtls_ecjpake_context
 {
-    const mbedtls_md_info_t *MBEDTLS_PRIVATE(md_info);   /**< Hash to use                    */
+    mbedtls_md_type_t MBEDTLS_PRIVATE(md_type);          /**< Hash to use                    */
     mbedtls_ecp_group MBEDTLS_PRIVATE(grp);              /**< Elliptic curve                 */
     mbedtls_ecjpake_role MBEDTLS_PRIVATE(role);          /**< Are we client or server?       */
     int MBEDTLS_PRIVATE(point_format);                   /**< Format for point export        */
@@ -258,6 +258,29 @@ int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
                             void *p_rng );
 
+/**
+ * \brief           Write the shared key material to be passed to a Key
+ *                  Derivation Function as described in RFC8236.
+ *
+ * \param ctx       The ECJPAKE context to use. This must be initialized,
+ *                  set up and have performed both round one and two.
+ * \param buf       The buffer to write the derived secret to. This must
+ *                  be a writable buffer of length \p len Bytes.
+ * \param len       The length of \p buf in Bytes.
+ * \param olen      The address at which to store the total number of bytes
+ *                  written to \p buf. This must not be \c NULL.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG parameter to be passed to \p f_rng. This
+ *                  may be \c NULL if \p f_rng doesn't use a context.
+ *
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
+ */
+int mbedtls_ecjpake_write_shared_key( mbedtls_ecjpake_context *ctx,
+                            unsigned char *buf, size_t len, size_t *olen,
+                            int (*f_rng)(void *, unsigned char *, size_t),
+                            void *p_rng );
+
 /**
  * \brief           This clears an ECJPAKE context and frees any
  *                  embedded data structure.

include/mbedtls/ecp.h

@@ -262,7 +262,7 @@ mbedtls_ecp_group;
 #if !defined(MBEDTLS_ECP_WINDOW_SIZE)
 /*
  * Maximum "window" size used for point multiplication.
- * Default: a point where higher memory usage yields disminishing performance
+ * Default: a point where higher memory usage yields diminishing performance
  *          returns.
  * Minimum value: 2. Maximum value: 7.
  *
@@ -918,7 +918,7 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
  * \note            To prevent timing attacks, this function
  *                  executes the exact same sequence of base-field
  *                  operations for any valid \p m. It avoids any if-branch or
- *                  array index depending on the value of \p m. If also uses
+ *                  array index depending on the value of \p m. It also uses
  *                  \p f_rng to randomize some intermediate results.
  *
  * \param grp       The ECP group to use.
@@ -1278,6 +1278,26 @@ int mbedtls_ecp_check_pub_priv(
         const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv,
         int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
+/**
+ * \brief           This function exports generic key-pair parameters.
+ *
+ * \param key       The key pair to export from.
+ * \param grp       Slot for exported ECP group.
+ *                  It must point to an initialized ECP group.
+ * \param d         Slot for the exported secret value.
+ *                  It must point to an initialized mpi.
+ * \param Q         Slot for the exported public value.
+ *                  It must point to an initialized ECP point.
+ *
+ * \return          \c 0 on success,
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if key id doesn't
+ *                  correspond to a known group.
+ * \return          Another negative error code on other kinds of failure.
+ */
+int mbedtls_ecp_export(const mbedtls_ecp_keypair *key, mbedtls_ecp_group *grp,
+                       mbedtls_mpi *d, mbedtls_ecp_point *Q);
+
 #if defined(MBEDTLS_SELF_TEST)
 
 /**

include/mbedtls/hmac_drbg.h

@@ -204,7 +204,7 @@ int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
                     size_t len );
 
 /**
- * \brief               Initilisation of simpified HMAC_DRBG (never reseeds).
+ * \brief               Initialisation of simplified HMAC_DRBG (never reseeds).
  *
  * This function is meant for use in algorithms that need a pseudorandom
  * input such as deterministic ECDSA.

include/mbedtls/mbedtls_config.h

@@ -25,7 +25,7 @@
  */
 
 /**
- * This is an optional version symbol that enables comatibility handling of
+ * This is an optional version symbol that enables compatibility handling of
  * config files.
  *
  * It is equal to the #MBEDTLS_VERSION_NUMBER of the Mbed TLS version that
@@ -129,7 +129,12 @@
  * MBEDTLS_PLATFORM_TIME_MACRO, MBEDTLS_PLATFORM_TIME_TYPE_MACRO and
  * MBEDTLS_PLATFORM_STD_TIME.
  *
- * Comment if your system does not support time functions
+ * Comment if your system does not support time functions.
+ *
+ * \note If MBEDTLS_TIMING_C is set - to enable the semi-portable timing
+ *       interface - timing.c will include time.h on suitable platforms
+ *       regardless of the setting of MBEDTLS_HAVE_TIME, unless
+ *       MBEDTLS_TIMING_ALT is used. See timing.c for more information.
  */
 #define MBEDTLS_HAVE_TIME
 
@@ -220,6 +225,7 @@
  * Uncomment a macro to enable alternate implementation of specific base
  * platform function
  */
+//#define MBEDTLS_PLATFORM_SETBUF_ALT
 //#define MBEDTLS_PLATFORM_EXIT_ALT
 //#define MBEDTLS_PLATFORM_TIME_ALT
 //#define MBEDTLS_PLATFORM_FPRINTF_ALT
@@ -325,7 +331,7 @@
 //#define MBEDTLS_SHA512_ALT
 
 /*
- * When replacing the elliptic curve module, pleace consider, that it is
+ * When replacing the elliptic curve module, please consider, that it is
  * implemented with two .c files:
  *      - ecp.c
  *      - ecp_curves.c
@@ -1104,7 +1110,7 @@
  * Include backtrace information with each allocated block.
  *
  * Requires: MBEDTLS_MEMORY_BUFFER_ALLOC_C
- *           GLIBC-compatible backtrace() an backtrace_symbols() support
+ *           GLIBC-compatible backtrace() and backtrace_symbols() support
  *
  * Uncomment this macro to include backtrace information
  */
@@ -1124,7 +1130,7 @@
  *
  * Enable support for PKCS#1 v1.5 encoding.
  *
- * Requires: MBEDTLS_RSA_C
+ * Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C
  *
  * This enables support for PKCS#1 v1.5 operations.
  */
@@ -1135,7 +1141,10 @@
  *
  * Enable support for PKCS#1 v2.1 encoding.
  *
- * Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C
+ * Requires: MBEDTLS_RSA_C and (MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C).
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any PKCS#1 v2.1 operation.
  *
  * This enables support for RSAES-OAEP and RSASSA-PSS operations.
  */
@@ -1179,8 +1188,9 @@
  *
  * Requires: MBEDTLS_PSA_CRYPTO_C
  *
- * \warning This interface is experimental and may change or be removed
+ * \warning This interface is experimental. We intend to maintain backward
- * without notice.
+ *          compatibility with application code that relies on drivers,
+ *          but the driver interfaces may change without notice.
  */
 //#define MBEDTLS_PSA_CRYPTO_DRIVERS
 
@@ -1273,7 +1283,7 @@
  * Enable an implementation of SHA-256 that has lower ROM footprint but also
  * lower performance.
  *
- * The default implementation is meant to be a reasonnable compromise between
+ * The default implementation is meant to be a reasonable compromise between
  * performance and size. This version optimizes more aggressively for size at
  * the expense of performance. Eg on Cortex-M4 it reduces the size of
  * mbedtls_sha256_process() from ~2KB to ~0.5KB for a performance hit of about
@@ -1317,8 +1327,9 @@
  * in the underlying transport.
  *
  * Setting this option enables the SSL APIs `mbedtls_ssl_set_cid()`,
- * `mbedtls_ssl_get_peer_cid()` and `mbedtls_ssl_conf_cid()`.
+ * mbedtls_ssl_get_own_cid()`, `mbedtls_ssl_get_peer_cid()` and
- * See the corresponding documentation for more information.
+ * `mbedtls_ssl_conf_cid()`. See the corresponding documentation for
+ * more information.
  *
  * \warning The Connection ID extension is still in draft state.
  *          We make no stability promises for the availability
@@ -1410,7 +1421,7 @@
  * Enable support for RFC 7627: Session Hash and Extended Master Secret
  * Extension.
  *
- * This was introduced as "the proper fix" to the Triple Handshake familiy of
+ * This was introduced as "the proper fix" to the Triple Handshake family of
  * attacks, but it is recommended to always use it (even if you disable
  * renegotiation), since it actually fixes a more fundamental issue in the
  * original SSL/TLS design, and has implications beyond Triple Handshake.
@@ -1436,7 +1447,9 @@
  * \note This option has no influence on the protection against the
  *       triple handshake attack. Even if it is disabled, Mbed TLS will
  *       still ensure that certificates do not change during renegotiation,
- *       for exaple by keeping a hash of the peer's certificate.
+ *       for example by keeping a hash of the peer's certificate.
+ *
+ * \note This option is required if MBEDTLS_SSL_PROTO_TLS1_3 is set.
  *
  * Comment this macro to disable storing the peer's certificate
  * after the handshake.
@@ -1480,7 +1493,12 @@
  * Enable support for TLS 1.2 (and DTLS 1.2 if DTLS is enabled).
  *
  * Requires: MBEDTLS_SHA1_C or MBEDTLS_SHA256_C or MBEDTLS_SHA512_C
- *           (Depends on ciphersuites)
+ *           (Depends on ciphersuites) when MBEDTLS_USE_PSA_CRYPTO
+ *           is not defined, PSA_WANT_ALG_SHA_1 or PSA_WANT_ALG_SHA_256 or
+ *           PSA_WANT_ALG_SHA_512 when MBEDTLS_USE_PSA_CRYPTO is defined.
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any TLS operation.
  *
  * Comment this macro to disable support for TLS 1.2 / DTLS 1.2
  */
@@ -1496,8 +1514,16 @@
  *       See docs/architecture/tls13-support.md for a description of the TLS
  *       1.3 support that this option enables.
  *
- * Uncomment this macro to enable the support for TLS 1.3.
+ * Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+ * Requires: MBEDTLS_PSA_CRYPTO_C
  *
+ * Note: even though TLS 1.3 depends on PSA Crypto, if you want it to only use
+ * PSA for all crypto operations, you need to also enable
+ * MBEDTLS_USE_PSA_CRYPTO; otherwise X.509 operations, and functions that are
+ * common with TLS 1.2 (record protection, running handshake hash) will still
+ * use non-PSA crypto.
+ *
+ * Uncomment this macro to enable the support for TLS 1.3.
  */
 //#define MBEDTLS_SSL_PROTO_TLS1_3
 
@@ -1523,6 +1549,15 @@
  */
 //#define MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE
 
+/**
+ * \def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH
+ *
+ * Size in bytes of a ticket nonce. This is not used in TLS 1.2.
+ *
+ * This must be less than 256.
+ */
+#define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32
+
 /**
  * \def MBEDTLS_SSL_PROTO_DTLS
  *
@@ -1570,7 +1605,7 @@
  * unless you know for sure amplification cannot be a problem in the
  * environment in which your server operates.
  *
- * \warning Disabling this can ba a security risk! (see above)
+ * \warning Disabling this can be a security risk! (see above)
  *
  * Requires: MBEDTLS_SSL_PROTO_DTLS
  *
@@ -1752,12 +1787,11 @@
  * \note See docs/use-psa-crypto.md for a complete description of what this
  * option currently does, and of parts that are not affected by it so far.
  *
- * \warning This option enables new Mbed TLS APIs which are currently
+ * \warning If you enable this option, you need to call `psa_crypto_init()`
- * considered experimental and may change in incompatible ways at any time.
+ * before calling any function from the SSL/TLS, X.509 or PK modules.
- * That is, the APIs enabled by this option are not covered by the usual
- * promises of API stability.
  *
  * Requires: MBEDTLS_PSA_CRYPTO_C.
+ * Conflicts with: MBEDTLS_ECP_RESTARTABLE
  *
  * Uncomment this to enable internal use of PSA Crypto and new associated APIs.
  */
@@ -1769,8 +1803,19 @@
  * This setting allows support for cryptographic mechanisms through the PSA
  * API to be configured separately from support through the mbedtls API.
  *
- * Uncomment this to enable use of PSA Crypto configuration settings which
+ * When this option is disabled, the PSA API exposes the cryptographic
- * can be found in include/psa/crypto_config.h.
+ * mechanisms that can be implemented on top of the `mbedtls_xxx` API
+ * configured with `MBEDTLS_XXX` symbols.
+ *
+ * When this option is enabled, the PSA API exposes the cryptographic
+ * mechanisms requested by the `PSA_WANT_XXX` symbols defined in
+ * include/psa/crypto_config.h. The corresponding `MBEDTLS_XXX` settings are
+ * automatically enabled if required (i.e. if no PSA driver provides the
+ * mechanism). You may still freely enable additional `MBEDTLS_XXX` symbols
+ * in mbedtls_config.h.
+ *
+ * If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies
+ * an alternative header to include instead of include/psa/crypto_config.h.
  *
  * This feature is still experimental and is not ready for production since
  * it is not completed.
@@ -1973,6 +2018,9 @@
  * Enable the multi-precision integer library.
  *
  * Module:  library/bignum.c
+ *          library/bignum_core.c
+ *          library/bignum_mod.c
+ *          library/bignum_mod_raw.c
  * Caller:  library/dhm.c
  *          library/ecp.c
  *          library/ecdsa.c
@@ -2098,7 +2146,8 @@
  *
  * Module:  library/ccm.c
  *
- * Requires: MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C
+ * Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or
+ *                             MBEDTLS_ARIA_C
  *
  * This module enables the AES-CCM ciphersuites, if other requisites are
  * enabled as well.
@@ -2131,7 +2180,17 @@
  * Enable the generic cipher layer.
  *
  * Module:  library/cipher.c
- * Caller:  library/ssl_tls.c
+ * Caller:  library/ccm.c
+ *          library/cmac.c
+ *          library/gcm.c
+ *          library/nist_kw.c
+ *          library/pkcs12.c
+ *          library/pkcs5.c
+ *          library/psa_crypto_aead.c
+ *          library/psa_crypto_mac.c
+ *          library/ssl_ciphersuites.c
+ *          library/ssl_msg.c
+ *          library/ssl_ticket.c (unless MBEDTLS_USE_PSA_CRYPTO is enabled)
  *
  * Uncomment to enable generic cipher wrappers.
  */
@@ -2150,7 +2209,7 @@
  *
  * Module:  library/cmac.c
  *
- * Requires: MBEDTLS_AES_C or MBEDTLS_DES_C
+ * Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_DES_C
  *
  */
 #define MBEDTLS_CMAC_C
@@ -2181,9 +2240,10 @@
  * Enable the debug functions.
  *
  * Module:  library/debug.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/ssl_msg.c
- *          library/ssl_srv.c
  *          library/ssl_tls.c
+ *          library/ssl_tls12_*.c
+ *          library/ssl_tls13_*.c
  *
  * This module provides debugging functions.
  */
@@ -2211,8 +2271,9 @@
  * Enable the Diffie-Hellman-Merkle module.
  *
  * Module:  library/dhm.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/ssl_tls.c
- *          library/ssl_srv.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
  *
  * This module is used by the following key exchanges:
  *      DHE-RSA, DHE-PSK
@@ -2232,8 +2293,10 @@
  * Enable the elliptic curve Diffie-Hellman library.
  *
  * Module:  library/ecdh.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/psa_crypto.c
- *          library/ssl_srv.c
+ *          library/ssl_tls.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
  *
  * This module is used by the following key exchanges:
  *      ECDHE-ECDSA, ECDHE-RSA, DHE-PSK
@@ -2275,6 +2338,9 @@
  *      ECJPAKE
  *
  * Requires: MBEDTLS_ECP_C, MBEDTLS_MD_C
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any EC J-PAKE operations.
  */
 #define MBEDTLS_ECJPAKE_C
 
@@ -2325,7 +2391,8 @@
  *
  * Module:  library/gcm.c
  *
- * Requires: MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or MBEDTLS_ARIA_C
+ * Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or
+ *                             MBEDTLS_ARIA_C
  *
  * This module enables the AES-GCM and CAMELLIA-GCM ciphersuites, if other
  * requisites are enabled as well.
@@ -2357,7 +2424,7 @@
  *
  * Requires: MBEDTLS_MD_C
  *
- * Uncomment to enable the HMAC_DRBG random number geerator.
+ * Uncomment to enable the HMAC_DRBG random number generator.
  */
 #define MBEDTLS_HMAC_DRBG_C
 
@@ -2379,8 +2446,28 @@
  *
  * Enable the generic message digest layer.
  *
+ * Requires: one of: MBEDTLS_MD5_C, MBEDTLS_RIPEMD160_C, MBEDTLS_SHA1_C,
+ *                   MBEDTLS_SHA224_C, MBEDTLS_SHA256_C, MBEDTLS_SHA384_C,
+ *                   MBEDTLS_SHA512_C.
  * Module:  library/md.c
- * Caller:
+ * Caller:  library/constant_time.c
+ *          library/ecdsa.c
+ *          library/ecjpake.c
+ *          library/hkdf.c
+ *          library/hmac_drbg.c
+ *          library/pk.c
+ *          library/pkcs5.c
+ *          library/pkcs12.c
+ *          library/psa_crypto_ecp.c
+ *          library/psa_crypto_rsa.c
+ *          library/rsa.c
+ *          library/ssl_cookie.c
+ *          library/ssl_msg.c
+ *          library/ssl_tls.c
+ *          library/x509.c
+ *          library/x509_crt.c
+ *          library/x509write_crt.c
+ *          library/x509write_csr.c
  *
  * Uncomment to enable generic message digest wrappers.
  */
@@ -2516,14 +2603,16 @@
 /**
  * \def MBEDTLS_PK_C
  *
- * Enable the generic public (asymetric) key layer.
+ * Enable the generic public (asymmetric) key layer.
  *
  * Module:  library/pk.c
- * Caller:  library/ssl_tls.c
+ * Caller:  library/psa_crypto_rsa.c
- *          library/ssl_cli.c
+ *          library/ssl_tls.c
- *          library/ssl_srv.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
+ *          library/x509.c
  *
- * Requires: MBEDTLS_RSA_C or MBEDTLS_ECP_C
+ * Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C or MBEDTLS_ECP_C
  *
  * Uncomment to enable generic public key wrappers.
  */
@@ -2532,7 +2621,7 @@
 /**
  * \def MBEDTLS_PK_PARSE_C
  *
- * Enable the generic public (asymetric) key parser.
+ * Enable the generic public (asymmetric) key parser.
  *
  * Module:  library/pkparse.c
  * Caller:  library/x509_crt.c
@@ -2547,7 +2636,7 @@
 /**
  * \def MBEDTLS_PK_WRITE_C
  *
- * Enable the generic public (asymetric) key writer.
+ * Enable the generic public (asymmetric) key writer.
  *
  * Module:  library/pkwrite.c
  * Caller:  library/x509write.c
@@ -2565,7 +2654,7 @@
  *
  * Module:  library/pkcs5.c
  *
- * Requires: MBEDTLS_MD_C
+ * Requires: MBEDTLS_CIPHER_C, MBEDTLS_MD_C
  *
  * This module adds support for the PKCS#5 functions.
  */
@@ -2580,7 +2669,11 @@
  * Module:  library/pkcs12.c
  * Caller:  library/pkparse.c
  *
- * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_CIPHER_C, MBEDTLS_MD_C
+ * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_CIPHER_C and either
+ * MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C.
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any PKCS12 operation.
  *
  * This module enables PKCS#12 functions.
  */
@@ -2597,7 +2690,7 @@
  * above to be specified at runtime or compile time respectively.
  *
  * \note This abstraction layer must be enabled on Windows (including MSYS2)
- * as other module rely on it for a fixed snprintf implementation.
+ * as other modules rely on it for a fixed snprintf implementation.
  *
  * Module:  library/platform.c
  * Caller:  Most other .c files
@@ -2623,7 +2716,8 @@
  *
  * Module:  library/psa_crypto.c
  *
- * Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C,
+ * Requires: MBEDTLS_CIPHER_C,
+ *           either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C,
  *           or MBEDTLS_HMAC_DRBG_C and MBEDTLS_ENTROPY_C,
  *           or MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.
  *
@@ -2633,11 +2727,11 @@
 /**
  * \def MBEDTLS_PSA_CRYPTO_SE_C
  *
- * Enable secure element support in the Platform Security Architecture
+ * Enable dynamic secure element support in the Platform Security Architecture
  * cryptography API.
  *
- * \warning This feature is not yet suitable for production. It is provided
+ * \deprecated This feature is deprecated. Please switch to the driver
- *          for API evaluation and testing purposes only.
+ *             interface enabled by #MBEDTLS_PSA_CRYPTO_DRIVERS.
  *
  * Module:  library/psa_crypto_se.c
  *
@@ -2689,10 +2783,11 @@
  *
  * Module:  library/rsa.c
  *          library/rsa_alt_helpers.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/pk.c
- *          library/ssl_srv.c
+ *          library/psa_crypto.c
  *          library/ssl_tls.c
- *          library/x509.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
  *
  * This module is used by the following key exchanges:
  *      RSA, DHE-RSA, ECDHE-RSA, RSA-PSK
@@ -2708,10 +2803,7 @@
  *
  * Module:  library/sha1.c
  * Caller:  library/md.c
- *          library/ssl_cli.c
+ *          library/psa_crypto_hash.c
- *          library/ssl_srv.c
- *          library/ssl_tls.c
- *          library/x509write_crt.c
  *
  * This module is required for TLS 1.2 depending on the handshake parameters,
  * and for SHA1-signed certificates.
@@ -2750,15 +2842,65 @@
  * Module:  library/sha256.c
  * Caller:  library/entropy.c
  *          library/md.c
- *          library/ssl_cli.c
- *          library/ssl_srv.c
  *          library/ssl_tls.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
  *
  * This module adds support for SHA-256.
  * This module is required for the SSL/TLS 1.2 PRF function.
  */
 #define MBEDTLS_SHA256_C
 
+/**
+ * \def MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT
+ *
+ * Enable acceleration of the SHA-256 and SHA-224 cryptographic hash algorithms
+ * with the ARMv8 cryptographic extensions if they are available at runtime.
+ * If not, the library will fall back to the C implementation.
+ *
+ * \note If MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT is defined when building
+ * for a non-Aarch64 build it will be silently ignored.
+ *
+ * \note The code uses Neon intrinsics, so \c CFLAGS must be set to a minimum
+ * of \c -march=armv8-a+crypto.
+ *
+ * \warning MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the
+ * same time as MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY.
+ *
+ * Requires: MBEDTLS_SHA256_C.
+ *
+ * Module:  library/sha256.c
+ *
+ * Uncomment to have the library check for the A64 SHA-256 crypto extensions
+ * and use them if available.
+ */
+//#define MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT
+
+/**
+ * \def MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY
+ *
+ * Enable acceleration of the SHA-256 and SHA-224 cryptographic hash algorithms
+ * with the ARMv8 cryptographic extensions, which must be available at runtime
+ * or else an illegal instruction fault will occur.
+ *
+ * \note This allows builds with a smaller code size than with
+ * MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT
+ *
+ * \note The code uses Neon intrinsics, so \c CFLAGS must be set to a minimum
+ * of \c -march=armv8-a+crypto.
+ *
+ * \warning MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY cannot be defined at the same
+ * time as MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT.
+ *
+ * Requires: MBEDTLS_SHA256_C.
+ *
+ * Module:  library/sha256.c
+ *
+ * Uncomment to have the library use the A64 SHA-256 crypto extensions
+ * unconditionally.
+ */
+//#define MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY
+
 /**
  * \def MBEDTLS_SHA384_C
  *
@@ -2768,8 +2910,10 @@
  *
  * Module:  library/sha512.c
  * Caller:  library/md.c
- *          library/ssl_cli.c
+ *          library/psa_crypto_hash.c
- *          library/ssl_srv.c
+ *          library/ssl_tls.c
+ *          library/ssl*_client.c
+ *          library/ssl*_server.c
  *
  * Comment to disable SHA-384
  */
@@ -2790,6 +2934,60 @@
  */
 #define MBEDTLS_SHA512_C
 
+/**
+ * \def MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
+ *
+ * Enable acceleration of the SHA-512 and SHA-384 cryptographic hash algorithms
+ * with the ARMv8 cryptographic extensions if they are available at runtime.
+ * If not, the library will fall back to the C implementation.
+ *
+ * \note If MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT is defined when building
+ * for a non-Aarch64 build it will be silently ignored.
+ *
+ * \note The code uses the SHA-512 Neon intrinsics, so requires GCC >= 8 or
+ * Clang >= 7, and \c CFLAGS must be set to a minimum of
+ * \c -march=armv8.2-a+sha3. An optimisation level of \c -O3 generates the
+ * fastest code.
+ *
+ * \warning MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the
+ * same time as MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY.
+ *
+ * Requires: MBEDTLS_SHA512_C.
+ *
+ * Module:  library/sha512.c
+ *
+ * Uncomment to have the library check for the A64 SHA-512 crypto extensions
+ * and use them if available.
+ */
+//#define MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
+
+/**
+ * \def MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY
+ *
+ * Enable acceleration of the SHA-512 and SHA-384 cryptographic hash algorithms
+ * with the ARMv8 cryptographic extensions, which must be available at runtime
+ * or else an illegal instruction fault will occur.
+ *
+ * \note This allows builds with a smaller code size than with
+ * MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
+ *
+ * \note The code uses the SHA-512 Neon intrinsics, so requires GCC >= 8 or
+ * Clang >= 7, and \c CFLAGS must be set to a minimum of
+ * \c -march=armv8.2-a+sha3. An optimisation level of \c -O3 generates the
+ * fastest code.
+ *
+ * \warning MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY cannot be defined at the same
+ * time as MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT.
+ *
+ * Requires: MBEDTLS_SHA512_C.
+ *
+ * Module:  library/sha512.c
+ *
+ * Uncomment to have the library use the A64 SHA-512 crypto extensions
+ * unconditionally.
+ */
+//#define MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY
+
 /**
  * \def MBEDTLS_SSL_CACHE_C
  *
@@ -2820,7 +3018,7 @@
  * Module:  library/ssl_ticket.c
  * Caller:
  *
- * Requires: MBEDTLS_CIPHER_C
+ * Requires: MBEDTLS_CIPHER_C || MBEDTLS_USE_PSA_CRYPTO
  */
 #define MBEDTLS_SSL_TICKET_C
 
@@ -2829,7 +3027,7 @@
  *
  * Enable the SSL/TLS client code.
  *
- * Module:  library/ssl_cli.c
+ * Module:  library/ssl*_client.c
  * Caller:
  *
  * Requires: MBEDTLS_SSL_TLS_C
@@ -2843,7 +3041,7 @@
  *
  * Enable the SSL/TLS server code.
  *
- * Module:  library/ssl_srv.c
+ * Module:  library/ssl*_server.c
  * Caller:
  *
  * Requires: MBEDTLS_SSL_TLS_C
@@ -2858,8 +3056,8 @@
  * Enable the generic SSL/TLS code.
  *
  * Module:  library/ssl_tls.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/ssl*_client.c
- *          library/ssl_srv.c
+ *          library/ssl*_server.c
  *
  * Requires: MBEDTLS_CIPHER_C, MBEDTLS_MD_C
  *           and at least one of the MBEDTLS_SSL_PROTO_XXX defines
@@ -2902,6 +3100,10 @@
  * your own implementation of the whole module by setting
  * \c MBEDTLS_TIMING_ALT in the current file.
  *
+ * \note The timing module will include time.h on suitable platforms
+ *       regardless of the setting of MBEDTLS_HAVE_TIME, unless
+ *       MBEDTLS_TIMING_ALT is used. See timing.c for more information.
+ *
  * \note See also our Knowledge Base article about porting to a new
  * environment:
  * https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS
@@ -2931,8 +3133,11 @@
  *          library/x509_crt.c
  *          library/x509_csr.c
  *
- * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_BIGNUM_C, MBEDTLS_OID_C,
+ * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C,
- *           MBEDTLS_PK_PARSE_C
+ *           (MBEDTLS_MD_C or MBEDTLS_USE_PSA_CRYPTO)
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any X.509 operation.
  *
  * This module is required for the X.509 parsing modules.
  */
@@ -2944,9 +3149,9 @@
  * Enable X.509 certificate parsing.
  *
  * Module:  library/x509_crt.c
- * Caller:  library/ssl_cli.c
+ * Caller:  library/ssl_tls.c
- *          library/ssl_srv.c
+ *          library/ssl*_client.c
- *          library/ssl_tls.c
+ *          library/ssl*_server.c
  *
  * Requires: MBEDTLS_X509_USE_C
  *
@@ -2989,7 +3194,11 @@
  *
  * Module:  library/x509_create.c
  *
- * Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_WRITE_C
+ * Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C,
+ *           (MBEDTLS_MD_C or MBEDTLS_USE_PSA_CRYPTO)
+ *
+ * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
+ * before doing any X.509 create operation.
  *
  * This module is the basis for creating X.509 certificates and CSRs.
  */
@@ -3023,6 +3232,88 @@
 
 /** \} name SECTION: mbed TLS modules */
 
+/**
+ * \name SECTION: General configuration options
+ *
+ * This section contains Mbed TLS build settings that are not associated
+ * with a particular module.
+ *
+ * \{
+ */
+
+/**
+ * \def MBEDTLS_CONFIG_FILE
+ *
+ * If defined, this is a header which will be included instead of
+ * `"mbedtls/mbedtls_config.h"`.
+ * This header file specifies the compile-time configuration of Mbed TLS.
+ * Unlike other configuration options, this one must be defined on the
+ * compiler command line: a definition in `mbedtls_config.h` would have
+ * no effect.
+ *
+ * This macro is expanded after an <tt>\#include</tt> directive. This is a popular but
+ * non-standard feature of the C language, so this feature is only available
+ * with compilers that perform macro expansion on an <tt>\#include</tt> line.
+ *
+ * The value of this symbol is typically a path in double quotes, either
+ * absolute or relative to a directory on the include search path.
+ */
+//#define MBEDTLS_CONFIG_FILE "mbedtls/mbedtls_config.h"
+
+/**
+ * \def MBEDTLS_USER_CONFIG_FILE
+ *
+ * If defined, this is a header which will be included after
+ * `"mbedtls/mbedtls_config.h"` or #MBEDTLS_CONFIG_FILE.
+ * This allows you to modify the default configuration, including the ability
+ * to undefine options that are enabled by default.
+ *
+ * This macro is expanded after an <tt>\#include</tt> directive. This is a popular but
+ * non-standard feature of the C language, so this feature is only available
+ * with compilers that perform macro expansion on an <tt>\#include</tt> line.
+ *
+ * The value of this symbol is typically a path in double quotes, either
+ * absolute or relative to a directory on the include search path.
+ */
+//#define MBEDTLS_USER_CONFIG_FILE "/dev/null"
+
+/**
+ * \def MBEDTLS_PSA_CRYPTO_CONFIG_FILE
+ *
+ * If defined, this is a header which will be included instead of
+ * `"psa/crypto_config.h"`.
+ * This header file specifies which cryptographic mechanisms are available
+ * through the PSA API when #MBEDTLS_PSA_CRYPTO_CONFIG is enabled, and
+ * is not used when #MBEDTLS_PSA_CRYPTO_CONFIG is disabled.
+ *
+ * This macro is expanded after an <tt>\#include</tt> directive. This is a popular but
+ * non-standard feature of the C language, so this feature is only available
+ * with compilers that perform macro expansion on an <tt>\#include</tt> line.
+ *
+ * The value of this symbol is typically a path in double quotes, either
+ * absolute or relative to a directory on the include search path.
+ */
+//#define MBEDTLS_PSA_CRYPTO_CONFIG_FILE "psa/crypto_config.h"
+
+/**
+ * \def MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE
+ *
+ * If defined, this is a header which will be included after
+ * `"psa/crypto_config.h"` or #MBEDTLS_PSA_CRYPTO_CONFIG_FILE.
+ * This allows you to modify the default configuration, including the ability
+ * to undefine options that are enabled by default.
+ *
+ * This macro is expanded after an <tt>\#include</tt> directive. This is a popular but
+ * non-standard feature of the C language, so this feature is only available
+ * with compilers that perform macro expansion on an <tt>\#include</tt> line.
+ *
+ * The value of this symbol is typically a path in double quotes, either
+ * absolute or relative to a directory on the include search path.
+ */
+//#define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null"
+
+/** \} name SECTION: General configuration options */
+
 /**
  * \name SECTION: Module configuration options
  *
@@ -3032,11 +3323,15 @@
  *
  * Our advice is to enable options and change their values here
  * only if you have a good reason and know the consequences.
- *
- * Please check the respective header file for documentation on these
- * parameters (to prevent duplicate documentation).
  * \{
  */
+/* The Doxygen documentation here is used when a user comments out a
+ * setting and runs doxygen themselves. On the other hand, when we typeset
+ * the full documentation including disabled settings, the documentation
+ * in specific modules' header files is used if present. When editing this
+ * file, make sure that each option is documented in exactly one place,
+ * plus optionally a same-line Doxygen comment here if there is a Doxygen
+ * comment in the specific module. */
 
 /* MPI / BIGNUM options */
 //#define MBEDTLS_MPI_WINDOW_SIZE            6 /**< Maximum window size used. */
@@ -3071,6 +3366,7 @@
 //#define MBEDTLS_PLATFORM_STD_MEM_HDR   <stdlib.h> /**< Header to include if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS is defined. Don't define if no header is needed. */
 //#define MBEDTLS_PLATFORM_STD_CALLOC        calloc /**< Default allocator to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_FREE            free /**< Default free to use, can be undefined */
+//#define MBEDTLS_PLATFORM_STD_SETBUF      setbuf /**< Default setbuf to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_EXIT            exit /**< Default exit to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_TIME            time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
 //#define MBEDTLS_PLATFORM_STD_FPRINTF      fprintf /**< Default fprintf to use, can be undefined */
@@ -3088,6 +3384,7 @@
 //#define MBEDTLS_PLATFORM_CALLOC_MACRO        calloc /**< Default allocator macro to use, can be undefined */
 //#define MBEDTLS_PLATFORM_FREE_MACRO            free /**< Default free macro to use, can be undefined */
 //#define MBEDTLS_PLATFORM_EXIT_MACRO            exit /**< Default exit macro to use, can be undefined */
+//#define MBEDTLS_PLATFORM_SETBUF_MACRO      setbuf /**< Default setbuf macro to use, can be undefined */
 //#define MBEDTLS_PLATFORM_TIME_MACRO            time /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
 //#define MBEDTLS_PLATFORM_TIME_TYPE_MACRO       time_t /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
 //#define MBEDTLS_PLATFORM_FPRINTF_MACRO      fprintf /**< Default fprintf macro to use, can be undefined */
@@ -3319,4 +3616,4 @@
  */
 //#define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED
 
-/** \} name SECTION: Customisation configuration options */
+/** \} name SECTION: Module configuration options */

include/mbedtls/md.h

@@ -199,7 +199,7 @@ MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
 
 /**
- * \brief           This function clones the state of an message-digest
+ * \brief           This function clones the state of a message-digest
  *                  context.
  *
  * \note            You must call mbedtls_md_setup() on \c dst before calling

include/mbedtls/memory_buffer_alloc.h

@@ -90,6 +90,14 @@ void mbedtls_memory_buffer_set_verify( int verify );
  */
 void mbedtls_memory_buffer_alloc_status( void );
 
+/**
+ * \brief   Get the number of alloc/free so far.
+ *
+ * \param alloc_count   Number of allocations.
+ * \param free_count    Number of frees.
+ */
+void mbedtls_memory_buffer_alloc_count_get( size_t *alloc_count, size_t *free_count );
+
 /**
  * \brief   Get the peak heap usage so far
  *

include/mbedtls/oid.h

@@ -34,9 +34,7 @@
 #include "mbedtls/cipher.h"
 #endif
 
-#if defined(MBEDTLS_MD_C)
 #include "mbedtls/md.h"
-#endif
 
 /** OID is not found. */
 #define MBEDTLS_ERR_OID_NOT_FOUND                         -0x002E
@@ -140,7 +138,7 @@
 #define MBEDTLS_OID_AT_GIVEN_NAME               MBEDTLS_OID_AT "\x2A" /**< id-at-givenName AttributeType:= {id-at 42} */
 #define MBEDTLS_OID_AT_INITIALS                 MBEDTLS_OID_AT "\x2B" /**< id-at-initials AttributeType:= {id-at 43} */
 #define MBEDTLS_OID_AT_GENERATION_QUALIFIER     MBEDTLS_OID_AT "\x2C" /**< id-at-generationQualifier AttributeType:= {id-at 44} */
-#define MBEDTLS_OID_AT_UNIQUE_IDENTIFIER        MBEDTLS_OID_AT "\x2D" /**< id-at-uniqueIdentifier AttributType:= {id-at 45} */
+#define MBEDTLS_OID_AT_UNIQUE_IDENTIFIER        MBEDTLS_OID_AT "\x2D" /**< id-at-uniqueIdentifier AttributeType:= {id-at 45} */
 #define MBEDTLS_OID_AT_DN_QUALIFIER             MBEDTLS_OID_AT "\x2E" /**< id-at-dnQualifier AttributeType:= {id-at 46} */
 #define MBEDTLS_OID_AT_PSEUDONYM                MBEDTLS_OID_AT "\x41" /**< id-at-pseudonym AttributeType:= {id-at 65} */
 
@@ -519,7 +517,6 @@ int mbedtls_oid_get_oid_by_ec_grp( mbedtls_ecp_group_id grp_id,
                            const char **oid, size_t *olen );
 #endif /* MBEDTLS_ECP_C */
 
-#if defined(MBEDTLS_MD_C)
 /**
  * \brief          Translate SignatureAlgorithm OID into md_type and pk_type
  *
@@ -555,16 +552,6 @@ int mbedtls_oid_get_sig_alg_desc( const mbedtls_asn1_buf *oid, const char **desc
 int mbedtls_oid_get_oid_by_sig_alg( mbedtls_pk_type_t pk_alg, mbedtls_md_type_t md_alg,
                             const char **oid, size_t *olen );
 
-/**
- * \brief          Translate hash algorithm OID into md_type
- *
- * \param oid      OID to use
- * \param md_alg   place to store message digest algorithm
- *
- * \return         0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
- */
-int mbedtls_oid_get_md_alg( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_alg );
-
 /**
  * \brief          Translate hmac algorithm OID into md_type
  *
@@ -574,7 +561,16 @@ int mbedtls_oid_get_md_alg( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_a
  * \return         0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
  */
 int mbedtls_oid_get_md_hmac( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_hmac );
-#endif /* MBEDTLS_MD_C */
+
+/**
+ * \brief          Translate hash algorithm OID into md_type
+ *
+ * \param oid      OID to use
+ * \param md_alg   place to store message digest algorithm
+ *
+ * \return         0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
+ */
+int mbedtls_oid_get_md_alg( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_alg );
 
 #if !defined(MBEDTLS_X509_REMOVE_INFO)
 /**

include/mbedtls/pk.h

@@ -216,32 +216,6 @@ typedef struct
 typedef void mbedtls_pk_restart_ctx;
 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
 
-#if defined(MBEDTLS_RSA_C)
-/**
- * Quick access to an RSA context inside a PK context.
- *
- * \warning You must make sure the PK context actually holds an RSA context
- * before using this function!
- */
-static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
-{
-    return( (mbedtls_rsa_context *) (pk).MBEDTLS_PRIVATE(pk_ctx) );
-}
-#endif /* MBEDTLS_RSA_C */
-
-#if defined(MBEDTLS_ECP_C)
-/**
- * Quick access to an EC context inside a PK context.
- *
- * \warning You must make sure the PK context actually holds an EC context
- * before using this function!
- */
-static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
-{
-    return( (mbedtls_ecp_keypair *) (pk).MBEDTLS_PRIVATE(pk_ctx) );
-}
-#endif /* MBEDTLS_ECP_C */
-
 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
 /**
  * \brief           Types for RSA-alt abstraction
@@ -330,8 +304,8 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
  *                  storing and manipulating the key material directly.
  *
  * \param ctx       The context to initialize. It must be empty (type NONE).
- * \param key       The PSA key to wrap, which must hold an ECC key pair
+ * \param key       The PSA key to wrap, which must hold an ECC or RSA key
- *                  (see notes below).
+ *                  pair (see notes below).
  *
  * \note            The wrapped key must remain valid as long as the
  *                  wrapping PK context is in use, that is at least between
@@ -339,8 +313,8 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
  *                  mbedtls_pk_free() is called on this context. The wrapped
  *                  key might then be independently used or destroyed.
  *
- * \note            This function is currently only available for ECC key
+ * \note            This function is currently only available for ECC or RSA
- *                  pairs (that is, ECC keys containing private key material).
+ *                  key pairs (that is, keys containing private key material).
  *                  Support for other key types may be added later.
  *
  * \return          \c 0 on success.
@@ -411,6 +385,38 @@ static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
  */
 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
 
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+/**
+ * \brief           Tell if context can do the operation given by PSA algorithm
+ *
+ * \param ctx       The context to query. It must have been initialized.
+ * \param alg       PSA algorithm to check against, the following are allowed:
+ *                  PSA_ALG_RSA_PKCS1V15_SIGN(hash),
+ *                  PSA_ALG_RSA_PSS(hash),
+ *                  PSA_ALG_RSA_PKCS1V15_CRYPT,
+ *                  PSA_ALG_ECDSA(hash),
+ *                  PSA_ALG_ECDH, where hash is a specific hash.
+ * \param usage  PSA usage flag to check against, must be composed of:
+ *                  PSA_KEY_USAGE_SIGN_HASH
+ *                  PSA_KEY_USAGE_DECRYPT
+ *                  PSA_KEY_USAGE_DERIVE.
+ *                  Context key must match all passed usage flags.
+ *
+ * \warning         Since the set of allowed algorithms and usage flags may be
+ *                  expanded in the future, the return value \c 0 should not
+ *                  be taken in account for non-allowed algorithms and usage
+ *                  flags.
+ *
+ * \return          1 if the context can do operations on the given type.
+ * \return          0 if the context cannot do the operations on the given
+ *                  type, for non-allowed algorithms and usage flags, or
+ *                  for a context that has been initialized but not set up
+ *                  or that has been cleared with mbedtls_pk_free().
+ */
+int mbedtls_pk_can_do_ext( const mbedtls_pk_context *ctx, psa_algorithm_t alg,
+                           psa_key_usage_t usage );
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+
 /**
  * \brief           Verify signature (including padding if relevant).
  *
@@ -535,6 +541,45 @@ int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
              unsigned char *sig, size_t sig_size, size_t *sig_len,
              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
+#if defined(MBEDTLS_PSA_CRYPTO_C)
+/**
+ * \brief           Make signature given a signature type.
+ *
+ * \param pk_type   Signature type.
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
+ * \param md_alg    Hash algorithm used (see notes)
+ * \param hash      Hash of the message to sign
+ * \param hash_len  Hash length
+ * \param sig       Place to write the signature.
+ *                  It must have enough room for the signature.
+ *                  #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough.
+ *                  You may use a smaller buffer if it is large enough
+ *                  given the key type.
+ * \param sig_size  The size of the \p sig buffer in bytes.
+ * \param sig_len   On successful return,
+ *                  the number of bytes written to \p sig.
+ * \param f_rng     RNG function, must not be \c NULL.
+ * \param p_rng     RNG parameter
+ *
+ * \return          0 on success, or a specific error code.
+ *
+ * \note            When \p pk_type is #MBEDTLS_PK_RSASSA_PSS,
+ *                  see #PSA_ALG_RSA_PSS for a description of PSS options used.
+ *
+ * \note            For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
+ *                  For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
+ *
+ */
+int mbedtls_pk_sign_ext( mbedtls_pk_type_t pk_type,
+                         mbedtls_pk_context *ctx,
+                         mbedtls_md_type_t md_alg,
+                         const unsigned char *hash, size_t hash_len,
+                         unsigned char *sig, size_t sig_size, size_t *sig_len,
+                         int (*f_rng)(void *, unsigned char *, size_t),
+                         void *p_rng );
+#endif /* MBEDTLS_PSA_CRYPTO_C */
+
 /**
  * \brief           Restartable version of \c mbedtls_pk_sign()
  *
@@ -664,6 +709,55 @@ const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
  */
 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
 
+#if defined(MBEDTLS_RSA_C)
+/**
+ * Quick access to an RSA context inside a PK context.
+ *
+ * \warning This function can only be used when the type of the context, as
+ * returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_RSA.
+ * Ensuring that is the caller's responsibility.
+ * Alternatively, you can check whether this function returns NULL.
+ *
+ * \return The internal RSA context held by the PK context, or NULL.
+ */
+static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
+{
+    switch( mbedtls_pk_get_type( &pk ) )
+    {
+        case MBEDTLS_PK_RSA:
+            return( (mbedtls_rsa_context *) (pk).MBEDTLS_PRIVATE(pk_ctx) );
+        default:
+            return( NULL );
+    }
+}
+#endif /* MBEDTLS_RSA_C */
+
+#if defined(MBEDTLS_ECP_C)
+/**
+ * Quick access to an EC context inside a PK context.
+ *
+ * \warning This function can only be used when the type of the context, as
+ * returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_ECKEY,
+ * #MBEDTLS_PK_ECKEY_DH, or #MBEDTLS_PK_ECDSA.
+ * Ensuring that is the caller's responsibility.
+ * Alternatively, you can check whether this function returns NULL.
+ *
+ * \return The internal EC context held by the PK context, or NULL.
+ */
+static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
+{
+    switch( mbedtls_pk_get_type( &pk ) )
+    {
+        case MBEDTLS_PK_ECKEY:
+        case MBEDTLS_PK_ECKEY_DH:
+        case MBEDTLS_PK_ECDSA:
+            return( (mbedtls_ecp_keypair *) (pk).MBEDTLS_PRIVATE(pk_ctx) );
+        default:
+            return( NULL );
+    }
+}
+#endif /* MBEDTLS_ECP_C */
+
 #if defined(MBEDTLS_PK_PARSE_C)
 /** \ingroup pk_module */
 /**
@@ -878,28 +972,29 @@ int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
 /**
- * \brief           Turn an EC key into an opaque one.
+ * \brief           Turn an EC or RSA key into an opaque one.
  *
  * \warning         This is a temporary utility function for tests. It might
  *                  change or be removed at any time without notice.
  *
- * \note            Only ECDSA keys are supported so far. Signing with the
+ * \param pk        Input: the EC or RSA key to import to a PSA key.
- *                  specified hash is the only allowed use of that key.
- *
- * \param pk        Input: the EC key to import to a PSA key.
  *                  Output: a PK context wrapping that PSA key.
  * \param key       Output: a PSA key identifier.
  *                  It's the caller's responsibility to call
  *                  psa_destroy_key() on that key identifier after calling
  *                  mbedtls_pk_free() on the PK context.
- * \param hash_alg  The hash algorithm to allow for use with that key.
+ * \param alg       The algorithm to allow for use with that key.
+ * \param usage     The usage to allow for use with that key.
+ * \param alg2      The secondary algorithm to allow for use with that key.
  *
  * \return          \c 0 if successful.
  * \return          An Mbed TLS error code otherwise.
  */
 int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
                                mbedtls_svc_key_id_t *key,
-                               psa_algorithm_t hash_alg );
+                               psa_algorithm_t alg,
+                               psa_key_usage_t usage,
+                               psa_algorithm_t alg2 );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
 #ifdef __cplusplus

include/mbedtls/pkcs5.h

@@ -70,9 +70,33 @@ int mbedtls_pkcs5_pbes2( const mbedtls_asn1_buf *pbe_params, int mode,
 
 #endif /* MBEDTLS_ASN1_PARSE_C */
 
+/**
+ * \brief          PKCS#5 PBKDF2 using HMAC without using the HMAC context
+ *
+ * \param md_type  Hash algorithm used
+ * \param password Password to use when generating key
+ * \param plen     Length of password
+ * \param salt     Salt to use when generating key
+ * \param slen     Length of salt
+ * \param iteration_count       Iteration count
+ * \param key_length            Length of generated key in bytes
+ * \param output   Generated key. Must be at least as big as key_length
+ *
+ * \returns        0 on success, or a MBEDTLS_ERR_XXX code if verification fails.
+ */
+int mbedtls_pkcs5_pbkdf2_hmac_ext( mbedtls_md_type_t md_type,
+                       const unsigned char *password,
+                       size_t plen, const unsigned char *salt, size_t slen,
+                       unsigned int iteration_count,
+                       uint32_t key_length, unsigned char *output );
+
+#if defined(MBEDTLS_MD_C)
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 /**
  * \brief          PKCS#5 PBKDF2 using HMAC
  *
+ * \deprecated     Superseded by mbedtls_pkcs5_pbkdf2_hmac_ext().
+ *
  * \param ctx      Generic HMAC context
  * \param password Password to use when generating key
  * \param plen     Length of password
@@ -84,11 +108,13 @@ int mbedtls_pkcs5_pbes2( const mbedtls_asn1_buf *pbe_params, int mode,
  *
  * \returns        0 on success, or a MBEDTLS_ERR_XXX code if verification fails.
  */
-int mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx, const unsigned char *password,
+int MBEDTLS_DEPRECATED mbedtls_pkcs5_pbkdf2_hmac( mbedtls_md_context_t *ctx,
+                       const unsigned char *password,
                        size_t plen, const unsigned char *salt, size_t slen,
                        unsigned int iteration_count,
                        uint32_t key_length, unsigned char *output );
-
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#endif /* MBEDTLS_MD_C */
 #if defined(MBEDTLS_SELF_TEST)
 
 /**

include/mbedtls/platform.h

@@ -62,7 +62,9 @@ extern "C" {
 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
 #include <stdio.h>
 #include <stdlib.h>
+#if defined(MBEDTLS_HAVE_TIME)
 #include <time.h>
+#endif
 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
 #define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use.  */
@@ -89,6 +91,9 @@ extern "C" {
 #if !defined(MBEDTLS_PLATFORM_STD_FREE)
 #define MBEDTLS_PLATFORM_STD_FREE       free /**< The default \c free function to use. */
 #endif
+#if !defined(MBEDTLS_PLATFORM_STD_SETBUF)
+#define MBEDTLS_PLATFORM_STD_SETBUF   setbuf /**< The default \c setbuf function to use. */
+#endif
 #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
 #define MBEDTLS_PLATFORM_STD_EXIT      exit /**< The default \c exit function to use. */
 #endif
@@ -274,6 +279,56 @@ int mbedtls_platform_set_vsnprintf( int (*vsnprintf_func)( char * s, size_t n,
 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */
 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
 
+/*
+ * The function pointers for setbuf
+ */
+#if defined(MBEDTLS_PLATFORM_SETBUF_ALT)
+#include <stdio.h>
+/**
+ * \brief                  Function pointer to call for `setbuf()` functionality
+ *                         (changing the internal buffering on stdio calls).
+ *
+ * \note                   The library calls this function to disable
+ *                         buffering when reading or writing sensitive data,
+ *                         to avoid having extra copies of sensitive data
+ *                         remaining in stdio buffers after the file is
+ *                         closed. If this is not a concern, for example if
+ *                         your platform's stdio doesn't have any buffering,
+ *                         you can set mbedtls_setbuf to a function that
+ *                         does nothing.
+ *
+ *                         The library always calls this function with
+ *                         `buf` equal to `NULL`.
+ */
+extern void (*mbedtls_setbuf)( FILE *stream, char *buf );
+
+/**
+ * \brief                  Dynamically configure the function that is called
+ *                         when the mbedtls_setbuf() function is called by the
+ *                         library.
+ *
+ * \param   setbuf_func   The \c setbuf function implementation
+ *
+ * \return                 \c 0
+ */
+int mbedtls_platform_set_setbuf( void (*setbuf_func)(
+                                     FILE *stream, char *buf ) );
+#elif defined(MBEDTLS_PLATFORM_SETBUF_MACRO)
+/**
+ * \brief                  Macro defining the function for the library to
+ *                         call for `setbuf` functionality (changing the
+ *                         internal buffering on stdio calls).
+ *
+ * \note                   See extra comments on the mbedtls_setbuf() function
+ *                         pointer above.
+ *
+ * \return                 \c 0 on success, negative on error.
+ */
+#define mbedtls_setbuf    MBEDTLS_PLATFORM_SETBUF_MACRO
+#else
+#define mbedtls_setbuf    setbuf
+#endif /* MBEDTLS_PLATFORM_SETBUF_ALT / MBEDTLS_PLATFORM_SETBUF_MACRO */
+
 /*
  * The function pointers for exit
  */

include/mbedtls/platform_util.h

@@ -122,7 +122,7 @@ MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
  *
  * This macro has an empty expansion. It exists for documentation purposes:
  * a #MBEDTLS_CHECK_RETURN_OPTIONAL annotation indicates that the function
- * has been analyzed for return-check usefuless, whereas the lack of
+ * has been analyzed for return-check usefulness, whereas the lack of
  * an annotation indicates that the function has not been analyzed and its
  * return-check usefulness is unknown.
  */

include/mbedtls/private_access.h

@@ -1,7 +1,7 @@
  /**
  * \file private_access.h
  *
- * \brief Macro wrapper for struct's memebrs.
+ * \brief Macro wrapper for struct's members.
  */
 /*
  *  Copyright The Mbed TLS Contributors

include/mbedtls/psa_util.h

@@ -29,7 +29,7 @@
 
 #include "mbedtls/build_info.h"
 
-#if defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3)
+#if defined(MBEDTLS_PSA_CRYPTO_C)
 
 #include "psa/crypto.h"
 
@@ -124,35 +124,38 @@ static inline psa_key_usage_t mbedtls_psa_translate_cipher_operation(
 
 /* Translations for hashing. */
 
+/* Note: this function should not be used from inside the library, use
+ * mbedtls_hash_info_psa_from_md() from the internal hash_info.h instead.
+ * It is kept only for compatibility in case applications were using it. */
 static inline psa_algorithm_t mbedtls_psa_translate_md( mbedtls_md_type_t md_alg )
 {
     switch( md_alg )
     {
-#if defined(MBEDTLS_MD5_C)
+#if defined(MBEDTLS_MD5_C) || defined(PSA_WANT_ALG_MD5)
     case MBEDTLS_MD_MD5:
         return( PSA_ALG_MD5 );
 #endif
-#if defined(MBEDTLS_SHA1_C)
+#if defined(MBEDTLS_SHA1_C) || defined(PSA_WANT_ALG_SHA_1)
     case MBEDTLS_MD_SHA1:
         return( PSA_ALG_SHA_1 );
 #endif
-#if defined(MBEDTLS_SHA224_C)
+#if defined(MBEDTLS_SHA224_C) || defined(PSA_WANT_ALG_SHA_224)
     case MBEDTLS_MD_SHA224:
         return( PSA_ALG_SHA_224 );
 #endif
-#if defined(MBEDTLS_SHA256_C)
+#if defined(MBEDTLS_SHA256_C) || defined(PSA_WANT_ALG_SHA_256)
     case MBEDTLS_MD_SHA256:
         return( PSA_ALG_SHA_256 );
 #endif
-#if defined(MBEDTLS_SHA384_C)
+#if defined(MBEDTLS_SHA384_C) || defined(PSA_WANT_ALG_SHA_384)
     case MBEDTLS_MD_SHA384:
         return( PSA_ALG_SHA_384 );
 #endif
-#if defined(MBEDTLS_SHA512_C)
+#if defined(MBEDTLS_SHA512_C) || defined(PSA_WANT_ALG_SHA_512)
     case MBEDTLS_MD_SHA512:
         return( PSA_ALG_SHA_512 );
 #endif
-#if defined(MBEDTLS_RIPEMD160_C)
+#if defined(MBEDTLS_RIPEMD160_C) || defined(PSA_WANT_ALG_RIPEMD160)
     case MBEDTLS_MD_RIPEMD160:
         return( PSA_ALG_RIPEMD160 );
 #endif
@@ -277,13 +280,11 @@ static inline psa_key_type_t mbedtls_psa_parse_tls_ecc_group(
 }
 #endif /* MBEDTLS_ECP_C */
 
-#endif /* MBEDTLS_USE_PSA_CRYPTO */
-
 /* Expose whatever RNG the PSA subsystem uses to applications using the
  * mbedtls_xxx API. The declarations and definitions here need to be
  * consistent with the implementation in library/psa_crypto_random_impl.h.
  * See that file for implementation documentation. */
-#if defined(MBEDTLS_PSA_CRYPTO_C)
+
 
 /* The type of a `f_rng` random generator function that many library functions
  * take.
@@ -363,6 +364,6 @@ extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state;
 
 #endif /* !defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) */
 
-#endif /* defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3) */
+#endif /* MBEDTLS_PSA_CRYPTO_C */
 
 #endif /* MBEDTLS_PSA_UTIL_H */

include/mbedtls/ripemd160.h

@@ -66,7 +66,7 @@ void mbedtls_ripemd160_init( mbedtls_ripemd160_context *ctx );
 void mbedtls_ripemd160_free( mbedtls_ripemd160_context *ctx );
 
 /**
- * \brief          Clone (the state of) an RIPEMD-160 context
+ * \brief          Clone (the state of) a RIPEMD-160 context
  *
  * \param dst      The destination context
  * \param src      The context to be cloned

include/mbedtls/rsa.h

@@ -74,7 +74,7 @@
 
 /*
  * The above constants may be used even if the RSA module is compile out,
- * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
+ * eg for alternative (PKCS#11) RSA implementations in the PK layers.
  */
 
 #ifdef __cplusplus
@@ -479,7 +479,7 @@ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
  *             the current function does not have access to them,
  *             and therefore cannot check them. See mbedtls_rsa_complete().
  *             If you want to check the consistency of the entire
- *             content of an PKCS1-encoded RSA private key, for example, you
+ *             content of a PKCS1-encoded RSA private key, for example, you
  *             should use mbedtls_rsa_validate_params() before setting
  *             up the RSA context.
  *             Additionally, if the implementation performs empirical checks,
@@ -540,7 +540,7 @@ int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
  *
  * \note           Blinding is used if and only if a PRNG is provided.
  *
- * \note           If blinding is used, both the base of exponentation
+ * \note           If blinding is used, both the base of exponentiation
  *                 and the exponent are blinded, providing protection
  *                 against some side-channel attacks.
  *
@@ -634,7 +634,7 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
  * \note             The output buffer must be as large as the size
  *                   of ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \param ctx        The initnialized RSA context to use.
+ * \param ctx        The initialized RSA context to use.
  * \param f_rng      The RNG function to use. This is needed for padding
  *                   generation and is mandatory.
  * \param p_rng      The RNG context to be passed to \p f_rng. This may

include/mbedtls/ssl.h

@@ -41,9 +41,8 @@
 #endif
 
 /* Adding guard for MBEDTLS_ECDSA_C to ensure no compile errors due
- * to guards also being in ssl_srv.c and ssl_cli.c. There is a gap
+ * to guards in TLS code. There is a gap in functionality that access to
- * in functionality that access to ecdh_ctx structure is needed for
+ * ecdh_ctx structure is needed for MBEDTLS_ECDSA_C which does not seem correct.
- * MBEDTLS_ECDSA_C which does not seem correct.
  */
 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C)
 #include "mbedtls/ecdh.h"
@@ -99,6 +98,8 @@
 /* Error space gap */
 /** Processing of the Certificate handshake message failed. */
 #define MBEDTLS_ERR_SSL_BAD_CERTIFICATE                   -0x7A00
+/** Received NewSessionTicket Post Handshake Message */
+#define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET       -0x7B00
 /* Error space gap */
 /* Error space gap */
 /* Error space gap */
@@ -170,6 +171,15 @@
 /** Invalid value in SSL config */
 #define MBEDTLS_ERR_SSL_BAD_CONFIG                        -0x5E80
 
+/*
+ * Constants from RFC 8446 for TLS 1.3 PSK modes
+ *
+ * Those are used in the Pre-Shared Key Exchange Modes extension.
+ * See Section 4.2.9 in RFC 8446.
+ */
+#define MBEDTLS_SSL_TLS1_3_PSK_MODE_PURE  0 /* Pure PSK-based exchange  */
+#define MBEDTLS_SSL_TLS1_3_PSK_MODE_ECDHE 1 /* PSK+ECDHE-based exchange */
+
 /*
  * TLS 1.3 NamedGroup values
  *
@@ -240,17 +250,21 @@
     ( MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL        |            \
       MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL    ) /*!< All ephemeral TLS 1.3 key exchanges */
 
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE   ( 0 )
+
 /*
  * Various constants
  */
 
-/* These are the high an low bytes of ProtocolVersion as defined by:
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+/* These are the high and low bytes of ProtocolVersion as defined by:
  * - RFC 5246: ProtocolVersion version = { 3, 3 };     // TLS v1.2
  * - RFC 8446: see section 4.2.1
  */
 #define MBEDTLS_SSL_MAJOR_VERSION_3             3
 #define MBEDTLS_SSL_MINOR_VERSION_3             3   /*!< TLS v1.2 */
 #define MBEDTLS_SSL_MINOR_VERSION_4             4   /*!< TLS v1.3 */
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
 
 #define MBEDTLS_SSL_TRANSPORT_STREAM            0   /*!< TLS      */
 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM          1   /*!< DTLS     */
@@ -323,6 +337,13 @@
 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT  1
 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER  0
 
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
+#if defined(PSA_WANT_ALG_SHA_384)
+#define MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN        48
+#elif defined(PSA_WANT_ALG_SHA_256)
+#define MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN        32
+#endif
+#endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
 /*
  * Default range for DTLS retransmission timer value, in milliseconds.
  * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
@@ -487,9 +508,11 @@
 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86  /* 0x56 */
 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED         90  /* 0x5A */
 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION     100  /* 0x64 */
+#define MBEDTLS_SSL_ALERT_MSG_MISSING_EXTENSION    109  /* 0x6d -- new in TLS 1.3 */
 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT      110  /* 0x6E */
 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME    112  /* 0x70 */
 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115  /* 0x73 */
+#define MBEDTLS_SSL_ALERT_MSG_CERT_REQUIRED        116  /* 0x74 */
 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
 
 #define MBEDTLS_SSL_HS_HELLO_REQUEST            0
@@ -606,7 +629,12 @@ union mbedtls_ssl_premaster_secret
 
 #define MBEDTLS_PREMASTER_SIZE     sizeof( union mbedtls_ssl_premaster_secret )
 
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#define MBEDTLS_TLS1_3_MD_MAX_SIZE         PSA_HASH_MAX_SIZE
+#else
 #define MBEDTLS_TLS1_3_MD_MAX_SIZE         MBEDTLS_MD_MAX_SIZE
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+
 
 /* Length in number of bytes of the TLS sequence number */
 #define MBEDTLS_SSL_SEQUENCE_NUMBER_LEN 8
@@ -637,16 +665,16 @@ typedef enum
     MBEDTLS_SSL_FLUSH_BUFFERS,
     MBEDTLS_SSL_HANDSHAKE_WRAPUP,
     MBEDTLS_SSL_HANDSHAKE_OVER,
-    MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
+    MBEDTLS_SSL_NEW_SESSION_TICKET,
     MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
+    MBEDTLS_SSL_HELLO_RETRY_REQUEST,
     MBEDTLS_SSL_ENCRYPTED_EXTENSIONS,
     MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY,
-#if defined(MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE)
     MBEDTLS_SSL_CLIENT_CCS_AFTER_SERVER_FINISHED,
     MBEDTLS_SSL_CLIENT_CCS_BEFORE_2ND_CLIENT_HELLO,
-#endif /* MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE */
+    MBEDTLS_SSL_SERVER_CCS_AFTER_SERVER_HELLO,
-#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
+    MBEDTLS_SSL_SERVER_CCS_AFTER_HELLO_RETRY_REQUEST,
+    MBEDTLS_SSL_NEW_SESSION_TICKET_FLUSH,
 }
 mbedtls_ssl_states;
 
@@ -733,7 +761,7 @@ typedef int mbedtls_ssl_recv_timeout_t( void *ctx,
  *                 for the associated \c mbedtls_ssl_get_timer_t callback to
  *                 return correct information.
  *
- * \note           If using a event-driven style of programming, an event must
+ * \note           If using an event-driven style of programming, an event must
  *                 be generated when the final delay is passed. The event must
  *                 cause a call to \c mbedtls_ssl_handshake() with the proper
  *                 SSL context to be scheduled. Care must be taken to ensure
@@ -1100,6 +1128,14 @@ mbedtls_dtls_srtp_info;
 
 #endif /* MBEDTLS_SSL_DTLS_SRTP */
 
+/** Human-friendly representation of the (D)TLS protocol version. */
+typedef enum
+{
+    MBEDTLS_SSL_VERSION_UNKNOWN, /*!< Context not in use or version not yet negotiated. */
+    MBEDTLS_SSL_VERSION_TLS1_2 = 0x0303, /*!< (D)TLS 1.2 */
+    MBEDTLS_SSL_VERSION_TLS1_3 = 0x0304, /*!< (D)TLS 1.3 */
+} mbedtls_ssl_protocol_version;
+
 /*
  * This structure is used for storing current session data.
  *
@@ -1119,16 +1155,15 @@ struct mbedtls_ssl_session
 
     unsigned char MBEDTLS_PRIVATE(exported);
 
-    /* This field is temporarily duplicated with mbedtls_ssl_context.minor_ver.
+    /** TLS version negotiated in the session. Used if and when renegotiating
-     * Once runtime negotiation of TLS 1.2 and TLS 1.3 is implemented, it needs
+     *  or resuming a session instead of the configured minor TLS version.
-     * to be studied whether one of them can be removed. */
+     */
-    unsigned char MBEDTLS_PRIVATE(minor_ver);    /*!< The TLS version used in the session. */
+    mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(tls_version);
 
 #if defined(MBEDTLS_HAVE_TIME)
     mbedtls_time_t MBEDTLS_PRIVATE(start);       /*!< starting time      */
 #endif
     int MBEDTLS_PRIVATE(ciphersuite);            /*!< chosen ciphersuite */
-    int MBEDTLS_PRIVATE(compression);            /*!< chosen compression */
     size_t MBEDTLS_PRIVATE(id_len);              /*!< session id length  */
     unsigned char MBEDTLS_PRIVATE(id)[32];       /*!< session identifier */
     unsigned char MBEDTLS_PRIVATE(master)[48];   /*!< the master secret  */
@@ -1152,6 +1187,19 @@ struct mbedtls_ssl_session
     uint32_t MBEDTLS_PRIVATE(ticket_lifetime);   /*!< ticket lifetime hint    */
 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
 
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
+    uint8_t MBEDTLS_PRIVATE(endpoint);          /*!< 0: client, 1: server */
+    uint8_t MBEDTLS_PRIVATE(ticket_flags);      /*!< Ticket flags */
+    uint32_t MBEDTLS_PRIVATE(ticket_age_add);               /*!< Randomly generated value used to obscure the age of the ticket */
+    uint8_t MBEDTLS_PRIVATE(resumption_key_len);            /*!< resumption_key length */
+    unsigned char MBEDTLS_PRIVATE(resumption_key)[MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN];
+
+#if defined(MBEDTLS_HAVE_TIME) && defined(MBEDTLS_SSL_CLI_C)
+    mbedtls_time_t MBEDTLS_PRIVATE(ticket_received);        /*!< time ticket was received */
+#endif /* MBEDTLS_HAVE_TIME && MBEDTLS_SSL_CLI_C */
+
+#endif /*  MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
+
 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
     int MBEDTLS_PRIVATE(encrypt_then_mac);       /*!< flag for EtM activation                */
 #endif
@@ -1161,14 +1209,6 @@ struct mbedtls_ssl_session
 #endif
 };
 
-/** Human-friendly representation of the (D)TLS protocol version. */
-typedef enum
-{
-    MBEDTLS_SSL_VERSION_UNKNOWN, /*!< Context not in use or version not yet negotiated. */
-    MBEDTLS_SSL_VERSION_1_2,     /*!< (D)TLS 1.2 */
-    MBEDTLS_SSL_VERSION_1_3,     /*!< (D)TLS 1.3 */
-} mbedtls_ssl_protocol_version;
-
 /*
  * Identifiers for PRFs used in various versions of TLS.
  */
@@ -1218,6 +1258,25 @@ typedef void mbedtls_ssl_export_keys_t( void *p_expkey,
                                         const unsigned char server_random[32],
                                         mbedtls_tls_prf_types tls_prf_type );
 
+#if defined(MBEDTLS_SSL_SRV_C)
+/**
+ * \brief           Callback type: generic handshake callback
+ *
+ * \note            Callbacks may use user_data funcs to set/get app user data.
+ *                  See \c mbedtls_ssl_get_user_data_p()
+ *                      \c mbedtls_ssl_get_user_data_n()
+ *                      \c mbedtls_ssl_conf_get_user_data_p()
+ *                      \c mbedtls_ssl_conf_get_user_data_n()
+ *
+ * \param ssl       \c mbedtls_ssl_context on which the callback is run
+ *
+ * \return          The return value of the callback is 0 if successful,
+ *                  or a specific MBEDTLS_ERR_XXX code, which will cause
+ *                  the handshake to be aborted.
+ */
+typedef int (*mbedtls_ssl_hs_cb_t)( mbedtls_ssl_context *ssl );
+#endif
+
 /* A type for storing user data in a library structure.
  *
  * The representation of type may change in future versions of the library.
@@ -1240,10 +1299,8 @@ struct mbedtls_ssl_config
      * so that elements tend to be in the 128-element direct access window
      * on Arm Thumb, which reduces the code size. */
 
-    unsigned char MBEDTLS_PRIVATE(max_major_ver);    /*!< max. major version used            */
+    mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(max_tls_version);  /*!< max. TLS version used */
-    unsigned char MBEDTLS_PRIVATE(max_minor_ver);    /*!< max. minor version used            */
+    mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(min_tls_version);  /*!< min. TLS version used */
-    unsigned char MBEDTLS_PRIVATE(min_major_ver);    /*!< min. major version used            */
-    unsigned char MBEDTLS_PRIVATE(min_minor_ver);    /*!< min. minor version used            */
 
     /*
      * Flags (could be bit-fields to save RAM, but separate bytes make
@@ -1337,7 +1394,7 @@ struct mbedtls_ssl_config
 #endif
 
 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
-    /** Callback to create & write a cookie for ClientHello veirifcation    */
+    /** Callback to create & write a cookie for ClientHello verification    */
     int (*MBEDTLS_PRIVATE(f_cookie_write))( void *, unsigned char **, unsigned char *,
                            const unsigned char *, size_t );
     /** Callback to verify validity of a ClientHello cookie                 */
@@ -1354,7 +1411,6 @@ struct mbedtls_ssl_config
     int (*MBEDTLS_PRIVATE(f_ticket_parse))( void *, mbedtls_ssl_session *, unsigned char *, size_t);
     void *MBEDTLS_PRIVATE(p_ticket);                 /*!< context for the ticket callbacks   */
 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
-
 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
     size_t MBEDTLS_PRIVATE(cid_len); /*!< The length of CIDs for incoming DTLS records.      */
 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
@@ -1409,7 +1465,6 @@ struct mbedtls_ssl_config
                               *   configured, this has value \c 0.
                               */
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
-
     unsigned char *MBEDTLS_PRIVATE(psk);      /*!< The raw pre-shared key. This field should
                               *   only be set via mbedtls_ssl_conf_psk().
                               *   If either no PSK or an opaque PSK
@@ -1477,8 +1532,12 @@ struct mbedtls_ssl_config
     mbedtls_ssl_user_data_t MBEDTLS_PRIVATE(user_data);
 
 #if defined(MBEDTLS_SSL_SRV_C)
-    int (*MBEDTLS_PRIVATE(f_cert_cb))(mbedtls_ssl_context *); /*!< certificate selection callback */
+    mbedtls_ssl_hs_cb_t MBEDTLS_PRIVATE(f_cert_cb);  /*!< certificate selection callback */
 #endif /* MBEDTLS_SSL_SRV_C */
+
+#if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
+    const mbedtls_x509_crt *MBEDTLS_PRIVATE(dn_hints);/*!< acceptable client cert issuers    */
+#endif
 };
 
 struct mbedtls_ssl_context
@@ -1496,12 +1555,22 @@ struct mbedtls_ssl_context
                                   renego_max_records is < 0           */
 #endif /* MBEDTLS_SSL_RENEGOTIATION */
 
-    int MBEDTLS_PRIVATE(major_ver);              /*!< equal to  MBEDTLS_SSL_MAJOR_VERSION_3    */
+    /** Server: Negotiated TLS protocol version.
+     *  Client: Maximum TLS version to be negotiated, then negotiated TLS
+     *          version.
+     *
+     *  It is initialized as the maximum TLS version to be negotiated in the
+     *  ClientHello writing preparation stage and used throughout the
+     *  ClientHello writing. For a fresh handshake not linked to any previous
+     *  handshake, it is initialized to the configured maximum TLS version
+     *  to be negotiated. When renegotiating or resuming a session, it is
+     *  initialized to the previously negotiated TLS version.
+     *
+     *  Updated to the negotiated TLS version as soon as the ServerHello is
+     *  received.
+     */
+    mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(tls_version);
 
-    /* This field is temporarily duplicated with mbedtls_ssl_context.minor_ver.
-     * Once runtime negotiation of TLS 1.2 and TLS 1.3 is implemented, it needs
-     * to be studied whether one of them can be removed. */
-    int MBEDTLS_PRIVATE(minor_ver);              /*!< one of MBEDTLS_SSL_MINOR_VERSION_x macros */
     unsigned MBEDTLS_PRIVATE(badmac_seen);       /*!< records with a bad MAC received    */
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
@@ -1910,7 +1979,7 @@ static inline const mbedtls_ssl_config *mbedtls_ssl_context_get_config(
  *
  * \note           The two most common use cases are:
  *                 - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
- *                 - blocking I/O, f_recv == NULL, f_recv_timout != NULL
+ *                 - blocking I/O, f_recv == NULL, f_recv_timeout != NULL
  *
  * \note           For DTLS, you need to provide either a non-NULL
  *                 f_recv_timeout callback, or a f_recv that doesn't block.
@@ -2023,6 +2092,40 @@ int mbedtls_ssl_set_cid( mbedtls_ssl_context *ssl,
                          unsigned char const *own_cid,
                          size_t own_cid_len );
 
+/**
+ * \brief              Get information about our request for usage of the CID
+ *                     extension in the current connection.
+ *
+ * \param ssl          The SSL context to query.
+ * \param enabled      The address at which to store whether the CID extension
+ *                     is requested to be used or not. If the CID is
+ *                     requested, `*enabled` is set to
+ *                     MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to
+ *                     MBEDTLS_SSL_CID_DISABLED.
+ * \param own_cid      The address of the buffer in which to store our own
+ *                     CID (if the CID extension is requested). This may be
+ *                     \c NULL in case the value of our CID isn't needed. If
+ *                     it is not \c NULL, \p own_cid_len must not be \c NULL.
+ * \param own_cid_len  The address at which to store the size of our own CID
+ *                     (if the CID extension is requested). This is also the
+ *                     number of Bytes in \p own_cid that have been written.
+ *                     This may be \c NULL in case the length of our own CID
+ *                     isn't needed. If it is \c NULL, \p own_cid must be
+ *                     \c NULL, too.
+ *
+ *\note                If we are requesting an empty CID this function sets
+ *                     `*enabled` to #MBEDTLS_SSL_CID_DISABLED (the rationale
+ *                     for this is that the resulting outcome is the
+ *                     same as if the CID extensions wasn't requested).
+ *
+ * \return            \c 0 on success.
+ * \return            A negative error code on failure.
+ */
+int mbedtls_ssl_get_own_cid( mbedtls_ssl_context *ssl,
+                            int *enabled,
+                            unsigned char own_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX],
+                            size_t *own_cid_len );
+
 /**
  * \brief              Get information about the use of the CID extension
  *                     in the current connection.
@@ -2068,7 +2171,7 @@ int mbedtls_ssl_get_peer_cid( mbedtls_ssl_context *ssl,
 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
 
 /**
- * \brief          Set the Maximum Tranport Unit (MTU).
+ * \brief          Set the Maximum Transport Unit (MTU).
  *                 Special value: 0 means unset (no limit).
  *                 This represents the maximum size of a datagram payload
  *                 handled by the transport layer (usually UDP) as determined
@@ -2231,19 +2334,15 @@ void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl,
  *                  If set, the callback is always called for each handshake,
  *                  after `ClientHello` processing has finished.
  *
- *                  The callback has the following parameters:
- *                  - \c mbedtls_ssl_context*: The SSL context to which
- *                                             the operation applies.
- *                  The return value of the callback is 0 if successful,
- *                  or a specific MBEDTLS_ERR_XXX code, which will cause
- *                  the handshake to be aborted.
- *
  * \param conf      The SSL configuration to register the callback with.
  * \param f_cert_cb The callback for selecting server certificate after
  *                  `ClientHello` processing has finished.
  */
-void mbedtls_ssl_conf_cert_cb( mbedtls_ssl_config *conf,
+static inline void mbedtls_ssl_conf_cert_cb( mbedtls_ssl_config *conf,
-                               int (*f_cert_cb)(mbedtls_ssl_context *) );
+                                             mbedtls_ssl_hs_cb_t f_cert_cb )
+{
+    conf->MBEDTLS_PRIVATE(f_cert_cb) = f_cert_cb;
+}
 #endif /* MBEDTLS_SSL_SRV_C */
 
 /**
@@ -2677,7 +2776,7 @@ void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode );
  *                 ones going through the authentication-decryption phase.
  *
  * \note           This is a security trade-off related to the fact that it's
- *                 often relatively easy for an active attacker ot inject UDP
+ *                 often relatively easy for an active attacker to inject UDP
  *                 datagrams. On one hand, setting a low limit here makes it
  *                 easier for such an attacker to forcibly terminated a
  *                 connection. On the other hand, a high limit or no limit
@@ -2787,7 +2886,7 @@ void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min,
  *                 successfully cached, return 1 otherwise.
  *
  * \param conf           SSL configuration
- * \param p_cache        parmater (context) for both callbacks
+ * \param p_cache        parameter (context) for both callbacks
  * \param f_get_cache    session get callback
  * \param f_set_cache    session set callback
  */
@@ -2849,7 +2948,7 @@ int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session
 /**
  * \brief          Load serialized session data into a session structure.
  *                 On client, this can be used for loading saved sessions
- *                 before resuming them with mbedstls_ssl_set_session().
+ *                 before resuming them with mbedtls_ssl_set_session().
  *                 On server, this can be used for alternative implementations
  *                 of session cache or session tickets.
  *
@@ -3071,6 +3170,26 @@ void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
                                mbedtls_x509_crt *ca_chain,
                                mbedtls_x509_crl *ca_crl );
 
+#if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
+/**
+ * \brief          Set DN hints sent to client in CertificateRequest message
+ *
+ * \note           If not set, subject distinguished names (DNs) are taken
+ *                 from \c mbedtls_ssl_conf_ca_chain()
+ *                 or \c mbedtls_ssl_set_hs_ca_chain())
+ *
+ * \param conf     SSL configuration
+ * \param crt      crt chain whose subject DNs are issuer DNs of client certs
+ *                 from which the client should select client peer certificate.
+ */
+static inline
+void mbedtls_ssl_conf_dn_hints( mbedtls_ssl_config *conf,
+                                const mbedtls_x509_crt *crt )
+{
+    conf->MBEDTLS_PRIVATE(dn_hints) = crt;
+}
+#endif /* MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED */
+
 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
 /**
  * \brief          Set the trusted certificate callback.
@@ -3145,7 +3264,7 @@ void mbedtls_ssl_conf_ca_cb( mbedtls_ssl_config *conf,
  *
  * \note           On client, only the first call has any effect. That is,
  *                 only one client certificate can be provisioned. The
- *                 server's preferences in its CertficateRequest message will
+ *                 server's preferences in its CertificateRequest message will
  *                 be ignored and our only cert will be sent regardless of
  *                 whether it matches those preferences - the server can then
  *                 decide what it wants to do with it.
@@ -3396,7 +3515,7 @@ void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf,
  *                 Both sides: limits the set of curves accepted for use in
  *                 ECDHE and in the peer's end-entity certificate.
  *
- * \deprecated     Superseeded by mbedtls_ssl_conf_groups().
+ * \deprecated     Superseded by mbedtls_ssl_conf_groups().
  *
  * \note           This has no influence on which curves are allowed inside the
  *                 certificate chains, see \c mbedtls_ssl_conf_cert_profile()
@@ -3595,6 +3714,21 @@ void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl,
                                   mbedtls_x509_crt *ca_chain,
                                   mbedtls_x509_crl *ca_crl );
 
+#if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
+/**
+ * \brief          Set DN hints sent to client in CertificateRequest message
+ *
+ * \note           Same as \c mbedtls_ssl_conf_dn_hints() but for use within
+ *                 the SNI callback or the certificate selection callback.
+ *
+ * \param ssl      SSL context
+ * \param crt      crt chain whose subject DNs are issuer DNs of client certs
+ *                 from which the client should select client peer certificate.
+ */
+void mbedtls_ssl_set_hs_dn_hints( mbedtls_ssl_context *ssl,
+                                  const mbedtls_x509_crt *crt );
+#endif /* MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED */
+
 /**
  * \brief          Set authmode for the current handshake.
  *
@@ -3667,7 +3801,7 @@ int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl,
  * \param protos   Pointer to a NULL-terminated list of supported protocols,
  *                 in decreasing preference order. The pointer to the list is
  *                 recorded by the library for later reference as required, so
- *                 the lifetime of the table must be atleast as long as the
+ *                 the lifetime of the table must be at least as long as the
  *                 lifetime of the SSL configuration structure.
  *
  * \return         0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
@@ -3681,7 +3815,7 @@ int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **prot
  *
  * \param ssl      SSL context
  *
- * \return         Protcol name, or NULL if no protocol was negotiated.
+ * \return         Protocol name, or NULL if no protocol was negotiated.
  */
 const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl );
 #endif /* MBEDTLS_SSL_ALPN */
@@ -3764,7 +3898,7 @@ int mbedtls_ssl_dtls_srtp_set_mki_value( mbedtls_ssl_context *ssl,
                                          unsigned char *mki_value,
                                          uint16_t mki_len );
 /**
- * \brief                  Get the negotiated DTLS-SRTP informations:
+ * \brief                  Get the negotiated DTLS-SRTP information:
  *                         Protection profile and MKI value.
  *
  * \warning                This function must be called after the handshake is
@@ -3772,7 +3906,7 @@ int mbedtls_ssl_dtls_srtp_set_mki_value( mbedtls_ssl_context *ssl,
  *                         not be trusted or acted upon before the handshake completes.
  *
  * \param ssl              The SSL context to query.
- * \param dtls_srtp_info   The negotiated DTLS-SRTP informations:
+ * \param dtls_srtp_info   The negotiated DTLS-SRTP information:
  *                         - Protection profile in use.
  *                         A direct mapping of the iana defined value for protection
  *                         profile on an uint16_t.
@@ -3785,6 +3919,7 @@ void mbedtls_ssl_get_dtls_srtp_negotiation_result( const mbedtls_ssl_context *ss
                                                    mbedtls_dtls_srtp_info *dtls_srtp_info );
 #endif /* MBEDTLS_SSL_DTLS_SRTP */
 
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 /**
  * \brief          Set the maximum supported version sent from the client side
  *                 and/or accepted at the server side.
@@ -3793,14 +3928,37 @@ void mbedtls_ssl_get_dtls_srtp_negotiation_result( const mbedtls_ssl_context *ss
  *
  * \note           This ignores ciphersuites from higher versions.
  *
+ * \note           This function is deprecated and has been replaced by
+ *                 \c mbedtls_ssl_conf_max_tls_version().
+ *
  * \param conf     SSL configuration
  * \param major    Major version number (#MBEDTLS_SSL_MAJOR_VERSION_3)
  * \param minor    Minor version number
  *                 (#MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2,
  *                 #MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3)
  */
-void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor );
+void MBEDTLS_DEPRECATED mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor );
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
 
+/**
+ * \brief          Set the maximum supported version sent from the client side
+ *                 and/or accepted at the server side.
+ *
+ * \note           After the handshake, you can call
+ *                 mbedtls_ssl_get_version_number() to see what version was
+ *                 negotiated.
+ *
+ * \param conf         SSL configuration
+ * \param tls_version  TLS protocol version number (\p mbedtls_ssl_protocol_version)
+ *                     (#MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
+ */
+static inline void mbedtls_ssl_conf_max_tls_version( mbedtls_ssl_config *conf,
+                                     mbedtls_ssl_protocol_version tls_version )
+{
+    conf->MBEDTLS_PRIVATE(max_tls_version) = tls_version;
+}
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 /**
  * \brief          Set the minimum accepted SSL/TLS protocol version
  *
@@ -3826,13 +3984,35 @@ void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int mino
  *                 mbedtls_ssl_get_version_number() to see what version was
  *                 negotiated.
  *
+ * \note           This function is deprecated and has been replaced by
+ *                 \c mbedtls_ssl_conf_min_tls_version().
+ *
  * \param conf     SSL configuration
  * \param major    Major version number (#MBEDTLS_SSL_MAJOR_VERSION_3)
  * \param minor    Minor version number
  *                 (#MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2,
  *                 #MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3)
  */
-void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor );
+void MBEDTLS_DEPRECATED mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor );
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief          Set the minimum supported version sent from the client side
+ *                 and/or accepted at the server side.
+ *
+ * \note           After the handshake, you can call
+ *                 mbedtls_ssl_get_version_number() to see what version was
+ *                 negotiated.
+ *
+ * \param conf         SSL configuration
+ * \param tls_version  TLS protocol version number (\p mbedtls_ssl_protocol_version)
+ *                     (#MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
+ */
+static inline void mbedtls_ssl_conf_min_tls_version( mbedtls_ssl_config *conf,
+                                     mbedtls_ssl_protocol_version tls_version )
+{
+    conf->MBEDTLS_PRIVATE(min_tls_version) = tls_version;
+}
 
 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
 /**
@@ -3903,7 +4083,7 @@ void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf,
  *                 \c mbedtls_ssl_get_record_expansion().
  *
  * \note           For DTLS, it is also possible to set a limit for the total
- *                 size of daragrams passed to the transport layer, including
+ *                 size of datagrams passed to the transport layer, including
  *                 record overhead, see \c mbedtls_ssl_set_mtu().
  *
  * \param conf     SSL configuration
@@ -3949,7 +4129,7 @@ void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets
  *                 initiated by peer
  *                 (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
  *
- * \warning        It is recommended to always disable renegotation unless you
+ * \warning        It is recommended to always disable renegotiation unless you
  *                 know you need it and you know what you're doing. In the
  *                 past, there have been several issues associated with
  *                 renegotiation or a poor understanding of its properties.
@@ -4012,7 +4192,7 @@ void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_
  *                 scenario.
  *
  * \note           With DTLS and server-initiated renegotiation, the
- *                 HelloRequest is retransmited every time mbedtls_ssl_read() times
+ *                 HelloRequest is retransmitted every time mbedtls_ssl_read() times
  *                 out or receives Application Data, until:
  *                 - max_records records have beens seen, if it is >= 0, or
  *                 - the number of retransmits that would happen during an
@@ -4163,8 +4343,11 @@ const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl );
  * \param ssl      The SSL context to query.
  * \return         The negotiated protocol version.
  */
-mbedtls_ssl_protocol_version mbedtls_ssl_get_version_number(
+static inline mbedtls_ssl_protocol_version mbedtls_ssl_get_version_number(
-    const mbedtls_ssl_context *ssl );
+    const mbedtls_ssl_context *ssl )
+{
+    return ssl->MBEDTLS_PRIVATE(tls_version);
+}
 
 /**
  * \brief          Return the current TLS version
@@ -4357,12 +4540,41 @@ int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl,
  */
 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
 
+/**
+ * \brief          After calling mbedtls_ssl_handshake() to start the SSL
+ *                 handshake you can call this function to check whether the
+ *                 handshake is over for a given SSL context. This function
+ *                 should be also used to determine when to stop calling
+ *                 mbedtls_handshake_step() for that context.
+ *
+ * \param ssl      SSL context
+ *
+ * \return         \c 1 if handshake is over, \c 0 if it is still ongoing.
+ */
+static inline int mbedtls_ssl_is_handshake_over( mbedtls_ssl_context *ssl )
+{
+    return( ssl->MBEDTLS_PRIVATE( state ) == MBEDTLS_SSL_HANDSHAKE_OVER );
+}
+
 /**
  * \brief          Perform a single step of the SSL handshake
  *
  * \note           The state of the context (ssl->state) will be at
  *                 the next state after this function returns \c 0. Do not
- *                 call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
+ *                 call this function if mbedtls_ssl_is_handshake_over()
+ *                 returns \c 1.
+ *
+ * \warning        Whilst in the past you may have used direct access to the
+ *                 context state (ssl->state) in order to ascertain when to
+ *                 stop calling this function and although you can still do
+ *                 so with something like ssl->MBEDTLS_PRIVATE(state) or by
+ *                 defining MBEDTLS_ALLOW_PRIVATE_ACCESS, this is now
+ *                 considered deprecated and could be broken in any future
+ *                 release. If you still find you have good reason for such
+ *                 direct access, then please do contact the team to explain
+ *                 this (raise an issue or post to the mailing list), so that
+ *                 we can add a solution to your problem that will be
+ *                 guaranteed to work in the future.
  *
  * \param ssl      SSL context
  *
@@ -4529,7 +4741,7 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
  *
  * \note           When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ,
  *                 it must be called later with the *same* arguments,
- *                 until it returns a value greater that or equal to 0. When
+ *                 until it returns a value greater than or equal to 0. When
  *                 the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be
  *                 some partial data in the output buffer, however this is not
  *                 yet sent.
@@ -4639,7 +4851,7 @@ void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
  * \return         \c 0 if successful.
  * \return         #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small.
  * \return         #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed
- *                 while reseting the context.
+ *                 while resetting the context.
  * \return         #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in
  *                 progress, or there is pending data for reading or sending,
  *                 or the connection does not use DTLS 1.2 with an AEAD
@@ -4736,7 +4948,7 @@ int mbedtls_ssl_context_load( mbedtls_ssl_context *ssl,
 void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );
 
 /**
- * \brief          Load reasonnable default SSL configuration values.
+ * \brief          Load reasonable default SSL configuration values.
  *                 (You need to call mbedtls_ssl_config_init() first.)
  *
  * \param conf     SSL configuration context