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 "md_wrap.h"
27 
28 /** Calculate the hash (digest) of a message using Mbed TLS routines.
29  *
30  * \note The signature of this function is that of a PSA driver hash_compute
31  *       entry point. This function behaves as a hash_compute entry point as
32  *       defined in the PSA driver interface specification for transparent
33  *       drivers.
34  *
35  * \param alg               The hash algorithm to compute (\c PSA_ALG_XXX value
36  *                          such that #PSA_ALG_IS_HASH(\p alg) is true).
37  * \param[in] input         Buffer containing the message to hash.
38  * \param input_length      Size of the \p input buffer in bytes.
39  * \param[out] hash         Buffer where the hash is to be written.
40  * \param hash_size         Size of the \p hash buffer in bytes.
41  * \param[out] hash_length  On success, the number of bytes
42  *                          that make up the hash value. This is always
43  *                          #PSA_HASH_LENGTH(\p alg).
44  *
45  * \retval #PSA_SUCCESS
46  *         Success.
47  * \retval #PSA_ERROR_NOT_SUPPORTED
48  *         \p alg is not supported
49  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
50  *         \p hash_size is too small
51  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
52  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
53  */
54 psa_status_t mbedtls_psa_hash_compute(
55     psa_algorithm_t alg,
56     const uint8_t *input,
57     size_t input_length,
58     uint8_t *hash,
59     size_t hash_size,
60     size_t *hash_length);
61 
62 /** Set up a multipart hash operation using Mbed TLS routines.
63  *
64  * \note The signature of this function is that of a PSA driver hash_setup
65  *       entry point. This function behaves as a hash_setup entry point as
66  *       defined in the PSA driver interface specification for transparent
67  *       drivers.
68  *
69  * If an error occurs at any step after a call to mbedtls_psa_hash_setup(), the
70  * operation will need to be reset by a call to mbedtls_psa_hash_abort(). The
71  * core may call mbedtls_psa_hash_abort() at any time after the operation
72  * has been initialized.
73  *
74  * After a successful call to mbedtls_psa_hash_setup(), the core must
75  * eventually terminate the operation. The following events terminate an
76  * operation:
77  * - A successful call to mbedtls_psa_hash_finish() or mbedtls_psa_hash_verify().
78  * - A call to mbedtls_psa_hash_abort().
79  *
80  * \param[in,out] operation The operation object to set up. It must have
81  *                          been initialized to all-zero and not yet be in use.
82  * \param alg               The hash algorithm to compute (\c PSA_ALG_XXX value
83  *                          such that #PSA_ALG_IS_HASH(\p alg) is true).
84  *
85  * \retval #PSA_SUCCESS
86  *         Success.
87  * \retval #PSA_ERROR_NOT_SUPPORTED
88  *         \p alg is not supported
89  * \retval #PSA_ERROR_BAD_STATE
90  *         The operation state is not valid (it must be inactive).
91  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
92  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
93  */
94 psa_status_t mbedtls_psa_hash_setup(
95     mbedtls_psa_hash_operation_t *operation,
96     psa_algorithm_t alg);
97 
98 /** Clone an Mbed TLS hash operation.
99  *
100  * \note The signature of this function is that of a PSA driver hash_clone
101  *       entry point. This function behaves as a hash_clone entry point as
102  *       defined in the PSA driver interface specification for transparent
103  *       drivers.
104  *
105  * This function copies the state of an ongoing hash operation to
106  * a new operation object. In other words, this function is equivalent
107  * to calling mbedtls_psa_hash_setup() on \p target_operation with the same
108  * algorithm that \p source_operation was set up for, then
109  * mbedtls_psa_hash_update() on \p target_operation with the same input that
110  * that was passed to \p source_operation. After this function returns, the
111  * two objects are independent, i.e. subsequent calls involving one of
112  * the objects do not affect the other object.
113  *
114  * \param[in] source_operation      The active hash operation to clone.
115  * \param[in,out] target_operation  The operation object to set up.
116  *                                  It must be initialized but not active.
117  *
118  * \retval #PSA_SUCCESS \emptydescription
119  * \retval #PSA_ERROR_BAD_STATE
120  *         The \p source_operation state is not valid (it must be active).
121  * \retval #PSA_ERROR_BAD_STATE
122  *         The \p target_operation state is not valid (it must be inactive).
123  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
124  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
125  */
126 psa_status_t mbedtls_psa_hash_clone(
127     const mbedtls_psa_hash_operation_t *source_operation,
128     mbedtls_psa_hash_operation_t *target_operation);
129 
130 /** Add a message fragment to a multipart Mbed TLS hash operation.
131  *
132  * \note The signature of this function is that of a PSA driver hash_update
133  *       entry point. This function behaves as a hash_update entry point as
134  *       defined in the PSA driver interface specification for transparent
135  *       drivers.
136  *
137  * The application must call mbedtls_psa_hash_setup() before calling this function.
138  *
139  * If this function returns an error status, the operation enters an error
140  * state and must be aborted by calling mbedtls_psa_hash_abort().
141  *
142  * \param[in,out] operation Active hash operation.
143  * \param[in] input         Buffer containing the message fragment to hash.
144  * \param input_length      Size of the \p input buffer in bytes.
145  *
146  * \retval #PSA_SUCCESS
147  *         Success.
148  * \retval #PSA_ERROR_BAD_STATE
149  *         The operation state is not valid (it must be active).
150  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
151  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
152  */
153 psa_status_t mbedtls_psa_hash_update(
154     mbedtls_psa_hash_operation_t *operation,
155     const uint8_t *input,
156     size_t input_length);
157 
158 /** Finish the calculation of the Mbed TLS-calculated hash of a message.
159  *
160  * \note The signature of this function is that of a PSA driver hash_finish
161  *       entry point. This function behaves as a hash_finish entry point as
162  *       defined in the PSA driver interface specification for transparent
163  *       drivers.
164  *
165  * The application must call mbedtls_psa_hash_setup() before calling this function.
166  * This function calculates the hash of the message formed by concatenating
167  * the inputs passed to preceding calls to mbedtls_psa_hash_update().
168  *
169  * When this function returns successfully, the operation becomes inactive.
170  * If this function returns an error status, the operation enters an error
171  * state and must be aborted by calling mbedtls_psa_hash_abort().
172  *
173  * \param[in,out] operation     Active hash operation.
174  * \param[out] hash             Buffer where the hash is to be written.
175  * \param hash_size             Size of the \p hash buffer in bytes.
176  * \param[out] hash_length      On success, the number of bytes
177  *                              that make up the hash value. This is always
178  *                              #PSA_HASH_LENGTH(\c alg) where \c alg is the
179  *                              hash algorithm that is calculated.
180  *
181  * \retval #PSA_SUCCESS
182  *         Success.
183  * \retval #PSA_ERROR_BAD_STATE
184  *         The operation state is not valid (it must be active).
185  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
186  *         The size of the \p hash buffer is too small. You can determine a
187  *         sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg)
188  *         where \c alg is the hash algorithm that is calculated.
189  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
190  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
191  */
192 psa_status_t mbedtls_psa_hash_finish(
193     mbedtls_psa_hash_operation_t *operation,
194     uint8_t *hash,
195     size_t hash_size,
196     size_t *hash_length);
197 
198 /** Abort an Mbed TLS hash operation.
199  *
200  * \note The signature of this function is that of a PSA driver hash_abort
201  *       entry point. This function behaves as a hash_abort entry point as
202  *       defined in the PSA driver interface specification for transparent
203  *       drivers.
204  *
205  * Aborting an operation frees all associated resources except for the
206  * \p operation structure itself. Once aborted, the operation object
207  * can be reused for another operation by calling
208  * mbedtls_psa_hash_setup() again.
209  *
210  * You may call this function any time after the operation object has
211  * been initialized by one of the methods described in #psa_hash_operation_t.
212  *
213  * In particular, calling mbedtls_psa_hash_abort() after the operation has been
214  * terminated by a call to mbedtls_psa_hash_abort(), mbedtls_psa_hash_finish() or
215  * mbedtls_psa_hash_verify() is safe and has no effect.
216  *
217  * \param[in,out] operation     Initialized hash operation.
218  *
219  * \retval #PSA_SUCCESS \emptydescription
220  * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
221  */
222 psa_status_t mbedtls_psa_hash_abort(
223     mbedtls_psa_hash_operation_t *operation);
224 
225 #endif /* PSA_CRYPTO_HASH_H */
226