Loading...
Searching...
No Matches
psa_crypto_se_driver.h
Go to the documentation of this file.
1/*
2 * Copyright The Mbed TLS Contributors
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License"); you may
6 * not use this file except in compliance with the License.
7 *
8 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
39#ifndef PSA_CRYPTO_SE_DRIVER_H
40#define PSA_CRYPTO_SE_DRIVER_H
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46#include <stdint.h>
47#include <stdlib.h>
48
49#include "psa/crypto_values.h"
50#include "psa/crypto_types.h"
51
55#define PSA_MAX_PERSISTENT_DATA_SIZE (16)
56
71typedef struct {
116 const void * persistent_data;
117
125
132 uintptr_t transient_data;
134
153 void *persistent_data,
154 psa_key_location_t location);
155
159typedef uint64_t psa_key_slot_number_t;
198 void *op_context,
199 psa_key_slot_number_t key_slot,
200 psa_algorithm_t algorithm);
201
213typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context,
214 const uint8_t *p_input,
215 size_t input_length);
216
233typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
234 uint8_t *p_mac,
235 size_t mac_size,
236 size_t *p_mac_length);
237
254 const uint8_t *p_mac,
255 size_t mac_length);
256
263typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context);
264
284 const uint8_t *p_input,
285 size_t input_length,
286 psa_key_slot_number_t key_slot,
287 psa_algorithm_t alg,
288 uint8_t *p_mac,
289 size_t mac_size,
290 size_t *p_mac_length);
291
312 const uint8_t *p_input,
313 size_t input_length,
314 psa_key_slot_number_t key_slot,
315 psa_algorithm_t alg,
316 const uint8_t *p_mac,
317 size_t mac_length);
318
397 void *op_context,
398 psa_key_slot_number_t key_slot,
399 psa_algorithm_t algorithm,
400 psa_encrypt_or_decrypt_t direction);
401
418typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
419 const uint8_t *p_iv,
420 size_t iv_length);
421
441typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
442 const uint8_t *p_input,
443 size_t input_size,
444 uint8_t *p_output,
445 size_t output_size,
446 size_t *p_output_length);
447
463typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
464 uint8_t *p_output,
465 size_t output_size,
466 size_t *p_output_length);
467
475typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context);
476
502 psa_key_slot_number_t key_slot,
503 psa_algorithm_t algorithm,
504 psa_encrypt_or_decrypt_t direction,
505 const uint8_t *p_input,
506 size_t input_size,
507 uint8_t *p_output,
508 size_t output_size);
509
540
570 psa_key_slot_number_t key_slot,
571 psa_algorithm_t alg,
572 const uint8_t *p_hash,
573 size_t hash_length,
574 uint8_t *p_signature,
575 size_t signature_size,
576 size_t *p_signature_length);
577
595 psa_key_slot_number_t key_slot,
596 psa_algorithm_t alg,
597 const uint8_t *p_hash,
598 size_t hash_length,
599 const uint8_t *p_signature,
600 size_t signature_length);
601
632 psa_key_slot_number_t key_slot,
633 psa_algorithm_t alg,
634 const uint8_t *p_input,
635 size_t input_length,
636 const uint8_t *p_salt,
637 size_t salt_length,
638 uint8_t *p_output,
639 size_t output_size,
640 size_t *p_output_length);
641
672 psa_key_slot_number_t key_slot,
673 psa_algorithm_t alg,
674 const uint8_t *p_input,
675 size_t input_length,
676 const uint8_t *p_salt,
677 size_t salt_length,
678 uint8_t *p_output,
679 size_t output_size,
680 size_t *p_output_length);
681
701
746 psa_key_slot_number_t key_slot,
747 psa_algorithm_t algorithm,
748 const uint8_t *p_nonce,
749 size_t nonce_length,
750 const uint8_t *p_additional_data,
751 size_t additional_data_length,
752 const uint8_t *p_plaintext,
753 size_t plaintext_length,
754 uint8_t *p_ciphertext,
755 size_t ciphertext_size,
756 size_t *p_ciphertext_length);
757
788 psa_key_slot_number_t key_slot,
789 psa_algorithm_t algorithm,
790 const uint8_t *p_nonce,
791 size_t nonce_length,
792 const uint8_t *p_additional_data,
793 size_t additional_data_length,
794 const uint8_t *p_ciphertext,
795 size_t ciphertext_length,
796 uint8_t *p_plaintext,
797 size_t plaintext_size,
798 size_t *p_plaintext_length);
799
837
898 void *persistent_data,
899 const psa_key_attributes_t *attributes,
901 psa_key_slot_number_t *key_slot);
902
940 void *persistent_data,
941 const psa_key_attributes_t *attributes,
943 psa_key_slot_number_t key_slot);
944
974 psa_key_slot_number_t key_slot,
975 const psa_key_attributes_t *attributes,
976 const uint8_t *data,
977 size_t data_length,
978 size_t *bits);
979
998 void *persistent_data,
999 psa_key_slot_number_t key_slot);
1000
1031 psa_key_slot_number_t key_slot,
1032 uint8_t *p_data,
1033 size_t data_size,
1034 size_t *p_data_length);
1035
1071 psa_key_slot_number_t key_slot,
1072 const psa_key_attributes_t *attributes,
1073 uint8_t *pubkey, size_t pubkey_size,
1074 size_t *pubkey_length);
1075
1101
1171 void *op_context,
1172 psa_algorithm_t kdf_alg,
1173 psa_key_slot_number_t source_key);
1174
1192 uint32_t collateral_id,
1193 const uint8_t *p_collateral,
1194 size_t collateral_size);
1195
1207 psa_key_slot_number_t dest_key);
1208
1223 uint8_t *p_output,
1224 size_t output_size,
1225 size_t *p_output_length);
1226
1248
1307#define PSA_DRV_SE_HAL_VERSION 0x00000005
1308
1309#ifdef __cplusplus
1310}
1311#endif
1312
1313#endif /* PSA_CRYPTO_SE_DRIVER_H */
Type definitions for PSA Crypto.
uint32_t psa_key_location_t
Encoding of key location indicators.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
psa_encrypt_or_decrypt_t
For encrypt-decrypt functions, whether the operation is an encryption or a decryption.
Value definitions for PSA Crypto.
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...
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 mat...
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 ag...
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...
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.
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.
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.
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.
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.
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 se...
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.
psa_status_t(* psa_drv_se_cipher_abort_t)(void *op_context)
A function that aborts a previously started secure element cipher operation.
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.
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.
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.
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.
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.
uint64_t psa_key_slot_number_t
Encoding of a key slot number on a secure element.
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.
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.
psa_key_creation_method_t
An enumeration indicating how a key is created.
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.
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.
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.
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.
@ PSA_KEY_CREATION_COPY
During psa_copy_key()
@ PSA_KEY_CREATION_IMPORT
During psa_import_key()
@ PSA_KEY_CREATION_DERIVE
During psa_key_derivation_output_key()
@ PSA_KEY_CREATION_GENERATE
During psa_generate_key()
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.
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.
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 resultin...
psa_status_t(* psa_drv_se_mac_abort_t)(void *op_context)
A function that aborts a previous started secure element MAC operation.
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...
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 resultin...
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...
int32_t psa_status_t
Status code type used for all PSA Certified APIs.
Definition error.h:41
A struct containing all of the function pointers needed to implement secure element Authenticated Enc...
psa_drv_se_aead_encrypt_t p_encrypt
Function that performs the AEAD encrypt operation.
psa_drv_se_aead_decrypt_t p_decrypt
Function that performs the AEAD decrypt operation.
A struct containing all of the function pointers needed to implement asymmetric cryptographic operati...
psa_drv_se_asymmetric_verify_t p_verify
Function that performs an asymmetric verify operation.
psa_drv_se_asymmetric_sign_t p_sign
Function that performs an asymmetric sign operation.
psa_drv_se_asymmetric_encrypt_t p_encrypt
Function that performs an asymmetric encrypt operation.
psa_drv_se_asymmetric_decrypt_t p_decrypt
Function that performs an asymmetric decrypt operation.
A struct containing all of the function pointers needed to implement cipher operations using secure e...
size_t context_size
The size in bytes of the hardware-specific secure element cipher context structure.
psa_drv_se_cipher_setup_t p_setup
Function that performs a cipher setup operation.
psa_drv_se_cipher_finish_t p_finish
Function that completes a cipher operation.
psa_drv_se_cipher_set_iv_t p_set_iv
Function that sets a cipher IV (if necessary)
psa_drv_se_cipher_ecb_t p_ecb
Function that performs ECB mode for a cipher operation.
psa_drv_se_cipher_abort_t p_abort
Function that aborts a cipher operation.
psa_drv_se_cipher_update_t p_update
Function that performs a cipher update operation.
Driver context structure.
uintptr_t transient_data
Driver transient data.
const void * persistent_data
A read-only pointer to the driver's persistent data.
const size_t persistent_data_size
The size of persistent_data in bytes.
A struct containing all of the function pointers needed to for secure element key derivation and agre...
psa_drv_se_key_derivation_setup_t p_setup
Function that performs a key derivation setup.
psa_drv_se_key_derivation_collateral_t p_collateral
Function that sets key derivation collateral.
psa_drv_se_key_derivation_export_t p_export
Function that perforsm a final key derivation or agreement and exports the key.
psa_drv_se_key_derivation_derive_t p_derive
Function that performs a final key derivation step.
size_t context_size
The driver-specific size of the key derivation context.
A struct containing all of the function pointers needed to for secure element key management.
psa_drv_se_export_key_t p_export
Function that performs a key export operation.
psa_drv_se_validate_slot_number_t p_validate_slot_number
Function that checks the validity of a slot for a key.
psa_drv_se_import_key_t p_import
Function that performs a key import operation.
psa_drv_se_destroy_key_t p_destroy
Function that performs a key destroy operation.
psa_drv_se_generate_key_t p_generate
Function that performs a generation.
psa_drv_se_allocate_key_t p_allocate
Function that allocates a slot for a key.
psa_drv_se_export_key_t p_export_public
Function that performs a public key export operation.
A struct containing all of the function pointers needed to perform secure element MAC operations.
psa_drv_se_mac_setup_t p_setup
Function that performs a MAC setup operation.
psa_drv_se_mac_update_t p_update
Function that performs a MAC update operation.
size_t context_size
The size in bytes of the hardware-specific secure element MAC context structure.
psa_drv_se_mac_verify_t p_mac_verify
Function that performs a MAC and verify operation in one call.
psa_drv_se_mac_finish_t p_finish
Function that completes a MAC operation.
psa_drv_se_mac_abort_t p_abort
Function that aborts a previoustly started MAC operation.
psa_drv_se_mac_finish_verify_t p_finish_verify
Function that completes a MAC operation with a verify check.
psa_drv_se_mac_generate_t p_mac
Function that performs a MAC operation in one call.
A structure containing pointers to all the entry points of a secure element driver.
size_t persistent_data_size
The size of the driver's persistent data in bytes.
const psa_drv_se_key_management_t * key_management
Key management methods.
const psa_drv_se_aead_t * aead
AEAD operation methods.
const psa_drv_se_cipher_t * cipher
Cipher operation methods.
const psa_drv_se_asymmetric_t * asymmetric
Asymmetric operation methods.
const psa_drv_se_mac_t * mac
MAC operation methods.
psa_drv_se_init_t p_init
The driver initialization function.
const psa_drv_se_key_derivation_t * derivation
Key derivation methods.
uint32_t hal_version
The version of the driver HAL that this driver implements.
Structure storing key attributes.