Merge branch 'Mbed-TLS:development' into sha3

2022-10-13 08:28:13 +02:00 · 2022-10-13 08:28:13 +02:00 · c9754c3ec1
commit c9754c3ec1
parent e884fd7acb 8fd3254cfc
394 changed files with 51669 additions and 11750 deletions
--- a/.gitattributes
+++ b/.gitattributes
@ -0,0 +1,2 @@
+# Classify all '.function' files as C for syntax highlighting purposes
+*.function linguist-language=C
--- a/.travis.yml
+++ b/.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
@ -65,7 +65,7 @@ addons:
    - gnutls-bin
  coverity_scan:
    project:
-      name: "Mbed-TLS/mbedtls"
+      name: "ARMmbed/mbedtls"
    notification_email: support-mbedtls@arm.com
    build_command_prepend:
    build_command: make
--- a/3rdparty/everest/CMakeLists.txt
+++ b/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)
--- a/3rdparty/everest/README.md
+++ b/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).
--- a/3rdparty/everest/include/everest/everest.h
+++ b/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
--- a/3rdparty/everest/library/Hacl_Curve25519_joined.c
+++ b/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"

--- a/BRANCHES.md
+++ b/BRANCHES.md
@ -12,11 +12,6 @@ At any point in time, we have a number of maintained branches, currently consist
 - 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/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/Mbed-TLS/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/Mbed-TLS/mbedtls/tree/archive/mbedtls-2.7).
@ -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
--- a/CMakeLists.txt
+++ b/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)
@ -118,35 +120,33 @@ endif()

 # Create a symbolic link from ${base_name} in the binary directory
 # to the corresponding path in the source directory.
+# Note: Copies the file(s) on Windows.
 function(link_to_source base_name)
-    # Get OS dependent path to use in `execute_process`
-    if (CMAKE_HOST_WIN32)
-        #mklink is an internal command of cmd.exe it can only work with \
-        string(REPLACE "/" "\\" link "${CMAKE_CURRENT_BINARY_DIR}/${base_name}")
-        string(REPLACE "/" "\\" target "${CMAKE_CURRENT_SOURCE_DIR}/${base_name}")
-    else()
-        set(link "${CMAKE_CURRENT_BINARY_DIR}/${base_name}")
-        set(target "${CMAKE_CURRENT_SOURCE_DIR}/${base_name}")
-    endif()
+    set(link "${CMAKE_CURRENT_BINARY_DIR}/${base_name}")
+    set(target "${CMAKE_CURRENT_SOURCE_DIR}/${base_name}")

-    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})
+            execute_process(COMMAND ln -s ${target} ${link}
+                RESULT_VARIABLE result
+                ERROR_VARIABLE output)
+
+            if (NOT ${result} EQUAL 0)
+                message(FATAL_ERROR "Could not create symbolic link for: ${target} --> ${output}")
+            endif()
        else()
            if (IS_DIRECTORY ${target})
-                set(command cmd.exe /c mklink /j ${link} ${target})
+                file(GLOB_RECURSE files FOLLOW_SYMLINKS LIST_DIRECTORIES false RELATIVE ${target} "${target}/*")
+                foreach(file IN LISTS files)
+                    configure_file("${target}/${file}" "${link}/${file}" COPYONLY)
+                endforeach(file)
            else()
-                set(command cmd.exe /c mklink /h ${link} ${target})
+                configure_file(${target} ${link} COPYONLY)
            endif()
        endif()
-
-        execute_process(COMMAND ${command}
-            RESULT_VARIABLE result
-            ERROR_VARIABLE output)
-
-        if (NOT ${result} EQUAL 0)
-            message(FATAL_ERROR "Could not create symbolic link for: ${target} --> ${output}")
-        endif()
    endif()
 endfunction(link_to_source)

@ -170,6 +170,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 +222,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 +243,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 +256,7 @@ if(CMAKE_BUILD_TYPE STREQUAL "Coverage")
 endif(CMAKE_BUILD_TYPE STREQUAL "Coverage")

 if(LIB_INSTALL_DIR)
