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

Go to the SVN repository for this file.

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  */
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  */
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  */
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  */
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  */
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  */
210 
211 #endif /* PSA_CRYPTO_HASH_H */
Platform Security Architecture cryptography module.
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_hash_clone(const mbedtls_psa_hash_operation_t *source_operation, mbedtls_psa_hash_operation_t *target_operation)
Clone an Mbed TLS hash operation.
psa_status_t mbedtls_psa_hash_setup(mbedtls_psa_hash_operation_t *operation, psa_algorithm_t alg)
Set up a multipart hash operation using Mbed TLS routines.
psa_status_t mbedtls_psa_hash_finish(mbedtls_psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
Finish the calculation of the Mbed TLS-calculated hash of a message.
psa_status_t mbedtls_psa_hash_abort(mbedtls_psa_hash_operation_t *operation)
Abort an Mbed TLS hash operation.
psa_status_t mbedtls_psa_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)
Calculate the hash (digest) of a message using Mbed TLS routines.
psa_status_t mbedtls_psa_hash_update(mbedtls_psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart Mbed TLS hash operation.
Definition: _hash_fun.h:40
Modified on Fri Jul 19 17:16:49 2024 by modify_doxy.py rev. 669887