xref: /openbmc/qemu/include/crypto/block.h (revision 3ab0f063)
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 int (*QCryptoBlockReadFunc)(QCryptoBlock *block,
33                                     size_t offset,
34                                     uint8_t *buf,
35                                     size_t buflen,
36                                     void *opaque,
37                                     Error **errp);
38 
39 typedef int (*QCryptoBlockInitFunc)(QCryptoBlock *block,
40                                     size_t headerlen,
41                                     void *opaque,
42                                     Error **errp);
43 
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);
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     QCRYPTO_BLOCK_OPEN_DETACHED = (1 << 1),
70 } QCryptoBlockOpenFlags;
71 
72 /**
73  * qcrypto_block_open:
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  * @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 @flags contains QCRYPTO_BLOCK_OPEN_DETACHED then
99  * the open process will be optimized to skip the LUKS
100  * payload overlap check.
101  *
102  * If any part of initializing the encryption context
103  * fails an error will be returned. This could be due
104  * to the volume being in the wrong format, a cipher
105  * or IV generator algorithm that is not supported,
106  * or incorrect passphrases.
107  *
108  * Returns: a block encryption format, or NULL on error
109  */
110 QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options,
111                                  const char *optprefix,
112                                  QCryptoBlockReadFunc readfunc,
113                                  void *opaque,
114                                  unsigned int flags,
115                                  Error **errp);
116 
117 typedef enum {
118     QCRYPTO_BLOCK_CREATE_DETACHED = (1 << 0),
119 } QCryptoBlockCreateFlags;
120 
121 /**
122  * qcrypto_block_create:
123  * @options: the encryption options
124  * @optprefix: name prefix for options
125  * @initfunc: callback for initializing volume header
126  * @writefunc: callback for writing data to the volume header
127  * @opaque: data to pass to @initfunc and @writefunc
128  * @flags: bitmask of QCryptoBlockCreateFlags values
129  * @errp: pointer to a NULL-initialized error object
130  *
131  * Create a new block encryption object for initializing
132  * a storage volume to be encrypted with format identified
133  * by the parameters in @options.
134  *
135  * This method will allocate space for a new volume header
136  * using @initfunc and then write header data using @writefunc,
137  * generating new master keys, etc as required. Any existing
138  * data present on the volume will be irrevocably destroyed.
139  *
140  * If @flags contains QCRYPTO_BLOCK_CREATE_DETACHED then
141  * the open process will set the payload_offset_sector to 0
142  * to specify the starting point for the read/write of a
143  * detached LUKS header image.
144  *
145  * If any part of initializing the encryption context
146  * fails an error will be returned. This could be due
147  * to the volume being in the wrong format, a cipher
148  * or IV generator algorithm that is not supported,
149  * or incorrect passphrases.
150  *
151  * Returns: a block encryption format, or NULL on error
152  */
153 QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options,
154                                    const char *optprefix,
155                                    QCryptoBlockInitFunc initfunc,
156                                    QCryptoBlockWriteFunc writefunc,
157                                    void *opaque,
158                                    unsigned int flags,
159                                    Error **errp);
160 
161 /**
162  * qcrypto_block_amend_options:
163  * @block: the block encryption object
164  *
165  * @readfunc: callback for reading data from the volume header
166  * @writefunc: callback for writing data to the volume header
167  * @opaque: data to pass to @readfunc and @writefunc
168  * @options: the new/amended encryption options
169  * @force: hint for the driver to allow unsafe operation
170  * @errp: error pointer
171  *
172  * Changes the crypto options of the encryption format
173  *
174  */
175 int qcrypto_block_amend_options(QCryptoBlock *block,
176                                 QCryptoBlockReadFunc readfunc,
177                                 QCryptoBlockWriteFunc writefunc,
178                                 void *opaque,
179                                 QCryptoBlockAmendOptions *options,
180                                 bool force,
181                                 Error **errp);
182 
183 
184 /**
185  * qcrypto_block_calculate_payload_offset:
186  * @create_opts: the encryption options
187  * @optprefix: name prefix for options
188  * @len: output for number of header bytes before payload
189  * @errp: pointer to a NULL-initialized error object
190  *
191  * Calculate the number of header bytes before the payload in an encrypted
192  * storage volume.  The header is an area before the payload that is reserved
193  * for encryption metadata.
194  *
195  * Returns: true on success, false on error
196  */
197 bool
198 qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions *create_opts,
199                                        const char *optprefix,
200                                        size_t *len,
201                                        Error **errp);
202 
203 
204 /**
205  * qcrypto_block_get_info:
206  * @block: the block encryption object
207  * @errp: pointer to a NULL-initialized error object
208  *
209  * Get information about the configuration options for the
210  * block encryption object. This includes details such as
211  * the cipher algorithms, modes, and initialization vector
212  * generators.
213  *
214  * Returns: a block encryption info object, or NULL on error
215  */
216 QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block,
217                                          Error **errp);
218 
219 /**
220  * @qcrypto_block_decrypt:
221  * @block: the block encryption object
222  * @offset: the position at which @iov was read
223  * @buf: the buffer to decrypt
224  * @len: the length of @buf in bytes
225  * @errp: pointer to a NULL-initialized error object
226  *
227  * Decrypt @len bytes of cipher text in @buf, writing
228  * plain text back into @buf. @len and @offset must be
229  * a multiple of the encryption format sector size.
230  *
231  * Returns 0 on success, -1 on failure
232  */
233 int qcrypto_block_decrypt(QCryptoBlock *block,
234                           uint64_t offset,
235                           uint8_t *buf,
236                           size_t len,
237                           Error **errp);
238 
239 /**
240  * @qcrypto_block_encrypt:
241  * @block: the block encryption object
242  * @offset: the position at which @iov will be written
243  * @buf: the buffer to decrypt
244  * @len: the length of @buf in bytes
245  * @errp: pointer to a NULL-initialized error object
246  *
247  * Encrypt @len bytes of plain text in @buf, writing
248  * cipher text back into @buf. @len and @offset must be
249  * a multiple of the encryption format sector size.
250  *
251  * Returns 0 on success, -1 on failure
252  */
253 int qcrypto_block_encrypt(QCryptoBlock *block,
254                           uint64_t offset,
255                           uint8_t *buf,
256                           size_t len,
257                           Error **errp);
258 
259 /**
260  * qcrypto_block_get_cipher:
261  * @block: the block encryption object
262  *
263  * Get the cipher to use for payload encryption
264  *
265  * Returns: the cipher object
266  */
267 QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block);
268 
269 /**
270  * qcrypto_block_get_ivgen:
271  * @block: the block encryption object
272  *
273  * Get the initialization vector generator to use for
274  * payload encryption
275  *
276  * Returns: the IV generator object
277  */
278 QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block);
279 
280 
281 /**
282  * qcrypto_block_get_kdf_hash:
283  * @block: the block encryption object
284  *
285  * Get the hash algorithm used with the key derivation
286  * function
287  *
288  * Returns: the hash algorithm
289  */
290 QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block);
291 
292 /**
293  * qcrypto_block_get_payload_offset:
294  * @block: the block encryption object
295  *
296  * Get the offset to the payload indicated by the
297  * encryption header, in bytes.
298  *
299  * Returns: the payload offset in bytes
300  */
301 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block);
302 
303 /**
304  * qcrypto_block_get_sector_size:
305  * @block: the block encryption object
306  *
307  * Get the size of sectors used for payload encryption. A new
308  * IV is used at the start of each sector. The encryption
309  * sector size is not required to match the sector size of the
310  * underlying storage. For example LUKS will always use a 512
311  * byte sector size, even if the volume is on a disk with 4k
312  * sectors.
313  *
314  * Returns: the sector in bytes
315  */
316 uint64_t qcrypto_block_get_sector_size(QCryptoBlock *block);
317 
318 /**
319  * qcrypto_block_free:
320  * @block: the block encryption object
321  *
322  * Release all resources associated with the encryption
323  * object
324  */
325 void qcrypto_block_free(QCryptoBlock *block);
326 
327 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free)
328 
329 #endif /* QCRYPTO_BLOCK_H */
330