block.h (10888B)
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 27typedef struct QCryptoBlock QCryptoBlock; 28 29/* See also QCryptoBlockFormat, QCryptoBlockCreateOptions 30 * and QCryptoBlockOpenOptions in qapi/crypto.json */ 31 32typedef ssize_t (*QCryptoBlockReadFunc)(QCryptoBlock *block, 33 size_t offset, 34 uint8_t *buf, 35 size_t buflen, 36 void *opaque, 37 Error **errp); 38 39typedef ssize_t (*QCryptoBlockInitFunc)(QCryptoBlock *block, 40 size_t headerlen, 41 void *opaque, 42 Error **errp); 43 44typedef 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 */ 63bool qcrypto_block_has_format(QCryptoBlockFormat format, 64 const uint8_t *buf, 65 size_t buflen); 66 67typedef enum { 68 QCRYPTO_BLOCK_OPEN_NO_IO = (1 << 0), 69} QCryptoBlockOpenFlags; 70 71/** 72 * qcrypto_block_open: 73 * @options: the encryption options 74 * @optprefix: name prefix for options 75 * @readfunc: callback for reading data from the volume 76 * @opaque: data to pass to @readfunc 77 * @flags: bitmask of QCryptoBlockOpenFlags values 78 * @n_threads: allow concurrent I/O from up to @n_threads threads 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 any part of initializing the encryption context 99 * fails an error will be returned. This could be due 100 * to the volume being in the wrong format, a cipher 101 * or IV generator algorithm that is not supported, 102 * or incorrect passphrases. 103 * 104 * Returns: a block encryption format, or NULL on error 105 */ 106QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options, 107 const char *optprefix, 108 QCryptoBlockReadFunc readfunc, 109 void *opaque, 110 unsigned int flags, 111 size_t n_threads, 112 Error **errp); 113 114/** 115 * qcrypto_block_create: 116 * @options: the encryption options 117 * @optprefix: name prefix for options 118 * @initfunc: callback for initializing volume header 119 * @writefunc: callback for writing data to the volume header 120 * @opaque: data to pass to @initfunc and @writefunc 121 * @errp: pointer to a NULL-initialized error object 122 * 123 * Create a new block encryption object for initializing 124 * a storage volume to be encrypted with format identified 125 * by the parameters in @options. 126 * 127 * This method will allocate space for a new volume header 128 * using @initfunc and then write header data using @writefunc, 129 * generating new master keys, etc as required. Any existing 130 * data present on the volume will be irrevocably destroyed. 131 * 132 * If any part of initializing the encryption context 133 * fails an error will be returned. This could be due 134 * to the volume being in the wrong format, a cipher 135 * or IV generator algorithm that is not supported, 136 * or incorrect passphrases. 137 * 138 * Returns: a block encryption format, or NULL on error 139 */ 140QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options, 141 const char *optprefix, 142 QCryptoBlockInitFunc initfunc, 143 QCryptoBlockWriteFunc writefunc, 144 void *opaque, 145 Error **errp); 146 147/** 148 * qcrypto_block_amend_options: 149 * @block: the block encryption object 150 * 151 * @readfunc: callback for reading data from the volume header 152 * @writefunc: callback for writing data to the volume header 153 * @opaque: data to pass to @readfunc and @writefunc 154 * @options: the new/amended encryption options 155 * @force: hint for the driver to allow unsafe operation 156 * @errp: error pointer 157 * 158 * Changes the crypto options of the encryption format 159 * 160 */ 161int qcrypto_block_amend_options(QCryptoBlock *block, 162 QCryptoBlockReadFunc readfunc, 163 QCryptoBlockWriteFunc writefunc, 164 void *opaque, 165 QCryptoBlockAmendOptions *options, 166 bool force, 167 Error **errp); 168 169 170/** 171 * qcrypto_block_calculate_payload_offset: 172 * @create_opts: the encryption options 173 * @optprefix: name prefix for options 174 * @len: output for number of header bytes before payload 175 * @errp: pointer to a NULL-initialized error object 176 * 177 * Calculate the number of header bytes before the payload in an encrypted 178 * storage volume. The header is an area before the payload that is reserved 179 * for encryption metadata. 180 * 181 * Returns: true on success, false on error 182 */ 183bool 184qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions *create_opts, 185 const char *optprefix, 186 size_t *len, 187 Error **errp); 188 189 190/** 191 * qcrypto_block_get_info: 192 * @block: the block encryption object 193 * @errp: pointer to a NULL-initialized error object 194 * 195 * Get information about the configuration options for the 196 * block encryption object. This includes details such as 197 * the cipher algorithms, modes, and initialization vector 198 * generators. 199 * 200 * Returns: a block encryption info object, or NULL on error 201 */ 202QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block, 203 Error **errp); 204 205/** 206 * @qcrypto_block_decrypt: 207 * @block: the block encryption object 208 * @offset: the position at which @iov was read 209 * @buf: the buffer to decrypt 210 * @len: the length of @buf in bytes 211 * @errp: pointer to a NULL-initialized error object 212 * 213 * Decrypt @len bytes of cipher text in @buf, writing 214 * plain text back into @buf. @len and @offset must be 215 * a multiple of the encryption format sector size. 216 * 217 * Returns 0 on success, -1 on failure 218 */ 219int qcrypto_block_decrypt(QCryptoBlock *block, 220 uint64_t offset, 221 uint8_t *buf, 222 size_t len, 223 Error **errp); 224 225/** 226 * @qcrypto_block_encrypt: 227 * @block: the block encryption object 228 * @offset: the position at which @iov will be written 229 * @buf: the buffer to decrypt 230 * @len: the length of @buf in bytes 231 * @errp: pointer to a NULL-initialized error object 232 * 233 * Encrypt @len bytes of plain text in @buf, writing 234 * cipher text back into @buf. @len and @offset must be 235 * a multiple of the encryption format sector size. 236 * 237 * Returns 0 on success, -1 on failure 238 */ 239int qcrypto_block_encrypt(QCryptoBlock *block, 240 uint64_t offset, 241 uint8_t *buf, 242 size_t len, 243 Error **errp); 244 245/** 246 * qcrypto_block_get_cipher: 247 * @block: the block encryption object 248 * 249 * Get the cipher to use for payload encryption 250 * 251 * Returns: the cipher object 252 */ 253QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block); 254 255/** 256 * qcrypto_block_get_ivgen: 257 * @block: the block encryption object 258 * 259 * Get the initialization vector generator to use for 260 * payload encryption 261 * 262 * Returns: the IV generator object 263 */ 264QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block); 265 266 267/** 268 * qcrypto_block_get_kdf_hash: 269 * @block: the block encryption object 270 * 271 * Get the hash algorithm used with the key derivation 272 * function 273 * 274 * Returns: the hash algorithm 275 */ 276QCryptoHashAlgorithm qcrypto_block_get_kdf_hash(QCryptoBlock *block); 277 278/** 279 * qcrypto_block_get_payload_offset: 280 * @block: the block encryption object 281 * 282 * Get the offset to the payload indicated by the 283 * encryption header, in bytes. 284 * 285 * Returns: the payload offset in bytes 286 */ 287uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block); 288 289/** 290 * qcrypto_block_get_sector_size: 291 * @block: the block encryption object 292 * 293 * Get the size of sectors used for payload encryption. A new 294 * IV is used at the start of each sector. The encryption 295 * sector size is not required to match the sector size of the 296 * underlying storage. For example LUKS will always use a 512 297 * byte sector size, even if the volume is on a disk with 4k 298 * sectors. 299 * 300 * Returns: the sector in bytes 301 */ 302uint64_t qcrypto_block_get_sector_size(QCryptoBlock *block); 303 304/** 305 * qcrypto_block_free: 306 * @block: the block encryption object 307 * 308 * Release all resources associated with the encryption 309 * object 310 */ 311void qcrypto_block_free(QCryptoBlock *block); 312 313G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free) 314 315#endif /* QCRYPTO_BLOCK_H */