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