Migration guide: remaining APIs #479

2025-09-25T11:57:20-05:00

gilles-peskine-arm commented

2025-09-25 11:57:20 -05:00

(Migrated from github.com)

These are updates to the 1.0 migration guide based on comparing the public header files in Mbed TLS 3.6 (excluding X.509/TLS ones) and in TF-PSA-Crypto 1.0.

See https://github.com/Mbed-TLS/mbedtls/pull/10422#discussion_r2383050384 regarding removed compilation options. I haven't gone looking for compilation options with changed semantics; I don't recall anything except arguably the RNG which already has a well-populated section.

Out of scope:

PK #478
PAKE #484
Changes that aren't visible via header files, such as build system changes

PR checklist

changelog not required because: doc only
framework PR not required
mbedtls development PR https://github.com/Mbed-TLS/mbedtls/pull/10422 (essentially independent, but very similar sections on the config file split)
mbedtls 3.6 PR not required because: new stuff
tests not required because: doc only

These are updates to the 1.0 migration guide based on comparing the public header files in Mbed TLS 3.6 (excluding X.509/TLS ones) and in TF-PSA-Crypto 1.0. See https://github.com/Mbed-TLS/mbedtls/pull/10422#discussion_r2383050384 regarding removed compilation options. I haven't gone looking for compilation options with changed semantics; I don't recall anything except arguably the RNG which already has a well-populated section. Out of scope: * [x] PK #478 * [x] PAKE #484 * [ ] Changes that aren't visible via header files, such as build system changes ## PR checklist - [x] **changelog** not required because: doc only - [x] **framework PR** not required - [x] **mbedtls development PR** https://github.com/Mbed-TLS/mbedtls/pull/10422 (essentially independent, but very similar sections on the config file split) - [x] **mbedtls 3.6 PR** not required because: new stuff - **tests** not required because: doc only

gilles-peskine-arm commented

2025-09-29 02:24:57 -05:00

(Migrated from github.com)

I'm going to rebase on top of the latest development so that the CI passes.

I'm going to rebase on top of the latest `development` so that the CI passes.

bjwtaylor (Migrated from github.com) reviewed

2025-09-29 03:40:23 -05:00

docs/4.0-migration-guide/configuration.md

					
				@ -0,0 +1,36 @@

				## Compile-time configuration

probably "all the configuration" would sound better.

bjwtaylor (Migrated from github.com) reviewed

2025-09-29 03:51:29 -05:00

docs/4.0-migration-guide/configuration.md

					
				@ -0,0 +8,4 @@

				* otherwise `<psa/crypto_config.h>`;

				* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set.

				The macros `MBEDTLS_PSA_CRYPTO_CONFIG_FILE` and `MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE` are no longer recognized. Use `TF_PSA_CRYPTO_CONFIG_FILE` and `TF_PSA_CRYPTO_USER_CONFIG_FILE` instead

Probably more a question than a comment "recognized" is american English, as opposed to recognised (British English). I don't think there is a right or wrong answer which one to use, on previous projects I seem to remember being told we should use British English in Arm. I guess we should at least be consistent across the project if not the company? So do we have precedence or instruction to use American over British English?

bjwtaylor (Migrated from github.com) reviewed

2025-09-29 04:08:42 -05:00

docs/4.0-migration-guide/rng.md

					
				@ -1,11 +1,172 @@

				## Random number generation configuration

I would change this to "If you have a fast cryptographic-quality source of random data, enable MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG and do not enable MBEDTLS_ENTROPY_C." As it probably reads better, though it's very minor.

I would change this to "If you have a fast cryptographic-quality source of random data, enable `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` and do not enable `MBEDTLS_ENTROPY_C`." As it probably reads better, though it's very minor.

mpg (Migrated from github.com) reviewed

2025-09-29 04:10:02 -05:00

