include/psa/crypto_values.h

46  * value, check with the Arm PSA framework group to pick one that other
94  * in cases when performing the operation with a larger output
240  * an algorithm with a randomized result, as well as functions that
332  *  still has work to do, thus the user should call the function again with the
362  * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should
439  * This size can be calculated with #PSA_HASH_LENGTH(\c alg) where
460  * their size. It can be used for randomly generated or derived keys with
462  * for such keys. It is not suitable for passwords with extremely low entropy,
528  *       with the initial counter value 1, you can process and discard a
552  * The size of an elliptic curve key is the bit size associated with the curve,
674  *   The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve.
677  *   The algorithm #PSA_ALG_ECDH performs X448 when used with this curve.
738  * This family includes groups with the following key sizes (in bits):
777  * bit set. Vendors who define additional algorithms must use an encoding with
834  * with associated data (AEAD) algorithm.
895  * that is suitable for use with a low-entropy secret such as a password.
954  * algorithm parametrized with any supported hash.
1029  * is a wildcard algorithm. A key with such wildcard algorithm as permitted
1030  * algorithm policy can be used with any algorithm corresponding to the
1062  * \return              The corresponding MAC algorithm with the specified
1121  * \return                The corresponding MAC wildcard algorithm with the
1159  * by applying a bitwise-xor with a stream of bytes that is generated
1183  * For example, to use AES-128-CTR, use this algorithm with
1208 /** The Electronic Code Book (ECB) mode of a block cipher, with no padding.
1219  * This symmetric cipher mode can only be used with messages whose lengths are a
1223  * multi-part cipher operation with this algorithm, psa_cipher_generate_iv()
1228 /** The CBC block cipher chaining mode, with no padding.
1232  * This symmetric cipher mode can only be used with messages whose lengths
1237 /** The CBC block cipher chaining mode with PKCS#7 padding.
1268  * This is CCM* as specified in IEEE 802.15.4 §7, with a tag length of 0.
1269  * For CCM* with a nonzero tag length, use the AEAD algorithm #PSA_ALG_CCM.
1303  * is a wildcard algorithm. A key with such wildcard algorithm as permitted
1304  * algorithm policy can be used with any algorithm corresponding to the
1321  * \return              The corresponding AEAD algorithm with the specified
1347 /** Calculate the corresponding AEAD algorithm with the default tag length.
1352  * \return              The corresponding AEAD algorithm with the default
1384  * \return                The corresponding AEAD wildcard algorithm with the
1395 /** RSA PKCS#1 v1.5 signature with hashing.
1424 /** RSA PSS signature with hashing.
1428  * RSASSA-PSS, with the message generation function MGF1, and with
1447 /** RSA PSS signature with hashing with relaxed verification.
1465 /** Whether the specified algorithm is RSA PSS with standard salt.
1479 /** Whether the specified algorithm is RSA PSS with any salt.
1513 /** ECDSA signature with hashing.
1516  * with a random per-message secret number (*k*).
1540  * already-calculated hash. Note that the input is padded with
1546 /** Deterministic ECDSA signature with hashing.
1550  * The representation of a signature is the same as with #PSA_ALG_ECDSA().
1553  * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the
1601  * This algorithm can be used with psa_sign_message() and
1603  * with psa_sign_hash() or psa_verify_hash().
1615 /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
1629  *   with psa_hash_compute()
1630  *   or with a multi-part hash operation started with psa_hash_setup(),
1632  *   then sign the calculated hash with psa_sign_hash().
1639 /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
1654  *   with psa_hash_compute()
1655  *   or with a multi-part hash operation started with psa_hash_setup(),
1657  *   then sign the calculated hash with psa_sign_hash().
1664 /* Default definition, to be overridden if the library is extended with
1670  * with psa_sign_hash() and psa_verify_hash().
1692  * with psa_sign_message() and psa_verify_message().
1721  * to be calculated in multiple steps with psa_hash_setup(), psa_hash_update()
1760  * \warning     Calling psa_asymmetric_decrypt() with this algorithm as a
1774  * RSAES-OAEP, with the message generation function MGF1.
1807  *  \warning  HKDF processes the salt as follows: first hash it with hash_alg
1809  *  pad with null bytes up to the block size. As a result, it is possible
1855  *  in applications that use HKDF with the same salt and key but many
1858  *  \warning  HKDF processes the salt as follows: first hash it with hash_alg
1860  *  pad with null bytes up to the block size. As a result, it is possible
1904  *  that use HKDF with the same salt and key but many different info strings.
1949  * used with either SHA-256 or SHA-384.
1993  * The latter is based on HMAC and can be used with either SHA-256
2001  *   if omitted, it defaults to a string of null bytes with the same length
2015  *   PSA_ALG_FFDH or PSA_ALG_ECDH key agreement performed with the peer.
2020  *   this input may be an output of `psa_raw_key_agreement()` passed with
2021  *   psa_key_derivation_input_bytes(), or an equivalent input passed with
2029  *   with `psa_key_derivation_input_bytes()`.
2076  * Those algorithms cannot be combined with a key agreement algorithm.
2085  * HMAC with the specified hash.
2129  * #PSA_ALG_PBKDF2_HMAC() with the same constraints.
2140 /** Macro to build a combined algorithm that chains a key agreement with
2167  * Usually, raw key agreement algorithms are constructed directly with
2169  * constructed with #PSA_ALG_KEY_AGREEMENT().
2212  * `m` is the bit size associated with the curve, i.e. the bit size of the
2215  * is padded with zero bits. The byte order is either little-endian
2302  * A key with this lifetime is typically stored in the RAM area of the
2305  * it must release all the resources associated with the key and erase the
2374  * consider a platform with multiple levels of privilege, where a
2376  * it, and the platform exposes the key to the application with a read-only
2551  * with the same policy or a more restrictive policy.
2556  * Copying the key inside the secure element is permitted with just
2558  * For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or
2775 /** Maximum value for use with \c psa_interruptible_set_max_ops() to determine