-else()
-    set(LIB_INSTALL_DIR lib)
+    set(CMAKE_INSTALL_LIBDIR "${LIB_INSTALL_DIR}")
 endif()

 add_subdirectory(include)
@ -344,7 +350,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"
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -19,8 +19,6 @@ Making a Contribution
 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
 -----------------------
@ -79,3 +77,12 @@ Mbed TLS is well documented, but if you think documentation is needed, speak out
 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/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.
--- a/277
+++ b/277
@ -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

--- a/ChangeLog.d/Driver_wrapper_codegen_1.0.txt
+++ b/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
--- a/ChangeLog.d/MD-X.509-hashing.txt
+++ b/ChangeLog.d/MD-X.509-hashing.txt
@ -1,2 +0,0 @@
-Features
-   * The X.509 module now uses PSA hash acceleration if present.
--- a/ChangeLog.d/PSA-test-suites-NOT-using-UID-0.txt
+++ b/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.
--- a/ChangeLog.d/add-mbedtls_md_starts-to-mbedtls_md_process-test.txt
+++ b/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.
--- a/ChangeLog.d/add-rsa-pss-rsae-support-for-tls12.txt
+++ b/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.
--- a/ChangeLog.d/add_final_delay_accessor
+++ b/ChangeLog.d/add_final_delay_accessor
@ -1,4 +0,0 @@
-Features
-   * Add the function mbedtls_timing_get_final_delay() to access the private
-     final delay field in an mbedtls_timing_delay_context, as requested in
-     #5183
--- a/ChangeLog.d/add_handshake_completion_accessor
+++ b/ChangeLog.d/add_handshake_completion_accessor
@ -1,4 +0,0 @@
-Features
-   * 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
--- a/ChangeLog.d/add_own_cid_accessors
+++ b/ChangeLog.d/add_own_cid_accessors
@ -1,4 +0,0 @@
-Features
-   * Add the function mbedtls_ssl_get_own_cid() to access our own connection id
-     within mbedtls_ssl_context, as requested in #5184
-
--- a/ChangeLog.d/alert_reentrant.txt
+++ b/ChangeLog.d/alert_reentrant.txt
@ -1,5 +0,0 @@
-Bugfix
-   * 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.
--- a/ChangeLog.d/bn_mul-fix-x86-pic-compilation-for-gcc-4.txt
+++ b/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.
--- a/ChangeLog.d/ccm_star_no_tag.txt
+++ b/ChangeLog.d/ccm_star_no_tag.txt
@ -1,4 +0,0 @@
-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.
--- a/ChangeLog.d/chacha20_invalid_iv_len_fix.txt
+++ b/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.
--- a/ChangeLog.d/cmake_msvc_utf8.txt
+++ b/ChangeLog.d/cmake_msvc_utf8.txt
@ -1,2 +0,0 @@
-Changes
-   * Assume source files are in UTF-8 when using MSVC with CMake.
--- a/ChangeLog.d/doc-x509-profile-pk.txt
+++ b/ChangeLog.d/doc-x509-profile-pk.txt
@ -1,5 +0,0 @@
-Bugfix
-   * 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.
--- a/ChangeLog.d/driver-only-hashes.txt
+++ b/ChangeLog.d/driver-only-hashes.txt
@ -0,0 +1,20 @@
+Features
+   * Some crypto modules that previously depended on MD or a low-level hash
+     module, either unconditionally (RSA, PK, PKCS5, PKCS12, EC J-PAKE), or
+     for some features (PEM for encrypted files), are now able to use PSA
+     Crypto instead when the legacy API is not available. This means it is
+     now possible to use all features from those modules in configurations
+     where the built-in implementations of hashes are excluded and the hashes
+     are only provided by PSA drivers. In these configurations, you need to
+     call `psa_crypto_init()` before you call any function from those
+     modules; this is not required in configurations where the built-in
+     implementation is still available. Note that some crypto modules and
+     features still depend on the built-in implementation of hashes:
+     MBEDTLS_HKDF_C (but the PSA HKDF function do not depend on it),
+     MBEDTLS_ENTROPY_C, MBEDTLS_HMAC_DRBG_C and MBEDTLS_ECDSA_DETERMINISTIC.
+     In particular, for now, compiling without built-in hashes requires use
+     of MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.
+   * When MBEDTLS_USE_PSA_CRYPTO is enabled, X.509, TLS 1.2 and TLS 1.3 no
+     longer depend on MD. This means it is now possible to use them in
+     configurations where the built-in implementations of hashes are excluded
+     and the hashes are only provided by PSA drivers.
--- a/ChangeLog.d/dtls-cid-null.txt
+++ b/ChangeLog.d/dtls-cid-null.txt
@ -1,5 +0,0 @@
-Bugfix
-   * 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.
--- a/ChangeLog.d/ecjpake_to_pms.txt
+++ b/ChangeLog.d/ecjpake_to_pms.txt
@ -0,0 +1,5 @@
+API changes
+   * Add an ad-hoc key derivation function handling ECJPAKE to PMS
+     calculation that can be used to derive the session secret in TLS 1.2,
+     as described in draft-cragie-tls-ecjpake-01. This can be achieved by
+     using PSA_ALG_TLS12_ECJPAKE_TO_PMS as the key derivation algorithm.
--- a/ChangeLog.d/extend-query_compile_time_config-to-psa_want.txt
+++ b/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
--- a/ChangeLog.d/fix-aes-shallow-copying.txt
+++ b/ChangeLog.d/fix-aes-shallow-copying.txt
@ -0,0 +1,2 @@
+Bugfix
+   * Refactor mbedtls_aes_context to support shallow-copying. Fixes #2147.
--- a/ChangeLog.d/fix-ctr-drbg-may-free-invalid-aes-context.txt
+++ b/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.
--- a/ChangeLog.d/fix-parllel-cmake-build-fail.txt
+++ b/ChangeLog.d/fix-parllel-cmake-build-fail.txt
@ -1,3 +0,0 @@
-Bugfix
-   * Fix a race condition in out-of-source builds with CMake when generated data
-     files are already present. Fixes #5374
--- a/ChangeLog.d/fix-windows-cmake-build-with-shared-libraries.txt
+++ b/ChangeLog.d/fix-windows-cmake-build-with-shared-libraries.txt
@ -1,3 +0,0 @@
-Bugfix
-   * Fix compilation on Windows when building shared library, by setting
-     library search path to CMAKE_CURRENT_BINARY_DIR.
--- a/ChangeLog.d/fix_build_error_for_mbedtls_deprecated_removed.txt
+++ b/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
--- a/ChangeLog.d/fix_build_tls1_2_with_single_encryption_type.txt
+++ b/ChangeLog.d/fix_build_tls1_2_with_single_encryption_type.txt
@ -0,0 +1,4 @@
+Bugfix
+    * Fix bugs and missing dependencies when
+      building and testing configurations with
+      only one encryption type enabled in TLS 1.2.
--- a/ChangeLog.d/fix_cmake_gen_files
+++ b/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.
--- a/ChangeLog.d/fix_cmake_using_iar_toolchain.txt
+++ b/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.
--- a/ChangeLog.d/fix_hard_link_across_drives
+++ b/ChangeLog.d/fix_hard_link_across_drives
@ -0,0 +1,3 @@
+Bugfix
+   * Fix a build issue on Windows where the source and build directory could not be on
+     different drives (#5751).
--- a/ChangeLog.d/fix_psa_crypto_cipher_h_include.txt
+++ b/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.
--- a/ChangeLog.d/mbedtls_ecp_export.txt
+++ b/ChangeLog.d/mbedtls_ecp_export.txt
@ -1,3 +0,0 @@
-Features
-   * Add mbedtls_ecp_export() function to export ECP
-     keypair parameters. Fixes #4838.
--- a/ChangeLog.d/mbedtls_pem_get_der.txt
+++ b/ChangeLog.d/mbedtls_pem_get_der.txt
@ -1,2 +0,0 @@
-Features
-   * Add accessor to get the raw buffer pointer from a PEM context.
--- a/ChangeLog.d/mbedtls_pk_sign_ext.txt
+++ b/ChangeLog.d/mbedtls_pk_sign_ext.txt
@ -1,3 +0,0 @@
-Features
-    * Add mbedtls_pk_sign_ext() which allows generating RSA-PSS signatures when
-      PSA Crypto is enabled.
--- a/ChangeLog.d/mbedtls_sha256_a64_crypto_acceleration.txt
+++ b/ChangeLog.d/mbedtls_sha256_a64_crypto_acceleration.txt
@ -1,2 +0,0 @@
-Features
-   * A64 SHA-2 crypto extension support for SHA-256
--- a/ChangeLog.d/mbedtls_sha512_a64_crypto_acceleration.txt
+++ b/ChangeLog.d/mbedtls_sha512_a64_crypto_acceleration.txt
@ -1,2 +0,0 @@
-Features
-   * A64 crypto extension support for SHA-512
--- a/ChangeLog.d/mbedtls_ssl_cert_cb.txt
+++ b/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.
--- a/ChangeLog.d/mbedtls_ssl_comfig_defaults-memleak.txt
+++ b/ChangeLog.d/mbedtls_ssl_comfig_defaults-memleak.txt
@ -1,2 +0,0 @@
-Bugfix
-   * Fix memory leak if mbedtls_ssl_config_defaults() call is repeated
--- a/ChangeLog.d/mbedtls_ssl_get_ciphersuite_id.txt
+++ b/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.
--- a/ChangeLog.d/mbedtls_ssl_hs_cb_t.txt
+++ b/ChangeLog.d/mbedtls_ssl_hs_cb_t.txt
@ -1,4 +0,0 @@
-Features
-   * Introduce mbedtls_ssl_hs_cb_t typedef for use with
-     mbedtls_ssl_conf_cert_cb() and perhaps future callbacks
-     during TLS handshake.
--- a/ChangeLog.d/mbedtls_ssl_ticket_rotate.txt
+++ b/ChangeLog.d/mbedtls_ssl_ticket_rotate.txt
@ -1,2 +0,0 @@
-Features
-   * Add mbedtls_ssl_ticket_rotate() for external ticket rotation.
--- a/ChangeLog.d/mbedtls_ssl_tls13_client.txt
+++ b/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.
--- a/ChangeLog.d/mbedtls_tlsver_enum.txt
+++ b/ChangeLog.d/mbedtls_tlsver_enum.txt
@ -1,6 +0,0 @@
-Features
-   * Unify internal/external TLS protocol version enums
-   * Deprecate mbedtls_ssl_conf_max_version()
-     Replaced with mbedtls_ssl_conf_max_tls_version()
-   * Deprecate mbedtls_ssl_conf_min_version()
-     Replaced with mbedtls_ssl_conf_min_tls_version()
--- a/ChangeLog.d/md_info_from_ctx.txt
+++ b/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.
--- a/ChangeLog.d/muladdc_microblaze.txt
+++ b/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.
--- a/ChangeLog.d/nonversioned-library-soname.txt
+++ b/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".
--- a/ChangeLog.d/pkparse-pkcs8-unencrypted-no-alloc.txt
+++ b/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.
--- a/ChangeLog.d/psa_aead_singleshot_error.txt
+++ b/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.
--- a/ChangeLog.d/psa_crypto_config_file.txt
+++ b/ChangeLog.d/psa_crypto_config_file.txt
@ -1,6 +0,0 @@
-Features
-   * 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.
--- a/ChangeLog.d/psa_crypto_key_derivation_for_ECC_keys.txt
+++ b/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.
--- a/ChangeLog.d/psa_crypto_pake.txt
+++ b/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.
--- a/ChangeLog.d/psa_crypto_reduced_configs.txt
+++ b/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.
--- a/ChangeLog.d/psa_crypto_reduced_configs_bugs.txt
+++ b/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.
--- a/ChangeLog.d/psk_to_ms_mixed_psk.txt
+++ b/ChangeLog.d/psk_to_ms_mixed_psk.txt
@ -1,4 +0,0 @@
-Features
-    * 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.
--- a/ChangeLog.d/raw-agreement-destroy-missing.txt
+++ b/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.
--- a/ChangeLog.d/remove_ssl_session_compression.txt
+++ b/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.
--- a/ChangeLog.d/ssl_context-user_data.txt
+++ b/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.
--- a/ChangeLog.d/ssl_context-version_number.txt
+++ b/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.
--- a/ChangeLog.d/ssl_get_version_1_3.txt
+++ b/ChangeLog.d/ssl_get_version_1_3.txt
@ -1,2 +0,0 @@
-Bugfix
-   * Fix mbedtls_ssl_get_version() not reporting TLSv1.3. Fixes #5406.
--- a/ChangeLog.d/timeless.txt
+++ b/ChangeLog.d/timeless.txt
@ -1,3 +0,0 @@
-Bugfix
-   * Fix compile errors when MBEDTLS_HAVE_TIME is not defined. Add tests
-     to catch bad uses of time.h.
--- a/ChangeLog.d/tls13_and_use_psa_crypto.txt
+++ b/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.
--- a/ChangeLog.d/tls13_f_export_keys.txt
+++ b/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.
--- a/ChangeLog.d/tls13_sig_alg_selection.txt
+++ b/ChangeLog.d/tls13_sig_alg_selection.txt
@ -0,0 +1,3 @@
+Features
+   * Add support for opaque keys as the private keys associated to certificates
+     for authentication in TLS 1.3.
--- a/ChangeLog.d/use-psa-ecdhe-curve.txt
+++ b/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.
--- a/ChangeLog.d/x509-broken-symlink-handling.txt
+++ b/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.
--- a/ChangeLog.d/zeroize_key_buffers_before_free.txt
+++ b/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.
--- a/README.md
+++ b/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`.
-
-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/Mbed-TLS/mbedtls/labels/compliance) for an up-to-date list.
+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.

 ### Upcoming features

--- a/SECURITY.md
+++ b/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/).

--- a/configs/config-suite-b.h
+++ b/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.
 */
--- a/docs/3.0-migration-guide.md
+++ b/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
@ -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
--- a/docs/architecture/mbed-crypto-storage-specification.md
+++ b/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.
--- a/docs/architecture/psa-crypto-implementation-structure.md
+++ b/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
--- a/docs/architecture/psa-migration/outcome-analysis.sh
+++ b/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
--- a/docs/architecture/psa-migration/psa-limitations.md
+++ b/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
-implementation, would be non-trivial.
+There is currently no support for that in PSA at all, but it will be added at
+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`.
@ -29,11 +29,6 @@ github.

 [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/Mbed-TLS/projects/1#column-17950140
-
 Arbitrary parameters for FFDH
 -----------------------------

@ -60,16 +55,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
-   when moving to PSA. We can modify our server so that it only selects a DHE
-   ciphersuite if the client offered name FFDH groups; unfortunately
+   (For people who want some algorithmic variety in case ECC collapses, FFDH
+would still be available in TLS 1.3, just not in 1.2.) (Can only be done in
+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 +88,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 +166,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 +298,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 +312,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, `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).
+Currently none.
--- a/docs/architecture/psa-migration/strategy.md
+++ b/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
-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.
+the preceding ones to be completed.

 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/Mbed-TLS/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
-    `psa_crypto_init()` before TLS/X.509 uses PSA functions
-  - `MBEDTLS_PSA_CRYPTO_C` has a hard depend on `MBEDTLS_ENTROPY_C ||
+  - When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
+    `psa_crypto_init()` before TLS/X.509 uses PSA functions. (This prevents us
+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
-to make `MBEDTLS_USE_PSA_CRYPTO` non-optional (always enabled).
+At the time of writing (early 2022) it is unclear what could be done about the
+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
-below generalizing support for `MBEDTLS_USE_PSA_CRYPTO` for “mainstream” use
-cases on our priority list. So in the medium term `MBEDTLS_ECP_RESTARTABLE` is
-incompatible with `MBEDTLS_USE_PSA_CRYPTO`.
+Supporting this in PSA is on our roadmap and currently planned for end of
+2022, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18883250>.

-Note: it is possible to make the options compatible at build time simply by
-deciding that when `USE_PSA_CRYPTO` is enabled, PSA APIs are used except if
-restartable behaviour was requested at run-time (in addition to enabling
-`MBEDTLS_ECP_RESTARTABLE` in the build).
+It will then require follow-up work to make use of the new PSA API in
+PK/X.509/TLS in all places where we currently allow restartable operations.

-### `MBEDTLS_PSA_CRYPTO_CONFIG`
-
-(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/Mbed-TLS/mbedtls/issues/3674 and
-https://github.com/Mbed-TLS/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
+### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` 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/Mbed-TLS/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
-verification in the PK layer, and could be extended to all operations in the
-PK layer.
+This strategy is currently (early 2022) used for all operations in the 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
-a subset of calling places, but will be extended to all of them.)
-
-In the future (early 2022) we're going to use it for the Cipher layer as well.
+This strategy is currently (early 2022) used for the MD layer and the Cipher
+layer.

 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
-signature generation in the PK layer - see `mbedtls_pk_setup_opaque()`. This
+This strategy, with support for key isolation, is currently (early 2022) used for
+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
-extended to other private key operations in the PK layer, which is the plan as
-of early 2022.
+the TLS/X.509 code, but a contained change in the application.

-This strategy, without key isolation, is also currently used in the Cipher
-layer - see `mbedtls_cipher_setup_psa()`. This allows use of PSA for cipher
-operations in TLS with no change to the application code, and a
-contained change in TLS code. (It currently only supports a subset of
-ciphers.) However, we'll move to the "Replace calls for each operation"
-strategy (early 2022), in the hope of being able to build without this layer
-in order to save some code size in the future.
+This strategy, without key isolation, was also previously used (until 3.1
+included) in the Cipher layer - see `mbedtls_cipher_setup_psa()`. This allowed
+use of PSA for cipher operations in TLS with no change to the application
+code, and a contained change in TLS code. (It only supported a subset of
+ciphers.)

 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,198 @@ 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):
-  - late 2021: opt-in use of PSA (new setup function)
-  - early 2022: moving to "replace calls at each call site"
+- Cipher (G1): 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
+`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.
+
+Note: the new macros supplement but do not replace the existing macros:
+- code that always uses PSA Crypto (for example, code specific to TLS 1.3)
+  should use `PSA_WANT_xxx`;
+- code that always uses the legacy API (for example, crypto modules that have
+  not undergone step 1 yet) should use `MBEDTLS_xxx_C`;
+- code that may use one of the two APIs, either based on
+  `MBEDTLS_USE_PSA_CRYPTO` (X.509, TLS 1.2, shared between TLS 1.2 and 1.3),
+  or based on availability (crypto modules after step 1), should use one of
+  the new macros from `legacy_or_psa.h`.
+
+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 +406,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 +420,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 +499,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 +512,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.
--- a/docs/architecture/psa-migration/tasks-g2.md
+++ b/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)
--- a/docs/architecture/psa-migration/testing.md
+++ b/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
-via PSA while some others aren't, with a run-time fallback. In this case, it's
+path. (For example, for record protection, previously (until 3.1), some ciphers were supported
+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()`.
-    (We should have something similar for
-    `mbedtls_x509write_crt_set_issuer_key()`.)
+    existing `mbedtls_x509write_csr_set_key()`. (And also
+    `mbedtls_x509write_crt_set_issuer_key()` since #5710.)

 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
-layer, but probably not directly by applications.
+For example, `mbedtls_cipher_setup_psa()` (no longer used, soon to be
+deprecated - #5261) was meant to be used by the TLS layer, but probably not
+directly by applications.

 In that case, we want:

--- a/docs/architecture/testing/driver-interface-test-strategy.md
+++ b/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.

--- a/docs/architecture/testing/psa-storage-format-testing.md
+++ b/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`).
--- a/docs/architecture/tls13-support.md
+++ b/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
-defined in the "MVP definition" section below. The TLS 1.3 support enablement
+Mbed TLS provides a partial implementation of the TLS 1.3 protocol defined in
+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) |
-  | ---------------------------- | ------- | ------------- |
-  | server_name                  | YES     | YES           |
-  | max_fragment_length          | no      | YES           |
-  | status_request               | no      | no            |
-  | supported_groups             | YES     | YES           |
-  | signature_algorithms         | YES     | YES           |
-  | use_srtp                     | no      | no            |
-  | heartbeat                    | no      | no            |
-  | apln                         | no      | YES           |
-  | signed_certificate_timestamp | no      | no            |
-  | client_certificate_type      | no      | no            |
-  | server_certificate_type      | no      | no            |
-  | padding                      | no      | no            |
-  | key_share                    | YES (2) | YES           |
-  | pre_shared_key               | no      | YES           |
-  | psk_key_exchange_modes       | no      | YES           |
-  | early_data                   | no      | YES           |
-  | cookie                       | no      | YES           |
-  | supported_versions           | YES (3) | YES           |
-  | certificate_authorities      | no      | no            |
-  | post_handshake_auth          | no      | no            |
-  | signature_algorithms_cert    | no      | no            |
+  | Extension                    | Support |
+  | ---------------------------- | ------- |
+  | server_name                  | YES     |
+  | max_fragment_length          | no      |
+  | status_request               | no      |
+  | supported_groups             | YES     |
+  | signature_algorithms         | YES     |
+  | use_srtp                     | no      |
+  | heartbeat                    | no      |
+  | apln                         | YES     |
+  | signed_certificate_timestamp | no      |
+  | client_certificate_type      | no      |
+  | server_certificate_type      | no      |
+  | padding                      | no      |
+  | key_share                    | YES     |
+  | pre_shared_key               | no      |
+  | psk_key_exchange_modes       | no      |
+  | early_data                   | no      |
+  | cookie                       | no      |
+  | supported_versions           | YES     |
+  | certificate_authorities      | no      |
+  | post_handshake_auth          | 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:
-  secp256r1, x25519, secp384r1 and secp521r1.
+  Potentially all ECDHE groups:
+  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_secp384r1_sha384 and ecdsa_secp521r1_sha512.
+  ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 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
-  specification).
+  rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are
+  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
-    configuration option) without TLS 1.2 (MBEDTLS_SSL_PROTO_TLS1_2 configuration
-    option).
-
-  - TLS 1.2 can be enabled in the build independently of TLS 1.3.
+  - TLS 1.2 and TLS 1.3 can be enabled in the build independently of each
+    other.

  - 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,
-    `mbedtls_ssl_setup` will raise `MBEDTLS_ERR_SSL_BAD_CONFIG` error.
+    be configured at runtime via `mbedtls_ssl_conf_{min,max}_tls_version` for a
+    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
-  sense that when enabling the TLS 1.3 MVP in the library there is no need to
-  modify the configuration for TLS 1.2. The MBEDTLS_USE_PSA_CRYPTO configuration
-  option is an exception though, the TLS 1.3 MVP is not compatible with it.
+  The TLS 1.3 implementation is compatible with nearly all TLS 1.2
+  configuration options in the sense that when enabling TLS 1.3 in the library
+  there is rarely any need to modify the configuration from that used for
+  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
-  TLS 1.3 MVP:
+  Most of the Mbed TLS SSL/TLS related options are not supported or not
+  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       | no      |
+  | MBEDTLS_SSL_SERVER_NAME_INDICATION       | yes     |
  | 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
-upstreamed:
-
- Ephemeral only handshake on client side: client authentication,
-  HelloRetryRequest support, version negotiation.
-
- Ephemeral only handshake server side.
+The following parts of the TLS 1.3 prototype remain to be upstreamed:

 - Pre-shared keys, session resumption and 0-RTT data (both client and server
  side).
@ -409,3 +355,101 @@ General coding rules:
                                     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.
--- a/docs/proposed/psa-driver-interface.md
+++ b/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.

--- a/docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
+++ b/docs/proposed/psa-driver-wrappers-codegen-migration-guide.md
@ -21,7 +21,7 @@ Python3 and Jinja2 rev 2.10.1

 ### 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.0 here's what's changed

--- a/docs/use-psa-crypto.md
+++ b/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
-current effects as well as the parts that aren't covered yet.
+`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.

-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
-`MBEDTLS_ECP_RESTARTABLE` and
-`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled.
+**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
+`MBEDTLS_ECP_RESTARTABLE` to be disabled.

-Effect: `MBEDTLS_USE_PSA_CRYPTO` has no effect on TLS 1.3 for which PSA
-cryptography is mandatory.
+**Application code:** when this option is enabled, you need to call
+`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
-defined is considered experimental and may change in incompatible ways at any
-time. Said otherwise, these APIs are explicitly excluded from the usual API
-stability promises.
+**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
+are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the
+TLS 1.3 code that are common with TLS 1.2, however, follow this option;
+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
-wrap a PSA keypair into a PK context. The key can be used for private-key
+**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
+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
-generation. Note: currently this will use randomized ECDSA while Mbed TLS uses
-deterministic ECDSA by default.) The following operations are not supported
+**Limitations:** can only wrap a key pair, can only use it for private key
+operations. (That is, signature generation, and for RSA decryption too.)
+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()`,
-`mbedtls_pk_debug()`.
+context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key
+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
-this is supported on both sides, it's currently only tested client-side);
+  key together with a certificate for certificate-based key exchanges;
 - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
-  request).
-
-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.
+  request);
+- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.

 ### 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"
-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`.
+**Limitations:** none.

-Use in TLS: opt-in. The application needs to register the key using the new
-APIs to get the benefits.
+**Use in TLS:** opt-in. The application needs to register the key using one of
+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
-(still generated outside of PSA, but then held by PSA).
+This function only worked for a small number of ciphers. It is now deprecated
+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
-multi-part APIs are not supported, only the one-shot APIs. The only modes
-supported are ECB, CBC without padding, GCM and CCM (this excludes stream
-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.
+**Warning:** This function will be removed in a future version of Mbed TLS. If
+you are using it and would like us to keep it, please let us know about your
+use case.

 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
-verification.
+Other than the above exceptions, all crypto operations are based on PSA when
+`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
-computation of the ECDHE key exchange is done by PSA.
+Other than the above exception, all crypto operations are based on PSA when
+`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:
- the running handshake hashes;
- the hash of the ServerKeyExchange part that is signed;
- the `verify_data` part of the Finished message;
- the TLS PRF.
+Other than the above exception, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.

-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
--- a/doxygen/input/doc_mainpage.h
+++ b/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
--- a/doxygen/mbedtls.doxyfile
+++ b/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
--- a/include/mbedtls/aes.h
+++ b/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
--- a/include/mbedtls/aria.h
+++ b/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
--- a/include/mbedtls/asn1.h
+++ b/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,
--- a/include/mbedtls/asn1write.h
+++ b/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.
--- a/include/mbedtls/bignum.h
+++ b/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
- *                 the swap or not. Possible values:
+ * \param swap     The condition deciding whether to perform
+ *                 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.
 *
--- a/include/mbedtls/build_info.h
+++ b/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_PATCH  0
+#define MBEDTLS_VERSION_MINOR  2
+#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_STRING         "3.1.0"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 3.1.0"
+#define MBEDTLS_VERSION_NUMBER         0x03020100
+#define MBEDTLS_VERSION_STRING         "3.2.1"
+#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

--- a/include/mbedtls/camellia.h
+++ b/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
--- a/include/mbedtls/chachapoly.h
+++ b/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).
 *
--- a/Show more
+++ b/Show more