Mistake on this page?
Report an issue in GitHub or email us
TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h
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 (C) 2018, ARM Limited, All Rights Reserved
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  * This file is part of mbed TLS (https://tls.mbed.org)
33  */
34 
35 #ifndef PSA_CRYPTO_TYPES_H
36 #define PSA_CRYPTO_TYPES_H
37 
38 #include <stdint.h>
39 
40 /** \defgroup error Error codes
41  * @{
42  */
43 
44 /**
45  * \brief Function return status.
46  *
47  * This is either #PSA_SUCCESS (which is zero), indicating success,
48  * or a small negative value indicating that an error occurred. Errors are
49  * encoded as one of the \c PSA_ERROR_xxx values defined here. */
50 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t
51  * is also defined in an external header, so prevent its multiple
52  * definition.
53  */
54 #ifndef PSA_SUCCESS
55 typedef int32_t psa_status_t;
56 #endif
57 
58 /**@}*/
59 
60 /** \defgroup crypto_types Key and algorithm types
61  * @{
62  */
63 
64 /** \brief Encoding of a key type.
65  */
66 typedef uint16_t psa_key_type_t;
67 
68 /** The type of PSA elliptic curve family identifiers.
69  *
70  * The curve identifier is required to create an ECC key using the
71  * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
72  * macros.
73  *
74  * Values defined by this standard will never be in the range 0x80-0xff.
75  * Vendors who define additional families must use an encoding in this range.
76  */
77 typedef uint8_t psa_ecc_curve_t;
78 
79 /** The type of PSA Diffie-Hellman group family identifiers.
80  *
81  * The group identifier is required to create an Diffie-Hellman key using the
82  * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
83  * macros.
84  *
85  * Values defined by this standard will never be in the range 0x80-0xff.
86  * Vendors who define additional families must use an encoding in this range.
87  */
88 typedef uint8_t psa_dh_group_t;
89 
90 /** \brief Encoding of a cryptographic algorithm.
91  *
92  * For algorithms that can be applied to multiple key types, this type
93  * does not encode the key type. For example, for symmetric ciphers
94  * based on a block cipher, #psa_algorithm_t encodes the block cipher
95  * mode and the padding mode while the block cipher itself is encoded
96  * via #psa_key_type_t.
97  */
98 typedef uint32_t psa_algorithm_t;
99 
100 /**@}*/
101 
102 /** \defgroup key_lifetimes Key lifetimes
103  * @{
104  */
105 
106 /** Encoding of key lifetimes.
107  *
108  * The lifetime of a key indicates where it is stored and what system actions
109  * may create and destroy it.
110  *
111  * Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are automatically
112  * destroyed when the application terminates or on a power reset.
113  *
114  * Keys with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE are said
115  * to be _persistent_.
116  * Persistent keys are preserved if the application or the system restarts.
117  * Persistent keys have a key identifier of type #psa_key_id_t.
118  * The application can call psa_open_key() to open a persistent key that
119  * it created previously.
120  */
121 typedef uint32_t psa_key_lifetime_t;
122 
123 /** Encoding of identifiers of persistent keys.
124  *
125  * - Applications may freely choose key identifiers in the range
126  * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX.
127  * - Implementations may define additional key identifiers in the range
128  * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX.
129  * - 0 is reserved as an invalid key identifier.
130  * - Key identifiers outside these ranges are reserved for future use.
131  */
132 /* Implementation-specific quirk: The Mbed Crypto library can be built as
133  * part of a multi-client service that exposes the PSA Crypto API in each
134  * client and encodes the client identity in the key id argument of functions
135  * such as psa_open_key(). In this build configuration, we define
136  * psa_key_id_t in crypto_platform.h instead of here. */
137 #if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
138 typedef uint32_t psa_key_id_t;
139 #define PSA_KEY_ID_INIT 0
140 #endif
141 
142 /**@}*/
143 
144 /** \defgroup policy Key policies
145  * @{
146  */
147 
148 /** \brief Encoding of permitted usage on a key. */
149 typedef uint32_t psa_key_usage_t;
150 
151 /**@}*/
152 
153 /** \defgroup attributes Key attributes
154  * @{
155  */
156 
157 /** The type of a structure containing key attributes.
158  *
159  * This is an opaque structure that can represent the metadata of a key
160  * object. Metadata that can be stored in attributes includes:
161  * - The location of the key in storage, indicated by its key identifier
162  * and its lifetime.
163  * - The key's policy, comprising usage flags and a specification of
164  * the permitted algorithm(s).
165  * - Information about the key itself: the key type and its size.
166  * - Implementations may define additional attributes.
167  *
168  * The actual key material is not considered an attribute of a key.
169  * Key attributes do not contain information that is generally considered
170  * highly confidential.
171  *
172  * An attribute structure can be a simple data structure where each function
173  * `psa_set_key_xxx` sets a field and the corresponding function
174  * `psa_get_key_xxx` retrieves the value of the corresponding field.
175  * However, implementations may report values that are equivalent to the
176  * original one, but have a different encoding. For example, an
177  * implementation may use a more compact representation for types where
178  * many bit-patterns are invalid or not supported, and store all values
179  * that it does not support as a special marker value. In such an
180  * implementation, after setting an invalid value, the corresponding
181  * get function returns an invalid value which may not be the one that
182  * was originally stored.
183  *
184  * An attribute structure may contain references to auxiliary resources,
185  * for example pointers to allocated memory or indirect references to
186  * pre-calculated values. In order to free such resources, the application
187  * must call psa_reset_key_attributes(). As an exception, calling
188  * psa_reset_key_attributes() on an attribute structure is optional if
189  * the structure has only been modified by the following functions
190  * since it was initialized or last reset with psa_reset_key_attributes():
191  * - psa_set_key_id()
192  * - psa_set_key_lifetime()
193  * - psa_set_key_type()
194  * - psa_set_key_bits()
195  * - psa_set_key_usage_flags()
196  * - psa_set_key_algorithm()
197  *
198  * Before calling any function on a key attribute structure, the application
199  * must initialize it by any of the following means:
200  * - Set the structure to all-bits-zero, for example:
201  * \code
202  * psa_key_attributes_t attributes;
203  * memset(&attributes, 0, sizeof(attributes));
204  * \endcode
205  * - Initialize the structure to logical zero values, for example:
206  * \code
207  * psa_key_attributes_t attributes = {0};
208  * \endcode
209  * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
210  * for example:
211  * \code
212  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
213  * \endcode
214  * - Assign the result of the function psa_key_attributes_init()
215  * to the structure, for example:
216  * \code
217  * psa_key_attributes_t attributes;
218  * attributes = psa_key_attributes_init();
219  * \endcode
220  *
221  * A freshly initialized attribute structure contains the following
222  * values:
223  *
224  * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
225  * - key identifier: 0 (which is not a valid key identifier).
226  * - type: \c 0 (meaning that the type is unspecified).
227  * - key size: \c 0 (meaning that the size is unspecified).
228  * - usage flags: \c 0 (which allows no usage except exporting a public key).
229  * - algorithm: \c 0 (which allows no cryptographic usage, but allows
230  * exporting).
231  *
232  * A typical sequence to create a key is as follows:
233  * -# Create and initialize an attribute structure.
234  * -# If the key is persistent, call psa_set_key_id().
235  * Also call psa_set_key_lifetime() to place the key in a non-default
236  * location.
237  * -# Set the key policy with psa_set_key_usage_flags() and
238  * psa_set_key_algorithm().
239  * -# Set the key type with psa_set_key_type().
240  * Skip this step if copying an existing key with psa_copy_key().
241  * -# When generating a random key with psa_generate_key() or deriving a key
242  * with psa_key_derivation_output_key(), set the desired key size with
243  * psa_set_key_bits().
244  * -# Call a key creation function: psa_import_key(), psa_generate_key(),
245  * psa_key_derivation_output_key() or psa_copy_key(). This function reads
246  * the attribute structure, creates a key with these attributes, and
247  * outputs a handle to the newly created key.
248  * -# The attribute structure is now no longer necessary.
249  * You may call psa_reset_key_attributes(), although this is optional
250  * with the workflow presented here because the attributes currently
251  * defined in this specification do not require any additional resources
252  * beyond the structure itself.
253  *
254  * A typical sequence to query a key's attributes is as follows:
255  * -# Call psa_get_key_attributes().
256  * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
257  * you are interested in.
258  * -# Call psa_reset_key_attributes() to free any resources that may be
259  * used by the attribute structure.
260  *
261  * Once a key has been created, it is impossible to change its attributes.
262  */
264 
265 
266 #ifndef __DOXYGEN_ONLY__
267 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
268 /* Mbed Crypto defines this type in crypto_types.h because it is also
269  * visible to applications through an implementation-specific extension.
270  * For the PSA Cryptography specification, this type is only visible
271  * via crypto_se_driver.h. */
272 typedef uint64_t psa_key_slot_number_t;
273 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
274 #endif /* !__DOXYGEN_ONLY__ */
275 
276 /**@}*/
277 
278 /** \defgroup derivation Key derivation
279  * @{
280  */
281 
282 /** \brief Encoding of the step of a key derivation. */
283 typedef uint16_t psa_key_derivation_step_t;
284 
285 /**@}*/
286 
287 #endif /* PSA_CRYPTO_TYPES_H */
uint8_t psa_dh_group_t
The type of PSA Diffie-Hellman group family identifiers.
uint8_t psa_ecc_curve_t
The type of PSA elliptic curve family identifiers.
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
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 ...
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
uint16_t psa_key_type_t
Encoding of a key type.
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
int32_t psa_status_t
Function return status.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.