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