xref: /openbmc/qemu/include/crypto/hash.h (revision be46e0bf)
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 
35 /* See also "QCryptoHashAlgo" defined in qapi/crypto.json */
36 
37 typedef struct QCryptoHash QCryptoHash;
38 struct QCryptoHash {
39     QCryptoHashAlgo alg;
40     void *opaque;
41     void *driver;
42 };
43 
44 /**
45  * qcrypto_hash_supports:
46  * @alg: the hash algorithm
47  *
48  * Determine if @alg hash algorithm is supported by the
49  * current configured build.
50  *
51  * Returns: true if the algorithm is supported, false otherwise
52  */
53 gboolean qcrypto_hash_supports(QCryptoHashAlgo alg);
54 
55 
56 /**
57  * qcrypto_hash_digest_len:
58  * @alg: the hash algorithm
59  *
60  * Determine the size of the hash digest in bytes
61  *
62  * Returns: the digest length in bytes
63  */
64 size_t qcrypto_hash_digest_len(QCryptoHashAlgo alg);
65 
66 /**
67  * qcrypto_hash_bytesv:
68  * @alg: the hash algorithm
69  * @iov: the array of memory regions to hash
70  * @niov: the length of @iov
71  * @result: pointer to hold output hash
72  * @resultlen: pointer to hold length of @result
73  * @errp: pointer to a NULL-initialized error object
74  *
75  * Computes the hash across all the memory regions
76  * present in @iov. The @result pointer will be
77  * filled with raw bytes representing the computed
78  * hash, which will have length @resultlen. The
79  * memory pointer in @result must be released
80  * with a call to g_free() when no longer required.
81  *
82  * Returns: 0 on success, -1 on error
83  */
84 int qcrypto_hash_bytesv(QCryptoHashAlgo alg,
85                         const struct iovec *iov,
86                         size_t niov,
87                         uint8_t **result,
88                         size_t *resultlen,
89                         Error **errp);
90 
91 /**
92  * qcrypto_hash_bytes:
93  * @alg: the hash algorithm
94  * @buf: the memory region to hash
95  * @len: the length of @buf
96  * @result: pointer to hold output hash
97  * @resultlen: pointer to hold length of @result
98  * @errp: pointer to a NULL-initialized error object
99  *
100  * Computes the hash across all the memory region
101  * @buf of length @len. The @result pointer will be
102  * filled with raw bytes representing the computed
103  * hash, which will have length @resultlen. The
104  * memory pointer in @result must be released
105  * with a call to g_free() when no longer required.
106  *
107  * Returns: 0 on success, -1 on error
108  */
109 int qcrypto_hash_bytes(QCryptoHashAlgo alg,
110                        const char *buf,
111                        size_t len,
112                        uint8_t **result,
113                        size_t *resultlen,
114                        Error **errp);
115 
116 /**
117  * qcrypto_hash_digestv:
118  * @alg: the hash algorithm
119  * @iov: the array of memory regions to hash
120  * @niov: the length of @iov
121  * @digest: pointer to hold output hash
122  * @errp: pointer to a NULL-initialized error object
123  *
124  * Computes the hash across all the memory regions
125  * present in @iov. The @digest pointer will be
126  * filled with the printable hex digest of the computed
127  * hash, which will be terminated by '\0'. The
128  * memory pointer in @digest must be released
129  * with a call to g_free() when no longer required.
130  *
131  * Returns: 0 on success, -1 on error
132  */
133 int qcrypto_hash_digestv(QCryptoHashAlgo alg,
134                          const struct iovec *iov,
135                          size_t niov,
136                          char **digest,
137                          Error **errp);
138 
139 /**
140  * qcrypto_hash_updatev:
141  * @hash: hash object from qcrypto_hash_new
142  * @iov: the array of memory regions to hash
143  * @niov: the length of @iov
144  * @errp: pointer to a NULL-initialized error object
145  *
146  * Updates the given hash object with all the memory regions
147  * present in @iov.
148  *
149  * Returns: 0 on success, -1 on error
150  */
151 int qcrypto_hash_updatev(QCryptoHash *hash,
152                          const struct iovec *iov,
153                          size_t niov,
154                          Error **errp);
155 /**
156  * qcrypto_hash_update:
157  * @hash: hash object from qcrypto_hash_new
158  * @buf: the memory region to hash
159  * @len: the length of @buf
160  * @errp: pointer to a NULL-initialized error object
161  *
162  * Updates the given hash object with the data from
163  * the given buffer.
164  *
165  * Returns: 0 on success, -1 on error
166  */
167 int qcrypto_hash_update(QCryptoHash *hash,
168                         const char *buf,
169                         size_t len,
170                         Error **errp);
171 
172 /**
173  * qcrypto_hash_finalize_digest:
174  * @hash: the hash object to finalize
175  * @digest: pointer to hold output hash
176  * @errp: pointer to a NULL-initialized error object
177  *
178  * Computes the hash from the given hash object. Hash object
179  * is expected to have its data updated from the qcrypto_hash_update function.
180  * The @digest pointer will be filled with the printable hex digest of the
181  * computed hash, which will be terminated by '\0'. The memory pointer
182  * in @digest must be released with a call to g_free() when
183  * no longer required.
184  *
185  * Returns: 0 on success, -1 on error
186  */
187 int qcrypto_hash_finalize_digest(QCryptoHash *hash,
188                                  char **digest,
189                                  Error **errp);
190 
191 /**
192  * qcrypto_hash_finalize_base64:
193  * @hash_ctx: hash object to finalize
194  * @base64: pointer to store the hash result in
195  * @errp: pointer to a NULL-initialized error object
196  *
197  * Computes the hash from the given hash object. Hash object
198  * is expected to have it's data updated from the qcrypto_hash_update function.
199  * The @base64 pointer will be filled with the base64 encoding of the computed
200  * hash, which will be terminated by '\0'. The memory pointer in @base64
201  * must be released with a call to g_free() when no longer required.
202  *
203  * Returns: 0 on success, -1 on error
204  */
205 int qcrypto_hash_finalize_base64(QCryptoHash *hash,
206                                  char **base64,
207                                  Error **errp);
208 
209 /**
210  * qcrypto_hash_finalize_bytes:
211  * @hash_ctx: hash object to finalize
212  * @result: pointer to store the hash result in
213  * @result_len: Pointer to store the length of the result in
214  * @errp: pointer to a NULL-initialized error object
215  *
216  * Computes the hash from the given hash object. Hash object
217  * is expected to have it's data updated from the qcrypto_hash_update function.
218  * The memory pointer in @result must be released with a call to g_free()
219  * when no longer required.
220  *
221  * Returns: 0 on success, -1 on error
222  */
223 int qcrypto_hash_finalize_bytes(QCryptoHash *hash,
224                                 uint8_t **result,
225                                 size_t *result_len,
226                                 Error **errp);
227 
228 /**
229  * qcrypto_hash_new:
230  * @alg: the hash algorithm
231  * @errp: pointer to a NULL-initialized error object
232  *
233  * Creates a new hashing context for the chosen algorithm for
234  * usage with qcrypto_hash_update.
235  *
236  * Returns: New hash object with the given algorithm, or NULL on error.
237  */
238 QCryptoHash *qcrypto_hash_new(QCryptoHashAlgo alg, Error **errp);
239 
240 /**
241  * qcrypto_hash_free:
242  * @hash: hash object to free
243  *
244  * Frees a hashing context for the chosen algorithm.
245  */
246 void qcrypto_hash_free(QCryptoHash *hash);
247 
248 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHash, qcrypto_hash_free)
249 
250 /**
251  * qcrypto_hash_digest:
252  * @alg: the hash algorithm
253  * @buf: the memory region to hash
254  * @len: the length of @buf
255  * @digest: pointer to hold output hash
256  * @errp: pointer to a NULL-initialized error object
257  *
258  * Computes the hash across all the memory region
259  * @buf of length @len. The @digest pointer will be
260  * filled with the printable hex digest of the computed
261  * hash, which will be terminated by '\0'. The
262  * memory pointer in @digest must be released
263  * with a call to g_free() when no longer required.
264  *
265  * Returns: 0 on success, -1 on error
266  */
267 int qcrypto_hash_digest(QCryptoHashAlgo alg,
268                         const char *buf,
269                         size_t len,
270                         char **digest,
271                         Error **errp);
272 
273 /**
274  * qcrypto_hash_base64v:
275  * @alg: the hash algorithm
276  * @iov: the array of memory regions to hash
277  * @niov: the length of @iov
278  * @base64: pointer to hold output hash
279  * @errp: pointer to a NULL-initialized error object
280  *
281  * Computes the hash across all the memory regions
282  * present in @iov. The @base64 pointer will be
283  * filled with the base64 encoding of the computed
284  * hash, which will be terminated by '\0'. The
285  * memory pointer in @base64 must be released
286  * with a call to g_free() when no longer required.
287  *
288  * Returns: 0 on success, -1 on error
289  */
290 int qcrypto_hash_base64v(QCryptoHashAlgo alg,
291                          const struct iovec *iov,
292                          size_t niov,
293                          char **base64,
294                          Error **errp);
295 
296 /**
297  * qcrypto_hash_base64:
298  * @alg: the hash algorithm
299  * @buf: the memory region to hash
300  * @len: the length of @buf
301  * @base64: pointer to hold output hash
302  * @errp: pointer to a NULL-initialized error object
303  *
304  * Computes the hash across all the memory region
305  * @buf of length @len. The @base64 pointer will be
306  * filled with the base64 encoding of the computed
307  * hash, which will be terminated by '\0'. The
308  * memory pointer in @base64 must be released
309  * with a call to g_free() when no longer required.
310  *
311  * Returns: 0 on success, -1 on error
312  */
313 int qcrypto_hash_base64(QCryptoHashAlgo alg,
314                         const char *buf,
315                         size_t len,
316                         char **base64,
317                         Error **errp);
318 
319 #endif /* QCRYPTO_HASH_H */
320