From 05ee3fbdc013e99de876e4740a6d34eaf025759e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 7 Feb 2024 18:58:10 +0100 Subject: [PATCH] mbedtls_pk_import_into_psa: documentation Signed-off-by: Gilles Peskine --- ChangeLog.d/mbedtls_pk_import_into_psa.txt | 4 ++ include/mbedtls/pk.h | 48 ++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 ChangeLog.d/mbedtls_pk_import_into_psa.txt diff --git a/ChangeLog.d/mbedtls_pk_import_into_psa.txt b/ChangeLog.d/mbedtls_pk_import_into_psa.txt new file mode 100644 index 0000000000..c294f4490d --- /dev/null +++ b/ChangeLog.d/mbedtls_pk_import_into_psa.txt @@ -0,0 +1,4 @@ +Features + * The new functions mbedtls_pk_get_psa_attributes() and + mbedtls_pk_import_into_psa() provide a uniform way to create a PSA + key from a PK key. diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 66f39015fa..b5d65e39aa 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -599,6 +599,54 @@ int mbedtls_pk_can_do_ext(const mbedtls_pk_context *ctx, psa_algorithm_t alg, int mbedtls_pk_get_psa_attributes(const mbedtls_pk_context *pk, psa_key_usage_t usage, psa_key_attributes_t *attributes); + +/** + * \brief Import a key into the PSA key store. + * + * This function is equivalent to calling psa_import_key() + * with the key material from \p pk. + * + * The typical way to use this function is: + * -# Call mbedtls_pk_get_psa_attributes() to obtain + * attributes for the given key. + * -# If desired, modify the attributes, for example: + * - To create a persistent key, call + * psa_set_key_identifier() and optionally + * psa_set_key_lifetime(). + * - To import only the public part of a key pair: + * ``` + * psa_set_key_type(&attributes, + * PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR( + * psa_get_key_type(&attributes))); + * ``` + * - Restrict the key usage if desired. + * -# Call mbedtls_pk_import_into_psa(). + * + * \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[in] attributes + * The attributes to use for the new key. They must be + * compatible with \p pk. In particular, the key type + * must match the content of \p pk. + * If \p pk contains a key pair, the key type in + * attributes can be either the key pair type or the + * corresponding public key type (to import only the + * public part). + * \param[out] key_id + * On success, the identifier of the newly created key. + * On error, this is #MBEDTLS_SVC_KEY_ID_INIT. + * + * \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_import_into_psa(const mbedtls_pk_context *pk, + const psa_key_attributes_t *attributes, + mbedtls_svc_key_id_t *key_id); #endif /* MBEDTLS_PSA_CRYPTO_C */ /**