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 TLS, multipart operation structures live independently from
39 * the key. This allows Mbed TLS 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 OR GPL-2.0-or-later
47 */
48
49#ifndef PSA_CRYPTO_STRUCT_H
50#define PSA_CRYPTO_STRUCT_H
51#include "mbedtls/private_access.h"
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57/*
58 * Include the build-time configuration information header. Here, we do not
59 * include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which
60 * is basically just an alias to it. This is to ease the maintenance of the
61 * TF-PSA-Crypto repository which has a different build system and
62 * configuration.
63 */
64#include "psa/build_info.h"
65
66/* Include the context definition for the compiled-in drivers for the primitive
67 * algorithms. */
68#include "psa/crypto_driver_contexts_primitives.h"
69
70struct psa_hash_operation_s {
71#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
72    mbedtls_psa_client_handle_t handle;
73#else
74    /** Unique ID indicating which driver got assigned to do the
75     * operation. Since driver contexts are driver-specific, swapping
76     * drivers halfway through the operation is not supported.
77     * ID values are auto-generated in psa_driver_wrappers.h.
78     * ID value zero means the context is not valid or not assigned to
79     * any driver (i.e. the driver context is not active, in use). */
80    unsigned int MBEDTLS_PRIVATE(id);
81    psa_driver_hash_context_t MBEDTLS_PRIVATE(ctx);
82#endif
83};
84#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
85#define PSA_HASH_OPERATION_INIT { 0 }
86#else
87#define PSA_HASH_OPERATION_INIT { 0, { 0 } }
88#endif
89static inline struct psa_hash_operation_s psa_hash_operation_init(void)
90{
91    const struct psa_hash_operation_s v = PSA_HASH_OPERATION_INIT;
92    return v;
93}
94
95struct psa_cipher_operation_s {
96#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
97    mbedtls_psa_client_handle_t handle;
98#else
99    /** Unique ID indicating which driver got assigned to do the
100     * operation. Since driver contexts are driver-specific, swapping
101     * drivers halfway through the operation is not supported.
102     * ID values are auto-generated in psa_crypto_driver_wrappers.h
103     * ID value zero means the context is not valid or not assigned to
104     * any driver (i.e. none of the driver contexts are active). */
105    unsigned int MBEDTLS_PRIVATE(id);
106
107    unsigned int MBEDTLS_PRIVATE(iv_required) : 1;
108    unsigned int MBEDTLS_PRIVATE(iv_set) : 1;
109
110    uint8_t MBEDTLS_PRIVATE(default_iv_length);
111
112    psa_driver_cipher_context_t MBEDTLS_PRIVATE(ctx);
113#endif
114};
115
116#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
117#define PSA_CIPHER_OPERATION_INIT { 0 }
118#else
119#define PSA_CIPHER_OPERATION_INIT { 0, 0, 0, 0, { 0 } }
120#endif
121static inline struct psa_cipher_operation_s psa_cipher_operation_init(void)
122{
123    const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT;
124    return v;
125}
126
127/* Include the context definition for the compiled-in drivers for the composite
128 * algorithms. */
129#include "psa/crypto_driver_contexts_composites.h"
130
131struct psa_mac_operation_s {
132#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
133    mbedtls_psa_client_handle_t handle;
134#else
135    /** Unique ID indicating which driver got assigned to do the
136     * operation. Since driver contexts are driver-specific, swapping
137     * drivers halfway through the operation is not supported.
138     * ID values are auto-generated in psa_driver_wrappers.h
139     * ID value zero means the context is not valid or not assigned to
140     * any driver (i.e. none of the driver contexts are active). */
141    unsigned int MBEDTLS_PRIVATE(id);
142    uint8_t MBEDTLS_PRIVATE(mac_size);
143    unsigned int MBEDTLS_PRIVATE(is_sign) : 1;
144    psa_driver_mac_context_t MBEDTLS_PRIVATE(ctx);
145#endif
146};
147
148#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
149#define PSA_MAC_OPERATION_INIT { 0 }
150#else
151#define PSA_MAC_OPERATION_INIT { 0, 0, 0, { 0 } }
152#endif
153static inline struct psa_mac_operation_s psa_mac_operation_init(void)
154{
155    const struct psa_mac_operation_s v = PSA_MAC_OPERATION_INIT;
156    return v;
157}
158
159struct psa_aead_operation_s {
160#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
161    mbedtls_psa_client_handle_t handle;
162#else
163    /** Unique ID indicating which driver got assigned to do the
164     * operation. Since driver contexts are driver-specific, swapping
165     * drivers halfway through the operation is not supported.
166     * ID values are auto-generated in psa_crypto_driver_wrappers.h
167     * ID value zero means the context is not valid or not assigned to
168     * any driver (i.e. none of the driver contexts are active). */
169    unsigned int MBEDTLS_PRIVATE(id);
170
171    psa_algorithm_t MBEDTLS_PRIVATE(alg);
172    psa_key_type_t MBEDTLS_PRIVATE(key_type);
173
174    size_t MBEDTLS_PRIVATE(ad_remaining);
175    size_t MBEDTLS_PRIVATE(body_remaining);
176
177    unsigned int MBEDTLS_PRIVATE(nonce_set) : 1;
178    unsigned int MBEDTLS_PRIVATE(lengths_set) : 1;
179    unsigned int MBEDTLS_PRIVATE(ad_started) : 1;
180    unsigned int MBEDTLS_PRIVATE(body_started) : 1;
181    unsigned int MBEDTLS_PRIVATE(is_encrypt) : 1;
182
183    psa_driver_aead_context_t MBEDTLS_PRIVATE(ctx);
184#endif
185};
186
187#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
188#define PSA_AEAD_OPERATION_INIT { 0 }
189#else
190#define PSA_AEAD_OPERATION_INIT { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, { 0 } }
191#endif
192static inline struct psa_aead_operation_s psa_aead_operation_init(void)
193{
194    const struct psa_aead_operation_s v = PSA_AEAD_OPERATION_INIT;
195    return v;
196}
197
198/* Include the context definition for the compiled-in drivers for the key
199 * derivation algorithms. */
200#include "psa/crypto_driver_contexts_key_derivation.h"
201
202struct psa_key_derivation_s {
203#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
204    mbedtls_psa_client_handle_t handle;
205#else
206    psa_algorithm_t MBEDTLS_PRIVATE(alg);
207    unsigned int MBEDTLS_PRIVATE(can_output_key) : 1;
208    size_t MBEDTLS_PRIVATE(capacity);
209    psa_driver_key_derivation_context_t MBEDTLS_PRIVATE(ctx);
210#endif
211};
212
213#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
214#define PSA_KEY_DERIVATION_OPERATION_INIT { 0 }
215#else
216/* This only zeroes out the first byte in the union, the rest is unspecified. */
217#define PSA_KEY_DERIVATION_OPERATION_INIT { 0, 0, 0, { 0 } }
218#endif
219static inline struct psa_key_derivation_s psa_key_derivation_operation_init(
220    void)
221{
222    const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT;
223    return v;
224}
225
226struct psa_key_production_parameters_s {
227    /* Future versions may add other fields in this structure. */
228    uint32_t flags;
229    uint8_t data[];
230};
231
232/** The default production parameters for key generation or key derivation.
233 *
234 * Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext()
235 * with `params=PSA_KEY_PRODUCTION_PARAMETERS_INIT` and
236 * `params_data_length == 0` is equivalent to
237 * calling psa_generate_key() or psa_key_derivation_output_key()
238 * respectively.
239 */
240#define PSA_KEY_PRODUCTION_PARAMETERS_INIT { 0 }
241
242struct psa_key_policy_s {
243    psa_key_usage_t MBEDTLS_PRIVATE(usage);
244    psa_algorithm_t MBEDTLS_PRIVATE(alg);
245    psa_algorithm_t MBEDTLS_PRIVATE(alg2);
246};
247typedef struct psa_key_policy_s psa_key_policy_t;
248
249#define PSA_KEY_POLICY_INIT { 0, 0, 0 }
250static inline struct psa_key_policy_s psa_key_policy_init(void)
251{
252    const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT;
253    return v;
254}
255
256/* The type used internally for key sizes.
257 * Public interfaces use size_t, but internally we use a smaller type. */
258typedef uint16_t psa_key_bits_t;
259/* The maximum value of the type used to represent bit-sizes.
260 * This is used to mark an invalid key size. */
261#define PSA_KEY_BITS_TOO_LARGE          ((psa_key_bits_t) -1)
262/* The maximum size of a key in bits.
263 * Currently defined as the maximum that can be represented, rounded down
264 * to a whole number of bytes.
265 * This is an uncast value so that it can be used in preprocessor
266 * conditionals. */
267#define PSA_MAX_KEY_BITS 0xfff8
268
269struct psa_key_attributes_s {
270#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
271    psa_key_slot_number_t MBEDTLS_PRIVATE(slot_number);
272    int MBEDTLS_PRIVATE(has_slot_number);
273#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
274    psa_key_type_t MBEDTLS_PRIVATE(type);
275    psa_key_bits_t MBEDTLS_PRIVATE(bits);
276    psa_key_lifetime_t MBEDTLS_PRIVATE(lifetime);
277    psa_key_policy_t MBEDTLS_PRIVATE(policy);
278    /* This type has a different layout in the client view wrt the
279     * service view of the key id, i.e. in service view usually is
280     * expected to have MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER defined
281     * thus adding an owner field to the standard psa_key_id_t. For
282     * implementations with client/service separation, this means the
283     * object will be marshalled through a transport channel and
284     * interpreted differently at each side of the transport. Placing
285     * it at the end of structures allows to interpret the structure
286     * at the client without reorganizing the memory layout of the
287     * struct
288     */
289    mbedtls_svc_key_id_t MBEDTLS_PRIVATE(id);
290};
291
292#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
293#define PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER 0, 0,
294#else
295#define PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER
296#endif
297#define PSA_KEY_ATTRIBUTES_INIT { PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER \
298                                      PSA_KEY_TYPE_NONE, 0,            \
299                                      PSA_KEY_LIFETIME_VOLATILE,       \
300                                      PSA_KEY_POLICY_INIT,             \
301                                      MBEDTLS_SVC_KEY_ID_INIT }
302
303static inline struct psa_key_attributes_s psa_key_attributes_init(void)
304{
305    const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
306    return v;
307}
308
309static inline void psa_set_key_id(psa_key_attributes_t *attributes,
310                                  mbedtls_svc_key_id_t key)
311{
312    psa_key_lifetime_t lifetime = attributes->MBEDTLS_PRIVATE(lifetime);
313
314    attributes->MBEDTLS_PRIVATE(id) = key;
315
316    if (PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)) {
317        attributes->MBEDTLS_PRIVATE(lifetime) =
318            PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
319                PSA_KEY_LIFETIME_PERSISTENT,
320                PSA_KEY_LIFETIME_GET_LOCATION(lifetime));
321    }
322}
323
324static inline mbedtls_svc_key_id_t psa_get_key_id(
325    const psa_key_attributes_t *attributes)
326{
327    return attributes->MBEDTLS_PRIVATE(id);
328}
329
330#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
331static inline void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes,
332                                            mbedtls_key_owner_id_t owner)
333{
334    attributes->MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(owner) = owner;
335}
336#endif
337
338static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes,
339                                        psa_key_lifetime_t lifetime)
340{
341    attributes->MBEDTLS_PRIVATE(lifetime) = lifetime;
342    if (PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)) {
343#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
344        attributes->MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(key_id) = 0;
345#else
346        attributes->MBEDTLS_PRIVATE(id) = 0;
347#endif
348    }
349}
350
351static inline psa_key_lifetime_t psa_get_key_lifetime(
352    const psa_key_attributes_t *attributes)
353{
354    return attributes->MBEDTLS_PRIVATE(lifetime);
355}
356
357static inline void psa_extend_key_usage_flags(psa_key_usage_t *usage_flags)
358{
359    if (*usage_flags & PSA_KEY_USAGE_SIGN_HASH) {
360        *usage_flags |= PSA_KEY_USAGE_SIGN_MESSAGE;
361    }
362
363    if (*usage_flags & PSA_KEY_USAGE_VERIFY_HASH) {
364        *usage_flags |= PSA_KEY_USAGE_VERIFY_MESSAGE;
365    }
366}
367
368static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
369                                           psa_key_usage_t usage_flags)
370{
371    psa_extend_key_usage_flags(&usage_flags);
372    attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage) = usage_flags;
373}
374
375static inline psa_key_usage_t psa_get_key_usage_flags(
376    const psa_key_attributes_t *attributes)
377{
378    return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage);
379}
380
381static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes,
382                                         psa_algorithm_t alg)
383{
384    attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg) = alg;
385}
386
387static inline psa_algorithm_t psa_get_key_algorithm(
388    const psa_key_attributes_t *attributes)
389{
390    return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg);
391}
392
393static inline void psa_set_key_type(psa_key_attributes_t *attributes,
394                                    psa_key_type_t type)
395{
396    attributes->MBEDTLS_PRIVATE(type) = type;
397}
398
399static inline psa_key_type_t psa_get_key_type(
400    const psa_key_attributes_t *attributes)
401{
402    return attributes->MBEDTLS_PRIVATE(type);
403}
404
405static inline void psa_set_key_bits(psa_key_attributes_t *attributes,
406                                    size_t bits)
407{
408    if (bits > PSA_MAX_KEY_BITS) {
409        attributes->MBEDTLS_PRIVATE(bits) = PSA_KEY_BITS_TOO_LARGE;
410    } else {
411        attributes->MBEDTLS_PRIVATE(bits) = (psa_key_bits_t) bits;
412    }
413}
414
415static inline size_t psa_get_key_bits(
416    const psa_key_attributes_t *attributes)
417{
418    return attributes->MBEDTLS_PRIVATE(bits);
419}
420
421/**
422 * \brief The context for PSA interruptible hash signing.
423 */
424struct psa_sign_hash_interruptible_operation_s {
425#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
426    mbedtls_psa_client_handle_t handle;
427#else
428    /** Unique ID indicating which driver got assigned to do the
429     * operation. Since driver contexts are driver-specific, swapping
430     * drivers halfway through the operation is not supported.
431     * ID values are auto-generated in psa_crypto_driver_wrappers.h
432     * ID value zero means the context is not valid or not assigned to
433     * any driver (i.e. none of the driver contexts are active). */
434    unsigned int MBEDTLS_PRIVATE(id);
435
436    psa_driver_sign_hash_interruptible_context_t MBEDTLS_PRIVATE(ctx);
437
438    unsigned int MBEDTLS_PRIVATE(error_occurred) : 1;
439
440    uint32_t MBEDTLS_PRIVATE(num_ops);
441#endif
442};
443
444#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
445#define PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT { 0 }
446#else
447#define PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT { 0, { 0 }, 0, 0 }
448#endif
449
450static inline struct psa_sign_hash_interruptible_operation_s
451psa_sign_hash_interruptible_operation_init(void)
452{
453    const struct psa_sign_hash_interruptible_operation_s v =
454        PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT;
455
456    return v;
457}
458
459/**
460 * \brief The context for PSA interruptible hash verification.
461 */
462struct psa_verify_hash_interruptible_operation_s {
463#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
464    mbedtls_psa_client_handle_t handle;
465#else
466    /** Unique ID indicating which driver got assigned to do the
467     * operation. Since driver contexts are driver-specific, swapping
468     * drivers halfway through the operation is not supported.
469     * ID values are auto-generated in psa_crypto_driver_wrappers.h
470     * ID value zero means the context is not valid or not assigned to
471     * any driver (i.e. none of the driver contexts are active). */
472    unsigned int MBEDTLS_PRIVATE(id);
473
474    psa_driver_verify_hash_interruptible_context_t MBEDTLS_PRIVATE(ctx);
475
476    unsigned int MBEDTLS_PRIVATE(error_occurred) : 1;
477
478    uint32_t MBEDTLS_PRIVATE(num_ops);
479#endif
480};
481
482#if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C)
483#define PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT { 0 }
484#else
485#define PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT { 0, { 0 }, 0, 0 }
486#endif
487
488static inline struct psa_verify_hash_interruptible_operation_s
489psa_verify_hash_interruptible_operation_init(void)
490{
491    const struct psa_verify_hash_interruptible_operation_s v =
492        PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT;
493
494    return v;
495}
496
497#ifdef __cplusplus
498}
499#endif
500
501#endif /* PSA_CRYPTO_STRUCT_H */
502