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