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