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 <mbedtls/md_internal.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