Legacy-to-PSA transition guide #7766

gilles-peskine-arm · 2023-06-13T17:58:00Z

A new document explains how to migrate application code from the legacy crypto API to the PSA API.

I initially thought this would go in the knowledge base, but we're going to have different versions in the 3.x series and in the 4.x series, so upon reflection it should be versioned. The document mostly focuses on what is in Mbed TLS today, but includes a few notes about upcoming changes.

As I was writing this document, some gaps between the two APIs became evident. I created a few issues for these gaps, with a link in the document.

Reviewers

The top-level sections are largely independent, so we are splitting the review load. For each section, we will have at least one person reviewing for clarity and one for correctness.

Clarity (including completeness of coverage): is the document comprehensible by people who aren't familiar with the PSA API, and maybe not with the legacy API either? The document isn't meant to be self-contained: readers are supposed to refer to the Mbed TLS reference documentation. The goal of this document is to allow readers to determine which functions to call and how to combine them. Note that this includes a completeness aspect: are all the elements of the legacy API discussed?
Correctness (including completeness of purpose): is this document making incorrect claims? Are there major use cases of the legacy API that are not covered but should be?

I recommend that all reviewers read “Introduction” and at least skim “General considerations” to get an idea of the goals of the document.

Sections	Length	Reviewers for correctness	Reviewers for clarity
Introduction	S	Ronald ✅	@tom-daubney-arm ✅
General considerations	S	Ronald ✅	@tom-daubney-arm ✅
Summary of API modules	S	Ronald ✅	@tom-daubney-arm ✅
Compile-time configuration	M	Ronald ✅	@tom-daubney-arm ✅
Miscellaneous support modules	S	Ronald ✅	@tom-daubney-arm ✅
Symmetric encryption	L	@davidhorstmann-arm ✅	@Ryan-Everett-arm ✅
Hashes and MAC	L	@gowthamsk-arm✅	@davidhorstmann-arm ✅
Key derivation	S	@valeriosetti✅	@tgonzalezorlandoarm✅
Random generation	S	@valeriosetti✅	@tgonzalezorlandoarm✅
Asymmetric cryptography	XL	Manuel ✅	@tom-daubney-arm ✅

PR checklist

changelog no (doc only)
backport no (no point in a 2.28 migration guide)
tests no (doc only)

Covers most modules, but missing most of ecp, ecdh and dhm. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

docs/psa-transition.md

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

per Mbed-TLS#7439 (comment) and Mbed-TLS#7774 (comment) State that EXPORT implies BASIC. Also fix missing `WANT_` parts. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Also correct some statements about rsa/ecp/pk check functions. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm · 2023-06-15T19:16:32Z

I have now covered ecp.h and have no further changes planned for this first edition of the document, except for handling review comments as they come.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

It's not pretty. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm · 2023-06-20T21:40:58Z

docs/psa-transition.md

+    mbedtls_mpi_init(&d);
+    mbedtls_ecp_export(ec, &grp, &d, &Q);
+    size_t bits;
+    curve = mbedtls_ecc_group_to_psa(grp.id, &bits);


Turns out we did have the ECP→PSA bridge function here, since the beginning. On the other hand the way to extract metadata from the legacy object is ridiculous because we haven't finished 3.0 properly.

gilles-peskine-arm · 2023-11-23T09:12:04Z

I'm raising the priority to very-high because the detailed investigation for the legacy-to-PSA API design depends on this and this investigation is overdue.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

ronald-cron-arm

Regarding the "Compile-time configuration" section, only two propositions that make things more explicit to me.

docs/psa-transition.md

ronald-cron-arm

One comment about the "Miscellaneous support modules" section.

docs/psa-transition.md

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

mpg · 2023-12-13T11:01:10Z

For the record, I'm happy with my section except for the part about static (EC)DH. Since it looks like this is unlikely to reveal any new gaps in existing APIs (in my experience, doing static (EC)DH is actually easier with PSA as there are fewer differences between static and ephemeral, it's really the legacy API that makes things awkward, as usual), I'd be happy to leave that to a follow-up as long as it's tracked.

davidhorstmann-arm · 2023-12-13T13:48:00Z

I hereby note for the avoidance of doubt that I'm happy with the 'Hashes and MAC' section and therefore have ticked it.

docs/psa-transition.md

tom-daubney-arm

My sections LGTM, thanks.

ronald-cron-arm

LGTM for the sections I've reviewed.

Happy with this section, one more to review

tgonzalezorlandoarm

LGTM

gowthamsk-arm

LGTM

davidhorstmann-arm

I have finished going through symmetric encryption.

LGTM, thanks!

gilles-peskine-arm · 2023-12-20T10:08:12Z

@mpg I've filed an issue for static ECDH. Is the document ok to merge now as far as you're concerned?

mpg

LGTM for asymmetric crypto.

Legacy-to-PSA transition guide

5ad8ca2

Covers most modules, but missing most of ecp, ecdh and dhm. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Mention mbedtls_psa_get_random

c7b53f3

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

mpg reviewed Jun 14, 2023

View reviewed changes

docs/psa-transition.md Outdated Show resolved Hide resolved

mpg reviewed Jun 14, 2023

View reviewed changes

docs/psa-transition.md Outdated Show resolved Hide resolved

mpg reviewed Jun 14, 2023

View reviewed changes

docs/psa-transition.md Outdated Show resolved Hide resolved

mpg mentioned this pull request Jun 14, 2023

Update PSA_WANT spec for new KEY_PAIR scheme #7774

Merged

3 tasks

ronald-cron-arm self-requested a review June 14, 2023 10:33

