]>
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 | |
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 | ||
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 | ||
32 | typedef ssize_t (*QCryptoBlockReadFunc)(QCryptoBlock *block, | |
33 | size_t offset, | |
34 | uint8_t *buf, | |
35 | size_t buflen, | |
e4a3507e | 36 | void *opaque, |
37509233 | 37 | Error **errp); |
7d969014 DB |
38 | |
39 | typedef ssize_t (*QCryptoBlockInitFunc)(QCryptoBlock *block, | |
40 | size_t headerlen, | |
e4a3507e | 41 | void *opaque, |
37509233 | 42 | Error **errp); |
7d969014 DB |
43 | |
44 | typedef ssize_t (*QCryptoBlockWriteFunc)(QCryptoBlock *block, | |
45 | size_t offset, | |
46 | const uint8_t *buf, | |
47 | size_t buflen, | |
e4a3507e | 48 | void *opaque, |
37509233 | 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 | |
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 | ||
40c85028 DB |
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 | ||
7d969014 DB |
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 | ||
2a6a4076 | 248 | #endif /* QCRYPTO_BLOCK_H */ |