psa_crypto_hash.h (9116B)
1 /* 2 * PSA hashing layer on top of Mbed TLS software crypto 3 */ 4 /* 5 * Copyright The Mbed TLS Contributors 6 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7 */ 8 9 #ifndef PSA_CRYPTO_HASH_H 10 #define PSA_CRYPTO_HASH_H 11 12 #include <psa/crypto.h> 13 14 /** Calculate the hash (digest) of a message using Mbed TLS routines. 15 * 16 * \note The signature of this function is that of a PSA driver hash_compute 17 * entry point. This function behaves as a hash_compute entry point as 18 * defined in the PSA driver interface specification for transparent 19 * drivers. 20 * 21 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value 22 * such that #PSA_ALG_IS_HASH(\p alg) is true). 23 * \param[in] input Buffer containing the message to hash. 24 * \param input_length Size of the \p input buffer in bytes. 25 * \param[out] hash Buffer where the hash is to be written. 26 * \param hash_size Size of the \p hash buffer in bytes. 27 * \param[out] hash_length On success, the number of bytes 28 * that make up the hash value. This is always 29 * #PSA_HASH_LENGTH(\p alg). 30 * 31 * \retval #PSA_SUCCESS 32 * Success. 33 * \retval #PSA_ERROR_NOT_SUPPORTED 34 * \p alg is not supported 35 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 36 * \p hash_size is too small 37 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 38 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 39 */ 40 psa_status_t mbedtls_psa_hash_compute( 41 psa_algorithm_t alg, 42 const uint8_t *input, 43 size_t input_length, 44 uint8_t *hash, 45 size_t hash_size, 46 size_t *hash_length); 47 48 /** Set up a multipart hash operation using Mbed TLS routines. 49 * 50 * \note The signature of this function is that of a PSA driver hash_setup 51 * entry point. This function behaves as a hash_setup entry point as 52 * defined in the PSA driver interface specification for transparent 53 * drivers. 54 * 55 * If an error occurs at any step after a call to mbedtls_psa_hash_setup(), the 56 * operation will need to be reset by a call to mbedtls_psa_hash_abort(). The 57 * core may call mbedtls_psa_hash_abort() at any time after the operation 58 * has been initialized. 59 * 60 * After a successful call to mbedtls_psa_hash_setup(), the core must 61 * eventually terminate the operation. The following events terminate an 62 * operation: 63 * - A successful call to mbedtls_psa_hash_finish() or mbedtls_psa_hash_verify(). 64 * - A call to mbedtls_psa_hash_abort(). 65 * 66 * \param[in,out] operation The operation object to set up. It must have 67 * been initialized to all-zero and not yet be in use. 68 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value 69 * such that #PSA_ALG_IS_HASH(\p alg) is true). 70 * 71 * \retval #PSA_SUCCESS 72 * Success. 73 * \retval #PSA_ERROR_NOT_SUPPORTED 74 * \p alg is not supported 75 * \retval #PSA_ERROR_BAD_STATE 76 * The operation state is not valid (it must be inactive). 77 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 78 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 79 */ 80 psa_status_t mbedtls_psa_hash_setup( 81 mbedtls_psa_hash_operation_t *operation, 82 psa_algorithm_t alg); 83 84 /** Clone an Mbed TLS hash operation. 85 * 86 * \note The signature of this function is that of a PSA driver hash_clone 87 * entry point. This function behaves as a hash_clone entry point as 88 * defined in the PSA driver interface specification for transparent 89 * drivers. 90 * 91 * This function copies the state of an ongoing hash operation to 92 * a new operation object. In other words, this function is equivalent 93 * to calling mbedtls_psa_hash_setup() on \p target_operation with the same 94 * algorithm that \p source_operation was set up for, then 95 * mbedtls_psa_hash_update() on \p target_operation with the same input that 96 * that was passed to \p source_operation. After this function returns, the 97 * two objects are independent, i.e. subsequent calls involving one of 98 * the objects do not affect the other object. 99 * 100 * \param[in] source_operation The active hash operation to clone. 101 * \param[in,out] target_operation The operation object to set up. 102 * It must be initialized but not active. 103 * 104 * \retval #PSA_SUCCESS \emptydescription 105 * \retval #PSA_ERROR_BAD_STATE 106 * The \p source_operation state is not valid (it must be active). 107 * \retval #PSA_ERROR_BAD_STATE 108 * The \p target_operation state is not valid (it must be inactive). 109 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 110 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 111 */ 112 psa_status_t mbedtls_psa_hash_clone( 113 const mbedtls_psa_hash_operation_t *source_operation, 114 mbedtls_psa_hash_operation_t *target_operation); 115 116 /** Add a message fragment to a multipart Mbed TLS hash operation. 117 * 118 * \note The signature of this function is that of a PSA driver hash_update 119 * entry point. This function behaves as a hash_update entry point as 120 * defined in the PSA driver interface specification for transparent 121 * drivers. 122 * 123 * The application must call mbedtls_psa_hash_setup() before calling this function. 124 * 125 * If this function returns an error status, the operation enters an error 126 * state and must be aborted by calling mbedtls_psa_hash_abort(). 127 * 128 * \param[in,out] operation Active hash operation. 129 * \param[in] input Buffer containing the message fragment to hash. 130 * \param input_length Size of the \p input buffer in bytes. 131 * 132 * \retval #PSA_SUCCESS 133 * Success. 134 * \retval #PSA_ERROR_BAD_STATE 135 * The operation state is not valid (it must be active). 136 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 137 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 138 */ 139 psa_status_t mbedtls_psa_hash_update( 140 mbedtls_psa_hash_operation_t *operation, 141 const uint8_t *input, 142 size_t input_length); 143 144 /** Finish the calculation of the Mbed TLS-calculated hash of a message. 145 * 146 * \note The signature of this function is that of a PSA driver hash_finish 147 * entry point. This function behaves as a hash_finish entry point as 148 * defined in the PSA driver interface specification for transparent 149 * drivers. 150 * 151 * The application must call mbedtls_psa_hash_setup() before calling this function. 152 * This function calculates the hash of the message formed by concatenating 153 * the inputs passed to preceding calls to mbedtls_psa_hash_update(). 154 * 155 * When this function returns successfully, the operation becomes inactive. 156 * If this function returns an error status, the operation enters an error 157 * state and must be aborted by calling mbedtls_psa_hash_abort(). 158 * 159 * \param[in,out] operation Active hash operation. 160 * \param[out] hash Buffer where the hash is to be written. 161 * \param hash_size Size of the \p hash buffer in bytes. 162 * \param[out] hash_length On success, the number of bytes 163 * that make up the hash value. This is always 164 * #PSA_HASH_LENGTH(\c alg) where \c alg is the 165 * hash algorithm that is calculated. 166 * 167 * \retval #PSA_SUCCESS 168 * Success. 169 * \retval #PSA_ERROR_BAD_STATE 170 * The operation state is not valid (it must be active). 171 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 172 * The size of the \p hash buffer is too small. You can determine a 173 * sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg) 174 * where \c alg is the hash algorithm that is calculated. 175 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 176 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 177 */ 178 psa_status_t mbedtls_psa_hash_finish( 179 mbedtls_psa_hash_operation_t *operation, 180 uint8_t *hash, 181 size_t hash_size, 182 size_t *hash_length); 183 184 /** Abort an Mbed TLS hash operation. 185 * 186 * \note The signature of this function is that of a PSA driver hash_abort 187 * entry point. This function behaves as a hash_abort entry point as 188 * defined in the PSA driver interface specification for transparent 189 * drivers. 190 * 191 * Aborting an operation frees all associated resources except for the 192 * \p operation structure itself. Once aborted, the operation object 193 * can be reused for another operation by calling 194 * mbedtls_psa_hash_setup() again. 195 * 196 * You may call this function any time after the operation object has 197 * been initialized by one of the methods described in #psa_hash_operation_t. 198 * 199 * In particular, calling mbedtls_psa_hash_abort() after the operation has been 200 * terminated by a call to mbedtls_psa_hash_abort(), mbedtls_psa_hash_finish() or 201 * mbedtls_psa_hash_verify() is safe and has no effect. 202 * 203 * \param[in,out] operation Initialized hash operation. 204 * 205 * \retval #PSA_SUCCESS \emptydescription 206 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 207 */ 208 psa_status_t mbedtls_psa_hash_abort( 209 mbedtls_psa_hash_operation_t *operation); 210 211 #endif /* PSA_CRYPTO_HASH_H */