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