Consolidate migration guide #512

2025-10-10T08:46:49-05:00

gilles-peskine-arm commented

2025-10-10 08:46:49 -05:00

(Migrated from github.com)

Put it in one file and fix broken links.

PR checklist

changelog not required because: doc only
framework PR not required
crypto PR here
mbedtls development PR https://github.com/Mbed-TLS/mbedtls/pull/10446
mbedtls 3.6 PR not required because: new stuff
tests not required because: doc only

Put it in one file and fix broken links. ## PR checklist - [x] **changelog** not required because: doc only - [x] **framework PR** not required - [x] **crypto PR** here - [ ] **mbedtls development PR** https://github.com/Mbed-TLS/mbedtls/pull/10446 - [x] **mbedtls 3.6 PR** not required because: new stuff - **tests** not required because: doc only

minosgalanakis (Migrated from github.com) reviewed

2025-10-10 09:32:43 -05:00

minosgalanakis (Migrated from github.com) left a comment

looks good overall. Only some minor typos and artefacts.

I have confirmed that the only text which has been removed is the following

docs/4.0-migration-guide/README

This directory contains sections intended for the migration guide
from Mbed TLS 3.6 to TF-PSA-Crypto 1.0 + Mbed TLS 4.0.

The files in this document should be markdown files with the .md
extension. They should generally contain level-2 sections (## title).
The files will be consolidated into a single cohesive document or
document set shortly before the .0 releases.

The reason to have multiple files is that each strand of work can create
one file, without worrying about where to fit in the document structure.
We'll worry about the general structure once we have the content.
Furthermore, placing different strands of work in separate files will
avoid merge conflicts (as would happen e.g. if parallel strands of
work append to the same file in concurrent pull requests).

Files can be placed in the docs/4.0-migration-guide indifferently in
mbedtls or TF-PSA-Crypto, as convenient.

Documentation that is specifically about migrating from the legacy
crypto API to the PSA crypto API should be added to the existing
docs/psa-transition.md instead.

docs/4.0-migration-guide/private-decls/00README


docs/4.0-migration-guide/private-decls/00README

Temporary sub-directory to avoid conflicts in private-decls.md.
Will be merged back to private-decls.md as part of
https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/232

One file per header, with .md extension (and valid markdown content).

looks good overall. Only some minor typos and artefacts. I have confirmed that the only text which has been removed is the following docs/4.0-migration-guide/README ~~~~~ This directory contains sections intended for the migration guide from Mbed TLS 3.6 to TF-PSA-Crypto 1.0 + Mbed TLS 4.0. The files in this document should be markdown files with the .md extension. They should generally contain level-2 sections (## title). The files will be consolidated into a single cohesive document or document set shortly before the .0 releases. The reason to have multiple files is that each strand of work can create one file, without worrying about where to fit in the document structure. We'll worry about the general structure once we have the content. Furthermore, placing different strands of work in separate files will avoid merge conflicts (as would happen e.g. if parallel strands of work append to the same file in concurrent pull requests). Files can be placed in the docs/4.0-migration-guide indifferently in mbedtls or TF-PSA-Crypto, as convenient. Documentation that is specifically about migrating from the legacy crypto API to the PSA crypto API should be added to the existing docs/psa-transition.md instead. ~~~~~ docs/4.0-migration-guide/private-decls/00README ~~~~~ docs/4.0-migration-guide/private-decls/00README ~~~~~ Temporary sub-directory to avoid conflicts in private-decls.md. Will be merged back to private-decls.md as part of https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/232 One file per header, with .md extension (and valid markdown content). ~~~~~

docs/1.0-migration-guide.md

					
				@ -0,0 +1,1076 @@

				# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0

typo:
ommited -> omitted

Multiple occurences

typo: `ommited` -> `omitted` Multiple occurences

Platform-specific configuration are now handled in include/psa/crypto_config.h.

- Platform-specific configurations are now handled in `include/psa/crypto_config.h`.

- Platform-specific configuration are now handled in `include/psa/crypto_config.h`. ```suggestion - Platform-specific configurations are now handled in `include/psa/crypto_config.h`. ```

This

```c

looks like merge artifact

This ```c looks like merge artifact

bjwtaylor (Migrated from github.com) approved these changes

2025-10-10 09:56:46 -05:00

bjwtaylor (Migrated from github.com) left a comment

A few fairly minor things that are probably only worth updating if you are already upreving,

docs/1.0-migration-guide.md

					
				@ -0,0 +1,1076 @@

				# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0

1.0 instead of 1?

instead.

all the options

docs/1.0-migration-guide.md

					
				@ -0,0 +12,4 @@

				- CMake is now the only supported build system.

				- The cryptography API is now mostly the PSA API: most legacy cryptography APIs have been removed. Some non-PSA APIs remain for features that PSA does not cover.

				- In the same vein, third-party implementations of cryptographic mechanisms must be provided as PSA drivers: ALT implementations are no longer supported.

				- In the same vein, the random generator configuration has been adapted and simplified.

Random Number Generator not Random Generator?

docs/1.0-migration-guide.md

					
				@ -0,0 +243,4 @@

				### No random generator instantiation

				Formerly, applications using various cryptographic features needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem.

Random Number Generator?

docs/1.0-migration-guide.md

					
				@ -0,0 +458,4 @@

				Some obsolescent cryptographic mechanisms have been removed:

				* The library no longer supports DES (including 3DES). All supported block ciphers now have 128-bit blocks. As a consequence, the PKCS12 module, which provided the obsolete PBE mode for private key encryption that does not support stronger ciphers, has been removed.

				* The library no longer supports elliptic curves whose size is 224 bits or less. The following curves are no longer supported: secp192r1, secp192k1, secp224k1, secp224r1. Use larger curves such as secp256r1.

static ecdh?

docs/1.0-migration-guide.md

					
				@ -0,0 +965,4 @@

				### Move the hash algorithm parameter into the algorithm identifier

				The function `psa_pake_cs_set_hash()` has been removed. Its `hash` argument is now passed to `PSA_ALG_JPAKE()` which is now a function-like macro with one parameter.

probably , which is now...

minosgalanakis (Migrated from github.com) approved these changes

2025-10-10 10:00:47 -05:00

minosgalanakis (Migrated from github.com) left a comment

LGTM

gilles-peskine-arm (Migrated from github.com) reviewed

2025-10-10 10:05:20 -05:00

docs/1.0-migration-guide.md

					
				@ -0,0 +243,4 @@

				### No random generator instantiation

				Formerly, applications using various cryptographic features needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem.

“Random generator” and “random number generator” are synonyms in practice. “Random number generator” is more traditional, but it's more of a random bit generator or random byte generator, really, so modern terminology is evolving. The abbreviation RNG has stuck, however.

In this context, I don't think there's any risk of confusion from mixing the two terms, so I prefer to not make further changes for this.

“Random generator” and “random number generator” are synonyms in practice. “Random number generator” is more traditional, but it's more of a random bit generator or random byte generator, really, so modern terminology is evolving. The abbreviation RNG has stuck, however. In this context, I don't think there's any risk of confusion from mixing the two terms, so I prefer to not make further changes for this.

gilles-peskine-arm (Migrated from github.com) reviewed

2025-10-10 10:06:29 -05:00

docs/1.0-migration-guide.md

					
				@ -0,0 +1,1076 @@

				# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0

Technically 1 is a new major version, and 1.0.0 is the first release in that major version? I don't think that matters much anyway.

gilles-peskine-arm (Migrated from github.com) reviewed

2025-10-10 10:08:21 -05:00

docs/1.0-migration-guide.md

					
				@ -0,0 +458,4 @@

				Some obsolescent cryptographic mechanisms have been removed:

				* The library no longer supports DES (including 3DES). All supported block ciphers now have 128-bit blocks. As a consequence, the PKCS12 module, which provided the obsolete PBE mode for private key encryption that does not support stronger ciphers, has been removed.

				* The library no longer supports elliptic curves whose size is 224 bits or less. The following curves are no longer supported: secp192r1, secp192k1, secp224k1, secp224r1. Use larger curves such as secp256r1.

Static ECDH is a way to use ECDH. It wasn't a feature of the crypto library.

gilles-peskine-arm (Migrated from github.com) reviewed

2025-10-10 10:08:50 -05:00

docs/1.0-migration-guide.md

					
				@ -0,0 +965,4 @@

				### Move the hash algorithm parameter into the algorithm identifier

				The function `psa_pake_cs_set_hash()` has been removed. Its `hash` argument is now passed to `PSA_ALG_JPAKE()` which is now a function-like macro with one parameter.