1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
/*
* PSA crypto support for secure element drivers
*/
/*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
*/
#ifndef PSA_CRYPTO_SE_H
#define PSA_CRYPTO_SE_H
/*
* Include the build-time configuration information header. Here, we do not
* include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which
* is basically just an alias to it. This is to ease the maintenance of the
* TF-PSA-Crypto repository which has a different build system and
* configuration.
*/
#include "psa/build_info.h"
#include "psa/crypto.h"
#include "psa/crypto_se_driver.h"
/** The maximum location value that this implementation supports
* for a secure element.
*
* This is not a characteristic that each PSA implementation has, but a
* limitation of the current implementation due to the constraints imposed
* by storage. See #PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE.
*
* The minimum location value for a secure element is 1, like on any
* PSA implementation (0 means a transparent key).
*/
#define PSA_MAX_SE_LOCATION 255
/** The base of the range of ITS file identifiers for secure element
* driver persistent data.
*
* We use a slice of the implementation reserved range 0xffff0000..0xffffffff,
* specifically the range 0xfffffe00..0xfffffeff. The length of this range
* drives the value of #PSA_MAX_SE_LOCATION. The identifier 0xfffffe00 is
* actually not used since it corresponds to #PSA_KEY_LOCATION_LOCAL_STORAGE
* which doesn't have a driver.
*/
#define PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE ((psa_key_id_t) 0xfffffe00)
/** The maximum number of registered secure element driver locations. */
#define PSA_MAX_SE_DRIVERS 4
/** Unregister all secure element drivers.
*
* \warning Do not call this function while the library is in the initialized
* state. This function is only intended to be called at the end
* of mbedtls_psa_crypto_free().
*/
void psa_unregister_all_se_drivers(void);
/** Initialize all secure element drivers.
*
* Called from psa_crypto_init().
*/
psa_status_t psa_init_all_se_drivers(void);
/** A structure that describes a registered secure element driver.
*
* A secure element driver table entry contains a pointer to the
* driver's method table as well as the driver context structure.
*/
typedef struct psa_se_drv_table_entry_s psa_se_drv_table_entry_t;
/** Return the secure element driver information for a lifetime value.
*
* \param lifetime The lifetime value to query.
* \param[out] p_methods On output, if there is a driver,
* \c *methods points to its method table.
* Otherwise \c *methods is \c NULL.
* \param[out] p_drv_context On output, if there is a driver,
* \c *drv_context points to its context
* structure.
* Otherwise \c *drv_context is \c NULL.
*
* \retval 1
* \p lifetime corresponds to a registered driver.
* \retval 0
* \p lifetime does not correspond to a registered driver.
*/
int psa_get_se_driver(psa_key_lifetime_t lifetime,
const psa_drv_se_t **p_methods,
psa_drv_se_context_t **p_drv_context);
/** Return the secure element driver table entry for a lifetime value.
*
* \param lifetime The lifetime value to query.
*
* \return The driver table entry for \p lifetime, or
* \p NULL if \p lifetime does not correspond to a registered driver.
*/
psa_se_drv_table_entry_t *psa_get_se_driver_entry(
psa_key_lifetime_t lifetime);
/** Return the method table for a secure element driver.
*
* \param[in] driver The driver table entry to access, or \c NULL.
*
* \return The driver's method table.
* \c NULL if \p driver is \c NULL.
*/
const psa_drv_se_t *psa_get_se_driver_methods(
const psa_se_drv_table_entry_t *driver);
/** Return the context of a secure element driver.
*
* \param[in] driver The driver table entry to access, or \c NULL.
*
* \return A pointer to the driver context.
* \c NULL if \p driver is \c NULL.
*/
psa_drv_se_context_t *psa_get_se_driver_context(
psa_se_drv_table_entry_t *driver);
/** Find a free slot for a key that is to be created.
*
* This function calls the relevant method in the driver to find a suitable
* slot for a key with the given attributes.
*
* \param[in] attributes Metadata about the key that is about to be created.
* \param[in] driver The driver table entry to query.
* \param[out] slot_number On success, a slot number that is free in this
* secure element.
*/
psa_status_t psa_find_se_slot_for_key(
const psa_key_attributes_t *attributes,
psa_key_creation_method_t method,
psa_se_drv_table_entry_t *driver,
psa_key_slot_number_t *slot_number);
/** Destroy a key in a secure element.
*
* This function calls the relevant driver method to destroy a key
* and updates the driver's persistent data.
*/
psa_status_t psa_destroy_se_key(psa_se_drv_table_entry_t *driver,
psa_key_slot_number_t slot_number);
/** Load the persistent data of a secure element driver.
*
* \param driver The driver table entry containing the persistent
* data to load from storage.
*
* \return #PSA_SUCCESS
* \return #PSA_ERROR_NOT_SUPPORTED
* \return #PSA_ERROR_DOES_NOT_EXIST
* \return #PSA_ERROR_STORAGE_FAILURE
* \return #PSA_ERROR_DATA_CORRUPT
* \return #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_load_se_persistent_data(
const psa_se_drv_table_entry_t *driver);
/** Save the persistent data of a secure element driver.
*
* \param[in] driver The driver table entry containing the persistent
* data to save to storage.
*
* \return #PSA_SUCCESS
* \return #PSA_ERROR_NOT_SUPPORTED
* \return #PSA_ERROR_NOT_PERMITTED
* \return #PSA_ERROR_NOT_SUPPORTED
* \return #PSA_ERROR_INSUFFICIENT_STORAGE
* \return #PSA_ERROR_STORAGE_FAILURE
* \return #PSA_ERROR_INVALID_ARGUMENT
*/
psa_status_t psa_save_se_persistent_data(
const psa_se_drv_table_entry_t *driver);
/** Destroy the persistent data of a secure element driver.
*
* This is currently only used for testing.
*
* \param[in] location The location identifier for the driver whose
* persistent data is to be erased.
*/
psa_status_t psa_destroy_se_persistent_data(psa_key_location_t location);
/** The storage representation of a key whose data is in a secure element.
*/
typedef struct {
uint8_t slot_number[sizeof(psa_key_slot_number_t)];
} psa_se_key_data_storage_t;
#endif /* PSA_CRYPTO_SE_H */
|
