1 /** 2 * \file psa/crypto_extra.h 3 * 4 * \brief PSA cryptography module: Mbed TLS vendor extensions 5 * 6 * \note This file may not be included directly. Applications must 7 * include psa/crypto.h. 8 * 9 * This file is reserved for vendor-specific definitions. 10 */ 11 /* 12 * Copyright The Mbed TLS Contributors 13 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 14 */ 15 16 #ifndef PSA_CRYPTO_EXTRA_H 17 #define PSA_CRYPTO_EXTRA_H 18 #include "mbedtls/private_access.h" 19 20 #include "crypto_types.h" 21 #include "crypto_compat.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* UID for secure storage seed */ 28 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52 29 30 /* See mbedtls_config.h for definition */ 31 #if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT) 32 #define MBEDTLS_PSA_KEY_SLOT_COUNT 32 33 #endif 34 35 /** \addtogroup attributes 36 * @{ 37 */ 38 39 /** \brief Declare the enrollment algorithm for a key. 40 * 41 * An operation on a key may indifferently use the algorithm set with 42 * psa_set_key_algorithm() or with this function. 43 * 44 * \param[out] attributes The attribute structure to write to. 45 * \param alg2 A second algorithm that the key may be used 46 * for, in addition to the algorithm set with 47 * psa_set_key_algorithm(). 48 * 49 * \warning Setting an enrollment algorithm is not recommended, because 50 * using the same key with different algorithms can allow some 51 * attacks based on arithmetic relations between different 52 * computations made with the same key, or can escalate harmless 53 * side channels into exploitable ones. Use this function only 54 * if it is necessary to support a protocol for which it has been 55 * verified that the usage of the key with multiple algorithms 56 * is safe. 57 */ 58 static inline void psa_set_key_enrollment_algorithm( 59 psa_key_attributes_t *attributes, 60 psa_algorithm_t alg2) 61 { 62 attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2; 63 } 64 65 /** Retrieve the enrollment algorithm policy from key attributes. 66 * 67 * \param[in] attributes The key attribute structure to query. 68 * 69 * \return The enrollment algorithm stored in the attribute structure. 70 */ 71 static inline psa_algorithm_t psa_get_key_enrollment_algorithm( 72 const psa_key_attributes_t *attributes) 73 { 74 return attributes->MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2); 75 } 76 77 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 78 79 /** Retrieve the slot number where a key is stored. 80 * 81 * A slot number is only defined for keys that are stored in a secure 82 * element. 83 * 84 * This information is only useful if the secure element is not entirely 85 * managed through the PSA Cryptography API. It is up to the secure 86 * element driver to decide how PSA slot numbers map to any other interface 87 * that the secure element may have. 88 * 89 * \param[in] attributes The key attribute structure to query. 90 * \param[out] slot_number On success, the slot number containing the key. 91 * 92 * \retval #PSA_SUCCESS 93 * The key is located in a secure element, and \p *slot_number 94 * indicates the slot number that contains it. 95 * \retval #PSA_ERROR_NOT_PERMITTED 96 * The caller is not permitted to query the slot number. 97 * Mbed TLS currently does not return this error. 98 * \retval #PSA_ERROR_INVALID_ARGUMENT 99 * The key is not located in a secure element. 100 */ 101 psa_status_t psa_get_key_slot_number( 102 const psa_key_attributes_t *attributes, 103 psa_key_slot_number_t *slot_number); 104 105 /** Choose the slot number where a key is stored. 106 * 107 * This function declares a slot number in the specified attribute 108 * structure. 109 * 110 * A slot number is only meaningful for keys that are stored in a secure 111 * element. It is up to the secure element driver to decide how PSA slot 112 * numbers map to any other interface that the secure element may have. 113 * 114 * \note Setting a slot number in key attributes for a key creation can 115 * cause the following errors when creating the key: 116 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does 117 * not support choosing a specific slot number. 118 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to 119 * choose slot numbers in general or to choose this specific slot. 120 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not 121 * valid in general or not valid for this specific key. 122 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the 123 * selected slot. 124 * 125 * \param[out] attributes The attribute structure to write to. 126 * \param slot_number The slot number to set. 127 */ 128 static inline void psa_set_key_slot_number( 129 psa_key_attributes_t *attributes, 130 psa_key_slot_number_t slot_number) 131 { 132 attributes->MBEDTLS_PRIVATE(has_slot_number) = 1; 133 attributes->MBEDTLS_PRIVATE(slot_number) = slot_number; 134 } 135 136 /** Remove the slot number attribute from a key attribute structure. 137 * 138 * This function undoes the action of psa_set_key_slot_number(). 139 * 140 * \param[out] attributes The attribute structure to write to. 141 */ 142 static inline void psa_clear_key_slot_number( 143 psa_key_attributes_t *attributes) 144 { 145 attributes->MBEDTLS_PRIVATE(has_slot_number) = 0; 146 } 147 148 /** Register a key that is already present in a secure element. 149 * 150 * The key must be located in a secure element designated by the 151 * lifetime field in \p attributes, in the slot set with 152 * psa_set_key_slot_number() in the attribute structure. 153 * This function makes the key available through the key identifier 154 * specified in \p attributes. 155 * 156 * \param[in] attributes The attributes of the existing key. 157 * - The lifetime must be a persistent lifetime 158 * in a secure element. Volatile lifetimes are 159 * not currently supported. 160 * - The key identifier must be in the valid 161 * range for persistent keys. 162 * - The key type and size must be specified and 163 * must be consistent with the key material 164 * in the secure element. 165 * 166 * \retval #PSA_SUCCESS 167 * The key was successfully registered. 168 * Note that depending on the design of the driver, this may or may 169 * not guarantee that a key actually exists in the designated slot 170 * and is compatible with the specified attributes. 171 * \retval #PSA_ERROR_ALREADY_EXISTS 172 * There is already a key with the identifier specified in 173 * \p attributes. 174 * \retval #PSA_ERROR_NOT_SUPPORTED 175 * The secure element driver for the specified lifetime does not 176 * support registering a key. 177 * \retval #PSA_ERROR_INVALID_ARGUMENT 178 * The identifier in \p attributes is invalid, namely the identifier is 179 * not in the user range, or 180 * \p attributes specifies a lifetime which is not located 181 * in a secure element, or no slot number is specified in \p attributes, 182 * or the specified slot number is not valid. 183 * \retval #PSA_ERROR_NOT_PERMITTED 184 * The caller is not authorized to register the specified key slot. 185 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 186 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 187 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 188 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 189 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 190 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 191 * \retval #PSA_ERROR_BAD_STATE 192 * The library has not been previously initialized by psa_crypto_init(). 193 * It is implementation-dependent whether a failure to initialize 194 * results in this error code. 195 */ 196 psa_status_t mbedtls_psa_register_se_key( 197 const psa_key_attributes_t *attributes); 198 199 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */ 200 201 /**@}*/ 202 203 /** 204 * \brief Library deinitialization. 205 * 206 * This function clears all data associated with the PSA layer, 207 * including the whole key store. 208 * This function is not thread safe, it wipes every key slot regardless of 209 * state and reader count. It should only be called when no slot is in use. 210 * 211 * This is an Mbed TLS extension. 212 */ 213 void mbedtls_psa_crypto_free(void); 214 215 /** \brief Statistics about 216 * resource consumption related to the PSA keystore. 217 * 218 * \note The content of this structure is not part of the stable API and ABI 219 * of Mbed TLS and may change arbitrarily from version to version. 220 */ 221 typedef struct mbedtls_psa_stats_s { 222 /** Number of slots containing key material for a volatile key. */ 223 size_t MBEDTLS_PRIVATE(volatile_slots); 224 /** Number of slots containing key material for a key which is in 225 * internal persistent storage. */ 226 size_t MBEDTLS_PRIVATE(persistent_slots); 227 /** Number of slots containing a reference to a key in a 228 * secure element. */ 229 size_t MBEDTLS_PRIVATE(external_slots); 230 /** Number of slots which are occupied, but do not contain 231 * key material yet. */ 232 size_t MBEDTLS_PRIVATE(half_filled_slots); 233 /** Number of slots that contain cache data. */ 234 size_t MBEDTLS_PRIVATE(cache_slots); 235 /** Number of slots that are not used for anything. */ 236 size_t MBEDTLS_PRIVATE(empty_slots); 237 /** Number of slots that are locked. */ 238 size_t MBEDTLS_PRIVATE(locked_slots); 239 /** Largest key id value among open keys in internal persistent storage. */ 240 psa_key_id_t MBEDTLS_PRIVATE(max_open_internal_key_id); 241 /** Largest key id value among open keys in secure elements. */ 242 psa_key_id_t MBEDTLS_PRIVATE(max_open_external_key_id); 243 } mbedtls_psa_stats_t; 244 245 /** \brief Get statistics about 246 * resource consumption related to the PSA keystore. 247 * 248 * \note When Mbed TLS is built as part of a service, with isolation 249 * between the application and the keystore, the service may or 250 * may not expose this function. 251 */ 252 void mbedtls_psa_get_stats(mbedtls_psa_stats_t *stats); 253 254 /** 255 * \brief Inject an initial entropy seed for the random generator into 256 * secure storage. 257 * 258 * This function injects data to be used as a seed for the random generator 259 * used by the PSA Crypto implementation. On devices that lack a trusted 260 * entropy source (preferably a hardware random number generator), 261 * the Mbed PSA Crypto implementation uses this value to seed its 262 * random generator. 263 * 264 * On devices without a trusted entropy source, this function must be 265 * called exactly once in the lifetime of the device. On devices with 266 * a trusted entropy source, calling this function is optional. 267 * In all cases, this function may only be called before calling any 268 * other function in the PSA Crypto API, including psa_crypto_init(). 269 * 270 * When this function returns successfully, it populates a file in 271 * persistent storage. Once the file has been created, this function 272 * can no longer succeed. 273 * 274 * If any error occurs, this function does not change the system state. 275 * You can call this function again after correcting the reason for the 276 * error if possible. 277 * 278 * \warning This function **can** fail! Callers MUST check the return status. 279 * 280 * \warning If you use this function, you should use it as part of a 281 * factory provisioning process. The value of the injected seed 282 * is critical to the security of the device. It must be 283 * *secret*, *unpredictable* and (statistically) *unique per device*. 284 * You should be generate it randomly using a cryptographically 285 * secure random generator seeded from trusted entropy sources. 286 * You should transmit it securely to the device and ensure 287 * that its value is not leaked or stored anywhere beyond the 288 * needs of transmitting it from the point of generation to 289 * the call of this function, and erase all copies of the value 290 * once this function returns. 291 * 292 * This is an Mbed TLS extension. 293 * 294 * \note This function is only available on the following platforms: 295 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled. 296 * Note that you must provide compatible implementations of 297 * mbedtls_nv_seed_read and mbedtls_nv_seed_write. 298 * * In a client-server integration of PSA Cryptography, on the client side, 299 * if the server supports this feature. 300 * \param[in] seed Buffer containing the seed value to inject. 301 * \param[in] seed_size Size of the \p seed buffer. 302 * The size of the seed in bytes must be greater 303 * or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE 304 * and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM 305 * in `library/entropy_poll.h` in the Mbed TLS source 306 * code. 307 * It must be less or equal to 308 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE. 309 * 310 * \retval #PSA_SUCCESS 311 * The seed value was injected successfully. The random generator 312 * of the PSA Crypto implementation is now ready for use. 313 * You may now call psa_crypto_init() and use the PSA Crypto 314 * implementation. 315 * \retval #PSA_ERROR_INVALID_ARGUMENT 316 * \p seed_size is out of range. 317 * \retval #PSA_ERROR_STORAGE_FAILURE 318 * There was a failure reading or writing from storage. 319 * \retval #PSA_ERROR_NOT_PERMITTED 320 * The library has already been initialized. It is no longer 321 * possible to call this function. 322 */ 323 psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, 324 size_t seed_size); 325 326 /** \addtogroup crypto_types 327 * @{ 328 */ 329 330 /** DSA public key. 331 * 332 * The import and export format is the 333 * representation of the public key `y = g^x mod p` as a big-endian byte 334 * string. The length of the byte string is the length of the base prime `p` 335 * in bytes. 336 */ 337 #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t) 0x4002) 338 339 /** DSA key pair (private and public key). 340 * 341 * The import and export format is the 342 * representation of the private key `x` as a big-endian byte string. The 343 * length of the byte string is the private key size in bytes (leading zeroes 344 * are not stripped). 345 * 346 * Deterministic DSA key derivation with psa_generate_derived_key follows 347 * FIPS 186-4 §B.1.2: interpret the byte string as integer 348 * in big-endian order. Discard it if it is not in the range 349 * [0, *N* - 2] where *N* is the boundary of the private key domain 350 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, 351 * or the order of the curve's base point for ECC). 352 * Add 1 to the resulting integer and use this as the private key *x*. 353 * 354 */ 355 #define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t) 0x7002) 356 357 /** Whether a key type is a DSA key (pair or public-only). */ 358 #define PSA_KEY_TYPE_IS_DSA(type) \ 359 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY) 360 361 #define PSA_ALG_DSA_BASE ((psa_algorithm_t) 0x06000400) 362 /** DSA signature with hashing. 363 * 364 * This is the signature scheme defined by FIPS 186-4, 365 * with a random per-message secret number (*k*). 366 * 367 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 368 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 369 * This includes #PSA_ALG_ANY_HASH 370 * when specifying the algorithm in a usage policy. 371 * 372 * \return The corresponding DSA signature algorithm. 373 * \return Unspecified if \p hash_alg is not a supported 374 * hash algorithm. 375 */ 376 #define PSA_ALG_DSA(hash_alg) \ 377 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 378 #define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t) 0x06000500) 379 #define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG 380 /** Deterministic DSA signature with hashing. 381 * 382 * This is the deterministic variant defined by RFC 6979 of 383 * the signature scheme defined by FIPS 186-4. 384 * 385 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 386 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 387 * This includes #PSA_ALG_ANY_HASH 388 * when specifying the algorithm in a usage policy. 389 * 390 * \return The corresponding DSA signature algorithm. 391 * \return Unspecified if \p hash_alg is not a supported 392 * hash algorithm. 393 */ 394 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \ 395 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 396 #define PSA_ALG_IS_DSA(alg) \ 397 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \ 398 PSA_ALG_DSA_BASE) 399 #define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \ 400 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0) 401 #define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \ 402 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg)) 403 #define PSA_ALG_IS_RANDOMIZED_DSA(alg) \ 404 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg)) 405 406 407 /* We need to expand the sample definition of this macro from 408 * the API definition. */ 409 #undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN 410 #define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \ 411 PSA_ALG_IS_DSA(alg) 412 413 /**@}*/ 414 415 /** \addtogroup attributes 416 * @{ 417 */ 418 419 /** PAKE operation stages. */ 420 #define PSA_PAKE_OPERATION_STAGE_SETUP 0 421 #define PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS 1 422 #define PSA_PAKE_OPERATION_STAGE_COMPUTATION 2 423 424 /**@}*/ 425 426 427 /** \defgroup psa_external_rng External random generator 428 * @{ 429 */ 430 431 #if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 432 /** External random generator function, implemented by the platform. 433 * 434 * When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled, 435 * this function replaces Mbed TLS's entropy and DRBG modules for all 436 * random generation triggered via PSA crypto interfaces. 437 * 438 * \note This random generator must deliver random numbers with cryptographic 439 * quality and high performance. It must supply unpredictable numbers 440 * with a uniform distribution. The implementation of this function 441 * is responsible for ensuring that the random generator is seeded 442 * with sufficient entropy. If you have a hardware TRNG which is slow 443 * or delivers non-uniform output, declare it as an entropy source 444 * with mbedtls_entropy_add_source() instead of enabling this option. 445 * 446 * \param[in,out] context Pointer to the random generator context. 447 * This is all-bits-zero on the first call 448 * and preserved between successive calls. 449 * \param[out] output Output buffer. On success, this buffer 450 * contains random data with a uniform 451 * distribution. 452 * \param output_size The size of the \p output buffer in bytes. 453 * \param[out] output_length On success, set this value to \p output_size. 454 * 455 * \retval #PSA_SUCCESS 456 * Success. The output buffer contains \p output_size bytes of 457 * cryptographic-quality random data, and \c *output_length is 458 * set to \p output_size. 459 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY 460 * The random generator requires extra entropy and there is no 461 * way to obtain entropy under current environment conditions. 462 * This error should not happen under normal circumstances since 463 * this function is responsible for obtaining as much entropy as 464 * it needs. However implementations of this function may return 465 * #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain 466 * entropy without blocking indefinitely. 467 * \retval #PSA_ERROR_HARDWARE_FAILURE 468 * A failure of the random generator hardware that isn't covered 469 * by #PSA_ERROR_INSUFFICIENT_ENTROPY. 470 */ 471 psa_status_t mbedtls_psa_external_get_random( 472 mbedtls_psa_external_random_context_t *context, 473 uint8_t *output, size_t output_size, size_t *output_length); 474 #endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */ 475 476 /**@}*/ 477 478 /** \defgroup psa_builtin_keys Built-in keys 479 * @{ 480 */ 481 482 /** The minimum value for a key identifier that is built into the 483 * implementation. 484 * 485 * The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN 486 * to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from 487 * #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect 488 * with any other set of implementation-chosen key identifiers. 489 * 490 * This value is part of the library's API since changing it would invalidate 491 * the values of built-in key identifiers in applications. 492 */ 493 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t) 0x7fff0000) 494 495 /** The maximum value for a key identifier that is built into the 496 * implementation. 497 * 498 * See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information. 499 */ 500 #define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t) 0x7fffefff) 501 502 /** A slot number identifying a key in a driver. 503 * 504 * Values of this type are used to identify built-in keys. 505 */ 506 typedef uint64_t psa_drv_slot_number_t; 507 508 #if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS) 509 /** Test whether a key identifier belongs to the builtin key range. 510 * 511 * \param key_id Key identifier to test. 512 * 513 * \retval 1 514 * The key identifier is a builtin key identifier. 515 * \retval 0 516 * The key identifier is not a builtin key identifier. 517 */ 518 static inline int psa_key_id_is_builtin(psa_key_id_t key_id) 519 { 520 return (key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN) && 521 (key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX); 522 } 523 524 /** Platform function to obtain the location and slot number of a built-in key. 525 * 526 * An application-specific implementation of this function must be provided if 527 * #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided 528 * as part of a platform's system image. 529 * 530 * #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from 531 * #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX. 532 * 533 * In a multi-application configuration 534 * (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined), 535 * this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id) 536 * is allowed to use the given key. 537 * 538 * \param key_id The key ID for which to retrieve the 539 * location and slot attributes. 540 * \param[out] lifetime On success, the lifetime associated with the key 541 * corresponding to \p key_id. Lifetime is a 542 * combination of which driver contains the key, 543 * and with what persistence level the key is 544 * intended to be used. If the platform 545 * implementation does not contain specific 546 * information about the intended key persistence 547 * level, the persistence level may be reported as 548 * #PSA_KEY_PERSISTENCE_DEFAULT. 549 * \param[out] slot_number On success, the slot number known to the driver 550 * registered at the lifetime location reported 551 * through \p lifetime which corresponds to the 552 * requested built-in key. 553 * 554 * \retval #PSA_SUCCESS 555 * The requested key identifier designates a built-in key. 556 * In a multi-application configuration, the requested owner 557 * is allowed to access it. 558 * \retval #PSA_ERROR_DOES_NOT_EXIST 559 * The requested key identifier is not a built-in key which is known 560 * to this function. If a key exists in the key storage with this 561 * identifier, the data from the storage will be used. 562 * \return (any other error) 563 * Any other error is propagated to the function that requested the key. 564 * Common errors include: 565 * - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner 566 * is not allowed to access it. 567 */ 568 psa_status_t mbedtls_psa_platform_get_builtin_key( 569 mbedtls_svc_key_id_t key_id, 570 psa_key_lifetime_t *lifetime, 571 psa_drv_slot_number_t *slot_number); 572 #endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */ 573 574 /** @} */ 575 576 /** \addtogroup crypto_types 577 * @{ 578 */ 579 580 #define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t) 0x0a000000) 581 582 /** Whether the specified algorithm is a password-authenticated key exchange. 583 * 584 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 585 * 586 * \return 1 if \p alg is a password-authenticated key exchange (PAKE) 587 * algorithm, 0 otherwise. 588 * This macro may return either 0 or 1 if \p alg is not a supported 589 * algorithm identifier. 590 */ 591 #define PSA_ALG_IS_PAKE(alg) \ 592 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE) 593 594 /** The Password-authenticated key exchange by juggling (J-PAKE) algorithm. 595 * 596 * This is J-PAKE as defined by RFC 8236, instantiated with the following 597 * parameters: 598 * 599 * - The group can be either an elliptic curve or defined over a finite field. 600 * - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the 601 * J-PAKE algorithm. 602 * - A cryptographic hash function. 603 * 604 * To select these parameters and set up the cipher suite, call these functions 605 * in any order: 606 * 607 * \code 608 * psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE); 609 * psa_pake_cs_set_primitive(cipher_suite, 610 * PSA_PAKE_PRIMITIVE(type, family, bits)); 611 * psa_pake_cs_set_hash(cipher_suite, hash); 612 * \endcode 613 * 614 * For more information on how to set a specific curve or field, refer to the 615 * documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. 616 * 617 * After initializing a J-PAKE operation, call 618 * 619 * \code 620 * psa_pake_setup(operation, cipher_suite); 621 * psa_pake_set_user(operation, ...); 622 * psa_pake_set_peer(operation, ...); 623 * psa_pake_set_password_key(operation, ...); 624 * \endcode 625 * 626 * The password is provided as a key. This can be the password text itself, 627 * in an agreed character encoding, or some value derived from the password 628 * as required by a higher level protocol. 629 * 630 * (The implementation converts the key material to a number as described in 631 * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_ 632 * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here 633 * \c q is order of the group defined by the primitive set in the cipher suite. 634 * The \c psa_pake_set_password_key() function returns an error if the result 635 * of the reduction is 0.) 636 * 637 * The key exchange flow for J-PAKE is as follows: 638 * -# To get the first round data that needs to be sent to the peer, call 639 * \code 640 * // Get g1 641 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 642 * // Get the ZKP public key for x1 643 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 644 * // Get the ZKP proof for x1 645 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 646 * // Get g2 647 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 648 * // Get the ZKP public key for x2 649 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 650 * // Get the ZKP proof for x2 651 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 652 * \endcode 653 * -# To provide the first round data received from the peer to the operation, 654 * call 655 * \code 656 * // Set g3 657 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 658 * // Set the ZKP public key for x3 659 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 660 * // Set the ZKP proof for x3 661 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 662 * // Set g4 663 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 664 * // Set the ZKP public key for x4 665 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 666 * // Set the ZKP proof for x4 667 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 668 * \endcode 669 * -# To get the second round data that needs to be sent to the peer, call 670 * \code 671 * // Get A 672 * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 673 * // Get ZKP public key for x2*s 674 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 675 * // Get ZKP proof for x2*s 676 * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 677 * \endcode 678 * -# To provide the second round data received from the peer to the operation, 679 * call 680 * \code 681 * // Set B 682 * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...); 683 * // Set ZKP public key for x4*s 684 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...); 685 * // Set ZKP proof for x4*s 686 * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...); 687 * \endcode 688 * -# To access the shared secret call 689 * \code 690 * // Get Ka=Kb=K 691 * psa_pake_get_implicit_key() 692 * \endcode 693 * 694 * For more information consult the documentation of the individual 695 * \c PSA_PAKE_STEP_XXX constants. 696 * 697 * At this point there is a cryptographic guarantee that only the authenticated 698 * party who used the same password is able to compute the key. But there is no 699 * guarantee that the peer is the party it claims to be and was able to do so. 700 * 701 * That is, the authentication is only implicit (the peer is not authenticated 702 * at this point, and no action should be taken that assume that they are - like 703 * for example accessing restricted files). 704 * 705 * To make the authentication explicit there are various methods, see Section 5 706 * of RFC 8236 for two examples. 707 * 708 */ 709 #define PSA_ALG_JPAKE ((psa_algorithm_t) 0x0a000100) 710 711 /** @} */ 712 713 /** \defgroup pake Password-authenticated key exchange (PAKE) 714 * 715 * This is a proposed PAKE interface for the PSA Crypto API. It is not part of 716 * the official PSA Crypto API yet. 717 * 718 * \note The content of this section is not part of the stable API and ABI 719 * of Mbed TLS and may change arbitrarily from version to version. 720 * Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and 721 * #PSA_ALG_JPAKE. 722 * @{ 723 */ 724 725 /** \brief Encoding of the application role of PAKE 726 * 727 * Encodes the application's role in the algorithm is being executed. For more 728 * information see the documentation of individual \c PSA_PAKE_ROLE_XXX 729 * constants. 730 */ 731 typedef uint8_t psa_pake_role_t; 732 733 /** Encoding of input and output indicators for PAKE. 734 * 735 * Some PAKE algorithms need to exchange more data than just a single key share. 736 * This type is for encoding additional input and output data for such 737 * algorithms. 738 */ 739 typedef uint8_t psa_pake_step_t; 740 741 /** Encoding of the type of the PAKE's primitive. 742 * 743 * Values defined by this standard will never be in the range 0x80-0xff. 744 * Vendors who define additional types must use an encoding in this range. 745 * 746 * For more information see the documentation of individual 747 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. 748 */ 749 typedef uint8_t psa_pake_primitive_type_t; 750 751 /** \brief Encoding of the family of the primitive associated with the PAKE. 752 * 753 * For more information see the documentation of individual 754 * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. 755 */ 756 typedef uint8_t psa_pake_family_t; 757 758 /** \brief Encoding of the primitive associated with the PAKE. 759 * 760 * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro. 761 */ 762 typedef uint32_t psa_pake_primitive_t; 763 764 /** A value to indicate no role in a PAKE algorithm. 765 * This value can be used in a call to psa_pake_set_role() for symmetric PAKE 766 * algorithms which do not assign roles. 767 */ 768 #define PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00) 769 770 /** The first peer in a balanced PAKE. 771 * 772 * Although balanced PAKE algorithms are symmetric, some of them needs an 773 * ordering of peers for the transcript calculations. If the algorithm does not 774 * need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are 775 * accepted. 776 */ 777 #define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01) 778 779 /** The second peer in a balanced PAKE. 780 * 781 * Although balanced PAKE algorithms are symmetric, some of them needs an 782 * ordering of peers for the transcript calculations. If the algorithm does not 783 * need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are 784 * accepted. 785 */ 786 #define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02) 787 788 /** The client in an augmented PAKE. 789 * 790 * Augmented PAKE algorithms need to differentiate between client and server. 791 */ 792 #define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11) 793 794 /** The server in an augmented PAKE. 795 * 796 * Augmented PAKE algorithms need to differentiate between client and server. 797 */ 798 #define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12) 799 800 /** The PAKE primitive type indicating the use of elliptic curves. 801 * 802 * The values of the \c family and \c bits fields of the cipher suite identify a 803 * specific elliptic curve, using the same mapping that is used for ECC 804 * (::psa_ecc_family_t) keys. 805 * 806 * (Here \c family means the value returned by psa_pake_cs_get_family() and 807 * \c bits means the value returned by psa_pake_cs_get_bits().) 808 * 809 * Input and output during the operation can involve group elements and scalar 810 * values: 811 * -# The format for group elements is the same as for public keys on the 812 * specific curve would be. For more information, consult the documentation of 813 * psa_export_public_key(). 814 * -# The format for scalars is the same as for private keys on the specific 815 * curve would be. For more information, consult the documentation of 816 * psa_export_key(). 817 */ 818 #define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01) 819 820 /** The PAKE primitive type indicating the use of Diffie-Hellman groups. 821 * 822 * The values of the \c family and \c bits fields of the cipher suite identify 823 * a specific Diffie-Hellman group, using the same mapping that is used for 824 * Diffie-Hellman (::psa_dh_family_t) keys. 825 * 826 * (Here \c family means the value returned by psa_pake_cs_get_family() and 827 * \c bits means the value returned by psa_pake_cs_get_bits().) 828 * 829 * Input and output during the operation can involve group elements and scalar 830 * values: 831 * -# The format for group elements is the same as for public keys on the 832 * specific group would be. For more information, consult the documentation of 833 * psa_export_public_key(). 834 * -# The format for scalars is the same as for private keys on the specific 835 * group would be. For more information, consult the documentation of 836 * psa_export_key(). 837 */ 838 #define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02) 839 840 /** Construct a PAKE primitive from type, family and bit-size. 841 * 842 * \param pake_type The type of the primitive 843 * (value of type ::psa_pake_primitive_type_t). 844 * \param pake_family The family of the primitive 845 * (the type and interpretation of this parameter depends 846 * on \p pake_type, for more information consult the 847 * documentation of individual ::psa_pake_primitive_type_t 848 * constants). 849 * \param pake_bits The bit-size of the primitive 850 * (Value of type \c size_t. The interpretation 851 * of this parameter depends on \p pake_family, for more 852 * information consult the documentation of individual 853 * ::psa_pake_primitive_type_t constants). 854 * 855 * \return The constructed primitive value of type ::psa_pake_primitive_t. 856 * Return 0 if the requested primitive can't be encoded as 857 * ::psa_pake_primitive_t. 858 */ 859 #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ 860 ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \ 861 ((psa_pake_primitive_t) (((pake_type) << 24 | \ 862 (pake_family) << 16) | (pake_bits))) 863 864 /** The key share being sent to or received from the peer. 865 * 866 * The format for both input and output at this step is the same as for public 867 * keys on the group determined by the primitive (::psa_pake_primitive_t) would 868 * be. 869 * 870 * For more information on the format, consult the documentation of 871 * psa_export_public_key(). 872 * 873 * For information regarding how the group is determined, consult the 874 * documentation #PSA_PAKE_PRIMITIVE. 875 */ 876 #define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01) 877 878 /** A Schnorr NIZKP public key. 879 * 880 * This is the ephemeral public key in the Schnorr Non-Interactive 881 * Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235). 882 * 883 * The format for both input and output at this step is the same as for public 884 * keys on the group determined by the primitive (::psa_pake_primitive_t) would 885 * be. 886 * 887 * For more information on the format, consult the documentation of 888 * psa_export_public_key(). 889 * 890 * For information regarding how the group is determined, consult the 891 * documentation #PSA_PAKE_PRIMITIVE. 892 */ 893 #define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02) 894 895 /** A Schnorr NIZKP proof. 896 * 897 * This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the 898 * value denoted by the letter 'r' in RFC 8235). 899 * 900 * Both for input and output, the value at this step is an integer less than 901 * the order of the group selected in the cipher suite. The format depends on 902 * the group as well: 903 * 904 * - For Montgomery curves, the encoding is little endian. 905 * - For everything else the encoding is big endian (see Section 2.3.8 of 906 * _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf). 907 * 908 * In both cases leading zeroes are allowed as long as the length in bytes does 909 * not exceed the byte length of the group order. 910 * 911 * For information regarding how the group is determined, consult the 912 * documentation #PSA_PAKE_PRIMITIVE. 913 */ 914 #define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03) 915 916 /** The type of the data structure for PAKE cipher suites. 917 * 918 * This is an implementation-defined \c struct. Applications should not 919 * make any assumptions about the content of this structure. 920 * Implementation details can change in future versions without notice. 921 */ 922 typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t; 923 924 /** Return an initial value for a PAKE cipher suite object. 925 */ 926 static psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void); 927 928 /** Retrieve the PAKE algorithm from a PAKE cipher suite. 929 * 930 * \param[in] cipher_suite The cipher suite structure to query. 931 * 932 * \return The PAKE algorithm stored in the cipher suite structure. 933 */ 934 static psa_algorithm_t psa_pake_cs_get_algorithm( 935 const psa_pake_cipher_suite_t *cipher_suite); 936 937 /** Declare the PAKE algorithm for the cipher suite. 938 * 939 * This function overwrites any PAKE algorithm 940 * previously set in \p cipher_suite. 941 * 942 * \param[out] cipher_suite The cipher suite structure to write to. 943 * \param algorithm The PAKE algorithm to write. 944 * (`PSA_ALG_XXX` values of type ::psa_algorithm_t 945 * such that #PSA_ALG_IS_PAKE(\c alg) is true.) 946 * If this is 0, the PAKE algorithm in 947 * \p cipher_suite becomes unspecified. 948 */ 949 static void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t *cipher_suite, 950 psa_algorithm_t algorithm); 951 952 /** Retrieve the primitive from a PAKE cipher suite. 953 * 954 * \param[in] cipher_suite The cipher suite structure to query. 955 * 956 * \return The primitive stored in the cipher suite structure. 957 */ 958 static psa_pake_primitive_t psa_pake_cs_get_primitive( 959 const psa_pake_cipher_suite_t *cipher_suite); 960 961 /** Declare the primitive for a PAKE cipher suite. 962 * 963 * This function overwrites any primitive previously set in \p cipher_suite. 964 * 965 * \param[out] cipher_suite The cipher suite structure to write to. 966 * \param primitive The primitive to write. If this is 0, the 967 * primitive type in \p cipher_suite becomes 968 * unspecified. 969 */ 970 static void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t *cipher_suite, 971 psa_pake_primitive_t primitive); 972 973 /** Retrieve the PAKE family from a PAKE cipher suite. 974 * 975 * \param[in] cipher_suite The cipher suite structure to query. 976 * 977 * \return The PAKE family stored in the cipher suite structure. 978 */ 979 static psa_pake_family_t psa_pake_cs_get_family( 980 const psa_pake_cipher_suite_t *cipher_suite); 981 982 /** Retrieve the PAKE primitive bit-size from a PAKE cipher suite. 983 * 984 * \param[in] cipher_suite The cipher suite structure to query. 985 * 986 * \return The PAKE primitive bit-size stored in the cipher suite structure. 987 */ 988 static uint16_t psa_pake_cs_get_bits( 989 const psa_pake_cipher_suite_t *cipher_suite); 990 991 /** Retrieve the hash algorithm from a PAKE cipher suite. 992 * 993 * \param[in] cipher_suite The cipher suite structure to query. 994 * 995 * \return The hash algorithm stored in the cipher suite structure. The return 996 * value is 0 if the PAKE is not parametrised by a hash algorithm or if 997 * the hash algorithm is not set. 998 */ 999 static psa_algorithm_t psa_pake_cs_get_hash( 1000 const psa_pake_cipher_suite_t *cipher_suite); 1001 1002 /** Declare the hash algorithm for a PAKE cipher suite. 1003 * 1004 * This function overwrites any hash algorithm 1005 * previously set in \p cipher_suite. 1006 * 1007 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1008 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1009 * for more information. 1010 * 1011 * \param[out] cipher_suite The cipher suite structure to write to. 1012 * \param hash The hash involved in the cipher suite. 1013 * (`PSA_ALG_XXX` values of type ::psa_algorithm_t 1014 * such that #PSA_ALG_IS_HASH(\c alg) is true.) 1015 * If this is 0, the hash algorithm in 1016 * \p cipher_suite becomes unspecified. 1017 */ 1018 static void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite, 1019 psa_algorithm_t hash); 1020 1021 /** The type of the state data structure for PAKE operations. 1022 * 1023 * Before calling any function on a PAKE operation object, the application 1024 * must initialize it by any of the following means: 1025 * - Set the structure to all-bits-zero, for example: 1026 * \code 1027 * psa_pake_operation_t operation; 1028 * memset(&operation, 0, sizeof(operation)); 1029 * \endcode 1030 * - Initialize the structure to logical zero values, for example: 1031 * \code 1032 * psa_pake_operation_t operation = {0}; 1033 * \endcode 1034 * - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT, 1035 * for example: 1036 * \code 1037 * psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT; 1038 * \endcode 1039 * - Assign the result of the function psa_pake_operation_init() 1040 * to the structure, for example: 1041 * \code 1042 * psa_pake_operation_t operation; 1043 * operation = psa_pake_operation_init(); 1044 * \endcode 1045 * 1046 * This is an implementation-defined \c struct. Applications should not 1047 * make any assumptions about the content of this structure. 1048 * Implementation details can change in future versions without notice. */ 1049 typedef struct psa_pake_operation_s psa_pake_operation_t; 1050 1051 /** The type of input values for PAKE operations. */ 1052 typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t; 1053 1054 /** The type of computation stage for J-PAKE operations. */ 1055 typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t; 1056 1057 /** Return an initial value for a PAKE operation object. 1058 */ 1059 static psa_pake_operation_t psa_pake_operation_init(void); 1060 1061 /** Get the length of the password in bytes from given inputs. 1062 * 1063 * \param[in] inputs Operation inputs. 1064 * \param[out] password_len Password length. 1065 * 1066 * \retval #PSA_SUCCESS 1067 * Success. 1068 * \retval #PSA_ERROR_BAD_STATE 1069 * Password hasn't been set yet. 1070 */ 1071 psa_status_t psa_crypto_driver_pake_get_password_len( 1072 const psa_crypto_driver_pake_inputs_t *inputs, 1073 size_t *password_len); 1074 1075 /** Get the password from given inputs. 1076 * 1077 * \param[in] inputs Operation inputs. 1078 * \param[out] buffer Return buffer for password. 1079 * \param buffer_size Size of the return buffer in bytes. 1080 * \param[out] buffer_length Actual size of the password in bytes. 1081 * 1082 * \retval #PSA_SUCCESS 1083 * Success. 1084 * \retval #PSA_ERROR_BAD_STATE 1085 * Password hasn't been set yet. 1086 */ 1087 psa_status_t psa_crypto_driver_pake_get_password( 1088 const psa_crypto_driver_pake_inputs_t *inputs, 1089 uint8_t *buffer, size_t buffer_size, size_t *buffer_length); 1090 1091 /** Get the length of the user id in bytes from given inputs. 1092 * 1093 * \param[in] inputs Operation inputs. 1094 * \param[out] user_len User id length. 1095 * 1096 * \retval #PSA_SUCCESS 1097 * Success. 1098 * \retval #PSA_ERROR_BAD_STATE 1099 * User id hasn't been set yet. 1100 */ 1101 psa_status_t psa_crypto_driver_pake_get_user_len( 1102 const psa_crypto_driver_pake_inputs_t *inputs, 1103 size_t *user_len); 1104 1105 /** Get the length of the peer id in bytes from given inputs. 1106 * 1107 * \param[in] inputs Operation inputs. 1108 * \param[out] peer_len Peer id length. 1109 * 1110 * \retval #PSA_SUCCESS 1111 * Success. 1112 * \retval #PSA_ERROR_BAD_STATE 1113 * Peer id hasn't been set yet. 1114 */ 1115 psa_status_t psa_crypto_driver_pake_get_peer_len( 1116 const psa_crypto_driver_pake_inputs_t *inputs, 1117 size_t *peer_len); 1118 1119 /** Get the user id from given inputs. 1120 * 1121 * \param[in] inputs Operation inputs. 1122 * \param[out] user_id User id. 1123 * \param user_id_size Size of \p user_id in bytes. 1124 * \param[out] user_id_len Size of the user id in bytes. 1125 * 1126 * \retval #PSA_SUCCESS 1127 * Success. 1128 * \retval #PSA_ERROR_BAD_STATE 1129 * User id hasn't been set yet. 1130 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1131 * The size of the \p user_id is too small. 1132 */ 1133 psa_status_t psa_crypto_driver_pake_get_user( 1134 const psa_crypto_driver_pake_inputs_t *inputs, 1135 uint8_t *user_id, size_t user_id_size, size_t *user_id_len); 1136 1137 /** Get the peer id from given inputs. 1138 * 1139 * \param[in] inputs Operation inputs. 1140 * \param[out] peer_id Peer id. 1141 * \param peer_id_size Size of \p peer_id in bytes. 1142 * \param[out] peer_id_length Size of the peer id in bytes. 1143 * 1144 * \retval #PSA_SUCCESS 1145 * Success. 1146 * \retval #PSA_ERROR_BAD_STATE 1147 * Peer id hasn't been set yet. 1148 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1149 * The size of the \p peer_id is too small. 1150 */ 1151 psa_status_t psa_crypto_driver_pake_get_peer( 1152 const psa_crypto_driver_pake_inputs_t *inputs, 1153 uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length); 1154 1155 /** Get the cipher suite from given inputs. 1156 * 1157 * \param[in] inputs Operation inputs. 1158 * \param[out] cipher_suite Return buffer for role. 1159 * 1160 * \retval #PSA_SUCCESS 1161 * Success. 1162 * \retval #PSA_ERROR_BAD_STATE 1163 * Cipher_suite hasn't been set yet. 1164 */ 1165 psa_status_t psa_crypto_driver_pake_get_cipher_suite( 1166 const psa_crypto_driver_pake_inputs_t *inputs, 1167 psa_pake_cipher_suite_t *cipher_suite); 1168 1169 /** Set the session information for a password-authenticated key exchange. 1170 * 1171 * The sequence of operations to set up a password-authenticated key exchange 1172 * is as follows: 1173 * -# Allocate an operation object which will be passed to all the functions 1174 * listed here. 1175 * -# Initialize the operation object with one of the methods described in the 1176 * documentation for #psa_pake_operation_t, e.g. 1177 * #PSA_PAKE_OPERATION_INIT. 1178 * -# Call psa_pake_setup() to specify the cipher suite. 1179 * -# Call \c psa_pake_set_xxx() functions on the operation to complete the 1180 * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs 1181 * to be called depends on the algorithm in use. 1182 * 1183 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1184 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1185 * for more information. 1186 * 1187 * A typical sequence of calls to perform a password-authenticated key 1188 * exchange: 1189 * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the 1190 * key share that needs to be sent to the peer. 1191 * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide 1192 * the key share that was received from the peer. 1193 * -# Depending on the algorithm additional calls to psa_pake_output() and 1194 * psa_pake_input() might be necessary. 1195 * -# Call psa_pake_get_implicit_key() for accessing the shared secret. 1196 * 1197 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1198 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1199 * for more information. 1200 * 1201 * If an error occurs at any step after a call to psa_pake_setup(), 1202 * the operation will need to be reset by a call to psa_pake_abort(). The 1203 * application may call psa_pake_abort() at any time after the operation 1204 * has been initialized. 1205 * 1206 * After a successful call to psa_pake_setup(), the application must 1207 * eventually terminate the operation. The following events terminate an 1208 * operation: 1209 * - A call to psa_pake_abort(). 1210 * - A successful call to psa_pake_get_implicit_key(). 1211 * 1212 * \param[in,out] operation The operation object to set up. It must have 1213 * been initialized but not set up yet. 1214 * \param[in] cipher_suite The cipher suite to use. (A cipher suite fully 1215 * characterizes a PAKE algorithm and determines 1216 * the algorithm as well.) 1217 * 1218 * \retval #PSA_SUCCESS 1219 * Success. 1220 * \retval #PSA_ERROR_INVALID_ARGUMENT 1221 * The algorithm in \p cipher_suite is not a PAKE algorithm, or the 1222 * PAKE primitive in \p cipher_suite is not compatible with the 1223 * PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid 1224 * or not compatible with the PAKE algorithm and primitive. 1225 * \retval #PSA_ERROR_NOT_SUPPORTED 1226 * The algorithm in \p cipher_suite is not a supported PAKE algorithm, 1227 * or the PAKE primitive in \p cipher_suite is not supported or not 1228 * compatible with the PAKE algorithm, or the hash algorithm in 1229 * \p cipher_suite is not supported or not compatible with the PAKE 1230 * algorithm and primitive. 1231 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1232 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1233 * \retval #PSA_ERROR_BAD_STATE 1234 * The operation state is not valid, or 1235 * the library has not been previously initialized by psa_crypto_init(). 1236 * It is implementation-dependent whether a failure to initialize 1237 * results in this error code. 1238 */ 1239 psa_status_t psa_pake_setup(psa_pake_operation_t *operation, 1240 const psa_pake_cipher_suite_t *cipher_suite); 1241 1242 /** Set the password for a password-authenticated key exchange from key ID. 1243 * 1244 * Call this function when the password, or a value derived from the password, 1245 * is already present in the key store. 1246 * 1247 * \param[in,out] operation The operation object to set the password for. It 1248 * must have been set up by psa_pake_setup() and 1249 * not yet in use (neither psa_pake_output() nor 1250 * psa_pake_input() has been called yet). It must 1251 * be on operation for which the password hasn't 1252 * been set yet (psa_pake_set_password_key() 1253 * hasn't been called yet). 1254 * \param password Identifier of the key holding the password or a 1255 * value derived from the password (eg. by a 1256 * memory-hard function). It must remain valid 1257 * until the operation terminates. It must be of 1258 * type #PSA_KEY_TYPE_PASSWORD or 1259 * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow 1260 * the usage #PSA_KEY_USAGE_DERIVE. 1261 * 1262 * \retval #PSA_SUCCESS 1263 * Success. 1264 * \retval #PSA_ERROR_INVALID_HANDLE 1265 * \p password is not a valid key identifier. 1266 * \retval #PSA_ERROR_NOT_PERMITTED 1267 * The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not 1268 * permit the \p operation's algorithm. 1269 * \retval #PSA_ERROR_INVALID_ARGUMENT 1270 * The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or 1271 * #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with 1272 * the \p operation's cipher suite. 1273 * \retval #PSA_ERROR_NOT_SUPPORTED 1274 * The key type or key size of \p password is not supported with the 1275 * \p operation's cipher suite. 1276 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1277 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1278 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1279 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 1280 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 1281 * \retval #PSA_ERROR_BAD_STATE 1282 * The operation state is not valid (it must have been set up.), or 1283 * the library has not been previously initialized by psa_crypto_init(). 1284 * It is implementation-dependent whether a failure to initialize 1285 * results in this error code. 1286 */ 1287 psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation, 1288 mbedtls_svc_key_id_t password); 1289 1290 /** Set the user ID for a password-authenticated key exchange. 1291 * 1292 * Call this function to set the user ID. For PAKE algorithms that associate a 1293 * user identifier with each side of the session you need to call 1294 * psa_pake_set_peer() as well. For PAKE algorithms that associate a single 1295 * user identifier with the session, call psa_pake_set_user() only. 1296 * 1297 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1298 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1299 * for more information. 1300 * 1301 * \param[in,out] operation The operation object to set the user ID for. It 1302 * must have been set up by psa_pake_setup() and 1303 * not yet in use (neither psa_pake_output() nor 1304 * psa_pake_input() has been called yet). It must 1305 * be on operation for which the user ID hasn't 1306 * been set (psa_pake_set_user() hasn't been 1307 * called yet). 1308 * \param[in] user_id The user ID to authenticate with. 1309 * \param user_id_len Size of the \p user_id buffer in bytes. 1310 * 1311 * \retval #PSA_SUCCESS 1312 * Success. 1313 * \retval #PSA_ERROR_INVALID_ARGUMENT 1314 * \p user_id is not valid for the \p operation's algorithm and cipher 1315 * suite. 1316 * \retval #PSA_ERROR_NOT_SUPPORTED 1317 * The value of \p user_id is not supported by the implementation. 1318 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1319 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1320 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1321 * \retval #PSA_ERROR_BAD_STATE 1322 * The operation state is not valid, or 1323 * the library has not been previously initialized by psa_crypto_init(). 1324 * It is implementation-dependent whether a failure to initialize 1325 * results in this error code. 1326 */ 1327 psa_status_t psa_pake_set_user(psa_pake_operation_t *operation, 1328 const uint8_t *user_id, 1329 size_t user_id_len); 1330 1331 /** Set the peer ID for a password-authenticated key exchange. 1332 * 1333 * Call this function in addition to psa_pake_set_user() for PAKE algorithms 1334 * that associate a user identifier with each side of the session. For PAKE 1335 * algorithms that associate a single user identifier with the session, call 1336 * psa_pake_set_user() only. 1337 * 1338 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1339 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1340 * for more information. 1341 * 1342 * \param[in,out] operation The operation object to set the peer ID for. It 1343 * must have been set up by psa_pake_setup() and 1344 * not yet in use (neither psa_pake_output() nor 1345 * psa_pake_input() has been called yet). It must 1346 * be on operation for which the peer ID hasn't 1347 * been set (psa_pake_set_peer() hasn't been 1348 * called yet). 1349 * \param[in] peer_id The peer's ID to authenticate. 1350 * \param peer_id_len Size of the \p peer_id buffer in bytes. 1351 * 1352 * \retval #PSA_SUCCESS 1353 * Success. 1354 * \retval #PSA_ERROR_INVALID_ARGUMENT 1355 * \p peer_id is not valid for the \p operation's algorithm and cipher 1356 * suite. 1357 * \retval #PSA_ERROR_NOT_SUPPORTED 1358 * The algorithm doesn't associate a second identity with the session. 1359 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1360 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1361 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1362 * \retval #PSA_ERROR_BAD_STATE 1363 * Calling psa_pake_set_peer() is invalid with the \p operation's 1364 * algorithm, the operation state is not valid, or the library has not 1365 * been previously initialized by psa_crypto_init(). 1366 * It is implementation-dependent whether a failure to initialize 1367 * results in this error code. 1368 */ 1369 psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation, 1370 const uint8_t *peer_id, 1371 size_t peer_id_len); 1372 1373 /** Set the application role for a password-authenticated key exchange. 1374 * 1375 * Not all PAKE algorithms need to differentiate the communicating entities. 1376 * It is optional to call this function for PAKEs that don't require a role 1377 * to be specified. For such PAKEs the application role parameter is ignored, 1378 * or #PSA_PAKE_ROLE_NONE can be passed as \c role. 1379 * 1380 * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` 1381 * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) 1382 * for more information. 1383 * 1384 * \param[in,out] operation The operation object to specify the 1385 * application's role for. It must have been set up 1386 * by psa_pake_setup() and not yet in use (neither 1387 * psa_pake_output() nor psa_pake_input() has been 1388 * called yet). It must be on operation for which 1389 * the application's role hasn't been specified 1390 * (psa_pake_set_role() hasn't been called yet). 1391 * \param role A value of type ::psa_pake_role_t indicating the 1392 * application's role in the PAKE the algorithm 1393 * that is being set up. For more information see 1394 * the documentation of \c PSA_PAKE_ROLE_XXX 1395 * constants. 1396 * 1397 * \retval #PSA_SUCCESS 1398 * Success. 1399 * \retval #PSA_ERROR_INVALID_ARGUMENT 1400 * The \p role is not a valid PAKE role in the \p operation’s algorithm. 1401 * \retval #PSA_ERROR_NOT_SUPPORTED 1402 * The \p role for this algorithm is not supported or is not valid. 1403 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1404 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1405 * \retval #PSA_ERROR_BAD_STATE 1406 * The operation state is not valid, or 1407 * the library has not been previously initialized by psa_crypto_init(). 1408 * It is implementation-dependent whether a failure to initialize 1409 * results in this error code. 1410 */ 1411 psa_status_t psa_pake_set_role(psa_pake_operation_t *operation, 1412 psa_pake_role_t role); 1413 1414 /** Get output for a step of a password-authenticated key exchange. 1415 * 1416 * Depending on the algorithm being executed, you might need to call this 1417 * function several times or you might not need to call this at all. 1418 * 1419 * The exact sequence of calls to perform a password-authenticated key 1420 * exchange depends on the algorithm in use. Refer to the documentation of 1421 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type 1422 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more 1423 * information. 1424 * 1425 * If this function returns an error status, the operation enters an error 1426 * state and must be aborted by calling psa_pake_abort(). 1427 * 1428 * \param[in,out] operation Active PAKE operation. 1429 * \param step The step of the algorithm for which the output is 1430 * requested. 1431 * \param[out] output Buffer where the output is to be written in the 1432 * format appropriate for this \p step. Refer to 1433 * the documentation of the individual 1434 * \c PSA_PAKE_STEP_XXX constants for more 1435 * information. 1436 * \param output_size Size of the \p output buffer in bytes. This must 1437 * be at least #PSA_PAKE_OUTPUT_SIZE(\c alg, \c 1438 * primitive, \p output_step) where \c alg and 1439 * \p primitive are the PAKE algorithm and primitive 1440 * in the operation's cipher suite, and \p step is 1441 * the output step. 1442 * 1443 * \param[out] output_length On success, the number of bytes of the returned 1444 * output. 1445 * 1446 * \retval #PSA_SUCCESS 1447 * Success. 1448 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 1449 * The size of the \p output buffer is too small. 1450 * \retval #PSA_ERROR_INVALID_ARGUMENT 1451 * \p step is not compatible with the operation's algorithm. 1452 * \retval #PSA_ERROR_NOT_SUPPORTED 1453 * \p step is not supported with the operation's algorithm. 1454 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 1455 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1456 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1457 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1458 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1459 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 1460 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 1461 * \retval #PSA_ERROR_BAD_STATE 1462 * The operation state is not valid (it must be active, and fully set 1463 * up, and this call must conform to the algorithm's requirements 1464 * for ordering of input and output steps), or 1465 * the library has not been previously initialized by psa_crypto_init(). 1466 * It is implementation-dependent whether a failure to initialize 1467 * results in this error code. 1468 */ 1469 psa_status_t psa_pake_output(psa_pake_operation_t *operation, 1470 psa_pake_step_t step, 1471 uint8_t *output, 1472 size_t output_size, 1473 size_t *output_length); 1474 1475 /** Provide input for a step of a password-authenticated key exchange. 1476 * 1477 * Depending on the algorithm being executed, you might need to call this 1478 * function several times or you might not need to call this at all. 1479 * 1480 * The exact sequence of calls to perform a password-authenticated key 1481 * exchange depends on the algorithm in use. Refer to the documentation of 1482 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type 1483 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more 1484 * information. 1485 * 1486 * If this function returns an error status, the operation enters an error 1487 * state and must be aborted by calling psa_pake_abort(). 1488 * 1489 * \param[in,out] operation Active PAKE operation. 1490 * \param step The step for which the input is provided. 1491 * \param[in] input Buffer containing the input in the format 1492 * appropriate for this \p step. Refer to the 1493 * documentation of the individual 1494 * \c PSA_PAKE_STEP_XXX constants for more 1495 * information. 1496 * \param input_length Size of the \p input buffer in bytes. 1497 * 1498 * \retval #PSA_SUCCESS 1499 * Success. 1500 * \retval #PSA_ERROR_INVALID_SIGNATURE 1501 * The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step. 1502 * \retval #PSA_ERROR_INVALID_ARGUMENT 1503 * \p input_length is not compatible with the \p operation’s algorithm, 1504 * or the \p input is not valid for the \p operation's algorithm, 1505 * cipher suite or \p step. 1506 * \retval #PSA_ERROR_NOT_SUPPORTED 1507 * \p step p is not supported with the \p operation's algorithm, or the 1508 * \p input is not supported for the \p operation's algorithm, cipher 1509 * suite or \p step. 1510 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1511 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1512 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1513 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1514 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 1515 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 1516 * \retval #PSA_ERROR_BAD_STATE 1517 * The operation state is not valid (it must be active, and fully set 1518 * up, and this call must conform to the algorithm's requirements 1519 * for ordering of input and output steps), or 1520 * the library has not been previously initialized by psa_crypto_init(). 1521 * It is implementation-dependent whether a failure to initialize 1522 * results in this error code. 1523 */ 1524 psa_status_t psa_pake_input(psa_pake_operation_t *operation, 1525 psa_pake_step_t step, 1526 const uint8_t *input, 1527 size_t input_length); 1528 1529 /** Get implicitly confirmed shared secret from a PAKE. 1530 * 1531 * At this point there is a cryptographic guarantee that only the authenticated 1532 * party who used the same password is able to compute the key. But there is no 1533 * guarantee that the peer is the party it claims to be and was able to do so. 1534 * 1535 * That is, the authentication is only implicit. Since the peer is not 1536 * authenticated yet, no action should be taken yet that assumes that the peer 1537 * is who it claims to be. For example, do not access restricted files on the 1538 * peer's behalf until an explicit authentication has succeeded. 1539 * 1540 * This function can be called after the key exchange phase of the operation 1541 * has completed. It imports the shared secret output of the PAKE into the 1542 * provided derivation operation. The input step 1543 * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key 1544 * material in the key derivation operation. 1545 * 1546 * The exact sequence of calls to perform a password-authenticated key 1547 * exchange depends on the algorithm in use. Refer to the documentation of 1548 * individual PAKE algorithm types (`PSA_ALG_XXX` values of type 1549 * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more 1550 * information. 1551 * 1552 * When this function returns successfully, \p operation becomes inactive. 1553 * If this function returns an error status, both \p operation 1554 * and \c key_derivation operations enter an error state and must be aborted by 1555 * calling psa_pake_abort() and psa_key_derivation_abort() respectively. 1556 * 1557 * \param[in,out] operation Active PAKE operation. 1558 * \param[out] output A key derivation operation that is ready 1559 * for an input step of type 1560 * #PSA_KEY_DERIVATION_INPUT_SECRET. 1561 * 1562 * \retval #PSA_SUCCESS 1563 * Success. 1564 * \retval #PSA_ERROR_INVALID_ARGUMENT 1565 * #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the 1566 * algorithm in the \p output key derivation operation. 1567 * \retval #PSA_ERROR_NOT_SUPPORTED 1568 * Input from a PAKE is not supported by the algorithm in the \p output 1569 * key derivation operation. 1570 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 1571 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1572 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1573 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 1574 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 1575 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 1576 * \retval #PSA_ERROR_BAD_STATE 1577 * The PAKE operation state is not valid (it must be active, but beyond 1578 * that validity is specific to the algorithm), or 1579 * the library has not been previously initialized by psa_crypto_init(), 1580 * or the state of \p output is not valid for 1581 * the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the 1582 * step is out of order or the application has done this step already 1583 * and it may not be repeated. 1584 * It is implementation-dependent whether a failure to initialize 1585 * results in this error code. 1586 */ 1587 psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation, 1588 psa_key_derivation_operation_t *output); 1589 1590 /** Abort a PAKE operation. 1591 * 1592 * Aborting an operation frees all associated resources except for the \c 1593 * operation structure itself. Once aborted, the operation object can be reused 1594 * for another operation by calling psa_pake_setup() again. 1595 * 1596 * This function may be called at any time after the operation 1597 * object has been initialized as described in #psa_pake_operation_t. 1598 * 1599 * In particular, calling psa_pake_abort() after the operation has been 1600 * terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key() 1601 * is safe and has no effect. 1602 * 1603 * \param[in,out] operation The operation to abort. 1604 * 1605 * \retval #PSA_SUCCESS 1606 * Success. 1607 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1608 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1609 * \retval #PSA_ERROR_BAD_STATE 1610 * The library has not been previously initialized by psa_crypto_init(). 1611 * It is implementation-dependent whether a failure to initialize 1612 * results in this error code. 1613 */ 1614 psa_status_t psa_pake_abort(psa_pake_operation_t *operation); 1615 1616 /**@}*/ 1617 1618 /** A sufficient output buffer size for psa_pake_output(). 1619 * 1620 * If the size of the output buffer is at least this large, it is guaranteed 1621 * that psa_pake_output() will not fail due to an insufficient output buffer 1622 * size. The actual size of the output might be smaller in any given call. 1623 * 1624 * See also #PSA_PAKE_OUTPUT_MAX_SIZE 1625 * 1626 * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that 1627 * #PSA_ALG_IS_PAKE(\p alg) is true). 1628 * \param primitive A primitive of type ::psa_pake_primitive_t that is 1629 * compatible with algorithm \p alg. 1630 * \param output_step A value of type ::psa_pake_step_t that is valid for the 1631 * algorithm \p alg. 1632 * \return A sufficient output buffer size for the specified 1633 * PAKE algorithm, primitive, and output step. If the 1634 * PAKE algorithm, primitive, or output step is not 1635 * recognized, or the parameters are incompatible, 1636 * return 0. 1637 */ 1638 #define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) \ 1639 (alg == PSA_ALG_JPAKE && \ 1640 primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, \ 1641 PSA_ECC_FAMILY_SECP_R1, 256) ? \ 1642 ( \ 1643 output_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \ 1644 output_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \ 1645 32 \ 1646 ) : \ 1647 0) 1648 1649 /** A sufficient input buffer size for psa_pake_input(). 1650 * 1651 * The value returned by this macro is guaranteed to be large enough for any 1652 * valid input to psa_pake_input() in an operation with the specified 1653 * parameters. 1654 * 1655 * See also #PSA_PAKE_INPUT_MAX_SIZE 1656 * 1657 * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that 1658 * #PSA_ALG_IS_PAKE(\p alg) is true). 1659 * \param primitive A primitive of type ::psa_pake_primitive_t that is 1660 * compatible with algorithm \p alg. 1661 * \param input_step A value of type ::psa_pake_step_t that is valid for the 1662 * algorithm \p alg. 1663 * \return A sufficient input buffer size for the specified 1664 * input, cipher suite and algorithm. If the cipher suite, 1665 * the input type or PAKE algorithm is not recognized, or 1666 * the parameters are incompatible, return 0. 1667 */ 1668 #define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ 1669 (alg == PSA_ALG_JPAKE && \ 1670 primitive == PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, \ 1671 PSA_ECC_FAMILY_SECP_R1, 256) ? \ 1672 ( \ 1673 input_step == PSA_PAKE_STEP_KEY_SHARE ? 65 : \ 1674 input_step == PSA_PAKE_STEP_ZK_PUBLIC ? 65 : \ 1675 32 \ 1676 ) : \ 1677 0) 1678 1679 /** Output buffer size for psa_pake_output() for any of the supported PAKE 1680 * algorithm and primitive suites and output step. 1681 * 1682 * This macro must expand to a compile-time constant integer. 1683 * 1684 * The value of this macro must be at least as large as the largest value 1685 * returned by PSA_PAKE_OUTPUT_SIZE() 1686 * 1687 * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p output_step). 1688 */ 1689 #define PSA_PAKE_OUTPUT_MAX_SIZE 65 1690 1691 /** Input buffer size for psa_pake_input() for any of the supported PAKE 1692 * algorithm and primitive suites and input step. 1693 * 1694 * This macro must expand to a compile-time constant integer. 1695 * 1696 * The value of this macro must be at least as large as the largest value 1697 * returned by PSA_PAKE_INPUT_SIZE() 1698 * 1699 * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p output_step). 1700 */ 1701 #define PSA_PAKE_INPUT_MAX_SIZE 65 1702 1703 /** Returns a suitable initializer for a PAKE cipher suite object of type 1704 * psa_pake_cipher_suite_t. 1705 */ 1706 #define PSA_PAKE_CIPHER_SUITE_INIT { PSA_ALG_NONE, 0, 0, 0, PSA_ALG_NONE } 1707 1708 /** Returns a suitable initializer for a PAKE operation object of type 1709 * psa_pake_operation_t. 1710 */ 1711 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 1712 #define PSA_PAKE_OPERATION_INIT { 0 } 1713 #else 1714 #define PSA_PAKE_OPERATION_INIT { 0, PSA_ALG_NONE, 0, PSA_PAKE_OPERATION_STAGE_SETUP, \ 1715 { 0 }, { { 0 } } } 1716 #endif 1717 1718 struct psa_pake_cipher_suite_s { 1719 psa_algorithm_t algorithm; 1720 psa_pake_primitive_type_t type; 1721 psa_pake_family_t family; 1722 uint16_t bits; 1723 psa_algorithm_t hash; 1724 }; 1725 1726 static inline psa_algorithm_t psa_pake_cs_get_algorithm( 1727 const psa_pake_cipher_suite_t *cipher_suite) 1728 { 1729 return cipher_suite->algorithm; 1730 } 1731 1732 static inline void psa_pake_cs_set_algorithm( 1733 psa_pake_cipher_suite_t *cipher_suite, 1734 psa_algorithm_t algorithm) 1735 { 1736 if (!PSA_ALG_IS_PAKE(algorithm)) { 1737 cipher_suite->algorithm = 0; 1738 } else { 1739 cipher_suite->algorithm = algorithm; 1740 } 1741 } 1742 1743 static inline psa_pake_primitive_t psa_pake_cs_get_primitive( 1744 const psa_pake_cipher_suite_t *cipher_suite) 1745 { 1746 return PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family, 1747 cipher_suite->bits); 1748 } 1749 1750 static inline void psa_pake_cs_set_primitive( 1751 psa_pake_cipher_suite_t *cipher_suite, 1752 psa_pake_primitive_t primitive) 1753 { 1754 cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24); 1755 cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16)); 1756 cipher_suite->bits = (uint16_t) (0xFFFF & primitive); 1757 } 1758 1759 static inline psa_pake_family_t psa_pake_cs_get_family( 1760 const psa_pake_cipher_suite_t *cipher_suite) 1761 { 1762 return cipher_suite->family; 1763 } 1764 1765 static inline uint16_t psa_pake_cs_get_bits( 1766 const psa_pake_cipher_suite_t *cipher_suite) 1767 { 1768 return cipher_suite->bits; 1769 } 1770 1771 static inline psa_algorithm_t psa_pake_cs_get_hash( 1772 const psa_pake_cipher_suite_t *cipher_suite) 1773 { 1774 return cipher_suite->hash; 1775 } 1776 1777 static inline void psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite, 1778 psa_algorithm_t hash) 1779 { 1780 if (!PSA_ALG_IS_HASH(hash)) { 1781 cipher_suite->hash = 0; 1782 } else { 1783 cipher_suite->hash = hash; 1784 } 1785 } 1786 1787 struct psa_crypto_driver_pake_inputs_s { 1788 uint8_t *MBEDTLS_PRIVATE(password); 1789 size_t MBEDTLS_PRIVATE(password_len); 1790 uint8_t *MBEDTLS_PRIVATE(user); 1791 size_t MBEDTLS_PRIVATE(user_len); 1792 uint8_t *MBEDTLS_PRIVATE(peer); 1793 size_t MBEDTLS_PRIVATE(peer_len); 1794 psa_key_attributes_t MBEDTLS_PRIVATE(attributes); 1795 psa_pake_cipher_suite_t MBEDTLS_PRIVATE(cipher_suite); 1796 }; 1797 1798 typedef enum psa_crypto_driver_pake_step { 1799 PSA_JPAKE_STEP_INVALID = 0, /* Invalid step */ 1800 PSA_JPAKE_X1_STEP_KEY_SHARE = 1, /* Round 1: input/output key share (for ephemeral private key X1).*/ 1801 PSA_JPAKE_X1_STEP_ZK_PUBLIC = 2, /* Round 1: input/output Schnorr NIZKP public key for the X1 key */ 1802 PSA_JPAKE_X1_STEP_ZK_PROOF = 3, /* Round 1: input/output Schnorr NIZKP proof for the X1 key */ 1803 PSA_JPAKE_X2_STEP_KEY_SHARE = 4, /* Round 1: input/output key share (for ephemeral private key X2).*/ 1804 PSA_JPAKE_X2_STEP_ZK_PUBLIC = 5, /* Round 1: input/output Schnorr NIZKP public key for the X2 key */ 1805 PSA_JPAKE_X2_STEP_ZK_PROOF = 6, /* Round 1: input/output Schnorr NIZKP proof for the X2 key */ 1806 PSA_JPAKE_X2S_STEP_KEY_SHARE = 7, /* Round 2: output X2S key (our key) */ 1807 PSA_JPAKE_X2S_STEP_ZK_PUBLIC = 8, /* Round 2: output Schnorr NIZKP public key for the X2S key (our key) */ 1808 PSA_JPAKE_X2S_STEP_ZK_PROOF = 9, /* Round 2: output Schnorr NIZKP proof for the X2S key (our key) */ 1809 PSA_JPAKE_X4S_STEP_KEY_SHARE = 10, /* Round 2: input X4S key (from peer) */ 1810 PSA_JPAKE_X4S_STEP_ZK_PUBLIC = 11, /* Round 2: input Schnorr NIZKP public key for the X4S key (from peer) */ 1811 PSA_JPAKE_X4S_STEP_ZK_PROOF = 12 /* Round 2: input Schnorr NIZKP proof for the X4S key (from peer) */ 1812 } psa_crypto_driver_pake_step_t; 1813 1814 typedef enum psa_jpake_round { 1815 PSA_JPAKE_FIRST = 0, 1816 PSA_JPAKE_SECOND = 1, 1817 PSA_JPAKE_FINISHED = 2 1818 } psa_jpake_round_t; 1819 1820 typedef enum psa_jpake_io_mode { 1821 PSA_JPAKE_INPUT = 0, 1822 PSA_JPAKE_OUTPUT = 1 1823 } psa_jpake_io_mode_t; 1824 1825 struct psa_jpake_computation_stage_s { 1826 /* The J-PAKE round we are currently on */ 1827 psa_jpake_round_t MBEDTLS_PRIVATE(round); 1828 /* The 'mode' we are currently in (inputting or outputting) */ 1829 psa_jpake_io_mode_t MBEDTLS_PRIVATE(io_mode); 1830 /* The number of completed inputs so far this round */ 1831 uint8_t MBEDTLS_PRIVATE(inputs); 1832 /* The number of completed outputs so far this round */ 1833 uint8_t MBEDTLS_PRIVATE(outputs); 1834 /* The next expected step (KEY_SHARE, ZK_PUBLIC or ZK_PROOF) */ 1835 psa_pake_step_t MBEDTLS_PRIVATE(step); 1836 }; 1837 1838 #define PSA_JPAKE_EXPECTED_INPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \ 1839 ((round) == PSA_JPAKE_FIRST ? 2 : 1)) 1840 #define PSA_JPAKE_EXPECTED_OUTPUTS(round) ((round) == PSA_JPAKE_FINISHED ? 0 : \ 1841 ((round) == PSA_JPAKE_FIRST ? 2 : 1)) 1842 1843 struct psa_pake_operation_s { 1844 #if defined(MBEDTLS_PSA_CRYPTO_CLIENT) && !defined(MBEDTLS_PSA_CRYPTO_C) 1845 mbedtls_psa_client_handle_t handle; 1846 #else 1847 /** Unique ID indicating which driver got assigned to do the 1848 * operation. Since driver contexts are driver-specific, swapping 1849 * drivers halfway through the operation is not supported. 1850 * ID values are auto-generated in psa_crypto_driver_wrappers.h 1851 * ID value zero means the context is not valid or not assigned to 1852 * any driver (i.e. none of the driver contexts are active). */ 1853 unsigned int MBEDTLS_PRIVATE(id); 1854 /* Algorithm of the PAKE operation */ 1855 psa_algorithm_t MBEDTLS_PRIVATE(alg); 1856 /* A primitive of type compatible with algorithm */ 1857 psa_pake_primitive_t MBEDTLS_PRIVATE(primitive); 1858 /* Stage of the PAKE operation: waiting for the setup, collecting inputs 1859 * or computing. */ 1860 uint8_t MBEDTLS_PRIVATE(stage); 1861 /* Holds computation stage of the PAKE algorithms. */ 1862 union { 1863 uint8_t MBEDTLS_PRIVATE(dummy); 1864 #if defined(PSA_WANT_ALG_JPAKE) 1865 psa_jpake_computation_stage_t MBEDTLS_PRIVATE(jpake); 1866 #endif 1867 } MBEDTLS_PRIVATE(computation_stage); 1868 union { 1869 psa_driver_pake_context_t MBEDTLS_PRIVATE(ctx); 1870 psa_crypto_driver_pake_inputs_t MBEDTLS_PRIVATE(inputs); 1871 } MBEDTLS_PRIVATE(data); 1872 #endif 1873 }; 1874 1875 static inline struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init(void) 1876 { 1877 const struct psa_pake_cipher_suite_s v = PSA_PAKE_CIPHER_SUITE_INIT; 1878 return v; 1879 } 1880 1881 static inline struct psa_pake_operation_s psa_pake_operation_init(void) 1882 { 1883 const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT; 1884 return v; 1885 } 1886 1887 #ifdef __cplusplus 1888 } 1889 #endif 1890 1891 #endif /* PSA_CRYPTO_EXTRA_H */ 1892