Merge remote-tracking branch 'remotes/kraxel/tags/pull-vga-20170103-1' into staging
[qemu.git] / crypto / hmac.h
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-types.h"
16
17 typedef struct QCryptoHmac QCryptoHmac;
18 struct QCryptoHmac {
19 QCryptoHashAlgorithm alg;
20 void *opaque;
21 };
22
23 /**
24 * qcrypto_hmac_supports:
25 * @alg: the hmac algorithm
26 *
27 * Determine if @alg hmac algorithm is supported by
28 * the current configured build
29 *
30 * Returns:
31 * true if the algorithm is supported, false otherwise
32 */
33 bool qcrypto_hmac_supports(QCryptoHashAlgorithm alg);
34
35 /**
36 * qcrypto_hmac_new:
37 * @alg: the hmac algorithm
38 * @key: the key bytes
39 * @nkey: the length of @key
40 * @errp: pointer to a NULL-initialized error object
41 *
42 * Creates a new hmac object with the algorithm @alg
43 *
44 * The @key parameter provides the bytes representing
45 * the secret key to use. The @nkey parameter specifies
46 * the length of @key in bytes
47 *
48 * Note: must use qcrypto_hmac_free() to release the
49 * returned hmac object when no longer required
50 *
51 * Returns:
52 * a new hmac object, or NULL on error
53 */
54 QCryptoHmac *qcrypto_hmac_new(QCryptoHashAlgorithm alg,
55 const uint8_t *key, size_t nkey,
56 Error **errp);
57
58 /**
59 * qcrypto_hmac_free:
60 * @hmac: the hmac object
61 *
62 * Release the memory associated with @hmac that was
63 * previously allocated by qcrypto_hmac_new()
64 */
65 void qcrypto_hmac_free(QCryptoHmac *hmac);
66
67 /**
68 * qcrypto_hmac_bytesv:
69 * @hmac: the hmac object
70 * @iov: the array of memory regions to hmac
71 * @niov: the length of @iov
72 * @result: pointer to hold output hmac
73 * @resultlen: pointer to hold length of @result
74 * @errp: pointer to a NULL-initialized error object
75 *
76 * Computes the hmac across all the memory regions
77 * present in @iov. The @result pointer will be
78 * filled with raw bytes representing the computed
79 * hmac, which will have length @resultlen. The
80 * memory pointer in @result must be released
81 * with a call to g_free() when no longer required.
82 *
83 * Returns:
84 * 0 on success, -1 on error
85 */
86 int qcrypto_hmac_bytesv(QCryptoHmac *hmac,
87 const struct iovec *iov,
88 size_t niov,
89 uint8_t **result,
90 size_t *resultlen,
91 Error **errp);
92
93 /**
94 * qcrypto_hmac_bytes:
95 * @hmac: the hmac object
96 * @buf: the memory region to hmac
97 * @len: the length of @buf
98 * @result: pointer to hold output hmac
99 * @resultlen: pointer to hold length of @result
100 * @errp: pointer to a NULL-initialized error object
101 *
102 * Computes the hmac across all the memory region
103 * @buf of length @len. The @result pointer will be
104 * filled with raw bytes representing the computed
105 * hmac, which will have length @resultlen. The
106 * memory pointer in @result must be released
107 * with a call to g_free() when no longer required.
108 *
109 * Returns:
110 * 0 on success, -1 on error
111 */
112 int qcrypto_hmac_bytes(QCryptoHmac *hmac,
113 const char *buf,
114 size_t len,
115 uint8_t **result,
116 size_t *resultlen,
117 Error **errp);
118
119 /**
120 * qcrypto_hmac_digestv:
121 * @hmac: the hmac object
122 * @iov: the array of memory regions to hmac
123 * @niov: the length of @iov
124 * @digest: pointer to hold output hmac
125 * @errp: pointer to a NULL-initialized error object
126 *
127 * Computes the hmac across all the memory regions
128 * present in @iov. The @digest pointer will be
129 * filled with the printable hex digest of the computed
130 * hmac, which will be terminated by '\0'. The
131 * memory pointer in @digest must be released
132 * with a call to g_free() when no longer required.
133 *
134 * Returns:
135 * 0 on success, -1 on error
136 */
137 int qcrypto_hmac_digestv(QCryptoHmac *hmac,
138 const struct iovec *iov,
139 size_t niov,
140 char **digest,
141 Error **errp);
142
143 /**
144 * qcrypto_hmac_digest:
145 * @hmac: the hmac object
146 * @buf: the memory region to hmac
147 * @len: the length of @buf
148 * @digest: pointer to hold output hmac
149 * @errp: pointer to a NULL-initialized error object
150 *
151 * Computes the hmac across all the memory region
152 * @buf of length @len. The @digest pointer will be
153 * filled with the printable hex digest of the computed
154 * hmac, which will be terminated by '\0'. The
155 * memory pointer in @digest must be released
156 * with a call to g_free() when no longer required.
157 *
158 * Returns: 0 on success, -1 on error
159 */
160 int qcrypto_hmac_digest(QCryptoHmac *hmac,
161 const char *buf,
162 size_t len,
163 char **digest,
164 Error **errp);
165
166 #endif