File crypto_struct.h

PSA cryptography module: Mbed TLS structured type implementations.

This file contains the definitions of some data structures with implementation-specific definitions.

In implementations with isolation between the application and the cryptography module, it is expected that the front-end and the back-end would have different versions of this file.

Design notes about multipart operation structures

For multipart operations without driver delegation support, each multipart operation structure contains a psa_algorithm_t alg field which indicates which specific algorithm the structure is for. When the structure is not in use, alg is 0. Most of the structure consists of a union which is discriminated by alg.

For multipart operations with driver delegation support, each multipart operation structure contains an unsigned int id field indicating which driver got assigned to do the operation. When the structure is not in use, ‘id’ is 0. The structure contains also a driver context which is the union of the contexts of all drivers able to handle the type of multipart operation.

Note that when alg or id is 0, the content of other fields is undefined. In particular, it is not guaranteed that a freshly-initialized structure is all-zero: we initialize structures to something like {0, 0}, which is only guaranteed to initializes the first member of the union; GCC and Clang initialize the whole structure to 0 (at the time of writing), but MSVC and CompCert don’t.

In Mbed TLS, multipart operation structures live independently from the key. This allows Mbed TLS to free the key objects when destroying a key slot. If a multipart operation needs to remember the key after the setup function returns, the operation structure needs to contain a copy of the key.

Note

This file may not be included directly. Applications must include psa/crypto.h.

Defines

PSA_HASH_OPERATION_INIT: This macro returns a suitable initializer for a hash operation object of type psa_hash_operation_t.

PSA_CIPHER_OPERATION_INIT: This macro returns a suitable initializer for a cipher operation object of type psa_cipher_operation_t.

PSA_MAC_OPERATION_INIT: This macro returns a suitable initializer for a MAC operation object of type psa_mac_operation_t.

PSA_AEAD_OPERATION_INIT: This macro returns a suitable initializer for an AEAD operation object of type psa_aead_operation_t.

PSA_KEY_DERIVATION_OPERATION_INIT: This macro returns a suitable initializer for a key derivation operation object of type psa_key_derivation_operation_t.

PSA_KEY_POLICY_INIT

PSA_KEY_BITS_TOO_LARGE

PSA_MAX_KEY_BITS

MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER

MBEDTLS_PSA_KA_MASK_EXTERNAL_ONLY

MBEDTLS_PSA_KA_MASK_DUAL_USE

PSA_CORE_KEY_ATTRIBUTES_INIT

PSA_KEY_ATTRIBUTES_INIT: This macro returns a suitable initializer for a key attribute structure of type psa_key_attributes_t.

Typedefs

typedef struct psa_tls12_prf_key_derivation_s psa_tls12_prf_key_derivation_t

typedef struct psa_key_policy_s psa_key_policy_t

typedef uint16_t psa_key_bits_t

typedef uint16_t psa_key_attributes_flag_t

A mask of flags that can be stored in key attributes.

This type is also used internally to store flags in slots. Internal flags are defined in library/psa_crypto_core.h. Internal flags may have the same value as external flags if they are properly handled during key creation and in psa_get_key_attributes.

Enums

enum psa_tls12_prf_key_derivation_state_t

Values:

enumerator PSA_TLS12_PRF_STATE_INIT

enumerator PSA_TLS12_PRF_STATE_SEED_SET

enumerator PSA_TLS12_PRF_STATE_KEY_SET

enumerator PSA_TLS12_PRF_STATE_LABEL_SET

enumerator PSA_TLS12_PRF_STATE_OUTPUT

Functions

static inline struct psa_hash_operation_s psa_hash_operation_init(void)

static inline struct psa_cipher_operation_s psa_cipher_operation_init(void)

static inline struct psa_mac_operation_s psa_mac_operation_init(void)

static inline struct psa_aead_operation_s psa_aead_operation_init(void)

static inline struct psa_key_derivation_s psa_key_derivation_operation_init(void)

static inline struct psa_key_policy_s psa_key_policy_init(void)

static inline struct psa_key_attributes_s psa_key_attributes_init(void)

static inline void psa_set_key_id(psa_key_attributes_t *attributes, mbedtls_svc_key_id_t key)

static inline mbedtls_svc_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)

static inline void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes, mbedtls_key_owner_id_t owner)

static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)

static inline psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes)

static inline void psa_extend_key_usage_flags(psa_key_usage_t *usage_flags)

static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)

static inline psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)

static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)

static inline psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes)

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)

static inline void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type)

static inline psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes)

static inline void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)

static inline size_t psa_get_key_bits(const psa_key_attributes_t *attributes)

struct psa_hash_operation_s

#include <crypto_struct.h>

Public Members

unsigned int id: Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_driver_wrappers.h. ID value zero means the context is not valid or not assigned to any driver (i.e. the driver context is not active, in use).

psa_driver_hash_context_t ctx

struct psa_cipher_operation_s

#include <crypto_struct.h>

Public Members

unsigned int id: Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).

unsigned int iv_required

unsigned int iv_set

uint8_t default_iv_length

psa_driver_cipher_context_t ctx

struct psa_mac_operation_s

#include <crypto_struct.h>

Public Members

unsigned int id: Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).