Merge branch 'development' into sha3

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es>

.github/pull_request_template.md

@@ -1,36 +1,19 @@
-Notes:
-* Pull requests cannot be accepted until the PR follows the [contributing guidelines](../CONTRIBUTING.md). In particular, each commit must have at least one `Signed-off-by:` line from the committer to certify that the contribution is made under the terms of the [Developer Certificate of Origin](../dco.txt).
-* This is just a template, so feel free to use/remove the unnecessary things
 ## Description
-A few sentences describing the overall goals of the pull request's commits.
+
+Please write a few sentences describing the overall goals of the pull request's commits.
 
 
-## Status
-**READY/IN DEVELOPMENT/HOLD**
 
-## Requires Backporting
+## Gatekeeper checklist
-When there is a bug fix, it should be backported to all maintained and supported branches.
-Changes do not have to be backported if:
-- This PR is a new feature\enhancement
-- This PR contains changes in the API. If this is true, and there is a need for the fix to be backported, the fix should be handled differently in the legacy branch
 
-Yes | NO  
+- [ ] **changelog** provided, or not required
-Which branch?
+- [ ] **backport** done, or not required
-
+- [ ] **tests** provided, or not required
-## Migrations
-If there is any API change, what's the incentive and logic for it.
-
-YES | NO
-
-## Additional comments
-Any additional information that could be of interest
-
-## Todos
-- [ ] Tests
-- [ ] Documentation
-- [ ] Changelog updated
-- [ ] Backported
 
 
-## Steps to test or reproduce
+
-Outline the steps to test or reproduce the PR here.
+## Notes for the submitter
+
+Please refer to the [contributing guidelines](https://github.com/Mbed-TLS/mbedtls/blob/development/CONTRIBUTING.md), especially the
+checklist for PR contributors.
+

.pylintrc

@@ -1,5 +1,6 @@
 [MASTER]
 init-hook='import sys; sys.path.append("scripts")'
+min-similarity-lines=10
 
 [BASIC]
 # We're ok with short funtion argument names.
@@ -73,3 +74,7 @@ reports=no
 # Allow unused variables if their name starts with an underscore.
 # [unused-argument]
 dummy-variables-rgx=_.*
+
+[SIMILARITIES]
+# Ignore imports when computing similarities.
+ignore-imports=yes

.travis.yml

@@ -25,8 +25,40 @@ jobs:
         - tests/scripts/all.sh -k build_arm_linux_gnueabi_gcc_arm5vte build_arm_none_eabi_gcc_m0plus
 
     - name: full configuration
+      os: linux
+      dist: focal
+      addons:
+        apt:
+          packages:
+          - clang-10
+          - gnutls-bin
       script:
-        - tests/scripts/all.sh -k test_full_cmake_gcc_asan
+        # Do a manual build+test sequence rather than using all.sh,
+        # because there's no all.sh component that does what we want,
+        # which is a build with Clang >= 10 and ASan, running all the SSL
+        # testing.
+        #   - The clang executable in the default PATH is Clang 7 on
+        #     Travis's focal instances, but we want Clang >= 10.
+        #   - Running all the SSL testing requires a specific set of
+        #     OpenSSL and GnuTLS versions and we don't want to bother
+        #     with those on Travis.
+        # So we explicitly select clang-10 as the compiler, and we
+        # have ad hoc restrictions on SSL testing based on what is
+        # passing at the time of writing. We will remove these limitations
+        # gradually.
+        - make generated_files
+        - make CC=clang-10 CFLAGS='-Werror -Wall -Wextra -fsanitize=address,undefined -fno-sanitize-recover=all -O2' LDFLAGS='-Werror -Wall -Wextra -fsanitize=address,undefined -fno-sanitize-recover=all'
+        - make test
+        - programs/test/selftest
+        - tests/scripts/test_psa_constant_names.py
+        - tests/ssl-opt.sh
+        # Modern OpenSSL does not support fixed ECDH or null ciphers.
+        - tests/compat.sh -p OpenSSL -e 'NULL\|ECDH_'
+        - tests/scripts/travis-log-failure.sh
+        # GnuTLS supports CAMELLIA but compat.sh doesn't properly enable it.
+        - tests/compat.sh -p GnuTLS -e 'CAMELLIA'
+        - tests/scripts/travis-log-failure.sh
+        - tests/context-info.sh
 
     - name: Windows
       os: windows

.uncrustify.cfg

@@ -0,0 +1,252 @@
+# Configuration options for Uncrustify specifying the Mbed TLS code style.
+#
+# Note: The code style represented by this file has not yet been introduced
+# to Mbed TLS.
+#
+# Copyright The Mbed TLS Contributors
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Wrap lines at 100 characters
+code_width = 100
+
+# Allow splitting long for statements between the condition statements
+ls_for_split_full = true
+
+# Allow splitting function calls between arguments
+ls_func_split_full = true
+
+input_tab_size = 4
+
+# Spaces-only indentation
+indent_with_tabs = 0
+
+indent_columns = 4
+
+# Indent 'case' 1 level from 'switch'
+indent_switch_case = indent_columns
+
+# Line-up strings broken by '\'
+indent_align_string = true
+
+# Braces on the same line (Egyptian-style braces)
+nl_enum_brace = remove
+nl_union_brace = remove
+nl_struct_brace = remove
+nl_do_brace = remove
+nl_if_brace = remove
+nl_for_brace = remove
+nl_else_brace = remove
+nl_while_brace = remove
+nl_switch_brace = remove
+
+# Braces on same line as keywords that follow them - 'else' and the 'while' in 'do {} while ()';
+nl_brace_else = remove
+nl_brace_while = remove
+# Space before else on the same line
+sp_brace_else = add
+# If else is on the same line as '{', force exactly 1 space between them
+sp_else_brace = force
+
+# Functions are the exception and have braces on the next line
+nl_fcall_brace = add
+nl_fdef_brace = add
+
+# Force exactly one space between ')' and '{' in statements
+sp_sparen_brace = force
+
+# At least 1 space around assignment
+sp_assign = add
+
+# Remove spaces around the preprocessor '##' token-concatenate
+sp_pp_concat = ignore
+
+# At least 1 space around '||' and '&&'
+sp_bool = add
+
+# But no space after the '!' operator
+sp_not = remove
+
+# No space after the bitwise-not '~' operator
+sp_inv = remove
+
+# No space after the addressof '&' operator
+sp_addr = remove
+
+# No space around the member '.' and '->' operators
+sp_member = remove
+
+# No space after the dereference '*' operator
+sp_deref = remove
+
+# No space after a unary negation '-'
+sp_sign = remove
+
+# No space between the '++'/'--' operator and its operand
+sp_incdec = remove
+
+# At least 1 space around comparison operators
+sp_compare = add
+
+# Remove spaces inside all kinds of parentheses:
+
+# Remove spaces inside parentheses
+sp_inside_paren = remove
+
+# No spaces inside statement parentheses
+sp_inside_sparen = remove
+
+# No spaces inside cast parentheses '( char )x' -> '(char)x'
+sp_inside_paren_cast = remove
+
+# No spaces inside function parentheses
+sp_inside_fparen = remove
+# (The case where the function has no parameters/arguments)
+sp_inside_fparens = remove
+
+# No spaces inside the first parentheses in a function type
+sp_inside_tparen = remove
+
+# (Uncrustify >= 0.74.0) No spaces inside parens in for statements
+sp_inside_for = remove
+
+# Remove spaces between nested parentheses '( (' -> '(('
+sp_paren_paren = remove
+# (Uncrustify >= 0.74.0)
+sp_sparen_paren = remove
+
+# Remove spaces between ')' and adjacent '('
+sp_cparen_oparen = remove
+
+# (Uncrustify >= 0.73.0) space between 'do' and '{'
+sp_do_brace_open = force
+
+# (Uncrustify >= 0.73.0) space between '}' and 'while'
+sp_brace_close_while = force
+
+# At least 1 space before a '*' pointer star
+sp_before_ptr_star = add
+
+# Remove spaces between pointer stars
+sp_between_ptr_star = remove
+
+# No space after a pointer star
+sp_after_ptr_star = remove
+
+# But allow a space in the case of e.g. char * const x;
+sp_after_ptr_star_qualifier = ignore
+
+# Remove space after star in a function return type
+sp_after_ptr_star_func = remove
+
+# At least 1 space after a type in variable definition etc
+sp_after_type = add
+
+# Force exactly 1 space between a statement keyword (e.g. 'if') and an opening parenthesis
+sp_before_sparen = force
+
+# Remove a space before a ';'
+sp_before_semi = remove
+# (Uncrustify >= 0.73.0) Remove space before a semi in a non-empty for
+sp_before_semi_for = remove
+# (Uncrustify >= 0.73.0) Remove space in empty first statement of a for
+sp_before_semi_for_empty = remove
+# (Uncrustify >= 0.74.0) Remove space in empty middle statement of a for
+sp_between_semi_for_empty = remove
+
+# Add a space after a ';' (unless a comment follows)
+sp_after_semi = add
+# (Uncrustify >= 0.73.0) Add a space after a semi in non-empty for statements
+sp_after_semi_for = add
+# (Uncrustify >= 0.73.0) No space after final semi in empty for statements
+sp_after_semi_for_empty = remove
+
+# Remove spaces on the inside of square brackets '[]'
+sp_inside_square = remove
+
+# Must have at least 1 space after a comma
+sp_after_comma = add
+
+# Must not have a space before a comma
+sp_before_comma = remove
+
+# No space before the ':' in a case statement
+sp_before_case_colon = remove
+
+# Must have space after a cast - '(char)x' -> '(char) x'
+sp_after_cast = add
+
+# No space between 'sizeof' and '('
+sp_sizeof_paren = remove
+
+# At least 1 space inside '{ }'
+sp_inside_braces = add
+
+# At least 1 space inside '{ }' in an enum
+sp_inside_braces_enum = add
+
+# At least 1 space inside '{ }' in a struct
+sp_inside_braces_struct = add
+
+# At least 1 space between a function return type and the function name
+sp_type_func = add
+
+# No space between a function name and its arguments/parameters
+sp_func_proto_paren = remove
+sp_func_def_paren = remove
+sp_func_call_paren = remove
+
+# No space between '__attribute__' and '('
+sp_attribute_paren = remove
+
+# No space between 'defined' and '(' in preprocessor conditions
+sp_defined_paren = remove
+
+# At least 1 space between a macro's name and its definition
+sp_macro = add
+sp_macro_func = add
+
+# Force exactly 1 space between a '}' and the name of a typedef if on the same line
+sp_brace_typedef = force
+
+# At least 1 space before a '\' line continuation
+sp_before_nl_cont = add
+
+# At least 1 space around '?' and ':' in ternary statements
+sp_cond_colon = add
+sp_cond_question = add
+
+# Space between #else/#endif and comment afterwards
+sp_endif_cmt = add
+
+# Remove newlines at the start of a file
+nl_start_of_file = remove
+
+# At least 1 newline at the end of a file
+nl_end_of_file = add
+nl_end_of_file_min = 1
+
+# Add braces in single-line statements
+mod_full_brace_do = add
+mod_full_brace_for = add
+mod_full_brace_if = add
+mod_full_brace_while = add
+
+# Remove parentheses from return statements
+mod_paren_on_return = remove
+
+# Disable removal of leading spaces in a multi-line comment if the first and
+# last lines are the same length
+cmt_multi_check_last = false

3rdparty/everest/library/everest.c

@@ -28,12 +28,7 @@
 #include "everest/x25519.h"
 #include "everest/everest.h"
 
-#if defined(MBEDTLS_PLATFORM_C)
 #include "mbedtls/platform.h"
-#else
-#define mbedtls_calloc calloc
-#define mbedtls_free   free
-#endif
 
 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
 

BRANCHES.md

@@ -101,6 +101,6 @@ The following branches are currently maintained:
 - [`development`](https://github.com/Mbed-TLS/mbedtls/)
 - [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28)
  maintained until at least the end of 2024, see
-  <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.0>.
+  <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.2>.
 
 Users are urged to always use the latest version of a maintained branch.

CMakeLists.txt

@@ -304,22 +304,15 @@ if(ENABLE_TESTING)
     # additional convenience targets for Unix only
     if(UNIX)
 
-        ADD_CUSTOM_TARGET(covtest
+        # For coverage testing:
-            COMMAND make test
+        # 1. Build with:
-            COMMAND programs/test/selftest
+        #         cmake -D CMAKE_BUILD_TYPE=Coverage /path/to/source && make
-            COMMAND tests/compat.sh
+        # 2. Run the relevant tests for the part of the code you're interested in.
-            COMMAND tests/ssl-opt.sh
+        #    For the reference coverage measurement, see
-        )
+        #    tests/scripts/basic-build-test.sh
-
+        # 3. Run scripts/lcov.sh to generate an HTML report.
         ADD_CUSTOM_TARGET(lcov
-            COMMAND rm -rf Coverage
+            COMMAND scripts/lcov.sh
-            COMMAND lcov --capture --initial --directory library/CMakeFiles/mbedtls.dir -o files.info
-            COMMAND lcov --capture --directory library/CMakeFiles/mbedtls.dir -o tests.info
-            COMMAND lcov --add-tracefile files.info --add-tracefile tests.info -o all.info
-            COMMAND lcov --remove all.info -o final.info '*.h'
-            COMMAND gendesc tests/Descriptions.txt -o descriptions
-            COMMAND genhtml --title "mbed TLS" --description-file descriptions --keep-descriptions --legend --no-branch-coverage -o Coverage final.info
-            COMMAND rm -f files.info tests.info all.info final.info descriptions
         )
 
         ADD_CUSTOM_TARGET(memcheck
@@ -350,12 +343,12 @@ if(NOT DISABLE_PACKAGE_CONFIG_AND_INSTALL)
     write_basic_package_version_file(
         "cmake/MbedTLSConfigVersion.cmake"
             COMPATIBILITY SameMajorVersion
-            VERSION 3.2.1)
+            VERSION 3.3.0)
 
     install(
         FILES "${CMAKE_CURRENT_BINARY_DIR}/cmake/MbedTLSConfig.cmake"
               "${CMAKE_CURRENT_BINARY_DIR}/cmake/MbedTLSConfigVersion.cmake"
-        DESTINATION "cmake")
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/MbedTLS")
 
     export(
         EXPORT MbedTLSTargets
@@ -365,7 +358,7 @@ if(NOT DISABLE_PACKAGE_CONFIG_AND_INSTALL)
     install(
         EXPORT MbedTLSTargets
         NAMESPACE MbedTLS::
-        DESTINATION "cmake"
+        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/MbedTLS"
         FILE "MbedTLSTargets.cmake")
 
     if(CMAKE_VERSION VERSION_GREATER 3.15 OR CMAKE_VERSION VERSION_EQUAL 3.15)

CONTRIBUTING.md

@@ -1,13 +1,20 @@
 Contributing
 ============
-We gratefully accept bug reports and contributions from the community. There are some requirements we need to fulfill in order to be able to integrate contributions:
+We gratefully accept bug reports and contributions from the community. All PRs are reviewed by the project team / community, and may need some modifications to
+be accepted.
 
- - As with any open source project, contributions will be reviewed by the project team and community and may need some modifications to be accepted.
+Quick Checklist for PR contributors
- - The contribution should not break API or ABI, unless there is a real justification for that. If there is an API change, the contribution, if accepted, will be merged only when there will be a major release.
+-----------------------------------
+More details on all of these points may be found in the sections below.
+
+- [Sign-off](#license-and-copyright): all commits must be signed off.
+- [Tests](#tests): please ensure the PR includes adequate tests.
+- [Changelog](#documentation): if needed, please provide a changelog entry.
+- [Backports](#long-term-support-branches): provide a backport if needed (it's fine to wait until the main PR is accepted).
 
 Coding Standards
 ----------------
-- We would ask that contributions conform to [our coding standards](https://tls.mbed.org/kb/development/mbedtls-coding-standards), and that contributions are fully tested before submission, as mentioned in the [Tests](#tests) and [Continuous Integration](#continuous-integration-tests) sections.
+- We would ask that contributions conform to [our coding standards](https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards/), and that contributions are fully tested before submission, as mentioned in the [Tests](#tests) and [Continuous Integration](#continuous-integration-tests) sections.
 - The code should be written in a clean and readable style.
 - The code should be written in a portable generic way, that will benefit the whole community, and not only your own needs.
 - The code should be secure, and will be reviewed from a security point of view as well.
@@ -25,13 +32,9 @@ Backwards Compatibility
 
 The project aims to minimise the impact on users upgrading to newer versions of the library and it should not be necessary for a user to make any changes to their own code to work with a newer version of the library. Unless the user has made an active decision to use newer features, a newer generation of the library or a change has been necessary due to a security issue or other significant software defect, no modifications to their own code should be necessary. To achieve this, API compatibility is maintained between different versions of Mbed TLS on the main development branch and in LTS (Long Term Support) branches, as described in [BRANCHES.md](BRANCHES.md).
 
-To minimise such disruption to users, where a change to the interface is required, all changes to the ABI or API, even on the main development branch where new features are added, need to be justifiable by either being a significant enhancement, new feature or bug fix which is best resolved by an interface change.
+To minimise such disruption to users, where a change to the interface is required, all changes to the ABI or API, even on the main development branch where new features are added, need to be justifiable by either being a significant enhancement, new feature or bug fix which is best resolved by an interface change. If there is an API change, the contribution, if accepted, will be merged only when there is a major release.
 
-Where changes to an existing interface are necessary, functions in the public interface which need to be changed, are marked as 'deprecated'. This is done with the preprocessor symbols `MBEDTLS_DEPRECATED_WARNING` and `MBEDTLS_DEPRECATED_REMOVED`. Then, a new function with a new name but similar if not identical behaviour to the original function containing the necessary changes should be created alongside the existing deprecated function.
+No changes are permitted to the definition of functions in the public interface which will change the API. Instead the interface can only be changed by its extension. Where changes to an existing interface are necessary, functions in the public interface which need to be changed are marked as 'deprecated'. If there is a strong reason to replace an existing function with one that has a slightly different interface (different prototype, or different documented behavior), create a new function with a new name with the desired interface. Keep the old function, but mark it as deprecated.
-
-When a build is made with the deprecation preprocessor symbols defined, a compiler warning will be generated to warn a user that the function will be removed at some point in the future, notifying users that they should change from the older deprecated function to the newer function at their own convenience.
-
-Therefore, no changes are permitted to the definition of functions in the public interface which will change the API. Instead the interface can only be changed by its extension. As described above, if a function needs to be changed, a new function needs to be created alongside it, with a new name, and whatever change is necessary, such as a new parameter or the addition of a return value.
 
 Periodically, the library will remove deprecated functions from the library which will be a breaking change in the API, but such changes will be made only in a planned, structured way that gives sufficient notice to users of the library.
 
@@ -54,9 +57,9 @@ Tests
 -----
 As mentioned, tests that show the correctness of the feature or bug fix should be added to the pull request, if no such tests exist.
 
-Mbed TLS includes a comprehensive set of test suites in the `tests/` directory that are dynamically generated to produce the actual test source files (e.g. `test_suite_mpi.c`). These files are generated from a `function file` (e.g. `suites/test_suite_mpi.function`) and a `data file` (e.g. `suites/test_suite_mpi.data`). The function file contains the test functions. The data file contains the test cases, specified as parameters that will be passed to the test function.
+Mbed TLS includes a comprehensive set of test suites in the `tests/` directory that are dynamically generated to produce the actual test source files (e.g. `test_suite_rsa.c`). These files are generated from a `function file` (e.g. `suites/test_suite_rsa.function`) and a `data file` (e.g. `suites/test_suite_rsa.data`). The function file contains the test functions. The data file contains the test cases, specified as parameters that will be passed to the test function.
 
-[A Knowledge Base article describing how to add additional tests is available on the Mbed TLS website](https://tls.mbed.org/kb/development/test_suites).
+[A Knowledge Base article describing how to add additional tests is available on the Mbed TLS website](https://mbed-tls.readthedocs.io/en/latest/kb/development/test_suites/).
 
 A test script `tests/scripts/basic-build-test.sh` is available to show test coverage of the library. New code contributions should provide a similar level of code coverage to that which already exists for the library.
 
@@ -75,7 +78,7 @@ Mbed TLS is well documented, but if you think documentation is needed, speak out
 1. All interfaces should be documented through Doxygen. New APIs should introduce Doxygen documentation.
 1. Complex parts in the code should include comments.
 1. If needed, a Readme file is advised.
-1. If a [Knowledge Base (KB)](https://tls.mbed.org/kb) article should be added, write this as a comment in the PR description.
+1. If a [Knowledge Base (KB)](https://mbed-tls.readthedocs.io/en/latest/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

ChangeLog

@@ -1,9 +1,213 @@
 Mbed TLS ChangeLog (Sorted per branch, date)
 
+= Mbed TLS 3.3.0 branch released 2022-12-14
+
+Default behavior changes
+   * Previously the macro MBEDTLS_SSL_DTLS_CONNECTION_ID implemented version 05
+     of the IETF draft, and was marked experimental and disabled by default.
+     It is now no longer experimental, and implements the final version from
+     RFC 9146, which is not interoperable with the draft-05 version.
+     If you need to communicate with peers that use earlier versions of
+     Mbed TLS, then you need to define MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT
+     to 1, but then you won't be able to communicate with peers that use the
+     standard (non-draft) version.
+     If you need to interoperate with both classes of peers with the
+     same build of Mbed TLS, please let us know about your situation on the
+     mailing list or GitHub.
+
+Requirement changes
+   * When building with PSA drivers using generate_driver_wrappers.py, or
+     when building the library from the development branch rather than
+     from a release, the Python module jsonschema is now necessary, in
+     addition to jinja2. The official list of required Python modules is
+     maintained in scripts/basic.requirements.txt and may change again
+     in the future.
+
+New deprecations
+   * Deprecate mbedtls_asn1_free_named_data().
+     Use mbedtls_asn1_free_named_data_list()
+     or mbedtls_asn1_free_named_data_list_shallow().
+
+Features
+   * Support rsa_pss_rsae_* signature algorithms in TLS 1.2.
+   * 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".
+   * 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.
+   * Some modules can now use PSA drivers for hashes, including with no
+     built-in implementation present, but only in some configurations.
+     - RSA OAEP and PSS (PKCS#1 v2.1), PKCS5, PKCS12 and EC J-PAKE now use
+       hashes from PSA when (and only when) MBEDTLS_MD_C is disabled.
+     - PEM parsing of encrypted files now uses MD-5 from PSA when (and only
+       when) MBEDTLS_MD5_C is disabled.
+     See the documentation of the corresponding macros in mbedtls_config.h for
+     details.
+     Note that some modules are not able to use hashes from PSA yet, including
+     the entropy module. As a consequence, for now the only way to build with
+     all hashes only provided by drivers (no built-in hash) is to use
+     MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.
+   * When MBEDTLS_USE_PSA_CRYPTO is enabled, X.509, TLS 1.2 and TLS 1.3 now
+     properly negotiate/accept hashes based on their availability in PSA.
+     As a consequence, they now work in configurations where the built-in
+     implementations of (some) hashes are excluded and those hashes are only
+     provided by PSA drivers. (See previous entry for limitation on RSA-PSS
+     though: that module only use hashes from PSA when MBEDTLS_MD_C is off).
+   * Add support for opaque keys as the private keys associated to certificates
+     for authentication in TLS 1.3.
+   * Add the LMS post-quantum-safe stateful-hash asymmetric signature scheme.
+     Signature verification is production-ready, but generation is for testing
+     purposes only. This currently only supports one parameter set
+     (LMS_SHA256_M32_H10), meaning that each private key can be used to sign
+     1024 messages. As such, it is not intended for use in TLS, but instead
+     for verification of assets transmitted over an insecure channel,
+     particularly firmware images.
+   * Add the LM-OTS post-quantum-safe one-time signature scheme, which is
+     required for LMS. This can be used independently, but each key can only
+     be used to sign one message so is impractical for most circumstances.
+   * Mbed TLS now supports TLS 1.3 key establishment via pre-shared keys.
+     The pre-shared keys can be provisioned externally or via the ticket
+     mechanism (session resumption).
+     The ticket mechanism is supported when the configuration option
+     MBEDTLS_SSL_SESSION_TICKETS is enabled.
+     New options MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_xxx_ENABLED
+     control the support for the three possible TLS 1.3 key exchange modes.
+   * cert_write: support for setting extended key usage attributes. A
+     corresponding new public API call has been added in the library,
+     mbedtls_x509write_crt_set_ext_key_usage().
+   * cert_write: support for writing certificate files in either PEM
+     or DER format.
+   * The PSA driver wrapper generator generate_driver_wrappers.py now
+     supports a subset of the driver description language, including
+     the following entry points: import_key, export_key, export_public_key,
+     get_builtin_key, copy_key.
+   * The new functions mbedtls_asn1_free_named_data_list() and
+     mbedtls_asn1_free_named_data_list_shallow() simplify the management
+     of memory in named data lists in X.509 structures.
+   * The TLS 1.2 EC J-PAKE key exchange can now use the PSA Crypto API.
+     Additional PSA key slots will be allocated in the process of such key
+     exchange for builds that enable MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED and
+     MBEDTLS_USE_PSA_CRYPTO.
+   * Add support for DTLS Connection ID as defined by RFC 9146, controlled by
+     MBEDTLS_SSL_DTLS_CONNECTION_ID (enabled by default) and configured with
+     mbedtls_ssl_set_cid().
+   * Add a driver dispatch layer for raw key agreement, enabling alternative
+     implementations of raw key agreement through the key_agreement driver
+     entry point. This entry point is specified in the proposed PSA driver
+     interface, but had not yet been implemented.
+   * Add an ad-hoc key derivation function handling EC J-PAKE 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.
+
+Security
+   * Fix potential heap buffer overread and overwrite in DTLS if
+     MBEDTLS_SSL_DTLS_CONNECTION_ID is enabled and
+     MBEDTLS_SSL_CID_IN_LEN_MAX > 2 * MBEDTLS_SSL_CID_OUT_LEN_MAX.
+   * An adversary with access to precise enough information about memory
+     accesses (typically, an untrusted operating system attacking a secure
+     enclave) could recover an RSA private key after observing the victim
+     performing a single private-key operation if the window size used for the
+     exponentiation was 3 or smaller. Found and reported by Zili KOU,
+     Wenjian HE, Sharad Sinha, and Wei ZHANG. See "Cache Side-channel Attacks
+     and Defenses of the Sliding Window Algorithm in TEEs" - Design, Automation
+     and Test in Europe 2023.
+
+Bugfix
+   * Refactor mbedtls_aes_context to support shallow-copying. Fixes #2147.
+   * Fix an issue with in-tree CMake builds in releases with GEN_FILES
+     turned off: if a shipped file was missing from the working directory,
+     it could be turned into a symbolic link to itself.
+   * 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.
+   * Fix support for little-endian Microblaze when MBEDTLS_HAVE_ASM is defined.
+     Contributed by Kazuyuki Kimura to fix #2020.
+   * Use double quotes to include private header file psa_crypto_cipher.h.
+     Fixes 'file not found with <angled> include' error
+     when building with Xcode.
+   * 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.
+   * Fix an interoperability failure between an Mbed TLS client with both
+     TLS 1.2 and TLS 1.3 support, and a TLS 1.2 server that supports
+     rsa_pss_rsae_* signature algorithms. This failed because Mbed TLS
+     advertised support for PSS in both TLS 1.2 and 1.3, but only
+     actually supported PSS in TLS 1.3.
+   * Fix a compilation error when using CMake with an IAR toolchain.
+     Fixes #5964.
+   * Fix a build error due to a missing prototype warning when
+     MBEDTLS_DEPRECATED_REMOVED is enabled.
+   * 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.
+   * Fix a build issue on Windows using CMake where the source and build
+     directories could not be on different drives. Fixes #5751.
+   * Fix bugs and missing dependencies when building and testing
+     configurations with only one encryption type enabled in TLS 1.2.
+   * Provide the missing definition of mbedtls_setbuf() in some configurations
+     with MBEDTLS_PLATFORM_C disabled. Fixes #6118, #6196.
+   * Fix compilation errors when trying to build with
+     PSA drivers for AEAD (GCM, CCM, Chacha20-Poly1305).
+   * Fix memory leak in ssl_parse_certificate_request() caused by
+     mbedtls_x509_get_name() not freeing allocated objects in case of error.
+     Change mbedtls_x509_get_name() to clean up allocated objects on error.
+   * Fix build failure with MBEDTLS_RSA_C and MBEDTLS_PSA_CRYPTO_C but not
+     MBEDTLS_USE_PSA_CRYPTO or MBEDTLS_PK_WRITE_C. Fixes #6408.
+   * Fix build failure with MBEDTLS_RSA_C and MBEDTLS_PSA_CRYPTO_C but not
+     MBEDTLS_PK_PARSE_C. Fixes #6409.
+   * Fix ECDSA verification, where it was not always validating the
+     public key. This bug meant that it was possible to verify a
+     signature with an invalid public key, in some cases. Reported by
+     Guido Vranken using Cryptofuzz in #4420.
+   * Fix a possible null pointer dereference if a memory allocation fails
+     in TLS PRF code. Reported by Michael Madsen in #6516.
+   * Fix TLS 1.3 session resumption. Fixes #6488.
+   * Add a configuration check to exclude optional client authentication
+     in TLS 1.3 (where it is forbidden).
+   * Fix a bug in which mbedtls_x509_crt_info() would produce non-printable
+     bytes when parsing certificates containing a binary RFC 4108
+     HardwareModuleName as a Subject Alternative Name extension. Hardware
+     serial numbers are now rendered in hex format. Fixes #6262.
+   * Fix bug in error reporting in dh_genprime.c where upon failure,
+     the error code returned by mbedtls_mpi_write_file() is overwritten
+     and therefore not printed.
+   * In the bignum module, operations of the form (-A) - (+A) or (-A) - (-A)
+     with A > 0 created an unintended representation of the value 0 which was
+     not processed correctly by some bignum operations. Fix this. This had no
+     consequence on cryptography code, but might affect applications that call
+     bignum directly and use negative numbers.
+   * Fix a bug whereby the list of signature algorithms sent as part of
+     the TLS 1.2 server certificate request would get corrupted, meaning the
+     first algorithm would not get sent and an entry consisting of two random
+     bytes would be sent instead. Found by Serban Bejan and Dudek Sebastian.
+   * Fix undefined behavior (typically harmless in practice) of
+     mbedtls_mpi_add_mpi(), mbedtls_mpi_add_abs() and mbedtls_mpi_add_int()
+     when both operands are 0 and the left operand is represented with 0 limbs.
+   * Fix undefined behavior (typically harmless in practice) when some bignum
+     functions receive the most negative value of mbedtls_mpi_sint. Credit
+     to OSS-Fuzz. Fixes #6597.
+   * Fix undefined behavior (typically harmless in practice) in PSA ECB
+     encryption and decryption.
+   * Move some SSL-specific code out of libmbedcrypto where it had been placed
+     accidentally.
+   * Fix a build error when compiling the bignum module for some Arm platforms.
+     Fixes #6089, #6124, #6217.
+
+Changes
+   * Add the ability to query PSA_WANT_xxx macros to query_compile_time_config.
+   * Calling AEAD tag-specific functions for non-AEAD algorithms (which
+     should not be done - they are documented for use only by AES-GCM and
+     ChaCha20+Poly1305) now returns MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
+     instead of success (0).
+
 = Mbed TLS 3.2.1 branch released 2022-07-12
 
 Bugfix
-   *  Re-add missing generated file library/ssl_debug_helpers_generated.c
+   *  Re-add missing generated file library/psa_crypto_driver_wrappers.c
 
 = Mbed TLS 3.2.0 branch released 2022-07-11
 
@@ -249,7 +453,7 @@ Bugfix
      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
+   * Removed the prompt to exit from all windows build programs, which was causing
      issues in CI/CD environments.
 
 Changes
@@ -463,7 +667,7 @@ API changes
      provides better randomness. Instead of HAVEGE, declare OS or hardware RNG
      interfaces with mbedtls_entropy_add_source() and/or use an entropy seed
      file created securely during device provisioning. See
-     https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool for
+     https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-entropy-sources-to-entropy-pool/ for
      more information.
    * Add missing const attributes to API functions.
    * Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0: the

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

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

ChangeLog.d/alignment-perf.txt

@@ -0,0 +1,8 @@
+Features
+   * General performance improvements by accessing multiple bytes at a time.
+     Fixes #1666.
+   * Improvements to use of unaligned and byte-swapped memory, reducing code
+     size and improving performance (depending on compiler and target
+     architecture).
+Changes
+   * Mixed-endian systems are explicitly not supported any more.

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

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

ChangeLog.d/c-build-helper-hostcc.txt

@@ -0,0 +1,4 @@
+Features
+   * Use HOSTCC (if it is set) when compiling C code during generation of the
+     configuration-independent files. This allows them to be generated when
+     CC is set for cross compilation.

ChangeLog.d/cmake-install.txt

@@ -0,0 +1,3 @@
+Changes
+  * Install the .cmake files into CMAKE_INSTALL_LIBDIR/cmake/MbedTLS,
+    typically /usr/lib/cmake/MbedTLS.

ChangeLog.d/conditionalize-mbedtls_mpi_sub_abs-memcpy.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Fix potential undefined behavior in mbedtls_mpi_sub_abs().  Reported by
+     Pascal Cuoq using TrustInSoft Analyzer in #6701; observed independently by
+     Aaron Ucko under Valgrind.

ChangeLog.d/crypto_config_ccm_star.txt

@@ -0,0 +1,3 @@
+Bugfix
+   * List PSA_WANT_ALG_CCM_STAR_NO_TAG in psa/crypto_config.h so that it can
+     be toggled with config.py.

ChangeLog.d/csr_v3_extensions.txt

@@ -0,0 +1,3 @@
+Features
+   * Add parsing of V3 extensions (key usage, Netscape cert-type,
+     Subject Alternative Names) in x509 Certificate Sign Requests.

ChangeLog.d/driver-only-hashes.txt

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

ChangeLog.d/ecjpake_to_pms.txt

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

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

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

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

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

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

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

ChangeLog.d/fix-example-programs-no-args.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Fix behavior of certain sample programs which could, when run with no
+     arguments, access uninitialized memory in some cases. Fixes #6700 (which
+     was found by TrustInSoft Analyzer during REDOCS'22) and #1120.

ChangeLog.d/fix-gettimeofday-overflow.txt

@@ -0,0 +1,3 @@
+Bugfix
+   * Fix possible integer overflow in mbedtls_timing_hardclock(), which
+     could cause a crash in programs/test/benchmark.

ChangeLog.d/fix-iar-warnings.txt

@@ -0,0 +1,2 @@
+Bugfix
+   * Fix IAR compiler warnings. Contributed by Glenn Strauss in #3835.

ChangeLog.d/fix-rsaalt-test-guards.txt

@@ -0,0 +1,3 @@
+Bugfix
+   * Fix compile error where MBEDTLS_RSA_C and MBEDTLS_X509_CRT_WRITE_C are
+     defined, but MBEDTLS_PK_RSA_ALT_SUPPORT is not defined. Fixes #3174.

ChangeLog.d/fix_build_error_for_mbedtls_deprecated_removed.txt

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

ChangeLog.d/fix_build_for_directory_names_containing_spaces.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * Fix a bug in the build where directory names containing spaces were
+     causing generate_errors.pl to error out resulting in a build failure.
+     Fixes issue #6879.

ChangeLog.d/fix_build_tls1_2_with_single_encryption_type.txt

@@ -1,4 +0,0 @@
-Bugfix
-    * Fix bugs and missing dependencies when
-      building and testing configurations with
-      only one encryption type enabled in TLS 1.2.

ChangeLog.d/fix_cmake_gen_files

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

ChangeLog.d/fix_cmake_using_iar_toolchain.txt

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

ChangeLog.d/fix_hard_link_across_drives

@@ -1,3 +0,0 @@
-Bugfix
-   * Fix a build issue on Windows where the source and build directory could not be on
-     different drives (#5751).

ChangeLog.d/fix_psa_crypto_cipher_h_include.txt

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

ChangeLog.d/improve_x509_cert_writing_serial_number_management.txt

@@ -0,0 +1,19 @@
+Bugfix
+   * mbedtls_x509write_crt_set_serial() now explicitly rejects serial numbers
+     whose binary representation is longer than 20 bytes. This was already
+     forbidden by the standard (RFC5280 - section 4.1.2.2) and now it's being
+     enforced also at code level.
+
+New deprecations
+   * mbedtls_x509write_crt_set_serial() is now being deprecated in favor of
+     mbedtls_x509write_crt_set_serial_raw(). The goal here is to remove any
+     direct dependency of X509 on BIGNUM_C.
+
+Changes
+   * programs/x509/cert_write:
+     - now it accepts the serial number in 2 different formats: decimal and
+       hex. They cannot be used simultaneously
+     - "serial" is used for the decimal format and it's limted in size to
+       unsigned long long int
+     - "serial_hex" is used for the hex format; max length here is
+       MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN*2

ChangeLog.d/make_sha224_sha384_independent_from_sha256_sha512.txt

@@ -0,0 +1,4 @@
+Features
+   * SHA224_C/SHA384_C are now independent from SHA384_C/SHA512_C respectively.
+     This helps in saving code size when some of the above hashes are not
+     required.

ChangeLog.d/mbedtls_ecp_point_read_binary-compressed-fmt.txt

@@ -0,0 +1,6 @@
+Features
+   * Add support for reading points in compressed format
+     (MBEDTLS_ECP_PF_COMPRESSED) with mbedtls_ecp_point_read_binary()
+     (and callers) for Short Weierstrass curves with prime p where p = 3 mod 4
+     (all mbedtls MBEDTLS_ECP_DP_SECP* and MBEDTLS_ECP_DP_BP* curves
+      except MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1)

ChangeLog.d/muladdc_microblaze.txt

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

ChangeLog.d/nonversioned-library-soname.txt

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

ChangeLog.d/pk-sign-restartable.txt

@@ -0,0 +1,5 @@
+Changes
+   * When MBEDTLS_USE_PSA_CRYPTO and MBEDTLS_ECDSA_DETERMINISTIC are both
+     defined, mbedtls_pk_sign() now use deterministic ECDSA for ECDSA
+     signatures. This aligns the behaviour with MBEDTLS_USE_PSA_CRYPTO to
+     the behaviour without it, where deterministic ECDSA was already used.

ChangeLog.d/psa_alg_tls12_ecjpake_to_pms-reject_ka.txt

@@ -0,0 +1,4 @@
+Bugfix
+   * The key derivation algorithm PSA_ALG_TLS12_ECJPAKE_TO_PMS cannot be
+     used on a shared secret from a key agreement since its input must be
+     an ECC public key. Reject this properly.

ChangeLog.d/psa_crypto_pake.txt

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

ChangeLog.d/remove_ssl_session_compression.txt

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

ChangeLog.d/tls13_sig_alg_selection.txt

@@ -1,3 +0,0 @@
-Features
-   * Add support for opaque keys as the private keys associated to certificates
-     for authentication in TLS 1.3.

ChangeLog.d/vs2013.txt

@@ -0,0 +1,4 @@
+Changes
+  * Visual Studio: Rename the directory containing Visual Studio files from
+    visualc/VS2010 to visualc/VS2013 as we do not support building with versions
+    older than 2013. Update the solution file to specify VS2013 as a minimum.

ChangeLog.d/workaround_gnutls_anti_replay_fail.txt

@@ -0,0 +1,7 @@
+Bugfix
+    * In TLS 1.3, when using a ticket for session resumption, tweak its age
+      calculation on the client side. It prevents a server with more accurate
+      ticket timestamps (typically timestamps in milliseconds) compared to the
+      Mbed TLS ticket timestamps (in seconds) to compute a ticket age smaller
+      than the age computed and transmitted by the client and thus potentially
+      reject the ticket. Fix #6623.

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

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

Makefile

@@ -4,7 +4,7 @@ PERL ?= perl
 
 .SILENT:
 
-.PHONY: all no_test programs lib tests install uninstall clean test check covtest lcov apidoc apidoc_clean
+.PHONY: all no_test programs lib tests install uninstall clean test check lcov apidoc apidoc_clean
 
 all: programs tests
 	$(MAKE) post_build
@@ -37,7 +37,7 @@ generated_files: tests/generated_files
 generated_files: visualc_files
 
 .PHONY: visualc_files
-VISUALC_FILES = visualc/VS2010/mbedTLS.sln visualc/VS2010/mbedTLS.vcxproj
+VISUALC_FILES = visualc/VS2013/mbedTLS.sln visualc/VS2013/mbedTLS.vcxproj
 # TODO: $(app).vcxproj for each $(app) in programs/
 visualc_files: $(VISUALC_FILES)
 
@@ -46,9 +46,9 @@ visualc_files: $(VISUALC_FILES)
 # they just need to be present.
 $(VISUALC_FILES): | library/generated_files
 $(VISUALC_FILES): scripts/generate_visualc_files.pl
-$(VISUALC_FILES): scripts/data_files/vs2010-app-template.vcxproj
+$(VISUALC_FILES): scripts/data_files/vs2013-app-template.vcxproj
-$(VISUALC_FILES): scripts/data_files/vs2010-main-template.vcxproj
+$(VISUALC_FILES): scripts/data_files/vs2013-main-template.vcxproj
-$(VISUALC_FILES): scripts/data_files/vs2010-sln-template.sln
+$(VISUALC_FILES): scripts/data_files/vs2013-sln-template.sln
 # TODO: also the list of .c and .h source files, but not their content
 $(VISUALC_FILES):
 	echo "  Gen   $@ ..."
@@ -124,10 +124,10 @@ neat: clean_more_on_top
 	$(MAKE) -C programs neat
 	$(MAKE) -C tests neat
 ifndef WINDOWS
-	rm -f visualc/VS2010/*.vcxproj visualc/VS2010/mbedTLS.sln
+	rm -f visualc/VS2013/*.vcxproj visualc/VS2013/mbedTLS.sln
 else
-	if exist visualc\VS2010\*.vcxproj del /Q /F visualc\VS2010\*.vcxproj
+	if exist visualc\VS2013\*.vcxproj del /Q /F visualc\VS2013\*.vcxproj
-	if exist visualc\VS2010\mbedTLS.sln del /Q /F visualc\VS2010\mbedTLS.sln
+	if exist visualc\VS2013\mbedTLS.sln del /Q /F visualc\VS2013\mbedTLS.sln
 endif
 
 check: lib tests
@@ -136,23 +136,15 @@ check: lib tests
 test: check
 
 ifndef WINDOWS
-# note: for coverage testing, build with:
+# For coverage testing:
-# make CFLAGS='--coverage -g3 -O0'
+# 1. Build with:
-covtest:
+#         make CFLAGS='--coverage -g3 -O0' LDFLAGS='--coverage'
-	$(MAKE) check
+# 2. Run the relevant tests for the part of the code you're interested in.
-	programs/test/selftest
+#    For the reference coverage measurement, see
-	tests/compat.sh
+#    tests/scripts/basic-build-test.sh
-	tests/ssl-opt.sh
+# 3. Run scripts/lcov.sh to generate an HTML report.
-
 lcov:
-	rm -rf Coverage
+	scripts/lcov.sh
-	lcov --capture --initial --directory library -o files.info
-	lcov --rc lcov_branch_coverage=1 --capture --directory library -o tests.info
-	lcov --rc lcov_branch_coverage=1 --add-tracefile files.info --add-tracefile tests.info -o all.info
-	lcov --rc lcov_branch_coverage=1 --remove all.info -o final.info '*.h'
-	gendesc tests/Descriptions.txt -o descriptions
-	genhtml --title "mbed TLS" --description-file descriptions --keep-descriptions --legend --branch-coverage -o Coverage final.info
-	rm -f files.info tests.info all.info final.info descriptions
 
 apidoc:
 	mkdir -p apidoc

README.md

@@ -17,7 +17,9 @@ We provide some non-standard configurations focused on specific use cases in the
 Documentation
 -------------
 
-Documentation for the Mbed TLS interfaces in the default library configuration is available as part of the [Mbed TLS documentation](https://tls.mbed.org/api/).
+The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/).
+
+Documentation for the PSA Cryptography API is available [on GitHub](https://arm-software.github.io/psa-api/crypto/).
 
 To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration:
 
@@ -103,9 +105,9 @@ Setting the variable `SHARED` in your environment will build shared libraries in
 
 Please note that setting `CFLAGS` overrides its default value of `-O2` and setting `WARNING_CFLAGS` overrides its default value (starting with `-Wall -Wextra`), so if you just want to add some warning options to the default ones, you can do so by setting `CFLAGS=-O2 -Werror` for example. Setting `WARNING_CFLAGS` is useful when you want to get rid of its default content (for example because your compiler doesn't accept `-Wall` as an option). Directory-specific options cannot be overridden from the command line.
 
-Depending on your platform, you might run into some issues. Please check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remove for specific platforms. You can also check [the Mbed TLS Knowledge Base](https://tls.mbed.org/kb) for articles on your platform or issue.
+Depending on your platform, you might run into some issues. Please check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remove for specific platforms. You can also check [the Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/) for articles on your platform or issue.
 
-In case you find that you need to do something else as well, please let us know what, so we can add it to the [Mbed TLS Knowledge Base](https://tls.mbed.org/kb).
+In case you find that you need to do something else as well, please let us know what, so we can add it to the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/).
 
 ### CMake
 
@@ -218,7 +220,7 @@ subproject.
 
 ### Microsoft Visual Studio
 
-The build files for Microsoft Visual Studio are generated for Visual Studio 2010.
+The build files for Microsoft Visual Studio are generated for Visual Studio 2013.
 
 The solution file `mbedTLS.sln` contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need Python and perl environments as well. However, the selftest program in `programs/test/` is still available.
 
@@ -240,17 +242,19 @@ For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, ad
 -   `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations.
 -   `tests/compat.sh` tests interoperability of every ciphersuite with other implementations.
 -   `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations.
--   `tests/scripts/key-exchanges.pl` test builds in configurations with a single key exchange enabled
+-   `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on.
 -   `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc).
 
+Instead of manually installing the required versions of all tools required for testing, it is possible to use the Docker images from our CI systems, as explained in [our testing infrastructure repository](https://github.com/Mbed-TLS/mbedtls-test/blob/master/README.md#quick-start).
+
 Porting Mbed TLS
 ----------------
 
 Mbed TLS can be ported to many different architectures, OS's and platforms. Before starting a port, you may find the following Knowledge Base articles useful:
 
--   [Porting Mbed TLS to a new environment or OS](https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS)
+-   [Porting Mbed TLS to a new environment or OS](https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS/)
--   [What external dependencies does Mbed TLS rely on?](https://tls.mbed.org/kb/development/what-external-dependencies-does-mbedtls-rely-on)
+-   [What external dependencies does Mbed TLS rely on?](https://mbed-tls.readthedocs.io/en/latest/kb/development/what-external-dependencies-does-mbedtls-rely-on/)
--   [How do I configure Mbed TLS](https://tls.mbed.org/kb/compiling-and-building/how-do-i-configure-mbedtls)
+-   [How do I configure Mbed TLS](https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-building/how-do-i-configure-mbedtls/)
 
 Mbed TLS is mostly written in portable C99; however, it has a few platform requirements that go beyond the standard, but are met by most modern architectures:
 
@@ -259,15 +263,16 @@ Mbed TLS is mostly written in portable C99; however, it has a few platform requi
 - Signed integers must be represented using two's complement.
 - `int` and `size_t` must be at least 32 bits wide.
 - The types `uint8_t`, `uint16_t`, `uint32_t` and their signed equivalents must be available.
+- Mixed-endian platforms are not supported.
 
 PSA cryptography API
 --------------------
 
-### PSA API design
+### PSA API
 
 Arm's [Platform Security Architecture (PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level.
 
-The [PSA cryptography API](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
+The [PSA cryptography API](https://arm-software.github.io/psa-api/crypto/) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
 
 The design goals of the PSA cryptography API include:
 
@@ -279,10 +284,6 @@ The design goals of the PSA cryptography API include:
 
 Arm welcomes feedback on the design of the API. If you think something could be improved, please open an issue on our Github repository. Alternatively, if you prefer to provide your feedback privately, please email us at [`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com). All feedback received by email is treated confidentially.
 
-### PSA API documentation
-
-A browsable copy of the PSA Cryptography API documents is available on the [PSA cryptography interfaces documentation portal](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) in [PDF](https://armmbed.github.io/mbed-crypto/PSA_Cryptography_API_Specification.pdf) and [HTML](https://armmbed.github.io/mbed-crypto/html/index.html) formats.
-
 ### PSA implementation in Mbed TLS
 
 Mbed TLS includes a reference implementation of the PSA Cryptography API.

SUPPORT.md

@@ -2,10 +2,11 @@
 
 Here are some useful sources of information about using Mbed TLS:
 
+- [ReadTheDocs](https://mbed-tls.readthedocs.io/);
 - API documentation, see the [Documentation section of the
-  README](README.md#License);
+  README](README.md#documentation);
 - the `docs` directory in the source tree;
-- the [Mbed TLS knowledge Base](https://tls.mbed.org/kb);
+- the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/);
 - the [Mbed TLS mailing-list
   archives](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/).
 

configs/config-ccm-psk-dtls1_2.h

@@ -47,10 +47,6 @@
 #define MBEDTLS_ENTROPY_C
 #define MBEDTLS_MD_C
 #define MBEDTLS_NET_C
-/* The library does not currently support enabling SHA-224 without SHA-256.
- * A future version of the library will have this option disabled
- * by default. */
-#define MBEDTLS_SHA224_C
 #define MBEDTLS_SHA256_C
 #define MBEDTLS_SSL_CLI_C
 #define MBEDTLS_SSL_COOKIE_C

configs/config-ccm-psk-tls1_2.h

@@ -46,10 +46,6 @@
 #define MBEDTLS_ENTROPY_C
 #define MBEDTLS_MD_C
 #define MBEDTLS_NET_C
-/* The library does not currently support enabling SHA-224 without SHA-256.
- * A future version of the library will have this option disabled
- * by default. */
-#define MBEDTLS_SHA224_C
 #define MBEDTLS_SHA256_C
 #define MBEDTLS_SSL_CLI_C
 #define MBEDTLS_SSL_SRV_C

configs/config-suite-b.h

@@ -60,10 +60,6 @@
 #define MBEDTLS_OID_C
 #define MBEDTLS_PK_C
 #define MBEDTLS_PK_PARSE_C
-/* The library does not currently support enabling SHA-224 without SHA-256.
- * A future version of the library will have this option disabled
- * by default. */
-#define MBEDTLS_SHA224_C
 #define MBEDTLS_SHA256_C
 #define MBEDTLS_SHA384_C
 #define MBEDTLS_SHA512_C

configs/config-thread.h

@@ -63,10 +63,6 @@
 #define MBEDTLS_OID_C
 #define MBEDTLS_PK_C
 #define MBEDTLS_PK_PARSE_C
-/* The library does not currently support enabling SHA-224 without SHA-256.
- * A future version of the library will have this option disabled
- * by default. */
-#define MBEDTLS_SHA224_C
 #define MBEDTLS_SHA256_C
 #define MBEDTLS_SSL_COOKIE_C
 #define MBEDTLS_SSL_CLI_C

docs/3.0-migration-guide.md

@@ -141,7 +141,7 @@ recommended), or users who used it through the entropy module but had it as the
 only source of entropy. If you're in that case, please declare OS or hardware
 RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed
 file created securely during device provisioning. See
-<https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool> for more
+<https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-entropy-sources-to-entropy-pool> for more
 information.
 
 ### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0

docs/architecture/alternative-implementations.md

@@ -38,7 +38,7 @@ The general principle of an alternative implementation is:
 * Create a header file `xxx_alt.h` that defines the context type(s) used by the module. For example, `mbedtls_aes_context` for AES.
 * Implement all the functions from the module, i.e. the functions declared in `include/mbedtls/xxx.h`.
 
-See https://tls.mbed.org/kb/development/hw_acc_guidelines for a more detailed guide.
+See https://mbed-tls.readthedocs.io/en/latest/kb/development/hw_acc_guidelines for a more detailed guide.
 
 ### Constraints on context types
 

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

@@ -1,47 +1,30 @@
 #!/bin/sh
 
-# This script runs tests in various revisions and configurations and analyses
+# This script runs tests before and after a PR and analyzes the results in
-# the results in order to highlight any difference in the set of tests skipped
+# 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,
+# It can be used to check the first testing criterion mentioned in strategy.md,
 # end of section "Supporting builds with drivers without the software
-# implementation" are met, namely:
+# implementation", namely: the sets of tests skipped in the default config and
+# the full config must be the same before and after the PR.
 #
-# - the sets of tests skipped in the default config and the full config must be
+# USAGE:
-#   the same before and after the PR that implements step 3;
+# - First, commit any uncommited changes. (Also, see warning below.)
-# - the set of tests skipped in the driver-only build is the same as in an
+# - Then launch --> [SKIP_SSL_OPT=1] docs/architecture/psa-migration/outcome-analysis.sh
-#   equivalent software-based configuration, or the difference is small enough,
+#     - SKIP_SSL_OPT=1 can optionally be set to skip ssl-opt.sh tests
-#   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
+# NOTE: you can comment out parts that don't need to be re-done when
-# 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
 
+: ${SKIP_SSL_OPT:=0}
+
 cleanup() {
     make clean
     git checkout -- include/mbedtls/mbedtls_config.h include/psa/crypto_config.h
@@ -50,7 +33,14 @@ cleanup() {
 record() {
     export MBEDTLS_TEST_OUTCOME_FILE="$PWD/outcome-$1.csv"
     rm -f $MBEDTLS_TEST_OUTCOME_FILE
+
     make check
+
+    if [ $SKIP_SSL_OPT -eq 0 ]; then
+        make -C programs ssl/ssl_server2 ssl/ssl_client2 \
+            test/udp_proxy test/query_compile_time_config
+        tests/ssl-opt.sh
+    fi
 }
 
 # save current HEAD
@@ -59,38 +49,55 @@ 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
 
+populate_suites () {
+    SUITES=''
+    make generated_files >/dev/null
+    data_files=$(cd tests/suites && echo *.data)
+    for data in $data_files; do
+        suite=${data%.data}
+        SUITES="$SUITES $suite"
+    done
+    make neat
+
+    if [ $SKIP_SSL_OPT -eq 0 ]; then
+        SUITES="$SUITES ssl-opt"
+        extra_files=$(cd tests/opt-testcases && echo *.sh)
+        for extra in $extra_files; do
+            suite=${extra%.sh}
+            SUITES="$SUITES $suite"
+        done
+    fi
+}
+
 compare_suite () {
     ref="outcome-$1.csv"
     new="outcome-$2.csv"
     suite="$3"
 
-    pattern_suite=";test_suite_$suite;"
+    pattern_suite=";$suite;"
     total=$(grep -c "$pattern_suite" "$ref")
     sed_cmd="s/^.*$pattern_suite\(.*\);SKIP.*/\1/p"
     sed -n "$sed_cmd" "$ref" > skipped-ref
@@ -98,19 +105,33 @@ compare_suite () {
     nb_ref=$(wc -l <skipped-ref)
     nb_new=$(wc -l <skipped-new)
 
-    printf "%12s: total %3d; skipped %3d -> %3d\n" \
+    name=${suite#test_suite_}
-            $suite      $total       $nb_ref $nb_new
+    printf "%40s: total %4d; skipped %4d -> %4d\n" \
-    diff skipped-ref skipped-new | grep '^> ' || true
+            $name       $total       $nb_ref $nb_new
+    if diff skipped-ref skipped-new | grep '^> '; then
+        ret=1
+    else
+        ret=0
+    fi
     rm skipped-ref skipped-new
+    return $ret
 }
 
 compare_builds () {
     printf "\n*** Comparing $1 -> $2 ***\n"
+    failed=''
     for suite in $SUITES; do
-        compare_suite "$1" "$2" "$suite"
+        if compare_suite "$1" "$2" "$suite"; then :; else
+            failed="$failed $suite"
+        fi
     done
+    if [ -z "$failed" ]; then
+        printf "No coverage gap found.\n"
+    else
+        printf "Suites with less coverage:%s\n" "$failed"
+    fi
 }
 
+populate_suites
 compare_builds before-default after-default
 compare_builds before-full after-full
-compare_builds reference drivers

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

@@ -17,8 +17,11 @@ Restartable ECC operations
 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
+Currently, when `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_ECP_RESTARTABLE` are
-`MBEDTLS_ECP_RESTARTABLE`.
+both enabled, some operations that should be restartable are not (ECDH in TLS
+1.2 clients using ECDHE-ECDSA), as they are using PSA instead, and some
+operations that should use PSA do not (signature generation & verification) as
+they use the legacy API instead, in order to get restartable behaviour.
 
 Things that are in the API but not implemented yet
 --------------------------------------------------

docs/architecture/psa-migration/strategy.md

@@ -386,15 +386,16 @@ 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
+1. 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 same before and after the PR that implements step 3. This is tested
-- the set of tests skipped in the driver-only build is the same as in an
+manually for each PR that changes dependency declarations by using the script
-  equivalent software-based configuration, or the difference is small enough,
+`outcome-analysis.sh` in the present directory.
-  justified, and a github issue is created to track it.
+2. The set of tests skipped in the driver-only build is the same as in an
-
+  equivalent software-based configuration. This is tested automatically by the
-Note that the favourable case is when the number of tests skipped is 0 in the
+CI in the "Results analysis" stage, by running
-driver-only build. In other cases, analysis of the outcome files is needed,
+`tests/scripts/analyze_outcomes.py`. See the
-see the example script `outcome-analysis.sh` in the same directory.
+`analyze_driver_vs_reference_xxx` actions in the script and the comments above
+their declaration for how to do that locally.
 
 
 Migrating away from the legacy API

docs/architecture/testing/test-framework.md

@@ -6,7 +6,7 @@ This document is incomplete. You can help by expanding it.
 
 ## Unit tests
 
-See <https://tls.mbed.org/kb/development/test_suites>
+See <https://mbed-tls.readthedocs.io/en/latest/kb/development/test_suites>
 
 ### Unit test descriptions
 

docs/architecture/tls13-support.md

@@ -28,9 +28,12 @@ Support description
 
   - Mbed TLS does not support DHE key establishment.
 
-  - Mbed TLS does not support pre-shared keys, including any form of
+  - Mbed TLS supports pre-shared keys for key establishment, pre-shared keys
-    session resumption. This implies that it does not support sending early
+    provisioned externally as well as provisioned via the ticket mechanism.
-    data (0-RTT data).
+
+  - Mbed TLS supports session resumption via the ticket mechanism.
+
+  - Mbed TLS does not support sending or receiving early data (0-RTT data).
 
 - Supported cipher suites: depends on the library configuration. Potentially
   all of them:
@@ -54,8 +57,8 @@ Support description
   | server_certificate_type      | no      |
   | padding                      | no      |
   | key_share                    | YES     |
-  | pre_shared_key               | no      |
+  | pre_shared_key               | YES     |
-  | psk_key_exchange_modes       | no      |
+  | psk_key_exchange_modes       | YES     |
   | early_data                   | no      |
   | cookie                       | no      |
   | supported_versions           | YES     |
@@ -118,7 +121,7 @@ Support description
   | MBEDTLS_SSL_RENEGOTIATION                | n/a     |
   | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH          | no      |
   |                                          |         |
-  | MBEDTLS_SSL_SESSION_TICKETS              | no      |
+  | MBEDTLS_SSL_SESSION_TICKETS              | yes     |
   | MBEDTLS_SSL_SERVER_NAME_INDICATION       | yes     |
   | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH       | no      |
   |                                          |         |
@@ -141,10 +144,33 @@ Support description
   | MBEDTLS_USE_PSA_CRYPTO                   | yes     |
 
   (1) These options must remain in their default state of enabled.
-  (2) Key exchange configuration options for TLS 1.3 will likely to be
+  (2) See the TLS 1.3 specific build options section below.
-      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
+- TLS 1.3 specific build options:
-      runtime configuration macros.
+
+  - MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE enables the support for middlebox
+    compatibility mode as defined in section D.4 of RFC 8446.
+
+  - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED enables the support for
+    the PSK key exchange mode as defined by RFC 8446. If it is the only key
+    exchange mode enabled, the TLS 1.3 implementation does not contain any code
+    related to key exchange protocols, certificates and signatures.
+
+  - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED enables the
+    support for the ephemeral key exchange mode. If it is the only key exchange
+    mode enabled, the TLS 1.3 implementation does not contain any code related
+    to PSK based key exchange. The ephemeral key exchange mode requires at least
+    one of the key exchange protocol allowed by the TLS 1.3 specification, the
+    parsing and validation of x509 certificates and at least one signature
+    algorithm allowed by the TLS 1.3 specification for signature computing and
+    verification.
+
+  - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED enables the
+    support for the PSK ephemeral key exchange mode. If it is the only key
+    exchange mode enabled, the TLS 1.3 implementation does not contain any code
+    related to certificates and signatures. The PSK ephemeral key exchange
+    mode requires at least one of the key exchange protocol allowed by the
+    TLS 1.3 specification.
 
 
 Prototype upstreaming status
@@ -152,8 +178,7 @@ Prototype upstreaming status
 
 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
+- Sending (client) and receiving (server) early data (0-RTT data).
-  side).
 
 - New TLS Message Processing Stack (MPS)
 
@@ -181,7 +206,7 @@ Coding rules checklist for TLS 1.3
 The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming
 work to reduce review rounds and the number of comments in each round. They
 come along (do NOT replace) the project coding rules
-(https://tls.mbed.org/kb/development/mbedtls-coding-standards). They have been
+(https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards). They have been
 established and discussed following the review of #4882 that was the
 PR upstreaming the first part of TLS 1.3 ClientHello writing code.
 
@@ -453,3 +478,175 @@ 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.
+
+
+Writing and reading early or 0-RTT data
+---------------------------------------
+
+An application function to write and send a buffer of data to a server through
+TLS may plausibly look like:
+
+```
+int write_data( mbedtls_ssl_context *ssl,
+                const unsigned char *data_to_write,
+                size_t data_to_write_len,
+                size_t *data_written )
+{
+    *data_written = 0;
+
+    while( *data_written < data_to_write_len )
+    {
+        ret = mbedtls_ssl_write( ssl, data_to_write + *data_written,
+                                 data_to_write_len - *data_written );
+
+        if( ret < 0 &&
+            ret != MBEDTLS_ERR_SSL_WANT_READ &&
+            ret != MBEDTLS_ERR_SSL_WANT_WRITE )
+        {
+            return( ret );
+        }
+
+        *data_written += ret;
+    }
+
+    return( 0 );
+}
+```
+where ssl is the SSL context to use, data_to_write the address of the data
+buffer and data_to_write_len the number of data bytes. The handshake may
+not be completed, not even started for the SSL context ssl when the function is
+called and in that case the mbedtls_ssl_write() API takes care transparently of
+completing the handshake before to write and send data to the server. The
+mbedtls_ssl_write() may not been able to write and send all data in one go thus
+the need for a loop calling it as long as there are still data to write and
+send.
+
+An application function to write and send early data and only early data,
+data sent during the first flight of client messages while the handshake is in
+its initial phase, would look completely similar but the call to
+mbedtls_ssl_write_early_data() instead of mbedtls_ssl_write().
+```
+int write_early_data( mbedtls_ssl_context *ssl,
+                      const unsigned char *data_to_write,
+                      size_t data_to_write_len,
+                      size_t *data_written )
+{
+    *data_written = 0;
+
+    while( *data_written < data_to_write_len )
+    {
+        ret = mbedtls_ssl_write_early_data( ssl, data_to_write + *data_written,
+                                            data_to_write_len - *data_written );
+
+        if( ret < 0 &&
+            ret != MBEDTLS_ERR_SSL_WANT_READ &&
+            ret != MBEDTLS_ERR_SSL_WANT_WRITE )
+        {
+            return( ret );
+        }
+
+        *data_written += ret;
+    }
+
+    return( 0 );
+}
+```
+Note that compared to write_data(), write_early_data() can also return
+MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA and that should be handled
+specifically by the user of write_early_data(). A fresh SSL context (typically
+just after a call to mbedtls_ssl_setup() or mbedtls_ssl_session_reset()) would
+be expected when calling `write_early_data`.
+
+All together, code to write and send a buffer of data as long as possible as
+early data and then as standard post-handshake application data could
+plausibly look like:
+
+```
+ret = write_early_data( ssl, data_to_write, data_to_write_len,
+                        &early_data_written );
+if( ret < 0 &&
+    ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA )
+{
+    goto error;
+}
+
+ret = write_data( ssl, data_to_write + early_data_written,
+                  data_to_write_len - early_data_written, &data_written );
+if( ret < 0 )
+    goto error;
+
+data_written += early_data_written;
+```
+
+Finally, taking into account that the server may reject early data, application
+code to write and send a buffer of data could plausibly look like:
+```
+ret = write_early_data( ssl, data_to_write, data_to_write_len,
+                        &early_data_written );
+if( ret < 0 &&
+    ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA )
+{
+    goto error;
+}
+
+/*
+ * Make sure the handshake is completed as it is a requisite to
+ * mbedtls_ssl_get_early_data_status().
+ */
+while( !mbedtls_ssl_is_handshake_over( ssl ) )
+{
+    ret = mbedtls_ssl_handshake( ssl );
+    if( ret < 0 &&
+        ret != MBEDTLS_ERR_SSL_WANT_READ &&
+        ret != MBEDTLS_ERR_SSL_WANT_WRITE )
+    {
+        goto error;
+    }
+}
+
+ret = mbedtls_ssl_get_early_data_status( ssl );
+if( ret < 0 )
+    goto error;
+
+if( ret == MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED )
+   early_data_written = 0;
+
+ret = write_data( ssl, data_to_write + early_data_written,
+                  data_to_write_len - early_data_written, &data_written );
+if( ret < 0 )
+    goto error;
+
+data_written += early_data_written;
+```
+
+Basically, the same holds for reading early data on the server side without the
+complication of possible rejection. An application function to read early data
+into a given buffer could plausibly look like:
+```
+int read_early_data( mbedtls_ssl_context *ssl,
+                     unsigned char *buffer,
+                     size_t buffer_size,
+                     size_t *data_len )
+{
+    *data_len = 0;
+
+    while( *data_len < buffer_size )
+    {
+        ret = mbedtls_ssl_read_early_data( ssl, buffer + *data_len,
+                                           buffer_size - *data_len );
+
+        if( ret < 0 &&
+            ret != MBEDTLS_ERR_SSL_WANT_READ &&
+            ret != MBEDTLS_ERR_SSL_WANT_WRITE )
+        {
+            return( ret );
+        }
+
+        *data_len += ret;
+    }
+
+    return( 0 );
+}
+```
+with again calls to read_early_data() expected to be done with a fresh SSL
+context.

docs/getting_started.md

@@ -1,8 +1,9 @@
-## Getting started with Mbed Crypto
+## Getting started with Mbed TLS
 
-### What is Mbed Crypto?
+### What is Mbed TLS?
 
-Mbed Crypto is an open source cryptographic library that supports a wide range of cryptographic operations, including:
+Mbed TLS is an open source cryptographic library that supports a wide range of
+cryptographic operations, including:
 * Key management
 * Hashing
 * Symmetric cryptography
@@ -11,20 +12,25 @@ Mbed Crypto is an open source cryptographic library that supports a wide range o
 * Key generation and derivation
 * Authenticated encryption with associated data (AEAD)
 
-The Mbed Crypto library is a reference implementation of the cryptography interface of the Arm Platform Security Architecture (PSA). It is written in portable C.
+Mbed TLS provides a reference implementation of the cryptography interface of
+the Arm Platform Security Architecture (PSA). It is written in portable C.
 
-The Mbed Crypto library is distributed under the Apache License, version 2.0.
+Mbed TLS is distributed under the Apache License, version 2.0.
 
 #### Platform Security Architecture (PSA)
 
 Arm's Platform Security Architecture (PSA) is a holistic set of threat models,
-security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that enables you to design security into both hardware and firmware consistently. Part of the API provided by PSA is the cryptography interface, which provides access to a set of primitives.
+security analyses, hardware and firmware architecture specifications, and an
+open source firmware reference implementation. PSA provides a recipe, based on
+industry best practice, that enables you to design security into both hardware
+and firmware consistently. Part of the API provided by PSA is the cryptography
+interface, which provides access to a set of primitives.
 
-### Using Mbed Crypto
+### Using Mbed TLS
 
-* [Getting the Mbed Crypto library](#getting-the-mbed-crypto-library)
+* [Getting the Mbed TLS library](#getting-the-mbed-tls-library)
-* [Building the Mbed Crypto library](#building-the-mbed-crypto-library)
+* [Building the Mbed TLS library](#building-the-mbed-tls-library)
-* [Using the Mbed Crypto library](#using-the-mbed-crypto-library)
+* [Using the PSA Crypto API](#using-the-psa-crypto-api)
 * [Importing a key](#importing-a-key)
 * [Signing a message using RSA](#signing-a-message-using-RSA)
 * [Encrypting or decrypting using symmetric ciphers](#encrypting-or-decrypting-using-symmetric-ciphers)
@@ -33,37 +39,45 @@ security analyses, hardware and firmware architecture specifications, and an ope
 * [Generating a random value](#generating-a-random-value)
 * [Authenticating and encrypting or decrypting a message](#authenticating-and-encrypting-or-decrypting-a-message)
 * [Generating and exporting keys](#generating-and-exporting-keys)
-* [More about the Mbed Crypto library](#more-about-the-mbed-crypto-library)
+* [More about the PSA Crypto API](#more-about-the-psa-crypto-api)
 
-### Getting the Mbed Crypto library
+### Getting the Mbed TLS library
 
-Mbed Crypto releases are available in the [public GitHub repository](https://github.com/ARMmbed/mbed-crypto).
+Mbed TLS releases are available in the [public GitHub repository](https://github.com/Mbed-TLS/mbedtls).
 
-### Building the Mbed Crypto library
+### Building the Mbed TLS library
 
 **Prerequisites to building the library with the provided makefiles:**
 * GNU Make.
-* A C toolchain (compiler, linker, archiver).
+* A C toolchain (compiler, linker, archiver) that supports C99.
-* Python 2 or Python 3 (either works) to generate the test code.
+* Python 3.6 to generate the test code.
 * Perl to run the tests.
 
-If you have a C compiler such as GCC or Clang, just run `make` in the top-level directory to build the library, a set of unit tests and some sample programs.
+If you have a C compiler such as GCC or Clang, just run `make` in the top-level
+directory to build the library, a set of unit tests and some sample programs.
 
-To select a different compiler, set the `CC` variable to the name or path of the compiler and linker (default: `cc`) and set `AR` to a compatible archiver (default: `ar`); for example:
+To select a different compiler, set the `CC` variable to the name or path of the
+compiler and linker (default: `cc`) and set `AR` to a compatible archiver
+(default: `ar`); for example:
 ```
 make CC=arm-linux-gnueabi-gcc AR=arm-linux-gnueabi-ar
 ```
-The provided makefiles pass options to the compiler that assume a GCC-like command line syntax. To use a different compiler, you may need to pass different values for `CFLAGS`, `WARNINGS_CFLAGS` and `LDFLAGS`.
+The provided makefiles pass options to the compiler that assume a GCC-like
+command line syntax. To use a different compiler, you may need to pass different
+values for `CFLAGS`, `WARNINGS_CFLAGS` and `LDFLAGS`.
 
-To run the unit tests on the host machine, run `make test` from the top-level directory. If you are cross-compiling, copy the test executable from the `tests` directory to the target machine.
+To run the unit tests on the host machine, run `make test` from the top-level
+directory. If you are cross-compiling, copy the test executable from the `tests`
+directory to the target machine.
 
-### Using the Mbed Crypto library
+### Using the PSA Crypto API
 
-To use the Mbed Crypto APIs, call `psa_crypto_init()` before calling any other API. This initializes the library.
+If using PSA Crypto, you must initialize the library by calling
+`psa_crypto_init()` before any other PSA API.
 
 ### Importing a key
 
-To use a key for cryptography operations in Mbed Crypto, you need to first
+To use a key for cryptography operations in PSA, you need to first
 import it. The import operation returns the identifier of the key for use
 with other function calls.
 
@@ -114,7 +128,8 @@ void import_a_key(const uint8_t *key, size_t key_len)
 
 ### Signing a message using RSA
 
-Mbed Crypto supports encrypting, decrypting, signing and verifying messages using public key signature algorithms, such as RSA or ECDSA.
+The PSA Crypto API supports encrypting, decrypting, signing and verifying
+messages using public key signature algorithms, such as RSA or ECDSA.
 
 **Prerequisites to performing asymmetric signature operations:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
@@ -184,21 +199,33 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
 
 ### Using symmetric ciphers
 
-Mbed Crypto supports encrypting and decrypting messages using various symmetric cipher algorithms (both block and stream ciphers).
+The PSA Crypto API supports encrypting and decrypting messages using various
+symmetric cipher algorithms (both block and stream ciphers).
 
 **Prerequisites to working with the symmetric cipher API:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
-* Have a symmetric key. This key's usage flags must include `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption.
+* Have a symmetric key. This key's usage flags must include
+  `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to
+  allow decryption.
 
 **To encrypt a message with a symmetric cipher:**
-1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
+1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the
+   cipher functions.
 1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
-1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be used.
+1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be
-1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommend calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
+   used.
-1. Call `psa_cipher_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
+1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate
-1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.
+   or set the initialization vector (IV). We recommend calling
+   `psa_cipher_generate_iv()`, unless you require a specific IV value.
+1. Call `psa_cipher_update()` with the message to encrypt. You may call this
+   function multiple times, passing successive fragments of the message on
+   successive calls.
+1. Call `psa_cipher_finish()` to end the operation and output the encrypted
+   message.
 
-This example shows how to encrypt data using an AES (Advanced Encryption Standard) key in CBC (Cipher Block Chaining) mode with no padding (assuming all prerequisites have been fulfilled):
+This example shows how to encrypt data using an AES (Advanced Encryption
+Standard) key in CBC (Cipher Block Chaining) mode with no padding (assuming all
+prerequisites have been fulfilled):
 ```c
 void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
 {
@@ -275,15 +302,20 @@ void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
 ```
 
 **To decrypt a message with a symmetric cipher:**
-1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
+1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the
+   cipher functions.
 1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
-1. Call `psa_cipher_decrypt_setup()` to specify the algorithm and the key to be used.
+1. Call `psa_cipher_decrypt_setup()` to specify the algorithm and the key to be
+   used.
 1. Call `psa_cipher_set_iv()` with the IV for the decryption.
-1. Call `psa_cipher_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
+1. Call `psa_cipher_update()` with the message to encrypt. You may call this
-1. Call `psa_cipher_finish()` to end the operation and output the decrypted message.
+   function multiple times, passing successive fragments of the message on
+   successive calls.
+1. Call `psa_cipher_finish()` to end the operation and output the decrypted
+   message.
 
-This example shows how to decrypt encrypted data using an AES key in CBC mode with no padding
+This example shows how to decrypt encrypted data using an AES key in CBC mode
-(assuming all prerequisites have been fulfilled):
+with no padding (assuming all prerequisites have been fulfilled):
 ```c
 void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
 {
@@ -360,34 +392,49 @@ void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
 
 #### Handling cipher operation contexts
 
-After you've initialized the operation structure with a successful call to `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`, you can terminate the operation at any time by calling `psa_cipher_abort()`.
+After you've initialized the operation structure with a successful call to
+`psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`, you can terminate
+the operation at any time by calling `psa_cipher_abort()`.
 
-The call to `psa_cipher_abort()` frees any resources associated with the operation, except for the operation structure itself.
+The call to `psa_cipher_abort()` frees any resources associated with the
+operation, except for the operation structure itself.
 
-Mbed Crypto implicitly calls `psa_cipher_abort()` when:
+The PSA Crypto API implicitly calls `psa_cipher_abort()` when:
-* A call to `psa_cipher_generate_iv()`, `psa_cipher_set_iv()` or `psa_cipher_update()` fails (returning any status other than `PSA_SUCCESS`).
+* A call to `psa_cipher_generate_iv()`, `psa_cipher_set_iv()` or
+  `psa_cipher_update()` fails (returning any status other than `PSA_SUCCESS`).
 * A call to `psa_cipher_finish()` succeeds or fails.
 
-After an implicit or explicit call to `psa_cipher_abort()`, the operation structure is invalidated; in other words, you cannot reuse the operation structure for the same operation. You can, however, reuse the operation structure for a different operation by calling either `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` again.
+After an implicit or explicit call to `psa_cipher_abort()`, the operation
+structure is invalidated; in other words, you cannot reuse the operation
+structure for the same operation. You can, however, reuse the operation
+structure for a different operation by calling either
+`psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` again.
 
-You must call `psa_cipher_abort()` at some point for any operation that is initialized successfully (by a successful call to `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`).
+You must call `psa_cipher_abort()` at some point for any operation that is
+initialized successfully (by a successful call to `psa_cipher_encrypt_setup()`
+or `psa_cipher_decrypt_setup()`).
 
-Making multiple sequential calls to `psa_cipher_abort()` on an operation that is terminated (either implicitly or explicitly) is safe and has no effect.
+Making multiple sequential calls to `psa_cipher_abort()` on an operation that
+is terminated (either implicitly or explicitly) is safe and has no effect.
 
 ### Hashing a message
 
-Mbed Crypto lets you compute and verify hashes using various hashing
+The PSA Crypto API lets you compute and verify hashes using various hashing
 algorithms.
 
 **Prerequisites to working with the hash APIs:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 
 **To calculate a hash:**
-1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions.
+1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash
+   functions.
 1. Initialize the operation structure to zero or to `PSA_HASH_OPERATION_INIT`.
 1. Call `psa_hash_setup()` to specify the hash algorithm.
-1. Call `psa_hash_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
+1. Call `psa_hash_update()` with the message to encrypt. You may call this
-1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to compare the computed hash with an expected hash value.
+   function multiple times, passing successive fragments of the message on
+   successive calls.
+1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to
+   compare the computed hash with an expected hash value.
 
 This example shows how to calculate the SHA-256 hash of a message:
 ```c
@@ -482,33 +529,46 @@ This example shows how to verify the SHA-256 hash of a message:
     mbedtls_psa_crypto_free();
 ```
 
-The API provides the macro `PSA_HASH_LENGTH`, which returns the expected hash length (in bytes) for the specified algorithm.
+The API provides the macro `PSA_HASH_LENGTH`, which returns the expected hash
+length (in bytes) for the specified algorithm.
 
 #### Handling hash operation contexts
 
-After a successful call to `psa_hash_setup()`, you can terminate the operation at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees any resources associated with the operation, except for the operation structure itself.
+After a successful call to `psa_hash_setup()`, you can terminate the operation
+at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees
+any resources associated with the operation, except for the operation structure
+itself.
 
-Mbed Crypto implicitly calls `psa_hash_abort()` when:
+The PSA Crypto API implicitly calls `psa_hash_abort()` when:
-1. A call to `psa_hash_update()` fails (returning any status other than `PSA_SUCCESS`).
+1. A call to `psa_hash_update()` fails (returning any status other than
+   `PSA_SUCCESS`).
 1. A call to `psa_hash_finish()` succeeds or fails.
 1. A call to `psa_hash_verify()` succeeds or fails.
 
-After an implicit or explicit call to `psa_hash_abort()`, the operation structure is invalidated; in other words, you cannot reuse the operation structure for the same operation. You can, however, reuse the operation structure for a different operation by calling `psa_hash_setup()` again.
+After an implicit or explicit call to `psa_hash_abort()`, the operation
+structure is invalidated; in other words, you cannot reuse the operation
+structure for the same operation. You can, however, reuse the operation
+structure for a different operation by calling `psa_hash_setup()` again.
 
-You must call `psa_hash_abort()` at some point for any operation that is initialized successfully (by a successful call to `psa_hash_setup()`) .
+You must call `psa_hash_abort()` at some point for any operation that is
+initialized successfully (by a successful call to `psa_hash_setup()`) .
 
-Making multiple sequential calls to `psa_hash_abort()` on an operation that has already been terminated (either implicitly or explicitly) is safe and has no effect.
+Making multiple sequential calls to `psa_hash_abort()` on an operation that has
+already been terminated (either implicitly or explicitly) is safe and has no
+effect.
 
 ### Generating a random value
 
-Mbed Crypto can generate random data.
+The PSA Crypto API can generate random data.
 
 **Prerequisites to generating random data:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 
-<span class="notes">**Note:** To generate a random key, use `psa_generate_key()` instead of `psa_generate_random()`.</span>
+<span class="notes">**Note:** To generate a random key, use `psa_generate_key()`
+instead of `psa_generate_random()`.</span>
 
-This example shows how to generate ten bytes of random data by calling `psa_generate_random()`:
+This example shows how to generate ten bytes of random data by calling
+`psa_generate_random()`:
 ```C
     psa_status_t status;
     uint8_t random[10] = { 0 };
@@ -537,16 +597,19 @@ This example shows how to generate ten bytes of random data by calling `psa_gene
 
 ### Deriving a new key from an existing key
 
-Mbed Crypto provides a key derivation API that lets you derive new keys from
+The PSA Crypto API provides a key derivation API that lets you derive new keys
-existing ones. The key derivation API has functions to take inputs, including
+from existing ones. The key derivation API has functions to take inputs,
-other keys and data, and functions to generate outputs, such as new keys or
+including other keys and data, and functions to generate outputs, such as
-other data.
+new keys or other data.
 
 You must first initialize and set up a key derivation context,
-provided with a key and, optionally, other data. Then, use the key derivation context to either read derived data to a buffer or send derived data directly to a key slot.
+provided with a key and, optionally, other data. Then, use the key derivation
+context to either read derived data to a buffer or send derived data directly
+to a key slot.
 
-See the documentation for the particular algorithm (such as HKDF or the TLS1.2 PRF) for
+See the documentation for the particular algorithm (such as HKDF or the
-information about which inputs to pass when, and when you can obtain which outputs.
+TLS 1.2 PRF) for information about which inputs to pass when, and when you can
+obtain which outputs.
 
 **Prerequisites to working with the key derivation APIs:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
@@ -563,11 +626,11 @@ with a given key, salt and info:**
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
 1. Provide an optional salt with `psa_key_derivation_input_bytes()`.
 1. Provide info with `psa_key_derivation_input_bytes()`.
-1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key that
+1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key
-   can be used for key derivation.
+   that can be used for key derivation.
 1. Set the key attributes desired for the new derived key. We'll set
-   the `PSA_KEY_USAGE_ENCRYPT` usage flag and the `PSA_ALG_CTR` algorithm for this
+   the `PSA_KEY_USAGE_ENCRYPT` usage flag and the `PSA_ALG_CTR` algorithm for
-   example.
+   this example.
 1. Derive the key by calling `psa_key_derivation_output_key()`.
 1. Clean up the key derivation context.
 
@@ -675,11 +738,13 @@ derived from the key, salt and info provided:
 
 ### Authenticating and encrypting or decrypting a message
 
-Mbed Crypto provides a simple way to authenticate and encrypt with associated data (AEAD), supporting the `PSA_ALG_CCM` algorithm.
+The PSA Crypto API provides a simple way to authenticate and encrypt with
+associated data (AEAD), supporting the `PSA_ALG_CCM` algorithm.
 
 **Prerequisites to working with the AEAD cipher APIs:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
-* The key attributes for the key used for derivation must have the `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT` usage flags.
+* The key attributes for the key used for derivation must have the
+  `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT` usage flags.
 
 This example shows how to authenticate and encrypt a message:
 ```C
@@ -829,7 +894,7 @@ This example shows how to authenticate and decrypt a message:
 
 ### Generating and exporting keys
 
-Mbed Crypto provides a simple way to generate a key or key pair.
+The PSA Crypto API provides a simple way to generate a key or key pair.
 
 **Prerequisites to using key generation and export APIs:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
@@ -837,7 +902,9 @@ Mbed Crypto provides a simple way to generate a key or key pair.
 **To generate an ECDSA key:**
 1. Set the desired key attributes for key generation by calling
    `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as
-   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). You only want to export the public key, not the key pair (or private key); therefore, do not set `PSA_KEY_USAGE_EXPORT`.
+   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). You only want to export the
+   public key, not the key pair (or private key); therefore, do not
+   set `PSA_KEY_USAGE_EXPORT`.
 1. Generate a key by calling `psa_generate_key()`.
 1. Export the generated public key by calling `psa_export_public_key()`:
 ```C
@@ -891,4 +958,5 @@ Mbed Crypto provides a simple way to generate a key or key pair.
 
 ### More about the PSA Crypto API
 
-For more information about the PSA Crypto API, please see the [PSA Cryptography API Specification](https://armmbed.github.io/mbed-crypto/html/index.html).
+For more information about the PSA Crypto API, please see the
+[PSA Cryptography API Specification](https://arm-software.github.io/psa-api/crypto/).

docs/proposed/psa-driver-developer-guide.md

@@ -36,6 +36,12 @@ A driver therefore consists of:
 
 Mbed TLS calls driver entry points [as specified in the PSA Cryptography Driver Interface specification](psa-driver-interface.html#driver-entry-points) except as otherwise indicated in this section.
 
+## Mbed TLS extensions
+
+The driver description can include Mbed TLS extensions (marked by the namespace "mbedtls"). Mbed TLS extensions are meant to extend/help integrating the driver into the library's infrastructure.
+* `"mbedtls/h_condition"` (optional, string) can include complex preprocessor definitions to conditionally include header files for a given driver. 
+* `"mbedtls/c_condition"` (optional, string) can include complex preprocessor definitions to conditionally enable dispatch capabilities for a driver.
+
 ## Building and testing your driver
 
 <!-- TODO -->

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

@@ -13,20 +13,28 @@ During the process of implementation there might be minor variations wrt version
 
 ## Prerequisites
 
-Python3 and Jinja2 rev 2.10.1
+Python3, Jinja2 rev 2.10.1 and jsonschema rev 3.2.0
 
 ## Feature Version
 
-1.0
+1.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 description JSON file(s).
 
-While that is the larger goal, for version 1.0 here's what's changed
+While that is the larger goal, for version 1.1 here's what's changed
 
 #### What's changed
 
 (1) psa_crypto_driver_wrappers.c will from this point on be auto generated.
-(2) The auto generation is based on the template file at scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja.
+(2) The auto generation is based on the template file at **scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja**.
-(3) So while all driver wrapper templating support is yet to come in, the library user will need to patch into the template file as needed, this could be read as replacing the template file with the current psa_crypto_driver_wrappers.c file maintained by the library user.
+(3) The driver JSONS to be used for generating the psa_crypto_driver_wrappers.c file can be found at **scripts/data_files/driver_jsons/** as their default location, this path includes the schemas against which the driver schemas will be validated (driver_opaque_schema.json, driver_transparent_schema.json) and a driverlist.json which specifies the drivers to be considered and the order in which they want to be called into. The default location for driverlist.json and driver JSONS can be overloaded by passing an argument --json-dir while running the script generate_driver_wrappers.py.
+(4) While the complete driver wrapper templating support is yet to come in, if the library user sees a need to patch psa_crypto_driver_wrappers.c file, the user will need to patch into the template file as needed (psa_crypto_driver_wrappers.c.jinja).
+
+#### How to set your driver up
+
+Please refer to psa-driver-interface.md for information on how a driver schema can be written.
+One can also refer to the example test drivers/ JSON schemas under **scripts/data_files/driver_jsons/**.
+
+The JSON file 'driverlist.json' is meant to be edited by the user to reflect the drivers one wants to use on a device. The order in which the drivers are passed is also essential if/when there are multiple transparent drivers on a given system to retain the same order in the templating.

docs/use-psa-crypto.md

@@ -7,9 +7,6 @@ operations, and enables new APIs for using keys handled by PSA Crypto.
 General considerations
 ----------------------
 
-**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
-`MBEDTLS_ECP_RESTARTABLE` to be disabled.
-
 **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.
@@ -86,30 +83,33 @@ is enabled, no change required on the application side.
 
 Current exceptions:
 
-- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED` is defined)
+- Finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
-- finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
+  DHE-PSK).
-  DHE-PSK)
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
+  the documentation of that option).
 
 Other than the above exceptions, all crypto operations are based on PSA when
 `MBEDTLS_USE_PSA_CRYPTO` is enabled.
 
 ### X.509: most crypto operations based on PSA
 
-Current exception:
+Current exceptions:
 
-- verification of RSA-PSS signatures with a salt length that is different from
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
-  the hash length.
+  the documentation of that option).
 
 Other than the above exception, all crypto operations are based on PSA when
 `MBEDTLS_USE_PSA_CRYPTO` is enabled.
 
 ### PK layer: most crypto operations based on PSA
 
-Current exception:
+Current exceptions:
 
-- verification of RSA-PSS signatures with a salt length that is different from
+- Verification of RSA-PSS signatures with an MGF hash that's different from
-  the hash length, or with an MGF hash that's different from the message hash.
+  the message hash.
+- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
+  the documentation of that option).
 
-Other than the above exception, all crypto operations are based on PSA when
+Other than the above exceptions, all crypto operations are based on PSA when
 `MBEDTLS_USE_PSA_CRYPTO` is enabled.
 

doxygen/input/doc_encdec.h

@@ -38,7 +38,7 @@
  * All symmetric encryption algorithms are accessible via the generic cipher layer
  * (see \c mbedtls_cipher_setup()).
  *
- * The asymmetric encryptrion algorithms are accessible via the generic public
+ * The asymmetric encryption algorithms are accessible via the generic public
  * key layer (see \c mbedtls_pk_init()).
  *
  * The following algorithms are provided:

doxygen/input/doc_mainpage.h

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

doxygen/mbedtls.doxyfile

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

include/mbedtls/aes.h

@@ -61,11 +61,6 @@
 /** Invalid input data. */
 #define MBEDTLS_ERR_AES_BAD_INPUT_DATA                    -0x0021
 
-#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
-    !defined(inline) && !defined(__cplusplus)
-#define inline __inline
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -77,8 +72,7 @@ extern "C" {
 /**
  * \brief The AES context-type definition.
  */
-typedef struct mbedtls_aes_context
+typedef struct mbedtls_aes_context {
-{
     int MBEDTLS_PRIVATE(nr);                     /*!< The number of rounds. */
     size_t MBEDTLS_PRIVATE(rk_offset);           /*!< The offset in array elements to AES
                                                     round keys in the buffer. */
@@ -97,8 +91,7 @@ mbedtls_aes_context;
 /**
  * \brief The AES XTS context-type definition.
  */
-typedef struct mbedtls_aes_xts_context
+typedef struct mbedtls_aes_xts_context {
-{
     mbedtls_aes_context MBEDTLS_PRIVATE(crypt); /*!< The AES context to use for AES block
                                                    encryption or decryption. */
     mbedtls_aes_context MBEDTLS_PRIVATE(tweak); /*!< The AES context used for tweak

include/mbedtls/aria.h

@@ -61,8 +61,7 @@ extern "C" {
 /**
  * \brief The ARIA context-type definition.
  */
-typedef struct mbedtls_aria_context
+typedef struct mbedtls_aria_context {
-{
     unsigned char MBEDTLS_PRIVATE(nr);           /*!< The number of rounds (12, 14 or 16) */
     /*! The ARIA round keys. */
     uint32_t MBEDTLS_PRIVATE(rk)[MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];

include/mbedtls/asn1.h

@@ -24,6 +24,7 @@
 #include "mbedtls/private_access.h"
 
 #include "mbedtls/build_info.h"
+#include "mbedtls/platform_util.h"
 
 #include <stddef.h>
 
@@ -38,8 +39,9 @@
 
 /**
  * \name ASN1 Error codes
- * These error codes are OR'ed to X509 error codes for
+ * These error codes are combined with other error codes for
  * higher error granularity.
+ * e.g. X.509 and PKCS #7 error codes
  * ASN1 is a standard to specify data structures.
  * \{
  */
@@ -149,8 +151,7 @@ extern "C" {
 /**
  * Type-length-value structure that allows for ASN1 using DER.
  */
-typedef struct mbedtls_asn1_buf
+typedef struct mbedtls_asn1_buf {
-{
     int tag;                /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
     size_t len;             /**< ASN1 length, in octets. */
     unsigned char *p;       /**< ASN1 data, e.g. in ASCII. */
@@ -160,8 +161,7 @@ mbedtls_asn1_buf;
 /**
  * Container for ASN1 bit strings.
  */
-typedef struct mbedtls_asn1_bitstring
+typedef struct mbedtls_asn1_bitstring {
-{
     size_t len;                 /**< ASN1 length, in octets. */
     unsigned char unused_bits;  /**< Number of unused bits at the end of the string */
     unsigned char *p;           /**< Raw ASN1 data for the bit string */
@@ -171,8 +171,7 @@ mbedtls_asn1_bitstring;
 /**
  * Container for a sequence of ASN.1 items
  */
-typedef struct mbedtls_asn1_sequence
+typedef struct mbedtls_asn1_sequence {
-{
     mbedtls_asn1_buf buf;                   /**< Buffer containing the given ASN.1 item. */
 
     /** The next entry in the sequence.
@@ -189,8 +188,7 @@ mbedtls_asn1_sequence;
 /**
  * Container for a sequence or list of 'named' ASN.1 data items
  */
-typedef struct mbedtls_asn1_named_data
+typedef struct mbedtls_asn1_named_data {
-{
     mbedtls_asn1_buf oid;                   /**< The object identifier. */
     mbedtls_asn1_buf val;                   /**< The named value. */
 
@@ -606,25 +604,41 @@ int mbedtls_asn1_get_alg_null( unsigned char **p,
 const mbedtls_asn1_named_data *mbedtls_asn1_find_named_data(const mbedtls_asn1_named_data *list,
                                                             const char *oid, size_t len);
 
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 /**
  * \brief       Free a mbedtls_asn1_named_data entry
  *
+ * \deprecated  This function is deprecated and will be removed in a
+ *              future version of the library.
+ *              Please use mbedtls_asn1_free_named_data_list()
+ *              or mbedtls_asn1_free_named_data_list_shallow().
+ *
  * \param entry The named data entry to free.
  *              This function calls mbedtls_free() on
  *              `entry->oid.p` and `entry->val.p`.
  */
-void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
+void MBEDTLS_DEPRECATED mbedtls_asn1_free_named_data(mbedtls_asn1_named_data *entry);
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
 
 /**
  * \brief       Free all entries in a mbedtls_asn1_named_data list.
  *
  * \param head  Pointer to the head of the list of named data entries to free.
- *              This function calls mbedtls_asn1_free_named_data() and
+ *              This function calls mbedtls_free() on
- *              mbedtls_free() on each list element and
+ *              `entry->oid.p` and `entry->val.p` and then on `entry`
- *              sets \c *head to \c NULL.
+ *              for each list entry, and sets \c *head to \c NULL.
  */
 void mbedtls_asn1_free_named_data_list(mbedtls_asn1_named_data **head);
 
+/**
+ * \brief       Free all shallow entries in a mbedtls_asn1_named_data list,
+ *              but do not free internal pointer targets.
+ *
+ * \param name  Head of the list of named data entries to free.
+ *              This function calls mbedtls_free() on each list element.
+ */
+void mbedtls_asn1_free_named_data_list_shallow(mbedtls_asn1_named_data *name);
+
 /** \} name Functions to parse ASN.1 data structures */
 /** \} addtogroup asn1_module */
 

include/mbedtls/asn1write.h

@@ -30,7 +30,7 @@
     do                                                  \
     {                                                   \
         if ((ret = (f)) < 0)                         \
-            return( ret );                              \
+        return ret;                              \
         else                                            \
         (g) += ret;                                 \
     } while (0)
@@ -352,7 +352,7 @@ int mbedtls_asn1_write_octet_string( unsigned char **p, const unsigned char *sta
  *                  the existing buffer to fit \p val_len.
  *
  * \return          A pointer to the new / existing entry on success.
- * \return          \c NULL if if there was a memory allocation error.
+ * \return          \c NULL if there was a memory allocation error.
  */
 mbedtls_asn1_named_data *mbedtls_asn1_store_named_data(mbedtls_asn1_named_data **list,
                                                        const char *oid, size_t oid_len,

include/mbedtls/bignum.h

@@ -107,7 +107,9 @@
  */
 #define MBEDTLS_MPI_MAX_BITS_SCALE100          (100 * MBEDTLS_MPI_MAX_BITS)
 #define MBEDTLS_LN_2_DIV_LN_10_SCALE100                 332
-#define MBEDTLS_MPI_RW_BUFFER_SIZE             ( ((MBEDTLS_MPI_MAX_BITS_SCALE100 + MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6 )
+#define MBEDTLS_MPI_RW_BUFFER_SIZE             (((MBEDTLS_MPI_MAX_BITS_SCALE100 + \
+                                                  MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / \
+                                                 MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6)
 
 /*
  * Define the base integer type, architecture-wise.
@@ -179,6 +181,20 @@
     #endif /* !MBEDTLS_NO_UDBL_DIVISION */
 #endif /* !MBEDTLS_HAVE_INT64 */
 
+/** \typedef mbedtls_mpi_uint
+ * \brief The type of machine digits in a bignum, called _limbs_.
+ *
+ * This is always an unsigned integer type with no padding bits. The size
+ * is platform-dependent.
+ */
+
+/** \typedef mbedtls_mpi_sint
+ * \brief The signed type corresponding to #mbedtls_mpi_uint.
+ *
+ * This is always an signed integer type with no padding bits. The size
+ * is platform-dependent.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -186,11 +202,28 @@ extern "C" {
 /**
  * \brief          MPI structure
  */
-typedef struct mbedtls_mpi
+typedef struct mbedtls_mpi {
-{
+    /** Sign: -1 if the mpi is negative, 1 otherwise.
-    int MBEDTLS_PRIVATE(s);              /*!<  Sign: -1 if the mpi is negative, 1 otherwise */
+     *
-    size_t MBEDTLS_PRIVATE(n);           /*!<  total # of limbs  */
+     * The number 0 must be represented with `s = +1`. Although many library
-    mbedtls_mpi_uint *MBEDTLS_PRIVATE(p);          /*!<  pointer to limbs  */
+     * functions treat all-limbs-zero as equivalent to a valid representation
+     * of 0 regardless of the sign bit, there are exceptions, so bignum
+     * functions and external callers must always set \c s to +1 for the
+     * number zero.
+     *
+     * Note that this implies that calloc() or `... = {0}` does not create
+     * a valid MPI representation. You must call mbedtls_mpi_init().
+     */
+    int MBEDTLS_PRIVATE(s);
+
+    /** Total number of limbs in \c p.  */
+    size_t MBEDTLS_PRIVATE(n);
+
+    /** Pointer to limbs.
+     *
+     * This may be \c NULL if \c n is 0.
+     */
+    mbedtls_mpi_uint *MBEDTLS_PRIVATE(p);
 }
 mbedtls_mpi;
 
@@ -758,11 +791,11 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A,
  *
  * \param Q        The destination MPI for the quotient.
  *                 This may be \c NULL if the value of the
- *                 quotient is not needed.
+ *                 quotient is not needed. This must not alias A or B.
  * \param R        The destination MPI for the remainder value.
  *                 This may be \c NULL if the value of the
- *                 remainder is not needed.
+ *                 remainder is not needed. This must not alias A or B.
- * \param A        The dividend. This must point to an initialized MPi.
+ * \param A        The dividend. This must point to an initialized MPI.
  * \param B        The divisor. This must point to an initialized MPI.
  *
  * \return         \c 0 if successful.
@@ -779,10 +812,10 @@ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
  *
  * \param Q        The destination MPI for the quotient.
  *                 This may be \c NULL if the value of the
- *                 quotient is not needed.
+ *                 quotient is not needed.  This must not alias A.
  * \param R        The destination MPI for the remainder value.
  *                 This may be \c NULL if the value of the
- *                 remainder is not needed.
+ *                 remainder is not needed.  This must not alias A.
  * \param A        The dividend. This must point to an initialized MPi.
  * \param b        The divisor.
  *
@@ -837,6 +870,7 @@ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A,
  * \brief          Perform a sliding-window exponentiation: X = A^E mod N
  *
  * \param X        The destination MPI. This must point to an initialized MPI.
+ *                 This must not alias E or N.
  * \param A        The base of the exponentiation.
  *                 This must point to an initialized MPI.
  * \param E        The exponent MPI. This must point to an initialized MPI.

include/mbedtls/build_info.h

@@ -37,22 +37,28 @@
  * Major, Minor, Patchlevel
  */
 #define MBEDTLS_VERSION_MAJOR  3
-#define MBEDTLS_VERSION_MINOR  2
+#define MBEDTLS_VERSION_MINOR  3
-#define MBEDTLS_VERSION_PATCH  1
+#define MBEDTLS_VERSION_PATCH  0
 
 /**
  * The single version number has the following structure:
  *    MMNNPP00
  *    Major version | Minor version | Patch version
  */
-#define MBEDTLS_VERSION_NUMBER         0x03020100
+#define MBEDTLS_VERSION_NUMBER         0x03030000
-#define MBEDTLS_VERSION_STRING         "3.2.1"
+#define MBEDTLS_VERSION_STRING         "3.3.0"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 3.2.1"
+#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 3.3.0"
 
 #if defined(_MSC_VER) && !defined(_CRT_SECURE_NO_DEPRECATE)
 #define _CRT_SECURE_NO_DEPRECATE 1
 #endif
 
+/* Define `inline` on some non-C99-compliant compilers. */
+#if (defined(__ARMCC_VERSION) || defined(_MSC_VER)) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #if !defined(MBEDTLS_CONFIG_FILE)
 #include "mbedtls/mbedtls_config.h"
 #else
@@ -74,8 +80,55 @@
 #include MBEDTLS_USER_CONFIG_FILE
 #endif
 
-#if defined(MBEDTLS_PK_C) && defined(MBEDTLS_USE_PSA_CRYPTO)
+/* The PK wrappers need pk_write functions to format RSA key objects
+ * when they are dispatching to the PSA API. This happens under USE_PSA_CRYPTO,
+ * and also even without USE_PSA_CRYPTO for mbedtls_pk_sign_ext().
+ * PSA crypto also needs pk_write to export RSA keys (otherwise the build
+ * goes through but psa_export_key() and psa_export_public_key() fail on
+ * RSA keys), and pk_parse to work with RSA keys in almost any way.
+ */
+#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_RSA_C)
+#define MBEDTLS_PK_C
 #define MBEDTLS_PK_WRITE_C
+#define MBEDTLS_PK_PARSE_C
+#endif
+
+/* Under MBEDTLS_USE_PSA_CRYPTO, the pk module needs pk_write functions
+ * to pass ECC keys to PSA. */
+#if defined(MBEDTLS_PK_C) &&                                    \
+    defined(MBEDTLS_USE_PSA_CRYPTO) && defined(MBEDTLS_ECP_C)
+#define MBEDTLS_PK_WRITE_C
+#endif
+
+#if !defined(MBEDTLS_SSL_PROTO_TLS1_2)
+#undef MBEDTLS_KEY_EXCHANGE_RSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED
+#undef MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
+#endif
+
+#if !defined(MBEDTLS_SSL_PROTO_TLS1_3)
+#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED
+#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED
+#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED
+#undef MBEDTLS_SSL_EARLY_DATA
+#endif
+
+#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED) || \
+    defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED
+#endif
+
+#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED) || \
+    defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_EPHEMERAL_ENABLED
 #endif
 
 /* Make sure all configuration symbols are set before including check_config.h,

include/mbedtls/camellia.h

@@ -50,8 +50,7 @@ extern "C" {
 /**
  * \brief          CAMELLIA context structure
  */
-typedef struct mbedtls_camellia_context
+typedef struct mbedtls_camellia_context {
-{
     int MBEDTLS_PRIVATE(nr);                     /*!<  number of rounds  */
     uint32_t MBEDTLS_PRIVATE(rk)[68];            /*!<  CAMELLIA round keys    */
 }

include/mbedtls/ccm.h

@@ -74,8 +74,7 @@ extern "C" {
  * \brief    The CCM context-type definition. The CCM context is passed
  *           to the APIs called.
  */
-typedef struct mbedtls_ccm_context
+typedef struct mbedtls_ccm_context {
-{
     unsigned char MBEDTLS_PRIVATE(y)[16];    /*!< The Y working buffer */
     unsigned char MBEDTLS_PRIVATE(ctr)[16];  /*!< The counter buffer */
     mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx);    /*!< The cipher context used. */

include/mbedtls/chacha20.h

@@ -47,8 +47,7 @@ extern "C" {
 
 #if !defined(MBEDTLS_CHACHA20_ALT)
 
-typedef struct mbedtls_chacha20_context
+typedef struct mbedtls_chacha20_context {
-{
     uint32_t MBEDTLS_PRIVATE(state)[16];          /*! The state (before round operations). */
     uint8_t  MBEDTLS_PRIVATE(keystream8)[64];     /*! Leftover keystream bytes. */
     size_t MBEDTLS_PRIVATE(keystream_bytes_used); /*! Number of keystream bytes already used. */

include/mbedtls/chachapoly.h

@@ -47,8 +47,7 @@
 extern "C" {
 #endif
 
-typedef enum
+typedef enum {
-{
     MBEDTLS_CHACHAPOLY_ENCRYPT,     /**< The mode value for performing encryption. */
     MBEDTLS_CHACHAPOLY_DECRYPT      /**< The mode value for performing decryption. */
 }
@@ -58,8 +57,7 @@ mbedtls_chachapoly_mode_t;
 
 #include "mbedtls/chacha20.h"
 
-typedef struct mbedtls_chachapoly_context
+typedef struct mbedtls_chachapoly_context {
-{
     mbedtls_chacha20_context MBEDTLS_PRIVATE(chacha20_ctx);  /**< The ChaCha20 context. */
     mbedtls_poly1305_context MBEDTLS_PRIVATE(poly1305_ctx);  /**< The Poly1305 context. */
     uint64_t MBEDTLS_PRIVATE(aad_len);                       /**< The length (bytes) of the Additional Authenticated Data. */

include/mbedtls/check_config.h

@@ -23,6 +23,7 @@
 #ifndef MBEDTLS_CHECK_CONFIG_H
 #define MBEDTLS_CHECK_CONFIG_H
 
+/* *INDENT-OFF* */
 /*
  * We assume CHAR_BIT is 8 in many places. In practice, this is true on our
  * target platforms, so not an issue, but let's just be extra sure.
@@ -32,6 +33,8 @@
 #error "mbed TLS requires a platform with 8-bit chars"
 #endif
 
+#include <stdint.h>
+
 #if defined(_WIN32)
 #if !defined(MBEDTLS_PLATFORM_C)
 #error "MBEDTLS_PLATFORM_C is required on Windows"
@@ -114,15 +117,19 @@
 #endif
 
 #if defined(MBEDTLS_ECP_RESTARTABLE)           && \
-    ( defined(MBEDTLS_USE_PSA_CRYPTO)          || \
+    ( defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
-      defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
       defined(MBEDTLS_ECDH_GEN_PUBLIC_ALT)     || \
       defined(MBEDTLS_ECDSA_SIGN_ALT)          || \
       defined(MBEDTLS_ECDSA_VERIFY_ALT)        || \
       defined(MBEDTLS_ECDSA_GENKEY_ALT)        || \
       defined(MBEDTLS_ECP_INTERNAL_ALT)        || \
       defined(MBEDTLS_ECP_ALT) )
-#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative or PSA-based ECP implementation"
+#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative ECP implementation"
+#endif
+
+#if defined(MBEDTLS_ECP_RESTARTABLE)           && \
+    !defined(MBEDTLS_ECP_C)
+#error "MBEDTLS_ECP_RESTARTABLE defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) && !defined(MBEDTLS_HMAC_DRBG_C)
@@ -327,7 +334,7 @@
 
 /* Use of EC J-PAKE in TLS requires SHA-256.
  * This will be taken from MD if it is present, or from PSA if MD is absent.
- * Note: ECJPAKE_C depends on MD_C || PSA_CRYPTO_C. */
+ * Note: MBEDTLS_ECJPAKE_C depends on MBEDTLS_MD_C || MBEDTLS_PSA_CRYPTO_C. */
 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED) &&                    \
     !( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA256_C) ) &&          \
     !( !defined(MBEDTLS_MD_C) && defined(PSA_WANT_ALG_SHA_256) )
@@ -353,6 +360,16 @@
 #error "MBEDTLS_MD_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_LMS_C) &&                                          \
+    ! ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_256) )
+#error "MBEDTLS_LMS_C requires MBEDTLS_PSA_CRYPTO_C and PSA_WANT_ALG_SHA_256"
+#endif
+
+#if defined(MBEDTLS_LMS_PRIVATE) &&                                    \
+    ( !defined(MBEDTLS_LMS_C) )
+#error "MBEDTLS_LMS_PRIVATE requires MBEDTLS_LMS_C"
+#endif
+
 #if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) &&                          \
     ( !defined(MBEDTLS_PLATFORM_C) || !defined(MBEDTLS_PLATFORM_MEMORY) )
 #error "MBEDTLS_MEMORY_BUFFER_ALLOC_C defined, but not all prerequisites"
@@ -523,6 +540,20 @@
 #error "MBEDTLS_PLATFORM_SNPRINTF_MACRO and MBEDTLS_PLATFORM_STD_SNPRINTF/MBEDTLS_PLATFORM_SNPRINTF_ALT cannot be defined simultaneously"
 #endif
 
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) && !defined(MBEDTLS_PLATFORM_C)
+#error "MBEDTLS_PLATFORM_VSNPRINTF_ALT defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO) && !defined(MBEDTLS_PLATFORM_C)
+#error "MBEDTLS_PLATFORM_VSNPRINTF_MACRO defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO) &&\
+    ( defined(MBEDTLS_PLATFORM_STD_VSNPRINTF) ||\
+        defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) )
+#error "MBEDTLS_PLATFORM_VSNPRINTF_MACRO and MBEDTLS_PLATFORM_STD_VSNPRINTF/MBEDTLS_PLATFORM_VSNPRINTF_ALT cannot be defined simultaneously"
+#endif
+
 #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR) &&\
     !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
 #error "MBEDTLS_PLATFORM_STD_MEM_HDR defined, but not all prerequisites"
@@ -664,10 +695,6 @@
 #error "MBEDTLS_X509_RSASSA_PSS_SUPPORT defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_SHA384_C) && !defined(MBEDTLS_SHA512_C)
-#error "MBEDTLS_SHA384_C defined without MBEDTLS_SHA512_C"
-#endif
-
 #if defined(MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT) && \
     defined(MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY)
 #error "Must only define one of MBEDTLS_SHA512_USE_A64_CRYPTO_*"
@@ -723,14 +750,6 @@
 #error "MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY defined on non-Aarch64 system"
 #endif
 
-#if defined(MBEDTLS_SHA224_C) && !defined(MBEDTLS_SHA256_C)
-#error "MBEDTLS_SHA224_C defined without MBEDTLS_SHA256_C"
-#endif
-
-#if defined(MBEDTLS_SHA256_C) && !defined(MBEDTLS_SHA224_C)
-#error "MBEDTLS_SHA256_C defined without MBEDTLS_SHA224_C"
-#endif
-
 #if defined(MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT) && \
     defined(MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY)
 #error "Must only define one of MBEDTLS_SHA256_USE_A64_CRYPTO_*"
@@ -782,6 +801,19 @@
 #endif /* !MBEDTLS_USE_PSA_CRYPTO */
 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
 
+#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
+#if !( defined(MBEDTLS_ECDH_C) && defined(MBEDTLS_X509_CRT_PARSE_C) && \
+       ( defined(MBEDTLS_ECDSA_C) || defined(MBEDTLS_PKCS1_V21) ) )
+#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED defined, but not all prerequisites"
+#endif
+#endif
+
+#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
+#if !( defined(MBEDTLS_ECDH_C) )
+#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED defined, but not all prerequisites"
+#endif
+#endif
+
 /*
  * The current implementation of TLS 1.3 requires MBEDTLS_SSL_KEEP_PEER_CERTIFICATE.
  */
@@ -805,6 +837,20 @@
         "but no key exchange methods defined with MBEDTLS_KEY_EXCHANGE_xxxx"
 #endif
 
+#if defined(MBEDTLS_SSL_EARLY_DATA) && \
+    ( !defined(MBEDTLS_SSL_SESSION_TICKETS) || \
+      ( !defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED) && \
+        !defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED) ) )
+#error "MBEDTLS_SSL_EARLY_DATA  defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_SSL_EARLY_DATA) && defined(MBEDTLS_SSL_SRV_C) && \
+    ( !defined(MBEDTLS_SSL_MAX_EARLY_DATA_SIZE)     || \
+      ( MBEDTLS_SSL_MAX_EARLY_DATA_SIZE < 0 )       || \
+      ( MBEDTLS_SSL_MAX_EARLY_DATA_SIZE > UINT32_MAX ) )
+#error "MBEDTLS_SSL_MAX_EARLY_DATA_SIZE MUST be defined and in range(0..UINT32_MAX)"
+#endif
+
 #if defined(MBEDTLS_SSL_PROTO_DTLS)     && \
     !defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #error "MBEDTLS_SSL_PROTO_DTLS defined, but not all prerequisites"
@@ -814,6 +860,10 @@
 #error "MBEDTLS_SSL_CLI_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_SSL_ASYNC_PRIVATE) && !defined(MBEDTLS_X509_CRT_PARSE_C)
+#error "MBEDTLS_SSL_ASYNC_PRIVATE defined, but not all prerequisites"
+#endif
+
 #if defined(MBEDTLS_SSL_TLS_C) && ( !defined(MBEDTLS_CIPHER_C) ||     \
     ( !defined(MBEDTLS_MD_C) && !defined(MBEDTLS_USE_PSA_CRYPTO) ) )
 #error "MBEDTLS_SSL_TLS_C defined, but not all prerequisites"
@@ -859,6 +909,19 @@
 #error "MBEDTLS_SSL_CID_OUT_LEN_MAX too large (max 255)"
 #endif
 
+#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT)     &&                 \
+    !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
+#error "MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT defined, but not all prerequisites"
+#endif
+
+#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT) && MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT != 0
+#if defined(MBEDTLS_DEPRECATED_REMOVED)
+#error "MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT is deprecated and will be removed in a future version of Mbed TLS"
+#elif defined(MBEDTLS_DEPRECATED_WARNING)
+#warning "MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT is deprecated and will be removed in a future version of Mbed TLS"
+#endif
+#endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT && MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT != 0 */
+
 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) &&   \
     !defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #error "MBEDTLS_SSL_ENCRYPT_THEN_MAC defined, but not all prerequisites"
@@ -950,6 +1013,11 @@
 #error "MBEDTLS_X509_CSR_WRITE_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) && \
+            ( !defined(MBEDTLS_X509_CRT_PARSE_C) )
+#error "MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK defined, but not all prerequisites"
+#endif
+
 #if defined(MBEDTLS_HAVE_INT32) && defined(MBEDTLS_HAVE_INT64)
 #error "MBEDTLS_HAVE_INT32 and MBEDTLS_HAVE_INT64 cannot be defined simultaneously"
 #endif /* MBEDTLS_HAVE_INT32 && MBEDTLS_HAVE_INT64 */
@@ -1018,6 +1086,14 @@
 #error "MBEDTLS_SSL_TRUNCATED_HMAC was removed in Mbed TLS 3.0. See https://github.com/Mbed-TLS/mbedtls/issues/4341"
 #endif
 
+#if defined(MBEDTLS_PKCS7_C) && ( ( !defined(MBEDTLS_ASN1_PARSE_C) ) || \
+    ( !defined(MBEDTLS_OID_C) ) || ( !defined(MBEDTLS_PK_PARSE_C) ) || \
+    ( !defined(MBEDTLS_X509_CRT_PARSE_C) ) ||\
+    ( !defined(MBEDTLS_X509_CRL_PARSE_C) ) || ( !defined(MBEDTLS_BIGNUM_C) ) || \
+    ( !defined(MBEDTLS_MD_C) ) )
+#error  "MBEDTLS_PKCS7_C is defined, but not all prerequisites"
+#endif
+
 /*
  * Avoid warning from -pedantic. This is a convenient place for this
  * workaround since this is included by every single file before the
@@ -1025,4 +1101,5 @@
  */
 typedef int mbedtls_iso_c_forbids_empty_translation_units;
 
+/* *INDENT-ON* */
 #endif /* MBEDTLS_CHECK_CONFIG_H */

include/mbedtls/cipher.h

@@ -46,11 +46,6 @@
 #define MBEDTLS_CIPHER_MODE_STREAM
 #endif
 
-#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
-    !defined(inline) && !defined(__cplusplus)
-#define inline __inline
-#endif
-
 /** The selected feature is not available. */
 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE  -0x6080
 /** Bad input parameters. */
@@ -76,16 +71,16 @@ extern "C" {
 /**
  * \brief     Supported cipher types.
  *
- * \warning   DES is considered weak cipher and its use
+ * \warning   DES/3DES are considered weak ciphers and their use
- *            constitutes a security risk. Arm recommends considering stronger
+ *            constitutes a security risk. We recommend considering stronger
  *            ciphers instead.
  */
 typedef enum {
     MBEDTLS_CIPHER_ID_NONE = 0,  /**< Placeholder to mark the end of cipher ID lists. */
     MBEDTLS_CIPHER_ID_NULL,      /**< The identity cipher, treated as a stream cipher. */
     MBEDTLS_CIPHER_ID_AES,       /**< The AES cipher. */
-    MBEDTLS_CIPHER_ID_DES,       /**< The DES cipher. */
+    MBEDTLS_CIPHER_ID_DES,       /**< The DES cipher. \warning DES is considered weak. */
-    MBEDTLS_CIPHER_ID_3DES,      /**< The Triple DES cipher. */
+    MBEDTLS_CIPHER_ID_3DES,      /**< The Triple DES cipher. \warning 3DES is considered weak. */
     MBEDTLS_CIPHER_ID_CAMELLIA,  /**< The Camellia cipher. */
     MBEDTLS_CIPHER_ID_ARIA,      /**< The Aria cipher. */
     MBEDTLS_CIPHER_ID_CHACHA20,  /**< The ChaCha20 cipher. */
@@ -94,8 +89,8 @@ typedef enum {
 /**
  * \brief     Supported {cipher type, cipher mode} pairs.
  *
- * \warning   DES is considered weak cipher and its use
+ * \warning   DES/3DES are considered weak ciphers and their use
- *            constitutes a security risk. Arm recommends considering stronger
+ *            constitutes a security risk. We recommend considering stronger
  *            ciphers instead.
  */
 typedef enum {
@@ -131,12 +126,12 @@ typedef enum {
     MBEDTLS_CIPHER_CAMELLIA_128_GCM,     /**< Camellia cipher with 128-bit GCM mode. */
     MBEDTLS_CIPHER_CAMELLIA_192_GCM,     /**< Camellia cipher with 192-bit GCM mode. */
     MBEDTLS_CIPHER_CAMELLIA_256_GCM,     /**< Camellia cipher with 256-bit GCM mode. */
-    MBEDTLS_CIPHER_DES_ECB,              /**< DES cipher with ECB mode. */
+    MBEDTLS_CIPHER_DES_ECB,              /**< DES cipher with ECB mode. \warning DES is considered weak. */
-    MBEDTLS_CIPHER_DES_CBC,              /**< DES cipher with CBC mode. */
+    MBEDTLS_CIPHER_DES_CBC,              /**< DES cipher with CBC mode. \warning DES is considered weak. */
-    MBEDTLS_CIPHER_DES_EDE_ECB,          /**< DES cipher with EDE ECB mode. */
+    MBEDTLS_CIPHER_DES_EDE_ECB,          /**< DES cipher with EDE ECB mode. \warning 3DES is considered weak. */
-    MBEDTLS_CIPHER_DES_EDE_CBC,          /**< DES cipher with EDE CBC mode. */
+    MBEDTLS_CIPHER_DES_EDE_CBC,          /**< DES cipher with EDE CBC mode. \warning 3DES is considered weak. */
-    MBEDTLS_CIPHER_DES_EDE3_ECB,         /**< DES cipher with EDE3 ECB mode. */
+    MBEDTLS_CIPHER_DES_EDE3_ECB,         /**< DES cipher with EDE3 ECB mode. \warning 3DES is considered weak. */
-    MBEDTLS_CIPHER_DES_EDE3_CBC,         /**< DES cipher with EDE3 CBC mode. */
+    MBEDTLS_CIPHER_DES_EDE3_CBC,         /**< DES cipher with EDE3 CBC mode. \warning 3DES is considered weak. */
     MBEDTLS_CIPHER_AES_128_CCM,          /**< AES cipher with 128-bit CCM mode. */
     MBEDTLS_CIPHER_AES_192_CCM,          /**< AES cipher with 192-bit CCM mode. */
     MBEDTLS_CIPHER_AES_256_CCM,          /**< AES cipher with 256-bit CCM mode. */
@@ -222,11 +217,11 @@ typedef enum {
 enum {
     /** Undefined key length. */
     MBEDTLS_KEY_LENGTH_NONE = 0,
-    /** Key length, in bits (including parity), for DES keys. */
+    /** Key length, in bits (including parity), for DES keys. \warning DES is considered weak. */
     MBEDTLS_KEY_LENGTH_DES  = 64,
-    /** Key length in bits, including parity, for DES in two-key EDE. */
+    /** Key length in bits, including parity, for DES in two-key EDE. \warning 3DES is considered weak. */
     MBEDTLS_KEY_LENGTH_DES_EDE = 128,
-    /** Key length in bits, including parity, for DES in three-key EDE. */
+    /** Key length in bits, including parity, for DES in three-key EDE. \warning 3DES is considered weak. */
     MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
 };
 
@@ -276,8 +271,7 @@ typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
  *              mbedtls_cipher_info_from_values(),
  *              mbedtls_cipher_info_from_psa().
  */
-typedef struct mbedtls_cipher_info_t
+typedef struct mbedtls_cipher_info_t {
-{
     /** Full cipher identifier. For example,
      * MBEDTLS_CIPHER_AES_256_CBC.
      */
@@ -318,8 +312,7 @@ typedef struct mbedtls_cipher_info_t
 /**
  * Generic cipher context.
  */
-typedef struct mbedtls_cipher_context_t
+typedef struct mbedtls_cipher_context_t {
-{
     /** Information about the associated cipher. */
     const mbedtls_cipher_info_t *MBEDTLS_PRIVATE(cipher_info);
 
@@ -443,10 +436,11 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_ciph
 static inline mbedtls_cipher_type_t mbedtls_cipher_info_get_type(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( MBEDTLS_CIPHER_NONE );
+        return MBEDTLS_CIPHER_NONE;
-    else
+    } else {
-        return( info->MBEDTLS_PRIVATE(type) );
+        return info->MBEDTLS_PRIVATE(type);
+    }
 }
 
 /**
@@ -461,10 +455,11 @@ static inline mbedtls_cipher_type_t mbedtls_cipher_info_get_type(
 static inline mbedtls_cipher_mode_t mbedtls_cipher_info_get_mode(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( MBEDTLS_MODE_NONE );
+        return MBEDTLS_MODE_NONE;
-    else
+    } else {
-        return( info->MBEDTLS_PRIVATE(mode) );
+        return info->MBEDTLS_PRIVATE(mode);
+    }
 }
 
 /**
@@ -481,10 +476,11 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_info_get_mode(
 static inline size_t mbedtls_cipher_info_get_key_bitlen(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( 0 );
+        return 0;
-    else
+    } else {
-        return( info->MBEDTLS_PRIVATE(key_bitlen) );
+        return info->MBEDTLS_PRIVATE(key_bitlen);
+    }
 }
 
 /**
@@ -501,10 +497,11 @@ static inline size_t mbedtls_cipher_info_get_key_bitlen(
 static inline const char *mbedtls_cipher_info_get_name(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( NULL );
+        return NULL;
-    else
+    } else {
-        return( info->MBEDTLS_PRIVATE(name) );
+        return info->MBEDTLS_PRIVATE(name);
+    }
 }
 
 /**
@@ -520,10 +517,11 @@ static inline const char *mbedtls_cipher_info_get_name(
 static inline size_t mbedtls_cipher_info_get_iv_size(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( 0 );
+        return 0;
+    }
 
-    return( (size_t) info->MBEDTLS_PRIVATE(iv_size) );
+    return (size_t) info->MBEDTLS_PRIVATE(iv_size);
 }
 
 /**
@@ -539,10 +537,11 @@ static inline size_t mbedtls_cipher_info_get_iv_size(
 static inline size_t mbedtls_cipher_info_get_block_size(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( 0 );
+        return 0;
+    }
 
-    return( (size_t) info->MBEDTLS_PRIVATE(block_size) );
+    return (size_t) info->MBEDTLS_PRIVATE(block_size);
 }
 
 /**
@@ -557,10 +556,11 @@ static inline size_t mbedtls_cipher_info_get_block_size(
 static inline int mbedtls_cipher_info_has_variable_key_bitlen(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( 0 );
+        return 0;
+    }
 
-    return( info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_KEY_LEN );
+    return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_KEY_LEN;
 }
 
 /**
@@ -575,10 +575,11 @@ static inline int mbedtls_cipher_info_has_variable_key_bitlen(
 static inline int mbedtls_cipher_info_has_variable_iv_size(
     const mbedtls_cipher_info_t *info)
 {
-    if( info == NULL )
+    if (info == NULL) {
-        return( 0 );
+        return 0;
+    }
 
-    return( info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_IV_LEN );
+    return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_IV_LEN;
 }
 
 /**
@@ -658,7 +659,8 @@ int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx,
  *                      cipher-specific context fails.
  */
 int MBEDTLS_DEPRECATED mbedtls_cipher_setup_psa(mbedtls_cipher_context_t *ctx,
-    const mbedtls_cipher_info_t *cipher_info, size_t taglen );
+                                                const mbedtls_cipher_info_t *cipher_info,
+                                                size_t taglen);
 #endif /* MBEDTLS_DEPRECATED_REMOVED */
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
@@ -676,8 +678,9 @@ static inline unsigned int mbedtls_cipher_get_block_size(
     const mbedtls_cipher_context_t *ctx)
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return 0;
+    }
 
     return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(block_size);
 }
@@ -695,8 +698,9 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(
     const mbedtls_cipher_context_t *ctx)
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, MBEDTLS_MODE_NONE);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return MBEDTLS_MODE_NONE;
+    }
 
     return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(mode);
 }
@@ -715,11 +719,13 @@ static inline int mbedtls_cipher_get_iv_size(
     const mbedtls_cipher_context_t *ctx)
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return 0;
+    }
 
-    if( ctx->MBEDTLS_PRIVATE(iv_size) != 0 )
+    if (ctx->MBEDTLS_PRIVATE(iv_size) != 0) {
         return (int) ctx->MBEDTLS_PRIVATE(iv_size);
+    }
 
     return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(iv_size);
 }
@@ -737,8 +743,9 @@ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type(
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(
         ctx != NULL, MBEDTLS_CIPHER_NONE);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return MBEDTLS_CIPHER_NONE;
+    }
 
     return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(type);
 }
@@ -756,8 +763,9 @@ static inline const char *mbedtls_cipher_get_name(
     const mbedtls_cipher_context_t *ctx)
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return 0;
+    }
 
     return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(name);
 }
@@ -776,8 +784,9 @@ static inline int mbedtls_cipher_get_key_bitlen(
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(
         ctx != NULL, MBEDTLS_KEY_LENGTH_NONE);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return MBEDTLS_KEY_LENGTH_NONE;
+    }
 
     return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(key_bitlen);
 }
@@ -795,8 +804,9 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation(
 {
     MBEDTLS_INTERNAL_VALIDATE_RET(
         ctx != NULL, MBEDTLS_OPERATION_NONE);
-    if( ctx->MBEDTLS_PRIVATE(cipher_info) == NULL )
+    if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
         return MBEDTLS_OPERATION_NONE;
+    }
 
     return ctx->MBEDTLS_PRIVATE(operation);
 }

include/mbedtls/cmac.h

@@ -49,8 +49,7 @@ extern "C" {
 /**
  * The CMAC context structure.
  */
-struct mbedtls_cmac_context_t
+struct mbedtls_cmac_context_t {
-{
     /** The internal state of the CMAC algorithm.  */
     unsigned char       MBEDTLS_PRIVATE(state)[MBEDTLS_CIPHER_BLKSIZE_MAX];
 

include/mbedtls/config_psa.h

@@ -7,7 +7,7 @@
  *  those definitions to define symbols used in the library code.
  *
  *  Users and integrators should not edit this file, please edit
- *  include/mbedtls/mbedtls_config.h for MBETLS_XXX settings or
+ *  include/mbedtls/mbedtls_config.h for MBEDTLS_XXX settings or
  *  include/psa/crypto_config.h for PSA_WANT_XXX settings.
  */
 /*
@@ -843,6 +843,8 @@ extern "C" {
 
 /* These features are always enabled. */
 #define PSA_WANT_KEY_TYPE_DERIVE 1
+#define PSA_WANT_KEY_TYPE_PASSWORD 1
+#define PSA_WANT_KEY_TYPE_PASSWORD_HASH 1
 #define PSA_WANT_KEY_TYPE_RAW_DATA 1
 
 #ifdef __cplusplus

include/mbedtls/constant_time.h

@@ -1,6 +1,7 @@
 /**
  *  Constant-time functions
- *
+ */
+/*
  *  Copyright The Mbed TLS Contributors
  *  SPDX-License-Identifier: Apache-2.0
  *

include/mbedtls/ctr_drbg.h

@@ -167,8 +167,7 @@ extern "C" {
 /**
  * \brief          The CTR_DRBG context structure.
  */
-typedef struct mbedtls_ctr_drbg_context
+typedef struct mbedtls_ctr_drbg_context {
-{
     unsigned char MBEDTLS_PRIVATE(counter)[16];  /*!< The counter (V). */
     int MBEDTLS_PRIVATE(reseed_counter);         /*!< The reseed counter.
                                                   * This is the number of requests that have

include/mbedtls/debug.h

@@ -124,10 +124,12 @@
    #include <inttypes.h>
    #define MBEDTLS_PRINTF_SIZET     PRIuPTR
    #define MBEDTLS_PRINTF_LONGLONG  "I64d"
-#else /* (defined(__MINGW32__)  && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
+#else \
+    /* (defined(__MINGW32__)  && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
    #define MBEDTLS_PRINTF_SIZET     "zu"
    #define MBEDTLS_PRINTF_LONGLONG  "lld"
-#endif /* (defined(__MINGW32__)  && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
+#endif \
+    /* (defined(__MINGW32__)  && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
 
 #ifdef __cplusplus
 extern "C" {
@@ -275,8 +277,7 @@ void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
 #endif
 
 #if defined(MBEDTLS_ECDH_C)
-typedef enum
+typedef enum {
-{
     MBEDTLS_DEBUG_ECDH_Q,
     MBEDTLS_DEBUG_ECDH_QP,
     MBEDTLS_DEBUG_ECDH_Z,

include/mbedtls/des.h

@@ -3,7 +3,7 @@
  *
  * \brief DES block cipher
  *
- * \warning   DES is considered a weak cipher and its use constitutes a
+ * \warning   DES/3DES are considered weak ciphers and their use constitutes a
  *            security risk. We recommend considering stronger ciphers
  *            instead.
  */
@@ -53,21 +53,23 @@ extern "C" {
 /**
  * \brief          DES context structure
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
-typedef struct mbedtls_des_context
+typedef struct mbedtls_des_context {
-{
     uint32_t MBEDTLS_PRIVATE(sk)[32];            /*!<  DES subkeys       */
 }
 mbedtls_des_context;
 
 /**
  * \brief          Triple-DES context structure
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
-typedef struct mbedtls_des3_context
+typedef struct mbedtls_des3_context {
-{
     uint32_t MBEDTLS_PRIVATE(sk)[96];            /*!<  3DES subkeys      */
 }
 mbedtls_des3_context;
@@ -81,7 +83,7 @@ mbedtls_des3_context;
  *
  * \param ctx      DES context to be initialized
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -92,7 +94,7 @@ void mbedtls_des_init( mbedtls_des_context *ctx );
  *
  * \param ctx      DES context to be cleared
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -102,6 +104,10 @@ void mbedtls_des_free( mbedtls_des_context *ctx );
  * \brief          Initialize Triple-DES context
  *
  * \param ctx      DES3 context to be initialized
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des3_init(mbedtls_des3_context *ctx);
 
@@ -109,6 +115,10 @@ void mbedtls_des3_init( mbedtls_des3_context *ctx );
  * \brief          Clear Triple-DES context
  *
  * \param ctx      DES3 context to be cleared
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des3_free(mbedtls_des3_context *ctx);
 
@@ -120,7 +130,7 @@ void mbedtls_des3_free( mbedtls_des3_context *ctx );
  *
  * \param key      8-byte secret key
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -136,7 +146,7 @@ void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  *
  * \return         0 is parity was ok, 1 if parity was not correct.
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -150,7 +160,7 @@ int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SI
  *
  * \return         0 if no weak key was found, 1 if a weak key was identified.
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -165,7 +175,7 @@ int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  *
  * \return         0
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -180,7 +190,7 @@ int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MB
  *
  * \return         0
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -194,6 +204,10 @@ int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MB
  * \param key      16-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_set2key_enc(mbedtls_des3_context *ctx,
@@ -206,6 +220,10 @@ int mbedtls_des3_set2key_enc( mbedtls_des3_context *ctx,
  * \param key      16-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_set2key_dec(mbedtls_des3_context *ctx,
@@ -218,6 +236,10 @@ int mbedtls_des3_set2key_dec( mbedtls_des3_context *ctx,
  * \param key      24-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_set3key_enc(mbedtls_des3_context *ctx,
@@ -230,6 +252,10 @@ int mbedtls_des3_set3key_enc( mbedtls_des3_context *ctx,
  * \param key      24-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_set3key_dec(mbedtls_des3_context *ctx,
@@ -244,7 +270,7 @@ int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx,
  *
  * \return         0 if successful
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -272,7 +298,7 @@ int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
  * \param input    buffer holding the input data
  * \param output   buffer holding the output data
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */
@@ -293,6 +319,10 @@ int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
  * \param output   64-bit output block
  *
  * \return         0 if successful
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_crypt_ecb(mbedtls_des3_context *ctx,
@@ -319,6 +349,10 @@ int mbedtls_des3_crypt_ecb( mbedtls_des3_context *ctx,
  * \param output   buffer holding the output data
  *
  * \return         0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH
+ *
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 MBEDTLS_CHECK_RETURN_TYPICAL
 int mbedtls_des3_crypt_cbc(mbedtls_des3_context *ctx,
@@ -337,7 +371,7 @@ int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx,
  * \param SK       Round keys
  * \param key      Base key
  *
- * \warning        DES is considered a weak cipher and its use constitutes a
+ * \warning        DES/3DES are considered weak ciphers and their use constitutes a
  *                 security risk. We recommend considering stronger ciphers
  *                 instead.
  */

include/mbedtls/dhm.h

@@ -92,8 +92,7 @@
 #define MBEDTLS_ERR_DHM_SET_GROUP_FAILED                  -0x3580
 
 /** Which parameter to access in mbedtls_dhm_get_value(). */
-typedef enum
+typedef enum {
-{
     MBEDTLS_DHM_PARAM_P,  /*!<  The prime modulus. */
     MBEDTLS_DHM_PARAM_G,  /*!<  The generator. */
     MBEDTLS_DHM_PARAM_X,  /*!<  Our secret value. */
@@ -111,8 +110,7 @@ extern "C" {
 /**
  * \brief          The DHM context structure.
  */
-typedef struct mbedtls_dhm_context
+typedef struct mbedtls_dhm_context {
-{
     mbedtls_mpi MBEDTLS_PRIVATE(P);      /*!<  The prime modulus. */
     mbedtls_mpi MBEDTLS_PRIVATE(G);      /*!<  The generator. */
     mbedtls_mpi MBEDTLS_PRIVATE(X);      /*!<  Our secret value. */

include/mbedtls/ecdh.h

@@ -68,8 +68,7 @@ extern "C" {
 /**
  * Defines the source of the imported EC key.
  */
-typedef enum
+typedef enum {
-{
     MBEDTLS_ECDH_OURS,   /**< Our key. */
     MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
 } mbedtls_ecdh_side;
@@ -81,8 +80,7 @@ typedef enum
  * Later versions of the library may add new variants, therefore users should
  * not make any assumptions about them.
  */
-typedef enum
+typedef enum {
-{
     MBEDTLS_ECDH_VARIANT_NONE = 0,   /*!< Implementation not defined. */
     MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
@@ -97,8 +95,7 @@ typedef enum
  * should not make any assumptions about the structure of
  * mbedtls_ecdh_context_mbed.
  */
-typedef struct mbedtls_ecdh_context_mbed
+typedef struct mbedtls_ecdh_context_mbed {
-{
     mbedtls_ecp_group MBEDTLS_PRIVATE(grp);   /*!< The elliptic curve used. */
     mbedtls_mpi MBEDTLS_PRIVATE(d);           /*!< The private key. */
     mbedtls_ecp_point MBEDTLS_PRIVATE(Q);     /*!< The public key. */
@@ -117,8 +114,7 @@ typedef struct mbedtls_ecdh_context_mbed
  *                  should not be shared between multiple threads.
  * \brief           The ECDH context structure.
  */
-typedef struct mbedtls_ecdh_context
+typedef struct mbedtls_ecdh_context {
-{
 #if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
     mbedtls_ecp_group MBEDTLS_PRIVATE(grp);   /*!< The elliptic curve used. */
     mbedtls_mpi MBEDTLS_PRIVATE(d);           /*!< The private key. */
@@ -138,8 +134,7 @@ typedef struct mbedtls_ecdh_context
                                                     as defined in RFC 4492. */
     mbedtls_ecp_group_id MBEDTLS_PRIVATE(grp_id);/*!< The elliptic curve used. */
     mbedtls_ecdh_variant MBEDTLS_PRIVATE(var);   /*!< The ECDH implementation/structure used. */
-    union
+    union {
-    {
         mbedtls_ecdh_context_mbed   MBEDTLS_PRIVATE(mbed_ecdh);
 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
         mbedtls_ecdh_context_everest MBEDTLS_PRIVATE(everest_ecdh);

include/mbedtls/ecdsa.h

@@ -102,8 +102,7 @@ typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
 /**
  * \brief           General context for resuming ECDSA operations
  */
-typedef struct
+typedef struct {
-{
     mbedtls_ecp_restart_ctx MBEDTLS_PRIVATE(ecp);        /*!<  base context for ECP restart and
                                                             shared administrative info    */
     mbedtls_ecdsa_restart_ver_ctx *MBEDTLS_PRIVATE(ver); /*!<  ecdsa_verify() sub-context    */
@@ -245,10 +244,8 @@ int mbedtls_ecdsa_sign_det_ext( mbedtls_ecp_group *grp, mbedtls_mpi *r,
  *                  This must be initialized.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
- *                  is invalid.
  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
- *                  error code on failure for any other reason.
+ *                  error code on failure.
  */
 int mbedtls_ecdsa_verify(mbedtls_ecp_group *grp,
                          const unsigned char *buf, size_t blen,

include/mbedtls/ecjpake.h

@@ -68,8 +68,7 @@ typedef enum {
  * convention from the Thread v1.0 spec. Correspondence is indicated in the
  * description as a pair C: client name, S: server name
  */
-typedef struct mbedtls_ecjpake_context
+typedef struct mbedtls_ecjpake_context {
-{
     mbedtls_md_type_t MBEDTLS_PRIVATE(md_type);          /**< Hash to use                    */
     mbedtls_ecp_group MBEDTLS_PRIVATE(grp);              /**< Elliptic curve                 */
     mbedtls_ecjpake_role MBEDTLS_PRIVATE(role);          /**< Are we client or server?       */
@@ -113,7 +112,7 @@ void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
  * \param curve     The identifier of the elliptic curve to use,
  *                  for example #MBEDTLS_ECP_DP_SECP256R1.
  * \param secret    The pre-shared secret (passphrase). This must be
- *                  a readable buffer of length \p len Bytes. It need
+ *                  a readable not empty buffer of length \p len Bytes. It need
  *                  only be valid for the duration of this call.
  * \param len       The length of the pre-shared secret \p secret.
  *

include/mbedtls/ecp.h

@@ -110,8 +110,7 @@ extern "C" {
  * - Add the curve to applicable profiles in x509_crt.c.
  * - Add the curve to applicable presets in ssl_tls.c.
  */
-typedef enum
+typedef enum {
-{
     MBEDTLS_ECP_DP_NONE = 0,       /*!< Curve not defined. */
     MBEDTLS_ECP_DP_SECP192R1,      /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
     MBEDTLS_ECP_DP_SECP224R1,      /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
@@ -136,8 +135,7 @@ typedef enum
 /*
  * Curve types
  */
-typedef enum
+typedef enum {
-{
     MBEDTLS_ECP_TYPE_NONE = 0,
     MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS,    /* y^2 = x^3 + a x + b      */
     MBEDTLS_ECP_TYPE_MONTGOMERY,           /* y^2 = x^3 + a x^2 + x    */
@@ -150,8 +148,7 @@ typedef enum
  * accessed directly by applications. Future versions of the library may
  * add extra fields or reorder existing fields.
  */
-typedef struct mbedtls_ecp_curve_info
+typedef struct mbedtls_ecp_curve_info {
-{
     mbedtls_ecp_group_id grp_id;    /*!< An internal identifier. */
     uint16_t tls_id;                /*!< The TLS NamedCurve identifier. */
     uint16_t bit_size;              /*!< The curve size in bits. */
@@ -169,8 +166,7 @@ typedef struct mbedtls_ecp_curve_info
  *                  Otherwise, \p X and \p Y are its standard (affine)
  *                  coordinates.
  */
-typedef struct mbedtls_ecp_point
+typedef struct mbedtls_ecp_point {
-{
     mbedtls_mpi MBEDTLS_PRIVATE(X);          /*!< The X coordinate of the ECP point. */
     mbedtls_mpi MBEDTLS_PRIVATE(Y);          /*!< The Y coordinate of the ECP point. */
     mbedtls_mpi MBEDTLS_PRIVATE(Z);          /*!< The Z coordinate of the ECP point. */
@@ -224,8 +220,7 @@ mbedtls_ecp_point;
  *                of these fields does not need to be supported.
  *                They do not need to be at the same offset in the structure.
  */
-typedef struct mbedtls_ecp_group
+typedef struct mbedtls_ecp_group {
-{
     mbedtls_ecp_group_id id;    /*!< An internal group identifier. */
     mbedtls_mpi P;              /*!< The prime modulus of the base field. */
     mbedtls_mpi A;              /*!< For Short Weierstrass: \p A in the equation. For
@@ -365,8 +360,7 @@ typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
 /**
  * \brief           General context for resuming ECC operations
  */
-typedef struct
+typedef struct {
-{
     unsigned MBEDTLS_PRIVATE(ops_done);                  /*!<  current ops count             */
     unsigned MBEDTLS_PRIVATE(depth);                     /*!<  call depth (0 = top-level)    */
     mbedtls_ecp_restart_mul_ctx *MBEDTLS_PRIVATE(rsm);   /*!<  ecp_mul_comb() sub-context    */
@@ -418,8 +412,7 @@ typedef void mbedtls_ecp_restart_ctx;
  * \note    Members are deliberately in the same order as in the
  *          ::mbedtls_ecdsa_context structure.
  */
-typedef struct mbedtls_ecp_keypair
+typedef struct mbedtls_ecp_keypair {
-{
     mbedtls_ecp_group MBEDTLS_PRIVATE(grp);      /*!<  Elliptic curve and base point     */
     mbedtls_mpi MBEDTLS_PRIVATE(d);              /*!<  our secret value                  */
     mbedtls_ecp_point MBEDTLS_PRIVATE(Q);        /*!<  our public value                  */

include/mbedtls/entropy.h

@@ -104,8 +104,7 @@ typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, s
 /**
  * \brief           Entropy source state
  */
-typedef struct mbedtls_entropy_source_state
+typedef struct mbedtls_entropy_source_state {
-{
     mbedtls_entropy_f_source_ptr    MBEDTLS_PRIVATE(f_source);   /**< The entropy source callback */
     void *MBEDTLS_PRIVATE(p_source);             /**< The callback data pointer */
     size_t          MBEDTLS_PRIVATE(size);       /**< Amount received in bytes */
@@ -117,8 +116,7 @@ mbedtls_entropy_source_state;
 /**
  * \brief           Entropy context structure
  */
-typedef struct mbedtls_entropy_context
+typedef struct mbedtls_entropy_context {
-{
     int MBEDTLS_PRIVATE(accumulator_started); /* 0 after init.
                                                * 1 after the first update.
                                                * -1 after free. */

include/mbedtls/error.h

@@ -26,11 +26,6 @@
 
 #include <stddef.h>
 
-#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
-    !defined(inline) && !defined(__cplusplus)
-#define inline __inline
-#endif
-
 /**
  * Error code layout.
  *
@@ -83,6 +78,7 @@
  * POLY1305  3                  0x0057-0x005B
  * CHACHAPOLY 2 0x0054-0x0056
  * PLATFORM  2  0x0070-0x0072
+ * LMS       5  0x0011-0x0019
  *
  * High-level module nr (3 bits - 0x0...-0x7...)
  * Name      ID  Nr of Errors
@@ -96,6 +92,7 @@
  * ECP       4   10 (Started from top)
  * MD        5   5
  * HKDF      5   1 (Started from top)
+ * PKCS7     5   12 (Started from 0x5300)
  * SSL       5   2 (Started from 0x5F00)
  * CIPHER    6   8 (Started from 0x6080)
  * SSL       6   22 (Started from top, plus 0x6000)
@@ -158,13 +155,14 @@ static inline int mbedtls_error_add( int high, int low,
                                     const char *file, int line)
 {
 #if defined(MBEDTLS_TEST_HOOKS)
-    if( *mbedtls_test_hook_error_add != NULL )
+    if (*mbedtls_test_hook_error_add != NULL) {
         (*mbedtls_test_hook_error_add)(high, low, file, line);
+    }
 #endif
     (void) file;
     (void) line;
 
-    return( high + low );
+    return high + low;
 }
 
 /**

include/mbedtls/gcm.h

@@ -57,8 +57,7 @@ extern "C" {
 /**
  * \brief          The GCM context structure.
  */
-typedef struct mbedtls_gcm_context
+typedef struct mbedtls_gcm_context {
-{
     mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx);  /*!< The cipher context used. */
     uint64_t MBEDTLS_PRIVATE(HL)[16];                      /*!< Precalculated HTable low. */
     uint64_t MBEDTLS_PRIVATE(HH)[16];                      /*!< Precalculated HTable high. */

include/mbedtls/hmac_drbg.h

@@ -83,8 +83,7 @@ extern "C" {
 /**
  * HMAC_DRBG context.
  */
-typedef struct mbedtls_hmac_drbg_context
+typedef struct mbedtls_hmac_drbg_context {
-{
     /* Working state: the key K is not stored explicitly,
      * but is implied by the HMAC context */
     mbedtls_md_context_t MBEDTLS_PRIVATE(md_ctx);                    /*!< HMAC context (inc. K)  */

include/mbedtls/legacy_or_psa.h

@@ -1,7 +1,10 @@
 /**
  *  Macros to express dependencies for code and tests that may use either the
- *  legacy API or PSA in various builds; mostly for internal use.
+ *  legacy API or PSA in various builds. This whole header file is currently
- *
+ *  for internal use only and both the header file and the macros it defines
+ *  may change or be removed without notice.
+ */
+/*
  *  Copyright The Mbed TLS Contributors
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -61,7 +64,7 @@
  * The naming scheme for these macros is:
  *      MBEDTLS_HAS_feature_VIA_legacy_OR_PSA(_condition)
  * where:
- * - feature is expressed the same way as in PSA_WANT macros, for example:
+ * - feature is expressed the same way as in PSA_WANT_xxx macros, for example:
  *   KEY_TYPE_AES, ALG_SHA_256, ECC_SECP_R1_256;
  * - legacy is either LOWLEVEL or the name of the layer: MD, CIPHER;
  * - condition is omitted if it's based on availability, else it's

include/mbedtls/lms.h

@@ -0,0 +1,452 @@
+/**
+ * \file lms.h
+ *
+ * \brief This file provides an API for the LMS post-quantum-safe stateful-hash
+          public-key signature scheme as defined in RFC8554 and NIST.SP.200-208.
+ *        This implementation currently only supports a single parameter set
+ *        MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one
+ *        of the signature schemes recommended by the IETF draft SUIT standard
+ *        for IOT firmware upgrades (RFC9019).
+ */
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+#ifndef MBEDTLS_LMS_H
+#define MBEDTLS_LMS_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "mbedtls/private_access.h"
+#include "mbedtls/build_info.h"
+
+#define MBEDTLS_ERR_LMS_BAD_INPUT_DATA   -0x0011 /**< Bad data has been input to an LMS function */
+#define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013 /**< Specified LMS key has utilised all of its private keys */
+#define MBEDTLS_ERR_LMS_VERIFY_FAILED    -0x0015 /**< LMS signature verification failed */
+#define MBEDTLS_ERR_LMS_ALLOC_FAILED     -0x0017 /**< LMS failed to allocate space for a private key */
+#define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019 /**< Input/output buffer is too small to contain requited data */
+
+/* Currently only defined for SHA256, 32 is the max hash output size */
+#define MBEDTLS_LMOTS_N_HASH_LEN_MAX           (32u)
+#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX    (34u)
+#define MBEDTLS_LMOTS_N_HASH_LEN(type)         ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)
+#define MBEDTLS_LMOTS_I_KEY_ID_LEN             (16u)
+#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN            (4u)
+#define MBEDTLS_LMOTS_TYPE_LEN                 (4u)
+#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type)  ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)
+#define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) (MBEDTLS_LMOTS_N_HASH_LEN(type))
+
+#define MBEDTLS_LMOTS_SIG_LEN(type) (MBEDTLS_LMOTS_TYPE_LEN + \
+                                     MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
+                                     (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
+                                      MBEDTLS_LMOTS_N_HASH_LEN(type)))
+
+
+#define MBEDTLS_LMS_TYPE_LEN            (4)
+#define MBEDTLS_LMS_H_TREE_HEIGHT(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)
+
+/* The length of a hash output, Currently only implemented for SHA256.
+ * Max is 32 bytes.
+ */
+#define MBEDTLS_LMS_M_NODE_BYTES(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)
+#define MBEDTLS_LMS_M_NODE_BYTES_MAX 32
+
+#define MBEDTLS_LMS_SIG_LEN(type, otstype) (MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
+                                            MBEDTLS_LMOTS_SIG_LEN(otstype) + \
+                                            MBEDTLS_LMS_TYPE_LEN + \
+                                            (MBEDTLS_LMS_H_TREE_HEIGHT(type) * \
+                                             MBEDTLS_LMS_M_NODE_BYTES(type)))
+
+#define MBEDTLS_LMS_PUBLIC_KEY_LEN(type) (MBEDTLS_LMS_TYPE_LEN + \
+                                          MBEDTLS_LMOTS_TYPE_LEN + \
+                                          MBEDTLS_LMOTS_I_KEY_ID_LEN + \
+                                          MBEDTLS_LMS_M_NODE_BYTES(type))
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** The Identifier of the LMS parameter set, as per
+ * https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml
+ * We are only implementing a subset of the types, particularly H10, for the sake of simplicity.
+ */
+typedef enum {
+    MBEDTLS_LMS_SHA256_M32_H10 = 0x6,
+} mbedtls_lms_algorithm_type_t;
+
+/** The Identifier of the LMOTS parameter set, as per
+ *  https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml.
+ *  We are only implementing a subset of the types, particularly N32_W8, for the sake of simplicity.
+ */
+typedef enum {
+    MBEDTLS_LMOTS_SHA256_N32_W8 = 4
+} mbedtls_lmots_algorithm_type_t;
+
+/** LMOTS parameters structure.
+ *
+ * This contains the metadata associated with an LMOTS key, detailing the
+ * algorithm type, the key ID, and the leaf identifier should be key be part of
+ * a LMS key.
+ */
+typedef struct {
+    unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
+                                                                                    identifier. */
+    unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]); /*!< Which
+                                                                                      leaf of the LMS key this is.
+                                                                                      0 if the key is not part of an LMS key. */
+    mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LM-OTS key type identifier as
+                                                               per IANA. Only SHA256_N32_W8 is
+                                                               currently supported. */
+} mbedtls_lmots_parameters_t;
+
+/** LMOTS public context structure.
+ *
+ * A LMOTS public key is a hash output, and the applicable parameter set.
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported or generated from a private context.
+ *
+ * \dot
+ * digraph lmots_public_t {
+ *   UNINITIALIZED -> INIT [label="init"];
+ *   HAVE_PUBLIC_KEY -> INIT [label="free"];
+ *   INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
+ *   INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
+ *   HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
+ * }
+ * \enddot
+ */
+typedef struct {
+    mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
+    unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
+    unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
+                                                       Boolean values only. */
+} mbedtls_lmots_public_t;
+
+#if defined(MBEDTLS_LMS_PRIVATE)
+/** LMOTS private context structure.
+ *
+ * A LMOTS private key is one hash output for each of digit of the digest +
+ * checksum, and the applicable parameter set.
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported or generated from a private context.
+ *
+ * \dot
+ * digraph lmots_public_t {
+ *   UNINITIALIZED -> INIT [label="init"];
+ *   HAVE_PRIVATE_KEY -> INIT [label="free"];
+ *   INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
+ *   HAVE_PRIVATE_KEY -> INIT [label="sign"];
+ * }
+ * \enddot
+ */
+typedef struct {
+    mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
+    unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
+        MBEDTLS_LMOTS_N_HASH_LEN_MAX];
+    unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
+                                                        Boolean values only. */
+} mbedtls_lmots_private_t;
+#endif /* defined(MBEDTLS_LMS_PRIVATE) */
+
+
+/** LMS parameters structure.
+ *
+ * This contains the metadata associated with an LMS key, detailing the
+ * algorithm type, the type of the underlying OTS algorithm, and the key ID.
+ */
+typedef struct {
+    unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
+                                                                                    identifier. */
+    mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(otstype); /*!< The LM-OTS key type identifier as
+                                                                per IANA. Only SHA256_N32_W8 is
+                                                                currently supported. */
+    mbedtls_lms_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LMS key type identifier as per
+                                                             IANA. Only SHA256_M32_H10 is currently
+                                                             supported. */
+} mbedtls_lms_parameters_t;
+
+/** LMS public context structure.
+ *
+ * A LMS public key is the hash output that is the root of the Merkle tree, and
+ * the applicable parameter set
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported or generated from a private context.
+ *
+ * \dot
+ * digraph lms_public_t {
+ *   UNINITIALIZED -> INIT [label="init"];
+ *   HAVE_PUBLIC_KEY -> INIT [label="free"];
+ *   INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
+ *   INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
+ *   HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
+ * }
+ * \enddot
+ */
+typedef struct {
+    mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
+    unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX]; /*!< The public key, in
+                                                                                 the form of the Merkle tree root node. */
+    unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
+                                                       Boolean values only. */
+} mbedtls_lms_public_t;
+
+
+#if defined(MBEDTLS_LMS_PRIVATE)
+/** LMS private context structure.
+ *
+ * A LMS private key is a set of LMOTS private keys, an index to the next usable
+ * key, and the applicable parameter set.
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported or generated from a private context.
+ *
+ * \dot
+ * digraph lms_public_t {
+ *   UNINITIALIZED -> INIT [label="init"];
+ *   HAVE_PRIVATE_KEY -> INIT [label="free"];
+ *   INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
+ * }
+ * \enddot
+ */
+typedef struct {
+    mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
+    uint32_t MBEDTLS_PRIVATE(q_next_usable_key); /*!< The index of the next OTS key that has not
+                                                      been used. */
+    mbedtls_lmots_private_t *MBEDTLS_PRIVATE(ots_private_keys); /*!< The private key material. One OTS key
+                                                                   for each leaf node in the Merkle tree. NULL
+                                                                   when have_private_key is 0 and non-NULL otherwise.
+                                                                   is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type) in length. */
+    mbedtls_lmots_public_t *MBEDTLS_PRIVATE(ots_public_keys); /*!< The OTS key public keys, used to
+                                                                   build the Merkle tree. NULL
+                                                                   when have_private_key is 0 and
+                                                                   non-NULL otherwise.
+                                                                   Is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type)
+                                                                   in length. */
+    unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
+                                                        Boolean values only. */
+} mbedtls_lms_private_t;
+#endif /* defined(MBEDTLS_LMS_PRIVATE) */
+
+/**
+ * \brief                    This function initializes an LMS public context
+ *
+ * \param ctx                The uninitialized LMS context that will then be
+ *                           initialized.
+ */
+void mbedtls_lms_public_init(mbedtls_lms_public_t *ctx);
+
+/**
+ * \brief                    This function uninitializes an LMS public context
+ *
+ * \param ctx                The initialized LMS context that will then be
+ *                           uninitialized.
+ */
+void mbedtls_lms_public_free(mbedtls_lms_public_t *ctx);
+
+/**
+ * \brief                    This function imports an LMS public key into a
+ *                           public LMS context.
+ *
+ * \note                     Before this function is called, the context must
+ *                           have been initialized.
+ *
+ * \note                     See IETF RFC8554 for details of the encoding of
+ *                           this public key.
+ *
+ * \param ctx                The initialized LMS context store the key in.
+ * \param key                The buffer from which the key will be read.
+ *                           #MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from
+ *                           this.
+ * \param key_size           The size of the key being imported.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_import_public_key(mbedtls_lms_public_t *ctx,
+                                  const unsigned char *key, size_t key_size);
+
+/**
+ * \brief                    This function exports an LMS public key from a
+ *                           LMS public context that already contains a public
+ *                           key.
+ *
+ * \note                     Before this function is called, the context must
+ *                           have been initialized and the context must contain
+ *                           a public key.
+ *
+ * \note                     See IETF RFC8554 for details of the encoding of
+ *                           this public key.
+ *
+ * \param ctx                The initialized LMS public context that contains
+ *                           the public key.
+ * \param key                The buffer into which the key will be output. Must
+ *                           be at least #MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
+ * \param key_size           The size of the key buffer.
+ * \param key_len            If not NULL, will be written with the size of the
+ *                           key.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_export_public_key(const mbedtls_lms_public_t *ctx,
+                                  unsigned char *key, size_t key_size,
+                                  size_t *key_len);
+
+/**
+ * \brief                    This function verifies a LMS signature, using a
+ *                           LMS context that contains a public key.
+ *
+ * \note                     Before this function is called, the context must
+ *                           have been initialized and must contain a public key
+ *                           (either by import or generation).
+ *
+ * \param ctx                The initialized LMS public context from which the
+ *                           public key will be read.
+ * \param msg                The buffer from which the message will be read.
+ * \param msg_size           The size of the message that will be read.
+ * \param sig                The buf from which the signature will be read.
+ *                           #MBEDTLS_LMS_SIG_LEN bytes will be read from
+ *                           this.
+ * \param sig_size           The size of the signature to be verified.
+ *
+ * \return         \c 0 on successful verification.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_verify(const mbedtls_lms_public_t *ctx,
+                       const unsigned char *msg, size_t msg_size,
+                       const unsigned char *sig, size_t sig_size);
+
+#if defined(MBEDTLS_LMS_PRIVATE)
+/**
+ * \brief                    This function initializes an LMS private context
+ *
+ * \param ctx                The uninitialized LMS private context that will
+ *                           then be initialized. */
+void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx);
+
+/**
+ * \brief                    This function uninitializes an LMS private context
+ *
+ * \param ctx                The initialized LMS private context that will then
+ *                           be uninitialized.
+ */
+void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);
+
+/**
+ * \brief                    This function generates an LMS private key, and
+ *                           stores in into an LMS private context.
+ *
+ * \warning                  This function is **not intended for use in
+ *                           production**, due to as-yet unsolved problems with
+ *                           handling stateful keys. The API for this function
+ *                           may change considerably in future versions.
+ *
+ * \note                     The seed must have at least 256 bits of entropy.
+ *
+ * \param ctx                The initialized LMOTS context to generate the key
+ *                           into.
+ * \param type               The LMS parameter set identifier.
+ * \param otstype            The LMOTS parameter set identifier.
+ * \param f_rng              The RNG function to be used to generate the key ID.
+ * \param p_rng              The RNG context to be passed to f_rng
+ * \param seed               The seed used to deterministically generate the
+ *                           key.
+ * \param seed_size          The length of the seed.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
+                                     mbedtls_lms_algorithm_type_t type,
+                                     mbedtls_lmots_algorithm_type_t otstype,
+                                     int (*f_rng)(void *, unsigned char *, size_t),
+                                     void *p_rng, const unsigned char *seed,
+                                     size_t seed_size);
+
+/**
+ * \brief                    This function calculates an LMS public key from a
+ *                           LMS context that already contains a private key.
+ *
+ * \note                     Before this function is called, the context must
+ *                           have been initialized and the context must contain
+ *                           a private key.
+ *
+ * \param ctx                The initialized LMS public context to calculate the key
+ *                           from and store it into.
+ *
+ * \param priv_ctx           The LMS private context to read the private key
+ *                           from. This must have been initialized and contain a
+ *                           private key.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
+                                     const mbedtls_lms_private_t *priv_ctx);
+
+/**
+ * \brief                    This function creates a LMS signature, using a
+ *                           LMS context that contains unused private keys.
+ *
+ * \warning                  This function is **not intended for use in
+ *                           production**, due to as-yet unsolved problems with
+ *                           handling stateful keys. The API for this function
+ *                           may change considerably in future versions.
+ *
+ * \note                     Before this function is called, the context must
+ *                           have been initialized and must contain a private
+ *                           key.
+ *
+ * \note                     Each of the LMOTS private keys inside a LMS private
+ *                           key can only be used once. If they are reused, then
+ *                           attackers may be able to forge signatures with that
+ *                           key. This is all handled transparently, but it is
+ *                           important to not perform copy operations on LMS
+ *                           contexts that contain private key material.
+ *
+ * \param ctx                The initialized LMS private context from which the
+ *                           private key will be read.
+ * \param f_rng              The RNG function to be used for signature
+ *                           generation.
+ * \param p_rng              The RNG context to be passed to f_rng
+ * \param msg                The buffer from which the message will be read.
+ * \param msg_size           The size of the message that will be read.
+ * \param sig                The buf into which the signature will be stored.
+ *                           Must be at least #MBEDTLS_LMS_SIG_LEN in size.
+ * \param sig_size           The size of the buffer the signature will be
+ *                           written into.
+ * \param sig_len            If not NULL, will be written with the size of the
+ *                           signature.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
+ */
+int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
+                     int (*f_rng)(void *, unsigned char *, size_t),
+                     void *p_rng, const unsigned char *msg,
+                     unsigned int msg_size, unsigned char *sig, size_t sig_size,
+                     size_t *sig_len);
+#endif /* defined(MBEDTLS_LMS_PRIVATE) */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MBEDTLS_LMS_H */

include/mbedtls/mbedtls_config.h

@@ -48,8 +48,11 @@
  * Requires support for asm() in compiler.
  *
  * Used in:
+ *      library/aesni.h
  *      library/aria.c
  *      library/bn_mul.h
+ *      library/constant_time.c
+ *      library/padlock.h
  *
  * Required by:
  *      MBEDTLS_AESNI_C
@@ -690,11 +693,42 @@
  * This is useful in non-threaded environments if you want to avoid blocking
  * for too long on ECC (and, hence, X.509 or SSL/TLS) operations.
  *
- * Uncomment this macro to enable restartable ECC computations.
+ * This option:
+ * - Adds xxx_restartable() variants of existing operations in the
+ *   following modules, with corresponding restart context types:
+ *   - ECP (for Short Weierstrass curves only): scalar multiplication (mul),
+ *     linear combination (muladd);
+ *   - ECDSA: signature generation & verification;
+ *   - PK: signature generation & verification;
+ *   - X509: certificate chain verification.
+ * - Adds mbedtls_ecdh_enable_restart() in the ECDH module.
+ * - Changes the behaviour of TLS 1.2 clients (not servers) when using the
+ *   ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC
+ *   computations restartable:
+ *   - ECDH operations from the key exchange, only for Short Weierstass
+ *     curves, only when MBEDTLS_USE_PSA_CRYPTO is not enabled.
+ *   - verification of the server's key exchange signature;
+ *   - verification of the server's certificate chain;
+ *   - generation of the client's signature if client authentication is used,
+ *     with an ECC key/certificate.
+ *
+ * \note  In the cases above, the usual SSL/TLS functions, such as
+ *        mbedtls_ssl_handshake(), can now return
+ *        MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS.
+ *
+ * \note  When this option and MBEDTLS_USE_PSA_CRYPTO are both enabled,
+ *        restartable operations in PK, X.509 and TLS (see above) are not
+ *        using PSA. On the other hand, ECDH computations in TLS are using
+ *        PSA, and are not restartable. These are temporary limitations that
+ *        should be lifted in the future.
  *
  * \note  This option only works with the default software implementation of
  *        elliptic curve functionality. It is incompatible with
  *        MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT.
+ *
+ * Requires: MBEDTLS_ECP_C
+ *
+ * Uncomment this macro to enable restartable ECC computations.
  */
 //#define MBEDTLS_ECP_RESTARTABLE
 
@@ -1130,7 +1164,7 @@
  *
  * Enable support for PKCS#1 v1.5 encoding.
  *
- * Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C
+ * Requires: MBEDTLS_RSA_C
  *
  * This enables support for PKCS#1 v1.5 operations.
  */
@@ -1146,6 +1180,11 @@
  * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
  * before doing any PKCS#1 v2.1 operation.
  *
+ * \warning When building with MBEDTLS_MD_C, all hashes used with this
+ * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
+ * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
+ * this module in builds where MBEDTLS_MD_C is disabled.
+ *
  * This enables support for RSAES-OAEP and RSASSA-PSS operations.
  */
 #define MBEDTLS_PKCS1_V21
@@ -1320,21 +1359,16 @@
 /**
  * \def MBEDTLS_SSL_DTLS_CONNECTION_ID
  *
- * Enable support for the DTLS Connection ID extension
+ * Enable support for the DTLS Connection ID (CID) extension,
- * (version draft-ietf-tls-dtls-connection-id-05,
- * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05)
  * which allows to identify DTLS connections across changes
- * in the underlying transport.
+ * in the underlying transport. The CID functionality is described
+ * in RFC 9146.
  *
  * Setting this option enables the SSL APIs `mbedtls_ssl_set_cid()`,
  * mbedtls_ssl_get_own_cid()`, `mbedtls_ssl_get_peer_cid()` and
  * `mbedtls_ssl_conf_cid()`. See the corresponding documentation for
  * more information.
  *
- * \warning The Connection ID extension is still in draft state.
- *          We make no stability promises for the availability
- *          or the shape of the API controlled by this option.
- *
  * The maximum lengths of outgoing and incoming CIDs can be configured
  * through the options
  * - MBEDTLS_SSL_CID_OUT_LEN_MAX
@@ -1344,7 +1378,30 @@
  *
  * Uncomment to enable the Connection ID extension.
  */
-//#define MBEDTLS_SSL_DTLS_CONNECTION_ID
+#define MBEDTLS_SSL_DTLS_CONNECTION_ID
+
+
+/**
+ * \def MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT
+ *
+ * Defines whether RFC 9146 (default) or the legacy version
+ * (version draft-ietf-tls-dtls-connection-id-05,
+ * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05)
+ * is used.
+ *
+ * Set the value to 0 for the standard version, and
+ * 1 for the legacy draft version.
+ *
+ * \deprecated Support for the legacy version of the DTLS
+ *             Connection ID feature is deprecated. Please
+ *             switch to the standardized version defined
+ *             in RFC 9146 enabled by utilizing
+ *             MBEDTLS_SSL_DTLS_CONNECTION_ID without use
+ *             of MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT.
+ *
+ * Requires: MBEDTLS_SSL_DTLS_CONNECTION_ID
+ */
+#define MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT 0
 
 /**
  * \def MBEDTLS_SSL_ASYNC_PRIVATE
@@ -1354,6 +1411,7 @@
  * module to perform private key operations instead of performing the
  * operation inside the library.
  *
+ * Requires: MBEDTLS_X509_CRT_PARSE_C
  */
 //#define MBEDTLS_SSL_ASYNC_PRIVATE
 
@@ -1520,7 +1578,7 @@
  * Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
  * Requires: MBEDTLS_PSA_CRYPTO_C
  *
- * Note: even though TLS 1.3 depends on PSA Crypto, and uses it unconditonally
+ * Note: even though TLS 1.3 depends on PSA Crypto, and uses it unconditionally
  * for most operations, if you want it to only use PSA for all crypto
  * operations, you need to also enable MBEDTLS_USE_PSA_CRYPTO; otherwise X.509
  * operations, and functions that are common with TLS 1.2 (record protection,
@@ -1552,6 +1610,47 @@
  */
 //#define MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE
 
+/**
+ * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED
+ *
+ * Enable TLS 1.3 PSK key exchange mode.
+ *
+ * Comment to disable support for the PSK key exchange mode in TLS 1.3. If
+ * MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any
+ * effect on the build.
+ *
+ */
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED
+
+/**
+ * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED
+ *
+ * Enable TLS 1.3 ephemeral key exchange mode.
+ *
+ * Requires: MBEDTLS_ECDH_C, MBEDTLS_X509_CRT_PARSE_C, MBEDTLS_ECDSA_C or
+ *           MBEDTLS_PKCS1_V21
+ *
+ * Comment to disable support for the ephemeral key exchange mode in TLS 1.3.
+ * If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any
+ * effect on the build.
+ *
+ */
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED
+
+/**
+ * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED
+ *
+ * Enable TLS 1.3 PSK ephemeral key exchange mode.
+ *
+ * Requires: MBEDTLS_ECDH_C
+ *
+ * Comment to disable support for the PSK ephemeral key exchange mode in
+ * TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not
+ * have any effect on the build.
+ *
+ */
+#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED
+
 /**
  * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE
  *
@@ -1591,6 +1690,41 @@
  */
 #define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1
 
+/**
+ * \def MBEDTLS_SSL_EARLY_DATA
+ *
+ * Enable support for RFC 8446 TLS 1.3 early data.
+ *
+ * Requires: MBEDTLS_SSL_SESSION_TICKETS and either
+ *           MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED or
+ *           MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED
+ *
+ * Comment this to disable support for early data. If MBEDTLS_SSL_PROTO_TLS1_3
+ * is not enabled, this option does not have any effect on the build.
+ *
+ * This feature is experimental, not completed and thus not ready for
+ * production.
+ *
+ */
+//#define MBEDTLS_SSL_EARLY_DATA
+
+/**
+ * \def MBEDTLS_SSL_MAX_EARLY_DATA_SIZE
+ *
+ * The default maximum amount of 0-RTT data. See the documentation of
+ * \c mbedtls_ssl_tls13_conf_max_early_data_size() for more information.
+ *
+ * It must be positive and smaller than UINT32_MAX.
+ *
+ * If MBEDTLS_SSL_EARLY_DATA is not defined, this default value does not
+ * have any impact on the build.
+ *
+ * This feature is experimental, not completed and thus not ready for
+ * production.
+ *
+ */
+#define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE        1024
+
 /**
  * \def MBEDTLS_SSL_PROTO_DTLS
  *
@@ -1824,7 +1958,6 @@
  * before calling any function from the SSL/TLS, X.509 or PK modules.
  *
  * Requires: MBEDTLS_PSA_CRYPTO_C.
- * Conflicts with: MBEDTLS_ECP_RESTARTABLE
  *
  * Uncomment this to enable internal use of PSA Crypto and new associated APIs.
  */
@@ -1883,6 +2016,8 @@
  * See the documentation of `mbedtls_x509_crt_verify_with_ca_cb()` and
  * `mbedtls_ssl_conf_ca_cb()` for more information.
  *
+ * Requires: MBEDTLS_X509_CRT_PARSE_C
+ *
  * Uncomment to enable trusted certificate callbacks.
  */
 //#define MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK
@@ -2293,7 +2428,7 @@
  *
  * PEM_PARSE uses DES/3DES for decrypting encrypted keys.
  *
- * \warning   DES is considered a weak cipher and its use constitutes a
+ * \warning   DES/3DES are considered weak ciphers and their use constitutes a
  *            security risk. We recommend considering stronger ciphers instead.
  */
 #define MBEDTLS_DES_C
@@ -2374,6 +2509,11 @@
  *
  * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
  * before doing any EC J-PAKE operations.
+ *
+ * \warning When building with MBEDTLS_MD_C, all hashes used with this
+ * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
+ * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
+ * this module in builds where MBEDTLS_MD_C is disabled.
  */
 #define MBEDTLS_ECJPAKE_C
 
@@ -2461,6 +2601,32 @@
  */
 #define MBEDTLS_HMAC_DRBG_C
 
+/**
+ * \def MBEDTLS_LMS_C
+ *
+ * Enable the LMS stateful-hash asymmetric signature algorithm.
+ *
+ * Module:  library/lms.c
+ * Caller:
+ *
+ * Requires: MBEDTLS_PSA_CRYPTO_C
+ *
+ * Uncomment to enable the LMS verification algorithm and public key operations.
+ */
+#define MBEDTLS_LMS_C
+
+/**
+ * \def MBEDTLS_LMS_PRIVATE
+ *
+ * Enable LMS private-key operations and signing code. Functions enabled by this
+ * option are experimental, and should not be used in production.
+ *
+ * Requires: MBEDTLS_LMS_C
+ *
+ * Uncomment to enable the LMS signature algorithm and private key operations.
+ */
+//#define MBEDTLS_LMS_PRIVATE
+
 /**
  * \def MBEDTLS_NIST_KW_C
  *
@@ -2554,7 +2720,7 @@
  *
  * \note See also our Knowledge Base article about porting to a new
  * environment:
- * https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS
+ * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS
  *
  * Module:  library/net_sockets.c
  *
@@ -2692,10 +2858,35 @@
  * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
  * before doing any PKCS5 operation.
  *
+ * \warning When building with MBEDTLS_MD_C, all hashes used with this
+ * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
+ * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
+ * this module in builds where MBEDTLS_MD_C is disabled.
+ *
  * This module adds support for the PKCS#5 functions.
  */
 #define MBEDTLS_PKCS5_C
 
+/**
+ * \def MBEDTLS_PKCS7_C
+ *
+ * This feature is a work in progress and not ready for production. Testing and
+ * validation is incomplete, and handling of malformed inputs may not be robust.
+ * The API may change.
+ *
+ * Enable PKCS7 core for using PKCS7 formatted signatures.
+ * RFC Link - https://tools.ietf.org/html/rfc2315
+ *
+ * Module:  library/pkcs7.c
+ *
+ * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C,
+ *           MBEDTLS_X509_CRT_PARSE_C MBEDTLS_X509_CRL_PARSE_C,
+ *           MBEDTLS_BIGNUM_C, MBEDTLS_MD_C
+ *
+ * This module is required for the PKCS7 parsing modules.
+ */
+//#define MBEDTLS_PKCS7_C
+
 /**
  * \def MBEDTLS_PKCS12_C
  *
@@ -2711,6 +2902,11 @@
  * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
  * before doing any PKCS12 operation.
  *
+ * \warning When building with MBEDTLS_MD_C, all hashes used with this
+ * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
+ * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
+ * this module in builds where MBEDTLS_MD_C is disabled.
+ *
  * This module enables PKCS#12 functions.
  */
 #define MBEDTLS_PKCS12_C
@@ -2856,9 +3052,6 @@
  *
  * Enable the SHA-224 cryptographic hash algorithm.
  *
- * Requires: MBEDTLS_SHA256_C. The library does not currently support enabling
- *           SHA-224 without SHA-256.
- *
  * Module:  library/sha256.c
  * Caller:  library/md.c
  *          library/ssl_cookie.c
@@ -2872,9 +3065,6 @@
  *
  * Enable the SHA-256 cryptographic hash algorithm.
  *
- * Requires: MBEDTLS_SHA224_C. The library does not currently support enabling
- *           SHA-256 without SHA-224.
- *
  * Module:  library/sha256.c
  * Caller:  library/entropy.c
  *          library/md.c
@@ -2942,8 +3132,6 @@
  *
  * Enable the SHA-384 cryptographic hash algorithm.
  *
- * Requires: MBEDTLS_SHA512_C
- *
  * Module:  library/sha512.c
  * Caller:  library/md.c
  *          library/psa_crypto_hash.c
@@ -3122,7 +3310,7 @@
  * contexts are not shared between threads. If you do intend to use contexts
  * between threads, you will need to enable this layer to prevent race
  * conditions. See also our Knowledge Base article about threading:
- * https://tls.mbed.org/kb/development/thread-safety-and-multi-threading
+ * https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading
  *
  * Module:  library/threading.c
  *
@@ -3154,7 +3342,7 @@
  *
  * \note See also our Knowledge Base article about porting to a new
  * environment:
- * https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS
+ * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS
  *
  * Module:  library/timing.c
  */
@@ -3587,17 +3775,6 @@
 //#define MBEDTLS_PSK_MAX_LEN               32 /**< Max size of TLS pre-shared keys, in bytes (default 256 bits) */
 //#define MBEDTLS_SSL_COOKIE_TIMEOUT        60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */
 
-/** \def MBEDTLS_TLS_EXT_CID
- *
- * At the time of writing, the CID extension has not been assigned its
- * final value. Set this configuration option to make Mbed TLS use a
- * different value.
- *
- * A future minor revision of Mbed TLS may change the default value of
- * this option to match evolving standards and usage.
- */
-//#define MBEDTLS_TLS_EXT_CID                        254
-
 /**
  * Complete list of ciphersuites to use, in order of preference.
  *