xref: /openbmc/qemu/include/crypto/hash.h (revision 88dd060d)
1 /*
2  * QEMU Crypto hash algorithms
3  *
4  * Copyright (c) 2024 Seagate Technology LLC and/or its Affiliates
5  * Copyright (c) 2015 Red Hat, Inc.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19  *
20  */
21 
22 #ifndef QCRYPTO_HASH_H
23 #define QCRYPTO_HASH_H
24 
25 #include "qapi/qapi-types-crypto.h"
26 
27 #define QCRYPTO_HASH_DIGEST_LEN_MD5       16
28 #define QCRYPTO_HASH_DIGEST_LEN_SHA1      20
29 #define QCRYPTO_HASH_DIGEST_LEN_SHA224    28
30 #define QCRYPTO_HASH_DIGEST_LEN_SHA256    32
31 #define QCRYPTO_HASH_DIGEST_LEN_SHA384    48
32 #define QCRYPTO_HASH_DIGEST_LEN_SHA512    64
33 #define QCRYPTO_HASH_DIGEST_LEN_RIPEMD160 20
34 #define QCRYPTO_HASH_DIGEST_LEN_SM3       32
35 
36 /* See also "QCryptoHashAlgo" defined in qapi/crypto.json */
37 
38 typedef struct QCryptoHash QCryptoHash;
39 struct QCryptoHash {
40     QCryptoHashAlgo alg;
41     void *opaque;
42     void *driver;
43 };
44 
45 /**
46  * qcrypto_hash_supports:
47  * @alg: the hash algorithm
48  *
49  * Determine if @alg hash algorithm is supported by the
50  * current configured build.
51  *
52  * Returns: true if the algorithm is supported, false otherwise
53  */
54 gboolean qcrypto_hash_supports(QCryptoHashAlgo alg);
55 
56 
57 /**
58  * qcrypto_hash_digest_len:
59  * @alg: the hash algorithm
60  *
61  * Determine the size of the hash digest in bytes
62  *
63  * Returns: the digest length in bytes
64  */
65 size_t qcrypto_hash_digest_len(QCryptoHashAlgo alg);
66 
67 /**
68  * qcrypto_hash_bytesv:
69  * @alg: the hash algorithm
70  * @iov: the array of memory regions to hash
71  * @niov: the length of @iov
72  * @result: pointer to hold output hash
73  * @resultlen: pointer to hold length of @result
74  * @errp: pointer to a NULL-initialized error object
75  *
76  * Computes the hash across all the memory regions
77  * present in @iov.
78  *
79  * If @result_len is set to a non-zero value by the caller, then
80  * @result must hold a pointer that is @result_len in size, and
81  * @result_len match the size of the hash output. The digest will
82  * be written into @result.
83  *
84  * If @result_len is set to zero, then this function will allocate
85  * a buffer to hold the hash output digest, storing a pointer to
86  * the buffer in @result, and setting @result_len to its size.
87  * The memory referenced in @result must be released with a call
88  * to g_free() when no longer required by the caller.
89  *
90  * Returns: 0 on success, -1 on error
91  */
92 int qcrypto_hash_bytesv(QCryptoHashAlgo alg,
93                         const struct iovec *iov,
94                         size_t niov,
95                         uint8_t **result,
96                         size_t *resultlen,
97                         Error **errp);
98 
99 /**
100  * qcrypto_hash_bytes:
101  * @alg: the hash algorithm
102  * @buf: the memory region to hash
103  * @len: the length of @buf
104  * @result: pointer to hold output hash
105  * @resultlen: pointer to hold length of @result
106  * @errp: pointer to a NULL-initialized error object
107  *
108  * Computes the hash across all the memory region
109  * @buf of length @len.
110  *
111  * If @result_len is set to a non-zero value by the caller, then
112  * @result must hold a pointer that is @result_len in size, and
113  * @result_len match the size of the hash output. The digest will
114  * be written into @result.
115  *
116  * If @result_len is set to zero, then this function will allocate
117  * a buffer to hold the hash output digest, storing a pointer to
118  * the buffer in @result, and setting @result_len to its size.
119  * The memory referenced in @result must be released with a call
120  * to g_free() when no longer required by the caller.
121  *
122  * Returns: 0 on success, -1 on error
123  */
124 int qcrypto_hash_bytes(QCryptoHashAlgo alg,
125                        const char *buf,
126                        size_t len,
127                        uint8_t **result,
128                        size_t *resultlen,
129                        Error **errp);
130 
131 /**
132  * qcrypto_hash_digestv:
133  * @alg: the hash algorithm
134  * @iov: the array of memory regions to hash
135  * @niov: the length of @iov
136  * @digest: pointer to hold output hash
137  * @errp: pointer to a NULL-initialized error object
138  *
139  * Computes the hash across all the memory regions
140  * present in @iov. The @digest pointer will be
141  * filled with the printable hex digest of the computed
142  * hash, which will be terminated by '\0'. The
143  * memory pointer in @digest must be released
144  * with a call to g_free() when no longer required.
145  *
146  * Returns: 0 on success, -1 on error
147  */
148 int qcrypto_hash_digestv(QCryptoHashAlgo alg,
149                          const struct iovec *iov,
150                          size_t niov,
151                          char **digest,
152                          Error **errp);
153 
154 /**
155  * qcrypto_hash_updatev:
156  * @hash: hash object from qcrypto_hash_new
157  * @iov: the array of memory regions to hash
158  * @niov: the length of @iov
159  * @errp: pointer to a NULL-initialized error object
160  *
161  * Updates the given hash object with all the memory regions
162  * present in @iov.
163  *
164  * Returns: 0 on success, -1 on error
165  */
166 int qcrypto_hash_updatev(QCryptoHash *hash,
167                          const struct iovec *iov,
168                          size_t niov,
169                          Error **errp);
170 /**
171  * qcrypto_hash_update:
172  * @hash: hash object from qcrypto_hash_new
173  * @buf: the memory region to hash
174  * @len: the length of @buf
175  * @errp: pointer to a NULL-initialized error object
176  *
177  * Updates the given hash object with the data from
178  * the given buffer.
179  *
180  * Returns: 0 on success, -1 on error
181  */
182 int qcrypto_hash_update(QCryptoHash *hash,
183                         const char *buf,
184                         size_t len,
185                         Error **errp);
186 
187 /**
188  * qcrypto_hash_finalize_digest:
189  * @hash: the hash object to finalize
190  * @digest: pointer to hold output hash
191  * @errp: pointer to a NULL-initialized error object
192  *
193  * Computes the hash from the given hash object. Hash object
194  * is expected to have its data updated from the qcrypto_hash_update function.
195  * The @digest pointer will be filled with the printable hex digest of the
196  * computed hash, which will be terminated by '\0'. The memory pointer
197  * in @digest must be released with a call to g_free() when
198  * no longer required.
199  *
200  * Returns: 0 on success, -1 on error
201  */
202 int qcrypto_hash_finalize_digest(QCryptoHash *hash,
203                                  char **digest,
204                                  Error **errp);
205 
206 /**
207  * qcrypto_hash_finalize_base64:
208  * @hash_ctx: hash object to finalize
209  * @base64: pointer to store the hash result in
210  * @errp: pointer to a NULL-initialized error object
211  *
212  * Computes the hash from the given hash object. Hash object
213  * is expected to have it's data updated from the qcrypto_hash_update function.
214  * The @base64 pointer will be filled with the base64 encoding of the computed
215  * hash, which will be terminated by '\0'. The memory pointer in @base64
216  * must be released with a call to g_free() when no longer required.
217  *
218  * Returns: 0 on success, -1 on error
219  */
220 int qcrypto_hash_finalize_base64(QCryptoHash *hash,
221                                  char **base64,
222                                  Error **errp);
223 
224 /**
225  * qcrypto_hash_finalize_bytes:
226  * @hash_ctx: hash object to finalize
227  * @result: pointer to store the hash result in
228  * @result_len: Pointer to store the length of the result in
229  * @errp: pointer to a NULL-initialized error object
230  *
231  * Computes the hash from the given hash object. Hash object
232  * is expected to have it's data updated from the qcrypto_hash_update function.
233  *
234  * If @result_len is set to a non-zero value by the caller, then
235  * @result must hold a pointer that is @result_len in size, and
236  * @result_len match the size of the hash output. The digest will
237  * be written into @result.
238  *
239  * If @result_len is set to zero, then this function will allocate
240  * a buffer to hold the hash output digest, storing a pointer to
241  * the buffer in @result, and setting @result_len to its size.
242  * The memory referenced in @result must be released with a call
243  * to g_free() when no longer required by the caller.
244  *
245  * Returns: 0 on success, -1 on error
246  */
247 int qcrypto_hash_finalize_bytes(QCryptoHash *hash,
248                                 uint8_t **result,
249                                 size_t *result_len,
250                                 Error **errp);
251 
252 /**
253  * qcrypto_hash_new:
254  * @alg: the hash algorithm
255  * @errp: pointer to a NULL-initialized error object
256  *
257  * Creates a new hashing context for the chosen algorithm for
258  * usage with qcrypto_hash_update.
259  *
260  * Returns: New hash object with the given algorithm, or NULL on error.
261  */
262 QCryptoHash *qcrypto_hash_new(QCryptoHashAlgo alg, Error **errp);
263 
264 /**
265  * qcrypto_hash_free:
266  * @hash: hash object to free
267  *
268  * Frees a hashing context for the chosen algorithm.
269  */
270 void qcrypto_hash_free(QCryptoHash *hash);
271 
272 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHash, qcrypto_hash_free)
273 
274 /**
275  * qcrypto_hash_digest:
276  * @alg: the hash algorithm
277  * @buf: the memory region to hash
278  * @len: the length of @buf
279  * @digest: pointer to hold output hash
280  * @errp: pointer to a NULL-initialized error object
281  *
282  * Computes the hash across all the memory region
283  * @buf of length @len. The @digest pointer will be
284  * filled with the printable hex digest of the computed
285  * hash, which will be terminated by '\0'. The
286  * memory pointer in @digest must be released
287  * with a call to g_free() when no longer required.
288  *
289  * Returns: 0 on success, -1 on error
290  */
291 int qcrypto_hash_digest(QCryptoHashAlgo alg,
292                         const char *buf,
293                         size_t len,
294                         char **digest,
295                         Error **errp);
296 
297 /**
298  * qcrypto_hash_base64v:
299  * @alg: the hash algorithm
300  * @iov: the array of memory regions to hash
301  * @niov: the length of @iov
302  * @base64: pointer to hold output hash
303  * @errp: pointer to a NULL-initialized error object
304  *
305  * Computes the hash across all the memory regions
306  * present in @iov. The @base64 pointer will be
307  * filled with the base64 encoding of the computed
308  * hash, which will be terminated by '\0'. The
309  * memory pointer in @base64 must be released
310  * with a call to g_free() when no longer required.
311  *
312  * Returns: 0 on success, -1 on error
313  */
314 int qcrypto_hash_base64v(QCryptoHashAlgo alg,
315                          const struct iovec *iov,
316                          size_t niov,
317                          char **base64,
318                          Error **errp);
319 
320 /**
321  * qcrypto_hash_base64:
322  * @alg: the hash algorithm
323  * @buf: the memory region to hash
324  * @len: the length of @buf
325  * @base64: pointer to hold output hash
326  * @errp: pointer to a NULL-initialized error object
327  *
328  * Computes the hash across all the memory region
329  * @buf of length @len. The @base64 pointer will be
330  * filled with the base64 encoding of the computed
331  * hash, which will be terminated by '\0'. The
332  * memory pointer in @base64 must be released
333  * with a call to g_free() when no longer required.
334  *
335  * Returns: 0 on success, -1 on error
336  */
337 int qcrypto_hash_base64(QCryptoHashAlgo alg,
338                         const char *buf,
339                         size_t len,
340                         char **base64,
341                         Error **errp);
342 
343 #endif /* QCRYPTO_HASH_H */
344