Add ENET device to i.MX6 SOC.
[qemu.git] / include / crypto / block.h
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 Error **errp,
37 void *opaque);
38
39 typedef ssize_t (*QCryptoBlockInitFunc)(QCryptoBlock *block,
40 size_t headerlen,
41 Error **errp,
42 void *opaque);
43
44 typedef ssize_t (*QCryptoBlockWriteFunc)(QCryptoBlock *block,
45 size_t offset,
46 const uint8_t *buf,
47 size_t buflen,
48 Error **errp,
49 void *opaque);
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 * @qcrypto_block_decrypt:
143 * @block: the block encryption object
144 * @startsector: the sector from which @buf was read
145 * @buf: the buffer to decrypt
146 * @len: the length of @buf in bytes
147 * @errp: pointer to a NULL-initialized error object
148 *
149 * Decrypt @len bytes of cipher text in @buf, writing
150 * plain text back into @buf
151 *
152 * Returns 0 on success, -1 on failure
153 */
154 int qcrypto_block_decrypt(QCryptoBlock *block,
155 uint64_t startsector,
156 uint8_t *buf,
157 size_t len,
158 Error **errp);
159
160 /**
161 * @qcrypto_block_encrypt:
162 * @block: the block encryption object
163 * @startsector: the sector to which @buf will be written
164 * @buf: the buffer to decrypt
165 * @len: the length of @buf in bytes
166 * @errp: pointer to a NULL-initialized error object
167 *
168 * Encrypt @len bytes of plain text in @buf, writing
169 * cipher text back into @buf
170 *
171 * Returns 0 on success, -1 on failure
172 */
173 int qcrypto_block_encrypt(QCryptoBlock *block,
174 uint64_t startsector,
175 uint8_t *buf,
176 size_t len,
177 Error **errp);
178
179 /**
180 * qcrypto_block_get_cipher:
181 * @block: the block encryption object
182 *
183 * Get the cipher to use for payload encryption
184 *
185 * Returns: the cipher object
186 */
187 QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block);
188
189 /**
190 * qcrypto_block_get_ivgen:
191 * @block: the block encryption object
192 *
193 * Get the initialization vector generator to use for
194 * payload encryption
195 *
196 * Returns: the IV generator object
197 */
198 QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block);
199
200
201 /**
202 * qcrypto_block_get_kdf_hash:
203 * @block: the block encryption object
204 *
205 * Get the hash algorithm used with the key derivation
206 * function
207 *
208 * Returns: the hash algorithm
209 */
210 QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block);
211
212 /**
213 * qcrypto_block_get_payload_offset:
214 * @block: the block encryption object
215 *
216 * Get the offset to the payload indicated by the
217 * encryption header, in bytes.
218 *
219 * Returns: the payload offset in bytes
220 */
221 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block);
222
223 /**
224 * qcrypto_block_free:
225 * @block: the block encryption object
226 *
227 * Release all resources associated with the encryption
228 * object
229 */
230 void qcrypto_block_free(QCryptoBlock *block);
231
232 #endif /* QCRYPTO_BLOCK_H__ */