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 /** 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 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 248 #endif /* QCRYPTO_BLOCK_H */ 249