Lines Matching +full:- +full:- +full:algorithm
24 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
50 * it might change the spacing to something that is not PSA-compliant
53 * *INDENT-OFF*
64 #define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132)
70 * parameter such as a key type, algorithm, etc. is not recognized.
73 #define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134)
86 #define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133)
98 #define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138)
104 #define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139)
110 #define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140)
126 #define PSA_ERROR_BAD_STATE ((psa_status_t)-137)
137 #define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135)
143 #define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141)
152 #define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142)
169 #define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
194 #define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146)
200 #define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147)
231 #define PSA_ERROR_CORRUPTION_DETECTED ((psa_status_t)-151)
240 * an algorithm with a randomized result, as well as functions that
250 #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148)
260 #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149)
276 #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150)
280 #define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143)
282 /** The key identifier is not valid. See also :ref:\`key-handles\`.
284 #define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136)
292 * - A corruption of volatile memory - use #PSA_ERROR_CORRUPTION_DETECTED.
293 * - A communication error between the cryptoprocessor and its external
294 * storage - use #PSA_ERROR_COMMUNICATION_FAILURE.
295 * - When the storage is in a valid state but is full - use
297 * - When the storage fails for other reasons - use
299 * - When the stored data is not valid - use #PSA_ERROR_DATA_INVALID.
308 #define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152)
316 * - When the storage or stored data is corrupted - use #PSA_ERROR_DATA_CORRUPT
317 * - When the storage fails for other reasons - use #PSA_ERROR_STORAGE_FAILURE
318 * - An invalid argument to the API - use #PSA_ERROR_INVALID_ARGUMENT
324 #define PSA_ERROR_DATA_INVALID ((psa_status_t)-153)
331 #define PSA_OPERATION_INCOMPLETE ((psa_status_t)-248)
333 /* *INDENT-ON* */
337 /** \defgroup crypto_types Key and algorithm types
353 /** Vendor-defined key type flag.
370 /** Whether a key type is vendor-defined.
379 * This encompasses both symmetric keys and non-key data.
430 * The key policy determines which underlying hash algorithm the key can be
435 * \c alg is the HMAC algorithm or the underlying hash algorithm. */
440 * This key type is for high-entropy secrets only. For low-entropy secrets,
446 * The key policy determines which key derivation algorithm the key
451 /** A low-entropy secret for password hashing or key derivation.
456 * maximum or near-maximum entropy, but #PSA_KEY_TYPE_DERIVE is more suitable
462 * designed to accept low-entropy secret and are known as password hashing or
467 * it to be high-entropy.
469 * The key policy determines which key derivation algorithm the key can be
476 * The key policy determines which key derivation algorithm the key
484 * The key policy determines which key derivation algorithm the key
489 /** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.
491 * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or
492 * 32 bytes (AES-256).
496 /** Key for a cipher, AEAD or MAC algorithm based on the
500 /** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
502 * The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or
503 * 192 bits (3-key 3DES).
505 * Note that single DES and 2-key 3DES are weak and strongly
506 * deprecated and should only be used to decrypt legacy data. 3-key 3DES
511 /** Key for a cipher, AEAD or MAC algorithm based on the
515 /** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
520 * 12-byte nonces.
524 * 64-byte block before the real data.
538 /** Whether a key type is an RSA key (pair or public-only). */
568 /** Whether a key type is an elliptic curve key (pair or public-only). */
596 * https://www.secg.org/sec2-v2.pdf
606 * https://www.secg.org/sec2-v2.pdf
618 * https://www.secg.org/sec2-v2.pdf
628 * https://www.secg.org/sec2-v2.pdf
638 * https://www.secg.org/sec2-v2.pdf
654 * - 255-bit: Bernstein et al.,
655 * _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006.
656 * The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve.
657 * - 448-bit: Hamburg,
658 * _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015.
659 * The algorithm #PSA_ALG_ECDH performs X448 when used with this curve.
666 * #PSA_ALG_ED25519PH for the 255-bit curve,
667 * #PSA_ALG_ED448PH for the 448-bit curve).
670 * - 255-bit: Edwards25519, the twisted Edwards curve birationally equivalent
673 * - 448-bit: Edwards448, the twisted Edwards curve birationally equivalent
675 * Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015.
682 /** Diffie-Hellman key pair.
685 * Diffie-Hellman group to be used.
689 /** Diffie-Hellman public key.
692 * Diffie-Hellman group to be used.
697 /** Whether a key type is a Diffie-Hellman key (pair or public-only). */
701 /** Whether a key type is a Diffie-Hellman key pair. */
705 /** Whether a key type is a Diffie-Hellman public key. */
710 /** Extract the group from a Diffie-Hellman key type. */
716 /** Diffie-Hellman groups defined in RFC 7919 Appendix A.
740 * \note This macro returns a compile-time constant if its argument is one.
749 /* Note that algorithm values are embedded in the persistent key store,
754 /** Vendor-defined algorithm flag.
773 /** Whether an algorithm is vendor-defined.
780 /** Whether the specified algorithm is a hash algorithm.
782 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
784 * \return 1 if \p alg is a hash algorithm, 0 otherwise.
786 * algorithm identifier.
791 /** Whether the specified algorithm is a MAC algorithm.
793 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
795 * \return 1 if \p alg is a MAC algorithm, 0 otherwise.
797 * algorithm identifier.
802 /** Whether the specified algorithm is a symmetric cipher algorithm.
804 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
806 * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise.
808 * algorithm identifier.
813 /** Whether the specified algorithm is an authenticated encryption
814 * with associated data (AEAD) algorithm.
816 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
818 * \return 1 if \p alg is an AEAD algorithm, 0 otherwise.
820 * algorithm identifier.
825 /** Whether the specified algorithm is an asymmetric signature algorithm,
826 * also known as public-key signature algorithm.
828 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
830 * \return 1 if \p alg is an asymmetric signature algorithm, 0 otherwise.
832 * algorithm identifier.
837 /** Whether the specified algorithm is an asymmetric encryption algorithm,
838 * also known as public-key encryption algorithm.
840 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
842 * \return 1 if \p alg is an asymmetric encryption algorithm, 0 otherwise.
844 * algorithm identifier.
849 /** Whether the specified algorithm is a key agreement algorithm.
851 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
853 * \return 1 if \p alg is a key agreement algorithm, 0 otherwise.
855 * algorithm identifier.
860 /** Whether the specified algorithm is a key derivation algorithm.
862 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
864 * \return 1 if \p alg is a key derivation algorithm, 0 otherwise.
866 * algorithm identifier.
871 /** Whether the specified algorithm is a key stretching / password hashing
872 * algorithm.
874 * A key stretching / password hashing algorithm is a key derivation algorithm
875 * that is suitable for use with a low-entropy secret such as a password.
876 * Equivalently, it's a key derivation algorithm that uses a
879 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
881 * \return 1 if \p alg is a key stretching / password hashing algorithm, 0
883 * supported algorithm identifier.
889 /** An invalid algorithm identifier value. */
890 /* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */
892 /* *INDENT-ON* */
901 /** SHA2-224 */
903 /** SHA2-256 */
905 /** SHA2-384 */
907 /** SHA2-512 */
909 /** SHA2-512/224 */
911 /** SHA2-512/256 */
913 /** SHA3-224 */
915 /** SHA3-256 */
917 /** SHA3-384 */
919 /** SHA3-512 */
924 * scenarios where a hash function based on SHA3/SHAKE is desired, SHA3-512
929 /** In a hash-and-sign algorithm policy, allow any hash algorithm.
931 * This value may be used to form the algorithm usage field of a policy
932 * for a signature algorithm that is parametrized by a hash. The key
934 * algorithm parametrized with any supported hash.
937 * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, #PSA_ALG_RSA_PSS_ANY_SALT,
938 * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA.
940 * - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
945 * - Import or generate key material.
946 * - Call psa_sign_hash() or psa_verify_hash(), passing
947 * an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each
957 * an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true.
959 * This value may not be used to build an algorithm specification to
966 /** Macro to build an HMAC algorithm.
968 * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256.
970 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
973 * \return The corresponding HMAC algorithm.
975 * hash algorithm.
983 /** Whether the specified algorithm is an HMAC algorithm.
987 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
989 * \return 1 if \p alg is an HMAC algorithm, 0 otherwise.
991 * algorithm identifier.
997 /* In the encoding of a MAC algorithm, the bits corresponding to
999 * truncated. As an exception, the value 0 means the untruncated algorithm,
1002 * to full length is correctly encoded as 0 and any non-trivial truncation
1007 /* In the encoding of a MAC algorithm, the bit corresponding to
1008 * #PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm
1009 * is a wildcard algorithm. A key with such wildcard algorithm as permitted
1010 * algorithm policy can be used with any algorithm corresponding to the
1015 /** Macro to build a truncated MAC algorithm.
1017 * A truncated MAC algorithm is identical to the corresponding MAC
1018 * algorithm except that the MAC value for the truncated algorithm
1020 * for the untruncated algorithm.
1022 * \note This macro may allow constructing algorithm identifiers that
1027 * \note It is implementation-defined whether a truncated MAC that
1029 * algorithm is considered identical to the untruncated algorithm
1032 * \param mac_alg A MAC algorithm identifier (value of type
1035 * MAC algorithm.
1038 * and must be at least an implementation-specified
1039 * minimum. The implementation-specified minimum
1042 * \return The corresponding MAC algorithm with the specified
1045 * MAC algorithm or if \p mac_length is too small or
1046 * too large for the specified MAC algorithm.
1053 /** Macro to build the base MAC algorithm corresponding to a truncated
1054 * MAC algorithm.
1056 * \param mac_alg A MAC algorithm identifier (value of type
1059 * MAC algorithm.
1061 * \return The corresponding base MAC algorithm.
1063 * MAC algorithm.
1069 /** Length to which a MAC algorithm is truncated.
1071 * \param mac_alg A MAC algorithm identifier (value of type
1076 * \return 0 if \p mac_alg is a non-truncated MAC algorithm.
1078 * MAC algorithm.
1083 /** Macro to build a MAC minimum-MAC-length wildcard algorithm.
1085 * A minimum-MAC-length MAC wildcard algorithm permits all MAC algorithms
1086 * sharing the same base algorithm, and where the (potentially truncated) MAC
1087 * length of the specific algorithm is equal to or larger then the wildcard
1088 * algorithm's minimum MAC length.
1091 * smallest MAC length allowed by the base algorithm, this effectively
1092 * becomes an 'any-MAC-length-allowed' policy for that base algorithm.
1094 * \param mac_alg A MAC algorithm identifier (value of type
1101 * \return The corresponding MAC wildcard algorithm with the
1104 * algorithm or if \p min_mac_length is less than 1 or
1105 * too large for the specified MAC algorithm.
1112 /** The CBC-MAC construction over a block cipher
1114 * \warning CBC-MAC is insecure in many cases.
1121 /** Whether the specified algorithm is a MAC algorithm based on a block cipher.
1123 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1125 * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise.
1127 * algorithm identifier.
1136 /** Whether the specified algorithm is a stream cipher.
1139 * by applying a bitwise-xor with a stream of bytes that is generated
1142 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1144 * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise.
1146 * algorithm identifier or if it is not a symmetric cipher algorithm.
1152 /** The stream cipher mode of a stream cipher algorithm.
1155 * - To use ChaCha20, use a key type of #PSA_KEY_TYPE_CHACHA20.
1163 * For example, to use AES-128-CTR, use this algorithm with
1203 * multi-part cipher operation with this algorithm, psa_cipher_generate_iv()
1227 /** Whether the specified algorithm is an AEAD mode on a block cipher.
1229 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1231 * \return 1 if \p alg is an AEAD algorithm which is an AEAD mode based on
1234 * algorithm identifier.
1240 /** The CCM authenticated encryption algorithm.
1249 * For CCM* with a nonzero tag length, use the AEAD algorithm #PSA_ALG_CCM.
1253 * Currently only 13-byte long IV's are supported.
1257 /** The GCM authenticated encryption algorithm.
1263 /** The Chacha20-Poly1305 AEAD algorithm.
1267 * Implementations must support 12-byte nonces, may support 8-byte nonces,
1270 * Implementations must support 16-byte tags and should reject other sizes.
1274 /* In the encoding of an AEAD algorithm, the bits corresponding to
1281 /* In the encoding of an AEAD algorithm, the bit corresponding to
1282 * #PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm
1283 * is a wildcard algorithm. A key with such wildcard algorithm as permitted
1284 * algorithm policy can be used with any algorithm corresponding to the
1289 /** Macro to build a shortened AEAD algorithm.
1291 * A shortened AEAD algorithm is similar to the corresponding AEAD
1292 * algorithm, but has an authentication tag that consists of fewer bytes.
1293 * Depending on the algorithm, the tag length may affect the calculation
1296 * \param aead_alg An AEAD algorithm identifier (value of type
1301 * \return The corresponding AEAD algorithm with the specified
1304 * AEAD algorithm or if \p tag_length is not valid
1305 * for the specified AEAD algorithm.
1313 /** Retrieve the tag length of a specified AEAD algorithm
1315 * \param aead_alg An AEAD algorithm identifier (value of type
1319 * \return The tag length specified by the input algorithm.
1321 * AEAD algorithm.
1327 /** Calculate the corresponding AEAD algorithm with the default tag length.
1329 * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
1332 * \return The corresponding AEAD algorithm with the default
1333 * tag length for that algorithm.
1346 /** Macro to build an AEAD minimum-tag-length wildcard algorithm.
1348 * A minimum-tag-length AEAD wildcard algorithm permits all AEAD algorithms
1349 * sharing the same base algorithm, and where the tag length of the specific
1350 * algorithm is equal to or larger then the minimum tag length specified by the
1351 * wildcard algorithm.
1354 * smallest tag length allowed by the base algorithm, this effectively
1355 * becomes an 'any-tag-length-allowed' policy for that base algorithm.
1357 * \param aead_alg An AEAD algorithm identifier (value of type
1362 * allowed tag length of the algorithm.
1364 * \return The corresponding AEAD wildcard algorithm with the
1367 * AEAD algorithm or if \p min_tag_length is less than 1
1368 * or too large for the specified AEAD algorithm.
1379 * RSASSA-PKCS1-v1_5.
1381 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1384 * when specifying the algorithm in a usage policy.
1386 * \return The corresponding RSA PKCS#1 v1.5 signature algorithm.
1388 * hash algorithm.
1394 * The input to this algorithm is the DigestInfo structure used by
1408 * RSASSA-PSS, with the message generation function MGF1, and with
1410 * possible salt length for the algorithm and key size if that is
1411 * smaller than the hash length. The specified hash algorithm is
1415 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1418 * when specifying the algorithm in a usage policy.
1420 * \return The corresponding RSA PSS signature algorithm.
1422 * hash algorithm.
1429 * This algorithm has the same behavior as #PSA_ALG_RSA_PSS when signing,
1433 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1436 * when specifying the algorithm in a usage policy.
1438 * \return The corresponding RSA PSS signature algorithm.
1440 * hash algorithm.
1445 /** Whether the specified algorithm is RSA PSS with standard salt.
1447 * \param alg An algorithm value or an algorithm policy wildcard.
1451 * where \c hash_alg is a hash algorithm or
1454 * a supported algorithm identifier or policy.
1459 /** Whether the specified algorithm is RSA PSS with any salt.
1461 * \param alg An algorithm value or an algorithm policy wildcard.
1465 * where \c hash_alg is a hash algorithm or
1468 * a supported algorithm identifier or policy.
1473 /** Whether the specified algorithm is RSA PSS.
1475 * This includes any of the RSA PSS algorithm variants, regardless of the
1478 * \param alg An algorithm value or an algorithm policy wildcard.
1483 * where \c hash_alg is a hash algorithm or
1486 * a supported algorithm identifier or policy.
1496 * with a random per-message secret number (*k*).
1500 * *r* and *s* is encoded as an *N*-octet string, where *N* is the length
1502 * in big-endian order (most significant octet first).
1504 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1507 * when specifying the algorithm in a usage policy.
1509 * \return The corresponding ECDSA signature algorithm.
1511 * hash algorithm.
1518 * without specifying a hash algorithm. This algorithm may only be
1520 * already-calculated hash. Note that the input is padded with
1532 * Note that when this algorithm is used for verification, signatures
1538 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1541 * when specifying the algorithm in a usage policy.
1544 * algorithm.
1546 * hash algorithm.
1561 /** Edwards-curve digital signature algorithm without prehashing (PureEdDSA),
1567 * suitable functions and extend this algorithm to support contexts.
1571 * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified
1574 * The hash function used internally is SHA-512.
1575 * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 448-bit: Ed448 as specified
1581 * This algorithm can be used with psa_sign_message() and
1586 * RFC 8032 §5.1.6 and §5.2.6 (a 64-byte string for Ed25519, a 114-byte
1595 /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
1596 * using SHA-512 and the Edwards25519 curve.
1600 * This algorithm is Ed25519 as specified in RFC 8032.
1602 * The prehash is SHA-512.
1603 * The hash function used internally is SHA-512.
1605 * This is a hash-and-sign algorithm: to calculate a signature,
1607 * - call psa_sign_message() on the message;
1608 * - or calculate the SHA-512 hash of the message
1610 * or with a multi-part hash operation started with psa_hash_setup(),
1611 * using the hash algorithm #PSA_ALG_SHA_512,
1619 /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
1624 * This algorithm is Ed448 as specified in RFC 8032.
1630 * This is a hash-and-sign algorithm: to calculate a signature,
1632 * - call psa_sign_message() on the message;
1633 * - or calculate the first 64 bytes of the SHAKE256 output of the message
1635 * or with a multi-part hash operation started with psa_hash_setup(),
1636 * using the hash algorithm #PSA_ALG_SHAKE256_512,
1645 * more hash-and-sign algorithms that we want to keep out of this header
1649 /** Whether the specified algorithm is a signature algorithm that can be used
1652 * This encompasses all strict hash-and-sign algorithms categorized by
1655 * - #PSA_ALG_RSA_PKCS1V15_SIGN_RAW (expects its input to be an encoded hash)
1656 * - #PSA_ALG_ECDSA_ANY (doesn't specify what kind of hash the input is)
1658 * \param alg An algorithm identifier (value of type psa_algorithm_t).
1660 * \return 1 if alg is a signature algorithm that can be used to sign a
1661 * hash. 0 if alg is a signature algorithm that can only be used
1662 * to sign a message. 0 if alg is not a signature algorithm.
1664 * supported algorithm identifier.
1671 /** Whether the specified algorithm is a signature algorithm that can be used
1674 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1676 * \return 1 if alg is a signature algorithm that can be used to sign a
1677 * message. 0 if \p alg is a signature algorithm that can only be used
1678 * to sign an already-calculated hash. 0 if \p alg is not a signature
1679 * algorithm. This macro can return either 0 or 1 if \p alg is not a
1680 * supported algorithm identifier.
1685 /** Whether the specified algorithm is a hash-and-sign algorithm.
1687 * Hash-and-sign algorithms are asymmetric (public-key) signature algorithms
1690 * hash value and the key. Hash-and-sign algorithms encode the hash
1692 * to extract this algorithm.
1694 * Thus, for a hash-and-sign algorithm,
1705 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1707 * \return 1 if \p alg is a hash-and-sign algorithm, 0 otherwise.
1709 * algorithm identifier.
1715 /** Get the hash used by a hash-and-sign signature algorithm.
1717 * A hash-and-sign algorithm is a signature algorithm which is
1723 * \param alg A signature algorithm (\c PSA_ALG_XXX value such that
1726 * \return The underlying hash algorithm if \p alg is a hash-and-sign
1727 * algorithm.
1728 * \return 0 if \p alg is a signature algorithm that does not
1729 * follow the hash-and-sign structure.
1730 * \return Unspecified if \p alg is not a signature algorithm or
1740 * \warning Calling psa_asymmetric_decrypt() with this algorithm as a
1742 * (CWE-242). Unless it is used in a side channel free and safe
1754 * RSAES-OAEP, with the message generation function MGF1.
1756 * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that
1760 * \return The corresponding RSA OAEP encryption algorithm.
1762 * hash algorithm.
1774 /** Macro to build an HKDF algorithm.
1776 * For example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)` is HKDF using HMAC-SHA-256.
1778 * This key derivation algorithm uses the following inputs:
1779 * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step.
1781 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step.
1782 * - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step.
1788 * if the salt is longer than the block size of the hash algorithm; then
1793 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1796 * \return The corresponding HKDF algorithm.
1798 * hash algorithm.
1802 /** Whether the specified algorithm is an HKDF algorithm.
1807 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1809 * \return 1 if \c alg is an HKDF algorithm, 0 otherwise.
1811 * key derivation algorithm identifier.
1819 /** Macro to build an HKDF-Extract algorithm.
1822 * HKDF-Extract using HMAC-SHA-256.
1824 * This key derivation algorithm uses the following inputs:
1825 * - PSA_KEY_DERIVATION_INPUT_SALT is the salt.
1826 * - PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the
1831 * \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF
1833 * as a separate algorithm for the sake of protocols that use it as a
1839 * if the salt is longer than the block size of the hash algorithm; then
1844 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1847 * \return The corresponding HKDF-Extract algorithm.
1849 * hash algorithm.
1853 /** Whether the specified algorithm is an HKDF-Extract algorithm.
1855 * HKDF-Extract is a family of key derivation algorithms that are based
1858 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1860 * \return 1 if \c alg is an HKDF-Extract algorithm, 0 otherwise.
1862 * key derivation algorithm identifier.
1868 /** Macro to build an HKDF-Expand algorithm.
1871 * HKDF-Expand using HMAC-SHA-256.
1873 * This key derivation algorithm uses the following inputs:
1874 * - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK).
1875 * - PSA_KEY_DERIVATION_INPUT_INFO is the info string.
1880 * \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF`
1882 * a separate algorithm for the sake of protocols that use it as a building
1886 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1889 * \return The corresponding HKDF-Expand algorithm.
1891 * hash algorithm.
1895 /** Whether the specified algorithm is an HKDF-Expand algorithm.
1897 * HKDF-Expand is a family of key derivation algorithms that are based
1900 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1902 * \return 1 if \c alg is an HKDF-Expand algorithm, 0 otherwise.
1904 * key derivation algorithm identifier.
1909 /** Whether the specified algorithm is an HKDF or HKDF-Extract or
1910 * HKDF-Expand algorithm.
1913 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1915 * \return 1 if \c alg is any HKDF type algorithm, 0 otherwise.
1917 * key derivation algorithm identifier.
1925 /** Macro to build a TLS-1.2 PRF algorithm.
1929 * used with either SHA-256 or SHA-384.
1931 * This key derivation algorithm uses the following inputs, which must be
1933 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed.
1934 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
1935 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label.
1937 * For the application to TLS-1.2 key expansion, the seed is the
1942 * TLS 1.2 PRF using HMAC-SHA-256.
1944 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
1947 * \return The corresponding TLS-1.2 PRF algorithm.
1949 * hash algorithm.
1954 /** Whether the specified algorithm is a TLS-1.2 PRF algorithm.
1956 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
1958 * \return 1 if \c alg is a TLS-1.2 PRF algorithm, 0 otherwise.
1960 * key derivation algorithm identifier.
1968 /** Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.
1970 * In a pure-PSK handshake in TLS 1.2, the master secret is derived
1972 * (RFC 4279, Section 2) and the TLS-1.2 PRF (RFC 5246, Section 5).
1973 * The latter is based on HMAC and can be used with either SHA-256
1974 * or SHA-384.
1976 * This key derivation algorithm uses the following inputs, which must be
1978 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed.
1979 * - #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the
1983 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
1984 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label.
1986 * For the application to TLS-1.2, the seed (which is
1987 * forwarded to the TLS-1.2 PRF) is the concatenation of the
1991 * - for a plain PSK cipher suite (RFC 4279, Section 2), omit
1993 * - for a DHE-PSK (RFC 4279, Section 3) or ECDHE-PSK cipher suite
1997 * algorithm constructed as
2003 * - for a RSA-PSK cipher suite (RFC 4279, Section 4), the other secret
2004 * should be the 48-byte client challenge (the PreMasterSecret of
2006 * a 46-byte random string chosen by the client. On the server, this is
2012 * TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.
2014 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
2017 * \return The corresponding TLS-1.2 PSK to MS algorithm.
2019 * hash algorithm.
2024 /** Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.
2026 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2028 * \return 1 if \c alg is a TLS-1.2 PSK to MS algorithm, 0 otherwise.
2030 * key derivation algorithm identifier.
2037 /* The TLS 1.2 ECJPAKE-to-PMS KDF. It takes the shared secret K (an EC point
2038 * in case of EC J-PAKE) and calculates SHA256(K.X) that the rest of TLS 1.2
2040 * https://datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01#section-8.7.
2043 * #PSA_KEY_DERIVATION_INPUT_SECRET is the shared secret K from EC J-PAKE.
2044 * The only supported curve is secp256r1 (the 256-bit curve in
2051 /* This flag indicates whether the key derivation algorithm is suitable for
2052 * use on low-entropy secrets such as password - these algorithms are also
2056 * Those algorithms cannot be combined with a key agreement algorithm.
2061 /** Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm.
2064 * This macro specifies the PBKDF2 algorithm constructed using a PRF based on
2067 * using the PRF HMAC-SHA-256.
2069 * This key derivation algorithm uses the following inputs, which must be
2071 * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count.
2073 * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt.
2077 * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed.
2080 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
2083 * \return The corresponding PBKDF2-HMAC-XXX algorithm.
2085 * hash algorithm.
2090 /** Whether the specified algorithm is a PBKDF2-HMAC algorithm.
2092 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2094 * \return 1 if \c alg is a PBKDF2-HMAC algorithm, 0 otherwise.
2096 * key derivation algorithm identifier.
2102 /** The PBKDF2-AES-CMAC-PRF-128 password hashing / key stretching algorithm.
2105 * This macro specifies the PBKDF2 algorithm constructed using the
2106 * AES-CMAC-PRF-128 PRF specified by RFC 4615.
2108 * This key derivation algorithm uses the same inputs as
2120 /** Macro to build a combined algorithm that chains a key agreement with
2123 * \param ka_alg A key agreement algorithm (\c PSA_ALG_XXX value such
2125 * \param kdf_alg A key derivation algorithm (\c PSA_ALG_XXX value such
2129 * algorithm.
2131 * key agreement algorithm or \p kdf_alg is not a
2132 * supported key derivation algorithm.
2143 /** Whether the specified algorithm is a raw key agreement algorithm.
2145 * A raw key agreement algorithm is one that does not specify
2148 * a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are
2151 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2153 * \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise.
2155 * algorithm identifier.
2164 /** The finite-field Diffie-Hellman (DH) key agreement algorithm.
2167 * `g^{ab}` in big-endian format.
2173 /** Whether the specified algorithm is a finite field Diffie-Hellman algorithm.
2175 * This includes the raw finite field Diffie-Hellman algorithm as well as
2176 * finite-field Diffie-Hellman followed by any supporter key derivation
2177 * algorithm.
2179 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2181 * \return 1 if \c alg is a finite field Diffie-Hellman algorithm, 0 otherwise.
2183 * key agreement algorithm identifier.
2188 /** The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.
2190 * The shared secret produced by key agreement is the x-coordinate of
2195 * is padded with zero bits. The byte order is either little-endian
2196 * or big-endian depending on the curve type.
2198 * - For Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`),
2199 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A`
2200 * in little-endian byte order.
2202 * - For Weierstrass curves over prime fields (curve types
2204 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A`
2205 * in big-endian byte order.
2207 * - For Weierstrass curves over binary fields (curve types
2209 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A`
2210 * in big-endian byte order.
2215 /** Whether the specified algorithm is an elliptic curve Diffie-Hellman
2216 * algorithm.
2218 * This includes the raw elliptic curve Diffie-Hellman algorithm as well as
2219 * elliptic curve Diffie-Hellman followed by any supporter key derivation
2220 * algorithm.
2222 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2224 * \return 1 if \c alg is an elliptic curve Diffie-Hellman algorithm,
2227 * key agreement algorithm identifier.
2232 /** Whether the specified algorithm encoding is a wildcard.
2234 * Wildcard values may only be used to set the usage algorithm field in
2237 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2239 * \return 1 if \c alg is a wildcard algorithm encoding.
2240 * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for
2243 * algorithm identifier.
2254 /** Get the hash used by a composite algorithm.
2256 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
2258 * \return The underlying hash algorithm if alg is a composite algorithm that
2259 * uses a hash algorithm.
2261 * \return \c 0 if alg is not a composite algorithm that uses a hash.
2284 * If an implementation stores data about the key in a non-volatile memory,
2336 * implementation-specific device management event occurs (for example,
2348 /** Whether a key lifetime indicates that the key is read-only.
2350 * Read-only keys cannot be created or destroyed through the PSA Crypto API.
2351 * They must be created through platform-specific means that bypass the API.
2353 * Some platforms may offer ways to destroy read-only keys. For example,
2355 * low-privilege application can use a key but is not allowed to destroy
2356 * it, and the platform exposes the key to the application with a read-only
2357 * lifetime. High-privilege code can destroy the key even though the
2358 * application sees the key as read-only.
2363 * \return \c 1 if the key is read-only, otherwise \c 0.
2384 * keys without delegating the storage to a third-party cryptoprocessor.
2399 /* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */
2401 /* *INDENT-ON* */
2440 * \return Non-zero if the two key identifier are equal, zero otherwise.
2452 * \return Non-zero if the key identifier is null, zero otherwise.
2482 * \return Non-zero if the two key identifier are equal, zero otherwise.
2495 * \return Non-zero if the key identifier is null, zero otherwise.
2534 * enforce the non-exportability of keys, copying a key outside the secure
2547 * for an AEAD encryption-and-authentication operation,
2558 * for an AEAD decryption-and-verification operation,
2661 /** A low-entropy secret input for password hashing / key stretching.
2666 * also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or
2679 /** A high-entropy additional secret input for key derivation.
2732 /** Check if two AEAD algorithm identifiers refer to the same AEAD algorithm
2735 * \param aead_alg_1 An AEAD algorithm identifier.
2736 * \param aead_alg_2 An AEAD algorithm identifier.
2738 * \return 1 if both identifiers refer to the same AEAD algorithm,
2741 * a supported AEAD algorithm.