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