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
19  *
20  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
21  *  not use this file except in compliance with the License.
22  *  You may obtain a copy of the License at
23  *
24  *  http://www.apache.org/licenses/LICENSE-2.0
25  *
26  *  Unless required by applicable law or agreed to in writing, software
27  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
28  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29  *  See the License for the specific language governing permissions and
30  *  limitations under the License.
31  */
32 
33 #ifndef PSA_CRYPTO_TYPES_H
34 #define PSA_CRYPTO_TYPES_H
35 #include "mbedtls/private_access.h"
36 
37 #include "crypto_platform.h"
38 
39 /* If MBEDTLS_PSA_CRYPTO_C is defined, make sure MBEDTLS_PSA_CRYPTO_CLIENT
40  * is defined as well to include all PSA code.
41  */
42 #if defined(MBEDTLS_PSA_CRYPTO_C)
43 #define MBEDTLS_PSA_CRYPTO_CLIENT
44 #endif /* MBEDTLS_PSA_CRYPTO_C */
45 
46 #include <stdint.h>
47 
48 /** \defgroup error Error codes
49  * @{
50  */
51 
52 /**
53  * \brief Function return status.
54  *
55  * This is either #PSA_SUCCESS (which is zero), indicating success,
56  * or a small negative value indicating that an error occurred. Errors are
57  * encoded as one of the \c PSA_ERROR_xxx values defined here. */
58 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t
59  * is also defined in an external header, so prevent its multiple
60  * definition.
61  */
62 #ifndef PSA_SUCCESS
63 typedef int32_t psa_status_t;
64 #endif
65 
66 /**@}*/
67 
68 /** \defgroup crypto_types Key and algorithm types
69  * @{
70  */
71 
72 /** \brief Encoding of a key type.
73  */
74 typedef uint16_t psa_key_type_t;
75 
76 /** The type of PSA elliptic curve family identifiers.
77  *
78  * The curve identifier is required to create an ECC key using the
79  * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
80  * macros.
81  *
82  * Values defined by this standard will never be in the range 0x80-0xff.
83  * Vendors who define additional families must use an encoding in this range.
84  */
85 typedef uint8_t psa_ecc_family_t;
86 
87 /** The type of PSA Diffie-Hellman group family identifiers.
88  *
89  * The group identifier is required to create an Diffie-Hellman key using the
90  * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
91  * macros.
92  *
93  * Values defined by this standard will never be in the range 0x80-0xff.
94  * Vendors who define additional families must use an encoding in this range.
95  */
96 typedef uint8_t psa_dh_family_t;
97 
98 /** \brief Encoding of a cryptographic algorithm.
99  *
100  * For algorithms that can be applied to multiple key types, this type
101  * does not encode the key type. For example, for symmetric ciphers
102  * based on a block cipher, #psa_algorithm_t encodes the block cipher
103  * mode and the padding mode while the block cipher itself is encoded
104  * via #psa_key_type_t.
105  */
106 typedef uint32_t psa_algorithm_t;
107 
108 /**@}*/
109 
110 /** \defgroup key_lifetimes Key lifetimes
111  * @{
112  */
113 
114 /** Encoding of key lifetimes.
115  *
116  * The lifetime of a key indicates where it is stored and what system actions
117  * may create and destroy it.
118  *
119  * Lifetime values have the following structure:
120  * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)):
121  *   persistence level. This value indicates what device management
122  *   actions can cause it to be destroyed. In particular, it indicates
123  *   whether the key is _volatile_ or _persistent_.
124  *   See ::psa_key_persistence_t for more information.
125  * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)):
126  *   location indicator. This value indicates which part of the system
127  *   has access to the key material and can perform operations using the key.
128  *   See ::psa_key_location_t for more information.
129  *
130  * Volatile keys are automatically destroyed when the application instance
131  * terminates or on a power reset of the device. Persistent keys are
132  * preserved until the application explicitly destroys them or until an
133  * integration-specific device management event occurs (for example,
134  * a factory reset).
135  *
136  * Persistent keys have a key identifier of type #mbedtls_svc_key_id_t.
137  * This identifier remains valid throughout the lifetime of the key,
138  * even if the application instance that created the key terminates.
139  * The application can call psa_open_key() to open a persistent key that
140  * it created previously.
141  *
142  * The default lifetime of a key is #PSA_KEY_LIFETIME_VOLATILE. The lifetime
143  * #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is
144  * available. Other lifetime values may be supported depending on the
145  * library configuration.
146  */
147 typedef uint32_t psa_key_lifetime_t;
148 
149 /** Encoding of key persistence levels.
150  *
151  * What distinguishes different persistence levels is what device management
152  * events may cause keys to be destroyed. _Volatile_ keys are destroyed
153  * by a power reset. Persistent keys may be destroyed by events such as
154  * a transfer of ownership or a factory reset. What management events
155  * actually affect persistent keys at different levels is outside the
156  * scope of the PSA Cryptography specification.
157  *
158  * The PSA Cryptography specification defines the following values of
159  * persistence levels:
160  * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key.
161  *   A volatile key is automatically destroyed by the implementation when
162  *   the application instance terminates. In particular, a volatile key
163  *   is automatically destroyed on a power reset of the device.
164  * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT:
165  *   persistent key with a default lifetime.
166  * - \c 2-254: currently not supported by Mbed TLS.
167  * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY:
168  *   read-only or write-once key.
169  *   A key with this persistence level cannot be destroyed.
170  *   Mbed TLS does not currently offer a way to create such keys, but
171  *   integrations of Mbed TLS can use it for built-in keys that the
172  *   application cannot modify (for example, a hardware unique key (HUK)).
173  *
174  * \note Key persistence levels are 8-bit values. Key management
175  *       interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
176  *       encode the persistence as the lower 8 bits of a 32-bit value.
177  */
178 typedef uint8_t psa_key_persistence_t;
179 
180 /** Encoding of key location indicators.
181  *
182  * If an integration of Mbed TLS can make calls to external
183  * cryptoprocessors such as secure elements, the location of a key
184  * indicates which secure element performs the operations on the key.
185  * Depending on the design of the secure element, the key
186  * material may be stored either in the secure element, or
187  * in wrapped (encrypted) form alongside the key metadata in the
188  * primary local storage.
189  *
190  * The PSA Cryptography API specification defines the following values of
191  * location indicators:
192  * - \c 0: primary local storage.
193  *   This location is always available.
194  *   The primary local storage is typically the same storage area that
195  *   contains the key metadata.
196  * - \c 1: primary secure element.
197  *   Integrations of Mbed TLS should support this value if there is a secure
198  *   element attached to the operating environment.
199  *   As a guideline, secure elements may provide higher resistance against
200  *   side channel and physical attacks than the primary local storage, but may
201  *   have restrictions on supported key types, sizes, policies and operations
202  *   and may have different performance characteristics.
203  * - \c 2-0x7fffff: other locations defined by a PSA specification.
204  *   The PSA Cryptography API does not currently assign any meaning to these
205  *   locations, but future versions of that specification or other PSA
206  *   specifications may do so.
207  * - \c 0x800000-0xffffff: vendor-defined locations.
208  *   No PSA specification will assign a meaning to locations in this range.
209  *
210  * \note Key location indicators are 24-bit values. Key management
211  *       interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
212  *       encode the location as the upper 24 bits of a 32-bit value.
213  */
214 typedef uint32_t psa_key_location_t;
215 
216 /** Encoding of identifiers of persistent keys.
217  *
218  * - Applications may freely choose key identifiers in the range
219  *   #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX.
220  * - The implementation may define additional key identifiers in the range
221  *   #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX.
222  * - 0 is reserved as an invalid key identifier.
223  * - Key identifiers outside these ranges are reserved for future use.
224  */
225 typedef uint32_t psa_key_id_t;
226 
227 #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
228 typedef psa_key_id_t mbedtls_svc_key_id_t;
229 
230 #else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
231 /* Implementation-specific: The Mbed Cryptography library can be built as
232  * part of a multi-client service that exposes the PSA Cryptograpy API in each
233  * client and encodes the client identity in the key identifier argument of
234  * functions such as psa_open_key().
235  */
236 typedef struct
237 {
238     psa_key_id_t MBEDTLS_PRIVATE(key_id);
239     mbedtls_key_owner_id_t MBEDTLS_PRIVATE(owner);
240 } mbedtls_svc_key_id_t;
241 
242 #endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
243 
244 /**@}*/
245 
246 /** \defgroup policy Key policies
247  * @{
248  */
249 
250 /** \brief Encoding of permitted usage on a key. */
251 typedef uint32_t psa_key_usage_t;
252 
253 /**@}*/
254 
255 /** \defgroup attributes Key attributes
256  * @{
257  */
258 
259 /** The type of a structure containing key attributes.
260  *
261  * This is an opaque structure that can represent the metadata of a key
262  * object. Metadata that can be stored in attributes includes:
263  * - The location of the key in storage, indicated by its key identifier
264  *   and its lifetime.
265  * - The key's policy, comprising usage flags and a specification of
266  *   the permitted algorithm(s).
267  * - Information about the key itself: the key type and its size.
268  * - Additional implementation-defined attributes.
269  *
270  * The actual key material is not considered an attribute of a key.
271  * Key attributes do not contain information that is generally considered
272  * highly confidential.
273  *
274  * An attribute structure works like a simple data structure where each function
275  * `psa_set_key_xxx` sets a field and the corresponding function
276  * `psa_get_key_xxx` retrieves the value of the corresponding field.
277  * However, a future version of the library  may report values that are
278  * equivalent to the original one, but have a different encoding. Invalid
279  * values may be mapped to different, also invalid values.
280  *
281  * An attribute structure may contain references to auxiliary resources,
282  * for example pointers to allocated memory or indirect references to
283  * pre-calculated values. In order to free such resources, the application
284  * must call psa_reset_key_attributes(). As an exception, calling
285  * psa_reset_key_attributes() on an attribute structure is optional if
286  * the structure has only been modified by the following functions
287  * since it was initialized or last reset with psa_reset_key_attributes():
288  * - psa_set_key_id()
289  * - psa_set_key_lifetime()
290  * - psa_set_key_type()
291  * - psa_set_key_bits()
292  * - psa_set_key_usage_flags()
293  * - psa_set_key_algorithm()
294  *
295  * Before calling any function on a key attribute structure, the application
296  * must initialize it by any of the following means:
297  * - Set the structure to all-bits-zero, for example:
298  *   \code
299  *   psa_key_attributes_t attributes;
300  *   memset(&attributes, 0, sizeof(attributes));
301  *   \endcode
302  * - Initialize the structure to logical zero values, for example:
303  *   \code
304  *   psa_key_attributes_t attributes = {0};
305  *   \endcode
306  * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
307  *   for example:
308  *   \code
309  *   psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
310  *   \endcode
311  * - Assign the result of the function psa_key_attributes_init()
312  *   to the structure, for example:
313  *   \code
314  *   psa_key_attributes_t attributes;
315  *   attributes = psa_key_attributes_init();
316  *   \endcode
317  *
318  * A freshly initialized attribute structure contains the following
319  * values:
320  *
321  * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
322  * - key identifier: 0 (which is not a valid key identifier).
323  * - type: \c 0 (meaning that the type is unspecified).
324  * - key size: \c 0 (meaning that the size is unspecified).
325  * - usage flags: \c 0 (which allows no usage except exporting a public key).
326  * - algorithm: \c 0 (which allows no cryptographic usage, but allows
327  *   exporting).
328  *
329  * A typical sequence to create a key is as follows:
330  * -# Create and initialize an attribute structure.
331  * -# If the key is persistent, call psa_set_key_id().
332  *    Also call psa_set_key_lifetime() to place the key in a non-default
333  *    location.
334  * -# Set the key policy with psa_set_key_usage_flags() and
335  *    psa_set_key_algorithm().
336  * -# Set the key type with psa_set_key_type().
337  *    Skip this step if copying an existing key with psa_copy_key().
338  * -# When generating a random key with psa_generate_key() or deriving a key
339  *    with psa_key_derivation_output_key(), set the desired key size with
340  *    psa_set_key_bits().
341  * -# Call a key creation function: psa_import_key(), psa_generate_key(),
342  *    psa_key_derivation_output_key() or psa_copy_key(). This function reads
343  *    the attribute structure, creates a key with these attributes, and
344  *    outputs a key identifier to the newly created key.
345  * -# The attribute structure is now no longer necessary.
346  *    You may call psa_reset_key_attributes(), although this is optional
347  *    with the workflow presented here because the attributes currently
348  *    defined in this specification do not require any additional resources
349  *    beyond the structure itself.
350  *
351  * A typical sequence to query a key's attributes is as follows:
352  * -# Call psa_get_key_attributes().
353  * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
354  *    you are interested in.
355  * -# Call psa_reset_key_attributes() to free any resources that may be
356  *    used by the attribute structure.
357  *
358  * Once a key has been created, it is impossible to change its attributes.
359  */
360 typedef struct psa_key_attributes_s psa_key_attributes_t;
361 
362 
363 #ifndef __DOXYGEN_ONLY__
364 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
365 /* Mbed Crypto defines this type in crypto_types.h because it is also
366  * visible to applications through an implementation-specific extension.
367  * For the PSA Cryptography specification, this type is only visible
368  * via crypto_se_driver.h. */
369 typedef uint64_t psa_key_slot_number_t;
370 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
371 #endif /* !__DOXYGEN_ONLY__ */
372 
373 /**@}*/
374 
375 /** \defgroup derivation Key derivation
376  * @{
377  */
378 
379 /** \brief Encoding of the step of a key derivation. */
380 typedef uint16_t psa_key_derivation_step_t;
381 
382 /**@}*/
383 
384 #endif /* PSA_CRYPTO_TYPES_H */
385