Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_V1_0/include/psa/crypto_struct.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_struct.h
9  *
10  * \brief PSA cryptography module: structured type implementations
11  *
12  * \note This file may not be included directly. Applications must
13  * include psa/crypto.h.
14  *
15  * This file contains the definitions of some data structures with
16  * implementation-specific definitions.
17  *
18  * In implementations with isolation between the application and the
19  * cryptography module, it is expected that the front-end and the back-end
20  * would have different versions of this file.
21  */
22 
23 #ifndef PSA_CRYPTO_STRUCT_H
24 #define PSA_CRYPTO_STRUCT_H
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /*
31  * Note that the below structures are different from the decalrations in
32  * mbed-crypto. This is because TF-M maintains 'front-end' and 'back-end'
33  * versions of this header. In the front-end version, exported to NS
34  * clients in interface/include/psa, a crypto operation is defined as an
35  * opaque handle to a context in the Crypto service. The back-end
36  * version, directly included from the mbed-crypto repo by the Crypto
37  * service, contains the full definition of the operation structs.
38  *
39  * One of the functions of the Crypto service is to allocate the back-end
40  * operation contexts in its own partition memory (in crypto_alloc.c),
41  * and then do the mapping between front-end operation handles passed by
42  * NS clients and the corresponding back-end operation contexts. The
43  * advantage of doing it this way is that internal mbed-crypto state is never
44  * exposed to the NS client.
45  */
46 
48 {
49  uint32_t handle;
50 };
51 
52 #define PSA_HASH_OPERATION_INIT {0}
53 static inline struct psa_hash_operation_s psa_hash_operation_init( void )
54 {
55  const struct psa_hash_operation_s v = PSA_HASH_OPERATION_INIT;
56  return( v );
57 }
58 
60 {
61  uint32_t handle;
62 };
63 
64 #define PSA_MAC_OPERATION_INIT {0}
65 static inline struct psa_mac_operation_s psa_mac_operation_init( void )
66 {
67  const struct psa_mac_operation_s v = PSA_MAC_OPERATION_INIT;
68  return( v );
69 }
70 
72 {
73  uint32_t handle;
74 };
75 
76 #define PSA_CIPHER_OPERATION_INIT {0}
77 static inline struct psa_cipher_operation_s psa_cipher_operation_init( void )
78 {
79  const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT;
80  return( v );
81 }
82 
84 {
85  uint32_t handle;
86 };
87 
88 #define PSA_AEAD_OPERATION_INIT {0}
89 static inline struct psa_aead_operation_s psa_aead_operation_init( void )
90 {
91  const struct psa_aead_operation_s v = PSA_AEAD_OPERATION_INIT;
92  return( v );
93 }
94 
96 {
97  uint32_t handle;
98 };
99 
100 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
101 static inline struct psa_key_derivation_s psa_key_derivation_operation_init( void )
102 {
103  const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT;
104  return( v );
105 }
106 
107 struct psa_key_policy_s
108 {
109  psa_key_usage_t usage;
110  psa_algorithm_t alg;
111  psa_algorithm_t alg2;
112 };
113 typedef struct psa_key_policy_s psa_key_policy_t;
114 
115 #define PSA_KEY_POLICY_INIT {0, 0, 0}
116 static inline struct psa_key_policy_s psa_key_policy_init( void )
117 {
118  const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT;
119  return( v );
120 }
121 
122 /* The type used internally for key sizes.
123  * Public interfaces use size_t, but internally we use a smaller type. */
124 typedef uint16_t psa_key_bits_t;
125 /* The maximum value of the type used to represent bit-sizes.
126  * This is used to mark an invalid key size. */
127 #define PSA_KEY_BITS_TOO_LARGE ( (psa_key_bits_t) ( -1 ) )
128 /* The maximum size of a key in bits.
129  * Currently defined as the maximum that can be represented, rounded down
130  * to a whole number of bytes.
131  * This is an uncast value so that it can be used in preprocessor
132  * conditionals. */
133 #define PSA_MAX_KEY_BITS 0xfff8
134 
135 /** A mask of flags that can be stored in key attributes.
136  *
137  * This type is also used internally to store flags in slots. Internal
138  * flags are defined in library/psa_crypto_core.h. Internal flags may have
139  * the same value as external flags if they are properly handled during
140  * key creation and in psa_get_key_attributes.
141  */
142 typedef uint16_t psa_key_attributes_flag_t;
143 
144 #define MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER \
145  ( (psa_key_attributes_flag_t) 0x0001 )
146 
147 /* A mask of key attribute flags used externally only.
148  * Only meant for internal checks inside the library. */
149 #define MBEDTLS_PSA_KA_MASK_EXTERNAL_ONLY ( \
150  MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER | \
151  0 )
152 
153 /* A mask of key attribute flags used both internally and externally.
154  * Currently there aren't any. */
155 #define MBEDTLS_PSA_KA_MASK_DUAL_USE ( \
156  0 )
157 
158 typedef struct
159 {
160  psa_key_type_t type;
161  psa_key_lifetime_t lifetime;
162  psa_key_id_t id;
163  psa_key_policy_t policy;
164  psa_key_bits_t bits;
165  psa_key_attributes_flag_t flags;
167 
168 #define PSA_CORE_KEY_ATTRIBUTES_INIT {0, 0, PSA_KEY_ID_INIT, PSA_KEY_POLICY_INIT, 0, 0}
169 
171 {
173 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
174  psa_key_slot_number_t slot_number;
175 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
176  void *domain_parameters;
177  size_t domain_parameters_size;
178 };
179 
180 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
181 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, 0, NULL, 0}
182 #else
183 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0}
184 #endif
185 
186 static inline struct psa_key_attributes_s psa_key_attributes_init( void )
187 {
188  const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
189  return( v );
190 }
191 
192 static inline void psa_set_key_id(psa_key_attributes_t *attributes,
193  psa_key_id_t id)
194 {
195  attributes->core.id = id;
196  if( attributes->core.lifetime == PSA_KEY_LIFETIME_VOLATILE )
197  attributes->core.lifetime = PSA_KEY_LIFETIME_PERSISTENT;
198 }
199 
200 static inline psa_key_id_t psa_get_key_id(
201  const psa_key_attributes_t *attributes)
202 {
203  return( attributes->core.id );
204 }
205 
206 static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes,
207  psa_key_lifetime_t lifetime)
208 {
209  attributes->core.lifetime = lifetime;
210  if( lifetime == PSA_KEY_LIFETIME_VOLATILE )
211  {
212 #ifdef MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
213  attributes->core.id.key_id = 0;
214  attributes->core.id.owner = 0;
215 #else
216  attributes->core.id = 0;
217 #endif
218  }
219 }
220 
222  const psa_key_attributes_t *attributes)
223 {
224  return( attributes->core.lifetime );
225 }
226 
227 static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
228  psa_key_usage_t usage_flags)
229 {
230  attributes->core.policy.usage = usage_flags;
231 }
232 
234  const psa_key_attributes_t *attributes)
235 {
236  return( attributes->core.policy.usage );
237 }
238 
239 static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes,
240  psa_algorithm_t alg)
241 {
242  attributes->core.policy.alg = alg;
243 }
244 
246  const psa_key_attributes_t *attributes)
247 {
248  return( attributes->core.policy.alg );
249 }
250 
251 /* This function is declared in crypto_extra.h, which comes after this
252  * header file, but we need the function here, so repeat the declaration. */
254  psa_key_type_t type,
255  const uint8_t *data,
256  size_t data_length);
257 
258 static inline void psa_set_key_type(psa_key_attributes_t *attributes,
259  psa_key_type_t type)
260 {
261  if( attributes->domain_parameters == NULL )
262  {
263  /* Common case: quick path */
264  attributes->core.type = type;
265  }
266  else
267  {
268  /* Call the bigger function to free the old domain paramteres.
269  * Ignore any errors which may arise due to type requiring
270  * non-default domain parameters, since this function can't
271  * report errors. */
272  (void) psa_set_key_domain_parameters( attributes, type, NULL, 0 );
273  }
274 }
275 
276 static inline psa_key_type_t psa_get_key_type(
277  const psa_key_attributes_t *attributes)
278 {
279  return( attributes->core.type );
280 }
281 
282 static inline void psa_set_key_bits(psa_key_attributes_t *attributes,
283  size_t bits)
284 {
285  if( bits > PSA_MAX_KEY_BITS )
286  attributes->core.bits = PSA_KEY_BITS_TOO_LARGE;
287  else
288  attributes->core.bits = (psa_key_bits_t) bits;
289 }
290 
291 static inline size_t psa_get_key_bits(
292  const psa_key_attributes_t *attributes)
293 {
294  return( attributes->core.bits );
295 }
296 
297 #ifdef __cplusplus
298 }
299 #endif
300 
301 #endif /* PSA_CRYPTO_STRUCT_H */
static void psa_set_key_id(psa_key_attributes_t *attributes, psa_key_id_t id)
Declare a key as persistent and set its key identifier.
static psa_key_derivation_operation_t psa_key_derivation_operation_init(void)
Return an initial value for a key derivation operation object.
static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)
Declare the size of a key.
#define PSA_KEY_LIFETIME_VOLATILE
A volatile key only exists as long as the handle to it is not closed.
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes)
Retrieve the algorithm policy from key attributes.
static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
Declare usage flags for a key.
static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
Set the location of a persistent key.
static psa_hash_operation_t psa_hash_operation_init(void)
Return an initial value for a hash operation object.
static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes)
Retrieve the lifetime from key attributes.
static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type)
Declare the type of a key.
static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)
Retrieve the key identifier from key attributes.
static size_t psa_get_key_bits(const psa_key_attributes_t *attributes)
Retrieve the key size from key attributes.
psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, psa_key_type_t type, const uint8_t *data, size_t data_length)
Set domain parameters for a key.
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.
#define PSA_KEY_LIFETIME_PERSISTENT
The default storage area for persistent keys.
static psa_cipher_operation_t psa_cipher_operation_init(void)
Return an initial value for a cipher operation object.
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)
Declare the permitted algorithm policy for a key.
uint16_t psa_key_type_t
Encoding of a key type.
static psa_aead_operation_t psa_aead_operation_init(void)
Return an initial value for an AEAD operation object.
static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes)
Retrieve the key type from key attributes.
static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)
Retrieve the usage flags from key attributes.
static psa_key_attributes_t psa_key_attributes_init(void)
Return an initial value for a key attributes structure.
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
static psa_mac_operation_t psa_mac_operation_init(void)
Return an initial value for a MAC operation object.
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.