Merge remote-tracking branch 'mbedtls4.0.0-documentation' into mbedtls-4.0.0.rc

Signed-off-by: Minos Galanakis <[email protected]>

Author: minosgalanakis

BRANCHES.md

@@ -6,9 +6,8 @@ At any point in time, we have a number of maintained branches, currently consist
   this always contains the latest release, including all publicly available
   security fixes.
 - The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch:
-  this is where the next major version of Mbed TLS (version 4.0) is being
-  prepared. It has API changes that make it incompatible with Mbed TLS 3.x,
-  as well as all the new features and bug fixes and security fixes.
+  this is where the next minor version of Mbed TLS 4.x is prepared. It contains
+  new features, bug fixes, and security fixes.
 - One or more long-time support (LTS) branches: these only get bug fixes and
   security fixes. Currently, the supported LTS branches are:
 - [`mbedtls-3.6`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-3.6).
@@ -19,7 +18,7 @@ These branches will not receive any changes or updates.
 
 We use [Semantic Versioning](https://semver.org/). In particular, we maintain
 API compatibility in the `main` branch across minor version changes (e.g.
-the API of 3.(x+1) is backward compatible with 3.x). We only break API
+the API of 4.(x+1) is backward compatible with 4.x). We only break API
 compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain
 ABI compatibility within LTS branches; see the next section for details.
 
@@ -66,25 +65,6 @@ crypto that was found to be weak) may need to be changed. In case security
 comes in conflict with backwards compatibility, we will put security first,
 but always attempt to provide a compatibility option.
 
-## Backward compatibility for the key store
-
-We maintain backward compatibility with previous versions of the
-PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the
-storage backend (PSA ITS implementation) is configured in a compatible way.
-We intend to maintain this backward compatibility throughout a major version
-of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read
-keys written under any Mbed TLS 3.x with x <= y).
-
-Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x
-LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y)
-may require the use of an upgrade tool.
-
-Note that this guarantee does not currently fully extend to drivers, which
-are an experimental feature. We intend to maintain compatibility with the
-basic use of drivers from Mbed TLS 2.28.0 onwards, even if driver APIs
-change. However, for more experimental parts of the driver interface, such
-as the use of driver state, we do not yet guarantee backward compatibility.
-
 ## Long-time support branches
 
 For the LTS branches, additionally we try very hard to also maintain ABI

README.md

@@ -37,10 +37,6 @@ being implemented. (For example Mbed TLS alone won't guarantee that the
 messages will arrive without delay, as the TLS protocol doesn't guarantee that
 either.)
 
-**Warning!** Block ciphers do not yet achieve full protection against attackers
-who can measure the timing of packets with sufficient precision. For details
-and workarounds see the [Block Ciphers](#block-ciphers) section.
-
 ### Local attacks
 
 In this section, we consider an attacker who can run software on the same
@@ -69,9 +65,6 @@ physical side channels as well. Remote and physical timing attacks are covered
 in the [Remote attacks](remote-attacks) and [Physical
 attacks](physical-attacks) sections respectively.
 
-**Warning!** Block ciphers do not yet achieve full protection. For
-details and workarounds see the [Block Ciphers](#block-ciphers) section.
-
 #### Local non-timing side channels
 
 The attacker code running on the platform has access to some sensor capable of
@@ -115,36 +108,6 @@ protection against a class of attacks outside of the above described threat
 model. Neither does it mean that the failure of such a countermeasure is
 considered a vulnerability.
 
-#### Block ciphers
-
-Currently there are four block ciphers in Mbed TLS: AES, CAMELLIA, ARIA and
-DES. The pure software implementation in Mbed TLS implementation uses lookup
-tables, which are vulnerable to timing attacks.
-
-These timing attacks can be physical, local or depending on network latency
-even a remote. The attacks can result in key recovery.
-
-**Workarounds:**
-
-- Turn on hardware acceleration for AES. This is supported only on selected
-  architectures and currently only available for AES. See configuration options
-  `MBEDTLS_AESCE_C`, `MBEDTLS_AESNI_C` for details.
-- Add a secure alternative implementation (typically hardware acceleration) for
-  the vulnerable cipher. See the [Alternative Implementations
-Guide](docs/architecture/alternative-implementations.md) for more information.
-- Use cryptographic mechanisms that are not based on block ciphers. In
-  particular, for authenticated encryption, use ChaCha20/Poly1305 instead of
-  block cipher modes. For random generation, use HMAC\_DRBG instead of CTR\_DRBG.
-
-#### Everest
-
-The HACL* implementation of X25519 taken from the Everest project only protects
-against remote timing attacks. (See their [Security
-Policy](https://github.com/hacl-star/hacl-star/blob/main/SECURITY.md).)
-
-The Everest variant is only used when `MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED`
-configuration option is defined. This option is off by default.
-
 #### Formatting of X.509 certificates and certificate signing requests
 
 When parsing X.509 certificates and certificate signing requests (CSRs),

SECURITY.md

@@ -1,24 +1,28 @@
 This directory contains example configuration files.
 
-The examples are generally focused on a particular usage case (eg, support for
-a restricted number of ciphersuites) and aim at minimizing resource usage for
-this target. They can be used as a basis for custom configurations.
+The examples are generally focused on a particular use case (eg, support for
+a restricted set of ciphersuites) and aim to minimize resource usage for
+the target. They can be used as a basis for custom configurations.
 
-These files are complete replacements for the default mbedtls_config.h. To use one of
-them, you can pick one of the following methods:
+These files come in pairs and are complete replacements for the default
+mbedtls_config.h and crypto_config.h. The two files of a pair share the same or
+very similar name, with the crypto file prefixed by "crypto-". Note
+that some of the cryptography configuration files may be located in
+tf-psa-crypto/configs.
 
-1. Replace the default file include/mbedtls/mbedtls_config.h with the chosen one.
+To use one of these pairs, you can pick one of the following methods:
 
-2. Define MBEDTLS_CONFIG_FILE and adjust the include path accordingly.
-   For example, using make:
+1. Replace the default files include/mbedtls/mbedtls_config.h and
+   tf-psa-crypto/include/psa/crypto_config.h with the chosen ones.
 
-    CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" make
+2. Use the MBEDTLS_CONFIG_FILE and TF_PSA_CRYPTO_CONFIG_FILE CMake options. For
+   example, to build out-of-tree with the config-ccm-psk-tls1_2.h and
+   crypto-config-ccm-psk-tls1_2.h configuration pair:
 
-   Or, using cmake:
+   cmake -DMBEDTLS_CONFIG_FILE="configs/config-ccm-psk-tls1_2.h" \
+         -DTF_PSA_CRYPTO_CONFIG_FILE="configs/crypto-config-ccm-psk-tls1_2.h"
+         -B build-psktls12 .
+   cmake --build build-psktls12
 
-    find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
-    CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" cmake .
-    make
-
-Note that the second method also works if you want to keep your custom
-configuration file outside the Mbed TLS tree.
+The second method also works if you want to keep your custom configuration
+files outside the Mbed TLS tree.