Introduce mbedtls_pk_get_psa_attributes
Follow the specification in https://github.com/Mbed-TLS/mbedtls/pull/8657
as of dd77343381161e09a63b4694001da3957e27d3a7, i.e.
https://github.com/Mbed-TLS/mbedtls/blob/dd77343381161e09a63b4694001da3957e27d3a7/docs/architecture/psa-migration/psa-legacy-bridges.md#api-to-create-a-psa-key-from-a-pk-context
This commit introduces the function declaration, its documentation, the
definition without the interesting parts and a negative unit test function.
Subsequent commits will add RSA, ECC and PK_OPAQUE support.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 27768bd..a43b949 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -28,7 +28,7 @@
#include "mbedtls/ecdsa.h"
#endif
-#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)
#include "psa/crypto.h"
#endif
@@ -484,6 +484,120 @@
psa_key_usage_t usage);
#endif /* MBEDTLS_USE_PSA_CRYPTO */
+#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)
+/**
+ * \brief Determine valid PSA attributes that can be used to
+ * import a key into PSA.
+ *
+ * The attributes determined by this function are suitable
+ * for calling mbedtls_pk_import_into_psa() to create
+ * a PSA key with the same key material.
+ *
+ * The typical flow of operations involving this function is
+ * ```
+ * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
+ * int ret = mbedtls_pk_get_psa_attributes(pk, &attributes);
+ * if (ret != 0) ...; // error handling omitted
+ * // Tweak attributes if desired
+ * psa_key_id_t key_id = 0;
+ * ret = mbedtls_pk_import_into_psa(pk, &attributes, &key_id);
+ * if (ret != 0) ...; // error handling omitted
+ * ```
+ *
+ * \note This function does not support RSA-alt contexts
+ * (set up with mbedtls_pk_setup_rsa_alt()).
+ *
+ * \param[in] pk The PK context to use. It must have been set up.
+ * It can either contain a key pair or just a public key.
+ * \param usage A single `PSA_KEY_USAGE_xxx` flag among the following:
+ * - #PSA_KEY_USAGE_DECRYPT: \p pk must contain a
+ * key pair. The output \p attributes will contain a
+ * key pair type, and the usage policy will allow
+ * #PSA_KEY_USAGE_ENCRYPT as well as
+ * #PSA_KEY_USAGE_DECRYPT.
+ * - #PSA_KEY_USAGE_DERIVE: \p pk must contain a
+ * key pair. The output \p attributes will contain a
+ * key pair type.
+ * - #PSA_KEY_USAGE_ENCRYPT: The output
+ * \p attributes will contain a public key type.
+ * - #PSA_KEY_USAGE_SIGN_HASH: \p pk must contain a
+ * key pair. The output \p attributes will contain a
+ * key pair type, and the usage policy will allow
+ * #PSA_KEY_USAGE_VERIFY_HASH as well as
+ * #PSA_KEY_USAGE_SIGN_HASH.
+ * - #PSA_KEY_USAGE_SIGN_MESSAGE: \p pk must contain a
+ * key pair. The output \p attributes will contain a
+ * key pair type, and the usage policy will allow
+ * #PSA_KEY_USAGE_VERIFY_MESSAGE as well as
+ * #PSA_KEY_USAGE_SIGN_MESSAGE.
+ * - #PSA_KEY_USAGE_VERIFY_HASH: The output
+ * \p attributes will contain a public key type.
+ * - #PSA_KEY_USAGE_VERIFY_MESSAGE: The output
+ * \p attributes will contain a public key type.
+ * \param[out] attributes
+ * On success, valid attributes to import the key into PSA.
+ * - The lifetime and key identifier are unchanged. If the
+ * attribute structure was initialized or reset before
+ * calling this function, this will result in a volatile
+ * key. Call psa_set_key_identifier() before or after this
+ * function if you wish to create a persistent key. Call
+ * psa_set_key_lifetime() before or after this function if
+ * you wish to import the key in a secure element.
+ * - The key type and bit-size are determined by the contents
+ * of the PK context. If the PK context contains a key
+ * pair, the key type can be either a key pair type or
+ * the corresponding public key type, depending on
+ * \p usage. If the PK context contains a public key,
+ * the key type is a public key type.
+ * - The key's policy is determined by the key type and
+ * the \p usage parameter. The usage always allows
+ * \p usage, exporting and copying the key, and
+ * possibly other permissions as documented for the
+ * \p usage parameter.
+ * The permitted algorithm is determined as follows
+ * based on the #mbedtls_pk_type_t type of \p pk,
+ * the chosen \p usage and other factors:
+ * - #MBEDTLS_PK_RSA with whose underlying
+ * #mbedtls_rsa_context has the padding mode
+ * #MBEDTLS_RSA_PKCS_V15:
+ * #PSA_ALG_RSA_PKCS1V15_SIGN(#PSA_ALG_ANY_HASH)
+ * if \p usage is SIGN/VERIFY, and
+ * #PSA_ALG_RSA_PKCS1V15_CRYPT
+ * if \p usage is ENCRYPT/DECRYPT.
+ * - #MBEDTLS_PK_RSA with whose underlying
+ * #mbedtls_rsa_context has the padding mode
+ * #MBEDTLS_RSA_PKCS_V21 and the digest type
+ * corresponding to the PSA algorithm \c hash:
+ * #PSA_ALG_RSA_PSS_ANY_SALT(#PSA_ALG_ANY_HASH)
+ * if \p usage is SIGN/VERIFY, and
+ * #PSA_ALG_RSA_OAEP(\c hash)
+ * if \p usage is ENCRYPT/DECRYPT.
+ * - #MBEDTLS_PK_RSA_ALT: not supported.
+ * - #MBEDTLS_PK_ECDSA or #MBEDTLS_PK_ECKEY
+ * if \p usage is SIGN/VERIFY:
+ * #PSA_ALG_DETERMINISTIC_ECDSA(#PSA_ALG_ANY_HASH)
+ * if #MBEDTLS_ECDSA_DETERMINISTIC is enabled,
+ * otherwise #PSA_ALG_ECDSA(#PSA_ALG_ANY_HASH).
+ * - #MBEDTLS_PK_ECKEY_DH or #MBEDTLS_PK_ECKEY
+ * if \p usage is DERIVE:
+ * #PSA_ALG_ECDH.
+ * - #MBEDTLS_PK_OPAQUE: same as the algorithm policy
+ * set for the underlying PSA key, except that
+ * sign/decrypt flags are removed if the type is
+ * set to a public key type.
+ * Note that the enrollment algorithm set with
+ * psa_set_key_enrollment_algorithm() is not copied.
+ *
+ * \return 0 on success.
+ * #MBEDTLS_ERR_PK_TYPE_MISMATCH if \p pk does not contain
+ * a key of the type identified in \p attributes.
+ * Another error code on other failures.
+ */
+int mbedtls_pk_get_psa_attributes(const mbedtls_pk_context *pk,
+ psa_key_usage_t usage,
+ psa_key_attributes_t *attributes);
+#endif /* MBEDTLS_PSA_CRYPTO_CLIENT */
+
/**
* \brief Verify signature (including padding if relevant).
*