NCBI C++ ToolKit
crypto_types.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 /**
2  * \file psa/crypto_types.h
3  *
4  * \brief PSA cryptography module: type aliases.
5  *
6  * \note This file may not be included directly. Applications must
7  * include psa/crypto.h. Drivers must include the appropriate driver
8  * header file.
9  *
10  * This file contains portable definitions of integral types for properties
11  * of cryptographic keys, designations of cryptographic algorithms, and
12  * error codes returned by the library.
13  *
14  * This header file does not declare any function.
15  */
16 /*
17  * Copyright The Mbed TLS Contributors
18  * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
19  */
20 
21 #ifndef PSA_CRYPTO_TYPES_H
22 #define PSA_CRYPTO_TYPES_H
23 
24 /*
25  * Include the build-time configuration information header. Here, we do not
26  * include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which
27  * is basically just an alias to it. This is to ease the maintenance of the
28  * TF-PSA-Crypto repository which has a different build system and
29  * configuration.
30  */
31 #include "psa/build_info.h"
32 
33 /* Define the MBEDTLS_PRIVATE macro. */
34 #include "mbedtls/private_access.h"
35 
36 #if defined(MBEDTLS_PSA_CRYPTO_PLATFORM_FILE)
37 #include MBEDTLS_PSA_CRYPTO_PLATFORM_FILE
38 #else
39 #include "crypto_platform.h"
40 #endif
41 
42 #include <stdint.h>
43 
44 /** \defgroup error Error codes
45  * @{
46  */
47 
48 /**
49  * \brief Function return status.
50  *
51  * This is either #PSA_SUCCESS (which is zero), indicating success,
52  * or a small negative value indicating that an error occurred. Errors are
53  * encoded as one of the \c PSA_ERROR_xxx values defined here. */
54 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t
55  * is also defined in an external header, so prevent its multiple
56  * definition.
57  */
58 #ifndef PSA_SUCCESS
60 #endif
61 
62 /**@}*/
63 
64 /** \defgroup crypto_types Key and algorithm types
65  * @{
66  */
67 
68 /** \brief Encoding of a key type.
69  *
70  * Values of this type are generally constructed by macros called
71  * `PSA_KEY_TYPE_xxx`.
72  *
73  * \note Values of this type are encoded in the persistent key store.
74  * Any changes to existing values will require bumping the storage
75  * format version and providing a translation when reading the old
76  * format.
77  */
79 
80 /** The type of PSA elliptic curve family identifiers.
81  *
82  * Values of this type are generally constructed by macros called
83  * `PSA_ECC_FAMILY_xxx`.
84  *
85  * The curve identifier is required to create an ECC key using the
86  * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
87  * macros.
88  *
89  * Values defined by this standard will never be in the range 0x80-0xff.
90  * Vendors who define additional families must use an encoding in this range.
91  *
92  * \note Values of this type are encoded in the persistent key store.
93  * Any changes to existing values will require bumping the storage
94  * format version and providing a translation when reading the old
95  * format.
96  */
98 
99 /** The type of PSA Diffie-Hellman group family identifiers.
100  *
101  * Values of this type are generally constructed by macros called
102  * `PSA_DH_FAMILY_xxx`.
103  *
104  * The group identifier is required to create a Diffie-Hellman key using the
105  * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
106  * macros.
107  *
108  * Values defined by this standard will never be in the range 0x80-0xff.
109  * Vendors who define additional families must use an encoding in this range.
110  *
111  * \note Values of this type are encoded in the persistent key store.
112  * Any changes to existing values will require bumping the storage
113  * format version and providing a translation when reading the old
114  * format.
115  */
117 
118 /** \brief Encoding of a cryptographic algorithm.
119  *
120  * Values of this type are generally constructed by macros called
121  * `PSA_ALG_xxx`.
122  *
123  * For algorithms that can be applied to multiple key types, this type
124  * does not encode the key type. For example, for symmetric ciphers
125  * based on a block cipher, #psa_algorithm_t encodes the block cipher
126  * mode and the padding mode while the block cipher itself is encoded
127  * via #psa_key_type_t.
128  *
129  * \note Values of this type are encoded in the persistent key store.
130  * Any changes to existing values will require bumping the storage
131  * format version and providing a translation when reading the old
132  * format.
133  */
135 
136 /**@}*/
137 
138 /** \defgroup key_lifetimes Key lifetimes
139  * @{
140  */
141 
142 /** Encoding of key lifetimes.
143  *
144  * The lifetime of a key indicates where it is stored and what system actions
145  * may create and destroy it.
146  *
147  * Lifetime values have the following structure:
148  * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)):
149  * persistence level. This value indicates what device management
150  * actions can cause it to be destroyed. In particular, it indicates
151  * whether the key is _volatile_ or _persistent_.
152  * See ::psa_key_persistence_t for more information.
153  * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)):
154  * location indicator. This value indicates which part of the system
155  * has access to the key material and can perform operations using the key.
156  * See ::psa_key_location_t for more information.
157  *
158  * Volatile keys are automatically destroyed when the application instance
159  * terminates or on a power reset of the device. Persistent keys are
160  * preserved until the application explicitly destroys them or until an
161  * integration-specific device management event occurs (for example,
162  * a factory reset).
163  *
164  * Persistent keys have a key identifier of type #mbedtls_svc_key_id_t.
165  * This identifier remains valid throughout the lifetime of the key,
166  * even if the application instance that created the key terminates.
167  * The application can call psa_open_key() to open a persistent key that
168  * it created previously.
169  *
170  * The default lifetime of a key is #PSA_KEY_LIFETIME_VOLATILE. The lifetime
171  * #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is
172  * available. Other lifetime values may be supported depending on the
173  * library configuration.
174  *
175  * Values of this type are generally constructed by macros called
176  * `PSA_KEY_LIFETIME_xxx`.
177  *
178  * \note Values of this type are encoded in the persistent key store.
179  * Any changes to existing values will require bumping the storage
180  * format version and providing a translation when reading the old
181  * format.
182  */
184 
185 /** Encoding of key persistence levels.
186  *
187  * What distinguishes different persistence levels is what device management
188  * events may cause keys to be destroyed. _Volatile_ keys are destroyed
189  * by a power reset. Persistent keys may be destroyed by events such as
190  * a transfer of ownership or a factory reset. What management events
191  * actually affect persistent keys at different levels is outside the
192  * scope of the PSA Cryptography specification.
193  *
194  * The PSA Cryptography specification defines the following values of
195  * persistence levels:
196  * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key.
197  * A volatile key is automatically destroyed by the implementation when
198  * the application instance terminates. In particular, a volatile key
199  * is automatically destroyed on a power reset of the device.
200  * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT:
201  * persistent key with a default lifetime.
202  * - \c 2-254: currently not supported by Mbed TLS.
203  * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY:
204  * read-only or write-once key.
205  * A key with this persistence level cannot be destroyed.
206  * Mbed TLS does not currently offer a way to create such keys, but
207  * integrations of Mbed TLS can use it for built-in keys that the
208  * application cannot modify (for example, a hardware unique key (HUK)).
209  *
210  * \note Key persistence levels are 8-bit values. Key management
211  * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
212  * encode the persistence as the lower 8 bits of a 32-bit value.
213  *
214  * \note Values of this type are encoded in the persistent key store.
215  * Any changes to existing values will require bumping the storage
216  * format version and providing a translation when reading the old
217  * format.
218  */
220 
221 /** Encoding of key location indicators.
222  *
223  * If an integration of Mbed TLS can make calls to external
224  * cryptoprocessors such as secure elements, the location of a key
225  * indicates which secure element performs the operations on the key.
226  * Depending on the design of the secure element, the key
227  * material may be stored either in the secure element, or
228  * in wrapped (encrypted) form alongside the key metadata in the
229  * primary local storage.
230  *
231  * The PSA Cryptography API specification defines the following values of
232  * location indicators:
233  * - \c 0: primary local storage.
234  * This location is always available.
235  * The primary local storage is typically the same storage area that
236  * contains the key metadata.
237  * - \c 1: primary secure element.
238  * Integrations of Mbed TLS should support this value if there is a secure
239  * element attached to the operating environment.
240  * As a guideline, secure elements may provide higher resistance against
241  * side channel and physical attacks than the primary local storage, but may
242  * have restrictions on supported key types, sizes, policies and operations
243  * and may have different performance characteristics.
244  * - \c 2-0x7fffff: other locations defined by a PSA specification.
245  * The PSA Cryptography API does not currently assign any meaning to these
246  * locations, but future versions of that specification or other PSA
247  * specifications may do so.
248  * - \c 0x800000-0xffffff: vendor-defined locations.
249  * No PSA specification will assign a meaning to locations in this range.
250  *
251  * \note Key location indicators are 24-bit values. Key management
252  * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
253  * encode the location as the upper 24 bits of a 32-bit value.
254  *
255  * \note Values of this type are encoded in the persistent key store.
256  * Any changes to existing values will require bumping the storage
257  * format version and providing a translation when reading the old
258  * format.
259  */
261 
262 /** Encoding of identifiers of persistent keys.
263  *
264  * - Applications may freely choose key identifiers in the range
265  * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX.
266  * - The implementation may define additional key identifiers in the range
267  * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX.
268  * - 0 is reserved as an invalid key identifier.
269  * - Key identifiers outside these ranges are reserved for future use.
270  *
271  * \note Values of this type are encoded in the persistent key store.
272  * Any changes to how values are allocated must require careful
273  * consideration to allow backward compatibility.
274  */
276 
277 /** Encoding of key identifiers as seen inside the PSA Crypto implementation.
278  *
279  * When PSA Crypto is built as a library inside an application, this type
280  * is identical to #psa_key_id_t. When PSA Crypto is built as a service
281  * that can store keys on behalf of multiple clients, this type
282  * encodes the #psa_key_id_t value seen by each client application as
283  * well as extra information that identifies the client that owns
284  * the key.
285  *
286  * \note Values of this type are encoded in the persistent key store.
287  * Any changes to existing values will require bumping the storage
288  * format version and providing a translation when reading the old
289  * format.
290  */
291 #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
293 
294 #else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
295 /* Implementation-specific: The Mbed TLS library can be built as
296  * part of a multi-client service that exposes the PSA Cryptography API in each
297  * client and encodes the client identity in the key identifier argument of
298  * functions such as psa_open_key().
299  */
300 typedef struct {
302  mbedtls_key_owner_id_t MBEDTLS_PRIVATE(owner);
304 
305 #endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
306 
307 /**@}*/
308 
309 /** \defgroup policy Key policies
310  * @{
311  */
312 
313 /** \brief Encoding of permitted usage on a key.
314  *
315  * Values of this type are generally constructed as bitwise-ors of macros
316  * called `PSA_KEY_USAGE_xxx`.
317  *
318  * \note Values of this type are encoded in the persistent key store.
319  * Any changes to existing values will require bumping the storage
320  * format version and providing a translation when reading the old
321  * format.
322  */
324 
325 /**@}*/
326 
327 /** \defgroup attributes Key attributes
328  * @{
329  */
330 
331 /** The type of a structure containing key attributes.
332  *
333  * This is an opaque structure that can represent the metadata of a key
334  * object. Metadata that can be stored in attributes includes:
335  * - The location of the key in storage, indicated by its key identifier
336  * and its lifetime.
337  * - The key's policy, comprising usage flags and a specification of
338  * the permitted algorithm(s).
339  * - Information about the key itself: the key type and its size.
340  * - Additional implementation-defined attributes.
341  *
342  * The actual key material is not considered an attribute of a key.
343  * Key attributes do not contain information that is generally considered
344  * highly confidential.
345  *
346  * An attribute structure works like a simple data structure where each function
347  * `psa_set_key_xxx` sets a field and the corresponding function
348  * `psa_get_key_xxx` retrieves the value of the corresponding field.
349  * However, a future version of the library may report values that are
350  * equivalent to the original one, but have a different encoding. Invalid
351  * values may be mapped to different, also invalid values.
352  *
353  * An attribute structure may contain references to auxiliary resources,
354  * for example pointers to allocated memory or indirect references to
355  * pre-calculated values. In order to free such resources, the application
356  * must call psa_reset_key_attributes(). As an exception, calling
357  * psa_reset_key_attributes() on an attribute structure is optional if
358  * the structure has only been modified by the following functions
359  * since it was initialized or last reset with psa_reset_key_attributes():
360  * - psa_set_key_id()
361  * - psa_set_key_lifetime()
362  * - psa_set_key_type()
363  * - psa_set_key_bits()
364  * - psa_set_key_usage_flags()
365  * - psa_set_key_algorithm()
366  *
367  * Before calling any function on a key attribute structure, the application
368  * must initialize it by any of the following means:
369  * - Set the structure to all-bits-zero, for example:
370  * \code
371  * psa_key_attributes_t attributes;
372  * memset(&attributes, 0, sizeof(attributes));
373  * \endcode
374  * - Initialize the structure to logical zero values, for example:
375  * \code
376  * psa_key_attributes_t attributes = {0};
377  * \endcode
378  * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
379  * for example:
380  * \code
381  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
382  * \endcode
383  * - Assign the result of the function psa_key_attributes_init()
384  * to the structure, for example:
385  * \code
386  * psa_key_attributes_t attributes;
387  * attributes = psa_key_attributes_init();
388  * \endcode
389  *
390  * A freshly initialized attribute structure contains the following
391  * values:
392  *
393  * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
394  * - key identifier: 0 (which is not a valid key identifier).
395  * - type: \c 0 (meaning that the type is unspecified).
396  * - key size: \c 0 (meaning that the size is unspecified).
397  * - usage flags: \c 0 (which allows no usage except exporting a public key).
398  * - algorithm: \c 0 (which allows no cryptographic usage, but allows
399  * exporting).
400  *
401  * A typical sequence to create a key is as follows:
402  * -# Create and initialize an attribute structure.
403  * -# If the key is persistent, call psa_set_key_id().
404  * Also call psa_set_key_lifetime() to place the key in a non-default
405  * location.
406  * -# Set the key policy with psa_set_key_usage_flags() and
407  * psa_set_key_algorithm().
408  * -# Set the key type with psa_set_key_type().
409  * Skip this step if copying an existing key with psa_copy_key().
410  * -# When generating a random key with psa_generate_key() or deriving a key
411  * with psa_key_derivation_output_key(), set the desired key size with
412  * psa_set_key_bits().
413  * -# Call a key creation function: psa_import_key(), psa_generate_key(),
414  * psa_key_derivation_output_key() or psa_copy_key(). This function reads
415  * the attribute structure, creates a key with these attributes, and
416  * outputs a key identifier to the newly created key.
417  * -# The attribute structure is now no longer necessary.
418  * You may call psa_reset_key_attributes(), although this is optional
419  * with the workflow presented here because the attributes currently
420  * defined in this specification do not require any additional resources
421  * beyond the structure itself.
422  *
423  * A typical sequence to query a key's attributes is as follows:
424  * -# Call psa_get_key_attributes().
425  * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
426  * you are interested in.
427  * -# Call psa_reset_key_attributes() to free any resources that may be
428  * used by the attribute structure.
429  *
430  * Once a key has been created, it is impossible to change its attributes.
431  */
433 
434 
435 #ifndef __DOXYGEN_ONLY__
436 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
437 /* Mbed TLS defines this type in crypto_types.h because it is also
438  * visible to applications through an implementation-specific extension.
439  * For the PSA Cryptography specification, this type is only visible
440  * via crypto_se_driver.h. */
442 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
443 #endif /* !__DOXYGEN_ONLY__ */
444 
445 /**@}*/
446 
447 /** \defgroup derivation Key derivation
448  * @{
449  */
450 
451 /** \brief Encoding of the step of a key derivation.
452  *
453  * Values of this type are generally constructed by macros called
454  * `PSA_KEY_DERIVATION_INPUT_xxx`.
455  */
457 
458 /** \brief Custom parameters for key generation or key derivation.
459  *
460  * This is a structure type with at least the following fields:
461  *
462  * - \c flags: an unsigned integer type. 0 for the default production parameters.
463  * - \c data: a flexible array of bytes.
464  *
465  * The interpretation of this structure depend on the type of the
466  * created key.
467  *
468  * - #PSA_KEY_TYPE_RSA_KEY_PAIR:
469  * - \c flags: must be 0.
470  * - \c data: the public exponent, in little-endian order.
471  * This must be an odd integer and must not be 1.
472  * Implementations must support 65537, should support 3 and may
473  * support other values.
474  * When not using a driver, Mbed TLS supports values up to \c INT_MAX.
475  * If this is empty or if the custom production parameters are omitted
476  * altogether, the default value 65537 is used.
477  * - Other key types: reserved for future use. \c flags must be 0.
478  *
479  */
481 
482 /**@}*/
483 
484 #endif /* PSA_CRYPTO_TYPES_H */
PSA cryptography module: Mbed TLS platform definitions.
Uint8 uint64_t
Int4 int32_t
unsigned char uint8_t
Uint2 uint16_t
Uint4 uint32_t
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:78
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:134
uint8_t psa_ecc_family_t
The type of PSA elliptic curve family identifiers.
Definition: crypto_types.h:97
uint8_t psa_dh_family_t
The type of PSA Diffie-Hellman group family identifiers.
Definition: crypto_types.h:116
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
Definition: crypto_types.h:456
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:59
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
Definition: crypto_types.h:275
uint8_t psa_key_persistence_t
Encoding of key persistence levels.
Definition: crypto_types.h:219
uint32_t psa_key_location_t
Encoding of key location indicators.
Definition: crypto_types.h:260
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
Definition: crypto_types.h:183
psa_key_id_t mbedtls_svc_key_id_t
Encoding of key identifiers as seen inside the PSA Crypto implementation.
Definition: crypto_types.h:292
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: crypto_types.h:323
uint64_t psa_key_slot_number_t
An internal designation of a key slot between the core part of the PSA Crypto implementation and the ...
Macro wrapper for struct's members.
#define MBEDTLS_PRIVATE(member)
Build-time PSA configuration info.
Modified on Sat Jul 20 11:08:35 2024 by modify_doxy.py rev. 669887