NCBI C++ ToolKit
psa_crypto_mac.h
Go to the documentation of this file.

Go to the SVN repository for this file.

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  */
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  */
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  */
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  */
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  */
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  */
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  */
263 
264 #endif /* PSA_CRYPTO_MAC_H */
Platform Security Architecture cryptography module.
static const struct attribute attributes[]
Definition: attributes.c:165
unsigned char uint8_t
operation
Bit operations.
Definition: bmconst.h:191
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:134
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:59
static int input()
psa_status_t mbedtls_psa_mac_compute(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)
Calculate the MAC (message authentication code) of a message using Mbed TLS.
psa_status_t mbedtls_psa_mac_verify_finish(mbedtls_psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
Finish the calculation of the MAC of a message and compare it with an expected value using Mbed TLS.
psa_status_t mbedtls_psa_mac_update(mbedtls_psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart MAC operation using Mbed TLS.
psa_status_t mbedtls_psa_mac_verify_setup(mbedtls_psa_mac_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg)
Set up a multipart MAC verification operation using Mbed TLS.
psa_status_t mbedtls_psa_mac_abort(mbedtls_psa_mac_operation_t *operation)
Abort a MAC operation using Mbed TLS.
psa_status_t mbedtls_psa_mac_sign_finish(mbedtls_psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length)
Finish the calculation of the MAC of a message using Mbed TLS.
psa_status_t mbedtls_psa_mac_sign_setup(mbedtls_psa_mac_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg)
Set up a multipart MAC calculation operation using Mbed TLS.
Modified on Sun Jul 14 05:00:10 2024 by modify_doxy.py rev. 669887