xref: /openbmc/qemu/include/crypto/block.h (revision 795c40b8)
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 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  * @readfunc: callback for reading data from the volume
75  * @opaque: data to pass to @readfunc
76  * @flags: bitmask of QCryptoBlockOpenFlags values
77  * @errp: pointer to a NULL-initialized error object
78  *
79  * Create a new block encryption object for an existing
80  * storage volume encrypted with format identified by
81  * the parameters in @options.
82  *
83  * This will use @readfunc to initialize the encryption
84  * context based on the volume header(s), extracting the
85  * master key(s) as required.
86  *
87  * If @flags contains QCRYPTO_BLOCK_OPEN_NO_IO then
88  * the open process will be optimized to skip any parts
89  * that are only required to perform I/O. In particular
90  * this would usually avoid the need to decrypt any
91  * master keys. The only thing that can be done with
92  * the resulting QCryptoBlock object would be to query
93  * metadata such as the payload offset. There will be
94  * no cipher or ivgen objects available.
95  *
96  * If any part of initializing the encryption context
97  * fails an error will be returned. This could be due
98  * to the volume being in the wrong format, a cipher
99  * or IV generator algorithm that is not supported,
100  * or incorrect passphrases.
101  *
102  * Returns: a block encryption format, or NULL on error
103  */
104 QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options,
105                                  QCryptoBlockReadFunc readfunc,
106                                  void *opaque,
107                                  unsigned int flags,
108                                  Error **errp);
109 
110 /**
111  * qcrypto_block_create:
112  * @format: the encryption format
113  * @initfunc: callback for initializing volume header
114  * @writefunc: callback for writing data to the volume header
115  * @opaque: data to pass to @initfunc and @writefunc
116  * @errp: pointer to a NULL-initialized error object
117  *
118  * Create a new block encryption object for initializing
119  * a storage volume to be encrypted with format identified
120  * by the parameters in @options.
121  *
122  * This method will allocate space for a new volume header
123  * using @initfunc and then write header data using @writefunc,
124  * generating new master keys, etc as required. Any existing
125  * data present on the volume will be irrevocably destroyed.
126  *
127  * If any part of initializing the encryption context
128  * fails an error will be returned. This could be due
129  * to the volume being in the wrong format, a cipher
130  * or IV generator algorithm that is not supported,
131  * or incorrect passphrases.
132  *
133  * Returns: a block encryption format, or NULL on error
134  */
135 QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options,
136                                    QCryptoBlockInitFunc initfunc,
137                                    QCryptoBlockWriteFunc writefunc,
138                                    void *opaque,
139                                    Error **errp);
140 
141 
142 /**
143  * qcrypto_block_get_info:
144  * @block: the block encryption object
145  * @errp: pointer to a NULL-initialized error object
146  *
147  * Get information about the configuration options for the
148  * block encryption object. This includes details such as
149  * the cipher algorithms, modes, and initialization vector
150  * generators.
151  *
152  * Returns: a block encryption info object, or NULL on error
153  */
154 QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block,
155                                          Error **errp);
156 
157 /**
158  * @qcrypto_block_decrypt:
159  * @block: the block encryption object
160  * @startsector: the sector from which @buf was read
161  * @buf: the buffer to decrypt
162  * @len: the length of @buf in bytes
163  * @errp: pointer to a NULL-initialized error object
164  *
165  * Decrypt @len bytes of cipher text in @buf, writing
166  * plain text back into @buf
167  *
168  * Returns 0 on success, -1 on failure
169  */
170 int qcrypto_block_decrypt(QCryptoBlock *block,
171                           uint64_t startsector,
172                           uint8_t *buf,
173                           size_t len,
174                           Error **errp);
175 
176 /**
177  * @qcrypto_block_encrypt:
178  * @block: the block encryption object
179  * @startsector: the sector to which @buf will be written
180  * @buf: the buffer to decrypt
181  * @len: the length of @buf in bytes
182  * @errp: pointer to a NULL-initialized error object
183  *
184  * Encrypt @len bytes of plain text in @buf, writing
185  * cipher text back into @buf
186  *
187  * Returns 0 on success, -1 on failure
188  */
189 int qcrypto_block_encrypt(QCryptoBlock *block,
190                           uint64_t startsector,
191                           uint8_t *buf,
192                           size_t len,
193                           Error **errp);
194 
195 /**
196  * qcrypto_block_get_cipher:
197  * @block: the block encryption object
198  *
199  * Get the cipher to use for payload encryption
200  *
201  * Returns: the cipher object
202  */
203 QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block);
204 
205 /**
206  * qcrypto_block_get_ivgen:
207  * @block: the block encryption object
208  *
209  * Get the initialization vector generator to use for
210  * payload encryption
211  *
212  * Returns: the IV generator object
213  */
214 QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block);
215 
216 
217 /**
218  * qcrypto_block_get_kdf_hash:
219  * @block: the block encryption object
220  *
221  * Get the hash algorithm used with the key derivation
222  * function
223  *
224  * Returns: the hash algorithm
225  */
226 QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block);
227 
228 /**
229  * qcrypto_block_get_payload_offset:
230  * @block: the block encryption object
231  *
232  * Get the offset to the payload indicated by the
233  * encryption header, in bytes.
234  *
235  * Returns: the payload offset in bytes
236  */
237 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block);
238 
239 /**
240  * qcrypto_block_free:
241  * @block: the block encryption object
242  *
243  * Release all resources associated with the encryption
244  * object
245  */
246 void qcrypto_block_free(QCryptoBlock *block);
247 
248 #endif /* QCRYPTO_BLOCK_H */
249