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