1 /**
2 * \file psa/crypto_struct.h
3 *
4 * \brief PSA cryptography module: Mbed TLS structured type implementations
5 *
6 * \note This file may not be included directly. Applications must
7 * include psa/crypto.h.
8 *
9 * This file contains the definitions of some data structures with
10 * implementation-specific definitions.
11 *
12 * In implementations with isolation between the application and the
13 * cryptography module, it is expected that the front-end and the back-end
14 * would have different versions of this file.
15 *
16 * <h3>Design notes about multipart operation structures</h3>
17 *
18 * For multipart operations without driver delegation support, each multipart
19 * operation structure contains a `psa_algorithm_t alg` field which indicates
20 * which specific algorithm the structure is for. When the structure is not in
21 * use, `alg` is 0. Most of the structure consists of a union which is
22 * discriminated by `alg`.
23 *
24 * For multipart operations with driver delegation support, each multipart
25 * operation structure contains an `unsigned int id` field indicating which
26 * driver got assigned to do the operation. When the structure is not in use,
27 * 'id' is 0. The structure contains also a driver context which is the union
28 * of the contexts of all drivers able to handle the type of multipart
29 * operation.
30 *
31 * Note that when `alg` or `id` is 0, the content of other fields is undefined.
32 * In particular, it is not guaranteed that a freshly-initialized structure
33 * is all-zero: we initialize structures to something like `{0, 0}`, which
34 * is only guaranteed to initializes the first member of the union;
35 * GCC and Clang initialize the whole structure to 0 (at the time of writing),
36 * but MSVC and CompCert don't.
37 *
38 * In Mbed Crypto, multipart operation structures live independently from
39 * the key. This allows Mbed Crypto to free the key objects when destroying
40 * a key slot. If a multipart operation needs to remember the key after
41 * the setup function returns, the operation structure needs to contain a
42 * copy of the key.
43 */
44 /*
45 * Copyright The Mbed TLS Contributors
46 * SPDX-License-Identifier: Apache-2.0
47 *
48 * Licensed under the Apache License, Version 2.0 (the "License"); you may
49 * not use this file except in compliance with the License.
50 * You may obtain a copy of the License at
51 *
52 * http://www.apache.org/licenses/LICENSE-2.0
53 *
54 * Unless required by applicable law or agreed to in writing, software
55 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
56 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
57 * See the License for the specific language governing permissions and
58 * limitations under the License.
59 */
60
61 #ifndef PSA_CRYPTO_STRUCT_H
62 #define PSA_CRYPTO_STRUCT_H
63 #include "mbedtls/private_access.h"
64
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68
69 /* Include the Mbed TLS configuration file, the way Mbed TLS does it
70 * in each of its header files. */
71 #include "mbedtls/build_info.h"
72
73 #include "mbedtls/cmac.h"
74 #include "mbedtls/gcm.h"
75 #include "mbedtls/ccm.h"
76 #include "mbedtls/chachapoly.h"
77
78 /* Include the context definition for the compiled-in drivers for the primitive
79 * algorithms. */
80 #include "psa/crypto_driver_contexts_primitives.h"
81
82 struct psa_hash_operation_s
83 {
84 /** Unique ID indicating which driver got assigned to do the
85 * operation. Since driver contexts are driver-specific, swapping
86 * drivers halfway through the operation is not supported.
87 * ID values are auto-generated in psa_driver_wrappers.h.
88 * ID value zero means the context is not valid or not assigned to
89 * any driver (i.e. the driver context is not active, in use). */
90 unsigned int MBEDTLS_PRIVATE(id);
91 psa_driver_hash_context_t MBEDTLS_PRIVATE(ctx);
92 };
93
94 #define PSA_HASH_OPERATION_INIT { 0, { 0 } }
psa_hash_operation_init(void)95 static inline struct psa_hash_operation_s psa_hash_operation_init( void )
96 {
97 const struct psa_hash_operation_s v = PSA_HASH_OPERATION_INIT;
98 return( v );
99 }
100
101 struct psa_cipher_operation_s
102 {
103 /** Unique ID indicating which driver got assigned to do the
104 * operation. Since driver contexts are driver-specific, swapping
105 * drivers halfway through the operation is not supported.
106 * ID values are auto-generated in psa_crypto_driver_wrappers.h
107 * ID value zero means the context is not valid or not assigned to
108 * any driver (i.e. none of the driver contexts are active). */
109 unsigned int MBEDTLS_PRIVATE(id);
110
111 unsigned int MBEDTLS_PRIVATE(iv_required) : 1;
112 unsigned int MBEDTLS_PRIVATE(iv_set) : 1;
113
114 uint8_t MBEDTLS_PRIVATE(default_iv_length);
115
116 psa_driver_cipher_context_t MBEDTLS_PRIVATE(ctx);
117 };
118
119 #define PSA_CIPHER_OPERATION_INIT { 0, 0, 0, 0, { 0 } }
psa_cipher_operation_init(void)120 static inline struct psa_cipher_operation_s psa_cipher_operation_init( void )
121 {
122 const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT;
123 return( v );
124 }
125
126 /* Include the context definition for the compiled-in drivers for the composite
127 * algorithms. */
128 #include "psa/crypto_driver_contexts_composites.h"
129
130 struct psa_mac_operation_s
131 {
132 /** Unique ID indicating which driver got assigned to do the
133 * operation. Since driver contexts are driver-specific, swapping
134 * drivers halfway through the operation is not supported.
135 * ID values are auto-generated in psa_driver_wrappers.h
136 * ID value zero means the context is not valid or not assigned to
137 * any driver (i.e. none of the driver contexts are active). */
138 unsigned int MBEDTLS_PRIVATE(id);
139 uint8_t MBEDTLS_PRIVATE(mac_size);
140 unsigned int MBEDTLS_PRIVATE(is_sign) : 1;
141 psa_driver_mac_context_t MBEDTLS_PRIVATE(ctx);
142 };
143
144 #define PSA_MAC_OPERATION_INIT { 0, 0, 0, { 0 } }
psa_mac_operation_init(void)145 static inline struct psa_mac_operation_s psa_mac_operation_init( void )
146 {
147 const struct psa_mac_operation_s v = PSA_MAC_OPERATION_INIT;
148 return( v );
149 }
150
151 struct psa_aead_operation_s
152 {
153
154 /** Unique ID indicating which driver got assigned to do the
155 * operation. Since driver contexts are driver-specific, swapping
156 * drivers halfway through the operation is not supported.
157 * ID values are auto-generated in psa_crypto_driver_wrappers.h
158 * ID value zero means the context is not valid or not assigned to
159 * any driver (i.e. none of the driver contexts are active). */
160 unsigned int MBEDTLS_PRIVATE(id);
161
162 psa_algorithm_t MBEDTLS_PRIVATE(alg);
163 psa_key_type_t MBEDTLS_PRIVATE(key_type);
164
165 size_t MBEDTLS_PRIVATE(ad_remaining);
166 size_t MBEDTLS_PRIVATE(body_remaining);
167
168 unsigned int MBEDTLS_PRIVATE(nonce_set) : 1;
169 unsigned int MBEDTLS_PRIVATE(lengths_set) : 1;
170 unsigned int MBEDTLS_PRIVATE(ad_started) : 1;
171 unsigned int MBEDTLS_PRIVATE(body_started) : 1;
172 unsigned int MBEDTLS_PRIVATE(is_encrypt) : 1;
173
174 psa_driver_aead_context_t MBEDTLS_PRIVATE(ctx);
175 };
176
177 #define PSA_AEAD_OPERATION_INIT {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, {0}}
psa_aead_operation_init(void)178 static inline struct psa_aead_operation_s psa_aead_operation_init( void )
179 {
180 const struct psa_aead_operation_s v = PSA_AEAD_OPERATION_INIT;
181 return( v );
182 }
183
184 #if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF)
185 typedef struct
186 {
187 uint8_t *MBEDTLS_PRIVATE(info);
188 size_t MBEDTLS_PRIVATE(info_length);
189 #if PSA_HASH_MAX_SIZE > 0xff
190 #error "PSA_HASH_MAX_SIZE does not fit in uint8_t"
191 #endif
192 uint8_t MBEDTLS_PRIVATE(offset_in_block);
193 uint8_t MBEDTLS_PRIVATE(block_number);
194 unsigned int MBEDTLS_PRIVATE(state) : 2;
195 unsigned int MBEDTLS_PRIVATE(info_set) : 1;
196 uint8_t MBEDTLS_PRIVATE(output_block)[PSA_HASH_MAX_SIZE];
197 uint8_t MBEDTLS_PRIVATE(prk)[PSA_HASH_MAX_SIZE];
198 struct psa_mac_operation_s MBEDTLS_PRIVATE(hmac);
199 } psa_hkdf_key_derivation_t;
200 #endif /* MBEDTLS_PSA_BUILTIN_ALG_HKDF */
201
202 #if defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF) || \
203 defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PSK_TO_MS)
204 typedef enum
205 {
206 PSA_TLS12_PRF_STATE_INIT, /* no input provided */
207 PSA_TLS12_PRF_STATE_SEED_SET, /* seed has been set */
208 PSA_TLS12_PRF_STATE_KEY_SET, /* key has been set */
209 PSA_TLS12_PRF_STATE_LABEL_SET, /* label has been set */
210 PSA_TLS12_PRF_STATE_OUTPUT /* output has been started */
211 } psa_tls12_prf_key_derivation_state_t;
212
213 typedef struct psa_tls12_prf_key_derivation_s
214 {
215 #if PSA_HASH_MAX_SIZE > 0xff
216 #error "PSA_HASH_MAX_SIZE does not fit in uint8_t"
217 #endif
218
219 /* Indicates how many bytes in the current HMAC block have
220 * not yet been read by the user. */
221 uint8_t MBEDTLS_PRIVATE(left_in_block);
222
223 /* The 1-based number of the block. */
224 uint8_t MBEDTLS_PRIVATE(block_number);
225
226 psa_tls12_prf_key_derivation_state_t MBEDTLS_PRIVATE(state);
227
228 uint8_t *MBEDTLS_PRIVATE(secret);
229 size_t MBEDTLS_PRIVATE(secret_length);
230 uint8_t *MBEDTLS_PRIVATE(seed);
231 size_t MBEDTLS_PRIVATE(seed_length);
232 uint8_t *MBEDTLS_PRIVATE(label);
233 size_t MBEDTLS_PRIVATE(label_length);
234
235 uint8_t MBEDTLS_PRIVATE(Ai)[PSA_HASH_MAX_SIZE];
236
237 /* `HMAC_hash( prk, A( i ) + seed )` in the notation of RFC 5246, Sect. 5. */
238 uint8_t MBEDTLS_PRIVATE(output_block)[PSA_HASH_MAX_SIZE];
239 } psa_tls12_prf_key_derivation_t;
240 #endif /* MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF) ||
241 * MBEDTLS_PSA_BUILTIN_ALG_TLS12_PSK_TO_MS */
242
243 struct psa_key_derivation_s
244 {
245 psa_algorithm_t MBEDTLS_PRIVATE(alg);
246 unsigned int MBEDTLS_PRIVATE(can_output_key) : 1;
247 size_t MBEDTLS_PRIVATE(capacity);
248 union
249 {
250 /* Make the union non-empty even with no supported algorithms. */
251 uint8_t MBEDTLS_PRIVATE(dummy);
252 #if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF)
253 psa_hkdf_key_derivation_t MBEDTLS_PRIVATE(hkdf);
254 #endif
255 #if defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF) || \
256 defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PSK_TO_MS)
257 psa_tls12_prf_key_derivation_t MBEDTLS_PRIVATE(tls12_prf);
258 #endif
259 } MBEDTLS_PRIVATE(ctx);
260 };
261
262 /* This only zeroes out the first byte in the union, the rest is unspecified. */
263 #define PSA_KEY_DERIVATION_OPERATION_INIT { 0, 0, 0, { 0 } }
psa_key_derivation_operation_init(void)264 static inline struct psa_key_derivation_s psa_key_derivation_operation_init(
265 void )
266 {
267 const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT;
268 return( v );
269 }
270
271 struct psa_key_policy_s
272 {
273 psa_key_usage_t MBEDTLS_PRIVATE(usage);
274 psa_algorithm_t MBEDTLS_PRIVATE(alg);
275 psa_algorithm_t MBEDTLS_PRIVATE(alg2);
276 };
277 typedef struct psa_key_policy_s psa_key_policy_t;
278
279 #define PSA_KEY_POLICY_INIT { 0, 0, 0 }
psa_key_policy_init(void)280 static inline struct psa_key_policy_s psa_key_policy_init( void )
281 {
282 const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT;
283 return( v );
284 }
285
286 /* The type used internally for key sizes.
287 * Public interfaces use size_t, but internally we use a smaller type. */
288 typedef uint16_t psa_key_bits_t;
289 /* The maximum value of the type used to represent bit-sizes.
290 * This is used to mark an invalid key size. */
291 #define PSA_KEY_BITS_TOO_LARGE ( ( psa_key_bits_t ) -1 )
292 /* The maximum size of a key in bits.
293 * Currently defined as the maximum that can be represented, rounded down
294 * to a whole number of bytes.
295 * This is an uncast value so that it can be used in preprocessor
296 * conditionals. */
297 #define PSA_MAX_KEY_BITS 0xfff8
298
299 /** A mask of flags that can be stored in key attributes.
300 *
301 * This type is also used internally to store flags in slots. Internal
302 * flags are defined in library/psa_crypto_core.h. Internal flags may have
303 * the same value as external flags if they are properly handled during
304 * key creation and in psa_get_key_attributes.
305 */
306 typedef uint16_t psa_key_attributes_flag_t;
307
308 #define MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER \
309 ( (psa_key_attributes_flag_t) 0x0001 )
310
311 /* A mask of key attribute flags used externally only.
312 * Only meant for internal checks inside the library. */
313 #define MBEDTLS_PSA_KA_MASK_EXTERNAL_ONLY ( \
314 MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER | \
315 0 )
316
317 /* A mask of key attribute flags used both internally and externally.
318 * Currently there aren't any. */
319 #define MBEDTLS_PSA_KA_MASK_DUAL_USE ( \
320 0 )
321
322 typedef struct
323 {
324 psa_key_type_t MBEDTLS_PRIVATE(type);
325 psa_key_bits_t MBEDTLS_PRIVATE(bits);
326 psa_key_lifetime_t MBEDTLS_PRIVATE(lifetime);
327 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(id);
328 psa_key_policy_t MBEDTLS_PRIVATE(policy);
329 psa_key_attributes_flag_t MBEDTLS_PRIVATE(flags);
330 } psa_core_key_attributes_t;
331
332 #define PSA_CORE_KEY_ATTRIBUTES_INIT { PSA_KEY_TYPE_NONE, 0, \
333 PSA_KEY_LIFETIME_VOLATILE, \
334 MBEDTLS_SVC_KEY_ID_INIT, \
335 PSA_KEY_POLICY_INIT, 0 }
336
337 struct psa_key_attributes_s
338 {
339 psa_core_key_attributes_t MBEDTLS_PRIVATE(core);
340 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
341 psa_key_slot_number_t MBEDTLS_PRIVATE(slot_number);
342 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
343 void *MBEDTLS_PRIVATE(domain_parameters);
344 size_t MBEDTLS_PRIVATE(domain_parameters_size);
345 };
346
347 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
348 #define PSA_KEY_ATTRIBUTES_INIT { PSA_CORE_KEY_ATTRIBUTES_INIT, 0, NULL, 0 }
349 #else
350 #define PSA_KEY_ATTRIBUTES_INIT { PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0 }
351 #endif
352
psa_key_attributes_init(void)353 static inline struct psa_key_attributes_s psa_key_attributes_init( void )
354 {
355 const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
356 return( v );
357 }
358
psa_set_key_id(psa_key_attributes_t * attributes,mbedtls_svc_key_id_t key)359 static inline void psa_set_key_id( psa_key_attributes_t *attributes,
360 mbedtls_svc_key_id_t key )
361 {
362 psa_key_lifetime_t lifetime = attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(lifetime);
363
364 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(id) = key;
365
366 if( PSA_KEY_LIFETIME_IS_VOLATILE( lifetime ) )
367 {
368 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(lifetime) =
369 PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
370 PSA_KEY_LIFETIME_PERSISTENT,
371 PSA_KEY_LIFETIME_GET_LOCATION( lifetime ) );
372 }
373 }
374
psa_get_key_id(const psa_key_attributes_t * attributes)375 static inline mbedtls_svc_key_id_t psa_get_key_id(
376 const psa_key_attributes_t *attributes )
377 {
378 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(id) );
379 }
380
381 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
mbedtls_set_key_owner_id(psa_key_attributes_t * attributes,mbedtls_key_owner_id_t owner)382 static inline void mbedtls_set_key_owner_id( psa_key_attributes_t *attributes,
383 mbedtls_key_owner_id_t owner )
384 {
385 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(owner) = owner;
386 }
387 #endif
388
psa_set_key_lifetime(psa_key_attributes_t * attributes,psa_key_lifetime_t lifetime)389 static inline void psa_set_key_lifetime( psa_key_attributes_t *attributes,
390 psa_key_lifetime_t lifetime )
391 {
392 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(lifetime) = lifetime;
393 if( PSA_KEY_LIFETIME_IS_VOLATILE( lifetime ) )
394 {
395 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
396 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(key_id) = 0;
397 #else
398 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(id) = 0;
399 #endif
400 }
401 }
402
psa_get_key_lifetime(const psa_key_attributes_t * attributes)403 static inline psa_key_lifetime_t psa_get_key_lifetime(
404 const psa_key_attributes_t *attributes )
405 {
406 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(lifetime) );
407 }
408
psa_extend_key_usage_flags(psa_key_usage_t * usage_flags)409 static inline void psa_extend_key_usage_flags( psa_key_usage_t *usage_flags )
410 {
411 if( *usage_flags & PSA_KEY_USAGE_SIGN_HASH )
412 *usage_flags |= PSA_KEY_USAGE_SIGN_MESSAGE;
413
414 if( *usage_flags & PSA_KEY_USAGE_VERIFY_HASH )
415 *usage_flags |= PSA_KEY_USAGE_VERIFY_MESSAGE;
416 }
417
psa_set_key_usage_flags(psa_key_attributes_t * attributes,psa_key_usage_t usage_flags)418 static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
419 psa_key_usage_t usage_flags)
420 {
421 psa_extend_key_usage_flags( &usage_flags );
422 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage) = usage_flags;
423 }
424
psa_get_key_usage_flags(const psa_key_attributes_t * attributes)425 static inline psa_key_usage_t psa_get_key_usage_flags(
426 const psa_key_attributes_t *attributes )
427 {
428 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage) );
429 }
430
psa_set_key_algorithm(psa_key_attributes_t * attributes,psa_algorithm_t alg)431 static inline void psa_set_key_algorithm( psa_key_attributes_t *attributes,
432 psa_algorithm_t alg )
433 {
434 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg) = alg;
435 }
436
psa_get_key_algorithm(const psa_key_attributes_t * attributes)437 static inline psa_algorithm_t psa_get_key_algorithm(
438 const psa_key_attributes_t *attributes )
439 {
440 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg) );
441 }
442
443 /* This function is declared in crypto_extra.h, which comes after this
444 * header file, but we need the function here, so repeat the declaration. */
445 psa_status_t psa_set_key_domain_parameters( psa_key_attributes_t *attributes,
446 psa_key_type_t type,
447 const uint8_t *data,
448 size_t data_length );
449
psa_set_key_type(psa_key_attributes_t * attributes,psa_key_type_t type)450 static inline void psa_set_key_type( psa_key_attributes_t *attributes,
451 psa_key_type_t type )
452 {
453 if( attributes->MBEDTLS_PRIVATE(domain_parameters) == NULL )
454 {
455 /* Common case: quick path */
456 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(type) = type;
457 }
458 else
459 {
460 /* Call the bigger function to free the old domain paramteres.
461 * Ignore any errors which may arise due to type requiring
462 * non-default domain parameters, since this function can't
463 * report errors. */
464 (void) psa_set_key_domain_parameters( attributes, type, NULL, 0 );
465 }
466 }
467
psa_get_key_type(const psa_key_attributes_t * attributes)468 static inline psa_key_type_t psa_get_key_type(
469 const psa_key_attributes_t *attributes )
470 {
471 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(type) );
472 }
473
psa_set_key_bits(psa_key_attributes_t * attributes,size_t bits)474 static inline void psa_set_key_bits( psa_key_attributes_t *attributes,
475 size_t bits )
476 {
477 if( bits > PSA_MAX_KEY_BITS )
478 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(bits) = PSA_KEY_BITS_TOO_LARGE;
479 else
480 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(bits) = (psa_key_bits_t) bits;
481 }
482
psa_get_key_bits(const psa_key_attributes_t * attributes)483 static inline size_t psa_get_key_bits(
484 const psa_key_attributes_t *attributes )
485 {
486 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(bits) );
487 }
488
489 #ifdef __cplusplus
490 }
491 #endif
492
493 #endif /* PSA_CRYPTO_STRUCT_H */
494