Migration guide: PAKE #484

2025-09-29T03:33:17-05:00

mpg commented

2025-09-29 03:33:17 -05:00

(Migrated from github.com)

Description

Populate the PAKE section of the 1.0 migration guide. Resolves #335

Based on:

the PSA ChangeLog (link in the document);
the "Update PAKE API to 1.2" EPIC on the board:
- looking at changes in crypto_extra.h,
- using mbedtls PRs as a basis for the before-after examples.

PR checklist

changelog not required because: documentation
framework PR not required
mbedtls development PR not required because: crypto only
mbedtls 3.6 PR not required because: 1.0
tests not required because: documentation

## Description Populate the PAKE section of the 1.0 migration guide. Resolves #335 Based on: - the PSA ChangeLog (link in the document); - the "Update PAKE API to 1.2" EPIC on [the board](https://github.com/orgs/Mbed-TLS/projects/18/views/1): - looking at changes in `crypto_extra.h`, - using mbedtls PRs as a basis for the before-after examples. ## PR checklist - [x] **changelog** not required because: documentation - [x] **framework PR** not required - [x] **mbedtls development PR** not required because: crypto only - [x] **mbedtls 3.6 PR** not required because: 1.0 - **tests** not required because: documentation

yanesca (Migrated from github.com) reviewed

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

yanesca (Migrated from github.com) left a comment

Found a typo and have a non-blocker question, but other than that it looks good to me.

docs/4.0-migration-guide/pake.md

					
				@ -1,5 +1,126 @@

				## Changes to the PAKE interface

Typo

