1 /*
2 * PSA crypto core internal interfaces
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_CORE_H
22 #define PSA_CRYPTO_CORE_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 data structure representing a key slot, containing key material
34 * and metadata for one key.
35 */
36 typedef struct
37 {
38 psa_core_key_attributes_t attr;
39
40 /*
41 * Number of locks on the key slot held by the library.
42 *
43 * This counter is incremented by one each time a library function
44 * retrieves through one of the dedicated internal API a pointer to the
45 * key slot.
46 *
47 * This counter is decremented by one each time a library function stops
48 * accessing the key slot and states it by calling the
49 * psa_unlock_key_slot() API.
50 *
51 * This counter is used to prevent resetting the key slot while the library
52 * may access it. For example, such control is needed in the following
53 * scenarios:
54 * . In case of key slot starvation, all key slots contain the description
55 * of a key, and the library asks for the description of a persistent
56 * key not present in the key slots, the key slots currently accessed by
57 * the library cannot be reclaimed to free a key slot to load the
58 * persistent key.
59 * . In case of a multi-threaded application where one thread asks to close
60 * or purge or destroy a key while it is in used by the library through
61 * another thread.
62 */
63 size_t lock_count;
64
65 union
66 {
67 /* Dynamically allocated key data buffer.
68 * Format as specified in psa_export_key(). */
69 struct key_data
70 {
71 uint8_t *data;
72 size_t bytes;
73 } key;
74 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
75 /* Any key type in a secure element */
76 struct se
77 {
78 psa_key_slot_number_t slot_number;
79 } se;
80 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
81 } data;
82 } psa_key_slot_t;
83
84 /* A mask of key attribute flags used only internally.
85 * Currently there aren't any. */
86 #define PSA_KA_MASK_INTERNAL_ONLY ( \
87 0 )
88
89 /** Test whether a key slot is occupied.
90 *
91 * A key slot is occupied iff the key type is nonzero. This works because
92 * no valid key can have 0 as its key type.
93 *
94 * \param[in] slot The key slot to test.
95 *
96 * \return 1 if the slot is occupied, 0 otherwise.
97 */
psa_is_key_slot_occupied(const psa_key_slot_t * slot)98 static inline int psa_is_key_slot_occupied( const psa_key_slot_t *slot )
99 {
100 return( slot->attr.type != 0 );
101 }
102
103 /** Test whether a key slot is locked.
104 *
105 * A key slot is locked iff its lock counter is strictly greater than 0.
106 *
107 * \param[in] slot The key slot to test.
108 *
109 * \return 1 if the slot is locked, 0 otherwise.
110 */
psa_is_key_slot_locked(const psa_key_slot_t * slot)111 static inline int psa_is_key_slot_locked( const psa_key_slot_t *slot )
112 {
113 return( slot->lock_count > 0 );
114 }
115
116 /** Retrieve flags from psa_key_slot_t::attr::core::flags.
117 *
118 * \param[in] slot The key slot to query.
119 * \param mask The mask of bits to extract.
120 *
121 * \return The key attribute flags in the given slot,
122 * bitwise-anded with \p mask.
123 */
psa_key_slot_get_flags(const psa_key_slot_t * slot,uint16_t mask)124 static inline uint16_t psa_key_slot_get_flags( const psa_key_slot_t *slot,
125 uint16_t mask )
126 {
127 return( slot->attr.flags & mask );
128 }
129
130 /** Set flags in psa_key_slot_t::attr::core::flags.
131 *
132 * \param[in,out] slot The key slot to modify.
133 * \param mask The mask of bits to modify.
134 * \param value The new value of the selected bits.
135 */
psa_key_slot_set_flags(psa_key_slot_t * slot,uint16_t mask,uint16_t value)136 static inline void psa_key_slot_set_flags( psa_key_slot_t *slot,
137 uint16_t mask,
138 uint16_t value )
139 {
140 slot->attr.flags = ( ( ~mask & slot->attr.flags ) |
141 ( mask & value ) );
142 }
143
144 /** Turn on flags in psa_key_slot_t::attr::core::flags.
145 *
146 * \param[in,out] slot The key slot to modify.
147 * \param mask The mask of bits to set.
148 */
psa_key_slot_set_bits_in_flags(psa_key_slot_t * slot,uint16_t mask)149 static inline void psa_key_slot_set_bits_in_flags( psa_key_slot_t *slot,
150 uint16_t mask )
151 {
152 slot->attr.flags |= mask;
153 }
154
155 /** Turn off flags in psa_key_slot_t::attr::core::flags.
156 *
157 * \param[in,out] slot The key slot to modify.
158 * \param mask The mask of bits to clear.
159 */
psa_key_slot_clear_bits(psa_key_slot_t * slot,uint16_t mask)160 static inline void psa_key_slot_clear_bits( psa_key_slot_t *slot,
161 uint16_t mask )
162 {
163 slot->attr.flags &= ~mask;
164 }
165
166 /** Completely wipe a slot in memory, including its policy.
167 *
168 * Persistent storage is not affected.
169 *
170 * \param[in,out] slot The key slot to wipe.
171 *
172 * \retval #PSA_SUCCESS
173 * Success. This includes the case of a key slot that was
174 * already fully wiped.
175 * \retval #PSA_ERROR_CORRUPTION_DETECTED
176 */
177 psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot );
178
179 /** Copy key data (in export format) into an empty key slot.
180 *
181 * This function assumes that the slot does not contain
182 * any key material yet. On failure, the slot content is unchanged.
183 *
184 * \param[in,out] slot Key slot to copy the key into.
185 * \param[in] data Buffer containing the key material.
186 * \param data_length Size of the key buffer.
187 *
188 * \retval #PSA_SUCCESS
189 * The key has been copied successfully.
190 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
191 * Not enough memory was available for allocation of the
192 * copy buffer.
193 * \retval #PSA_ERROR_ALREADY_EXISTS
194 * There was other key material already present in the slot.
195 */
196 psa_status_t psa_copy_key_material_into_slot( psa_key_slot_t *slot,
197 const uint8_t *data,
198 size_t data_length );
199
200 /** Convert an mbed TLS error code to a PSA error code
201 *
202 * \note This function is provided solely for the convenience of
203 * Mbed TLS and may be removed at any time without notice.
204 *
205 * \param ret An mbed TLS-thrown error code
206 *
207 * \return The corresponding PSA error code
208 */
209 psa_status_t mbedtls_to_psa_error( int ret );
210
211 #endif /* PSA_CRYPTO_CORE_H */
212
