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