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