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.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 */