gilles-peskine-arm added 4 commits June 15, 2023 18:33

Mention self-tests

b33d0ac

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Cover ECDH and DHM

5bd4f17

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Rename PSA_WANT_KEY_TYPE_xxx_KEY_PAIR_USE to ..._BASIC

f75e65d

per Mbed-TLS#7439 (comment) and Mbed-TLS#7774 (comment) State that EXPORT implies BASIC. Also fix missing `WANT_` parts. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Cover ecp.h

379ff87

Also correct some statements about rsa/ecp/pk check functions. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm added 2 commits June 20, 2023 23:38

The ECP curve name is the one from TLS, not one we made up

603f0fc

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Show how to extract curve information from an ecp_keypair

909cf5a

It's not pretty. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm commented Jun 20, 2023

View reviewed changes

gilles-peskine-arm mentioned this pull request Jun 21, 2023

ECP keypair utility functions #7815

Merged

3 tasks

gilles-peskine-arm added priority-very-high Highest priority - prioritise this over other review work and removed priority-medium Medium priority - this can be reviewed as time permits labels Nov 23, 2023

mpg self-requested a review November 23, 2023 09:13

daverodgman self-requested a review November 27, 2023 16:19

tom-daubney-arm self-requested a review November 27, 2023 16:19

Ryan-Everett-arm self-requested a review November 27, 2023 16:24

gilles-peskine-arm added 2 commits December 12, 2023 19:20

Fix some MAC-related function names

0308d79

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Correct and clarify discussion of AES-CMAC-PRF-128

5feac95

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

ronald-cron-arm reviewed Dec 13, 2023

View reviewed changes

docs/psa-transition.md Show resolved Hide resolved

docs/psa-transition.md Show resolved Hide resolved

ronald-cron-arm reviewed Dec 13, 2023

View reviewed changes

docs/psa-transition.md Outdated Show resolved Hide resolved

Clarify psa_constant_names

1ef1eb2

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gowthamsk-arm reviewed Dec 13, 2023

View reviewed changes

docs/psa-transition.md Show resolved Hide resolved

tom-daubney-arm self-requested a review December 18, 2023 16:17

tom-daubney-arm approved these changes Dec 18, 2023

View reviewed changes

ronald-cron-arm approved these changes Dec 18, 2023

View reviewed changes

tgonzalezorlandoarm approved these changes Dec 19, 2023

View reviewed changes

gowthamsk-arm approved these changes Dec 19, 2023

View reviewed changes

davidhorstmann-arm approved these changes Dec 19, 2023

View reviewed changes

gilles-peskine-arm mentioned this pull request Dec 20, 2023

Update legacy-to-PSA transition guide regarding ECDH #8648

Open

mpg self-requested a review December 20, 2023 10:16

mpg reviewed Dec 20, 2023

View reviewed changes

mpg added approved Design and code approved - may be waiting for CI or backports and removed needs-review Every commit must be reviewed by at least two team members, labels Dec 20, 2023

mpg enabled auto-merge December 20, 2023 10:22

mpg approved these changes Dec 20, 2023

View reviewed changes

mpg added this pull request to the merge queue Dec 20, 2023

Merged via the queue into Mbed-TLS:development with commit 9934f83 Dec 20, 2023
6 checks passed

gilles-peskine-arm mentioned this pull request Feb 20, 2024

Official bridge from PK to PSA #7760

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Legacy-to-PSA transition guide #7766

Legacy-to-PSA transition guide #7766

gilles-peskine-arm commented Jun 13, 2023 •

edited by mpg

Loading

gilles-peskine-arm commented Jun 15, 2023 •

edited

Loading

gilles-peskine-arm Jun 20, 2023

gilles-peskine-arm commented Nov 23, 2023

ronald-cron-arm left a comment

ronald-cron-arm left a comment

mpg commented Dec 13, 2023 •

edited

Loading

davidhorstmann-arm commented Dec 13, 2023

tom-daubney-arm left a comment

ronald-cron-arm left a comment

tgonzalezorlandoarm left a comment

gowthamsk-arm left a comment

davidhorstmann-arm left a comment

gilles-peskine-arm commented Dec 20, 2023

mpg left a comment

Legacy-to-PSA transition guide #7766

Legacy-to-PSA transition guide #7766

Conversation

gilles-peskine-arm commented Jun 13, 2023 • edited by mpg Loading

Reviewers

PR checklist

gilles-peskine-arm commented Jun 15, 2023 • edited Loading

gilles-peskine-arm Jun 20, 2023

Choose a reason for hiding this comment

gilles-peskine-arm commented Nov 23, 2023

ronald-cron-arm left a comment

Choose a reason for hiding this comment

ronald-cron-arm left a comment

Choose a reason for hiding this comment

mpg commented Dec 13, 2023 • edited Loading

davidhorstmann-arm commented Dec 13, 2023

tom-daubney-arm left a comment

Choose a reason for hiding this comment

ronald-cron-arm left a comment

Choose a reason for hiding this comment

tgonzalezorlandoarm left a comment

Choose a reason for hiding this comment

gowthamsk-arm left a comment

Choose a reason for hiding this comment

davidhorstmann-arm left a comment

Choose a reason for hiding this comment

gilles-peskine-arm commented Dec 20, 2023

mpg left a comment

Choose a reason for hiding this comment

gilles-peskine-arm commented Jun 13, 2023 •

edited by mpg

Loading

gilles-peskine-arm commented Jun 15, 2023 •

edited

Loading

mpg commented Dec 13, 2023 •

edited

Loading