The PAKE interface in TF-PSA-Crypto 1.0 has been updated to match PSA Crypto API [1.2 Final](https://arm-software.github.io/psa-api/crypto/1.2/ext-pake/) PAKE extension, which is the same version that has been integrated into the main specification of PSA Crypto [version 1.3](https://arm-software.github.io/psa-api/crypto/1.3/).

Typo ```suggestion The PAKE interface in TF-PSA-Crypto 1.0 has been updated to match PSA Crypto API [1.2 Final](https://arm-software.github.io/psa-api/crypto/1.2/ext-pake/) PAKE extension, which is the same version that has been integrated into the main specification of PSA Crypto [version 1.3](https://arm-software.github.io/psa-api/crypto/1.3/). ```

docs/4.0-migration-guide/pake.md

					
				@ -6,0 +87,4 @@

				psa_set_key_algorithm(&shared_key_attributes, alg); // same as derivation

				psa_set_key_type(&shared_key_attributes, PSA_KEY_TYPE_DERIVE);

				status = psa_pake_get_shared_key(&pake_op,

Looking at the API spec, PSA_KEY_TYPE_HMAC is permitted here as well. Is that the case for our implementation too? If so would it be worth signalling that here in some way?

Looking at the API spec, `PSA_KEY_TYPE_HMAC` is permitted here as well. Is that the case for our implementation too? If so would it be worth signalling that here in some way?

mpg (Migrated from github.com) reviewed

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

docs/4.0-migration-guide/pake.md

					
				@ -6,0 +87,4 @@

				psa_set_key_algorithm(&shared_key_attributes, alg); // same as derivation

				psa_set_key_type(&shared_key_attributes, PSA_KEY_TYPE_DERIVE);

				status = psa_pake_get_shared_key(&pake_op,

Looking at the code, we don't seem to enforce any specific key type here. We probably should. Then we should have negative tests when the key type is not good, and also a positive test for KEY_TYPE_HMAC. I'm creating an issue to track this: https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/485

In the meantime, I'll add a sentence here about HMAC.

Looking at the code, we don't seem to enforce any specific key type here. We probably should. Then we should have negative tests when the key type is not good, and also a positive test for `KEY_TYPE_HMAC`. I'm creating an issue to track this: https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/485 In the meantime, I'll add a sentence here about HMAC.

yanesca (Migrated from github.com) reviewed

2025-09-29 06:55:30 -05:00

yanesca (Migrated from github.com) left a comment

No description provided.

LGTM

gilles-peskine-arm (Migrated from github.com) requested changes

2025-09-29 09:34:41 -05:00

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

How to replace psa_pake_get_implicit_key() with psa_pake_get_shared_key() is not fully clear. LGTM otherwise.

For completeness, I checked the changes from API 1.1beta to 1.2 that are relevant to J-PAKE, and the changes in psa/crypto_extra.h, and didn't find anything else to mention.

How to replace `psa_pake_get_implicit_key()` with `psa_pake_get_shared_key()` is not fully clear. LGTM otherwise. For completeness, I checked the changes from API 1.1beta to 1.2 that are relevant to J-PAKE, and the changes in `psa/crypto_extra.h`, and didn't find anything else to mention.

docs/4.0-migration-guide/pake.md

					
				@ -1,5 +1,126 @@

				## Changes to the PAKE interface

Minor: wouldn't PSA_ALG_TLS12_ECJPAKE_TO_PMS be a better example?

Minor: wouldn't `PSA_ALG_TLS12_ECJPAKE_TO_PMS` be a better example?

It has to be the algorithm that derivation_op was set up for.

I think it would be helpful to include the code to set up and use the derivation operation, in both the before and after snippets.

A typical audience for the migration guide is someone who may be upgrading multiple libraries used in a project, and who isn't very familiar with the code that they're upgrading. So we should guide them with respect to understanding their existing application code.

It has to be the algorithm that `derivation_op` was set up for. I think it would be helpful to include the code to set up and use the derivation operation, in both the before and after snippets. A typical audience for the migration guide is someone who may be upgrading multiple libraries used in a project, and who isn't very familiar with the code that they're upgrading. So we should guide them with respect to understanding their existing application code.

Minor: this can be done as soon as psa_pake_get_shared_key returns.

Also, it doesn't have to be done, but it's arguably good practice, so I agree with having it in, and not making any mention of it being optional (this code is already pretty long).

Minor: this can be done as soon as `psa_pake_get_shared_key` returns. Also, it doesn't _have_ to be done, but it's arguably good practice, so I agree with having it in, and not making any mention of it being optional (this code is already pretty long).

Can this be done immediately, or do you need to wait until the key derivation operation is finished?

(Answer: according to the PSA specification, you must not destroy a key while it's in use in an operation: that would effectively abort the operation. But in our implementation, destroying a key while an operation is in progress is currently undetected.)

Can this be done immediately, or do you need to wait until the key derivation operation is finished? (Answer: according to the PSA specification, you must not destroy a key while it's in use in an operation: that would effectively abort the operation. But in our implementation, destroying a key while an operation is in progress is currently undetected.)

mpg (Migrated from github.com) reviewed

2025-09-30 01:46:50 -05:00

docs/4.0-migration-guide/pake.md

					
				@ -1,5 +1,126 @@

				## Changes to the PAKE interface

Absolutely, that's what I was looking for, I must have navigated to the wrong part of the file by accident.

mpg (Migrated from github.com) reviewed

2025-09-30 01:50:21 -05:00

docs/4.0-migration-guide/pake.md

					
				@ -1,5 +1,126 @@

				## Changes to the PAKE interface

Yes, I wasn't sure whether to put cleanup as soon as it can be done, or all at the end to reduce clutter.

gilles-peskine-arm (Migrated from github.com) approved these changes

2025-09-30 04:37:46 -05:00

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

LGTM

yanesca (Migrated from github.com) approved these changes

2025-09-30 04:54:34 -05:00

yanesca (Migrated from github.com) left a comment

LGTM

Sign in to join this conversation.

No reviewers

gilles-peskine-arm

yanesca

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gh-Mbed-TLS/TF-PSA-Crypto!484

Rows
Columns