Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
psa_crypto_se.h
1 /*
2  * PSA crypto support for secure element drivers
3  */
4 /* Copyright (C) 2019, ARM Limited, All Rights Reserved
5  * SPDX-License-Identifier: Apache-2.0
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may
8  * not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  * This file is part of Mbed TLS (https://tls.mbed.org)
20  */
21 
22 #ifndef PSA_CRYPTO_SE_H
23 #define PSA_CRYPTO_SE_H
24 
25 #if !defined(MBEDTLS_CONFIG_FILE)
26 #include "mbedtls/config.h"
27 #else
28 #include MBEDTLS_CONFIG_FILE
29 #endif
30 
31 #include "psa/crypto.h"
32 #include "psa/crypto_se_driver.h"
33 
34 /** The maximum lifetime value that this implementation supports
35  * for a secure element.
36  *
37  * This is not a characteristic that each PSA implementation has, but a
38  * limitation of the current implementation due to the constraints imposed
39  * by storage. See #PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE.
40  *
41  * The minimum lifetime value for a secure element is 2, like on any
42  * PSA implementation (0=volatile and 1=internal-storage are taken).
43  */
44 #define PSA_MAX_SE_LIFETIME 255
45 
46 /** The base of the range of ITS file identifiers for secure element
47  * driver persistent data.
48  *
49  * We use a slice of the implemenation reserved range 0xffff0000..0xffffffff,
50  * specifically the range 0xfffffe00..0xfffffeff. The length of this range
51  * drives the value of #PSA_MAX_SE_LIFETIME.
52  * The identifiers 0xfffffe00 and 0xfffffe01 are actually not used since
53  * they correspond to #PSA_KEY_LIFETIME_VOLATILE and
54  * #PSA_KEY_LIFETIME_PERSISTENT which don't have a driver.
55  */
56 #define PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE ( (psa_key_id_t) 0xfffffe00 )
57 
58 /** The maximum number of registered secure element driver lifetimes. */
59 #define PSA_MAX_SE_DRIVERS 4
60 
61 /** Unregister all secure element drivers.
62  *
63  * \warning Do not call this function while the library is in the initialized
64  * state. This function is only intended to be called at the end
65  * of mbedtls_psa_crypto_free().
66  */
67 void psa_unregister_all_se_drivers( void );
68 
69 /** Initialize all secure element drivers.
70  *
71  * Called from psa_crypto_init().
72  */
73 psa_status_t psa_init_all_se_drivers( void );
74 
75 /** A structure that describes a registered secure element driver.
76  *
77  * A secure element driver table entry contains a pointer to the
78  * driver's method table as well as the driver context structure.
79  */
80 typedef struct psa_se_drv_table_entry_s psa_se_drv_table_entry_t;
81 
82 /** Return the secure element driver information for a lifetime value.
83  *
84  * \param lifetime The lifetime value to query.
85  * \param[out] p_methods On output, if there is a driver,
86  * \c *methods points to its method table.
87  * Otherwise \c *methods is \c NULL.
88  * \param[out] p_drv_context On output, if there is a driver,
89  * \c *drv_context points to its context
90  * structure.
91  * Otherwise \c *drv_context is \c NULL.
92  *
93  * \retval 1
94  * \p lifetime corresponds to a registered driver.
95  * \retval 0
96  * \p lifetime does not correspond to a registered driver.
97  */
98 int psa_get_se_driver( psa_key_lifetime_t lifetime,
99  const psa_drv_se_t **p_methods,
100  psa_drv_se_context_t **p_drv_context);
101 
102 /** Return the secure element driver table entry for a lifetime value.
103  *
104  * \param lifetime The lifetime value to query.
105  *
106  * \return The driver table entry for \p lifetime, or
107  * \p NULL if \p lifetime does not correspond to a registered driver.
108  */
109 psa_se_drv_table_entry_t *psa_get_se_driver_entry(
110  psa_key_lifetime_t lifetime );
111 
112 /** Return the method table for a secure element driver.
113  *
114  * \param[in] driver The driver table entry to access, or \c NULL.
115  *
116  * \return The driver's method table.
117  * \c NULL if \p driver is \c NULL.
118  */
119 const psa_drv_se_t *psa_get_se_driver_methods(
120  const psa_se_drv_table_entry_t *driver );
121 
122 /** Return the context of a secure element driver.
123  *
124  * \param[in] driver The driver table entry to access, or \c NULL.
125  *
126  * \return A pointer to the driver context.
127  * \c NULL if \p driver is \c NULL.
128  */
129 psa_drv_se_context_t *psa_get_se_driver_context(
130  psa_se_drv_table_entry_t *driver );
131 
132 /** Find a free slot for a key that is to be created.
133  *
134  * This function calls the relevant method in the driver to find a suitable
135  * slot for a key with the given attributes.
136  *
137  * \param[in] attributes Metadata about the key that is about to be created.
138  * \param[in] driver The driver table entry to query.
139  * \param[out] slot_number On success, a slot number that is free in this
140  * secure element.
141  */
142 psa_status_t psa_find_se_slot_for_key(
143  const psa_key_attributes_t *attributes,
144  psa_key_creation_method_t method,
145  psa_se_drv_table_entry_t *driver,
146  psa_key_slot_number_t *slot_number );
147 
148 /** Destoy a key in a secure element.
149  *
150  * This function calls the relevant driver method to destroy a key
151  * and updates the driver's persistent data.
152  */
153 psa_status_t psa_destroy_se_key( psa_se_drv_table_entry_t *driver,
154  psa_key_slot_number_t slot_number );
155 
156 /** Load the persistent data of a secure element driver.
157  *
158  * \param driver The driver table entry containing the persistent
159  * data to load from storage.
160  */
161 psa_status_t psa_load_se_persistent_data(
162  const psa_se_drv_table_entry_t *driver );
163 
164 /** Save the persistent data of a secure element driver.
165  *
166  * \param[in] driver The driver table entry containing the persistent
167  * data to save to storage.
168  */
169 psa_status_t psa_save_se_persistent_data(
170  const psa_se_drv_table_entry_t *driver );
171 
172 /** Destroy the persistent data of a secure element driver.
173  *
174  * This is currently only used for testing.
175  *
176  * \param[in] lifetime The driver lifetime whose persistent data should
177  * be erased.
178  */
179 psa_status_t psa_destroy_se_persistent_data( psa_key_lifetime_t lifetime );
180 
181 
182 /** The storage representation of a key whose data is in a secure element.
183  */
184 typedef struct
185 {
186  uint8_t slot_number[sizeof( psa_key_slot_number_t )];
187  uint8_t bits[sizeof( psa_key_bits_t )];
188 } psa_se_key_data_storage_t;
189 
190 #endif /* PSA_CRYPTO_SE_H */
psa_key_attributes_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:342
psa_se_key_data_storage_t
The storage representation of a key whose data is in a secure element.
Definition: psa_crypto_se.h:184
psa_drv_se_t
A structure containing pointers to all the entry points of a secure element driver.
Definition: crypto_se_driver.h:1287
psa_drv_se_context_t
Driver context structure.
Definition: crypto_se_driver.h:55
psa_key_slot_number_t
uint64_t psa_key_slot_number_t
An internal designation of a key slot between the core part of the PSA Crypto implementation and the ...
Definition: crypto_se_driver.h:146
crypto_se_driver.h
PSA external cryptoprocessor driver module.
psa_key_lifetime_t
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:121
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
psa_key_creation_method_t
psa_key_creation_method_t
An enumeration indicating how a key is created.
Definition: crypto_se_driver.h:815
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.