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