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_CUSTOM_KEY_PARAMETERS_INIT

The default production parameters for key generation or key derivation.

Calling psa_generate_key_custom() or psa_key_derivation_output_key_custom() with custom=PSA_CUSTOM_KEY_PARAMETERS_INIT and custom_data_length=0 is equivalent to calling psa_generate_key() or psa_key_derivation_output_key() respectively.

PSA_KEY_POLICY_INIT

PSA_KEY_BITS_TOO_LARGE

PSA_MAX_KEY_BITS

PSA_KEY_ATTRIBUTES_INIT

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

PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT

PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT

PSA_KEY_AGREEMENT_IOP_INIT

PSA_GENERATE_KEY_IOP_INIT

PSA_EXPORT_PUBLIC_KEY_IOP_INIT

Typedefs

typedef struct psa_key_policy_s psa_key_policy_t

typedef uint16_t psa_key_bits_t

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)

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)

static inline struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_init(void)

static inline struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_init(void)

static inline struct psa_key_agreement_iop_s psa_key_agreement_iop_init(void)

static inline struct psa_generate_key_iop_s psa_generate_key_iop_init(void)

static inline struct psa_export_public_key_iop_s psa_export_public_key_iop_init(void)

struct psa_hash_operation_s

#include <crypto_struct.h>

Public Members

unsigned int private_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 private_ctx

struct psa_cipher_operation_s

#include <crypto_struct.h>

Public Members

unsigned int private_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 private_iv_required

unsigned int private_iv_set

uint8_t private_default_iv_length

psa_driver_cipher_context_t private_ctx

struct psa_mac_operation_s

#include <crypto_struct.h>

Public Members

unsigned int private_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).

uint8_t private_mac_size

unsigned int private_is_sign

psa_driver_mac_context_t private_ctx

struct psa_aead_operation_s

#include <crypto_struct.h>

Public Members

unsigned int private_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).

psa_algorithm_t private_alg

psa_key_type_t private_key_type

size_t private_ad_remaining

size_t private_body_remaining

unsigned int private_nonce_set

unsigned int private_lengths_set

unsigned int private_ad_started

unsigned int private_body_started

unsigned int private_is_encrypt

psa_driver_aead_context_t private_ctx

struct psa_key_derivation_s

#include <crypto_struct.h>

Public Members

psa_algorithm_t private_alg

unsigned int private_can_output_key

size_t private_capacity

psa_driver_key_derivation_context_t private_ctx

struct psa_custom_key_parameters_s

#include <crypto_struct.h>

Public Members

uint32_t flags

struct psa_key_policy_s

#include <crypto_struct.h>

Public Members

psa_key_usage_t private_usage

psa_algorithm_t private_alg

psa_algorithm_t private_alg2

struct psa_key_attributes_s

#include <crypto_struct.h>

Public Members

psa_key_type_t private_type

psa_key_bits_t private_bits

psa_key_lifetime_t private_lifetime

psa_key_policy_t private_policy

mbedtls_svc_key_id_t private_id

struct psa_sign_hash_interruptible_operation_s

#include <crypto_struct.h>

The context for PSA interruptible hash signing.

Public Members

unsigned int private_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).

psa_driver_sign_hash_interruptible_context_t private_ctx

unsigned int private_error_occurred

uint32_t private_num_ops

struct psa_verify_hash_interruptible_operation_s

#include <crypto_struct.h>

The context for PSA interruptible hash verification.

Public Members

unsigned int private_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).

psa_driver_verify_hash_interruptible_context_t private_ctx

unsigned int private_error_occurred

uint32_t private_num_ops

struct psa_key_agreement_iop_s

#include <crypto_struct.h>

The context for PSA interruptible key agreement.

Public Members

unsigned int private_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).

mbedtls_psa_key_agreement_interruptible_operation_t private_mbedtls_ctx

uint32_t private_num_ops

psa_key_attributes_t private_attributes

unsigned int private_error_occurred

struct psa_generate_key_iop_s

#include <crypto_struct.h>

The context for PSA interruptible key generation.

Public Members

unsigned int private_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).

mbedtls_psa_generate_key_iop_t private_ctx

psa_key_attributes_t private_attributes

unsigned int private_error_occurred

uint32_t private_num_ops

struct psa_export_public_key_iop_s

#include <crypto_struct.h>

The context for PSA interruptible export public-key.

Public Members

unsigned int private_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).

mbedtls_psa_export_public_key_iop_t private_ctx

unsigned int private_error_occurred

uint32_t private_num_ops