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