Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_V1_0/include/psa/crypto_types.h
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 /**
8  * \file psa/crypto_types.h
9  *
10  * \brief PSA cryptography module: type aliases.
11  *
12  * \note This file may not be included directly. Applications must
13  * include psa/crypto.h. Drivers must include the appropriate driver
14  * header file.
15  *
16  * This file contains portable definitions of integral types for properties
17  * of cryptographic keys, designations of cryptographic algorithms, and
18  * error codes returned by the library.
19  *
20  * This header file does not declare any function.
21  */
22 
23 #ifndef PSA_CRYPTO_TYPES_H
24 #define PSA_CRYPTO_TYPES_H
25 
26 #include <stdint.h>
27 
28 /** \defgroup error Error codes
29  * @{
30  */
31 
32 /**
33  * \brief Function return status.
34  *
35  * This is either #PSA_SUCCESS (which is zero), indicating success,
36  * or a small negative value indicating that an error occurred. Errors are
37  * encoded as one of the \c PSA_ERROR_xxx values defined here. */
38 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t
39  * is also defined in an external header, so prevent its multiple
40  * definition.
41  */
42 #ifndef PSA_SUCCESS
43 typedef int32_t psa_status_t;
44 #endif
45 
46 /**@}*/
47 
48 /** \defgroup crypto_types Key and algorithm types
49  * @{
50  */
51 
52 /** \brief Encoding of a key type.
53  */
54 typedef uint32_t psa_key_type_t;
55 
56 /** The type of PSA elliptic curve family identifiers.
57  *
58  * The curve identifier is required to create an ECC key using the
59  * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
60  * macros.
61  *
62  * Values defined by this standard will never be in the range 0x80-0xff.
63  * Vendors who define additional families must use an encoding in this range.
64  */
65 typedef uint8_t psa_ecc_family_t;
66 
67 /** The type of PSA elliptic curve identifiers.
68  *
69  * The curve identifier is required to create an ECC key using the
70  * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
71  * macros.
72  *
73  * The encoding of curve identifiers is taken from the
74  * TLS Supported Groups Registry (formerly known as the
75  * TLS EC Named Curve Registry)
76  * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
77  *
78  * This specification defines identifiers for some of the curves in the IANA
79  * registry. Implementations that support other curves that are in the IANA
80  * registry should use the IANA value and a implementation-specific identifier.
81  * Implemenations that support non-IANA curves should use one of the following
82  * approaches for allocating a key type:
83  *
84  * 1. Select a ::psa_ecc_curve_t value in the range #PSA_ECC_CURVE_VENDOR_MIN to
85  * #PSA_ECC_CURVE_VENDOR_MAX, which is a subset of the IANA private use
86  * range.
87  * 2. Use a ::psa_key_type_t value that is vendor-defined.
88  *
89  * The first option is recommended.
90  */
91 typedef uint16_t psa_ecc_curve_t;
92 
93 /** The type of PSA Diffie-Hellman group identifiers.
94  *
95  * The group identifier is required to create an Diffie-Hellman key using the
96  * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
97  * macros.
98  *
99  * The encoding of group identifiers is taken from the
100  * TLS Supported Groups Registry (formerly known as the
101  * TLS EC Named Curve Registry)
102  * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
103  *
104  * This specification defines identifiers for some of the groups in the IANA
105  * registry. Implementations that support other groups that are in the IANA
106  * registry should use the IANA value and a implementation-specific identifier.
107  * Implemenations that support non-IANA groups should use one of the following
108  * approaches for allocating a key type:
109  *
110  * 1. Select a ::psa_dh_group_t value in the range #PSA_DH_GROUP_VENDOR_MIN to
111  * #PSA_DH_GROUP_VENDOR_MAX, which is a subset of the IANA private use
112  * range.
113  * 2. Select a ::psa_dh_group_t value from the named groups allocated for
114  * GREASE in the IETF draft specification. The GREASE specification and
115  * values are listed below.
116  * 3. Use a ::psa_key_type_t value that is vendor-defined.
117  *
118  * Option 1 or 2 are recommended.
119  *
120  * The current draft of the GREASE specification is
121  * https://datatracker.ietf.org/doc/draft-ietf-tls-grease
122  *
123  * The following GREASE values are allocated for named groups:
124  * \code
125  * 0x0A0A
126  * 0x1A1A
127  * 0x2A2A
128  * 0x3A3A
129  * 0x4A4A
130  * 0x5A5A
131  * 0x6A6A
132  * 0x7A7A
133  * 0x8A8A
134  * 0x9A9A
135  * 0xAAAA
136  * 0xBABA
137  * 0xCACA
138  * 0xDADA
139  * 0xEAEA
140  * 0xFAFA
141  * \endcode
142  */
143 typedef uint16_t psa_dh_group_t;
144 
145 /** \brief Encoding of a cryptographic algorithm.
146  *
147  * For algorithms that can be applied to multiple key types, this type
148  * does not encode the key type. For example, for symmetric ciphers
149  * based on a block cipher, #psa_algorithm_t encodes the block cipher
150  * mode and the padding mode while the block cipher itself is encoded
151  * via #psa_key_type_t.
152  */
153 typedef uint32_t psa_algorithm_t;
154 
155 /**@}*/
156 
157 /** \defgroup key_lifetimes Key lifetimes
158  * @{
159  */
160 
161 /** Encoding of key lifetimes.
162  *
163  * The lifetime of a key indicates where it is stored and what system actions
164  * may create and destroy it.
165  *
166  * Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are automatically
167  * destroyed when the application terminates or on a power reset.
168  *
169  * Keys with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE are said
170  * to be _persistent_.
171  * Persistent keys are preserved if the application or the system restarts.
172  * Persistent keys have a key identifier of type #psa_key_id_t.
173  * The application can call psa_open_key() to open a persistent key that
174  * it created previously.
175  */
176 typedef uint32_t psa_key_lifetime_t;
177 
178 /** Encoding of identifiers of persistent keys.
179  *
180  * - Applications may freely choose key identifiers in the range
181  * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX.
182  * - Implementations may define additional key identifiers in the range
183  * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX.
184  * - 0 is reserved as an invalid key identifier.
185  * - Key identifiers outside these ranges are reserved for future use.
186  */
187 typedef uint32_t psa_key_id_t;
188 #define PSA_KEY_ID_INIT 0
189 
190 /**@}*/
191 
192 /** \defgroup policy Key policies
193  * @{
194  */
195 
196 /** \brief Encoding of permitted usage on a key. */
197 typedef uint32_t psa_key_usage_t;
198 
199 /**@}*/
200 
201 /** \defgroup attributes Key attributes
202  * @{
203  */
204 
205 /** The type of a structure containing key attributes.
206  *
207  * This is an opaque structure that can represent the metadata of a key
208  * object. Metadata that can be stored in attributes includes:
209  * - The location of the key in storage, indicated by its key identifier
210  * and its lifetime.
211  * - The key's policy, comprising usage flags and a specification of
212  * the permitted algorithm(s).
213  * - Information about the key itself: the key type and its size.
214  * - Implementations may define additional attributes.
215  *
216  * The actual key material is not considered an attribute of a key.
217  * Key attributes do not contain information that is generally considered
218  * highly confidential.
219  *
220  * An attribute structure can be a simple data structure where each function
221  * `psa_set_key_xxx` sets a field and the corresponding function
222  * `psa_get_key_xxx` retrieves the value of the corresponding field.
223  * However, implementations may report values that are equivalent to the
224  * original one, but have a different encoding. For example, an
225  * implementation may use a more compact representation for types where
226  * many bit-patterns are invalid or not supported, and store all values
227  * that it does not support as a special marker value. In such an
228  * implementation, after setting an invalid value, the corresponding
229  * get function returns an invalid value which may not be the one that
230  * was originally stored.
231  *
232  * An attribute structure may contain references to auxiliary resources,
233  * for example pointers to allocated memory or indirect references to
234  * pre-calculated values. In order to free such resources, the application
235  * must call psa_reset_key_attributes(). As an exception, calling
236  * psa_reset_key_attributes() on an attribute structure is optional if
237  * the structure has only been modified by the following functions
238  * since it was initialized or last reset with psa_reset_key_attributes():
239  * - psa_set_key_id()
240  * - psa_set_key_lifetime()
241  * - psa_set_key_type()
242  * - psa_set_key_bits()
243  * - psa_set_key_usage_flags()
244  * - psa_set_key_algorithm()
245  *
246  * Before calling any function on a key attribute structure, the application
247  * must initialize it by any of the following means:
248  * - Set the structure to all-bits-zero, for example:
249  * \code
250  * psa_key_attributes_t attributes;
251  * memset(&attributes, 0, sizeof(attributes));
252  * \endcode
253  * - Initialize the structure to logical zero values, for example:
254  * \code
255  * psa_key_attributes_t attributes = {0};
256  * \endcode
257  * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
258  * for example:
259  * \code
260  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
261  * \endcode
262  * - Assign the result of the function psa_key_attributes_init()
263  * to the structure, for example:
264  * \code
265  * psa_key_attributes_t attributes;
266  * attributes = psa_key_attributes_init();
267  * \endcode
268  *
269  * A freshly initialized attribute structure contains the following
270  * values:
271  *
272  * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
273  * - key identifier: 0 (which is not a valid key identifier).
274  * - type: \c 0 (meaning that the type is unspecified).
275  * - key size: \c 0 (meaning that the size is unspecified).
276  * - usage flags: \c 0 (which allows no usage except exporting a public key).
277  * - algorithm: \c 0 (which allows no cryptographic usage, but allows
278  * exporting).
279  *
280  * A typical sequence to create a key is as follows:
281  * -# Create and initialize an attribute structure.
282  * -# If the key is persistent, call psa_set_key_id().
283  * Also call psa_set_key_lifetime() to place the key in a non-default
284  * location.
285  * -# Set the key policy with psa_set_key_usage_flags() and
286  * psa_set_key_algorithm().
287  * -# Set the key type with psa_set_key_type().
288  * Skip this step if copying an existing key with psa_copy_key().
289  * -# When generating a random key with psa_generate_key() or deriving a key
290  * with psa_key_derivation_output_key(), set the desired key size with
291  * psa_set_key_bits().
292  * -# Call a key creation function: psa_import_key(), psa_generate_key(),
293  * psa_key_derivation_output_key() or psa_copy_key(). This function reads
294  * the attribute structure, creates a key with these attributes, and
295  * outputs a handle to the newly created key.
296  * -# The attribute structure is now no longer necessary.
297  * You may call psa_reset_key_attributes(), although this is optional
298  * with the workflow presented here because the attributes currently
299  * defined in this specification do not require any additional resources
300  * beyond the structure itself.
301  *
302  * A typical sequence to query a key's attributes is as follows:
303  * -# Call psa_get_key_attributes().
304  * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
305  * you are interested in.
306  * -# Call psa_reset_key_attributes() to free any resources that may be
307  * used by the attribute structure.
308  *
309  * Once a key has been created, it is impossible to change its attributes.
310  */
312 
313 /**@}*/
314 
315 /** \defgroup derivation Key derivation
316  * @{
317  */
318 
319 /** \brief Encoding of the step of a key derivation. */
320 typedef uint16_t psa_key_derivation_step_t;
321 
322 /**@}*/
323 
324 #endif /* PSA_CRYPTO_TYPES_H */
uint16_t psa_ecc_curve_t
The type of PSA elliptic curve 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.
uint16_t psa_dh_group_t
The type of PSA Diffie-Hellman group identifiers.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
uint32_t psa_key_type_t
Encoding of a key type.
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
uint8_t psa_ecc_family_t
The type of PSA elliptic curve family identifiers.
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.