crypto_struct.h (18934B)
1 /** 2 * \file psa/crypto_struct.h 3 * 4 * \brief PSA cryptography module: Mbed TLS structured type implementations 5 * 6 * \note This file may not be included directly. Applications must 7 * include psa/crypto.h. 8 * 9 * This file contains the definitions of some data structures with 10 * implementation-specific definitions. 11 * 12 * In implementations with isolation between the application and the 13 * cryptography module, it is expected that the front-end and the back-end 14 * would have different versions of this file. 15 * 16 * <h3>Design notes about multipart operation structures</h3> 17 * 18 * For multipart operations without driver delegation support, each multipart 19 * operation structure contains a `psa_algorithm_t alg` field which indicates 20 * which specific algorithm the structure is for. When the structure is not in 21 * use, `alg` is 0. Most of the structure consists of a union which is 22 * discriminated by `alg`. 23 * 24 * For multipart operations with driver delegation support, each multipart 25 * operation structure contains an `unsigned int id` field indicating which 26 * driver got assigned to do the operation. When the structure is not in use, 27 * 'id' is 0. The structure contains also a driver context which is the union 28 * of the contexts of all drivers able to handle the type of multipart 29 * operation. 30 * 31 * Note that when `alg` or `id` is 0, the content of other fields is undefined. 32 * In particular, it is not guaranteed that a freshly-initialized structure 33 * is all-zero: we initialize structures to something like `{0, 0}`, which 34 * is only guaranteed to initializes the first member of the union; 35 * GCC and Clang initialize the whole structure to 0 (at the time of writing), 36 * but MSVC and CompCert don't. 37 * 38 * In Mbed TLS, multipart operation structures live independently from 39 * the key. This allows Mbed TLS to free the key objects when destroying 40 * a key slot. If a multipart operation needs to remember the key after 41 * the setup function returns, the operation structure needs to contain a 42 * copy of the key. 43 */ 44 /* 45 * Copyright The Mbed TLS Contributors 46 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 47 */ 48 49 #ifndef PSA_CRYPTO_STRUCT_H 50 #define PSA_CRYPTO_STRUCT_H 51 #include "mbedtls/private_access.h" 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 /* 58 * Include the build-time configuration information header. Here, we do not 59 * include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which 60 * is basically just an alias to it. This is to ease the maintenance of the 61 * TF-PSA-Crypto repository which has a different build system and 62 * configuration. 63 */ 64 #include "psa/build_info.h" 65 66 /* Include the context definition for the compiled-in drivers for the primitive 67 * algorithms. */ 68 #include "psa/crypto_driver_contexts_primitives.h" 69 70 struct psa_hash_operation_s { 71 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 72 mbedtls_psa_client_handle_t handle; 73 #else 74 /** Unique ID indicating which driver got assigned to do the 75 * operation. Since driver contexts are driver-specific, swapping 76 * drivers halfway through the operation is not supported. 77 * ID values are auto-generated in psa_driver_wrappers.h. 78 * ID value zero means the context is not valid or not assigned to 79 * any driver (i.e. the driver context is not active, in use). */ 80 unsigned int MBEDTLS_PRIVATE(id); 81 psa_driver_hash_context_t MBEDTLS_PRIVATE(ctx); 82 #endif 83 }; 84 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 85 #define PSA_HASH_OPERATION_INIT { 0 } 86 #else 87 #define PSA_HASH_OPERATION_INIT { 0, { 0 } } 88 #endif 89 static inline struct psa_hash_operation_s psa_hash_operation_init(void) 90 { 91 const struct psa_hash_operation_s v = PSA_HASH_OPERATION_INIT; 92 return v; 93 } 94 95 struct psa_cipher_operation_s { 96 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 97 mbedtls_psa_client_handle_t handle; 98 #else 99 /** Unique ID indicating which driver got assigned to do the 100 * operation. Since driver contexts are driver-specific, swapping 101 * drivers halfway through the operation is not supported. 102 * ID values are auto-generated in psa_crypto_driver_wrappers.h 103 * ID value zero means the context is not valid or not assigned to 104 * any driver (i.e. none of the driver contexts are active). */ 105 unsigned int MBEDTLS_PRIVATE(id); 106 107 unsigned int MBEDTLS_PRIVATE(iv_required) : 1; 108 unsigned int MBEDTLS_PRIVATE(iv_set) : 1; 109 110 uint8_t MBEDTLS_PRIVATE(default_iv_length); 111 112 psa_driver_cipher_context_t MBEDTLS_PRIVATE(ctx); 113 #endif 114 }; 115 116 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 117 #define PSA_CIPHER_OPERATION_INIT { 0 } 118 #else 119 #define PSA_CIPHER_OPERATION_INIT { 0, 0, 0, 0, { 0 } } 120 #endif 121 static inline struct psa_cipher_operation_s psa_cipher_operation_init(void) 122 { 123 const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT; 124 return v; 125 } 126 127 /* Include the context definition for the compiled-in drivers for the composite 128 * algorithms. */ 129 #include "psa/crypto_driver_contexts_composites.h" 130 131 struct psa_mac_operation_s { 132 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 133 mbedtls_psa_client_handle_t handle; 134 #else 135 /** Unique ID indicating which driver got assigned to do the 136 * operation. Since driver contexts are driver-specific, swapping 137 * drivers halfway through the operation is not supported. 138 * ID values are auto-generated in psa_driver_wrappers.h 139 * ID value zero means the context is not valid or not assigned to 140 * any driver (i.e. none of the driver contexts are active). */ 141 unsigned int MBEDTLS_PRIVATE(id); 142 uint8_t MBEDTLS_PRIVATE(mac_size); 143 unsigned int MBEDTLS_PRIVATE(is_sign) : 1; 144 psa_driver_mac_context_t MBEDTLS_PRIVATE(ctx); 145 #endif 146 }; 147 148 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 149 #define PSA_MAC_OPERATION_INIT { 0 } 150 #else 151 #define PSA_MAC_OPERATION_INIT { 0, 0, 0, { 0 } } 152 #endif 153 static inline struct psa_mac_operation_s psa_mac_operation_init(void) 154 { 155 const struct psa_mac_operation_s v = PSA_MAC_OPERATION_INIT; 156 return v; 157 } 158 159 struct psa_aead_operation_s { 160 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 161 mbedtls_psa_client_handle_t handle; 162 #else 163 /** Unique ID indicating which driver got assigned to do the 164 * operation. Since driver contexts are driver-specific, swapping 165 * drivers halfway through the operation is not supported. 166 * ID values are auto-generated in psa_crypto_driver_wrappers.h 167 * ID value zero means the context is not valid or not assigned to 168 * any driver (i.e. none of the driver contexts are active). */ 169 unsigned int MBEDTLS_PRIVATE(id); 170 171 psa_algorithm_t MBEDTLS_PRIVATE(alg); 172 psa_key_type_t MBEDTLS_PRIVATE(key_type); 173 174 size_t MBEDTLS_PRIVATE(ad_remaining); 175 size_t MBEDTLS_PRIVATE(body_remaining); 176 177 unsigned int MBEDTLS_PRIVATE(nonce_set) : 1; 178 unsigned int MBEDTLS_PRIVATE(lengths_set) : 1; 179 unsigned int MBEDTLS_PRIVATE(ad_started) : 1; 180 unsigned int MBEDTLS_PRIVATE(body_started) : 1; 181 unsigned int MBEDTLS_PRIVATE(is_encrypt) : 1; 182 183 psa_driver_aead_context_t MBEDTLS_PRIVATE(ctx); 184 #endif 185 }; 186 187 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 188 #define PSA_AEAD_OPERATION_INIT { 0 } 189 #else 190 #define PSA_AEAD_OPERATION_INIT { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, { 0 } } 191 #endif 192 static inline struct psa_aead_operation_s psa_aead_operation_init(void) 193 { 194 const struct psa_aead_operation_s v = PSA_AEAD_OPERATION_INIT; 195 return v; 196 } 197 198 /* Include the context definition for the compiled-in drivers for the key 199 * derivation algorithms. */ 200 #include "psa/crypto_driver_contexts_key_derivation.h" 201 202 struct psa_key_derivation_s { 203 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 204 mbedtls_psa_client_handle_t handle; 205 #else 206 psa_algorithm_t MBEDTLS_PRIVATE(alg); 207 unsigned int MBEDTLS_PRIVATE(can_output_key) : 1; 208 size_t MBEDTLS_PRIVATE(capacity); 209 psa_driver_key_derivation_context_t MBEDTLS_PRIVATE(ctx); 210 #endif 211 }; 212 213 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 214 #define PSA_KEY_DERIVATION_OPERATION_INIT { 0 } 215 #else 216 /* This only zeroes out the first byte in the union, the rest is unspecified. */ 217 #define PSA_KEY_DERIVATION_OPERATION_INIT { 0, 0, 0, { 0 } } 218 #endif 219 static inline struct psa_key_derivation_s psa_key_derivation_operation_init( 220 void) 221 { 222 const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT; 223 return v; 224 } 225 226 struct psa_custom_key_parameters_s { 227 /* Future versions may add other fields in this structure. */ 228 uint32_t flags; 229 }; 230 231 /** The default production parameters for key generation or key derivation. 232 * 233 * Calling psa_generate_key_custom() or psa_key_derivation_output_key_custom() 234 * with `custom=PSA_CUSTOM_KEY_PARAMETERS_INIT` and `custom_data_length=0` is 235 * equivalent to calling psa_generate_key() or psa_key_derivation_output_key() 236 * respectively. 237 */ 238 #define PSA_CUSTOM_KEY_PARAMETERS_INIT { 0 } 239 240 #ifndef __cplusplus 241 /* Omitted when compiling in C++, because one of the parameters is a 242 * pointer to a struct with a flexible array member, and that is not 243 * standard C++. 244 * https://github.com/Mbed-TLS/mbedtls/issues/9020 245 */ 246 /* This is a deprecated variant of `struct psa_custom_key_parameters_s`. 247 * It has exactly the same layout, plus an extra field which is a flexible 248 * array member. Thus a `const struct psa_key_production_parameters_s *` 249 * can be passed to any function that reads a 250 * `const struct psa_custom_key_parameters_s *`. 251 */ 252 struct psa_key_production_parameters_s { 253 uint32_t flags; 254 uint8_t data[]; 255 }; 256 257 /** The default production parameters for key generation or key derivation. 258 * 259 * Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext() 260 * with `params=PSA_KEY_PRODUCTION_PARAMETERS_INIT` and 261 * `params_data_length == 0` is equivalent to 262 * calling psa_generate_key() or psa_key_derivation_output_key() 263 * respectively. 264 */ 265 #define PSA_KEY_PRODUCTION_PARAMETERS_INIT { 0 } 266 #endif /* !__cplusplus */ 267 268 struct psa_key_policy_s { 269 psa_key_usage_t MBEDTLS_PRIVATE(usage); 270 psa_algorithm_t MBEDTLS_PRIVATE(alg); 271 psa_algorithm_t MBEDTLS_PRIVATE(alg2); 272 }; 273 typedef struct psa_key_policy_s psa_key_policy_t; 274 275 #define PSA_KEY_POLICY_INIT { 0, 0, 0 } 276 static inline struct psa_key_policy_s psa_key_policy_init(void) 277 { 278 const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT; 279 return v; 280 } 281 282 /* The type used internally for key sizes. 283 * Public interfaces use size_t, but internally we use a smaller type. */ 284 typedef uint16_t psa_key_bits_t; 285 /* The maximum value of the type used to represent bit-sizes. 286 * This is used to mark an invalid key size. */ 287 #define PSA_KEY_BITS_TOO_LARGE ((psa_key_bits_t) -1) 288 /* The maximum size of a key in bits. 289 * Currently defined as the maximum that can be represented, rounded down 290 * to a whole number of bytes. 291 * This is an uncast value so that it can be used in preprocessor 292 * conditionals. */ 293 #define PSA_MAX_KEY_BITS 0xfff8 294 295 struct psa_key_attributes_s { 296 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 297 psa_key_slot_number_t MBEDTLS_PRIVATE(slot_number); 298 int MBEDTLS_PRIVATE(has_slot_number); 299 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */ 300 psa_key_type_t MBEDTLS_PRIVATE(type); 301 psa_key_bits_t MBEDTLS_PRIVATE(bits); 302 psa_key_lifetime_t MBEDTLS_PRIVATE(lifetime); 303 psa_key_policy_t MBEDTLS_PRIVATE(policy); 304 /* This type has a different layout in the client view wrt the 305 * service view of the key id, i.e. in service view usually is 306 * expected to have MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER defined 307 * thus adding an owner field to the standard psa_key_id_t. For 308 * implementations with client/service separation, this means the 309 * object will be marshalled through a transport channel and 310 * interpreted differently at each side of the transport. Placing 311 * it at the end of structures allows to interpret the structure 312 * at the client without reorganizing the memory layout of the 313 * struct 314 */ 315 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(id); 316 }; 317 318 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 319 #define PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER 0, 0, 320 #else 321 #define PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER 322 #endif 323 #define PSA_KEY_ATTRIBUTES_INIT { PSA_KEY_ATTRIBUTES_MAYBE_SLOT_NUMBER \ 324 PSA_KEY_TYPE_NONE, 0, \ 325 PSA_KEY_LIFETIME_VOLATILE, \ 326 PSA_KEY_POLICY_INIT, \ 327 MBEDTLS_SVC_KEY_ID_INIT } 328 329 static inline struct psa_key_attributes_s psa_key_attributes_init(void) 330 { 331 const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT; 332 return v; 333 } 334 335 static inline void psa_set_key_id(psa_key_attributes_t *attributes, 336 mbedtls_svc_key_id_t key) 337 { 338 psa_key_lifetime_t lifetime = attributes->MBEDTLS_PRIVATE(lifetime); 339 340 attributes->MBEDTLS_PRIVATE(id) = key; 341 342 if (PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)) { 343 attributes->MBEDTLS_PRIVATE(lifetime) = 344 PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION( 345 PSA_KEY_LIFETIME_PERSISTENT, 346 PSA_KEY_LIFETIME_GET_LOCATION(lifetime)); 347 } 348 } 349 350 static inline mbedtls_svc_key_id_t psa_get_key_id( 351 const psa_key_attributes_t *attributes) 352 { 353 return attributes->MBEDTLS_PRIVATE(id); 354 } 355 356 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER 357 static inline void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes, 358 mbedtls_key_owner_id_t owner) 359 { 360 attributes->MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(owner) = owner; 361 } 362 #endif 363 364 static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes, 365 psa_key_lifetime_t lifetime) 366 { 367 attributes->MBEDTLS_PRIVATE(lifetime) = lifetime; 368 if (PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)) { 369 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER 370 attributes->MBEDTLS_PRIVATE(id).MBEDTLS_PRIVATE(key_id) = 0; 371 #else 372 attributes->MBEDTLS_PRIVATE(id) = 0; 373 #endif 374 } 375 } 376 377 static inline psa_key_lifetime_t psa_get_key_lifetime( 378 const psa_key_attributes_t *attributes) 379 { 380 return attributes->MBEDTLS_PRIVATE(lifetime); 381 } 382 383 static inline void psa_extend_key_usage_flags(psa_key_usage_t *usage_flags) 384 { 385 if (*usage_flags & PSA_KEY_USAGE_SIGN_HASH) { 386 *usage_flags |= PSA_KEY_USAGE_SIGN_MESSAGE; 387 } 388 389 if (*usage_flags & PSA_KEY_USAGE_VERIFY_HASH) { 390 *usage_flags |= PSA_KEY_USAGE_VERIFY_MESSAGE; 391 } 392 } 393 394 static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes, 395 psa_key_usage_t usage_flags) 396 { 397 psa_extend_key_usage_flags(&usage_flags); 398 attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage) = usage_flags; 399 } 400 401 static inline psa_key_usage_t psa_get_key_usage_flags( 402 const psa_key_attributes_t *attributes) 403 { 404 return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(usage); 405 } 406 407 static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes, 408 psa_algorithm_t alg) 409 { 410 attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg) = alg; 411 } 412 413 static inline psa_algorithm_t psa_get_key_algorithm( 414 const psa_key_attributes_t *attributes) 415 { 416 return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg); 417 } 418 419 static inline void psa_set_key_type(psa_key_attributes_t *attributes, 420 psa_key_type_t type) 421 { 422 attributes->MBEDTLS_PRIVATE(type) = type; 423 } 424 425 static inline psa_key_type_t psa_get_key_type( 426 const psa_key_attributes_t *attributes) 427 { 428 return attributes->MBEDTLS_PRIVATE(type); 429 } 430 431 static inline void psa_set_key_bits(psa_key_attributes_t *attributes, 432 size_t bits) 433 { 434 if (bits > PSA_MAX_KEY_BITS) { 435 attributes->MBEDTLS_PRIVATE(bits) = PSA_KEY_BITS_TOO_LARGE; 436 } else { 437 attributes->MBEDTLS_PRIVATE(bits) = (psa_key_bits_t) bits; 438 } 439 } 440 441 static inline size_t psa_get_key_bits( 442 const psa_key_attributes_t *attributes) 443 { 444 return attributes->MBEDTLS_PRIVATE(bits); 445 } 446 447 /** 448 * \brief The context for PSA interruptible hash signing. 449 */ 450 struct psa_sign_hash_interruptible_operation_s { 451 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 452 mbedtls_psa_client_handle_t handle; 453 #else 454 /** Unique ID indicating which driver got assigned to do the 455 * operation. Since driver contexts are driver-specific, swapping 456 * drivers halfway through the operation is not supported. 457 * ID values are auto-generated in psa_crypto_driver_wrappers.h 458 * ID value zero means the context is not valid or not assigned to 459 * any driver (i.e. none of the driver contexts are active). */ 460 unsigned int MBEDTLS_PRIVATE(id); 461 462 psa_driver_sign_hash_interruptible_context_t MBEDTLS_PRIVATE(ctx); 463 464 unsigned int MBEDTLS_PRIVATE(error_occurred) : 1; 465 466 uint32_t MBEDTLS_PRIVATE(num_ops); 467 #endif 468 }; 469 470 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 471 #define PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT { 0 } 472 #else 473 #define PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT { 0, { 0 }, 0, 0 } 474 #endif 475 476 static inline struct psa_sign_hash_interruptible_operation_s 477 psa_sign_hash_interruptible_operation_init(void) 478 { 479 const struct psa_sign_hash_interruptible_operation_s v = 480 PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT; 481 482 return v; 483 } 484 485 /** 486 * \brief The context for PSA interruptible hash verification. 487 */ 488 struct psa_verify_hash_interruptible_operation_s { 489 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 490 mbedtls_psa_client_handle_t handle; 491 #else 492 /** Unique ID indicating which driver got assigned to do the 493 * operation. Since driver contexts are driver-specific, swapping 494 * drivers halfway through the operation is not supported. 495 * ID values are auto-generated in psa_crypto_driver_wrappers.h 496 * ID value zero means the context is not valid or not assigned to 497 * any driver (i.e. none of the driver contexts are active). */ 498 unsigned int MBEDTLS_PRIVATE(id); 499 500 psa_driver_verify_hash_interruptible_context_t MBEDTLS_PRIVATE(ctx); 501 502 unsigned int MBEDTLS_PRIVATE(error_occurred) : 1; 503 504 uint32_t MBEDTLS_PRIVATE(num_ops); 505 #endif 506 }; 507 508 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 509 #define PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT { 0 } 510 #else 511 #define PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT { 0, { 0 }, 0, 0 } 512 #endif 513 514 static inline struct psa_verify_hash_interruptible_operation_s 515 psa_verify_hash_interruptible_operation_init(void) 516 { 517 const struct psa_verify_hash_interruptible_operation_s v = 518 PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT; 519 520 return v; 521 } 522 523 #ifdef __cplusplus 524 } 525 #endif 526 527 #endif /* PSA_CRYPTO_STRUCT_H */