docs/4.0-migration-guide/configuration.md

					
				@ -0,0 +8,4 @@

				* otherwise `<psa/crypto_config.h>`;

				* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set.

				The macros `MBEDTLS_PSA_CRYPTO_CONFIG_FILE` and `MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE` are no longer recognized. Use `TF_PSA_CRYPTO_CONFIG_FILE` and `TF_PSA_CRYPTO_USER_CONFIG_FILE` instead

IIRC last time I heard about it American English spelling was the rule, with an exception for products whose team was fully British, who were allowed to stick to British English if they wanted to, or something like that.

bjwtaylor (Migrated from github.com) reviewed

2025-09-29 04:12:03 -05:00

docs/4.0-migration-guide/rng.md

					
				@ -1,11 +1,172 @@

				## Random number generation configuration

Should probably be non-volatile, or possibly just non volatile.

bjwtaylor (Migrated from github.com) requested changes

2025-09-29 04:24:34 -05:00

bjwtaylor (Migrated from github.com) left a comment

Just a few minor suggestions and comments.

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

2025-09-29 04:25:03 -05:00

docs/4.0-migration-guide/configuration.md

					
				@ -0,0 +8,4 @@

				* otherwise `<psa/crypto_config.h>`;

				* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set.

				The macros `MBEDTLS_PSA_CRYPTO_CONFIG_FILE` and `MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE` are no longer recognized. Use `TF_PSA_CRYPTO_CONFIG_FILE` and `TF_PSA_CRYPTO_USER_CONFIG_FILE` instead

Arm's main style guide requires American English. But we're a TrustedFirmware project, not an Arm project, and there isn't any specific style guide that we're mandated to follow. I'm not sure if it's written down anywhere, but our unofficial policy is that all “mainstream” variants of English are welcome, as long as you're consistent within a reasonable fragment of text.

In our current documentation, -ized/-ization endings are much more prevalent than -ised/-isation endings.

Arm's main style guide requires American English. But we're a TrustedFirmware project, not an Arm project, and there isn't any specific style guide that we're mandated to follow. I'm not sure if it's written down anywhere, but our unofficial policy is that all “mainstream” variants of English are welcome, as long as you're consistent within a reasonable fragment of text. In our current documentation, -ized/-ization endings are much more prevalent than -ised/-isation endings.

mpg (Migrated from github.com) reviewed

2025-09-29 04:42:11 -05:00

mpg (Migrated from github.com) left a comment

LGTM except for two typos and a question.

docs/4.0-migration-guide/configuration.md

					
				@ -0,0 +1,36 @@

				## Compile-time configuration

Typo: s/is set/if set/

The last sentence doesn't sound very clear to me. Do you mean if you want say LMS you should #include "lms.h" and then check for defined(MBEDTLS_LMS_C) rather than include build_info.h? If so, probably just add an example.

(Btw, if there are strong reason for users not to include build_info.h directly or this is just a soft advice, like their code is going to be more compact without it?)

The last sentence doesn't sound very clear to me. Do you mean if you want say LMS you should `#include "lms.h"` and then check for `defined(MBEDTLS_LMS_C)` rather than include `build_info.h`? If so, probably just add an example. (Btw, if there are strong reason for users not to include `build_info.h` directly or this is just a soft advice, like their code is going to be more compact without it?)

Typo: properties OF the configuration

davidhorstmann-arm (Migrated from github.com) reviewed

2025-09-29 04:54:15 -05:00

davidhorstmann-arm (Migrated from github.com) left a comment

No description provided.

Two comments but LGTM otherwise, thanks!

davidhorstmann-arm commented

2025-09-29 04:56:13 -05:00

(Migrated from github.com)

Whoops, I was a third reviewer. I'll leave my comments here but go and review one of the other PRs.

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

2025-09-29 08:38:08 -05:00

docs/4.0-migration-guide/rng.md

					
				@ -1,11 +1,172 @@

				## Random number generation configuration

I've completely reworked this subsection, because MBEDTLS_ENTROPY_C is now an internal option. We had forgotten to update the migration guide for that.

I've completely reworked this subsection, because `MBEDTLS_ENTROPY_C` is now an internal option. We had forgotten to update the migration guide for that.