qapi: enable use of g_autoptr with QAPI types
[qemu.git] / include / crypto / block.h
1 /*
2 * QEMU Crypto block device encryption
3 *
4 * Copyright (c) 2015-2016 Red Hat, Inc.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 *
19 */
20
21 #ifndef QCRYPTO_BLOCK_H
22 #define QCRYPTO_BLOCK_H
23
24 #include "crypto/cipher.h"
25 #include "crypto/ivgen.h"
26
27 typedef struct QCryptoBlock QCryptoBlock;
28
29 /* See also QCryptoBlockFormat, QCryptoBlockCreateOptions
30 * and QCryptoBlockOpenOptions in qapi/crypto.json */
31
32 typedef ssize_t (*QCryptoBlockReadFunc)(QCryptoBlock *block,
33 size_t offset,
34 uint8_t *buf,
35 size_t buflen,
36 void *opaque,
37 Error **errp);
38
39 typedef ssize_t (*QCryptoBlockInitFunc)(QCryptoBlock *block,
40 size_t headerlen,
41 void *opaque,
42 Error **errp);
43
44 typedef ssize_t (*QCryptoBlockWriteFunc)(QCryptoBlock *block,
45 size_t offset,
46 const uint8_t *buf,
47 size_t buflen,
48 void *opaque,
49 Error **errp);
50
51 /**
52 * qcrypto_block_has_format:
53 * @format: the encryption format
54 * @buf: the data from head of the volume
55 * @len: the length of @buf in bytes
56 *
57 * Given @len bytes of data from the head of a storage volume
58 * in @buf, probe to determine if the volume has the encryption
59 * format specified in @format.
60 *
61 * Returns: true if the data in @buf matches @format
62 */
63 bool qcrypto_block_has_format(QCryptoBlockFormat format,
64 const uint8_t *buf,
65 size_t buflen);
66
67 typedef enum {
68 QCRYPTO_BLOCK_OPEN_NO_IO = (1 << 0),
69 } QCryptoBlockOpenFlags;
70
71 /**
72 * qcrypto_block_open:
73 * @options: the encryption options
74 * @optprefix: name prefix for options
75 * @readfunc: callback for reading data from the volume
76 * @opaque: data to pass to @readfunc
77 * @flags: bitmask of QCryptoBlockOpenFlags values
78 * @n_threads: allow concurrent I/O from up to @n_threads threads
79 * @errp: pointer to a NULL-initialized error object
80 *
81 * Create a new block encryption object for an existing
82 * storage volume encrypted with format identified by
83 * the parameters in @options.
84 *
85 * This will use @readfunc to initialize the encryption
86 * context based on the volume header(s), extracting the
87 * master key(s) as required.
88 *
89 * If @flags contains QCRYPTO_BLOCK_OPEN_NO_IO then
90 * the open process will be optimized to skip any parts
91 * that are only required to perform I/O. In particular
92 * this would usually avoid the need to decrypt any
93 * master keys. The only thing that can be done with
94 * the resulting QCryptoBlock object would be to query
95 * metadata such as the payload offset. There will be
96 * no cipher or ivgen objects available.
97 *
98 * If any part of initializing the encryption context
99 * fails an error will be returned. This could be due
100 * to the volume being in the wrong format, a cipher
101 * or IV generator algorithm that is not supported,
102 * or incorrect passphrases.
103 *
104 * Returns: a block encryption format, or NULL on error
105 */
106 QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options,
107 const char *optprefix,
108 QCryptoBlockReadFunc readfunc,
109 void *opaque,
110 unsigned int flags,
111 size_t n_threads,
112 Error **errp);
113
114 /**
115 * qcrypto_block_create:
116 * @options: the encryption options
117 * @optprefix: name prefix for options
118 * @initfunc: callback for initializing volume header
119 * @writefunc: callback for writing data to the volume header
120 * @opaque: data to pass to @initfunc and @writefunc
121 * @errp: pointer to a NULL-initialized error object
122 *
123 * Create a new block encryption object for initializing
124 * a storage volume to be encrypted with format identified
125 * by the parameters in @options.
126 *
127 * This method will allocate space for a new volume header
128 * using @initfunc and then write header data using @writefunc,
129 * generating new master keys, etc as required. Any existing
130 * data present on the volume will be irrevocably destroyed.
131 *
132 * If any part of initializing the encryption context
133 * fails an error will be returned. This could be due
134 * to the volume being in the wrong format, a cipher
135 * or IV generator algorithm that is not supported,
136 * or incorrect passphrases.
137 *
138 * Returns: a block encryption format, or NULL on error
139 */
140 QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options,
141 const char *optprefix,
142 QCryptoBlockInitFunc initfunc,
143 QCryptoBlockWriteFunc writefunc,
144 void *opaque,
145 Error **errp);
146
147 /**
148 * qcrypto_block_amend_options:
149 * @block: the block encryption object
150 *
151 * @readfunc: callback for reading data from the volume header
152 * @writefunc: callback for writing data to the volume header
153 * @opaque: data to pass to @readfunc and @writefunc
154 * @options: the new/amended encryption options
155 * @force: hint for the driver to allow unsafe operation
156 * @errp: error pointer
157 *
158 * Changes the crypto options of the encryption format
159 *
160 */
161 int qcrypto_block_amend_options(QCryptoBlock *block,
162 QCryptoBlockReadFunc readfunc,
163 QCryptoBlockWriteFunc writefunc,
164 void *opaque,
165 QCryptoBlockAmendOptions *options,
166 bool force,
167 Error **errp);
168
169
170 /**
171 * qcrypto_block_calculate_payload_offset:
172 * @create_opts: the encryption options
173 * @optprefix: name prefix for options
174 * @len: output for number of header bytes before payload
175 * @errp: pointer to a NULL-initialized error object
176 *
177 * Calculate the number of header bytes before the payload in an encrypted
178 * storage volume. The header is an area before the payload that is reserved
179 * for encryption metadata.
180 *
181 * Returns: true on success, false on error
182 */
183 bool
184 qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions *create_opts,
185 const char *optprefix,
186 size_t *len,
187 Error **errp);
188
189
190 /**
191 * qcrypto_block_get_info:
192 * @block: the block encryption object
193 * @errp: pointer to a NULL-initialized error object
194 *
195 * Get information about the configuration options for the
196 * block encryption object. This includes details such as
197 * the cipher algorithms, modes, and initialization vector
198 * generators.
199 *
200 * Returns: a block encryption info object, or NULL on error
201 */
202 QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block,
203 Error **errp);
204
205 /**
206 * @qcrypto_block_decrypt:
207 * @block: the block encryption object
208 * @offset: the position at which @iov was read
209 * @buf: the buffer to decrypt
210 * @len: the length of @buf in bytes
211 * @errp: pointer to a NULL-initialized error object
212 *
213 * Decrypt @len bytes of cipher text in @buf, writing
214 * plain text back into @buf. @len and @offset must be
215 * a multiple of the encryption format sector size.
216 *
217 * Returns 0 on success, -1 on failure
218 */
219 int qcrypto_block_decrypt(QCryptoBlock *block,
220 uint64_t offset,
221 uint8_t *buf,
222 size_t len,
223 Error **errp);
224
225 /**
226 * @qcrypto_block_encrypt:
227 * @block: the block encryption object
228 * @offset: the position at which @iov will be written
229 * @buf: the buffer to decrypt
230 * @len: the length of @buf in bytes
231 * @errp: pointer to a NULL-initialized error object
232 *
233 * Encrypt @len bytes of plain text in @buf, writing
234 * cipher text back into @buf. @len and @offset must be
235 * a multiple of the encryption format sector size.
236 *
237 * Returns 0 on success, -1 on failure
238 */
239 int qcrypto_block_encrypt(QCryptoBlock *block,
240 uint64_t offset,
241 uint8_t *buf,
242 size_t len,
243 Error **errp);
244
245 /**
246 * qcrypto_block_get_cipher:
247 * @block: the block encryption object
248 *
249 * Get the cipher to use for payload encryption
250 *
251 * Returns: the cipher object
252 */
253 QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block);
254
255 /**
256 * qcrypto_block_get_ivgen:
257 * @block: the block encryption object
258 *
259 * Get the initialization vector generator to use for
260 * payload encryption
261 *
262 * Returns: the IV generator object
263 */
264 QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block);
265
266
267 /**
268 * qcrypto_block_get_kdf_hash:
269 * @block: the block encryption object
270 *
271 * Get the hash algorithm used with the key derivation
272 * function
273 *
274 * Returns: the hash algorithm
275 */
276 QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block);
277
278 /**
279 * qcrypto_block_get_payload_offset:
280 * @block: the block encryption object
281 *
282 * Get the offset to the payload indicated by the
283 * encryption header, in bytes.
284 *
285 * Returns: the payload offset in bytes
286 */
287 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block);
288
289 /**
290 * qcrypto_block_get_sector_size:
291 * @block: the block encryption object
292 *
293 * Get the size of sectors used for payload encryption. A new
294 * IV is used at the start of each sector. The encryption
295 * sector size is not required to match the sector size of the
296 * underlying storage. For example LUKS will always use a 512
297 * byte sector size, even if the volume is on a disk with 4k
298 * sectors.
299 *
300 * Returns: the sector in bytes
301 */
302 uint64_t qcrypto_block_get_sector_size(QCryptoBlock *block);
303
304 /**
305 * qcrypto_block_free:
306 * @block: the block encryption object
307 *
308 * Release all resources associated with the encryption
309 * object
310 */
311 void qcrypto_block_free(QCryptoBlock *block);
312
313 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free)
314
315 #endif /* QCRYPTO_BLOCK_H */