]>
Commit | Line | Data |
---|---|---|
7d969014 DB |
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 | |
b7cbb874 | 9 | * version 2.1 of the License, or (at your option) any later version. |
7d969014 DB |
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 | ||
2a6a4076 MA |
21 | #ifndef QCRYPTO_BLOCK_H |
22 | #define QCRYPTO_BLOCK_H | |
7d969014 DB |
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 | ||
757dda54 AF |
32 | typedef int (*QCryptoBlockReadFunc)(QCryptoBlock *block, |
33 | size_t offset, | |
34 | uint8_t *buf, | |
35 | size_t buflen, | |
36 | void *opaque, | |
37 | Error **errp); | |
7d969014 | 38 | |
757dda54 AF |
39 | typedef int (*QCryptoBlockInitFunc)(QCryptoBlock *block, |
40 | size_t headerlen, | |
41 | void *opaque, | |
42 | Error **errp); | |
7d969014 | 43 | |
757dda54 AF |
44 | typedef int (*QCryptoBlockWriteFunc)(QCryptoBlock *block, |
45 | size_t offset, | |
46 | const uint8_t *buf, | |
47 | size_t buflen, | |
48 | void *opaque, | |
49 | Error **errp); | |
7d969014 DB |
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 | |
1cd9a787 | 74 | * @optprefix: name prefix for options |
7d969014 DB |
75 | * @readfunc: callback for reading data from the volume |
76 | * @opaque: data to pass to @readfunc | |
77 | * @flags: bitmask of QCryptoBlockOpenFlags values | |
c972fa12 | 78 | * @n_threads: allow concurrent I/O from up to @n_threads threads |
7d969014 DB |
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, | |
1cd9a787 | 107 | const char *optprefix, |
7d969014 DB |
108 | QCryptoBlockReadFunc readfunc, |
109 | void *opaque, | |
110 | unsigned int flags, | |
c972fa12 | 111 | size_t n_threads, |
7d969014 DB |
112 | Error **errp); |
113 | ||
114 | /** | |
115 | * qcrypto_block_create: | |
1cd9a787 DB |
116 | * @options: the encryption options |
117 | * @optprefix: name prefix for options | |
7d969014 DB |
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, | |
1cd9a787 | 141 | const char *optprefix, |
7d969014 DB |
142 | QCryptoBlockInitFunc initfunc, |
143 | QCryptoBlockWriteFunc writefunc, | |
144 | void *opaque, | |
145 | Error **errp); | |
146 | ||
43cbd06d ML |
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 | ||
40c85028 | 169 | |
6d49d3a8 SH |
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 | ||
40c85028 DB |
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 | ||
7d969014 DB |
205 | /** |
206 | * @qcrypto_block_decrypt: | |
207 | * @block: the block encryption object | |
4609742a | 208 | * @offset: the position at which @iov was read |
7d969014 DB |
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 | |
4609742a DB |
214 | * plain text back into @buf. @len and @offset must be |
215 | * a multiple of the encryption format sector size. | |
7d969014 DB |
216 | * |
217 | * Returns 0 on success, -1 on failure | |
218 | */ | |
219 | int qcrypto_block_decrypt(QCryptoBlock *block, | |
4609742a | 220 | uint64_t offset, |
7d969014 DB |
221 | uint8_t *buf, |
222 | size_t len, | |
223 | Error **errp); | |
224 | ||
225 | /** | |
226 | * @qcrypto_block_encrypt: | |
227 | * @block: the block encryption object | |
4609742a | 228 | * @offset: the position at which @iov will be written |
7d969014 DB |
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 | |
4609742a DB |
234 | * cipher text back into @buf. @len and @offset must be |
235 | * a multiple of the encryption format sector size. | |
7d969014 DB |
236 | * |
237 | * Returns 0 on success, -1 on failure | |
238 | */ | |
239 | int qcrypto_block_encrypt(QCryptoBlock *block, | |
4609742a | 240 | uint64_t offset, |
7d969014 DB |
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 | ||
850f49de DB |
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 | ||
7d969014 DB |
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 | ||
133cf1e5 DB |
313 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free) |
314 | ||
2a6a4076 | 315 | #endif /* QCRYPTO_BLOCK_H */ |