crypto.h

00001 /**
00002  * \file psa/crypto.h
00003  * \brief Platform Security Architecture cryptography module
00004  */
00005 /*
00006  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  */
00021 
00022 #ifndef PSA_CRYPTO_H
00023 #define PSA_CRYPTO_H
00024 
00025 #include "crypto_platform.h"
00026 
00027 #include <stddef.h>
00028 
00029 #ifdef __DOXYGEN_ONLY__
00030 /* This __DOXYGEN_ONLY__ block contains mock definitions for things that
00031  * must be defined in the crypto_platform.h header. These mock definitions
00032  * are present in this file as a convenience to generate pretty-printed
00033  * documentation that includes those definitions. */
00034 
00035 /** \defgroup platform Implementation-specific definitions
00036  * @{
00037  */
00038 
00039 /** \brief Key handle.
00040  *
00041  * This type represents open handles to keys. It must be an unsigned integral
00042  * type. The choice of type is implementation-dependent.
00043  *
00044  * 0 is not a valid key handle. How other handle values are assigned is
00045  * implementation-dependent.
00046  */
00047 typedef _unsigned_integral_type_ psa_key_handle_t;
00048 
00049 /**@}*/
00050 #endif /* __DOXYGEN_ONLY__ */
00051 
00052 #ifdef __cplusplus
00053 extern "C" {
00054 #endif
00055 
00056 /* The file "crypto_types.h" declares types that encode errors,
00057  * algorithms, key types, policies, etc. */
00058 #include "crypto_types.h"
00059 
00060 /** \defgroup version API version
00061  * @{
00062  */
00063 
00064 /**
00065  * The major version of this implementation of the PSA Crypto API
00066  */
00067 #define PSA_CRYPTO_API_VERSION_MAJOR 1
00068 
00069 /**
00070  * The minor version of this implementation of the PSA Crypto API
00071  */
00072 #define PSA_CRYPTO_API_VERSION_MINOR 0
00073 
00074 /**@}*/
00075 
00076 /* The file "crypto_values.h" declares macros to build and analyze values
00077  * of integral types defined in "crypto_types.h". */
00078 #include "crypto_values.h"
00079 
00080 /** \defgroup initialization Library initialization
00081  * @{
00082  */
00083 
00084 /**
00085  * \brief Library initialization.
00086  *
00087  * Applications must call this function before calling any other
00088  * function in this module.
00089  *
00090  * Applications may call this function more than once. Once a call
00091  * succeeds, subsequent calls are guaranteed to succeed.
00092  *
00093  * If the application calls other functions before calling psa_crypto_init(),
00094  * the behavior is undefined. Implementations are encouraged to either perform
00095  * the operation as if the library had been initialized or to return
00096  * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
00097  * implementations should not return a success status if the lack of
00098  * initialization may have security implications, for example due to improper
00099  * seeding of the random number generator.
00100  *
00101  * \retval #PSA_SUCCESS
00102  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00103  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00104  * \retval #PSA_ERROR_HARDWARE_FAILURE
00105  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00106  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
00107  */
00108 psa_status_t psa_crypto_init(void);
00109 
00110 /**@}*/
00111 
00112 /** \addtogroup attributes
00113  * @{
00114  */
00115 
00116 /** \def PSA_KEY_ATTRIBUTES_INIT
00117  *
00118  * This macro returns a suitable initializer for a key attribute structure
00119  * of type #psa_key_attributes_t.
00120  */
00121 #ifdef __DOXYGEN_ONLY__
00122 /* This is an example definition for documentation purposes.
00123  * Implementations should define a suitable value in `crypto_struct.h`.
00124  */
00125 #define PSA_KEY_ATTRIBUTES_INIT {0}
00126 #endif
00127 
00128 /** Return an initial value for a key attributes structure.
00129  */
00130 static psa_key_attributes_t psa_key_attributes_init(void);
00131 
00132 /** Declare a key as persistent and set its key identifier.
00133  *
00134  * If the attribute structure currently declares the key as volatile (which
00135  * is the default content of an attribute structure), this function sets
00136  * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
00137  *
00138  * This function does not access storage, it merely stores the given
00139  * value in the structure.
00140  * The persistent key will be written to storage when the attribute
00141  * structure is passed to a key creation function such as
00142  * psa_import_key(), psa_generate_key(),
00143  * psa_key_derivation_output_key() or psa_copy_key().
00144  *
00145  * This function may be declared as `static` (i.e. without external
00146  * linkage). This function may be provided as a function-like macro,
00147  * but in this case it must evaluate each of its arguments exactly once.
00148  *
00149  * \param[out] attributes       The attribute structure to write to.
00150  * \param id                    The persistent identifier for the key.
00151  */
00152 static void psa_set_key_id(psa_key_attributes_t *attributes,
00153                            psa_key_id_t id);
00154 
00155 /** Set the location of a persistent key.
00156  *
00157  * To make a key persistent, you must give it a persistent key identifier
00158  * with psa_set_key_id(). By default, a key that has a persistent identifier
00159  * is stored in the default storage area identifier by
00160  * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
00161  * area, or to explicitly declare the key as volatile.
00162  *
00163  * This function does not access storage, it merely stores the given
00164  * value in the structure.
00165  * The persistent key will be written to storage when the attribute
00166  * structure is passed to a key creation function such as
00167  * psa_import_key(), psa_generate_key(),
00168  * psa_key_derivation_output_key() or psa_copy_key().
00169  *
00170  * This function may be declared as `static` (i.e. without external
00171  * linkage). This function may be provided as a function-like macro,
00172  * but in this case it must evaluate each of its arguments exactly once.
00173  *
00174  * \param[out] attributes       The attribute structure to write to.
00175  * \param lifetime              The lifetime for the key.
00176  *                              If this is #PSA_KEY_LIFETIME_VOLATILE, the
00177  *                              key will be volatile, and the key identifier
00178  *                              attribute is reset to 0.
00179  */
00180 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
00181                                  psa_key_lifetime_t lifetime);
00182 
00183 /** Retrieve the key identifier from key attributes.
00184  *
00185  * This function may be declared as `static` (i.e. without external
00186  * linkage). This function may be provided as a function-like macro,
00187  * but in this case it must evaluate its argument exactly once.
00188  *
00189  * \param[in] attributes        The key attribute structure to query.
00190  *
00191  * \return The persistent identifier stored in the attribute structure.
00192  *         This value is unspecified if the attribute structure declares
00193  *         the key as volatile.
00194  */
00195 static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
00196 
00197 /** Retrieve the lifetime from key attributes.
00198  *
00199  * This function may be declared as `static` (i.e. without external
00200  * linkage). This function may be provided as a function-like macro,
00201  * but in this case it must evaluate its argument exactly once.
00202  *
00203  * \param[in] attributes        The key attribute structure to query.
00204  *
00205  * \return The lifetime value stored in the attribute structure.
00206  */
00207 static psa_key_lifetime_t psa_get_key_lifetime(
00208     const psa_key_attributes_t *attributes);
00209 
00210 /** Declare usage flags for a key.
00211  *
00212  * Usage flags are part of a key's usage policy. They encode what
00213  * kind of operations are permitted on the key. For more details,
00214  * refer to the documentation of the type #psa_key_usage_t.
00215  *
00216  * This function overwrites any usage flags
00217  * previously set in \p attributes.
00218  *
00219  * This function may be declared as `static` (i.e. without external
00220  * linkage). This function may be provided as a function-like macro,
00221  * but in this case it must evaluate each of its arguments exactly once.
00222  *
00223  * \param[out] attributes       The attribute structure to write to.
00224  * \param usage_flags           The usage flags to write.
00225  */
00226 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
00227                                     psa_key_usage_t usage_flags);
00228 
00229 /** Retrieve the usage flags from key attributes.
00230  *
00231  * This function may be declared as `static` (i.e. without external
00232  * linkage). This function may be provided as a function-like macro,
00233  * but in this case it must evaluate its argument exactly once.
00234  *
00235  * \param[in] attributes        The key attribute structure to query.
00236  *
00237  * \return The usage flags stored in the attribute structure.
00238  */
00239 static psa_key_usage_t psa_get_key_usage_flags(
00240     const psa_key_attributes_t *attributes);
00241 
00242 /** Declare the permitted algorithm policy for a key.
00243  *
00244  * The permitted algorithm policy of a key encodes which algorithm or
00245  * algorithms are permitted to be used with this key. The following
00246  * algorithm policies are supported:
00247  * - 0 does not allow any cryptographic operation with the key. The key
00248  *   may be used for non-cryptographic actions such as exporting (if
00249  *   permitted by the usage flags).
00250  * - An algorithm value permits this particular algorithm.
00251  * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified
00252  *   signature scheme with any hash algorithm.
00253  *
00254  * This function overwrites any algorithm policy
00255  * previously set in \p attributes.
00256  *
00257  * This function may be declared as `static` (i.e. without external
00258  * linkage). This function may be provided as a function-like macro,
00259  * but in this case it must evaluate each of its arguments exactly once.
00260  *
00261  * \param[out] attributes       The attribute structure to write to.
00262  * \param alg                   The permitted algorithm policy to write.
00263  */
00264 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
00265                                   psa_algorithm_t alg);
00266 
00267 
00268 /** Retrieve the algorithm policy from key attributes.
00269  *
00270  * This function may be declared as `static` (i.e. without external
00271  * linkage). This function may be provided as a function-like macro,
00272  * but in this case it must evaluate its argument exactly once.
00273  *
00274  * \param[in] attributes        The key attribute structure to query.
00275  *
00276  * \return The algorithm stored in the attribute structure.
00277  */
00278 static psa_algorithm_t psa_get_key_algorithm(
00279     const psa_key_attributes_t *attributes);
00280 
00281 /** Declare the type of a key.
00282  *
00283  * This function overwrites any key type
00284  * previously set in \p attributes.
00285  *
00286  * This function may be declared as `static` (i.e. without external
00287  * linkage). This function may be provided as a function-like macro,
00288  * but in this case it must evaluate each of its arguments exactly once.
00289  *
00290  * \param[out] attributes       The attribute structure to write to.
00291  * \param type                  The key type to write.
00292  *                              If this is 0, the key type in \p attributes
00293  *                              becomes unspecified.
00294  */
00295 static void psa_set_key_type(psa_key_attributes_t *attributes,
00296                              psa_key_type_t type);
00297 
00298 
00299 /** Declare the size of a key.
00300  *
00301  * This function overwrites any key size previously set in \p attributes.
00302  *
00303  * This function may be declared as `static` (i.e. without external
00304  * linkage). This function may be provided as a function-like macro,
00305  * but in this case it must evaluate each of its arguments exactly once.
00306  *
00307  * \param[out] attributes       The attribute structure to write to.
00308  * \param bits                  The key size in bits.
00309  *                              If this is 0, the key size in \p attributes
00310  *                              becomes unspecified. Keys of size 0 are
00311  *                              not supported.
00312  */
00313 static void psa_set_key_bits(psa_key_attributes_t *attributes,
00314                              size_t bits);
00315 
00316 /** Retrieve the key type from key attributes.
00317  *
00318  * This function may be declared as `static` (i.e. without external
00319  * linkage). This function may be provided as a function-like macro,
00320  * but in this case it must evaluate its argument exactly once.
00321  *
00322  * \param[in] attributes        The key attribute structure to query.
00323  *
00324  * \return The key type stored in the attribute structure.
00325  */
00326 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
00327 
00328 /** Retrieve the key size from key attributes.
00329  *
00330  * This function may be declared as `static` (i.e. without external
00331  * linkage). This function may be provided as a function-like macro,
00332  * but in this case it must evaluate its argument exactly once.
00333  *
00334  * \param[in] attributes        The key attribute structure to query.
00335  *
00336  * \return The key size stored in the attribute structure, in bits.
00337  */
00338 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
00339 
00340 /** Retrieve the attributes of a key.
00341  *
00342  * This function first resets the attribute structure as with
00343  * psa_reset_key_attributes(). It then copies the attributes of
00344  * the given key into the given attribute structure.
00345  *
00346  * \note This function may allocate memory or other resources.
00347  *       Once you have called this function on an attribute structure,
00348  *       you must call psa_reset_key_attributes() to free these resources.
00349  *
00350  * \param[in] handle            Handle to the key to query.
00351  * \param[in,out] attributes    On success, the attributes of the key.
00352  *                              On failure, equivalent to a
00353  *                              freshly-initialized structure.
00354  *
00355  * \retval #PSA_SUCCESS
00356  * \retval #PSA_ERROR_INVALID_HANDLE
00357  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00358  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00359  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00360  * \retval #PSA_ERROR_STORAGE_FAILURE
00361  * \retval #PSA_ERROR_BAD_STATE
00362  *         The library has not been previously initialized by psa_crypto_init().
00363  *         It is implementation-dependent whether a failure to initialize
00364  *         results in this error code.
00365  */
00366 psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
00367                                     psa_key_attributes_t *attributes);
00368 
00369 /** Reset a key attribute structure to a freshly initialized state.
00370  *
00371  * You must initialize the attribute structure as described in the
00372  * documentation of the type #psa_key_attributes_t before calling this
00373  * function. Once the structure has been initialized, you may call this
00374  * function at any time.
00375  *
00376  * This function frees any auxiliary resources that the structure
00377  * may contain.
00378  *
00379  * \param[in,out] attributes    The attribute structure to reset.
00380  */
00381 void psa_reset_key_attributes(psa_key_attributes_t *attributes);
00382 
00383 /**@}*/
00384 
00385 /** \defgroup key_management Key management
00386  * @{
00387  */
00388 
00389 /** Open a handle to an existing persistent key.
00390  *
00391  * Open a handle to a persistent key. A key is persistent if it was created
00392  * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
00393  * always has a nonzero key identifier, set with psa_set_key_id() when
00394  * creating the key. Implementations may provide additional pre-provisioned
00395  * keys that can be opened with psa_open_key(). Such keys have a key identifier
00396  * in the vendor range, as documented in the description of #psa_key_id_t.
00397  *
00398  * The application must eventually close the handle with psa_close_key() or
00399  * psa_destroy_key() to release associated resources. If the application dies
00400  * without calling one of these functions, the implementation should perform
00401  * the equivalent of a call to psa_close_key().
00402  *
00403  * Some implementations permit an application to open the same key multiple
00404  * times. If this is successful, each call to psa_open_key() will return a
00405  * different key handle.
00406  *
00407  * \note Applications that rely on opening a key multiple times will not be
00408  * portable to implementations that only permit a single key handle to be
00409  * opened. See also :ref:\`key-handles\`.
00410  *
00411  * \param id            The persistent identifier of the key.
00412  * \param[out] handle   On success, a handle to the key.
00413  *
00414  * \retval #PSA_SUCCESS
00415  *         Success. The application can now use the value of `*handle`
00416  *         to access the key.
00417  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00418  *         The implementation does not have sufficient resources to open the
00419  *         key. This can be due to reaching an implementation limit on the
00420  *         number of open keys, the number of open key handles, or available
00421  *         memory.
00422  * \retval #PSA_ERROR_DOES_NOT_EXIST
00423  *         There is no persistent key with key identifier \p id.
00424  * \retval #PSA_ERROR_INVALID_ARGUMENT
00425  *         \p id is not a valid persistent key identifier.
00426  * \retval #PSA_ERROR_NOT_PERMITTED
00427  *         The specified key exists, but the application does not have the
00428  *         permission to access it. Note that this specification does not
00429  *         define any way to create such a key, but it may be possible
00430  *         through implementation-specific means.
00431  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00432  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00433  * \retval #PSA_ERROR_STORAGE_FAILURE
00434  * \retval #PSA_ERROR_BAD_STATE
00435  *         The library has not been previously initialized by psa_crypto_init().
00436  *         It is implementation-dependent whether a failure to initialize
00437  *         results in this error code.
00438  */
00439 psa_status_t psa_open_key(psa_key_id_t id,
00440                           psa_key_handle_t *handle);
00441 
00442 
00443 /** Close a key handle.
00444  *
00445  * If the handle designates a volatile key, this will destroy the key material
00446  * and free all associated resources, just like psa_destroy_key().
00447  *
00448  * If this is the last open handle to a persistent key, then closing the handle
00449  * will free all resources associated with the key in volatile memory. The key
00450  * data in persistent storage is not affected and can be opened again later
00451  * with a call to psa_open_key().
00452  *
00453  * Closing the key handle makes the handle invalid, and the key handle
00454  * must not be used again by the application.
00455  *
00456  * \note If the key handle was used to set up an active
00457  * :ref:\`multipart operation <multipart-operations>\`, then closing the
00458  * key handle can cause the multipart operation to fail. Applications should
00459  * maintain the key handle until after the multipart operation has finished.
00460  *
00461  * \param handle        The key handle to close.
00462  *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
00463  *
00464  * \retval #PSA_SUCCESS
00465  *         \p handle was a valid handle or \c 0. It is now closed.
00466  * \retval #PSA_ERROR_INVALID_HANDLE
00467  *         \p handle is not a valid handle nor \c 0.
00468  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00469  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00470  * \retval #PSA_ERROR_BAD_STATE
00471  *         The library has not been previously initialized by psa_crypto_init().
00472  *         It is implementation-dependent whether a failure to initialize
00473  *         results in this error code.
00474  */
00475 psa_status_t psa_close_key(psa_key_handle_t handle);
00476 
00477 /** Make a copy of a key.
00478  *
00479  * Copy key material from one location to another.
00480  *
00481  * This function is primarily useful to copy a key from one location
00482  * to another, since it populates a key using the material from
00483  * another key which may have a different lifetime.
00484  *
00485  * This function may be used to share a key with a different party,
00486  * subject to implementation-defined restrictions on key sharing.
00487  *
00488  * The policy on the source key must have the usage flag
00489  * #PSA_KEY_USAGE_COPY set.
00490  * This flag is sufficient to permit the copy if the key has the lifetime
00491  * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
00492  * Some secure elements do not provide a way to copy a key without
00493  * making it extractable from the secure element. If a key is located
00494  * in such a secure element, then the key must have both usage flags
00495  * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
00496  * a copy of the key outside the secure element.
00497  *
00498  * The resulting key may only be used in a way that conforms to
00499  * both the policy of the original key and the policy specified in
00500  * the \p attributes parameter:
00501  * - The usage flags on the resulting key are the bitwise-and of the
00502  *   usage flags on the source policy and the usage flags in \p attributes.
00503  * - If both allow the same algorithm or wildcard-based
00504  *   algorithm policy, the resulting key has the same algorithm policy.
00505  * - If either of the policies allows an algorithm and the other policy
00506  *   allows a wildcard-based algorithm policy that includes this algorithm,
00507  *   the resulting key allows the same algorithm.
00508  * - If the policies do not allow any algorithm in common, this function
00509  *   fails with the status #PSA_ERROR_INVALID_ARGUMENT.
00510  *
00511  * The effect of this function on implementation-defined attributes is
00512  * implementation-defined.
00513  *
00514  * \param source_handle     The key to copy. It must be a valid key handle.
00515  * \param[in] attributes    The attributes for the new key.
00516  *                          They are used as follows:
00517  *                          - The key type and size may be 0. If either is
00518  *                            nonzero, it must match the corresponding
00519  *                            attribute of the source key.
00520  *                          - The key location (the lifetime and, for
00521  *                            persistent keys, the key identifier) is
00522  *                            used directly.
00523  *                          - The policy constraints (usage flags and
00524  *                            algorithm policy) are combined from
00525  *                            the source key and \p attributes so that
00526  *                            both sets of restrictions apply, as
00527  *                            described in the documentation of this function.
00528  * \param[out] target_handle On success, a handle to the newly created key.
00529  *                          \c 0 on failure.
00530  *
00531  * \retval #PSA_SUCCESS
00532  * \retval #PSA_ERROR_INVALID_HANDLE
00533  *         \p source_handle is invalid.
00534  * \retval #PSA_ERROR_ALREADY_EXISTS
00535  *         This is an attempt to create a persistent key, and there is
00536  *         already a persistent key with the given identifier.
00537  * \retval #PSA_ERROR_INVALID_ARGUMENT
00538  *         The lifetime or identifier in \p attributes are invalid.
00539  * \retval #PSA_ERROR_INVALID_ARGUMENT
00540  *         The policy constraints on the source and specified in
00541  *         \p attributes are incompatible.
00542  * \retval #PSA_ERROR_INVALID_ARGUMENT
00543  *         \p attributes specifies a key type or key size
00544  *         which does not match the attributes of the source key.
00545  * \retval #PSA_ERROR_NOT_PERMITTED
00546  *         The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
00547  * \retval #PSA_ERROR_NOT_PERMITTED
00548  *         The source key is not exportable and its lifetime does not
00549  *         allow copying it to the target's lifetime.
00550  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00551  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
00552  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00553  * \retval #PSA_ERROR_HARDWARE_FAILURE
00554  * \retval #PSA_ERROR_STORAGE_FAILURE
00555  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00556  * \retval #PSA_ERROR_BAD_STATE
00557  *         The library has not been previously initialized by psa_crypto_init().
00558  *         It is implementation-dependent whether a failure to initialize
00559  *         results in this error code.
00560  */
00561 psa_status_t psa_copy_key(psa_key_handle_t source_handle,
00562                           const psa_key_attributes_t *attributes,
00563                           psa_key_handle_t *target_handle);
00564 
00565 
00566 /**
00567  * \brief Destroy a key.
00568  *
00569  * This function destroys a key from both volatile
00570  * memory and, if applicable, non-volatile storage. Implementations shall
00571  * make a best effort to ensure that that the key material cannot be recovered.
00572  *
00573  * This function also erases any metadata such as policies and frees
00574  * resources associated with the key. To free all resources associated with
00575  * the key, all handles to the key must be closed or destroyed.
00576  *
00577  * Destroying the key makes the handle invalid, and the key handle
00578  * must not be used again by the application. Using other open handles to the
00579  * destroyed key in a cryptographic operation will result in an error.
00580  *
00581  * If a key is currently in use in a multipart operation, then destroying the
00582  * key will cause the multipart operation to fail.
00583  *
00584  * \param handle        Handle to the key to erase.
00585  *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
00586  *
00587  * \retval #PSA_SUCCESS
00588  *         \p handle was a valid handle and the key material that it
00589  *         referred to has been erased.
00590  *         Alternatively, \p handle is \c 0.
00591  * \retval #PSA_ERROR_NOT_PERMITTED
00592  *         The key cannot be erased because it is
00593  *         read-only, either due to a policy or due to physical restrictions.
00594  * \retval #PSA_ERROR_INVALID_HANDLE
00595  *         \p handle is not a valid handle nor \c 0.
00596  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00597  *         There was an failure in communication with the cryptoprocessor.
00598  *         The key material may still be present in the cryptoprocessor.
00599  * \retval #PSA_ERROR_STORAGE_FAILURE
00600  *         The storage is corrupted. Implementations shall make a best effort
00601  *         to erase key material even in this stage, however applications
00602  *         should be aware that it may be impossible to guarantee that the
00603  *         key material is not recoverable in such cases.
00604  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00605  *         An unexpected condition which is not a storage corruption or
00606  *         a communication failure occurred. The cryptoprocessor may have
00607  *         been compromised.
00608  * \retval #PSA_ERROR_BAD_STATE
00609  *         The library has not been previously initialized by psa_crypto_init().
00610  *         It is implementation-dependent whether a failure to initialize
00611  *         results in this error code.
00612  */
00613 psa_status_t psa_destroy_key(psa_key_handle_t handle);
00614 
00615 /**@}*/
00616 
00617 /** \defgroup import_export Key import and export
00618  * @{
00619  */
00620 
00621 /**
00622  * \brief Import a key in binary format.
00623  *
00624  * This function supports any output from psa_export_key(). Refer to the
00625  * documentation of psa_export_public_key() for the format of public keys
00626  * and to the documentation of psa_export_key() for the format for
00627  * other key types.
00628  *
00629  * The key data determines the key size. The attributes may optionally
00630  * specify a key size; in this case it must match the size determined
00631  * from the key data. A key size of 0 in \p attributes indicates that
00632  * the key size is solely determined by the key data.
00633  *
00634  * Implementations must reject an attempt to import a key of size 0.
00635  *
00636  * This specification supports a single format for each key type.
00637  * Implementations may support other formats as long as the standard
00638  * format is supported. Implementations that support other formats
00639  * should ensure that the formats are clearly unambiguous so as to
00640  * minimize the risk that an invalid input is accidentally interpreted
00641  * according to a different format.
00642  *
00643  * \param[in] attributes    The attributes for the new key.
00644  *                          The key size is always determined from the
00645  *                          \p data buffer.
00646  *                          If the key size in \p attributes is nonzero,
00647  *                          it must be equal to the size from \p data.
00648  * \param[out] handle       On success, a handle to the newly created key.
00649  *                          \c 0 on failure.
00650  * \param[in] data    Buffer containing the key data. The content of this
00651  *                    buffer is interpreted according to the type declared
00652  *                    in \p attributes.
00653  *                    All implementations must support at least the format
00654  *                    described in the documentation
00655  *                    of psa_export_key() or psa_export_public_key() for
00656  *                    the chosen type. Implementations may allow other
00657  *                    formats, but should be conservative: implementations
00658  *                    should err on the side of rejecting content if it
00659  *                    may be erroneous (e.g. wrong type or truncated data).
00660  * \param data_length Size of the \p data buffer in bytes.
00661  *
00662  * \retval #PSA_SUCCESS
00663  *         Success.
00664  *         If the key is persistent, the key material and the key's metadata
00665  *         have been saved to persistent storage.
00666  * \retval #PSA_ERROR_ALREADY_EXISTS
00667  *         This is an attempt to create a persistent key, and there is
00668  *         already a persistent key with the given identifier.
00669  * \retval #PSA_ERROR_NOT_SUPPORTED
00670  *         The key type or key size is not supported, either by the
00671  *         implementation in general or in this particular persistent location.
00672  * \retval #PSA_ERROR_INVALID_ARGUMENT
00673  *         The key attributes, as a whole, are invalid.
00674  * \retval #PSA_ERROR_INVALID_ARGUMENT
00675  *         The key data is not correctly formatted.
00676  * \retval #PSA_ERROR_INVALID_ARGUMENT
00677  *         The size in \p attributes is nonzero and does not match the size
00678  *         of the key data.
00679  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00680  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
00681  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00682  * \retval #PSA_ERROR_STORAGE_FAILURE
00683  * \retval #PSA_ERROR_HARDWARE_FAILURE
00684  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00685  * \retval #PSA_ERROR_BAD_STATE
00686  *         The library has not been previously initialized by psa_crypto_init().
00687  *         It is implementation-dependent whether a failure to initialize
00688  *         results in this error code.
00689  */
00690 psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
00691                             const uint8_t *data,
00692                             size_t data_length,
00693                             psa_key_handle_t *handle);
00694 
00695 
00696 
00697 /**
00698  * \brief Export a key in binary format.
00699  *
00700  * The output of this function can be passed to psa_import_key() to
00701  * create an equivalent object.
00702  *
00703  * If the implementation of psa_import_key() supports other formats
00704  * beyond the format specified here, the output from psa_export_key()
00705  * must use the representation specified here, not the original
00706  * representation.
00707  *
00708  * For standard key types, the output format is as follows:
00709  *
00710  * - For symmetric keys (including MAC keys), the format is the
00711  *   raw bytes of the key.
00712  * - For DES, the key data consists of 8 bytes. The parity bits must be
00713  *   correct.
00714  * - For Triple-DES, the format is the concatenation of the
00715  *   two or three DES keys.
00716  * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
00717  *   is the non-encrypted DER encoding of the representation defined by
00718  *   PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
00719  *   ```
00720  *   RSAPrivateKey ::= SEQUENCE {
00721  *       version             INTEGER,  -- must be 0
00722  *       modulus             INTEGER,  -- n
00723  *       publicExponent      INTEGER,  -- e
00724  *       privateExponent     INTEGER,  -- d
00725  *       prime1              INTEGER,  -- p
00726  *       prime2              INTEGER,  -- q
00727  *       exponent1           INTEGER,  -- d mod (p-1)
00728  *       exponent2           INTEGER,  -- d mod (q-1)
00729  *       coefficient         INTEGER,  -- (inverse of q) mod p
00730  *   }
00731  *   ```
00732  * - For elliptic curve key pairs (key types for which
00733  *   #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
00734  *   a representation of the private value as a `ceiling(m/8)`-byte string
00735  *   where `m` is the bit size associated with the curve, i.e. the bit size
00736  *   of the order of the curve's coordinate field. This byte string is
00737  *   in little-endian order for Montgomery curves (curve types
00738  *   `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
00739  *   curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
00740  *   and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
00741  *   This is the content of the `privateKey` field of the `ECPrivateKey`
00742  *   format defined by RFC 5915.
00743  * - For Diffie-Hellman key exchange key pairs (key types for which
00744  *   #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
00745  *   format is the representation of the private key `x` as a big-endian byte
00746  *   string. The length of the byte string is the private key size in bytes
00747  *   (leading zeroes are not stripped).
00748  * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
00749  *   true), the format is the same as for psa_export_public_key().
00750  *
00751  * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
00752  *
00753  * \param handle            Handle to the key to export.
00754  * \param[out] data         Buffer where the key data is to be written.
00755  * \param data_size         Size of the \p data buffer in bytes.
00756  * \param[out] data_length  On success, the number of bytes
00757  *                          that make up the key data.
00758  *
00759  * \retval #PSA_SUCCESS
00760  * \retval #PSA_ERROR_INVALID_HANDLE
00761  * \retval #PSA_ERROR_NOT_PERMITTED
00762  *         The key does not have the #PSA_KEY_USAGE_EXPORT flag.
00763  * \retval #PSA_ERROR_NOT_SUPPORTED
00764  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
00765  *         The size of the \p data buffer is too small. You can determine a
00766  *         sufficient buffer size by calling
00767  *         #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
00768  *         where \c type is the key type
00769  *         and \c bits is the key size in bits.
00770  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00771  * \retval #PSA_ERROR_HARDWARE_FAILURE
00772  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00773  * \retval #PSA_ERROR_STORAGE_FAILURE
00774  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00775  * \retval #PSA_ERROR_BAD_STATE
00776  *         The library has not been previously initialized by psa_crypto_init().
00777  *         It is implementation-dependent whether a failure to initialize
00778  *         results in this error code.
00779  */
00780 psa_status_t psa_export_key(psa_key_handle_t handle,
00781                             uint8_t *data,
00782                             size_t data_size,
00783                             size_t *data_length);
00784 
00785 /**
00786  * \brief Export a public key or the public part of a key pair in binary format.
00787  *
00788  * The output of this function can be passed to psa_import_key() to
00789  * create an object that is equivalent to the public key.
00790  *
00791  * This specification supports a single format for each key type.
00792  * Implementations may support other formats as long as the standard
00793  * format is supported. Implementations that support other formats
00794  * should ensure that the formats are clearly unambiguous so as to
00795  * minimize the risk that an invalid input is accidentally interpreted
00796  * according to a different format.
00797  *
00798  * For standard key types, the output format is as follows:
00799  * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
00800  *   the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
00801  *   ```
00802  *   RSAPublicKey ::= SEQUENCE {
00803  *      modulus            INTEGER,    -- n
00804  *      publicExponent     INTEGER  }  -- e
00805  *   ```
00806  * - For elliptic curve public keys (key types for which
00807  *   #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
00808  *   representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
00809  *   Let `m` be the bit size associated with the curve, i.e. the bit size of
00810  *   `q` for a curve over `F_q`. The representation consists of:
00811  *      - The byte 0x04;
00812  *      - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
00813  *      - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
00814  * - For Diffie-Hellman key exchange public keys (key types for which
00815  *   #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
00816  *   the format is the representation of the public key `y = g^x mod p` as a
00817  *   big-endian byte string. The length of the byte string is the length of the
00818  *   base prime `p` in bytes.
00819  *
00820  * Exporting a public key object or the public part of a key pair is
00821  * always permitted, regardless of the key's usage flags.
00822  *
00823  * \param handle            Handle to the key to export.
00824  * \param[out] data         Buffer where the key data is to be written.
00825  * \param data_size         Size of the \p data buffer in bytes.
00826  * \param[out] data_length  On success, the number of bytes
00827  *                          that make up the key data.
00828  *
00829  * \retval #PSA_SUCCESS
00830  * \retval #PSA_ERROR_INVALID_HANDLE
00831  * \retval #PSA_ERROR_INVALID_ARGUMENT
00832  *         The key is neither a public key nor a key pair.
00833  * \retval #PSA_ERROR_NOT_SUPPORTED
00834  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
00835  *         The size of the \p data buffer is too small. You can determine a
00836  *         sufficient buffer size by calling
00837  *         #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
00838  *         where \c type is the key type
00839  *         and \c bits is the key size in bits.
00840  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00841  * \retval #PSA_ERROR_HARDWARE_FAILURE
00842  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00843  * \retval #PSA_ERROR_STORAGE_FAILURE
00844  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00845  * \retval #PSA_ERROR_BAD_STATE
00846  *         The library has not been previously initialized by psa_crypto_init().
00847  *         It is implementation-dependent whether a failure to initialize
00848  *         results in this error code.
00849  */
00850 psa_status_t psa_export_public_key(psa_key_handle_t handle,
00851                                    uint8_t *data,
00852                                    size_t data_size,
00853                                    size_t *data_length);
00854 
00855 
00856 
00857 /**@}*/
00858 
00859 /** \defgroup hash Message digests
00860  * @{
00861  */
00862 
00863 /** Calculate the hash (digest) of a message.
00864  *
00865  * \note To verify the hash of a message against an
00866  *       expected value, use psa_hash_compare() instead.
00867  *
00868  * \param alg               The hash algorithm to compute (\c PSA_ALG_XXX value
00869  *                          such that #PSA_ALG_IS_HASH(\p alg) is true).
00870  * \param[in] input         Buffer containing the message to hash.
00871  * \param input_length      Size of the \p input buffer in bytes.
00872  * \param[out] hash         Buffer where the hash is to be written.
00873  * \param hash_size         Size of the \p hash buffer in bytes.
00874  * \param[out] hash_length  On success, the number of bytes
00875  *                          that make up the hash value. This is always
00876  *                          #PSA_HASH_SIZE(\p alg).
00877  *
00878  * \retval #PSA_SUCCESS
00879  *         Success.
00880  * \retval #PSA_ERROR_NOT_SUPPORTED
00881  *         \p alg is not supported or is not a hash algorithm.
00882  * \retval #PSA_ERROR_INVALID_ARGUMENT
00883  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
00884  *         \p hash_size is too small
00885  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00886  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00887  * \retval #PSA_ERROR_HARDWARE_FAILURE
00888  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00889  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00890  * \retval #PSA_ERROR_BAD_STATE
00891  *         The library has not been previously initialized by psa_crypto_init().
00892  *         It is implementation-dependent whether a failure to initialize
00893  *         results in this error code.
00894  */
00895 psa_status_t psa_hash_compute(psa_algorithm_t alg,
00896                               const uint8_t *input,
00897                               size_t input_length,
00898                               uint8_t *hash,
00899                               size_t hash_size,
00900                               size_t *hash_length);
00901 
00902 /** Calculate the hash (digest) of a message and compare it with a
00903  * reference value.
00904  *
00905  * \param alg               The hash algorithm to compute (\c PSA_ALG_XXX value
00906  *                          such that #PSA_ALG_IS_HASH(\p alg) is true).
00907  * \param[in] input         Buffer containing the message to hash.
00908  * \param input_length      Size of the \p input buffer in bytes.
00909  * \param[out] hash         Buffer containing the expected hash value.
00910  * \param hash_length       Size of the \p hash buffer in bytes.
00911  *
00912  * \retval #PSA_SUCCESS
00913  *         The expected hash is identical to the actual hash of the input.
00914  * \retval #PSA_ERROR_INVALID_SIGNATURE
00915  *         The hash of the message was calculated successfully, but it
00916  *         differs from the expected hash.
00917  * \retval #PSA_ERROR_NOT_SUPPORTED
00918  *         \p alg is not supported or is not a hash algorithm.
00919  * \retval #PSA_ERROR_INVALID_ARGUMENT
00920  *         \p input_length or \p hash_length do not match the hash size for \p alg
00921  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00922  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
00923  * \retval #PSA_ERROR_HARDWARE_FAILURE
00924  * \retval #PSA_ERROR_CORRUPTION_DETECTED
00925  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
00926  * \retval #PSA_ERROR_BAD_STATE
00927  *         The library has not been previously initialized by psa_crypto_init().
00928  *         It is implementation-dependent whether a failure to initialize
00929  *         results in this error code.
00930  */
00931 psa_status_t psa_hash_compare(psa_algorithm_t alg,
00932                               const uint8_t *input,
00933                               size_t input_length,
00934                               const uint8_t *hash,
00935                               const size_t hash_length);
00936 
00937 /** The type of the state data structure for multipart hash operations.
00938  *
00939  * Before calling any function on a hash operation object, the application must
00940  * initialize it by any of the following means:
00941  * - Set the structure to all-bits-zero, for example:
00942  *   \code
00943  *   psa_hash_operation_t operation;
00944  *   memset(&operation, 0, sizeof(operation));
00945  *   \endcode
00946  * - Initialize the structure to logical zero values, for example:
00947  *   \code
00948  *   psa_hash_operation_t operation = {0};
00949  *   \endcode
00950  * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
00951  *   for example:
00952  *   \code
00953  *   psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
00954  *   \endcode
00955  * - Assign the result of the function psa_hash_operation_init()
00956  *   to the structure, for example:
00957  *   \code
00958  *   psa_hash_operation_t operation;
00959  *   operation = psa_hash_operation_init();
00960  *   \endcode
00961  *
00962  * This is an implementation-defined \c struct. Applications should not
00963  * make any assumptions about the content of this structure except
00964  * as directed by the documentation of a specific implementation. */
00965 typedef struct psa_hash_operation_s psa_hash_operation_t;
00966 
00967 /** \def PSA_HASH_OPERATION_INIT
00968  *
00969  * This macro returns a suitable initializer for a hash operation object
00970  * of type #psa_hash_operation_t.
00971  */
00972 #ifdef __DOXYGEN_ONLY__
00973 /* This is an example definition for documentation purposes.
00974  * Implementations should define a suitable value in `crypto_struct.h`.
00975  */
00976 #define PSA_HASH_OPERATION_INIT {0}
00977 #endif
00978 
00979 /** Return an initial value for a hash operation object.
00980  */
00981 static psa_hash_operation_t psa_hash_operation_init(void);
00982 
00983 /** Set up a multipart hash operation.
00984  *
00985  * The sequence of operations to calculate a hash (message digest)
00986  * is as follows:
00987  * -# Allocate an operation object which will be passed to all the functions
00988  *    listed here.
00989  * -# Initialize the operation object with one of the methods described in the
00990  *    documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT.
00991  * -# Call psa_hash_setup() to specify the algorithm.
00992  * -# Call psa_hash_update() zero, one or more times, passing a fragment
00993  *    of the message each time. The hash that is calculated is the hash
00994  *    of the concatenation of these messages in order.
00995  * -# To calculate the hash, call psa_hash_finish().
00996  *    To compare the hash with an expected value, call psa_hash_verify().
00997  *
00998  * If an error occurs at any step after a call to psa_hash_setup(), the
00999  * operation will need to be reset by a call to psa_hash_abort(). The
01000  * application may call psa_hash_abort() at any time after the operation
01001  * has been initialized.
01002  *
01003  * After a successful call to psa_hash_setup(), the application must
01004  * eventually terminate the operation. The following events terminate an
01005  * operation:
01006  * - A successful call to psa_hash_finish() or psa_hash_verify().
01007  * - A call to psa_hash_abort().
01008  *
01009  * \param[in,out] operation The operation object to set up. It must have
01010  *                          been initialized as per the documentation for
01011  *                          #psa_hash_operation_t and not yet in use.
01012  * \param alg               The hash algorithm to compute (\c PSA_ALG_XXX value
01013  *                          such that #PSA_ALG_IS_HASH(\p alg) is true).
01014  *
01015  * \retval #PSA_SUCCESS
01016  *         Success.
01017  * \retval #PSA_ERROR_NOT_SUPPORTED
01018  *         \p alg is not a supported hash algorithm.
01019  * \retval #PSA_ERROR_INVALID_ARGUMENT
01020  *         \p alg is not a hash algorithm.
01021  * \retval #PSA_ERROR_BAD_STATE
01022  *         The operation state is not valid (it must be inactive).
01023  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01024  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01025  * \retval #PSA_ERROR_HARDWARE_FAILURE
01026  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01027  * \retval #PSA_ERROR_BAD_STATE
01028  *         The library has not been previously initialized by psa_crypto_init().
01029  *         It is implementation-dependent whether a failure to initialize
01030  *         results in this error code.
01031  */
01032 psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
01033                             psa_algorithm_t alg);
01034 
01035 /** Add a message fragment to a multipart hash operation.
01036  *
01037  * The application must call psa_hash_setup() before calling this function.
01038  *
01039  * If this function returns an error status, the operation enters an error
01040  * state and must be aborted by calling psa_hash_abort().
01041  *
01042  * \param[in,out] operation Active hash operation.
01043  * \param[in] input         Buffer containing the message fragment to hash.
01044  * \param input_length      Size of the \p input buffer in bytes.
01045  *
01046  * \retval #PSA_SUCCESS
01047  *         Success.
01048  * \retval #PSA_ERROR_BAD_STATE
01049  *         The operation state is not valid (it muct be active).
01050  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01051  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01052  * \retval #PSA_ERROR_HARDWARE_FAILURE
01053  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01054  * \retval #PSA_ERROR_BAD_STATE
01055  *         The library has not been previously initialized by psa_crypto_init().
01056  *         It is implementation-dependent whether a failure to initialize
01057  *         results in this error code.
01058  */
01059 psa_status_t psa_hash_update(psa_hash_operation_t *operation,
01060                              const uint8_t *input,
01061                              size_t input_length);
01062 
01063 /** Finish the calculation of the hash of a message.
01064  *
01065  * The application must call psa_hash_setup() before calling this function.
01066  * This function calculates the hash of the message formed by concatenating
01067  * the inputs passed to preceding calls to psa_hash_update().
01068  *
01069  * When this function returns successfuly, the operation becomes inactive.
01070  * If this function returns an error status, the operation enters an error
01071  * state and must be aborted by calling psa_hash_abort().
01072  *
01073  * \warning Applications should not call this function if they expect
01074  *          a specific value for the hash. Call psa_hash_verify() instead.
01075  *          Beware that comparing integrity or authenticity data such as
01076  *          hash values with a function such as \c memcmp is risky
01077  *          because the time taken by the comparison may leak information
01078  *          about the hashed data which could allow an attacker to guess
01079  *          a valid hash and thereby bypass security controls.
01080  *
01081  * \param[in,out] operation     Active hash operation.
01082  * \param[out] hash             Buffer where the hash is to be written.
01083  * \param hash_size             Size of the \p hash buffer in bytes.
01084  * \param[out] hash_length      On success, the number of bytes
01085  *                              that make up the hash value. This is always
01086  *                              #PSA_HASH_SIZE(\c alg) where \c alg is the
01087  *                              hash algorithm that is calculated.
01088  *
01089  * \retval #PSA_SUCCESS
01090  *         Success.
01091  * \retval #PSA_ERROR_BAD_STATE
01092  *         The operation state is not valid (it must be active).
01093  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01094  *         The size of the \p hash buffer is too small. You can determine a
01095  *         sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
01096  *         where \c alg is the hash algorithm that is calculated.
01097  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01098  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01099  * \retval #PSA_ERROR_HARDWARE_FAILURE
01100  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01101  * \retval #PSA_ERROR_BAD_STATE
01102  *         The library has not been previously initialized by psa_crypto_init().
01103  *         It is implementation-dependent whether a failure to initialize
01104  *         results in this error code.
01105  */
01106 psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
01107                              uint8_t *hash,
01108                              size_t hash_size,
01109                              size_t *hash_length);
01110 
01111 /** Finish the calculation of the hash of a message and compare it with
01112  * an expected value.
01113  *
01114  * The application must call psa_hash_setup() before calling this function.
01115  * This function calculates the hash of the message formed by concatenating
01116  * the inputs passed to preceding calls to psa_hash_update(). It then
01117  * compares the calculated hash with the expected hash passed as a
01118  * parameter to this function.
01119  *
01120  * When this function returns successfuly, the operation becomes inactive.
01121  * If this function returns an error status, the operation enters an error
01122  * state and must be aborted by calling psa_hash_abort().
01123  *
01124  * \note Implementations shall make the best effort to ensure that the
01125  * comparison between the actual hash and the expected hash is performed
01126  * in constant time.
01127  *
01128  * \param[in,out] operation     Active hash operation.
01129  * \param[in] hash              Buffer containing the expected hash value.
01130  * \param hash_length           Size of the \p hash buffer in bytes.
01131  *
01132  * \retval #PSA_SUCCESS
01133  *         The expected hash is identical to the actual hash of the message.
01134  * \retval #PSA_ERROR_INVALID_SIGNATURE
01135  *         The hash of the message was calculated successfully, but it
01136  *         differs from the expected hash.
01137  * \retval #PSA_ERROR_BAD_STATE
01138  *         The operation state is not valid (it must be active).
01139  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01140  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01141  * \retval #PSA_ERROR_HARDWARE_FAILURE
01142  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01143  * \retval #PSA_ERROR_BAD_STATE
01144  *         The library has not been previously initialized by psa_crypto_init().
01145  *         It is implementation-dependent whether a failure to initialize
01146  *         results in this error code.
01147  */
01148 psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
01149                              const uint8_t *hash,
01150                              size_t hash_length);
01151 
01152 /** Abort a hash operation.
01153  *
01154  * Aborting an operation frees all associated resources except for the
01155  * \p operation structure itself. Once aborted, the operation object
01156  * can be reused for another operation by calling
01157  * psa_hash_setup() again.
01158  *
01159  * You may call this function any time after the operation object has
01160  * been initialized by one of the methods described in #psa_hash_operation_t.
01161  *
01162  * In particular, calling psa_hash_abort() after the operation has been
01163  * terminated by a call to psa_hash_abort(), psa_hash_finish() or
01164  * psa_hash_verify() is safe and has no effect.
01165  *
01166  * \param[in,out] operation     Initialized hash operation.
01167  *
01168  * \retval #PSA_SUCCESS
01169  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01170  * \retval #PSA_ERROR_HARDWARE_FAILURE
01171  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01172  * \retval #PSA_ERROR_BAD_STATE
01173  *         The library has not been previously initialized by psa_crypto_init().
01174  *         It is implementation-dependent whether a failure to initialize
01175  *         results in this error code.
01176  */
01177 psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
01178 
01179 /** Clone a hash operation.
01180  *
01181  * This function copies the state of an ongoing hash operation to
01182  * a new operation object. In other words, this function is equivalent
01183  * to calling psa_hash_setup() on \p target_operation with the same
01184  * algorithm that \p source_operation was set up for, then
01185  * psa_hash_update() on \p target_operation with the same input that
01186  * that was passed to \p source_operation. After this function returns, the
01187  * two objects are independent, i.e. subsequent calls involving one of
01188  * the objects do not affect the other object.
01189  *
01190  * \param[in] source_operation      The active hash operation to clone.
01191  * \param[in,out] target_operation  The operation object to set up.
01192  *                                  It must be initialized but not active.
01193  *
01194  * \retval #PSA_SUCCESS
01195  * \retval #PSA_ERROR_BAD_STATE
01196  *         The \p source_operation state is not valid (it must be active).
01197  * \retval #PSA_ERROR_BAD_STATE
01198  *         The \p target_operation state is not valid (it must be inactive).
01199  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01200  * \retval #PSA_ERROR_HARDWARE_FAILURE
01201  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01202  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01203  * \retval #PSA_ERROR_BAD_STATE
01204  *         The library has not been previously initialized by psa_crypto_init().
01205  *         It is implementation-dependent whether a failure to initialize
01206  *         results in this error code.
01207  */
01208 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
01209                             psa_hash_operation_t *target_operation);
01210 
01211 /**@}*/
01212 
01213 /** \defgroup MAC Message authentication codes
01214  * @{
01215  */
01216 
01217 /** Calculate the MAC (message authentication code) of a message.
01218  *
01219  * \note To verify the MAC of a message against an
01220  *       expected value, use psa_mac_verify() instead.
01221  *       Beware that comparing integrity or authenticity data such as
01222  *       MAC values with a function such as \c memcmp is risky
01223  *       because the time taken by the comparison may leak information
01224  *       about the MAC value which could allow an attacker to guess
01225  *       a valid MAC and thereby bypass security controls.
01226  *
01227  * \param handle            Handle to the key to use for the operation.
01228  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
01229  *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
01230  * \param[in] input         Buffer containing the input message.
01231  * \param input_length      Size of the \p input buffer in bytes.
01232  * \param[out] mac          Buffer where the MAC value is to be written.
01233  * \param mac_size          Size of the \p mac buffer in bytes.
01234  * \param[out] mac_length   On success, the number of bytes
01235  *                          that make up the MAC value.
01236  *
01237  * \retval #PSA_SUCCESS
01238  *         Success.
01239  * \retval #PSA_ERROR_INVALID_HANDLE
01240  * \retval #PSA_ERROR_NOT_PERMITTED
01241  * \retval #PSA_ERROR_INVALID_ARGUMENT
01242  *         \p handle is not compatible with \p alg.
01243  * \retval #PSA_ERROR_NOT_SUPPORTED
01244  *         \p alg is not supported or is not a MAC algorithm.
01245  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01246  *         \p mac_size is too small
01247  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01248  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01249  * \retval #PSA_ERROR_HARDWARE_FAILURE
01250  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01251  * \retval #PSA_ERROR_STORAGE_FAILURE
01252  *         The key could not be retrieved from storage.
01253  * \retval #PSA_ERROR_BAD_STATE
01254  *         The library has not been previously initialized by psa_crypto_init().
01255  *         It is implementation-dependent whether a failure to initialize
01256  *         results in this error code.
01257  */
01258 psa_status_t psa_mac_compute(psa_key_handle_t handle,
01259                              psa_algorithm_t alg,
01260                              const uint8_t *input,
01261                              size_t input_length,
01262                              uint8_t *mac,
01263                              size_t mac_size,
01264                              size_t *mac_length);
01265 
01266 /** Calculate the MAC of a message and compare it with a reference value.
01267  *
01268  * \param handle            Handle to the key to use for the operation.
01269  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
01270  *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
01271  * \param[in] input         Buffer containing the input message.
01272  * \param input_length      Size of the \p input buffer in bytes.
01273  * \param[out] mac          Buffer containing the expected MAC value.
01274  * \param mac_length        Size of the \p mac buffer in bytes.
01275  *
01276  * \retval #PSA_SUCCESS
01277  *         The expected MAC is identical to the actual MAC of the input.
01278  * \retval #PSA_ERROR_INVALID_SIGNATURE
01279  *         The MAC of the message was calculated successfully, but it
01280  *         differs from the expected value.
01281  * \retval #PSA_ERROR_INVALID_HANDLE
01282  * \retval #PSA_ERROR_NOT_PERMITTED
01283  * \retval #PSA_ERROR_INVALID_ARGUMENT
01284  *         \p handle is not compatible with \p alg.
01285  * \retval #PSA_ERROR_NOT_SUPPORTED
01286  *         \p alg is not supported or is not a MAC algorithm.
01287  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01288  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01289  * \retval #PSA_ERROR_HARDWARE_FAILURE
01290  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01291  * \retval #PSA_ERROR_STORAGE_FAILURE
01292  *         The key could not be retrieved from storage.
01293  * \retval #PSA_ERROR_BAD_STATE
01294  *         The library has not been previously initialized by psa_crypto_init().
01295  *         It is implementation-dependent whether a failure to initialize
01296  *         results in this error code.
01297  */
01298 psa_status_t psa_mac_verify(psa_key_handle_t handle,
01299                             psa_algorithm_t alg,
01300                             const uint8_t *input,
01301                             size_t input_length,
01302                             const uint8_t *mac,
01303                             const size_t mac_length);
01304 
01305 /** The type of the state data structure for multipart MAC operations.
01306  *
01307  * Before calling any function on a MAC operation object, the application must
01308  * initialize it by any of the following means:
01309  * - Set the structure to all-bits-zero, for example:
01310  *   \code
01311  *   psa_mac_operation_t operation;
01312  *   memset(&operation, 0, sizeof(operation));
01313  *   \endcode
01314  * - Initialize the structure to logical zero values, for example:
01315  *   \code
01316  *   psa_mac_operation_t operation = {0};
01317  *   \endcode
01318  * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
01319  *   for example:
01320  *   \code
01321  *   psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
01322  *   \endcode
01323  * - Assign the result of the function psa_mac_operation_init()
01324  *   to the structure, for example:
01325  *   \code
01326  *   psa_mac_operation_t operation;
01327  *   operation = psa_mac_operation_init();
01328  *   \endcode
01329  *
01330  * This is an implementation-defined \c struct. Applications should not
01331  * make any assumptions about the content of this structure except
01332  * as directed by the documentation of a specific implementation. */
01333 typedef struct psa_mac_operation_s psa_mac_operation_t;
01334 
01335 /** \def PSA_MAC_OPERATION_INIT
01336  *
01337  * This macro returns a suitable initializer for a MAC operation object of type
01338  * #psa_mac_operation_t.
01339  */
01340 #ifdef __DOXYGEN_ONLY__
01341 /* This is an example definition for documentation purposes.
01342  * Implementations should define a suitable value in `crypto_struct.h`.
01343  */
01344 #define PSA_MAC_OPERATION_INIT {0}
01345 #endif
01346 
01347 /** Return an initial value for a MAC operation object.
01348  */
01349 static psa_mac_operation_t psa_mac_operation_init(void);
01350 
01351 /** Set up a multipart MAC calculation operation.
01352  *
01353  * This function sets up the calculation of the MAC
01354  * (message authentication code) of a byte string.
01355  * To verify the MAC of a message against an
01356  * expected value, use psa_mac_verify_setup() instead.
01357  *
01358  * The sequence of operations to calculate a MAC is as follows:
01359  * -# Allocate an operation object which will be passed to all the functions
01360  *    listed here.
01361  * -# Initialize the operation object with one of the methods described in the
01362  *    documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
01363  * -# Call psa_mac_sign_setup() to specify the algorithm and key.
01364  * -# Call psa_mac_update() zero, one or more times, passing a fragment
01365  *    of the message each time. The MAC that is calculated is the MAC
01366  *    of the concatenation of these messages in order.
01367  * -# At the end of the message, call psa_mac_sign_finish() to finish
01368  *    calculating the MAC value and retrieve it.
01369  *
01370  * If an error occurs at any step after a call to psa_mac_sign_setup(), the
01371  * operation will need to be reset by a call to psa_mac_abort(). The
01372  * application may call psa_mac_abort() at any time after the operation
01373  * has been initialized.
01374  *
01375  * After a successful call to psa_mac_sign_setup(), the application must
01376  * eventually terminate the operation through one of the following methods:
01377  * - A successful call to psa_mac_sign_finish().
01378  * - A call to psa_mac_abort().
01379  *
01380  * \param[in,out] operation The operation object to set up. It must have
01381  *                          been initialized as per the documentation for
01382  *                          #psa_mac_operation_t and not yet in use.
01383  * \param handle            Handle to the key to use for the operation.
01384  *                          It must remain valid until the operation
01385  *                          terminates.
01386  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
01387  *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
01388  *
01389  * \retval #PSA_SUCCESS
01390  *         Success.
01391  * \retval #PSA_ERROR_INVALID_HANDLE
01392  * \retval #PSA_ERROR_NOT_PERMITTED
01393  * \retval #PSA_ERROR_INVALID_ARGUMENT
01394  *         \p handle is not compatible with \p alg.
01395  * \retval #PSA_ERROR_NOT_SUPPORTED
01396  *         \p alg is not supported or is not a MAC algorithm.
01397  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01398  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01399  * \retval #PSA_ERROR_HARDWARE_FAILURE
01400  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01401  * \retval #PSA_ERROR_STORAGE_FAILURE
01402  *         The key could not be retrieved from storage.
01403  * \retval #PSA_ERROR_BAD_STATE
01404  *         The operation state is not valid (it must be inactive).
01405  * \retval #PSA_ERROR_BAD_STATE
01406  *         The library has not been previously initialized by psa_crypto_init().
01407  *         It is implementation-dependent whether a failure to initialize
01408  *         results in this error code.
01409  */
01410 psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
01411                                 psa_key_handle_t handle,
01412                                 psa_algorithm_t alg);
01413 
01414 /** Set up a multipart MAC verification operation.
01415  *
01416  * This function sets up the verification of the MAC
01417  * (message authentication code) of a byte string against an expected value.
01418  *
01419  * The sequence of operations to verify a MAC is as follows:
01420  * -# Allocate an operation object which will be passed to all the functions
01421  *    listed here.
01422  * -# Initialize the operation object with one of the methods described in the
01423  *    documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
01424  * -# Call psa_mac_verify_setup() to specify the algorithm and key.
01425  * -# Call psa_mac_update() zero, one or more times, passing a fragment
01426  *    of the message each time. The MAC that is calculated is the MAC
01427  *    of the concatenation of these messages in order.
01428  * -# At the end of the message, call psa_mac_verify_finish() to finish
01429  *    calculating the actual MAC of the message and verify it against
01430  *    the expected value.
01431  *
01432  * If an error occurs at any step after a call to psa_mac_verify_setup(), the
01433  * operation will need to be reset by a call to psa_mac_abort(). The
01434  * application may call psa_mac_abort() at any time after the operation
01435  * has been initialized.
01436  *
01437  * After a successful call to psa_mac_verify_setup(), the application must
01438  * eventually terminate the operation through one of the following methods:
01439  * - A successful call to psa_mac_verify_finish().
01440  * - A call to psa_mac_abort().
01441  *
01442  * \param[in,out] operation The operation object to set up. It must have
01443  *                          been initialized as per the documentation for
01444  *                          #psa_mac_operation_t and not yet in use.
01445  * \param handle            Handle to the key to use for the operation.
01446  *                          It must remain valid until the operation
01447  *                          terminates.
01448  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
01449  *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
01450  *
01451  * \retval #PSA_SUCCESS
01452  *         Success.
01453  * \retval #PSA_ERROR_INVALID_HANDLE
01454  * \retval #PSA_ERROR_NOT_PERMITTED
01455  * \retval #PSA_ERROR_INVALID_ARGUMENT
01456  *         \c key is not compatible with \c alg.
01457  * \retval #PSA_ERROR_NOT_SUPPORTED
01458  *         \c alg is not supported or is not a MAC algorithm.
01459  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01460  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01461  * \retval #PSA_ERROR_HARDWARE_FAILURE
01462  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01463  * \retval #PSA_ERROR_STORAGE_FAILURE
01464  *         The key could not be retrieved from storage
01465  * \retval #PSA_ERROR_BAD_STATE
01466  *         The operation state is not valid (it must be inactive).
01467  * \retval #PSA_ERROR_BAD_STATE
01468  *         The library has not been previously initialized by psa_crypto_init().
01469  *         It is implementation-dependent whether a failure to initialize
01470  *         results in this error code.
01471  */
01472 psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
01473                                   psa_key_handle_t handle,
01474                                   psa_algorithm_t alg);
01475 
01476 /** Add a message fragment to a multipart MAC operation.
01477  *
01478  * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
01479  * before calling this function.
01480  *
01481  * If this function returns an error status, the operation enters an error
01482  * state and must be aborted by calling psa_mac_abort().
01483  *
01484  * \param[in,out] operation Active MAC operation.
01485  * \param[in] input         Buffer containing the message fragment to add to
01486  *                          the MAC calculation.
01487  * \param input_length      Size of the \p input buffer in bytes.
01488  *
01489  * \retval #PSA_SUCCESS
01490  *         Success.
01491  * \retval #PSA_ERROR_BAD_STATE
01492  *         The operation state is not valid (it must be active).
01493  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01494  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01495  * \retval #PSA_ERROR_HARDWARE_FAILURE
01496  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01497  * \retval #PSA_ERROR_STORAGE_FAILURE
01498  * \retval #PSA_ERROR_BAD_STATE
01499  *         The library has not been previously initialized by psa_crypto_init().
01500  *         It is implementation-dependent whether a failure to initialize
01501  *         results in this error code.
01502  */
01503 psa_status_t psa_mac_update(psa_mac_operation_t *operation,
01504                             const uint8_t *input,
01505                             size_t input_length);
01506 
01507 /** Finish the calculation of the MAC of a message.
01508  *
01509  * The application must call psa_mac_sign_setup() before calling this function.
01510  * This function calculates the MAC of the message formed by concatenating
01511  * the inputs passed to preceding calls to psa_mac_update().
01512  *
01513  * When this function returns successfuly, the operation becomes inactive.
01514  * If this function returns an error status, the operation enters an error
01515  * state and must be aborted by calling psa_mac_abort().
01516  *
01517  * \warning Applications should not call this function if they expect
01518  *          a specific value for the MAC. Call psa_mac_verify_finish() instead.
01519  *          Beware that comparing integrity or authenticity data such as
01520  *          MAC values with a function such as \c memcmp is risky
01521  *          because the time taken by the comparison may leak information
01522  *          about the MAC value which could allow an attacker to guess
01523  *          a valid MAC and thereby bypass security controls.
01524  *
01525  * \param[in,out] operation Active MAC operation.
01526  * \param[out] mac          Buffer where the MAC value is to be written.
01527  * \param mac_size          Size of the \p mac buffer in bytes.
01528  * \param[out] mac_length   On success, the number of bytes
01529  *                          that make up the MAC value. This is always
01530  *                          #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
01531  *                          where \c key_type and \c key_bits are the type and
01532  *                          bit-size respectively of the key and \c alg is the
01533  *                          MAC algorithm that is calculated.
01534  *
01535  * \retval #PSA_SUCCESS
01536  *         Success.
01537  * \retval #PSA_ERROR_BAD_STATE
01538  *         The operation state is not valid (it must be an active mac sign
01539  *         operation).
01540  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01541  *         The size of the \p mac buffer is too small. You can determine a
01542  *         sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
01543  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01544  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01545  * \retval #PSA_ERROR_HARDWARE_FAILURE
01546  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01547  * \retval #PSA_ERROR_STORAGE_FAILURE
01548  * \retval #PSA_ERROR_BAD_STATE
01549  *         The library has not been previously initialized by psa_crypto_init().
01550  *         It is implementation-dependent whether a failure to initialize
01551  *         results in this error code.
01552  */
01553 psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
01554                                  uint8_t *mac,
01555                                  size_t mac_size,
01556                                  size_t *mac_length);
01557 
01558 /** Finish the calculation of the MAC of a message and compare it with
01559  * an expected value.
01560  *
01561  * The application must call psa_mac_verify_setup() before calling this function.
01562  * This function calculates the MAC of the message formed by concatenating
01563  * the inputs passed to preceding calls to psa_mac_update(). It then
01564  * compares the calculated MAC with the expected MAC passed as a
01565  * parameter to this function.
01566  *
01567  * When this function returns successfuly, the operation becomes inactive.
01568  * If this function returns an error status, the operation enters an error
01569  * state and must be aborted by calling psa_mac_abort().
01570  *
01571  * \note Implementations shall make the best effort to ensure that the
01572  * comparison between the actual MAC and the expected MAC is performed
01573  * in constant time.
01574  *
01575  * \param[in,out] operation Active MAC operation.
01576  * \param[in] mac           Buffer containing the expected MAC value.
01577  * \param mac_length        Size of the \p mac buffer in bytes.
01578  *
01579  * \retval #PSA_SUCCESS
01580  *         The expected MAC is identical to the actual MAC of the message.
01581  * \retval #PSA_ERROR_INVALID_SIGNATURE
01582  *         The MAC of the message was calculated successfully, but it
01583  *         differs from the expected MAC.
01584  * \retval #PSA_ERROR_BAD_STATE
01585  *         The operation state is not valid (it must be an active mac verify
01586  *         operation).
01587  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01588  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01589  * \retval #PSA_ERROR_HARDWARE_FAILURE
01590  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01591  * \retval #PSA_ERROR_STORAGE_FAILURE
01592  * \retval #PSA_ERROR_BAD_STATE
01593  *         The library has not been previously initialized by psa_crypto_init().
01594  *         It is implementation-dependent whether a failure to initialize
01595  *         results in this error code.
01596  */
01597 psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
01598                                    const uint8_t *mac,
01599                                    size_t mac_length);
01600 
01601 /** Abort a MAC operation.
01602  *
01603  * Aborting an operation frees all associated resources except for the
01604  * \p operation structure itself. Once aborted, the operation object
01605  * can be reused for another operation by calling
01606  * psa_mac_sign_setup() or psa_mac_verify_setup() again.
01607  *
01608  * You may call this function any time after the operation object has
01609  * been initialized by one of the methods described in #psa_mac_operation_t.
01610  *
01611  * In particular, calling psa_mac_abort() after the operation has been
01612  * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
01613  * psa_mac_verify_finish() is safe and has no effect.
01614  *
01615  * \param[in,out] operation Initialized MAC operation.
01616  *
01617  * \retval #PSA_SUCCESS
01618  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01619  * \retval #PSA_ERROR_HARDWARE_FAILURE
01620  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01621  * \retval #PSA_ERROR_BAD_STATE
01622  *         The library has not been previously initialized by psa_crypto_init().
01623  *         It is implementation-dependent whether a failure to initialize
01624  *         results in this error code.
01625  */
01626 psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
01627 
01628 /**@}*/
01629 
01630 /** \defgroup cipher Symmetric ciphers
01631  * @{
01632  */
01633 
01634 /** Encrypt a message using a symmetric cipher.
01635  *
01636  * This function encrypts a message with a random IV (initialization
01637  * vector). Use the multipart operation interface with a
01638  * #psa_cipher_operation_t object to provide other forms of IV.
01639  *
01640  * \param handle                Handle to the key to use for the operation.
01641  *                              It must remain valid until the operation
01642  *                              terminates.
01643  * \param alg                   The cipher algorithm to compute
01644  *                              (\c PSA_ALG_XXX value such that
01645  *                              #PSA_ALG_IS_CIPHER(\p alg) is true).
01646  * \param[in] input             Buffer containing the message to encrypt.
01647  * \param input_length          Size of the \p input buffer in bytes.
01648  * \param[out] output           Buffer where the output is to be written.
01649  *                              The output contains the IV followed by
01650  *                              the ciphertext proper.
01651  * \param output_size           Size of the \p output buffer in bytes.
01652  * \param[out] output_length    On success, the number of bytes
01653  *                              that make up the output.
01654  *
01655  * \retval #PSA_SUCCESS
01656  *         Success.
01657  * \retval #PSA_ERROR_INVALID_HANDLE
01658  * \retval #PSA_ERROR_NOT_PERMITTED
01659  * \retval #PSA_ERROR_INVALID_ARGUMENT
01660  *         \p handle is not compatible with \p alg.
01661  * \retval #PSA_ERROR_NOT_SUPPORTED
01662  *         \p alg is not supported or is not a cipher algorithm.
01663  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01664  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01665  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01666  * \retval #PSA_ERROR_HARDWARE_FAILURE
01667  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01668  * \retval #PSA_ERROR_STORAGE_FAILURE
01669  * \retval #PSA_ERROR_BAD_STATE
01670  *         The library has not been previously initialized by psa_crypto_init().
01671  *         It is implementation-dependent whether a failure to initialize
01672  *         results in this error code.
01673  */
01674 psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
01675                                 psa_algorithm_t alg,
01676                                 const uint8_t *input,
01677                                 size_t input_length,
01678                                 uint8_t *output,
01679                                 size_t output_size,
01680                                 size_t *output_length);
01681 
01682 /** Decrypt a message using a symmetric cipher.
01683  *
01684  * This function decrypts a message encrypted with a symmetric cipher.
01685  *
01686  * \param handle                Handle to the key to use for the operation.
01687  *                              It must remain valid until the operation
01688  *                              terminates.
01689  * \param alg                   The cipher algorithm to compute
01690  *                              (\c PSA_ALG_XXX value such that
01691  *                              #PSA_ALG_IS_CIPHER(\p alg) is true).
01692  * \param[in] input             Buffer containing the message to decrypt.
01693  *                              This consists of the IV followed by the
01694  *                              ciphertext proper.
01695  * \param input_length          Size of the \p input buffer in bytes.
01696  * \param[out] output           Buffer where the plaintext is to be written.
01697  * \param output_size           Size of the \p output buffer in bytes.
01698  * \param[out] output_length    On success, the number of bytes
01699  *                              that make up the output.
01700  *
01701  * \retval #PSA_SUCCESS
01702  *         Success.
01703  * \retval #PSA_ERROR_INVALID_HANDLE
01704  * \retval #PSA_ERROR_NOT_PERMITTED
01705  * \retval #PSA_ERROR_INVALID_ARGUMENT
01706  *         \p handle is not compatible with \p alg.
01707  * \retval #PSA_ERROR_NOT_SUPPORTED
01708  *         \p alg is not supported or is not a cipher algorithm.
01709  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01710  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01711  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01712  * \retval #PSA_ERROR_HARDWARE_FAILURE
01713  * \retval #PSA_ERROR_STORAGE_FAILURE
01714  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01715  * \retval #PSA_ERROR_BAD_STATE
01716  *         The library has not been previously initialized by psa_crypto_init().
01717  *         It is implementation-dependent whether a failure to initialize
01718  *         results in this error code.
01719  */
01720 psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
01721                                 psa_algorithm_t alg,
01722                                 const uint8_t *input,
01723                                 size_t input_length,
01724                                 uint8_t *output,
01725                                 size_t output_size,
01726                                 size_t *output_length);
01727 
01728 /** The type of the state data structure for multipart cipher operations.
01729  *
01730  * Before calling any function on a cipher operation object, the application
01731  * must initialize it by any of the following means:
01732  * - Set the structure to all-bits-zero, for example:
01733  *   \code
01734  *   psa_cipher_operation_t operation;
01735  *   memset(&operation, 0, sizeof(operation));
01736  *   \endcode
01737  * - Initialize the structure to logical zero values, for example:
01738  *   \code
01739  *   psa_cipher_operation_t operation = {0};
01740  *   \endcode
01741  * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
01742  *   for example:
01743  *   \code
01744  *   psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
01745  *   \endcode
01746  * - Assign the result of the function psa_cipher_operation_init()
01747  *   to the structure, for example:
01748  *   \code
01749  *   psa_cipher_operation_t operation;
01750  *   operation = psa_cipher_operation_init();
01751  *   \endcode
01752  *
01753  * This is an implementation-defined \c struct. Applications should not
01754  * make any assumptions about the content of this structure except
01755  * as directed by the documentation of a specific implementation. */
01756 typedef struct psa_cipher_operation_s psa_cipher_operation_t;
01757 
01758 /** \def PSA_CIPHER_OPERATION_INIT
01759  *
01760  * This macro returns a suitable initializer for a cipher operation object of
01761  * type #psa_cipher_operation_t.
01762  */
01763 #ifdef __DOXYGEN_ONLY__
01764 /* This is an example definition for documentation purposes.
01765  * Implementations should define a suitable value in `crypto_struct.h`.
01766  */
01767 #define PSA_CIPHER_OPERATION_INIT {0}
01768 #endif
01769 
01770 /** Return an initial value for a cipher operation object.
01771  */
01772 static psa_cipher_operation_t psa_cipher_operation_init(void);
01773 
01774 /** Set the key for a multipart symmetric encryption operation.
01775  *
01776  * The sequence of operations to encrypt a message with a symmetric cipher
01777  * is as follows:
01778  * -# Allocate an operation object which will be passed to all the functions
01779  *    listed here.
01780  * -# Initialize the operation object with one of the methods described in the
01781  *    documentation for #psa_cipher_operation_t, e.g.
01782  *    #PSA_CIPHER_OPERATION_INIT.
01783  * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
01784  * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
01785  *    generate or set the IV (initialization vector). You should use
01786  *    psa_cipher_generate_iv() unless the protocol you are implementing
01787  *    requires a specific IV value.
01788  * -# Call psa_cipher_update() zero, one or more times, passing a fragment
01789  *    of the message each time.
01790  * -# Call psa_cipher_finish().
01791  *
01792  * If an error occurs at any step after a call to psa_cipher_encrypt_setup(),
01793  * the operation will need to be reset by a call to psa_cipher_abort(). The
01794  * application may call psa_cipher_abort() at any time after the operation
01795  * has been initialized.
01796  *
01797  * After a successful call to psa_cipher_encrypt_setup(), the application must
01798  * eventually terminate the operation. The following events terminate an
01799  * operation:
01800  * - A successful call to psa_cipher_finish().
01801  * - A call to psa_cipher_abort().
01802  *
01803  * \param[in,out] operation     The operation object to set up. It must have
01804  *                              been initialized as per the documentation for
01805  *                              #psa_cipher_operation_t and not yet in use.
01806  * \param handle                Handle to the key to use for the operation.
01807  *                              It must remain valid until the operation
01808  *                              terminates.
01809  * \param alg                   The cipher algorithm to compute
01810  *                              (\c PSA_ALG_XXX value such that
01811  *                              #PSA_ALG_IS_CIPHER(\p alg) is true).
01812  *
01813  * \retval #PSA_SUCCESS
01814  *         Success.
01815  * \retval #PSA_ERROR_INVALID_HANDLE
01816  * \retval #PSA_ERROR_NOT_PERMITTED
01817  * \retval #PSA_ERROR_INVALID_ARGUMENT
01818  *         \p handle is not compatible with \p alg.
01819  * \retval #PSA_ERROR_NOT_SUPPORTED
01820  *         \p alg is not supported or is not a cipher algorithm.
01821  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01822  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01823  * \retval #PSA_ERROR_HARDWARE_FAILURE
01824  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01825  * \retval #PSA_ERROR_STORAGE_FAILURE
01826  * \retval #PSA_ERROR_BAD_STATE
01827  *         The operation state is not valid (it must be inactive).
01828  * \retval #PSA_ERROR_BAD_STATE
01829  *         The library has not been previously initialized by psa_crypto_init().
01830  *         It is implementation-dependent whether a failure to initialize
01831  *         results in this error code.
01832  */
01833 psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
01834                                       psa_key_handle_t handle,
01835                                       psa_algorithm_t alg);
01836 
01837 /** Set the key for a multipart symmetric decryption operation.
01838  *
01839  * The sequence of operations to decrypt a message with a symmetric cipher
01840  * is as follows:
01841  * -# Allocate an operation object which will be passed to all the functions
01842  *    listed here.
01843  * -# Initialize the operation object with one of the methods described in the
01844  *    documentation for #psa_cipher_operation_t, e.g.
01845  *    #PSA_CIPHER_OPERATION_INIT.
01846  * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
01847  * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
01848  *    decryption. If the IV is prepended to the ciphertext, you can call
01849  *    psa_cipher_update() on a buffer containing the IV followed by the
01850  *    beginning of the message.
01851  * -# Call psa_cipher_update() zero, one or more times, passing a fragment
01852  *    of the message each time.
01853  * -# Call psa_cipher_finish().
01854  *
01855  * If an error occurs at any step after a call to psa_cipher_decrypt_setup(),
01856  * the operation will need to be reset by a call to psa_cipher_abort(). The
01857  * application may call psa_cipher_abort() at any time after the operation
01858  * has been initialized.
01859  *
01860  * After a successful call to psa_cipher_decrypt_setup(), the application must
01861  * eventually terminate the operation. The following events terminate an
01862  * operation:
01863  * - A successful call to psa_cipher_finish().
01864  * - A call to psa_cipher_abort().
01865  *
01866  * \param[in,out] operation     The operation object to set up. It must have
01867  *                              been initialized as per the documentation for
01868  *                              #psa_cipher_operation_t and not yet in use.
01869  * \param handle                Handle to the key to use for the operation.
01870  *                              It must remain valid until the operation
01871  *                              terminates.
01872  * \param alg                   The cipher algorithm to compute
01873  *                              (\c PSA_ALG_XXX value such that
01874  *                              #PSA_ALG_IS_CIPHER(\p alg) is true).
01875  *
01876  * \retval #PSA_SUCCESS
01877  *         Success.
01878  * \retval #PSA_ERROR_INVALID_HANDLE
01879  * \retval #PSA_ERROR_NOT_PERMITTED
01880  * \retval #PSA_ERROR_INVALID_ARGUMENT
01881  *         \p handle is not compatible with \p alg.
01882  * \retval #PSA_ERROR_NOT_SUPPORTED
01883  *         \p alg is not supported or is not a cipher algorithm.
01884  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01885  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01886  * \retval #PSA_ERROR_HARDWARE_FAILURE
01887  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01888  * \retval #PSA_ERROR_STORAGE_FAILURE
01889  * \retval #PSA_ERROR_BAD_STATE
01890  *         The operation state is not valid (it must be inactive).
01891  * \retval #PSA_ERROR_BAD_STATE
01892  *         The library has not been previously initialized by psa_crypto_init().
01893  *         It is implementation-dependent whether a failure to initialize
01894  *         results in this error code.
01895  */
01896 psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
01897                                       psa_key_handle_t handle,
01898                                       psa_algorithm_t alg);
01899 
01900 /** Generate an IV for a symmetric encryption operation.
01901  *
01902  * This function generates a random IV (initialization vector), nonce
01903  * or initial counter value for the encryption operation as appropriate
01904  * for the chosen algorithm, key type and key size.
01905  *
01906  * The application must call psa_cipher_encrypt_setup() before
01907  * calling this function.
01908  *
01909  * If this function returns an error status, the operation enters an error
01910  * state and must be aborted by calling psa_cipher_abort().
01911  *
01912  * \param[in,out] operation     Active cipher operation.
01913  * \param[out] iv               Buffer where the generated IV is to be written.
01914  * \param iv_size               Size of the \p iv buffer in bytes.
01915  * \param[out] iv_length        On success, the number of bytes of the
01916  *                              generated IV.
01917  *
01918  * \retval #PSA_SUCCESS
01919  *         Success.
01920  * \retval #PSA_ERROR_BAD_STATE
01921  *         The operation state is not valid (it must be active, with no IV set).
01922  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
01923  *         The size of the \p iv buffer is too small.
01924  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01925  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01926  * \retval #PSA_ERROR_HARDWARE_FAILURE
01927  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01928  * \retval #PSA_ERROR_STORAGE_FAILURE
01929  * \retval #PSA_ERROR_BAD_STATE
01930  *         The library has not been previously initialized by psa_crypto_init().
01931  *         It is implementation-dependent whether a failure to initialize
01932  *         results in this error code.
01933  */
01934 psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
01935                                     uint8_t *iv,
01936                                     size_t iv_size,
01937                                     size_t *iv_length);
01938 
01939 /** Set the IV for a symmetric encryption or decryption operation.
01940  *
01941  * This function sets the IV (initialization vector), nonce
01942  * or initial counter value for the encryption or decryption operation.
01943  *
01944  * The application must call psa_cipher_encrypt_setup() before
01945  * calling this function.
01946  *
01947  * If this function returns an error status, the operation enters an error
01948  * state and must be aborted by calling psa_cipher_abort().
01949  *
01950  * \note When encrypting, applications should use psa_cipher_generate_iv()
01951  * instead of this function, unless implementing a protocol that requires
01952  * a non-random IV.
01953  *
01954  * \param[in,out] operation     Active cipher operation.
01955  * \param[in] iv                Buffer containing the IV to use.
01956  * \param iv_length             Size of the IV in bytes.
01957  *
01958  * \retval #PSA_SUCCESS
01959  *         Success.
01960  * \retval #PSA_ERROR_BAD_STATE
01961  *         The operation state is not valid (it must be an active cipher
01962  *         encrypt operation, with no IV set).
01963  * \retval #PSA_ERROR_INVALID_ARGUMENT
01964  *         The size of \p iv is not acceptable for the chosen algorithm,
01965  *         or the chosen algorithm does not use an IV.
01966  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
01967  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
01968  * \retval #PSA_ERROR_HARDWARE_FAILURE
01969  * \retval #PSA_ERROR_CORRUPTION_DETECTED
01970  * \retval #PSA_ERROR_STORAGE_FAILURE
01971  * \retval #PSA_ERROR_BAD_STATE
01972  *         The library has not been previously initialized by psa_crypto_init().
01973  *         It is implementation-dependent whether a failure to initialize
01974  *         results in this error code.
01975  */
01976 psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
01977                                const uint8_t *iv,
01978                                size_t iv_length);
01979 
01980 /** Encrypt or decrypt a message fragment in an active cipher operation.
01981  *
01982  * Before calling this function, you must:
01983  * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
01984  *    The choice of setup function determines whether this function
01985  *    encrypts or decrypts its input.
01986  * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
01987  *    (recommended when encrypting) or psa_cipher_set_iv().
01988  *
01989  * If this function returns an error status, the operation enters an error
01990  * state and must be aborted by calling psa_cipher_abort().
01991  *
01992  * \param[in,out] operation     Active cipher operation.
01993  * \param[in] input             Buffer containing the message fragment to
01994  *                              encrypt or decrypt.
01995  * \param input_length          Size of the \p input buffer in bytes.
01996  * \param[out] output           Buffer where the output is to be written.
01997  * \param output_size           Size of the \p output buffer in bytes.
01998  * \param[out] output_length    On success, the number of bytes
01999  *                              that make up the returned output.
02000  *
02001  * \retval #PSA_SUCCESS
02002  *         Success.
02003  * \retval #PSA_ERROR_BAD_STATE
02004  *         The operation state is not valid (it must be active, with an IV set
02005  *         if required for the algorithm).
02006  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02007  *         The size of the \p output buffer is too small.
02008  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02009  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02010  * \retval #PSA_ERROR_HARDWARE_FAILURE
02011  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02012  * \retval #PSA_ERROR_STORAGE_FAILURE
02013  * \retval #PSA_ERROR_BAD_STATE
02014  *         The library has not been previously initialized by psa_crypto_init().
02015  *         It is implementation-dependent whether a failure to initialize
02016  *         results in this error code.
02017  */
02018 psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
02019                                const uint8_t *input,
02020                                size_t input_length,
02021                                uint8_t *output,
02022                                size_t output_size,
02023                                size_t *output_length);
02024 
02025 /** Finish encrypting or decrypting a message in a cipher operation.
02026  *
02027  * The application must call psa_cipher_encrypt_setup() or
02028  * psa_cipher_decrypt_setup() before calling this function. The choice
02029  * of setup function determines whether this function encrypts or
02030  * decrypts its input.
02031  *
02032  * This function finishes the encryption or decryption of the message
02033  * formed by concatenating the inputs passed to preceding calls to
02034  * psa_cipher_update().
02035  *
02036  * When this function returns successfuly, the operation becomes inactive.
02037  * If this function returns an error status, the operation enters an error
02038  * state and must be aborted by calling psa_cipher_abort().
02039  *
02040  * \param[in,out] operation     Active cipher operation.
02041  * \param[out] output           Buffer where the output is to be written.
02042  * \param output_size           Size of the \p output buffer in bytes.
02043  * \param[out] output_length    On success, the number of bytes
02044  *                              that make up the returned output.
02045  *
02046  * \retval #PSA_SUCCESS
02047  *         Success.
02048  * \retval #PSA_ERROR_INVALID_ARGUMENT
02049  *         The total input size passed to this operation is not valid for
02050  *         this particular algorithm. For example, the algorithm is a based
02051  *         on block cipher and requires a whole number of blocks, but the
02052  *         total input size is not a multiple of the block size.
02053  * \retval #PSA_ERROR_INVALID_PADDING
02054  *         This is a decryption operation for an algorithm that includes
02055  *         padding, and the ciphertext does not contain valid padding.
02056  * \retval #PSA_ERROR_BAD_STATE
02057  *         The operation state is not valid (it must be active, with an IV set
02058  *         if required for the algorithm).
02059  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02060  *         The size of the \p output buffer is too small.
02061  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02062  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02063  * \retval #PSA_ERROR_HARDWARE_FAILURE
02064  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02065  * \retval #PSA_ERROR_STORAGE_FAILURE
02066  * \retval #PSA_ERROR_BAD_STATE
02067  *         The library has not been previously initialized by psa_crypto_init().
02068  *         It is implementation-dependent whether a failure to initialize
02069  *         results in this error code.
02070  */
02071 psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
02072                                uint8_t *output,
02073                                size_t output_size,
02074                                size_t *output_length);
02075 
02076 /** Abort a cipher operation.
02077  *
02078  * Aborting an operation frees all associated resources except for the
02079  * \p operation structure itself. Once aborted, the operation object
02080  * can be reused for another operation by calling
02081  * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
02082  *
02083  * You may call this function any time after the operation object has
02084  * been initialized as described in #psa_cipher_operation_t.
02085  *
02086  * In particular, calling psa_cipher_abort() after the operation has been
02087  * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
02088  * is safe and has no effect.
02089  *
02090  * \param[in,out] operation     Initialized cipher operation.
02091  *
02092  * \retval #PSA_SUCCESS
02093  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02094  * \retval #PSA_ERROR_HARDWARE_FAILURE
02095  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02096  * \retval #PSA_ERROR_BAD_STATE
02097  *         The library has not been previously initialized by psa_crypto_init().
02098  *         It is implementation-dependent whether a failure to initialize
02099  *         results in this error code.
02100  */
02101 psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
02102 
02103 /**@}*/
02104 
02105 /** \defgroup aead Authenticated encryption with associated data (AEAD)
02106  * @{
02107  */
02108 
02109 /** Process an authenticated encryption operation.
02110  *
02111  * \param handle                  Handle to the key to use for the operation.
02112  * \param alg                     The AEAD algorithm to compute
02113  *                                (\c PSA_ALG_XXX value such that
02114  *                                #PSA_ALG_IS_AEAD(\p alg) is true).
02115  * \param[in] nonce               Nonce or IV to use.
02116  * \param nonce_length            Size of the \p nonce buffer in bytes.
02117  * \param[in] additional_data     Additional data that will be authenticated
02118  *                                but not encrypted.
02119  * \param additional_data_length  Size of \p additional_data in bytes.
02120  * \param[in] plaintext           Data that will be authenticated and
02121  *                                encrypted.
02122  * \param plaintext_length        Size of \p plaintext in bytes.
02123  * \param[out] ciphertext         Output buffer for the authenticated and
02124  *                                encrypted data. The additional data is not
02125  *                                part of this output. For algorithms where the
02126  *                                encrypted data and the authentication tag
02127  *                                are defined as separate outputs, the
02128  *                                authentication tag is appended to the
02129  *                                encrypted data.
02130  * \param ciphertext_size         Size of the \p ciphertext buffer in bytes.
02131  *                                This must be at least
02132  *                                #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
02133  *                                \p plaintext_length).
02134  * \param[out] ciphertext_length  On success, the size of the output
02135  *                                in the \p ciphertext buffer.
02136  *
02137  * \retval #PSA_SUCCESS
02138  *         Success.
02139  * \retval #PSA_ERROR_INVALID_HANDLE
02140  * \retval #PSA_ERROR_NOT_PERMITTED
02141  * \retval #PSA_ERROR_INVALID_ARGUMENT
02142  *         \p handle is not compatible with \p alg.
02143  * \retval #PSA_ERROR_NOT_SUPPORTED
02144  *         \p alg is not supported or is not an AEAD algorithm.
02145  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02146  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02147  *         \p ciphertext_size is too small
02148  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02149  * \retval #PSA_ERROR_HARDWARE_FAILURE
02150  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02151  * \retval #PSA_ERROR_STORAGE_FAILURE
02152  * \retval #PSA_ERROR_BAD_STATE
02153  *         The library has not been previously initialized by psa_crypto_init().
02154  *         It is implementation-dependent whether a failure to initialize
02155  *         results in this error code.
02156  */
02157 psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
02158                               psa_algorithm_t alg,
02159                               const uint8_t *nonce,
02160                               size_t nonce_length,
02161                               const uint8_t *additional_data,
02162                               size_t additional_data_length,
02163                               const uint8_t *plaintext,
02164                               size_t plaintext_length,
02165                               uint8_t *ciphertext,
02166                               size_t ciphertext_size,
02167                               size_t *ciphertext_length);
02168 
02169 /** Process an authenticated decryption operation.
02170  *
02171  * \param handle                  Handle to the key to use for the operation.
02172  * \param alg                     The AEAD algorithm to compute
02173  *                                (\c PSA_ALG_XXX value such that
02174  *                                #PSA_ALG_IS_AEAD(\p alg) is true).
02175  * \param[in] nonce               Nonce or IV to use.
02176  * \param nonce_length            Size of the \p nonce buffer in bytes.
02177  * \param[in] additional_data     Additional data that has been authenticated
02178  *                                but not encrypted.
02179  * \param additional_data_length  Size of \p additional_data in bytes.
02180  * \param[in] ciphertext          Data that has been authenticated and
02181  *                                encrypted. For algorithms where the
02182  *                                encrypted data and the authentication tag
02183  *                                are defined as separate inputs, the buffer
02184  *                                must contain the encrypted data followed
02185  *                                by the authentication tag.
02186  * \param ciphertext_length       Size of \p ciphertext in bytes.
02187  * \param[out] plaintext          Output buffer for the decrypted data.
02188  * \param plaintext_size          Size of the \p plaintext buffer in bytes.
02189  *                                This must be at least
02190  *                                #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
02191  *                                \p ciphertext_length).
02192  * \param[out] plaintext_length   On success, the size of the output
02193  *                                in the \p plaintext buffer.
02194  *
02195  * \retval #PSA_SUCCESS
02196  *         Success.
02197  * \retval #PSA_ERROR_INVALID_HANDLE
02198  * \retval #PSA_ERROR_INVALID_SIGNATURE
02199  *         The ciphertext is not authentic.
02200  * \retval #PSA_ERROR_NOT_PERMITTED
02201  * \retval #PSA_ERROR_INVALID_ARGUMENT
02202  *         \p handle is not compatible with \p alg.
02203  * \retval #PSA_ERROR_NOT_SUPPORTED
02204  *         \p alg is not supported or is not an AEAD algorithm.
02205  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02206  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02207  *         \p plaintext_size or \p nonce_length is too small
02208  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02209  * \retval #PSA_ERROR_HARDWARE_FAILURE
02210  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02211  * \retval #PSA_ERROR_STORAGE_FAILURE
02212  * \retval #PSA_ERROR_BAD_STATE
02213  *         The library has not been previously initialized by psa_crypto_init().
02214  *         It is implementation-dependent whether a failure to initialize
02215  *         results in this error code.
02216  */
02217 psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
02218                               psa_algorithm_t alg,
02219                               const uint8_t *nonce,
02220                               size_t nonce_length,
02221                               const uint8_t *additional_data,
02222                               size_t additional_data_length,
02223                               const uint8_t *ciphertext,
02224                               size_t ciphertext_length,
02225                               uint8_t *plaintext,
02226                               size_t plaintext_size,
02227                               size_t *plaintext_length);
02228 
02229 /** The type of the state data structure for multipart AEAD operations.
02230  *
02231  * Before calling any function on an AEAD operation object, the application
02232  * must initialize it by any of the following means:
02233  * - Set the structure to all-bits-zero, for example:
02234  *   \code
02235  *   psa_aead_operation_t operation;
02236  *   memset(&operation, 0, sizeof(operation));
02237  *   \endcode
02238  * - Initialize the structure to logical zero values, for example:
02239  *   \code
02240  *   psa_aead_operation_t operation = {0};
02241  *   \endcode
02242  * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
02243  *   for example:
02244  *   \code
02245  *   psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
02246  *   \endcode
02247  * - Assign the result of the function psa_aead_operation_init()
02248  *   to the structure, for example:
02249  *   \code
02250  *   psa_aead_operation_t operation;
02251  *   operation = psa_aead_operation_init();
02252  *   \endcode
02253  *
02254  * This is an implementation-defined \c struct. Applications should not
02255  * make any assumptions about the content of this structure except
02256  * as directed by the documentation of a specific implementation. */
02257 typedef struct psa_aead_operation_s psa_aead_operation_t;
02258 
02259 /** \def PSA_AEAD_OPERATION_INIT
02260  *
02261  * This macro returns a suitable initializer for an AEAD operation object of
02262  * type #psa_aead_operation_t.
02263  */
02264 #ifdef __DOXYGEN_ONLY__
02265 /* This is an example definition for documentation purposes.
02266  * Implementations should define a suitable value in `crypto_struct.h`.
02267  */
02268 #define PSA_AEAD_OPERATION_INIT {0}
02269 #endif
02270 
02271 /** Return an initial value for an AEAD operation object.
02272  */
02273 static psa_aead_operation_t psa_aead_operation_init(void);
02274 
02275 /** Set the key for a multipart authenticated encryption operation.
02276  *
02277  * The sequence of operations to encrypt a message with authentication
02278  * is as follows:
02279  * -# Allocate an operation object which will be passed to all the functions
02280  *    listed here.
02281  * -# Initialize the operation object with one of the methods described in the
02282  *    documentation for #psa_aead_operation_t, e.g.
02283  *    #PSA_AEAD_OPERATION_INIT.
02284  * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
02285  * -# If needed, call psa_aead_set_lengths() to specify the length of the
02286  *    inputs to the subsequent calls to psa_aead_update_ad() and
02287  *    psa_aead_update(). See the documentation of psa_aead_set_lengths()
02288  *    for details.
02289  * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
02290  *    generate or set the nonce. You should use
02291  *    psa_aead_generate_nonce() unless the protocol you are implementing
02292  *    requires a specific nonce value.
02293  * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
02294  *    of the non-encrypted additional authenticated data each time.
02295  * -# Call psa_aead_update() zero, one or more times, passing a fragment
02296  *    of the message to encrypt each time.
02297  * -# Call psa_aead_finish().
02298  *
02299  * If an error occurs at any step after a call to psa_aead_encrypt_setup(),
02300  * the operation will need to be reset by a call to psa_aead_abort(). The
02301  * application may call psa_aead_abort() at any time after the operation
02302  * has been initialized.
02303  *
02304  * After a successful call to psa_aead_encrypt_setup(), the application must
02305  * eventually terminate the operation. The following events terminate an
02306  * operation:
02307  * - A successful call to psa_aead_finish().
02308  * - A call to psa_aead_abort().
02309  *
02310  * \param[in,out] operation     The operation object to set up. It must have
02311  *                              been initialized as per the documentation for
02312  *                              #psa_aead_operation_t and not yet in use.
02313  * \param handle                Handle to the key to use for the operation.
02314  *                              It must remain valid until the operation
02315  *                              terminates.
02316  * \param alg                   The AEAD algorithm to compute
02317  *                              (\c PSA_ALG_XXX value such that
02318  *                              #PSA_ALG_IS_AEAD(\p alg) is true).
02319  *
02320  * \retval #PSA_SUCCESS
02321  *         Success.
02322  * \retval #PSA_ERROR_BAD_STATE
02323  *         The operation state is not valid (it must be inactive).
02324   * \retval #PSA_ERROR_INVALID_HANDLE
02325  * \retval #PSA_ERROR_NOT_PERMITTED
02326  * \retval #PSA_ERROR_INVALID_ARGUMENT
02327  *         \p handle is not compatible with \p alg.
02328  * \retval #PSA_ERROR_NOT_SUPPORTED
02329  *         \p alg is not supported or is not an AEAD algorithm.
02330  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02331  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02332  * \retval #PSA_ERROR_HARDWARE_FAILURE
02333  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02334  * \retval #PSA_ERROR_STORAGE_FAILURE
02335  * \retval #PSA_ERROR_BAD_STATE
02336  *         The library has not been previously initialized by psa_crypto_init().
02337  *         It is implementation-dependent whether a failure to initialize
02338  *         results in this error code.
02339  */
02340 psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
02341                                     psa_key_handle_t handle,
02342                                     psa_algorithm_t alg);
02343 
02344 /** Set the key for a multipart authenticated decryption operation.
02345  *
02346  * The sequence of operations to decrypt a message with authentication
02347  * is as follows:
02348  * -# Allocate an operation object which will be passed to all the functions
02349  *    listed here.
02350  * -# Initialize the operation object with one of the methods described in the
02351  *    documentation for #psa_aead_operation_t, e.g.
02352  *    #PSA_AEAD_OPERATION_INIT.
02353  * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
02354  * -# If needed, call psa_aead_set_lengths() to specify the length of the
02355  *    inputs to the subsequent calls to psa_aead_update_ad() and
02356  *    psa_aead_update(). See the documentation of psa_aead_set_lengths()
02357  *    for details.
02358  * -# Call psa_aead_set_nonce() with the nonce for the decryption.
02359  * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
02360  *    of the non-encrypted additional authenticated data each time.
02361  * -# Call psa_aead_update() zero, one or more times, passing a fragment
02362  *    of the ciphertext to decrypt each time.
02363  * -# Call psa_aead_verify().
02364  *
02365  * If an error occurs at any step after a call to psa_aead_decrypt_setup(),
02366  * the operation will need to be reset by a call to psa_aead_abort(). The
02367  * application may call psa_aead_abort() at any time after the operation
02368  * has been initialized.
02369  *
02370  * After a successful call to psa_aead_decrypt_setup(), the application must
02371  * eventually terminate the operation. The following events terminate an
02372  * operation:
02373  * - A successful call to psa_aead_verify().
02374  * - A call to psa_aead_abort().
02375  *
02376  * \param[in,out] operation     The operation object to set up. It must have
02377  *                              been initialized as per the documentation for
02378  *                              #psa_aead_operation_t and not yet in use.
02379  * \param handle                Handle to the key to use for the operation.
02380  *                              It must remain valid until the operation
02381  *                              terminates.
02382  * \param alg                   The AEAD algorithm to compute
02383  *                              (\c PSA_ALG_XXX value such that
02384  *                              #PSA_ALG_IS_AEAD(\p alg) is true).
02385  *
02386  * \retval #PSA_SUCCESS
02387  *         Success.
02388  * \retval #PSA_ERROR_BAD_STATE
02389  *         The operation state is not valid (it must be inactive).
02390   * \retval #PSA_ERROR_INVALID_HANDLE
02391  * \retval #PSA_ERROR_NOT_PERMITTED
02392  * \retval #PSA_ERROR_INVALID_ARGUMENT
02393  *         \p handle is not compatible with \p alg.
02394  * \retval #PSA_ERROR_NOT_SUPPORTED
02395  *         \p alg is not supported or is not an AEAD algorithm.
02396  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02397  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02398  * \retval #PSA_ERROR_HARDWARE_FAILURE
02399  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02400  * \retval #PSA_ERROR_STORAGE_FAILURE
02401  * \retval #PSA_ERROR_BAD_STATE
02402  *         The library has not been previously initialized by psa_crypto_init().
02403  *         It is implementation-dependent whether a failure to initialize
02404  *         results in this error code.
02405  */
02406 psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
02407                                     psa_key_handle_t handle,
02408                                     psa_algorithm_t alg);
02409 
02410 /** Generate a random nonce for an authenticated encryption operation.
02411  *
02412  * This function generates a random nonce for the authenticated encryption
02413  * operation with an appropriate size for the chosen algorithm, key type
02414  * and key size.
02415  *
02416  * The application must call psa_aead_encrypt_setup() before
02417  * calling this function.
02418  *
02419  * If this function returns an error status, the operation enters an error
02420  * state and must be aborted by calling psa_aead_abort().
02421  *
02422  * \param[in,out] operation     Active AEAD operation.
02423  * \param[out] nonce            Buffer where the generated nonce is to be
02424  *                              written.
02425  * \param nonce_size            Size of the \p nonce buffer in bytes.
02426  * \param[out] nonce_length     On success, the number of bytes of the
02427  *                              generated nonce.
02428  *
02429  * \retval #PSA_SUCCESS
02430  *         Success.
02431  * \retval #PSA_ERROR_BAD_STATE
02432  *         The operation state is not valid (it must be an active aead encrypt
02433            operation, with no nonce set).
02434  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02435  *         The size of the \p nonce buffer is too small.
02436  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02437  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02438  * \retval #PSA_ERROR_HARDWARE_FAILURE
02439  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02440  * \retval #PSA_ERROR_STORAGE_FAILURE
02441  * \retval #PSA_ERROR_BAD_STATE
02442  *         The library has not been previously initialized by psa_crypto_init().
02443  *         It is implementation-dependent whether a failure to initialize
02444  *         results in this error code.
02445  */
02446 psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
02447                                      uint8_t *nonce,
02448                                      size_t nonce_size,
02449                                      size_t *nonce_length);
02450 
02451 /** Set the nonce for an authenticated encryption or decryption operation.
02452  *
02453  * This function sets the nonce for the authenticated
02454  * encryption or decryption operation.
02455  *
02456  * The application must call psa_aead_encrypt_setup() or
02457  * psa_aead_decrypt_setup() before calling this function.
02458  *
02459  * If this function returns an error status, the operation enters an error
02460  * state and must be aborted by calling psa_aead_abort().
02461  *
02462  * \note When encrypting, applications should use psa_aead_generate_nonce()
02463  * instead of this function, unless implementing a protocol that requires
02464  * a non-random IV.
02465  *
02466  * \param[in,out] operation     Active AEAD operation.
02467  * \param[in] nonce             Buffer containing the nonce to use.
02468  * \param nonce_length          Size of the nonce in bytes.
02469  *
02470  * \retval #PSA_SUCCESS
02471  *         Success.
02472  * \retval #PSA_ERROR_BAD_STATE
02473  *         The operation state is not valid (it must be active, with no nonce
02474  *         set).
02475  * \retval #PSA_ERROR_INVALID_ARGUMENT
02476  *         The size of \p nonce is not acceptable for the chosen algorithm.
02477  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02478  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02479  * \retval #PSA_ERROR_HARDWARE_FAILURE
02480  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02481  * \retval #PSA_ERROR_STORAGE_FAILURE
02482  * \retval #PSA_ERROR_BAD_STATE
02483  *         The library has not been previously initialized by psa_crypto_init().
02484  *         It is implementation-dependent whether a failure to initialize
02485  *         results in this error code.
02486  */
02487 psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
02488                                 const uint8_t *nonce,
02489                                 size_t nonce_length);
02490 
02491 /** Declare the lengths of the message and additional data for AEAD.
02492  *
02493  * The application must call this function before calling
02494  * psa_aead_update_ad() or psa_aead_update() if the algorithm for
02495  * the operation requires it. If the algorithm does not require it,
02496  * calling this function is optional, but if this function is called
02497  * then the implementation must enforce the lengths.
02498  *
02499  * You may call this function before or after setting the nonce with
02500  * psa_aead_set_nonce() or psa_aead_generate_nonce().
02501  *
02502  * - For #PSA_ALG_CCM, calling this function is required.
02503  * - For the other AEAD algorithms defined in this specification, calling
02504  *   this function is not required.
02505  * - For vendor-defined algorithm, refer to the vendor documentation.
02506  *
02507  * If this function returns an error status, the operation enters an error
02508  * state and must be aborted by calling psa_aead_abort().
02509  *
02510  * \param[in,out] operation     Active AEAD operation.
02511  * \param ad_length             Size of the non-encrypted additional
02512  *                              authenticated data in bytes.
02513  * \param plaintext_length      Size of the plaintext to encrypt in bytes.
02514  *
02515  * \retval #PSA_SUCCESS
02516  *         Success.
02517  * \retval #PSA_ERROR_BAD_STATE
02518  *         The operation state is not valid (it must be active, and
02519  *         psa_aead_update_ad() and psa_aead_update() must not have been
02520  *         called yet).
02521  * \retval #PSA_ERROR_INVALID_ARGUMENT
02522  *         At least one of the lengths is not acceptable for the chosen
02523  *         algorithm.
02524  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02525  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02526  * \retval #PSA_ERROR_HARDWARE_FAILURE
02527  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02528  * \retval #PSA_ERROR_BAD_STATE
02529  *         The library has not been previously initialized by psa_crypto_init().
02530  *         It is implementation-dependent whether a failure to initialize
02531  *         results in this error code.
02532  */
02533 psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
02534                                   size_t ad_length,
02535                                   size_t plaintext_length);
02536 
02537 /** Pass additional data to an active AEAD operation.
02538  *
02539  * Additional data is authenticated, but not encrypted.
02540  *
02541  * You may call this function multiple times to pass successive fragments
02542  * of the additional data. You may not call this function after passing
02543  * data to encrypt or decrypt with psa_aead_update().
02544  *
02545  * Before calling this function, you must:
02546  * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
02547  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
02548  *
02549  * If this function returns an error status, the operation enters an error
02550  * state and must be aborted by calling psa_aead_abort().
02551  *
02552  * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
02553  *          there is no guarantee that the input is valid. Therefore, until
02554  *          you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
02555  *          treat the input as untrusted and prepare to undo any action that
02556  *          depends on the input if psa_aead_verify() returns an error status.
02557  *
02558  * \param[in,out] operation     Active AEAD operation.
02559  * \param[in] input             Buffer containing the fragment of
02560  *                              additional data.
02561  * \param input_length          Size of the \p input buffer in bytes.
02562  *
02563  * \retval #PSA_SUCCESS
02564  *         Success.
02565  * \retval #PSA_ERROR_BAD_STATE
02566  *         The operation state is not valid (it must be active, have a nonce
02567  *         set, have lengths set if required by the algorithm, and
02568  *         psa_aead_update() must not have been called yet).
02569  * \retval #PSA_ERROR_INVALID_ARGUMENT
02570  *         The total input length overflows the additional data length that
02571  *         was previously specified with psa_aead_set_lengths().
02572  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02573  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02574  * \retval #PSA_ERROR_HARDWARE_FAILURE
02575  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02576  * \retval #PSA_ERROR_STORAGE_FAILURE
02577  * \retval #PSA_ERROR_BAD_STATE
02578  *         The library has not been previously initialized by psa_crypto_init().
02579  *         It is implementation-dependent whether a failure to initialize
02580  *         results in this error code.
02581  */
02582 psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
02583                                 const uint8_t *input,
02584                                 size_t input_length);
02585 
02586 /** Encrypt or decrypt a message fragment in an active AEAD operation.
02587  *
02588  * Before calling this function, you must:
02589  * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
02590  *    The choice of setup function determines whether this function
02591  *    encrypts or decrypts its input.
02592  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
02593  * 3. Call psa_aead_update_ad() to pass all the additional data.
02594  *
02595  * If this function returns an error status, the operation enters an error
02596  * state and must be aborted by calling psa_aead_abort().
02597  *
02598  * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
02599  *          there is no guarantee that the input is valid. Therefore, until
02600  *          you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
02601  *          - Do not use the output in any way other than storing it in a
02602  *            confidential location. If you take any action that depends
02603  *            on the tentative decrypted data, this action will need to be
02604  *            undone if the input turns out not to be valid. Furthermore,
02605  *            if an adversary can observe that this action took place
02606  *            (for example through timing), they may be able to use this
02607  *            fact as an oracle to decrypt any message encrypted with the
02608  *            same key.
02609  *          - In particular, do not copy the output anywhere but to a
02610  *            memory or storage space that you have exclusive access to.
02611  *
02612  * This function does not require the input to be aligned to any
02613  * particular block boundary. If the implementation can only process
02614  * a whole block at a time, it must consume all the input provided, but
02615  * it may delay the end of the corresponding output until a subsequent
02616  * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
02617  * provides sufficient input. The amount of data that can be delayed
02618  * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
02619  *
02620  * \param[in,out] operation     Active AEAD operation.
02621  * \param[in] input             Buffer containing the message fragment to
02622  *                              encrypt or decrypt.
02623  * \param input_length          Size of the \p input buffer in bytes.
02624  * \param[out] output           Buffer where the output is to be written.
02625  * \param output_size           Size of the \p output buffer in bytes.
02626  *                              This must be at least
02627  *                              #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
02628  *                              \p input_length) where \c alg is the
02629  *                              algorithm that is being calculated.
02630  * \param[out] output_length    On success, the number of bytes
02631  *                              that make up the returned output.
02632  *
02633  * \retval #PSA_SUCCESS
02634  *         Success.
02635  * \retval #PSA_ERROR_BAD_STATE
02636  *         The operation state is not valid (it must be active, have a nonce
02637  *         set, and have lengths set if required by the algorithm).
02638  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02639  *         The size of the \p output buffer is too small.
02640  *         You can determine a sufficient buffer size by calling
02641  *         #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
02642  *         where \c alg is the algorithm that is being calculated.
02643  * \retval #PSA_ERROR_INVALID_ARGUMENT
02644  *         The total length of input to psa_aead_update_ad() so far is
02645  *         less than the additional data length that was previously
02646  *         specified with psa_aead_set_lengths().
02647  * \retval #PSA_ERROR_INVALID_ARGUMENT
02648  *         The total input length overflows the plaintext length that
02649  *         was previously specified with psa_aead_set_lengths().
02650  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02651  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02652  * \retval #PSA_ERROR_HARDWARE_FAILURE
02653  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02654  * \retval #PSA_ERROR_STORAGE_FAILURE
02655  * \retval #PSA_ERROR_BAD_STATE
02656  *         The library has not been previously initialized by psa_crypto_init().
02657  *         It is implementation-dependent whether a failure to initialize
02658  *         results in this error code.
02659  */
02660 psa_status_t psa_aead_update(psa_aead_operation_t *operation,
02661                              const uint8_t *input,
02662                              size_t input_length,
02663                              uint8_t *output,
02664                              size_t output_size,
02665                              size_t *output_length);
02666 
02667 /** Finish encrypting a message in an AEAD operation.
02668  *
02669  * The operation must have been set up with psa_aead_encrypt_setup().
02670  *
02671  * This function finishes the authentication of the additional data
02672  * formed by concatenating the inputs passed to preceding calls to
02673  * psa_aead_update_ad() with the plaintext formed by concatenating the
02674  * inputs passed to preceding calls to psa_aead_update().
02675  *
02676  * This function has two output buffers:
02677  * - \p ciphertext contains trailing ciphertext that was buffered from
02678  *   preceding calls to psa_aead_update().
02679  * - \p tag contains the authentication tag. Its length is always
02680  *   #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
02681  *   that the operation performs.
02682  *
02683  * When this function returns successfuly, the operation becomes inactive.
02684  * If this function returns an error status, the operation enters an error
02685  * state and must be aborted by calling psa_aead_abort().
02686  *
02687  * \param[in,out] operation     Active AEAD operation.
02688  * \param[out] ciphertext       Buffer where the last part of the ciphertext
02689  *                              is to be written.
02690  * \param ciphertext_size       Size of the \p ciphertext buffer in bytes.
02691  *                              This must be at least
02692  *                              #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
02693  *                              \c alg is the algorithm that is being
02694  *                              calculated.
02695  * \param[out] ciphertext_length On success, the number of bytes of
02696  *                              returned ciphertext.
02697  * \param[out] tag              Buffer where the authentication tag is
02698  *                              to be written.
02699  * \param tag_size              Size of the \p tag buffer in bytes.
02700  *                              This must be at least
02701  *                              #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
02702  *                              the algorithm that is being calculated.
02703  * \param[out] tag_length       On success, the number of bytes
02704  *                              that make up the returned tag.
02705  *
02706  * \retval #PSA_SUCCESS
02707  *         Success.
02708  * \retval #PSA_ERROR_BAD_STATE
02709  *         The operation state is not valid (it must be an active encryption
02710  *         operation with a nonce set).
02711  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02712  *         The size of the \p ciphertext or \p tag buffer is too small.
02713  *         You can determine a sufficient buffer size for \p ciphertext by
02714  *         calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
02715  *         where \c alg is the algorithm that is being calculated.
02716  *         You can determine a sufficient buffer size for \p tag by
02717  *         calling #PSA_AEAD_TAG_LENGTH(\c alg).
02718  * \retval #PSA_ERROR_INVALID_ARGUMENT
02719  *         The total length of input to psa_aead_update_ad() so far is
02720  *         less than the additional data length that was previously
02721  *         specified with psa_aead_set_lengths().
02722  * \retval #PSA_ERROR_INVALID_ARGUMENT
02723  *         The total length of input to psa_aead_update() so far is
02724  *         less than the plaintext length that was previously
02725  *         specified with psa_aead_set_lengths().
02726  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02727  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02728  * \retval #PSA_ERROR_HARDWARE_FAILURE
02729  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02730  * \retval #PSA_ERROR_STORAGE_FAILURE
02731  * \retval #PSA_ERROR_BAD_STATE
02732  *         The library has not been previously initialized by psa_crypto_init().
02733  *         It is implementation-dependent whether a failure to initialize
02734  *         results in this error code.
02735  */
02736 psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
02737                              uint8_t *ciphertext,
02738                              size_t ciphertext_size,
02739                              size_t *ciphertext_length,
02740                              uint8_t *tag,
02741                              size_t tag_size,
02742                              size_t *tag_length);
02743 
02744 /** Finish authenticating and decrypting a message in an AEAD operation.
02745  *
02746  * The operation must have been set up with psa_aead_decrypt_setup().
02747  *
02748  * This function finishes the authenticated decryption of the message
02749  * components:
02750  *
02751  * -  The additional data consisting of the concatenation of the inputs
02752  *    passed to preceding calls to psa_aead_update_ad().
02753  * -  The ciphertext consisting of the concatenation of the inputs passed to
02754  *    preceding calls to psa_aead_update().
02755  * -  The tag passed to this function call.
02756  *
02757  * If the authentication tag is correct, this function outputs any remaining
02758  * plaintext and reports success. If the authentication tag is not correct,
02759  * this function returns #PSA_ERROR_INVALID_SIGNATURE.
02760  *
02761  * When this function returns successfuly, the operation becomes inactive.
02762  * If this function returns an error status, the operation enters an error
02763  * state and must be aborted by calling psa_aead_abort().
02764  *
02765  * \note Implementations shall make the best effort to ensure that the
02766  * comparison between the actual tag and the expected tag is performed
02767  * in constant time.
02768  *
02769  * \param[in,out] operation     Active AEAD operation.
02770  * \param[out] plaintext        Buffer where the last part of the plaintext
02771  *                              is to be written. This is the remaining data
02772  *                              from previous calls to psa_aead_update()
02773  *                              that could not be processed until the end
02774  *                              of the input.
02775  * \param plaintext_size        Size of the \p plaintext buffer in bytes.
02776  *                              This must be at least
02777  *                              #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
02778  *                              \c alg is the algorithm that is being
02779  *                              calculated.
02780  * \param[out] plaintext_length On success, the number of bytes of
02781  *                              returned plaintext.
02782  * \param[in] tag               Buffer containing the authentication tag.
02783  * \param tag_length            Size of the \p tag buffer in bytes.
02784  *
02785  * \retval #PSA_SUCCESS
02786  *         Success.
02787  * \retval #PSA_ERROR_INVALID_SIGNATURE
02788  *         The calculations were successful, but the authentication tag is
02789  *         not correct.
02790  * \retval #PSA_ERROR_BAD_STATE
02791  *         The operation state is not valid (it must be an active decryption
02792  *         operation with a nonce set).
02793  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02794  *         The size of the \p plaintext buffer is too small.
02795  *         You can determine a sufficient buffer size for \p plaintext by
02796  *         calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
02797  *         where \c alg is the algorithm that is being calculated.
02798  * \retval #PSA_ERROR_INVALID_ARGUMENT
02799  *         The total length of input to psa_aead_update_ad() so far is
02800  *         less than the additional data length that was previously
02801  *         specified with psa_aead_set_lengths().
02802  * \retval #PSA_ERROR_INVALID_ARGUMENT
02803  *         The total length of input to psa_aead_update() so far is
02804  *         less than the plaintext length that was previously
02805  *         specified with psa_aead_set_lengths().
02806  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02807  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02808  * \retval #PSA_ERROR_HARDWARE_FAILURE
02809  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02810  * \retval #PSA_ERROR_STORAGE_FAILURE
02811  * \retval #PSA_ERROR_BAD_STATE
02812  *         The library has not been previously initialized by psa_crypto_init().
02813  *         It is implementation-dependent whether a failure to initialize
02814  *         results in this error code.
02815  */
02816 psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
02817                              uint8_t *plaintext,
02818                              size_t plaintext_size,
02819                              size_t *plaintext_length,
02820                              const uint8_t *tag,
02821                              size_t tag_length);
02822 
02823 /** Abort an AEAD operation.
02824  *
02825  * Aborting an operation frees all associated resources except for the
02826  * \p operation structure itself. Once aborted, the operation object
02827  * can be reused for another operation by calling
02828  * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
02829  *
02830  * You may call this function any time after the operation object has
02831  * been initialized as described in #psa_aead_operation_t.
02832  *
02833  * In particular, calling psa_aead_abort() after the operation has been
02834  * terminated by a call to psa_aead_abort(), psa_aead_finish() or
02835  * psa_aead_verify() is safe and has no effect.
02836  *
02837  * \param[in,out] operation     Initialized AEAD operation.
02838  *
02839  * \retval #PSA_SUCCESS
02840  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02841  * \retval #PSA_ERROR_HARDWARE_FAILURE
02842  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02843  * \retval #PSA_ERROR_BAD_STATE
02844  *         The library has not been previously initialized by psa_crypto_init().
02845  *         It is implementation-dependent whether a failure to initialize
02846  *         results in this error code.
02847  */
02848 psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
02849 
02850 /**@}*/
02851 
02852 /** \defgroup asymmetric Asymmetric cryptography
02853  * @{
02854  */
02855 
02856 /**
02857  * \brief Sign a hash or short message with a private key.
02858  *
02859  * Note that to perform a hash-and-sign signature algorithm, you must
02860  * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
02861  * and psa_hash_finish(). Then pass the resulting hash as the \p hash
02862  * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
02863  * to determine the hash algorithm to use.
02864  *
02865  * \param handle                Handle to the key to use for the operation.
02866  *                              It must be an asymmetric key pair.
02867  * \param alg                   A signature algorithm that is compatible with
02868  *                              the type of \p handle.
02869  * \param[in] hash              The hash or message to sign.
02870  * \param hash_length           Size of the \p hash buffer in bytes.
02871  * \param[out] signature        Buffer where the signature is to be written.
02872  * \param signature_size        Size of the \p signature buffer in bytes.
02873  * \param[out] signature_length On success, the number of bytes
02874  *                              that make up the returned signature value.
02875  *
02876  * \retval #PSA_SUCCESS
02877  * \retval #PSA_ERROR_INVALID_HANDLE
02878  * \retval #PSA_ERROR_NOT_PERMITTED
02879  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02880  *         The size of the \p signature buffer is too small. You can
02881  *         determine a sufficient buffer size by calling
02882  *         #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
02883  *         where \c key_type and \c key_bits are the type and bit-size
02884  *         respectively of \p handle.
02885  * \retval #PSA_ERROR_NOT_SUPPORTED
02886  * \retval #PSA_ERROR_INVALID_ARGUMENT
02887  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02888  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02889  * \retval #PSA_ERROR_HARDWARE_FAILURE
02890  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02891  * \retval #PSA_ERROR_STORAGE_FAILURE
02892  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
02893  * \retval #PSA_ERROR_BAD_STATE
02894  *         The library has not been previously initialized by psa_crypto_init().
02895  *         It is implementation-dependent whether a failure to initialize
02896  *         results in this error code.
02897  */
02898 psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
02899                                  psa_algorithm_t alg,
02900                                  const uint8_t *hash,
02901                                  size_t hash_length,
02902                                  uint8_t *signature,
02903                                  size_t signature_size,
02904                                  size_t *signature_length);
02905 
02906 /**
02907  * \brief Verify the signature a hash or short message using a public key.
02908  *
02909  * Note that to perform a hash-and-sign signature algorithm, you must
02910  * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
02911  * and psa_hash_finish(). Then pass the resulting hash as the \p hash
02912  * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
02913  * to determine the hash algorithm to use.
02914  *
02915  * \param handle            Handle to the key to use for the operation.
02916  *                          It must be a public key or an asymmetric key pair.
02917  * \param alg               A signature algorithm that is compatible with
02918  *                          the type of \p handle.
02919  * \param[in] hash          The hash or message whose signature is to be
02920  *                          verified.
02921  * \param hash_length       Size of the \p hash buffer in bytes.
02922  * \param[in] signature     Buffer containing the signature to verify.
02923  * \param signature_length  Size of the \p signature buffer in bytes.
02924  *
02925  * \retval #PSA_SUCCESS
02926  *         The signature is valid.
02927  * \retval #PSA_ERROR_INVALID_HANDLE
02928  * \retval #PSA_ERROR_NOT_PERMITTED
02929  * \retval #PSA_ERROR_INVALID_SIGNATURE
02930  *         The calculation was perfomed successfully, but the passed
02931  *         signature is not a valid signature.
02932  * \retval #PSA_ERROR_NOT_SUPPORTED
02933  * \retval #PSA_ERROR_INVALID_ARGUMENT
02934  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02935  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02936  * \retval #PSA_ERROR_HARDWARE_FAILURE
02937  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02938  * \retval #PSA_ERROR_STORAGE_FAILURE
02939  * \retval #PSA_ERROR_BAD_STATE
02940  *         The library has not been previously initialized by psa_crypto_init().
02941  *         It is implementation-dependent whether a failure to initialize
02942  *         results in this error code.
02943  */
02944 psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
02945                                    psa_algorithm_t alg,
02946                                    const uint8_t *hash,
02947                                    size_t hash_length,
02948                                    const uint8_t *signature,
02949                                    size_t signature_length);
02950 
02951 /**
02952  * \brief Encrypt a short message with a public key.
02953  *
02954  * \param handle                Handle to the key to use for the operation.
02955  *                              It must be a public key or an asymmetric
02956  *                              key pair.
02957  * \param alg                   An asymmetric encryption algorithm that is
02958  *                              compatible with the type of \p handle.
02959  * \param[in] input             The message to encrypt.
02960  * \param input_length          Size of the \p input buffer in bytes.
02961  * \param[in] salt              A salt or label, if supported by the
02962  *                              encryption algorithm.
02963  *                              If the algorithm does not support a
02964  *                              salt, pass \c NULL.
02965  *                              If the algorithm supports an optional
02966  *                              salt and you do not want to pass a salt,
02967  *                              pass \c NULL.
02968  *
02969  *                              - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
02970  *                                supported.
02971  * \param salt_length           Size of the \p salt buffer in bytes.
02972  *                              If \p salt is \c NULL, pass 0.
02973  * \param[out] output           Buffer where the encrypted message is to
02974  *                              be written.
02975  * \param output_size           Size of the \p output buffer in bytes.
02976  * \param[out] output_length    On success, the number of bytes
02977  *                              that make up the returned output.
02978  *
02979  * \retval #PSA_SUCCESS
02980  * \retval #PSA_ERROR_INVALID_HANDLE
02981  * \retval #PSA_ERROR_NOT_PERMITTED
02982  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
02983  *         The size of the \p output buffer is too small. You can
02984  *         determine a sufficient buffer size by calling
02985  *         #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
02986  *         where \c key_type and \c key_bits are the type and bit-size
02987  *         respectively of \p handle.
02988  * \retval #PSA_ERROR_NOT_SUPPORTED
02989  * \retval #PSA_ERROR_INVALID_ARGUMENT
02990  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
02991  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
02992  * \retval #PSA_ERROR_HARDWARE_FAILURE
02993  * \retval #PSA_ERROR_CORRUPTION_DETECTED
02994  * \retval #PSA_ERROR_STORAGE_FAILURE
02995  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
02996  * \retval #PSA_ERROR_BAD_STATE
02997  *         The library has not been previously initialized by psa_crypto_init().
02998  *         It is implementation-dependent whether a failure to initialize
02999  *         results in this error code.
03000  */
03001 psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
03002                                     psa_algorithm_t alg,
03003                                     const uint8_t *input,
03004                                     size_t input_length,
03005                                     const uint8_t *salt,
03006                                     size_t salt_length,
03007                                     uint8_t *output,
03008                                     size_t output_size,
03009                                     size_t *output_length);
03010 
03011 /**
03012  * \brief Decrypt a short message with a private key.
03013  *
03014  * \param handle                Handle to the key to use for the operation.
03015  *                              It must be an asymmetric key pair.
03016  * \param alg                   An asymmetric encryption algorithm that is
03017  *                              compatible with the type of \p handle.
03018  * \param[in] input             The message to decrypt.
03019  * \param input_length          Size of the \p input buffer in bytes.
03020  * \param[in] salt              A salt or label, if supported by the
03021  *                              encryption algorithm.
03022  *                              If the algorithm does not support a
03023  *                              salt, pass \c NULL.
03024  *                              If the algorithm supports an optional
03025  *                              salt and you do not want to pass a salt,
03026  *                              pass \c NULL.
03027  *
03028  *                              - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
03029  *                                supported.
03030  * \param salt_length           Size of the \p salt buffer in bytes.
03031  *                              If \p salt is \c NULL, pass 0.
03032  * \param[out] output           Buffer where the decrypted message is to
03033  *                              be written.
03034  * \param output_size           Size of the \c output buffer in bytes.
03035  * \param[out] output_length    On success, the number of bytes
03036  *                              that make up the returned output.
03037  *
03038  * \retval #PSA_SUCCESS
03039  * \retval #PSA_ERROR_INVALID_HANDLE
03040  * \retval #PSA_ERROR_NOT_PERMITTED
03041  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
03042  *         The size of the \p output buffer is too small. You can
03043  *         determine a sufficient buffer size by calling
03044  *         #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
03045  *         where \c key_type and \c key_bits are the type and bit-size
03046  *         respectively of \p handle.
03047  * \retval #PSA_ERROR_NOT_SUPPORTED
03048  * \retval #PSA_ERROR_INVALID_ARGUMENT
03049  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03050  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03051  * \retval #PSA_ERROR_HARDWARE_FAILURE
03052  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03053  * \retval #PSA_ERROR_STORAGE_FAILURE
03054  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
03055  * \retval #PSA_ERROR_INVALID_PADDING
03056  * \retval #PSA_ERROR_BAD_STATE
03057  *         The library has not been previously initialized by psa_crypto_init().
03058  *         It is implementation-dependent whether a failure to initialize
03059  *         results in this error code.
03060  */
03061 psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
03062                                     psa_algorithm_t alg,
03063                                     const uint8_t *input,
03064                                     size_t input_length,
03065                                     const uint8_t *salt,
03066                                     size_t salt_length,
03067                                     uint8_t *output,
03068                                     size_t output_size,
03069                                     size_t *output_length);
03070 
03071 /**@}*/
03072 
03073 /** \defgroup key_derivation Key derivation and pseudorandom generation
03074  * @{
03075  */
03076 
03077 /** The type of the state data structure for key derivation operations.
03078  *
03079  * Before calling any function on a key derivation operation object, the
03080  * application must initialize it by any of the following means:
03081  * - Set the structure to all-bits-zero, for example:
03082  *   \code
03083  *   psa_key_derivation_operation_t operation;
03084  *   memset(&operation, 0, sizeof(operation));
03085  *   \endcode
03086  * - Initialize the structure to logical zero values, for example:
03087  *   \code
03088  *   psa_key_derivation_operation_t operation = {0};
03089  *   \endcode
03090  * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
03091  *   for example:
03092  *   \code
03093  *   psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
03094  *   \endcode
03095  * - Assign the result of the function psa_key_derivation_operation_init()
03096  *   to the structure, for example:
03097  *   \code
03098  *   psa_key_derivation_operation_t operation;
03099  *   operation = psa_key_derivation_operation_init();
03100  *   \endcode
03101  *
03102  * This is an implementation-defined \c struct. Applications should not
03103  * make any assumptions about the content of this structure except
03104  * as directed by the documentation of a specific implementation.
03105  */
03106 typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
03107 
03108 /** \def PSA_KEY_DERIVATION_OPERATION_INIT
03109  *
03110  * This macro returns a suitable initializer for a key derivation operation
03111  * object of type #psa_key_derivation_operation_t.
03112  */
03113 #ifdef __DOXYGEN_ONLY__
03114 /* This is an example definition for documentation purposes.
03115  * Implementations should define a suitable value in `crypto_struct.h`.
03116  */
03117 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
03118 #endif
03119 
03120 /** Return an initial value for a key derivation operation object.
03121  */
03122 static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
03123 
03124 /** Set up a key derivation operation.
03125  *
03126  * A key derivation algorithm takes some inputs and uses them to generate
03127  * a byte stream in a deterministic way.
03128  * This byte stream can be used to produce keys and other
03129  * cryptographic material.
03130  *
03131  * To derive a key:
03132  * -# Start with an initialized object of type #psa_key_derivation_operation_t.
03133  * -# Call psa_key_derivation_setup() to select the algorithm.
03134  * -# Provide the inputs for the key derivation by calling
03135  *    psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
03136  *    as appropriate. Which inputs are needed, in what order, and whether
03137  *    they may be keys and if so of what type depends on the algorithm.
03138  * -# Optionally set the operation's maximum capacity with
03139  *    psa_key_derivation_set_capacity(). You may do this before, in the middle
03140  *    of or after providing inputs. For some algorithms, this step is mandatory
03141  *    because the output depends on the maximum capacity.
03142  * -# To derive a key, call psa_key_derivation_output_key().
03143  *    To derive a byte string for a different purpose, call
03144  *    psa_key_derivation_output_bytes().
03145  *    Successive calls to these functions use successive output bytes
03146  *    calculated by the key derivation algorithm.
03147  * -# Clean up the key derivation operation object with
03148  *    psa_key_derivation_abort().
03149  *
03150  * If this function returns an error, the key derivation operation object is
03151  * not changed.
03152  *
03153  * If an error occurs at any step after a call to psa_key_derivation_setup(),
03154  * the operation will need to be reset by a call to psa_key_derivation_abort().
03155  *
03156  * Implementations must reject an attempt to derive a key of size 0.
03157  *
03158  * \param[in,out] operation       The key derivation operation object
03159  *                                to set up. It must
03160  *                                have been initialized but not set up yet.
03161  * \param alg                     The key derivation algorithm to compute
03162  *                                (\c PSA_ALG_XXX value such that
03163  *                                #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
03164  *
03165  * \retval #PSA_SUCCESS
03166  *         Success.
03167  * \retval #PSA_ERROR_INVALID_ARGUMENT
03168  *         \c alg is not a key derivation algorithm.
03169  * \retval #PSA_ERROR_NOT_SUPPORTED
03170  *         \c alg is not supported or is not a key derivation algorithm.
03171  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03172  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03173  * \retval #PSA_ERROR_HARDWARE_FAILURE
03174  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03175  * \retval #PSA_ERROR_STORAGE_FAILURE
03176  * \retval #PSA_ERROR_BAD_STATE
03177  *         The operation state is not valid (it must be inactive).
03178  * \retval #PSA_ERROR_BAD_STATE
03179  *         The library has not been previously initialized by psa_crypto_init().
03180  *         It is implementation-dependent whether a failure to initialize
03181  *         results in this error code.
03182  */
03183 psa_status_t psa_key_derivation_setup(
03184     psa_key_derivation_operation_t *operation,
03185     psa_algorithm_t alg);
03186 
03187 /** Retrieve the current capacity of a key derivation operation.
03188  *
03189  * The capacity of a key derivation is the maximum number of bytes that it can
03190  * return. When you get *N* bytes of output from a key derivation operation,
03191  * this reduces its capacity by *N*.
03192  *
03193  * \param[in] operation     The operation to query.
03194  * \param[out] capacity     On success, the capacity of the operation.
03195  *
03196  * \retval #PSA_SUCCESS
03197  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03198  * \retval #PSA_ERROR_BAD_STATE
03199  *         The operation state is not valid (it must be active).
03200  * \retval #PSA_ERROR_HARDWARE_FAILURE
03201  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03202  * \retval #PSA_ERROR_BAD_STATE
03203  *         The library has not been previously initialized by psa_crypto_init().
03204  *         It is implementation-dependent whether a failure to initialize
03205  *         results in this error code.
03206  */
03207 psa_status_t psa_key_derivation_get_capacity(
03208     const psa_key_derivation_operation_t *operation,
03209     size_t *capacity);
03210 
03211 /** Set the maximum capacity of a key derivation operation.
03212  *
03213  * The capacity of a key derivation operation is the maximum number of bytes
03214  * that the key derivation operation can return from this point onwards.
03215  *
03216  * \param[in,out] operation The key derivation operation object to modify.
03217  * \param capacity          The new capacity of the operation.
03218  *                          It must be less or equal to the operation's
03219  *                          current capacity.
03220  *
03221  * \retval #PSA_SUCCESS
03222  * \retval #PSA_ERROR_INVALID_ARGUMENT
03223  *         \p capacity is larger than the operation's current capacity.
03224  *         In this case, the operation object remains valid and its capacity
03225  *         remains unchanged.
03226  * \retval #PSA_ERROR_BAD_STATE
03227  *         The operation state is not valid (it must be active).
03228  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03229  * \retval #PSA_ERROR_HARDWARE_FAILURE
03230  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03231  * \retval #PSA_ERROR_BAD_STATE
03232  *         The library has not been previously initialized by psa_crypto_init().
03233  *         It is implementation-dependent whether a failure to initialize
03234  *         results in this error code.
03235  */
03236 psa_status_t psa_key_derivation_set_capacity(
03237     psa_key_derivation_operation_t *operation,
03238     size_t capacity);
03239 
03240 /** Use the maximum possible capacity for a key derivation operation.
03241  *
03242  * Use this value as the capacity argument when setting up a key derivation
03243  * to indicate that the operation should have the maximum possible capacity.
03244  * The value of the maximum possible capacity depends on the key derivation
03245  * algorithm.
03246  */
03247 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
03248 
03249 /** Provide an input for key derivation or key agreement.
03250  *
03251  * Which inputs are required and in what order depends on the algorithm.
03252  * Refer to the documentation of each key derivation or key agreement
03253  * algorithm for information.
03254  *
03255  * This function passes direct inputs, which is usually correct for
03256  * non-secret inputs. To pass a secret input, which should be in a key
03257  * object, call psa_key_derivation_input_key() instead of this function.
03258  * Refer to the documentation of individual step types
03259  * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t)
03260  * for more information.
03261  *
03262  * If this function returns an error status, the operation enters an error
03263  * state and must be aborted by calling psa_key_derivation_abort().
03264  *
03265  * \param[in,out] operation       The key derivation operation object to use.
03266  *                                It must have been set up with
03267  *                                psa_key_derivation_setup() and must not
03268  *                                have produced any output yet.
03269  * \param step                    Which step the input data is for.
03270  * \param[in] data                Input data to use.
03271  * \param data_length             Size of the \p data buffer in bytes.
03272  *
03273  * \retval #PSA_SUCCESS
03274  *         Success.
03275  * \retval #PSA_ERROR_INVALID_ARGUMENT
03276  *         \c step is not compatible with the operation's algorithm.
03277  * \retval #PSA_ERROR_INVALID_ARGUMENT
03278  *         \c step does not allow direct inputs.
03279  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03280  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03281  * \retval #PSA_ERROR_HARDWARE_FAILURE
03282  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03283  * \retval #PSA_ERROR_STORAGE_FAILURE
03284  * \retval #PSA_ERROR_BAD_STATE
03285  *         The operation state is not valid for this input \p step.
03286  * \retval #PSA_ERROR_BAD_STATE
03287  *         The library has not been previously initialized by psa_crypto_init().
03288  *         It is implementation-dependent whether a failure to initialize
03289  *         results in this error code.
03290  */
03291 psa_status_t psa_key_derivation_input_bytes(
03292     psa_key_derivation_operation_t *operation,
03293     psa_key_derivation_step_t step,
03294     const uint8_t *data,
03295     size_t data_length);
03296 
03297 /** Provide an input for key derivation in the form of a key.
03298  *
03299  * Which inputs are required and in what order depends on the algorithm.
03300  * Refer to the documentation of each key derivation or key agreement
03301  * algorithm for information.
03302  *
03303  * This function obtains input from a key object, which is usually correct for
03304  * secret inputs or for non-secret personalization strings kept in the key
03305  * store. To pass a non-secret parameter which is not in the key store,
03306  * call psa_key_derivation_input_bytes() instead of this function.
03307  * Refer to the documentation of individual step types
03308  * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t)
03309  * for more information.
03310  *
03311  * If this function returns an error status, the operation enters an error
03312  * state and must be aborted by calling psa_key_derivation_abort().
03313  *
03314  * \param[in,out] operation       The key derivation operation object to use.
03315  *                                It must have been set up with
03316  *                                psa_key_derivation_setup() and must not
03317  *                                have produced any output yet.
03318  * \param step                    Which step the input data is for.
03319  * \param handle                  Handle to the key. It must have an
03320  *                                appropriate type for \p step and must
03321  *                                allow the usage #PSA_KEY_USAGE_DERIVE.
03322  *
03323  * \retval #PSA_SUCCESS
03324  *         Success.
03325  * \retval #PSA_ERROR_INVALID_HANDLE
03326  * \retval #PSA_ERROR_NOT_PERMITTED
03327  * \retval #PSA_ERROR_INVALID_ARGUMENT
03328  *         \c step is not compatible with the operation's algorithm.
03329  * \retval #PSA_ERROR_INVALID_ARGUMENT
03330  *         \c step does not allow key inputs of the given type
03331  *         or does not allow key inputs at all.
03332  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03333  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03334  * \retval #PSA_ERROR_HARDWARE_FAILURE
03335  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03336  * \retval #PSA_ERROR_STORAGE_FAILURE
03337  * \retval #PSA_ERROR_BAD_STATE
03338  *         The operation state is not valid for this input \p step.
03339  * \retval #PSA_ERROR_BAD_STATE
03340  *         The library has not been previously initialized by psa_crypto_init().
03341  *         It is implementation-dependent whether a failure to initialize
03342  *         results in this error code.
03343  */
03344 psa_status_t psa_key_derivation_input_key(
03345     psa_key_derivation_operation_t *operation,
03346     psa_key_derivation_step_t step,
03347     psa_key_handle_t handle);
03348 
03349 /** Perform a key agreement and use the shared secret as input to a key
03350  * derivation.
03351  *
03352  * A key agreement algorithm takes two inputs: a private key \p private_key
03353  * a public key \p peer_key.
03354  * The result of this function is passed as input to a key derivation.
03355  * The output of this key derivation can be extracted by reading from the
03356  * resulting operation to produce keys and other cryptographic material.
03357  *
03358  * If this function returns an error status, the operation enters an error
03359  * state and must be aborted by calling psa_key_derivation_abort().
03360  *
03361  * \param[in,out] operation       The key derivation operation object to use.
03362  *                                It must have been set up with
03363  *                                psa_key_derivation_setup() with a
03364  *                                key agreement and derivation algorithm
03365  *                                \c alg (\c PSA_ALG_XXX value such that
03366  *                                #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
03367  *                                and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
03368  *                                is false).
03369  *                                The operation must be ready for an
03370  *                                input of the type given by \p step.
03371  * \param step                    Which step the input data is for.
03372  * \param private_key             Handle to the private key to use.
03373  * \param[in] peer_key      Public key of the peer. The peer key must be in the
03374  *                          same format that psa_import_key() accepts for the
03375  *                          public key type corresponding to the type of
03376  *                          private_key. That is, this function performs the
03377  *                          equivalent of
03378  *                          #psa_import_key(...,
03379  *                          `peer_key`, `peer_key_length`) where
03380  *                          with key attributes indicating the public key
03381  *                          type corresponding to the type of `private_key`.
03382  *                          For example, for EC keys, this means that peer_key
03383  *                          is interpreted as a point on the curve that the
03384  *                          private key is on. The standard formats for public
03385  *                          keys are documented in the documentation of
03386  *                          psa_export_public_key().
03387  * \param peer_key_length         Size of \p peer_key in bytes.
03388  *
03389  * \retval #PSA_SUCCESS
03390  *         Success.
03391  * \retval #PSA_ERROR_BAD_STATE
03392  *         The operation state is not valid for this key agreement \p step.
03393  * \retval #PSA_ERROR_INVALID_HANDLE
03394  * \retval #PSA_ERROR_NOT_PERMITTED
03395  * \retval #PSA_ERROR_INVALID_ARGUMENT
03396  *         \c private_key is not compatible with \c alg,
03397  *         or \p peer_key is not valid for \c alg or not compatible with
03398  *         \c private_key.
03399  * \retval #PSA_ERROR_NOT_SUPPORTED
03400  *         \c alg is not supported or is not a key derivation algorithm.
03401  * \retval #PSA_ERROR_INVALID_ARGUMENT
03402  *         \c step does not allow an input resulting from a key agreement.
03403  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03404  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03405  * \retval #PSA_ERROR_HARDWARE_FAILURE
03406  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03407  * \retval #PSA_ERROR_STORAGE_FAILURE
03408  * \retval #PSA_ERROR_BAD_STATE
03409  *         The library has not been previously initialized by psa_crypto_init().
03410  *         It is implementation-dependent whether a failure to initialize
03411  *         results in this error code.
03412  */
03413 psa_status_t psa_key_derivation_key_agreement(
03414     psa_key_derivation_operation_t *operation,
03415     psa_key_derivation_step_t step,
03416     psa_key_handle_t private_key,
03417     const uint8_t *peer_key,
03418     size_t peer_key_length);
03419 
03420 /** Read some data from a key derivation operation.
03421  *
03422  * This function calculates output bytes from a key derivation algorithm and
03423  * return those bytes.
03424  * If you view the key derivation's output as a stream of bytes, this
03425  * function destructively reads the requested number of bytes from the
03426  * stream.
03427  * The operation's capacity decreases by the number of bytes read.
03428  *
03429  * If this function returns an error status other than
03430  * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
03431  * state and must be aborted by calling psa_key_derivation_abort().
03432  *
03433  * \param[in,out] operation The key derivation operation object to read from.
03434  * \param[out] output       Buffer where the output will be written.
03435  * \param output_length     Number of bytes to output.
03436  *
03437  * \retval #PSA_SUCCESS
03438  * \retval #PSA_ERROR_INSUFFICIENT_DATA
03439  *                          The operation's capacity was less than
03440  *                          \p output_length bytes. Note that in this case,
03441  *                          no output is written to the output buffer.
03442  *                          The operation's capacity is set to 0, thus
03443  *                          subsequent calls to this function will not
03444  *                          succeed, even with a smaller output buffer.
03445  * \retval #PSA_ERROR_BAD_STATE
03446  *         The operation state is not valid (it must be active and completed
03447  *         all required input steps).
03448  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03449  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03450  * \retval #PSA_ERROR_HARDWARE_FAILURE
03451  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03452  * \retval #PSA_ERROR_STORAGE_FAILURE
03453  * \retval #PSA_ERROR_BAD_STATE
03454  *         The library has not been previously initialized by psa_crypto_init().
03455  *         It is implementation-dependent whether a failure to initialize
03456  *         results in this error code.
03457  */
03458 psa_status_t psa_key_derivation_output_bytes(
03459     psa_key_derivation_operation_t *operation,
03460     uint8_t *output,
03461     size_t output_length);
03462 
03463 /** Derive a key from an ongoing key derivation operation.
03464  *
03465  * This function calculates output bytes from a key derivation algorithm
03466  * and uses those bytes to generate a key deterministically.
03467  * The key's location, usage policy, type and size are taken from
03468  * \p attributes.
03469  *
03470  * If you view the key derivation's output as a stream of bytes, this
03471  * function destructively reads as many bytes as required from the
03472  * stream.
03473  * The operation's capacity decreases by the number of bytes read.
03474  *
03475  * If this function returns an error status other than
03476  * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
03477  * state and must be aborted by calling psa_key_derivation_abort().
03478  *
03479  * How much output is produced and consumed from the operation, and how
03480  * the key is derived, depends on the key type:
03481  *
03482  * - For key types for which the key is an arbitrary sequence of bytes
03483  *   of a given size, this function is functionally equivalent to
03484  *   calling #psa_key_derivation_output_bytes
03485  *   and passing the resulting output to #psa_import_key.
03486  *   However, this function has a security benefit:
03487  *   if the implementation provides an isolation boundary then
03488  *   the key material is not exposed outside the isolation boundary.
03489  *   As a consequence, for these key types, this function always consumes
03490  *   exactly (\p bits / 8) bytes from the operation.
03491  *   The following key types defined in this specification follow this scheme:
03492  *
03493  *     - #PSA_KEY_TYPE_AES;
03494  *     - #PSA_KEY_TYPE_ARC4;
03495  *     - #PSA_KEY_TYPE_CAMELLIA;
03496  *     - #PSA_KEY_TYPE_DERIVE;
03497  *     - #PSA_KEY_TYPE_HMAC.
03498  *
03499  * - For ECC keys on a Montgomery elliptic curve
03500  *   (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
03501  *   Montgomery curve), this function always draws a byte string whose
03502  *   length is determined by the curve, and sets the mandatory bits
03503  *   accordingly. That is:
03504  *
03505  *     - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
03506  *       and process it as specified in RFC 7748 &sect;5.
03507  *     - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
03508  *       and process it as specified in RFC 7748 &sect;5.
03509  *
03510  * - For key types for which the key is represented by a single sequence of
03511  *   \p bits bits with constraints as to which bit sequences are acceptable,
03512  *   this function draws a byte string of length (\p bits / 8) bytes rounded
03513  *   up to the nearest whole number of bytes. If the resulting byte string
03514  *   is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
03515  *   This process is repeated until an acceptable byte string is drawn.
03516  *   The byte string drawn from the operation is interpreted as specified
03517  *   for the output produced by psa_export_key().
03518  *   The following key types defined in this specification follow this scheme:
03519  *
03520  *     - #PSA_KEY_TYPE_DES.
03521  *       Force-set the parity bits, but discard forbidden weak keys.
03522  *       For 2-key and 3-key triple-DES, the three keys are generated
03523  *       successively (for example, for 3-key triple-DES,
03524  *       if the first 8 bytes specify a weak key and the next 8 bytes do not,
03525  *       discard the first 8 bytes, use the next 8 bytes as the first key,
03526  *       and continue reading output from the operation to derive the other
03527  *       two keys).
03528  *     - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
03529  *       where \c group designates any Diffie-Hellman group) and
03530  *       ECC keys on a Weierstrass elliptic curve
03531  *       (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
03532  *       Weierstrass curve).
03533  *       For these key types, interpret the byte string as integer
03534  *       in big-endian order. Discard it if it is not in the range
03535  *       [0, *N* - 2] where *N* is the boundary of the private key domain
03536  *       (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
03537  *       or the order of the curve's base point for ECC).
03538  *       Add 1 to the resulting integer and use this as the private key *x*.
03539  *       This method allows compliance to NIST standards, specifically
03540  *       the methods titled "key-pair generation by testing candidates"
03541  *       in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
03542  *       in FIPS 186-4 &sect;B.1.2 for DSA, and
03543  *       in NIST SP 800-56A &sect;5.6.1.2.2 or
03544  *       FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
03545  *
03546  * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
03547  *   the way in which the operation output is consumed is
03548  *   implementation-defined.
03549  *
03550  * In all cases, the data that is read is discarded from the operation.
03551  * The operation's capacity is decreased by the number of bytes read.
03552  *
03553  * For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET,
03554  * the input to that step must be provided with psa_key_derivation_input_key().
03555  * Future versions of this specification may include additional restrictions
03556  * on the derived key based on the attributes and strength of the secret key.
03557  *
03558  * \param[in] attributes    The attributes for the new key.
03559  * \param[in,out] operation The key derivation operation object to read from.
03560  * \param[out] handle       On success, a handle to the newly created key.
03561  *                          \c 0 on failure.
03562  *
03563  * \retval #PSA_SUCCESS
03564  *         Success.
03565  *         If the key is persistent, the key material and the key's metadata
03566  *         have been saved to persistent storage.
03567  * \retval #PSA_ERROR_ALREADY_EXISTS
03568  *         This is an attempt to create a persistent key, and there is
03569  *         already a persistent key with the given identifier.
03570  * \retval #PSA_ERROR_INSUFFICIENT_DATA
03571  *         There was not enough data to create the desired key.
03572  *         Note that in this case, no output is written to the output buffer.
03573  *         The operation's capacity is set to 0, thus subsequent calls to
03574  *         this function will not succeed, even with a smaller output buffer.
03575  * \retval #PSA_ERROR_NOT_SUPPORTED
03576  *         The key type or key size is not supported, either by the
03577  *         implementation in general or in this particular location.
03578  * \retval #PSA_ERROR_INVALID_ARGUMENT
03579  *         The provided key attributes are not valid for the operation.
03580  * \retval #PSA_ERROR_NOT_PERMITTED
03581  *         The #PSA_KEY_DERIVATION_INPUT_SECRET input was not provided through
03582  *         a key.
03583  * \retval #PSA_ERROR_BAD_STATE
03584  *         The operation state is not valid (it must be active and completed
03585  *         all required input steps).
03586  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03587  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
03588  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03589  * \retval #PSA_ERROR_HARDWARE_FAILURE
03590  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03591  * \retval #PSA_ERROR_STORAGE_FAILURE
03592  * \retval #PSA_ERROR_BAD_STATE
03593  *         The library has not been previously initialized by psa_crypto_init().
03594  *         It is implementation-dependent whether a failure to initialize
03595  *         results in this error code.
03596  */
03597 psa_status_t psa_key_derivation_output_key(
03598     const psa_key_attributes_t *attributes,
03599     psa_key_derivation_operation_t *operation,
03600     psa_key_handle_t *handle);
03601 
03602 /** Abort a key derivation operation.
03603  *
03604  * Aborting an operation frees all associated resources except for the \c
03605  * operation structure itself. Once aborted, the operation object can be reused
03606  * for another operation by calling psa_key_derivation_setup() again.
03607  *
03608  * This function may be called at any time after the operation
03609  * object has been initialized as described in #psa_key_derivation_operation_t.
03610  *
03611  * In particular, it is valid to call psa_key_derivation_abort() twice, or to
03612  * call psa_key_derivation_abort() on an operation that has not been set up.
03613  *
03614  * \param[in,out] operation    The operation to abort.
03615  *
03616  * \retval #PSA_SUCCESS
03617  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03618  * \retval #PSA_ERROR_HARDWARE_FAILURE
03619  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03620  * \retval #PSA_ERROR_BAD_STATE
03621  *         The library has not been previously initialized by psa_crypto_init().
03622  *         It is implementation-dependent whether a failure to initialize
03623  *         results in this error code.
03624  */
03625 psa_status_t psa_key_derivation_abort(
03626     psa_key_derivation_operation_t *operation);
03627 
03628 /** Perform a key agreement and return the raw shared secret.
03629  *
03630  * \warning The raw result of a key agreement algorithm such as finite-field
03631  * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
03632  * not be used directly as key material. It should instead be passed as
03633  * input to a key derivation algorithm. To chain a key agreement with
03634  * a key derivation, use psa_key_derivation_key_agreement() and other
03635  * functions from the key derivation interface.
03636  *
03637  * \param alg                     The key agreement algorithm to compute
03638  *                                (\c PSA_ALG_XXX value such that
03639  *                                #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
03640  *                                is true).
03641  * \param private_key             Handle to the private key to use.
03642  * \param[in] peer_key            Public key of the peer. It must be
03643  *                                in the same format that psa_import_key()
03644  *                                accepts. The standard formats for public
03645  *                                keys are documented in the documentation
03646  *                                of psa_export_public_key().
03647  * \param peer_key_length         Size of \p peer_key in bytes.
03648  * \param[out] output             Buffer where the decrypted message is to
03649  *                                be written.
03650  * \param output_size             Size of the \c output buffer in bytes.
03651  * \param[out] output_length      On success, the number of bytes
03652  *                                that make up the returned output.
03653  *
03654  * \retval #PSA_SUCCESS
03655  *         Success.
03656  * \retval #PSA_ERROR_INVALID_HANDLE
03657  * \retval #PSA_ERROR_NOT_PERMITTED
03658  * \retval #PSA_ERROR_INVALID_ARGUMENT
03659  *         \p alg is not a key agreement algorithm
03660  * \retval #PSA_ERROR_INVALID_ARGUMENT
03661  *         \p private_key is not compatible with \p alg,
03662  *         or \p peer_key is not valid for \p alg or not compatible with
03663  *         \p private_key.
03664  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
03665  *         \p output_size is too small
03666  * \retval #PSA_ERROR_NOT_SUPPORTED
03667  *         \p alg is not a supported key agreement algorithm.
03668  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03669  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03670  * \retval #PSA_ERROR_HARDWARE_FAILURE
03671  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03672  * \retval #PSA_ERROR_STORAGE_FAILURE
03673  * \retval #PSA_ERROR_BAD_STATE
03674  *         The library has not been previously initialized by psa_crypto_init().
03675  *         It is implementation-dependent whether a failure to initialize
03676  *         results in this error code.
03677  */
03678 psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
03679                                    psa_key_handle_t private_key,
03680                                    const uint8_t *peer_key,
03681                                    size_t peer_key_length,
03682                                    uint8_t *output,
03683                                    size_t output_size,
03684                                    size_t *output_length);
03685 
03686 /**@}*/
03687 
03688 /** \defgroup random Random generation
03689  * @{
03690  */
03691 
03692 /**
03693  * \brief Generate random bytes.
03694  *
03695  * \warning This function **can** fail! Callers MUST check the return status
03696  *          and MUST NOT use the content of the output buffer if the return
03697  *          status is not #PSA_SUCCESS.
03698  *
03699  * \note    To generate a key, use psa_generate_key() instead.
03700  *
03701  * \param[out] output       Output buffer for the generated data.
03702  * \param output_size       Number of bytes to generate and output.
03703  *
03704  * \retval #PSA_SUCCESS
03705  * \retval #PSA_ERROR_NOT_SUPPORTED
03706  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
03707  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03708  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03709  * \retval #PSA_ERROR_HARDWARE_FAILURE
03710  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03711  * \retval #PSA_ERROR_BAD_STATE
03712  *         The library has not been previously initialized by psa_crypto_init().
03713  *         It is implementation-dependent whether a failure to initialize
03714  *         results in this error code.
03715  */
03716 psa_status_t psa_generate_random(uint8_t *output,
03717                                  size_t output_size);
03718 
03719 /**
03720  * \brief Generate a key or key pair.
03721  *
03722  * The key is generated randomly.
03723  * Its location, usage policy, type and size are taken from \p attributes.
03724  *
03725  * Implementations must reject an attempt to generate a key of size 0.
03726  *
03727  * The following type-specific considerations apply:
03728  * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
03729  *   the public exponent is 65537.
03730  *   The modulus is a product of two probabilistic primes
03731  *   between 2^{n-1} and 2^n where n is the bit size specified in the
03732  *   attributes.
03733  *
03734  * \param[in] attributes    The attributes for the new key.
03735  * \param[out] handle       On success, a handle to the newly created key.
03736  *                          \c 0 on failure.
03737  *
03738  * \retval #PSA_SUCCESS
03739  *         Success.
03740  *         If the key is persistent, the key material and the key's metadata
03741  *         have been saved to persistent storage.
03742  * \retval #PSA_ERROR_ALREADY_EXISTS
03743  *         This is an attempt to create a persistent key, and there is
03744  *         already a persistent key with the given identifier.
03745  * \retval #PSA_ERROR_NOT_SUPPORTED
03746  * \retval #PSA_ERROR_INVALID_ARGUMENT
03747  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
03748  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
03749  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
03750  * \retval #PSA_ERROR_HARDWARE_FAILURE
03751  * \retval #PSA_ERROR_CORRUPTION_DETECTED
03752  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
03753  * \retval #PSA_ERROR_STORAGE_FAILURE
03754  * \retval #PSA_ERROR_BAD_STATE
03755  *         The library has not been previously initialized by psa_crypto_init().
03756  *         It is implementation-dependent whether a failure to initialize
03757  *         results in this error code.
03758  */
03759 psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
03760                               psa_key_handle_t *handle);
03761 
03762 /**@}*/
03763 
03764 #ifdef __cplusplus
03765 }
03766 #endif
03767 
03768 /* The file "crypto_sizes.h" contains definitions for size calculation
03769  * macros whose definitions are implementation-specific. */
03770 #include "crypto_sizes.h"
03771 
03772 /* The file "crypto_struct.h" contains definitions for
03773  * implementation-specific structs that are declared above. */
03774 #include "crypto_struct.h"
03775 
03776 /* The file "crypto_extra.h" contains vendor-specific definitions. This
03777  * can include vendor-defined algorithms, extra functions, etc. */
03778 #include "crypto_extra.h"
03779 
03780 #endif /* PSA_CRYPTO_H */