Skip to content

Commit 7cabd3e

Browse files
Wer-WolfWer-Wolf
committed
sys/psa_crypto: Split key attributes definitions into separate file
Split key attributes definitions into separate file, together with some basic support macros and helper functions. This allows PSA crypto backends to use this definitions without pulling in all the other type definitions. Signed-off-by: Armin Wolf <[email protected]>
1 parent dd81d18 commit 7cabd3e

File tree

3 files changed

+187
-152
lines changed

3 files changed

+187
-152
lines changed

‎sys/include/psa_crypto/psa/crypto_struct.h‎

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -28,50 +28,6 @@ extern "C" {
2828
#include "crypto_sizes.h"
2929
#include "crypto_contexts.h"
3030

31-
#if IS_USED(MODULE_PSA_KEY_MANAGEMENT) || defined(DOXYGEN)
32-
/**
33-
* @brief Structure storing the key usage policies
34-
*/
35-
struct psa_key_policy_s {
36-
psa_key_usage_t usage; /**< Key usage policy */
37-
psa_algorithm_t alg; /**< Algorithm for key usage */
38-
};
39-
40-
/**
41-
* @brief Type for key usage policies.
42-
*/
43-
typedef struct psa_key_policy_s psa_key_policy_t;
44-
45-
/**
46-
* @brief Structure storing key attributes
47-
*/
48-
struct psa_key_attributes_s {
49-
psa_key_type_t type; /**< Type of key */
50-
psa_key_bits_t bits; /**< Size of key in bits */
51-
psa_key_lifetime_t lifetime; /**< Lifetime of key */
52-
psa_key_id_t id; /**< Key identifier */
53-
psa_key_policy_t policy; /**< Key usage policy */
54-
};
55-
56-
/**
57-
* @brief This macro returns a suitable initializer for a key attribute object of
58-
* type @ref psa_key_attributes_t.
59-
*/
60-
#define PSA_KEY_ATTRIBUTES_INIT { 0 }
61-
62-
/**
63-
* @brief Return an initial value for a key attribute object.
64-
*
65-
* @return struct psa_key_attributes_s
66-
*/
67-
static inline struct psa_key_attributes_s psa_key_attributes_init(void)
68-
{
69-
const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
70-
71-
return v;
72-
}
73-
#endif /*(MODULE_PSA_KEY_MANAGEMENT */
74-
7531
#if IS_USED(MODULE_PSA_AEAD) || defined(DOXYGEN)
7632
/**
7733
* @brief Structure storing an AEAD operation context

‎sys/include/psa_crypto/psa/crypto_types.h‎

Lines changed: 1 addition & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,7 @@ extern "C" {
2828

2929
#include "psa/algorithm.h"
3030
#include "psa/error.h"
31-
#include "psa/key/bits.h"
32-
#include "psa/key/id.h"
33-
#include "psa/key/lifetime.h"
34-
#include "psa/key/usage.h"
35-
#include "psa/key/type.h"
31+
#include "psa/key/attributes.h"
3632

3733
/**
3834
* @brief For encrypt-decrypt functions, whether the operation is an encryption
@@ -177,109 +173,6 @@ typedef struct psa_mac_operation_s psa_mac_operation_t;
177173
*/
178174
typedef struct psa_hash_operation_s psa_hash_operation_t;
179175

180-
/**
181-
* @brief The type of an object containing key attributes.
182-
*
183-
* @details This is the object that represents the metadata of a key object. Metadata that can be
184-
* stored in attributes includes:
185-
* - The location of the key in storage, indicated by its key identifier and its lifetime.
186-
* - The key’s policy, comprising usage flags and a specification of the permitted
187-
* algorithm(s).
188-
* - Information about the key itself: the key type and its size.
189-
* - Implementations can define additional attributes.
190-
*
191-
* The actual key material is not considered an attribute of a key. Key attributes do not
192-
* contain information that is generally considered highly confidential.
193-
*
194-
* @note Implementations are recommended to define the attribute object as a simple data
195-
* structure, with fields corresponding to the individual key attributes. In such an
196-
* implementation, each function @c psa_set_key_xxx() sets a field and the corresponding
197-
* function @c psa_get_key_xxx() retrieves the value of the field.
198-
* An implementation can report attribute values that are equivalent to the original one,
199-
* but have a different encoding. For example, an implementation can use a more compact
200-
* representation for types where many bit-patterns are invalid or not supported, and
201-
* store all values that it does not support as a special marker value. In such an
202-
* implementation, after setting an invalid value, the corresponding get function returns
203-
* an invalid value which might not be the one that was originally stored.
204-
*
205-
* This is an implementation-defined type. Applications that make assumptions about the
206-
* content of this object will result in in implementation-specific behavior, and are
207-
* non-portable.
208-
*
209-
* An attribute object can contain references to auxiliary resources, for example pointers
210-
* to allocated memory or indirect references to pre-calculated values. In order to free
211-
* such resources, the application must call @ref psa_reset_key_attributes(). As an
212-
* exception, calling @ref psa_reset_key_attributes() on an attribute object is optional
213-
* if the object has only been modified by the following functions since it was
214-
* initialized or last reset with @ref psa_reset_key_attributes():
215-
* - @ref psa_set_key_id()
216-
* - @ref psa_set_key_lifetime()
217-
* - @ref psa_set_key_type()
218-
* - @ref psa_set_key_bits()
219-
* - @ref psa_set_key_usage_flags()
220-
* - @ref psa_set_key_algorithm()
221-
* Before calling any function on a key attribute object, the application must initialize
222-
* it by any of the following means:
223-
* - Set the object to all-bits-zero, for example:
224-
* @code
225-
* @ref psa_key_attributes_t attributes;
226-
* memset(&attributes, 0, sizeof(attributes));
227-
* @endcode
228-
* - Initialize the object to logical zero values by declaring the object as static or
229-
* global without an explicit initializer, for example:
230-
* @code
231-
* static @ref psa_key_attributes_t attributes;
232-
* @endcode
233-
* - Initialize the object to the initializer @ref PSA_KEY_ATTRIBUTES_INIT, for example:
234-
* @code
235-
* @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;
236-
* @endcode
237-
* - Assign the result of the function @ref psa_key_attributes_init() to the object,
238-
* for example:
239-
* @code
240-
* @ref psa_key_attributes_t attributes;
241-
* attributes = @ref psa_key_attributes_init();
242-
* @endcode
243-
*
244-
* A freshly initialized attribute object contains the following values:
245-
* - lifetime: @ref PSA_KEY_LIFETIME_VOLATILE.
246-
* - key identifier: @ref PSA_KEY_ID_NULL — which is not a valid key identifier.
247-
* - type: @ref PSA_KEY_TYPE_NONE — meaning that the type is unspecified.
248-
* - key size: @c 0 — meaning that the size is unspecified.
249-
* - usage flags: @c 0 — which allows no usage except exporting a public key.
250-
* - algorithm: @ref PSA_ALG_NONE — which does not allow cryptographic usage,
251-
* but allows exporting.
252-
*
253-
* ## Usage
254-
* A typical sequence to create a key is as follows:
255-
* -# Create and initialize an attribute object.
256-
* -# If the key is persistent, call @ref psa_set_key_id(). Also call @ref
257-
* psa_set_key_lifetime() to place the key in a non-default location.
258-
* -# Set the key policy with @ref psa_set_key_usage_flags() and @ref
259-
* psa_set_key_algorithm().
260-
* -# Set the key type with @ref psa_set_key_type(). Skip this step if copying an existing
261-
* key with @ref psa_copy_key().
262-
* -# When generating a random key with @ref psa_generate_key() or deriving a key with
263-
* @ref psa_key_derivation_output_key(), set the desired key size with @ref
264-
* psa_set_key_bits().
265-
* -# Call a key creation function: @ref psa_import_key(), @ref psa_generate_key(),
266-
* @ref psa_key_derivation_output_key() or @ref psa_copy_key(). This function reads the
267-
* attribute object, creates a key with these attributes, and outputs an identifier for
268-
* the newly created key.
269-
* -# Optionally call @ref psa_reset_key_attributes(), now that the attribute object is no
270-
* longer needed. Currently this call is not required as the attributes defined in this
271-
* specification do not require additional resources beyond the object itself.
272-
*
273-
* A typical sequence to query a key’s attributes is as follows:
274-
* -# Call @ref psa_get_key_attributes().
275-
* -# Call @c psa_get_key_xxx() functions to retrieve the required attribute(s).
276-
* -# Call @ref psa_reset_key_attributes() to free any resources that can be used by the
277-
* attribute object.
278-
*
279-
* Once a key has been created, it is impossible to change its attributes.
280-
*/
281-
typedef struct psa_key_attributes_s psa_key_attributes_t;
282-
283176
/**
284177
* @brief The type of the state object for multi-part cipher operations.
285178
*

‎sys/include/psa_crypto/psa/key/attributes.h‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
/*
2+
* Copyright (C) 2024 TU Dresden
3+
* Copyright (C) 2021 HAW Hamburg
4+
*
5+
* This file is subject to the terms and conditions of the GNU Lesser
6+
* General Public License v2.1. See the file LICENSE in the top level
7+
* directory for more details.
8+
*/
9+
10+
/**
11+
* @ingroup sys_psa_crypto
12+
* @{
13+
*
14+
* @file key/attributes.h
15+
* @brief Key attributes definitions for the PSA Crypto API
16+
*
17+
* @author Armin Wolf <[email protected]>
18+
* @author Lena Boeckmann <[email protected]>
19+
*
20+
*/
21+
22+
#ifndef PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H
23+
#define PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H
24+
25+
#ifdef __cplusplus
26+
extern "C" {
27+
#endif
28+
29+
#include "psa/algorithm.h"
30+
#include "bits.h"
31+
#include "id.h"
32+
#include "lifetime.h"
33+
#include "type.h"
34+
#include "usage.h"
35+
36+
/**
37+
* @brief Structure storing the key usage policies
38+
*/
39+
struct psa_key_policy_s {
40+
psa_key_usage_t usage; /**< Key usage policy */
41+
psa_algorithm_t alg; /**< Algorithm for key usage */
42+
};
43+
44+
/**
45+
* @brief Type for key usage policies.
46+
*/
47+
typedef struct psa_key_policy_s psa_key_policy_t;
48+
49+
/**
50+
* @brief Structure storing key attributes
51+
*/
52+
struct psa_key_attributes_s {
53+
psa_key_type_t type; /**< Type of key */
54+
psa_key_bits_t bits; /**< Size of key in bits */
55+
psa_key_lifetime_t lifetime; /**< Lifetime of key */
56+
psa_key_id_t id; /**< Key identifier */
57+
psa_key_policy_t policy; /**< Key usage policy */
58+
};
59+
60+
/**
61+
* @brief The type of an object containing key attributes.
62+
*
63+
* @details This is the object that represents the metadata of a key object. Metadata that can be
64+
* stored in attributes includes:
65+
* - The location of the key in storage, indicated by its key identifier and its lifetime.
66+
* - The key’s policy, comprising usage flags and a specification of the permitted
67+
* algorithm(s).
68+
* - Information about the key itself: the key type and its size.
69+
* - Implementations can define additional attributes.
70+
*
71+
* The actual key material is not considered an attribute of a key. Key attributes do not
72+
* contain information that is generally considered highly confidential.
73+
*
74+
* @note Implementations are recommended to define the attribute object as a simple data
75+
* structure, with fields corresponding to the individual key attributes. In such an
76+
* implementation, each function @c psa_set_key_xxx() sets a field and the corresponding
77+
* function @c psa_get_key_xxx() retrieves the value of the field.
78+
* An implementation can report attribute values that are equivalent to the original one,
79+
* but have a different encoding. For example, an implementation can use a more compact
80+
* representation for types where many bit-patterns are invalid or not supported, and
81+
* store all values that it does not support as a special marker value. In such an
82+
* implementation, after setting an invalid value, the corresponding get function returns
83+
* an invalid value which might not be the one that was originally stored.
84+
*
85+
* This is an implementation-defined type. Applications that make assumptions about the
86+
* content of this object will result in in implementation-specific behavior, and are
87+
* non-portable.
88+
*
89+
* An attribute object can contain references to auxiliary resources, for example pointers
90+
* to allocated memory or indirect references to pre-calculated values. In order to free
91+
* such resources, the application must call @ref psa_reset_key_attributes(). As an
92+
* exception, calling @ref psa_reset_key_attributes() on an attribute object is optional
93+
* if the object has only been modified by the following functions since it was
94+
* initialized or last reset with @ref psa_reset_key_attributes():
95+
* - @ref psa_set_key_id()
96+
* - @ref psa_set_key_lifetime()
97+
* - @ref psa_set_key_type()
98+
* - @ref psa_set_key_bits()
99+
* - @ref psa_set_key_usage_flags()
100+
* - @ref psa_set_key_algorithm()
101+
* Before calling any function on a key attribute object, the application must initialize
102+
* it by any of the following means:
103+
* - Set the object to all-bits-zero, for example:
104+
* @code
105+
* @ref psa_key_attributes_t attributes;
106+
* memset(&attributes, 0, sizeof(attributes));
107+
* @endcode
108+
* - Initialize the object to logical zero values by declaring the object as static or
109+
* global without an explicit initializer, for example:
110+
* @code
111+
* static @ref psa_key_attributes_t attributes;
112+
* @endcode
113+
* - Initialize the object to the initializer @ref PSA_KEY_ATTRIBUTES_INIT, for example:
114+
* @code
115+
* @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;
116+
* @endcode
117+
* - Assign the result of the function @ref psa_key_attributes_init() to the object,
118+
* for example:
119+
* @code
120+
* @ref psa_key_attributes_t attributes;
121+
* attributes = @ref psa_key_attributes_init();
122+
* @endcode
123+
*
124+
* A freshly initialized attribute object contains the following values:
125+
* - lifetime: @ref PSA_KEY_LIFETIME_VOLATILE.
126+
* - key identifier: @ref PSA_KEY_ID_NULL — which is not a valid key identifier.
127+
* - type: @ref PSA_KEY_TYPE_NONE — meaning that the type is unspecified.
128+
* - key size: @c 0 — meaning that the size is unspecified.
129+
* - usage flags: @c 0 — which allows no usage except exporting a public key.
130+
* - algorithm: @ref PSA_ALG_NONE — which does not allow cryptographic usage,
131+
* but allows exporting.
132+
*
133+
* ## Usage
134+
* A typical sequence to create a key is as follows:
135+
* -# Create and initialize an attribute object.
136+
* -# If the key is persistent, call @ref psa_set_key_id(). Also call @ref
137+
* psa_set_key_lifetime() to place the key in a non-default location.
138+
* -# Set the key policy with @ref psa_set_key_usage_flags() and @ref
139+
* psa_set_key_algorithm().
140+
* -# Set the key type with @ref psa_set_key_type(). Skip this step if copying an existing
141+
* key with @ref psa_copy_key().
142+
* -# When generating a random key with @ref psa_generate_key() or deriving a key with
143+
* @ref psa_key_derivation_output_key(), set the desired key size with @ref
144+
* psa_set_key_bits().
145+
* -# Call a key creation function: @ref psa_import_key(), @ref psa_generate_key(),
146+
* @ref psa_key_derivation_output_key() or @ref psa_copy_key(). This function reads the
147+
* attribute object, creates a key with these attributes, and outputs an identifier for
148+
* the newly created key.
149+
* -# Optionally call @ref psa_reset_key_attributes(), now that the attribute object is no
150+
* longer needed. Currently this call is not required as the attributes defined in this
151+
* specification do not require additional resources beyond the object itself.
152+
*
153+
* A typical sequence to query a key’s attributes is as follows:
154+
* -# Call @ref psa_get_key_attributes().
155+
* -# Call @c psa_get_key_xxx() functions to retrieve the required attribute(s).
156+
* -# Call @ref psa_reset_key_attributes() to free any resources that can be used by the
157+
* attribute object.
158+
*
159+
* Once a key has been created, it is impossible to change its attributes.
160+
*/
161+
typedef struct psa_key_attributes_s psa_key_attributes_t;
162+
163+
/**
164+
* @brief This macro returns a suitable initializer for a key attribute object of
165+
* type @ref psa_key_attributes_t.
166+
*/
167+
#define PSA_KEY_ATTRIBUTES_INIT { 0 }
168+
169+
/**
170+
* @brief Return an initial value for a key attribute object.
171+
*
172+
* @return psa_key_attributes_t
173+
*/
174+
static inline psa_key_attributes_t psa_key_attributes_init(void)
175+
{
176+
const psa_key_attributes_t v = PSA_KEY_ATTRIBUTES_INIT;
177+
178+
return v;
179+
}
180+
181+
#ifdef __cplusplus
182+
}
183+
#endif
184+
185+
#endif /* PSA_CRYPTO_PSA_KEY_ATTRIBUTES_H */
186+
/** @} */

0 commit comments

Comments
 (0)