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