Merge branch 'mbedtls-2.28-restricted' into mbedtls-2.28.8rc0-pr
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/BRANCHES.md b/BRANCHES.md
index 28a2c6a..bcceda8 100644
--- a/BRANCHES.md
+++ b/BRANCHES.md
@@ -1,25 +1,33 @@
# Maintained branches
-At any point in time, we have a number of maintained branches consisting of:
+At any point in time, we have a number of maintained branches, currently consisting of:
-- The [`master`](https://github.com/Mbed-TLS/mbedtls/tree/master) branch:
+- The [`main`](https://github.com/Mbed-TLS/mbedtls/tree/main) branch:
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 new features land,
- as well as bug fixes and security fixes.
-- One or more long-time support (LTS) branches:
- these only get bug fixes and security fixes.
+ 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.
+- One or more long-time support (LTS) branches: these only get bug fixes and
+ security fixes. Currently, the supported LTS branches are:
+- [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28).
+- [`mbedtls-3.6`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-3.6).
+
+We retain a number of historical branches, whose names are prefixed by `archive/`,
+such as [`archive/mbedtls-2.7`](https://github.com/Mbed-TLS/mbedtls/tree/archive/mbedtls-2.7).
+These branches will not receive any changes or updates.
We use [Semantic Versioning](https://semver.org/). In particular, we maintain
-API compatibility in the `master` branch between major version changes. We
-also maintain ABI compatibility within LTS branches; see the next section for
-details.
+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
+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.
-Every major version will become an LTS branch when the next major version is
-released. We may occasionally create LTS branches from other releases at our
-discretion.
-When a new LTS branch is created, it usually remains supported for three years.
+We will make regular LTS releases on an 18-month cycle, each of which will have
+a 3 year support lifetime. On this basis, 3.6 LTS (released March 2024) will be
+supported until March 2027. The next LTS release will be a 4.x release, which is
+planned for September 2025.
## Backwards Compatibility for application code
@@ -30,30 +38,33 @@
number, and your code will still build, be secure, and work.
Note that this guarantee only applies if you either use the default
-compile-time configuration (`mbedtls/config.h`) or the same modified
+compile-time configuration (`mbedtls/mbedtls_config.h`) or the same modified
compile-time configuration. Changing compile-time configuration options can
result in an incompatible API or ABI, although features will generally not
affect unrelated features (for example, enabling or disabling a
cryptographic algorithm does not break code that does not use that
algorithm).
-There are rare exceptions: code that was relying on something that became
-insecure in the meantime (for example, crypto that was found to be weak) may
-need to be changed. In case security comes in conflict with backwards
-compatibility, we will put security first, but always attempt to provide a
-compatibility option.
+Note that new releases of Mbed TLS may extend the API. Here are some
+examples of changes that are common in minor releases of Mbed TLS, and are
+not considered API compatibility breaks:
-For the LTS branches, additionally we try very hard to also maintain ABI
-compatibility (same definition as API except with re-linking instead of
-re-compiling) and to avoid any increase in code size or RAM usage, or in the
-minimum version of tools needed to build the code. The only exception, as
-before, is in case those goals would conflict with fixing a security issue, we
-will put security first but provide a compatibility option. (So far we never
-had to break ABI compatibility in an LTS branch, but we occasionally had to
-increase code size for a security fix.)
+* Adding or reordering fields in a structure or union.
+* Removing a field from a structure, unless the field is documented as public.
+* Adding items to an enum.
+* Returning an error code that was not previously documented for a function
+ when a new error condition arises.
+* Changing which error code is returned in a case where multiple error
+ conditions apply.
+* Changing the behavior of a function from failing to succeeding, when the
+ change is a reasonable extension of the current behavior, i.e. the
+ addition of a new feature.
-For contributors, see the [Backwards Compatibility section of
-CONTRIBUTING](CONTRIBUTING.md#backwards-compatibility).
+There are rare exceptions where we break API compatibility: code that was
+relying on something that became insecure in the meantime (for example,
+crypto that was found to be weak) may need to be changed. In case security
+comes in conflict with backwards compatibility, we will put security first,
+but always attempt to provide a compatibility option.
## Backward compatibility for the key store
@@ -68,14 +79,37 @@
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
+compatibility (same definition as API except with re-linking instead of
+re-compiling) and to avoid any increase in code size or RAM usage, or in the
+minimum version of tools needed to build the code. The only exception, as
+before, is in case those goals would conflict with fixing a security issue, we
+will put security first but provide a compatibility option. (So far we never
+had to break ABI compatibility in an LTS branch, but we occasionally had to
+increase code size for a security fix.)
+
+For contributors, see the [Backwards Compatibility section of
+CONTRIBUTING](CONTRIBUTING.md#backwards-compatibility).
+
## Current Branches
The following branches are currently maintained:
-- [master](https://github.com/Mbed-TLS/mbedtls/tree/master)
+- [main](https://github.com/Mbed-TLS/mbedtls/tree/main)
- [`development`](https://github.com/Mbed-TLS/mbedtls/)
+- [`mbedtls-3.6`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-3.6)
+ maintained until March 2027, see
+ <https://github.com/Mbed-TLS/mbedtls/releases/tag/v3.6.0>.
- [`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.7>.
+ maintained until the end of 2024, see
+ <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.8>.
Users are urged to always use the latest version of a maintained branch.
diff --git a/BUGS.md b/BUGS.md
index 47bde07..a65c606 100644
--- a/BUGS.md
+++ b/BUGS.md
@@ -7,7 +7,7 @@
If you think you've found a bug in Mbed TLS, please follow these steps:
1. Make sure you're using the latest version of a
- [maintained branch](BRANCHES.md): `master`, `development`,
+ [maintained branch](BRANCHES.md): `main`, `development`,
or a long-time support branch.
2. Check [GitHub](https://github.com/Mbed-TLS/mbedtls/issues) to see if
your issue has already been reported. If not, …
diff --git a/README.md b/README.md
index bbd1fb2..6cc7762 100644
--- a/README.md
+++ b/README.md
@@ -190,7 +190,7 @@
- `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 `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).
+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/main/README.md#quick-start).
Porting Mbed TLS
----------------