xref: /openbmc/qemu/include/crypto/hmac.h (revision ca5aa28e)
1 /*
2  * QEMU Crypto hmac algorithms
3  *
4  * Copyright (c) 2016 HUAWEI TECHNOLOGIES CO., LTD.
5  *
6  * This work is licensed under the terms of the GNU GPL, version 2 or
7  * (at your option) any later version.  See the COPYING file in the
8  * top-level directory.
9  *
10  */
11 
12 #ifndef QCRYPTO_HMAC_H
13 #define QCRYPTO_HMAC_H
14 
15 #include "qapi/qapi-types-crypto.h"
16 
17 typedef struct QCryptoHmac QCryptoHmac;
18 struct QCryptoHmac {
19     QCryptoHashAlgo alg;
20     void *opaque;
21     void *driver;
22 };
23 
24 /**
25  * qcrypto_hmac_supports:
26  * @alg: the hmac algorithm
27  *
28  * Determine if @alg hmac algorithm is supported by
29  * the current configured build
30  *
31  * Returns:
32  *  true if the algorithm is supported, false otherwise
33  */
34 bool qcrypto_hmac_supports(QCryptoHashAlgo alg);
35 
36 /**
37  * qcrypto_hmac_new:
38  * @alg: the hmac algorithm
39  * @key: the key bytes
40  * @nkey: the length of @key
41  * @errp: pointer to a NULL-initialized error object
42  *
43  * Creates a new hmac object with the algorithm @alg
44  *
45  * The @key parameter provides the bytes representing
46  * the secret key to use. The @nkey parameter specifies
47  * the length of @key in bytes
48  *
49  * Note: must use qcrypto_hmac_free() to release the
50  * returned hmac object when no longer required
51  *
52  * Returns:
53  *  a new hmac object, or NULL on error
54  */
55 QCryptoHmac *qcrypto_hmac_new(QCryptoHashAlgo alg,
56                               const uint8_t *key, size_t nkey,
57                               Error **errp);
58 
59 /**
60  * qcrypto_hmac_free:
61  * @hmac: the hmac object
62  *
63  * Release the memory associated with @hmac that was
64  * previously allocated by qcrypto_hmac_new()
65  */
66 void qcrypto_hmac_free(QCryptoHmac *hmac);
67 
68 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHmac, qcrypto_hmac_free)
69 
70 /**
71  * qcrypto_hmac_bytesv:
72  * @hmac: the hmac object
73  * @iov: the array of memory regions to hmac
74  * @niov: the length of @iov
75  * @result: pointer to hold output hmac
76  * @resultlen: pointer to hold length of @result
77  * @errp: pointer to a NULL-initialized error object
78  *
79  * Computes the hmac across all the memory regions
80  * present in @iov.
81  *
82  * If @result_len is set to a non-zero value by the caller, then
83  * @result must hold a pointer that is @result_len in size, and
84  * @result_len match the size of the hash output. The digest will
85  * be written into @result.
86  *
87  * If @result_len is set to zero, then this function will allocate
88  * a buffer to hold the hash output digest, storing a pointer to
89  * the buffer in @result, and setting @result_len to its size.
90  * The memory referenced in @result must be released with a call
91  * to g_free() when no longer required by the caller.
92  *
93  * Returns:
94  *  0 on success, -1 on error
95  */
96 int qcrypto_hmac_bytesv(QCryptoHmac *hmac,
97                         const struct iovec *iov,
98                         size_t niov,
99                         uint8_t **result,
100                         size_t *resultlen,
101                         Error **errp);
102 
103 /**
104  * qcrypto_hmac_bytes:
105  * @hmac: the hmac object
106  * @buf: the memory region to hmac
107  * @len: the length of @buf
108  * @result: pointer to hold output hmac
109  * @resultlen: pointer to hold length of @result
110  * @errp: pointer to a NULL-initialized error object
111  *
112  * Computes the hmac across all the memory region
113  * @buf of length @len.
114  *
115  * If @result_len is set to a non-zero value by the caller, then
116  * @result must hold a pointer that is @result_len in size, and
117  * @result_len match the size of the hash output. The digest will
118  * be written into @result.
119  *
120  * If @result_len is set to zero, then this function will allocate
121  * a buffer to hold the hash output digest, storing a pointer to
122  * the buffer in @result, and setting @result_len to its size.
123  * The memory referenced in @result must be released with a call
124  * to g_free() when no longer required by the caller.
125  *
126  * Returns:
127  *  0 on success, -1 on error
128  */
129 int qcrypto_hmac_bytes(QCryptoHmac *hmac,
130                        const char *buf,
131                        size_t len,
132                        uint8_t **result,
133                        size_t *resultlen,
134                        Error **errp);
135 
136 /**
137  * qcrypto_hmac_digestv:
138  * @hmac: the hmac object
139  * @iov: the array of memory regions to hmac
140  * @niov: the length of @iov
141  * @digest: pointer to hold output hmac
142  * @errp: pointer to a NULL-initialized error object
143  *
144  * Computes the hmac across all the memory regions
145  * present in @iov. The @digest pointer will be
146  * filled with the printable hex digest of the computed
147  * hmac, which will be terminated by '\0'. The
148  * memory pointer in @digest must be released
149  * with a call to g_free() when no longer required.
150  *
151  * Returns:
152  *  0 on success, -1 on error
153  */
154 int qcrypto_hmac_digestv(QCryptoHmac *hmac,
155                          const struct iovec *iov,
156                          size_t niov,
157                          char **digest,
158                          Error **errp);
159 
160 /**
161  * qcrypto_hmac_digest:
162  * @hmac: the hmac object
163  * @buf: the memory region to hmac
164  * @len: the length of @buf
165  * @digest: pointer to hold output hmac
166  * @errp: pointer to a NULL-initialized error object
167  *
168  * Computes the hmac across all the memory region
169  * @buf of length @len. The @digest pointer will be
170  * filled with the printable hex digest of the computed
171  * hmac, which will be terminated by '\0'. The
172  * memory pointer in @digest must be released
173  * with a call to g_free() when no longer required.
174  *
175  * Returns: 0 on success, -1 on error
176  */
177 int qcrypto_hmac_digest(QCryptoHmac *hmac,
178                         const char *buf,
179                         size_t len,
180                         char **digest,
181                         Error **errp);
182 
183 #endif
184