psa_crypto_se_driver.h File Reference

PSA external cryptoprocessor driver module. More...

Detailed Description

PSA external cryptoprocessor driver module.

This header declares types and function signatures for cryptography drivers that access key material via opaque references. This is meant for cryptoprocessors that have a separate key storage from the space in which the PSA Crypto implementation runs, typically secure elements (SEs).

This file is part of the PSA Crypto Driver HAL (hardware abstraction layer), containing functions for driver developers to implement to enable hardware to be called in a standardized way by a PSA Cryptography API implementation. The functions comprising the driver HAL, which driver authors implement, are not intended to be called by application developers.

Definition in file psa_crypto_se_driver.h.

#include <stdint.h>
#include <stdlib.h>
#include "psa/crypto_values.h"
#include "psa/crypto_types.h"

Include dependency graph for psa_crypto_se_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	psa_drv_se_context_t
	Driver context structure. More...
struct	psa_drv_se_mac_t
	A struct containing all of the function pointers needed to perform secure element MAC operations. More...
struct	psa_drv_se_cipher_t
	A struct containing all of the function pointers needed to implement cipher operations using secure elements. More...
struct	psa_drv_se_asymmetric_t
	A struct containing all of the function pointers needed to implement asymmetric cryptographic operations using secure elements. More...
struct	psa_drv_se_aead_t
	A struct containing all of the function pointers needed to implement secure element Authenticated Encryption with Additional Data operations. More...
struct	psa_drv_se_key_management_t
	A struct containing all of the function pointers needed to for secure element key management. More...
struct	psa_drv_se_key_derivation_t
	A struct containing all of the function pointers needed to for secure element key derivation and agreement. More...
struct	psa_drv_se_t
	A structure containing pointers to all the entry points of a secure element driver. More...

Macros
#define	PSA_MAX_PERSISTENT_DATA_SIZE   (16)
	Maximum size of persistent driver data in bytes.
#define	PSA_DRV_SE_HAL_VERSION   0x00000005
	The current version of the secure element driver HAL.

Typedefs
typedef psa_status_t(*	psa_drv_se_init_t) (psa_drv_se_context_t *drv_context, void *persistent_data, psa_key_location_t location)
	A driver initialization function.
typedef uint64_t	psa_key_slot_number_t
	Encoding of a key slot number on a secure element.
typedef psa_status_t(*	psa_drv_se_mac_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm)
	A function that starts a secure element MAC operation for a PSA Crypto Driver implementation.
typedef psa_status_t(*	psa_drv_se_mac_update_t) (void *op_context, const uint8_t *p_input, size_t input_length)
	A function that continues a previously started secure element MAC operation.
typedef psa_status_t(*	psa_drv_se_mac_finish_t) (void *op_context, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)
	A function that completes a previously started secure element MAC operation by returning the resulting MAC.
typedef psa_status_t(*	psa_drv_se_mac_finish_verify_t) (void *op_context, const uint8_t *p_mac, size_t mac_length)
	A function that completes a previously started secure element MAC operation by comparing the resulting MAC against a provided value.
typedef psa_status_t(*	psa_drv_se_mac_abort_t) (void *op_context)
	A function that aborts a previous started secure element MAC operation.
typedef psa_status_t(*	psa_drv_se_mac_generate_t) (psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)
	A function that performs a secure element MAC operation in one command and returns the calculated MAC.
typedef psa_status_t(*	psa_drv_se_mac_verify_t) (psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length)
	A function that performs a secure element MAC operation in one command and compares the resulting MAC against a provided value.
typedef psa_status_t(*	psa_drv_se_cipher_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction)
	A function that provides the cipher setup function for a secure element driver.
typedef psa_status_t(*	psa_drv_se_cipher_set_iv_t) (void *op_context, const uint8_t *p_iv, size_t iv_length)
	A function that sets the initialization vector (if necessary) for an secure element cipher operation.
typedef psa_status_t(*	psa_drv_se_cipher_update_t) (void *op_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length)
	A function that continues a previously started secure element cipher operation.
