Function esp_idf_svc::sys::mbedtls_pk_get_psa_attributes

pub unsafe extern "C" fn mbedtls_pk_get_psa_attributes(
    pk: *const mbedtls_pk_context,
    usage: u32,
    attributes: *mut psa_key_attributes_s,
) -> i32

\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 policy 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 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 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 primary algorithm set for the underlying PSA key, except that sign/decrypt flags are removed if the type is set to a public key type. The underlying key must allow \p usage. 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.