2 * QEMU Crypto block device encryption
4 * Copyright (c) 2015-2016 Red Hat, Inc.
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.
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.
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/>.
21 #ifndef QCRYPTO_BLOCK_H
22 #define QCRYPTO_BLOCK_H
24 #include "crypto/cipher.h"
25 #include "crypto/ivgen.h"
27 typedef struct QCryptoBlock QCryptoBlock
;
29 /* See also QCryptoBlockFormat, QCryptoBlockCreateOptions
30 * and QCryptoBlockOpenOptions in qapi/crypto.json */
32 typedef int (*QCryptoBlockReadFunc
)(QCryptoBlock
*block
,
39 typedef int (*QCryptoBlockInitFunc
)(QCryptoBlock
*block
,
44 typedef int (*QCryptoBlockWriteFunc
)(QCryptoBlock
*block
,
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
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.
61 * Returns: true if the data in @buf matches @format
63 bool qcrypto_block_has_format(QCryptoBlockFormat format
,
68 QCRYPTO_BLOCK_OPEN_NO_IO
= (1 << 0),
69 QCRYPTO_BLOCK_OPEN_DETACHED
= (1 << 1),
70 } QCryptoBlockOpenFlags
;
74 * @options: the encryption options
75 * @optprefix: name prefix for options
76 * @readfunc: callback for reading data from the volume
77 * @opaque: data to pass to @readfunc
78 * @flags: bitmask of QCryptoBlockOpenFlags values
79 * @n_threads: allow concurrent I/O from up to @n_threads threads
80 * @errp: pointer to a NULL-initialized error object
82 * Create a new block encryption object for an existing
83 * storage volume encrypted with format identified by
84 * the parameters in @options.
86 * This will use @readfunc to initialize the encryption
87 * context based on the volume header(s), extracting the
88 * master key(s) as required.
90 * If @flags contains QCRYPTO_BLOCK_OPEN_NO_IO then
91 * the open process will be optimized to skip any parts
92 * that are only required to perform I/O. In particular
93 * this would usually avoid the need to decrypt any
94 * master keys. The only thing that can be done with
95 * the resulting QCryptoBlock object would be to query
96 * metadata such as the payload offset. There will be
97 * no cipher or ivgen objects available.
99 * If @flags contains QCRYPTO_BLOCK_OPEN_DETACHED then
100 * the open process will be optimized to skip the LUKS
101 * payload overlap check.
103 * If any part of initializing the encryption context
104 * fails an error will be returned. This could be due
105 * to the volume being in the wrong format, a cipher
106 * or IV generator algorithm that is not supported,
107 * or incorrect passphrases.
109 * Returns: a block encryption format, or NULL on error
111 QCryptoBlock
*qcrypto_block_open(QCryptoBlockOpenOptions
*options
,
112 const char *optprefix
,
113 QCryptoBlockReadFunc readfunc
,
120 QCRYPTO_BLOCK_CREATE_DETACHED
= (1 << 0),
121 } QCryptoBlockCreateFlags
;
124 * qcrypto_block_create:
125 * @options: the encryption options
126 * @optprefix: name prefix for options
127 * @initfunc: callback for initializing volume header
128 * @writefunc: callback for writing data to the volume header
129 * @opaque: data to pass to @initfunc and @writefunc
130 * @flags: bitmask of QCryptoBlockCreateFlags values
131 * @errp: pointer to a NULL-initialized error object
133 * Create a new block encryption object for initializing
134 * a storage volume to be encrypted with format identified
135 * by the parameters in @options.
137 * This method will allocate space for a new volume header
138 * using @initfunc and then write header data using @writefunc,
139 * generating new master keys, etc as required. Any existing
140 * data present on the volume will be irrevocably destroyed.
142 * If @flags contains QCRYPTO_BLOCK_CREATE_DETACHED then
143 * the open process will set the payload_offset_sector to 0
144 * to specify the starting point for the read/write of a
145 * detached LUKS header image.
147 * If any part of initializing the encryption context
148 * fails an error will be returned. This could be due
149 * to the volume being in the wrong format, a cipher
150 * or IV generator algorithm that is not supported,
151 * or incorrect passphrases.
153 * Returns: a block encryption format, or NULL on error
155 QCryptoBlock
*qcrypto_block_create(QCryptoBlockCreateOptions
*options
,
156 const char *optprefix
,
157 QCryptoBlockInitFunc initfunc
,
158 QCryptoBlockWriteFunc writefunc
,
164 * qcrypto_block_amend_options:
165 * @block: the block encryption object
167 * @readfunc: callback for reading data from the volume header
168 * @writefunc: callback for writing data to the volume header
169 * @opaque: data to pass to @readfunc and @writefunc
170 * @options: the new/amended encryption options
171 * @force: hint for the driver to allow unsafe operation
172 * @errp: error pointer
174 * Changes the crypto options of the encryption format
177 int qcrypto_block_amend_options(QCryptoBlock
*block
,
178 QCryptoBlockReadFunc readfunc
,
179 QCryptoBlockWriteFunc writefunc
,
181 QCryptoBlockAmendOptions
*options
,
187 * qcrypto_block_calculate_payload_offset:
188 * @create_opts: the encryption options
189 * @optprefix: name prefix for options
190 * @len: output for number of header bytes before payload
191 * @errp: pointer to a NULL-initialized error object
193 * Calculate the number of header bytes before the payload in an encrypted
194 * storage volume. The header is an area before the payload that is reserved
195 * for encryption metadata.
197 * Returns: true on success, false on error
200 qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions
*create_opts
,
201 const char *optprefix
,
207 * qcrypto_block_get_info:
208 * @block: the block encryption object
209 * @errp: pointer to a NULL-initialized error object
211 * Get information about the configuration options for the
212 * block encryption object. This includes details such as
213 * the cipher algorithms, modes, and initialization vector
216 * Returns: a block encryption info object, or NULL on error
218 QCryptoBlockInfo
*qcrypto_block_get_info(QCryptoBlock
*block
,
222 * @qcrypto_block_decrypt:
223 * @block: the block encryption object
224 * @offset: the position at which @iov was read
225 * @buf: the buffer to decrypt
226 * @len: the length of @buf in bytes
227 * @errp: pointer to a NULL-initialized error object
229 * Decrypt @len bytes of cipher text in @buf, writing
230 * plain text back into @buf. @len and @offset must be
231 * a multiple of the encryption format sector size.
233 * Returns 0 on success, -1 on failure
235 int qcrypto_block_decrypt(QCryptoBlock
*block
,
242 * @qcrypto_block_encrypt:
243 * @block: the block encryption object
244 * @offset: the position at which @iov will be written
245 * @buf: the buffer to decrypt
246 * @len: the length of @buf in bytes
247 * @errp: pointer to a NULL-initialized error object
249 * Encrypt @len bytes of plain text in @buf, writing
250 * cipher text back into @buf. @len and @offset must be
251 * a multiple of the encryption format sector size.
253 * Returns 0 on success, -1 on failure
255 int qcrypto_block_encrypt(QCryptoBlock
*block
,
262 * qcrypto_block_get_cipher:
263 * @block: the block encryption object
265 * Get the cipher to use for payload encryption
267 * Returns: the cipher object
269 QCryptoCipher
*qcrypto_block_get_cipher(QCryptoBlock
*block
);
272 * qcrypto_block_get_ivgen:
273 * @block: the block encryption object
275 * Get the initialization vector generator to use for
278 * Returns: the IV generator object
280 QCryptoIVGen
*qcrypto_block_get_ivgen(QCryptoBlock
*block
);
284 * qcrypto_block_get_kdf_hash:
285 * @block: the block encryption object
287 * Get the hash algorithm used with the key derivation
290 * Returns: the hash algorithm
292 QCryptoHashAlgorithm
qcrypto_block_get_kdf_hash(QCryptoBlock
*block
);
295 * qcrypto_block_get_payload_offset:
296 * @block: the block encryption object
298 * Get the offset to the payload indicated by the
299 * encryption header, in bytes.
301 * Returns: the payload offset in bytes
303 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock
*block
);
306 * qcrypto_block_get_sector_size:
307 * @block: the block encryption object
309 * Get the size of sectors used for payload encryption. A new
310 * IV is used at the start of each sector. The encryption
311 * sector size is not required to match the sector size of the
312 * underlying storage. For example LUKS will always use a 512
313 * byte sector size, even if the volume is on a disk with 4k
316 * Returns: the sector in bytes
318 uint64_t qcrypto_block_get_sector_size(QCryptoBlock
*block
);
321 * qcrypto_block_free:
322 * @block: the block encryption object
324 * Release all resources associated with the encryption
327 void qcrypto_block_free(QCryptoBlock
*block
);
329 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock
, qcrypto_block_free
)
331 #endif /* QCRYPTO_BLOCK_H */