typedef psa_status_t(*	psa_drv_se_cipher_finish_t) (void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
	A function that completes a previously started secure element cipher operation.
typedef psa_status_t(*	psa_drv_se_cipher_abort_t) (void *op_context)
	A function that aborts a previously started secure element cipher operation.
typedef psa_status_t(*	psa_drv_se_cipher_ecb_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size)
	A function that performs the ECB block mode for secure element cipher operations.
typedef psa_status_t(*	psa_drv_se_asymmetric_sign_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_hash, size_t hash_length, uint8_t *p_signature, size_t signature_size, size_t *p_signature_length)
	A function that signs a hash or short message with a private key in a secure element.
typedef psa_status_t(*	psa_drv_se_asymmetric_verify_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_hash, size_t hash_length, const uint8_t *p_signature, size_t signature_length)
	A function that verifies the signature a hash or short message using an asymmetric public key in a secure element.
typedef psa_status_t(*	psa_drv_se_asymmetric_encrypt_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
	A function that encrypts a short message with an asymmetric public key in a secure element.
typedef psa_status_t(*	psa_drv_se_asymmetric_decrypt_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
	A function that decrypts a short message with an asymmetric private key in a secure element.
typedef psa_status_t(*	psa_drv_se_aead_encrypt_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, const uint8_t *p_additional_data, size_t additional_data_length, const uint8_t *p_plaintext, size_t plaintext_length, uint8_t *p_ciphertext, size_t ciphertext_size, size_t *p_ciphertext_length)
	A function that performs a secure element authenticated encryption operation.
typedef psa_status_t(*	psa_drv_se_aead_decrypt_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, const uint8_t *p_additional_data, size_t additional_data_length, const uint8_t *p_ciphertext, size_t ciphertext_length, uint8_t *p_plaintext, size_t plaintext_size, size_t *p_plaintext_length)
	A function that performs a secure element authenticated decryption operation.
typedef psa_status_t(*	psa_drv_se_allocate_key_t) (psa_drv_se_context_t *drv_context, void *persistent_data, const psa_key_attributes_t *attributes, psa_key_creation_method_t method, psa_key_slot_number_t *key_slot)
	A function that allocates a slot for a key.
typedef psa_status_t(*	psa_drv_se_validate_slot_number_t) (psa_drv_se_context_t *drv_context, void *persistent_data, const psa_key_attributes_t *attributes, psa_key_creation_method_t method, psa_key_slot_number_t key_slot)
	A function that determines whether a slot number is valid for a key.
typedef psa_status_t(*	psa_drv_se_import_key_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, size_t *bits)
	A function that imports a key into a secure element in binary format.
typedef psa_status_t(*	psa_drv_se_destroy_key_t) (psa_drv_se_context_t *drv_context, void *persistent_data, psa_key_slot_number_t key_slot)
	A function that destroys a secure element key and restore the slot to its default state.
typedef psa_status_t(*	psa_drv_se_export_key_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, uint8_t *p_data, size_t data_size, size_t *p_data_length)
	A function that exports a secure element key in binary format.
typedef psa_status_t(*	psa_drv_se_generate_key_t) (psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, const psa_key_attributes_t *attributes, uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length)
	A function that generates a symmetric or asymmetric key on a secure element.
typedef psa_status_t(*	psa_drv_se_key_derivation_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_algorithm_t kdf_alg, psa_key_slot_number_t source_key)
	A function that Sets up a secure element key derivation operation by specifying the algorithm and the source key sot.
typedef psa_status_t(*	psa_drv_se_key_derivation_collateral_t) (void *op_context, uint32_t collateral_id, const uint8_t *p_collateral, size_t collateral_size)
	A function that provides collateral (parameters) needed for a secure element key derivation or key agreement operation.
typedef psa_status_t(*	psa_drv_se_key_derivation_derive_t) (void *op_context, psa_key_slot_number_t dest_key)
	A function that performs the final secure element key derivation step and place the generated key material in a slot.
typedef psa_status_t(*	psa_drv_se_key_derivation_export_t) (void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
	A function that performs the final step of a secure element key agreement and place the generated key material in a buffer.

Enumerations
enum	psa_key_creation_method_t { PSA_KEY_CREATION_IMPORT , PSA_KEY_CREATION_GENERATE , PSA_KEY_CREATION_DERIVE , PSA_KEY_CREATION_COPY }
	An enumeration indicating how a key is created. More...