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 * @n_threads: allow concurrent I/O from up to @n_threads threads 80 * @errp: pointer to a NULL-initialized error object 81 * 82 * Create a new block encryption object for an existing 83 * storage volume encrypted with format identified by 84 * the parameters in @options. 85 * 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. 89 * 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. 98 * 99 * If @flags contains QCRYPTO_BLOCK_OPEN_DETACHED then 100 * the open process will be optimized to skip the LUKS 101 * payload overlap check. 102 * 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. 108 * 109 * Returns: a block encryption format, or NULL on error 110 */ 111 QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options, 112 const char *optprefix, 113 QCryptoBlockReadFunc readfunc, 114 void *opaque, 115 unsigned int flags, 116 size_t n_threads, 117 Error **errp); 118 119 typedef enum { 120 QCRYPTO_BLOCK_CREATE_DETACHED = (1 << 0), 121 } QCryptoBlockCreateFlags; 122 123 /** 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 132 * 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. 136 * 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. 141 * 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. 146 * 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. 152 * 153 * Returns: a block encryption format, or NULL on error 154 */ 155 QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options, 156 const char *optprefix, 157 QCryptoBlockInitFunc initfunc, 158 QCryptoBlockWriteFunc writefunc, 159 void *opaque, 160 unsigned int flags, 161 Error **errp); 162 163 /** 164 * qcrypto_block_amend_options: 165 * @block: the block encryption object 166 * 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 173 * 174 * Changes the crypto options of the encryption format 175 * 176 */ 177 int qcrypto_block_amend_options(QCryptoBlock *block, 178 QCryptoBlockReadFunc readfunc, 179 QCryptoBlockWriteFunc writefunc, 180 void *opaque, 181 QCryptoBlockAmendOptions *options, 182 bool force, 183 Error **errp); 184 185 186 /** 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 192 * 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. 196 * 197 * Returns: true on success, false on error 198 */ 199 bool 200 qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions *create_opts, 201 const char *optprefix, 202 size_t *len, 203 Error **errp); 204 205 206 /** 207 * qcrypto_block_get_info: 208 * @block: the block encryption object 209 * @errp: pointer to a NULL-initialized error object 210 * 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 214 * generators. 215 * 216 * Returns: a block encryption info object, or NULL on error 217 */ 218 QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block, 219 Error **errp); 220 221 /** 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 228 * 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. 232 * 233 * Returns 0 on success, -1 on failure 234 */ 235 int qcrypto_block_decrypt(QCryptoBlock *block, 236 uint64_t offset, 237 uint8_t *buf, 238 size_t len, 239 Error **errp); 240 241 /** 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 248 * 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. 252 * 253 * Returns 0 on success, -1 on failure 254 */ 255 int qcrypto_block_encrypt(QCryptoBlock *block, 256 uint64_t offset, 257 uint8_t *buf, 258 size_t len, 259 Error **errp); 260 261 /** 262 * qcrypto_block_get_cipher: 263 * @block: the block encryption object 264 * 265 * Get the cipher to use for payload encryption 266 * 267 * Returns: the cipher object 268 */ 269 QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block); 270 271 /** 272 * qcrypto_block_get_ivgen: 273 * @block: the block encryption object 274 * 275 * Get the initialization vector generator to use for 276 * payload encryption 277 * 278 * Returns: the IV generator object 279 */ 280 QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block); 281 282 283 /** 284 * qcrypto_block_get_kdf_hash: 285 * @block: the block encryption object 286 * 287 * Get the hash algorithm used with the key derivation 288 * function 289 * 290 * Returns: the hash algorithm 291 */ 292 QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block); 293 294 /** 295 * qcrypto_block_get_payload_offset: 296 * @block: the block encryption object 297 * 298 * Get the offset to the payload indicated by the 299 * encryption header, in bytes. 300 * 301 * Returns: the payload offset in bytes 302 */ 303 uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block); 304 305 /** 306 * qcrypto_block_get_sector_size: 307 * @block: the block encryption object 308 * 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 314 * sectors. 315 * 316 * Returns: the sector in bytes 317 */ 318 uint64_t qcrypto_block_get_sector_size(QCryptoBlock *block); 319 320 /** 321 * qcrypto_block_free: 322 * @block: the block encryption object 323 * 324 * Release all resources associated with the encryption 325 * object 326 */ 327 void qcrypto_block_free(QCryptoBlock *block); 328 329 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free) 330 331 #endif /* QCRYPTO_BLOCK_H */ 332