1 /* 2 * PSA MAC 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_MAC_H 22 #define PSA_CRYPTO_MAC_H 23 24 #include <psa/crypto.h> 25 26 /** Calculate the MAC (message authentication code) of a message using Mbed TLS. 27 * 28 * \note The signature of this function is that of a PSA driver mac_compute 29 * entry point. This function behaves as a mac_compute entry point as 30 * defined in the PSA driver interface specification for transparent 31 * drivers. 32 * 33 * \param[in] attributes The attributes of the key to use for the 34 * operation. 35 * \param[in] key_buffer The buffer containing the key to use for 36 * computing the MAC. This buffer contains the key 37 * in export representation as defined by 38 * psa_export_key() (i.e. the raw key bytes). 39 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 40 * \param alg The MAC algorithm to use (\c PSA_ALG_XXX value 41 * such that #PSA_ALG_IS_MAC(\p alg) is true). 42 * \param[in] input Buffer containing the input message. 43 * \param input_length Size of the \p input buffer in bytes. 44 * \param[out] mac Buffer where the MAC value is to be written. 45 * \param mac_size Size of the \p mac buffer in bytes. 46 * \param[out] mac_length On success, the number of bytes 47 * that make up the MAC value. 48 * 49 * \retval #PSA_SUCCESS 50 * Success. 51 * \retval #PSA_ERROR_NOT_SUPPORTED 52 * \p alg is not supported. 53 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 54 * \p mac_size is too small 55 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 56 * \retval #PSA_ERROR_CORRUPTION_DETECTED 57 */ 58 psa_status_t mbedtls_psa_mac_compute( 59 const psa_key_attributes_t *attributes, 60 const uint8_t *key_buffer, 61 size_t key_buffer_size, 62 psa_algorithm_t alg, 63 const uint8_t *input, 64 size_t input_length, 65 uint8_t *mac, 66 size_t mac_size, 67 size_t *mac_length); 68 69 /** Set up a multipart MAC calculation operation using Mbed TLS. 70 * 71 * \note The signature of this function is that of a PSA driver mac_sign_setup 72 * entry point. This function behaves as a mac_sign_setup entry point as 73 * defined in the PSA driver interface specification for transparent 74 * drivers. 75 * 76 * \param[in,out] operation The operation object to set up. It must have 77 * been initialized and not yet in use. 78 * \param[in] attributes The attributes of the key to use for the 79 * operation. 80 * \param[in] key_buffer The buffer containing the key to use for 81 * computing the MAC. This buffer contains the key 82 * in export representation as defined by 83 * psa_export_key() (i.e. the raw key bytes). 84 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 85 * \param alg The MAC algorithm to use (\c PSA_ALG_XXX value 86 * such that #PSA_ALG_IS_MAC(\p alg) is true). 87 * 88 * \retval #PSA_SUCCESS 89 * Success. 90 * \retval #PSA_ERROR_NOT_SUPPORTED 91 * \p alg is not supported. 92 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 93 * \retval #PSA_ERROR_CORRUPTION_DETECTED 94 * \retval #PSA_ERROR_BAD_STATE 95 * The operation state is not valid (it must be inactive). 96 */ 97 psa_status_t mbedtls_psa_mac_sign_setup( 98 mbedtls_psa_mac_operation_t *operation, 99 const psa_key_attributes_t *attributes, 100 const uint8_t *key_buffer, 101 size_t key_buffer_size, 102 psa_algorithm_t alg); 103 104 /** Set up a multipart MAC verification operation using Mbed TLS. 105 * 106 * \note The signature of this function is that of a PSA driver mac_verify_setup 107 * entry point. This function behaves as a mac_verify_setup entry point as 108 * defined in the PSA driver interface specification for transparent 109 * drivers. 110 * 111 * \param[in,out] operation The operation object to set up. It must have 112 * been initialized and not yet in use. 113 * \param[in] attributes The attributes of the key to use for the 114 * operation. 115 * \param[in] key_buffer The buffer containing the key to use for 116 * computing the MAC. This buffer contains the key 117 * in export representation as defined by 118 * psa_export_key() (i.e. the raw key bytes). 119 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 120 * \param alg The MAC algorithm to use (\c PSA_ALG_XXX value 121 * such that #PSA_ALG_IS_MAC(\p alg) is true). 122 * 123 * \retval #PSA_SUCCESS 124 * Success. 125 * \retval #PSA_ERROR_NOT_SUPPORTED 126 * \p alg is not supported. 127 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 128 * \retval #PSA_ERROR_CORRUPTION_DETECTED 129 * \retval #PSA_ERROR_BAD_STATE 130 * The operation state is not valid (it must be inactive). 131 */ 132 psa_status_t mbedtls_psa_mac_verify_setup( 133 mbedtls_psa_mac_operation_t *operation, 134 const psa_key_attributes_t *attributes, 135 const uint8_t *key_buffer, 136 size_t key_buffer_size, 137 psa_algorithm_t alg); 138 139 /** Add a message fragment to a multipart MAC operation using Mbed TLS. 140 * 141 * \note The signature of this function is that of a PSA driver mac_update 142 * entry point. This function behaves as a mac_update entry point as 143 * defined in the PSA driver interface specification for transparent 144 * drivers. 145 * 146 * The PSA core calls mbedtls_psa_mac_sign_setup() or 147 * mbedtls_psa_mac_verify_setup() before calling this function. 148 * 149 * If this function returns an error status, the PSA core aborts the 150 * operation by calling mbedtls_psa_mac_abort(). 151 * 152 * \param[in,out] operation Active MAC operation. 153 * \param[in] input Buffer containing the message fragment to add to 154 * the MAC calculation. 155 * \param input_length Size of the \p input buffer in bytes. 156 * 157 * \retval #PSA_SUCCESS 158 * Success. 159 * \retval #PSA_ERROR_BAD_STATE 160 * The operation state is not valid (it must be active). 161 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 162 * \retval #PSA_ERROR_CORRUPTION_DETECTED 163 */ 164 psa_status_t mbedtls_psa_mac_update( 165 mbedtls_psa_mac_operation_t *operation, 166 const uint8_t *input, 167 size_t input_length ); 168 169 /** Finish the calculation of the MAC of a message using Mbed TLS. 170 * 171 * \note The signature of this function is that of a PSA driver mac_sign_finish 172 * entry point. This function behaves as a mac_sign_finish entry point as 173 * defined in the PSA driver interface specification for transparent 174 * drivers. 175 * 176 * The PSA core calls mbedtls_psa_mac_sign_setup() before calling this function. 177 * This function calculates the MAC of the message formed by concatenating 178 * the inputs passed to preceding calls to mbedtls_psa_mac_update(). 179 * 180 * Whether this function returns successfully or not, the PSA core subsequently 181 * aborts the operation by calling mbedtls_psa_mac_abort(). 182 * 183 * \param[in,out] operation Active MAC operation. 184 * \param[out] mac Buffer where the MAC value is to be written. 185 * \param mac_size Output size requested for the MAC algorithm. The PSA 186 * core guarantees this is a valid MAC length for the 187 * algorithm and key combination passed to 188 * mbedtls_psa_mac_sign_setup(). It also guarantees the 189 * \p mac buffer is large enough to contain the 190 * requested output size. 191 * \param[out] mac_length On success, the number of bytes output to buffer 192 * \p mac, which will be equal to the requested length 193 * \p mac_size. 194 * 195 * \retval #PSA_SUCCESS 196 * Success. 197 * \retval #PSA_ERROR_BAD_STATE 198 * The operation state is not valid (it must be an active mac sign 199 * operation). 200 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 201 * The size of the \p mac buffer is too small. A sufficient buffer size 202 * can be determined by calling PSA_MAC_LENGTH(). 203 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 204 * \retval #PSA_ERROR_CORRUPTION_DETECTED 205 */ 206 psa_status_t mbedtls_psa_mac_sign_finish( 207 mbedtls_psa_mac_operation_t *operation, 208 uint8_t *mac, 209 size_t mac_size, 210 size_t *mac_length ); 211 212 /** Finish the calculation of the MAC of a message and compare it with 213 * an expected value using Mbed TLS. 214 * 215 * \note The signature of this function is that of a PSA driver 216 * mac_verify_finish entry point. This function behaves as a 217 * mac_verify_finish entry point as defined in the PSA driver interface 218 * specification for transparent drivers. 219 * 220 * The PSA core calls mbedtls_psa_mac_verify_setup() before calling this 221 * function. This function calculates the MAC of the message formed by 222 * concatenating the inputs passed to preceding calls to 223 * mbedtls_psa_mac_update(). It then compares the calculated MAC with the 224 * expected MAC passed as a parameter to this function. 225 * 226 * Whether this function returns successfully or not, the PSA core subsequently 227 * aborts the operation by calling mbedtls_psa_mac_abort(). 228 * 229 * \param[in,out] operation Active MAC operation. 230 * \param[in] mac Buffer containing the expected MAC value. 231 * \param mac_length Length in bytes of the expected MAC value. The PSA 232 * core guarantees that this length is a valid MAC 233 * length for the algorithm and key combination passed 234 * to mbedtls_psa_mac_verify_setup(). 235 * 236 * \retval #PSA_SUCCESS 237 * The expected MAC is identical to the actual MAC of the message. 238 * \retval #PSA_ERROR_INVALID_SIGNATURE 239 * The MAC of the message was calculated successfully, but it 240 * differs from the expected MAC. 241 * \retval #PSA_ERROR_BAD_STATE 242 * The operation state is not valid (it must be an active mac verify 243 * operation). 244 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 245 * \retval #PSA_ERROR_CORRUPTION_DETECTED 246 */ 247 psa_status_t mbedtls_psa_mac_verify_finish( 248 mbedtls_psa_mac_operation_t *operation, 249 const uint8_t *mac, 250 size_t mac_length ); 251 252 /** Abort a MAC operation using Mbed TLS. 253 * 254 * Aborting an operation frees all associated resources except for the 255 * \p operation structure itself. Once aborted, the operation object 256 * can be reused for another operation by calling 257 * mbedtls_psa_mac_sign_setup() or mbedtls_psa_mac_verify_setup() again. 258 * 259 * The PSA core may call this function any time after the operation object has 260 * been initialized by one of the methods described in 261 * #mbedtls_psa_mac_operation_t. 262 * 263 * In particular, calling mbedtls_psa_mac_abort() after the operation has been 264 * terminated by a call to mbedtls_psa_mac_abort(), 265 * mbedtls_psa_mac_sign_finish() or mbedtls_psa_mac_verify_finish() is safe and 266 * has no effect. 267 * 268 * \param[in,out] operation Initialized MAC operation. 269 * 270 * \retval #PSA_SUCCESS 271 * \retval #PSA_ERROR_CORRUPTION_DETECTED 272 */ 273 psa_status_t mbedtls_psa_mac_abort( 274 mbedtls_psa_mac_operation_t *operation ); 275 276 #endif /* PSA_CRYPTO_MAC_H */ 277