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 \emptydescription
56 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
57 */
58psa_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 \emptydescription
93 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
94 * \retval #PSA_ERROR_BAD_STATE
95 *         The operation state is not valid (it must be inactive).
96 */
97psa_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 \emptydescription
128 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
129 * \retval #PSA_ERROR_BAD_STATE
130 *         The operation state is not valid (it must be inactive).
131 */
132psa_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 \emptydescription
162 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
163 */
164psa_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 \emptydescription
204 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
205 */
206psa_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 \emptydescription
245 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
246 */
247psa_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 \emptydescription
271 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
272 */
273psa_status_t mbedtls_psa_mac_abort(
274    mbedtls_psa_mac_operation_t *operation);
275
276#endif /* PSA_CRYPTO_MAC_H */
277