Key attributes

Description

Functions

psa_status_t psa_get_key_attributes (mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)
Retrieve the attributes of a key.
void psa_reset_key_attributes (psa_key_attributes_t *attributes)
Reset a key attribute structure to a freshly initialized state.
psa_status_t psa_set_key_domain_parameters (psa_key_attributes_t *attributes, psa_key_type_t type, const uint8_t *data, size_t data_length)
Set domain parameters for a key.
psa_status_t psa_get_key_domain_parameters (const psa_key_attributes_t *attributes, uint8_t *data, size_t data_size, size_t *data_length)
Get domain parameters for a key.

Macros

#define PSA_KEY_ATTRIBUTES_INIT { PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0 }
#define PSA_DH_FAMILY_CUSTOM (( psa_dh_family_t ) 0x7e)
Custom Diffie-Hellman group.
#define PSA_KEY_DOMAIN_PARAMETERS_SIZE (key_type, key_bits)
Safe output buffer size for psa_get_key_domain_parameters() .
#define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE (key_bits)   (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
#define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE (key_bits)   (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)

Function Documentation

◆ psa_get_key_attributes()

psa_status_t psa_get_key_attributes ( mbedtls_svc_key_id_t key,
psa_key_attributes_t * attributes
)

Retrieve the attributes of a key.

This function first resets the attribute structure as with psa_reset_key_attributes() . It then copies the attributes of the given key into the given attribute structure.

Note
This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call psa_reset_key_attributes() to free these resources.
Parameters
[in] key Identifier of the key to query.
[in,out] attributes On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init() . It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_reset_key_attributes()

void psa_reset_key_attributes ( psa_key_attributes_t * attributes )

Reset a key attribute structure to a freshly initialized state.

You must initialize the attribute structure as described in the documentation of the type #psa_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time.

This function frees any auxiliary resources that the structure may contain.

Parameters
[in,out] attributes The attribute structure to reset.

◆ psa_set_key_domain_parameters()

psa_status_t psa_set_key_domain_parameters ( psa_key_attributes_t * attributes,
psa_key_type_t type,
const uint8_t * data,
size_t data_length
)

Set domain parameters for a key.

Some key types require additional domain parameters in addition to the key type identifier and the key size. Use this function instead of psa_set_key_type() when you need to specify domain parameters.

The format for the required domain parameters varies based on the key type.

  • For RSA keys ( PSA_KEY_TYPE_RSA_PUBLIC_KEY or PSA_KEY_TYPE_RSA_KEY_PAIR ), the domain parameter data consists of the public exponent, represented as a big-endian integer with no leading zeros. This information is used when generating an RSA key pair. When importing a key, the public exponent is read from the imported key data and the exponent recorded in the attribute structure is ignored. As an exception, the public exponent 65537 is represented by an empty byte string.
  • For DSA keys ( PSA_KEY_TYPE_DSA_PUBLIC_KEY or PSA_KEY_TYPE_DSA_KEY_PAIR ), the Dss-Parms format as defined by RFC 3279 §2.3.2.
    Dss-Parms ::= SEQUENCE {
    p INTEGER,
    q INTEGER,
    g INTEGER
    }
  • For Diffie-Hellman key exchange keys ( PSA_KEY_TYPE_DH_PUBLIC_KEY ( PSA_DH_FAMILY_CUSTOM ) or PSA_KEY_TYPE_DH_KEY_PAIR ( PSA_DH_FAMILY_CUSTOM )), the DomainParameters format as defined by RFC 3279 §2.3.3.
    DomainParameters ::= SEQUENCE {
    p INTEGER, -- odd prime, p=jq +1
    g INTEGER, -- generator, g
    q INTEGER, -- factor of p-1
    j INTEGER OPTIONAL, -- subgroup factor
    validationParms ValidationParms OPTIONAL
    }
    ValidationParms ::= SEQUENCE {
    seed BIT STRING,
    pgenCounter INTEGER
    }
Note
This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call psa_reset_key_attributes() to free these resources.
This is an experimental extension to the interface. It may change in future versions of the library.
Parameters
[in,out] attributes Attribute structure where the specified domain parameters will be stored. If this function fails, the content of attributes is not modified.
type Key type (a PSA_KEY_TYPE_XXX value).
[in] data Buffer containing the key domain parameters. The content of this buffer is interpreted according to type as described above.
data_length Size of the data buffer in bytes.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INSUFFICIENT_MEMORY

◆ psa_get_key_domain_parameters()

psa_status_t psa_get_key_domain_parameters ( const psa_key_attributes_t * attributes,
uint8_t * data,
size_t data_size,
size_t * data_length
)

Get domain parameters for a key.

Get the domain parameters for a key with this function, if any. The format of the domain parameters written to data is specified in the documentation for psa_set_key_domain_parameters() .

Note
This is an experimental extension to the interface. It may change in future versions of the library.
Parameters
[in] attributes The key attribute structure to query.
[out] data On success, the key domain parameters.
data_size Size of the data buffer in bytes. The buffer is guaranteed to be large enough if its size in bytes is at least the value given by PSA_KEY_DOMAIN_PARAMETERS_SIZE() .
[out] data_length On success, the number of bytes that make up the key domain parameters data.
Return values
PSA_SUCCESS
PSA_ERROR_BUFFER_TOO_SMALL

Macro Definition Documentation

◆ PSA_KEY_ATTRIBUTES_INIT

#define PSA_KEY_ATTRIBUTES_INIT   { PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0 }

This macro returns a suitable initializer for a key attribute structure of type #psa_key_attributes_t.

◆ PSA_DH_FAMILY_CUSTOM

#define PSA_DH_FAMILY_CUSTOM   (( psa_dh_family_t ) 0x7e)

Custom Diffie-Hellman group.

For keys of type PSA_KEY_TYPE_DH_PUBLIC_KEY ( PSA_DH_FAMILY_CUSTOM ) or PSA_KEY_TYPE_DH_KEY_PAIR ( PSA_DH_FAMILY_CUSTOM ), the group data comes from domain parameters set by psa_set_key_domain_parameters() .

◆ PSA_KEY_DOMAIN_PARAMETERS_SIZE

#define PSA_KEY_DOMAIN_PARAMETERS_SIZE ( key_type,
key_bits
)
Value:
( PSA_KEY_TYPE_IS_RSA (key_type) ? sizeof (int) : \
PSA_KEY_TYPE_IS_DH (key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
PSA_KEY_TYPE_IS_DSA (key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
0)

Safe output buffer size for psa_get_key_domain_parameters() .

This macro returns a compile-time constant if its arguments are compile-time constants.

Warning
This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
Note
This is an experimental extension to the interface. It may change in future versions of the library.
Parameters
key_type A supported key type.
key_bits The size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_get_key_domain_parameters() will not fail with PSA_ERROR_BUFFER_TOO_SMALL . If the parameters are a valid combination that is not supported by the implementation, this macro shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.