include/psa/crypto.h

173  * with psa_set_key_id(). By default, a key that has a persistent identifier
262  * algorithms are permitted to be used with this key. The following
264  * - 0 does not allow any cryptographic operation with the key. The key
269  *   signature scheme with any hash algorithm.
367  * This function first resets the attribute structure as with
422  * free all resources associated with the key in volatile memory. The key
447  * This function may be used to share a key with a different party,
471  *   fails with the status #PSA_ERROR_INVALID_ARGUMENT.
503  *         already a persistent key with the given identifier.
540  * resources associated with the key.
546  *             eventually be wiped from memory. With threading enabled
562  *         There was a failure in communication with the cryptoprocessor.
639  *         already a persistent key with the given identifier.
706  *   where `m` is the bit size associated with the curve, i.e. the bit size
790  *   Let `m` be the bit size associated with the curve, i.e. the bit size of
882 /** Calculate the hash (digest) of a message and compare it with a
962  * -# Initialize the operation object with one of the methods described in the
969  *    To compare the hash with an expected value, call psa_hash_verify().
1047  *          hash values with a function such as \c memcmp is risky
1081 /** Finish the calculation of the hash of a message and compare it with
1087  * compares the calculated hash with the expected hash passed as a
1152  * to calling psa_hash_setup() on \p target_operation with the same
1154  * psa_hash_update() on \p target_operation with the same input that
1189  *       MAC values with a function such as \c memcmp is risky
1210  *         \p key is not compatible with \p alg.
1234 /** Calculate the MAC of a message and compare it with a reference value.
1253  *         \p key is not compatible with \p alg.
1325  * -# Initialize the operation object with one of the methods described in the
1358  *         \p key is not compatible with \p alg.
1385  * -# Initialize the operation object with one of the methods described in the
1420  *         \c key is not compatible with \c alg.
1482  *          MAC values with a function such as \c memcmp is risky
1519 /** Finish the calculation of the MAC of a message and compare it with
1525  * compares the calculated MAC with the expected MAC passed as a
1596  * This function encrypts a message with a random IV (initialization
1597  * vector). Use the multipart operation interface with a
1619  *         \p key is not compatible with \p alg.
1643  * This function decrypts a message encrypted with a symmetric cipher.
1666  *         \p key is not compatible with \p alg.
1730  * The sequence of operations to encrypt a message with a symmetric cipher
1734  * -# Initialize the operation object with one of the methods described in the
1773  *         \p key is not compatible with \p alg.
1793  * The sequence of operations to decrypt a message with a symmetric cipher
1797  * -# Initialize the operation object with one of the methods described in the
1801  * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
1836  *         \p key is not compatible with \p alg.
1882  *         The operation state is not valid (it must be active, with no IV set),
1924  *         encrypt operation, with no IV set), or the library has not been
1964  *         The operation state is not valid (it must be active, with an IV set
2016  *         The operation state is not valid (it must be active, with an IV set
2056 /** \defgroup aead Authenticated encryption with associated data (AEAD)
2102  *         \p key is not compatible with \p alg.
2175  *         \p key is not compatible with \p alg.
2248  * The sequence of operations to encrypt a message with authentication
2252  * -# Initialize the operation object with one of the methods described in the
2300  *         \p key is not compatible with \p alg.
2318  * The sequence of operations to decrypt a message with authentication
2322  * -# Initialize the operation object with one of the methods described in the
2330  * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2364  *         \p key is not compatible with \p alg.
2385  * operation with an appropriate size for the chosen algorithm, key type
2412  *         operation, with no nonce set), or the library has not been
2451  *         The operation state is not valid (it must be active, with no nonce
2469  * You may call this function before or after setting the nonce with
2512  * data to encrypt or decrypt with psa_aead_update().
2516  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2536  *         was previously specified with psa_aead_set_lengths().
2560  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2575  *            fact as an oracle to decrypt any message encrypted with the
2619  *         specified with psa_aead_set_lengths(), or
2621  *         was previously specified with psa_aead_set_lengths().
2643  * The operation must have been set up with psa_aead_encrypt_setup().
2647  * psa_aead_update_ad() with the plaintext formed by concatenating the
2704  *         specified with psa_aead_set_lengths(), or
2707  *         specified with psa_aead_set_lengths().
2715  *         operation with a nonce set), or the library has not been previously
2730  * The operation must have been set up with psa_aead_decrypt_setup().
2787  *         specified with psa_aead_set_lengths(), or
2790  *         specified with psa_aead_set_lengths().
2798  *         operation with a nonce set), or the library has not been previously
2844  * \brief Sign a message with a private key. For hash-and-sign algorithms,
2857  *                              is true), that is compatible with the type of
2909 /** \brief Verify the signature of a message with a public key, using
2924  *                              is true), that is compatible with the type of
2961  * \brief Sign a hash or short message with a private key.
2975  *                              is true), that is compatible with
3030  *                          is true), that is compatible with
3065  * \brief Encrypt a short message with a public key.
3072  *                              compatible with the type of \p key.
3126  * \brief Decrypt a short message with a private key.
3132  *                              compatible with the type of \p key.
3241  * -# Start with an initialized object of type #psa_key_derivation_operation_t.
3247  * -# Optionally set the operation's maximum capacity with
3257  * -# Clean up the key derivation operation object with
3373  *                                It must have been set up with
3383  *         \c step is not compatible with the operation's algorithm, or
3417  *                                It must have been set up with
3426  *         \c step is not compatible with the operation's algorithm, or
3462  *                                It must have been set up with
3474  *   or  a key with #PSA_KEY_USAGE_DERIVE set;
3478  *   was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was
3479  *   either a direct input or a key with #PSA_KEY_USAGE_DERIVE set;
3481  *   or  a key with #PSA_KEY_USAGE_VERIFY_DERIVATION set;
3493  *         \c step is not compatible with the operation's algorithm, or
3525  *                                It must have been set up with
3526  *                                psa_key_derivation_setup() with a
3544  *                          with key attributes indicating the public key
3558  *         \c private_key is not compatible with \c alg,
3559  *         or \p peer_key is not valid for \c alg or not compatible with
3609  *                          succeed, even with a smaller output buffer.
3677  *   \c bits bits with constraints as to which bit sequences are acceptable,
3720  * the input to that step must be provided with psa_key_derivation_input_key().
3726  *       with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT
3746  *         already a persistent key with the given identifier.
3751  *         this function will not succeed, even with a smaller output buffer.
3782 /** Derive a key from an ongoing key derivation operation with custom
3786  * this function with the default production parameters.
3801  *                          with \p custom_data_length = 0,
3804  * \param[in] custom_data   Variable-length data associated with \c custom.
3818  *         already a persistent key with the given identifier.
3823  *         this function will not succeed, even with a smaller output buffer.
3859  * pointer to a struct with a flexible array member, and that is not
3863 /** Derive a key from an ongoing key derivation operation with custom
3880  *                          with \p params_data_length = 0,
3900  *         already a persistent key with the given identifier.
3905  *         this function will not succeed, even with a smaller output buffer.
3979  *                          succeed, even with a smaller expected output.
4044  *                          succeed, even with a smaller expected output.
4092  * input to a key derivation algorithm. To chain a key agreement with
4120  *         \p private_key is not compatible with \p alg,
4121  *         or \p peer_key is not valid for \p alg or not compatible with
4194  *       with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT
4209  *         already a persistent key with the given identifier.
4233  * function with the default production parameters. In addition, this function
4237  * - RSA keys: generation with a custom public exponent.
4245  *                          with \p custom_data_length = 0,
4248  * \param[in] custom_data   Variable-length data associated with \c custom.
4262  *         already a persistent key with the given identifier.
4287  * pointer to a struct with a flexible array member, and that is not
4303  *                          with \p params_data_length = 0,
4319  *         already a persistent key with the given identifier.
4433  *                              provided to help with tuning this value.
4444  *                              responsibility to either call again with the
4470  * \warning                     With implementations that interpret this number
4473  *                              call results in immediate return with no ops
4564  * \brief                       Start signing a hash or short message with a
4573  * \note                        This function combined with \c
4577  *                              resume according to the limit set with \c
4603  *                              is true), that is compatible with
4610  *         with the same context to complete the operation
4641  *                              signing a hash or short message with a private
4650  * \note                        This function combined with \c
4653  *                              early and resume according to the limit set with
4673  *                              had \c psa_sign_hash_start() called with it
4697  *         Call this function again with the same operation object.
4723  *         psa_sign_hash_start() with this operation object. It is
4782  * \note                        This function combined with \c
4786  *                              resume according to the limit set with \c
4812  *                              is true), that is compatible with
4821  *         psa_verify_hash_complete() with the same context to complete the
4855  *                              signed with a private key, in an interruptible
4864  * \note                        This function combined with \c
4868  *                              set with \c psa_interruptible_set_max_ops() to
4888  *                              had \c psa_verify_hash_start() called with it
4897  *         Call this function again with the same operation object.