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