Merge pull request #10444 from gilles-peskine-arm/jpake-persistent-key-compat-3.6.5

Backport 3.6: PSA JPAKE: add storage test case and document limitations

Author: minosgalanakis

include/psa/crypto_extra.h

@@ -760,6 +760,17 @@ 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) and `"server"` (6-byte string),
+ *         or the other way round.
+ *         Third-party drivers may or may not have this limitation.
+ *
  */
 #define PSA_ALG_JPAKE                   ((psa_algorithm_t) 0x0a000100)
 
@@ -1196,6 +1207,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 +1232,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 +1572,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 +1617,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

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