From 8ca2a5bf9502431e29d7338a3516bde53b8aa23d Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 8 Oct 2025 17:36:22 +0200
Subject: [PATCH] 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 <Gilles.Peskine@arm.com>
---
 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