From 8ca2a5bf9502431e29d7338a3516bde53b8aa23d Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 8 Oct 2025 17:36:22 +0200 Subject: [PATCH 1/3] Document JPAKE limitations Document limitations on the user ID, peer ID, primitive (elliptic curve) and hash for `PSA_ALG_JPAKE`. https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/502 https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/503 https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/504 Signed-off-by: Gilles Peskine --- include/psa/crypto_extra.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 0e7898983b..7ec110a20c 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -760,6 +760,16 @@ int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg); * To make the authentication explicit there are various methods, see Section 5 * of RFC 8236 for two examples. * + * \note The JPAKE implementation has the following limitations: + * - The only supported primitive is ECC on the curve secp256r1, i.e. + * `PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, + * PSA_ECC_FAMILY_SECP_R1, 256)`. + * - The only supported hash algorithm is SHA-256, i.e. + * `PSA_ALG_SHA_256`. + * - When using the built-in implementation, the user ID and the peer ID + * must be `"client"` (6-byte string) or `"server"` (6-byte string). + * Third-party drivers may or may not have this limitation. + * */ #define PSA_ALG_JPAKE ((psa_algorithm_t) 0x0a000100) @@ -1196,6 +1206,8 @@ static psa_algorithm_t psa_pake_cs_get_algorithm( * This function overwrites any PAKE algorithm * previously set in \p cipher_suite. * + * \note For #PSA_ALG_JPAKE, the only supported hash algorithm is SHA-256. + * * \param[out] cipher_suite The cipher suite structure to write to. * \param algorithm The PAKE algorithm to write. * (`PSA_ALG_XXX` values of type ::psa_algorithm_t @@ -1219,6 +1231,10 @@ static psa_pake_primitive_t psa_pake_cs_get_primitive( * * This function overwrites any primitive previously set in \p cipher_suite. * + * \note For #PSA_ALG_JPAKE, the only supported primitive is ECC on the curve + * secp256r1, i.e. `PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, + * PSA_ECC_FAMILY_SECP_R1, 256)`. + * * \param[out] cipher_suite The cipher suite structure to write to. * \param primitive The primitive to write. If this is 0, the * primitive type in \p cipher_suite becomes @@ -1555,6 +1571,10 @@ psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation, * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) * for more information. * + * \note When using the built-in implementation of #PSA_ALG_JPAKE, the user ID + * must be `"client"` (6-byte string) or `"server"` (6-byte string). + * Third-party drivers may or may not have this limitation. + * * \param[in,out] operation The operation object to set the user ID for. It * must have been set up by psa_pake_setup() and * not yet in use (neither psa_pake_output() nor @@ -1596,6 +1616,10 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation, * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) * for more information. * + * \note When using the built-in implementation of #PSA_ALG_JPAKE, the peer ID + * must be `"client"` (6-byte string) or `"server"` (6-byte string). + * Third-party drivers may or may not have this limitation. + * * \param[in,out] operation The operation object to set the peer ID for. It * must have been set up by psa_pake_setup() and * not yet in use (neither psa_pake_output() nor From 98a4029d5169e8f18f3a0c2864794000c9641876 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 8 Oct 2025 17:19:02 +0200 Subject: [PATCH 2/3] Add storage format test case for JPAKE The storage test generator doesn't support JPAKE at this time. So write a test case manually. The key is not exercised, since `psa_exercise_key()` doesn't support PAKE at this time. But at least we can use this test case to ensure that we know how the key is represented in storage. Signed-off-by: Gilles Peskine --- .../suites/test_suite_psa_crypto_storage_format.misc.data | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/suites/test_suite_psa_crypto_storage_format.misc.data b/tests/suites/test_suite_psa_crypto_storage_format.misc.data index 359053ec0d..5b8c2cb2c0 100644 --- a/tests/suites/test_suite_psa_crypto_storage_format.misc.data +++ b/tests/suites/test_suite_psa_crypto_storage_format.misc.data @@ -10,6 +10,14 @@ PSA storage save: AES-GCM+CTR depends_on:PSA_WANT_KEY_TYPE_AES key_storage_save:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_TYPE_AES:128:PSA_KEY_USAGE_EXPORT | PSA_KEY_USAGE_ENCRYPT:PSA_ALG_GCM:PSA_ALG_CTR:"404142434445464748494a4b4c4d4e4f":"505341004b45590000000000010000000024800001010000000250050010c00410000000404142434445464748494a4b4c4d4e4f" +PSA storage read: PASSWORD-JPAKE +depends_on:PSA_WANT_ALG_JPAKE:PSA_WANT_ALG_SHA_256:PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT:PSA_WANT_ECC_SECP_R1_256 +key_storage_read:0x0001:PSA_KEY_TYPE_PASSWORD:8:PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT:PSA_ALG_JPAKE:PSA_ALG_NONE:"4c":"505341004b455900000000000100000003120800014000000001000a00000000010000004c":0 + +PSA storage save: PASSWORD-JPAKE +depends_on:PSA_WANT_ALG_JPAKE:PSA_WANT_ALG_SHA_256:PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT:PSA_WANT_ECC_SECP_R1_256 +key_storage_save:0x0001:PSA_KEY_TYPE_PASSWORD:8:PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT:PSA_ALG_JPAKE:PSA_ALG_NONE:"4c":"505341004b455900000000000100000003120800014000000001000a00000000010000004c" + # Create a persistent key which is larger than MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE # so that when psa_get_key_attributes() tries to load it from the storage it will fail. PSA storage read: key larger than MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE From 84a9b26b88c81ec5abc3f7e156acdbcca2664f08 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 9 Oct 2025 12:49:01 +0200 Subject: [PATCH 3/3] Be more precise about the user/peer ID limitation Signed-off-by: Gilles Peskine --- include/psa/crypto_extra.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 7ec110a20c..a710397a77 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -767,7 +767,8 @@ int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg); * - The only supported hash algorithm is SHA-256, i.e. * `PSA_ALG_SHA_256`. * - When using the built-in implementation, the user ID and the peer ID - * must be `"client"` (6-byte string) or `"server"` (6-byte string). + * must be `"client"` (6-byte string) and `"server"` (6-byte string), + * or the other way round. * Third-party drivers may or may not have this limitation. * */