1 /* 2 * Copyright (c) 2017-2023, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __TFM_PLAT_CRYPTO_KEYS_H__ 9 #define __TFM_PLAT_CRYPTO_KEYS_H__ 10 11 #include <stdint.h> 12 #include "psa/crypto.h" 13 #include "tfm_plat_defs.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * \brief Callback function type platform key loader functions 21 * 22 * This function pointer type defines the prototype for a builtin key loader function so that the 23 * key can be probed by the tfm_builtin_key_loader driver during the init phase. Note that the key 24 * must be readable from the secure processing element to be able to use the tfm_builtin_key_loader 25 * 26 * \param[out] buf Buffer to hold the retrieved key material from the platform 27 * \param[in] buf_len Size of the buf buffer 28 * \param[out] key_len Actual length of the key material in bytes retrieved from the platform 29 * \param[out] key_bits Size in bits of the key (important for those keys that are not 30 * byte-multiple or encoded in different format than raw bytes) 31 * \param[out] algorithm \ref psa_algorithm_t value associated to the retrieved key material 32 * \param[out] type \ref psa_key_type_t value associated to the retrieved key material 33 * 34 * \return Returns an error value as specified by the \ref tfm_plat_err_t type. 35 * 36 */ 37 typedef enum tfm_plat_err_t (*key_loader_func_ptr) 38 (uint8_t *buf, size_t buf_len, size_t *key_len, psa_key_bits_t *key_bits, psa_algorithm_t *algorithm, psa_key_type_t *type); 39 40 /** 41 * \brief This type describes the information that each TF-M builtin key 42 * must key in the associated descriptor table in \ref crypto_keys.c 43 */ 44 typedef struct { 45 psa_key_id_t key_id; /*!< Key id associated to the builtin key */ 46 psa_drv_slot_number_t slot_number; /*!< Slot number for the builtin key in the platform */ 47 psa_key_lifetime_t lifetime; /*!< Lifetime (persistence + location) for the builtin key */ 48 key_loader_func_ptr loader_key_func; /*!< Loader function that reads the key from the platform */ 49 } tfm_plat_builtin_key_descriptor_t; 50 51 /** 52 * \brief This function retrieves a pointer to the description table for builtin keys. Each platform 53 * must implement this table with the details of the builtin keys available in the platform 54 * 55 * \param[out] desc_ptr A pointer to the description table 56 * 57 * \return size_t The number of builtin keys available in the platform 58 */ 59 size_t tfm_plat_builtin_key_get_desc_table_ptr(const tfm_plat_builtin_key_descriptor_t *desc_ptr[]); 60 61 /** 62 * \brief This type maps a particular user of a builtin key (i.e. an owner) to 63 * the allowed usage (i.e. a policy) as specified by the platform 64 */ 65 typedef struct { 66 int32_t user; 67 psa_key_usage_t usage; 68 } tfm_plat_builtin_key_per_user_policy_t; 69 70 /** 71 * \brief This type maps a particular key_id associated to a builtin key to the 72 * allowed usage (i.e. a policy). The policy can be user specific in case 73 * the per_user_policy field is greater than 0. In that case policy_ptr needs 74 * to be used to access the policies for each user of the key_id which are of 75 * type \ref tfm_platf_builtin_key_per_user_policy_t 76 */ 77 typedef struct { 78 psa_key_id_t key_id; 79 size_t per_user_policy; 80 union { 81 psa_key_usage_t usage; 82 const tfm_plat_builtin_key_per_user_policy_t *policy_ptr; 83 }; 84 } tfm_plat_builtin_key_policy_t; 85 86 /** 87 * \brief This function retrieves a pointer to the policy table of the builtin keys. Each platform 88 * must implement this table with the details of the builtin keys available in the platform 89 * 90 * \param[out] desc_ptr A pointer to the policy table 91 * 92 * \return size_t The number of builtin keys available in the platform with associated policies 93 */ 94 size_t tfm_plat_builtin_key_get_policy_table_ptr(const tfm_plat_builtin_key_policy_t *desc_ptr[]); 95 96 #ifdef __cplusplus 97 } 98 #endif 99 100 #endif /* __TFM_PLAT_CRYPTO_KEYS_H__ */ 101
