| /* | |
| * QEMU Crypto block device encryption | |
| * | |
| * Copyright (c) 2015-2016 Red Hat, Inc. | |
| * | |
| * This library is free software; you can redistribute it and/or | |
| * modify it under the terms of the GNU Lesser General Public | |
| * License as published by the Free Software Foundation; either | |
| * version 2.1 of the License, or (at your option) any later version. | |
| * | |
| * This library is distributed in the hope that it will be useful, | |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| * Lesser General Public License for more details. | |
| * | |
| * You should have received a copy of the GNU Lesser General Public | |
| * License along with this library; if not, see <http://www.gnu.org/licenses/>. | |
| * | |
| */ | |
| #ifndef QCRYPTO_BLOCK_H | |
| #define QCRYPTO_BLOCK_H | |
| #include "crypto/cipher.h" | |
| #include "crypto/ivgen.h" | |
| typedef struct QCryptoBlock QCryptoBlock; | |
| /* See also QCryptoBlockFormat, QCryptoBlockCreateOptions | |
| * and QCryptoBlockOpenOptions in qapi/crypto.json */ | |
| typedef int (*QCryptoBlockReadFunc)(QCryptoBlock *block, | |
| size_t offset, | |
| uint8_t *buf, | |
| size_t buflen, | |
| void *opaque, | |
| Error **errp); | |
| typedef int (*QCryptoBlockInitFunc)(QCryptoBlock *block, | |
| size_t headerlen, | |
| void *opaque, | |
| Error **errp); | |
| typedef int (*QCryptoBlockWriteFunc)(QCryptoBlock *block, | |
| size_t offset, | |
| const uint8_t *buf, | |
| size_t buflen, | |
| void *opaque, | |
| Error **errp); | |
| /** | |
| * qcrypto_block_has_format: | |
| * @format: the encryption format | |
| * @buf: the data from head of the volume | |
| * @len: the length of @buf in bytes | |
| * | |
| * Given @len bytes of data from the head of a storage volume | |
| * in @buf, probe to determine if the volume has the encryption | |
| * format specified in @format. | |
| * | |
| * Returns: true if the data in @buf matches @format | |
| */ | |
| bool qcrypto_block_has_format(QCryptoBlockFormat format, | |
| const uint8_t *buf, | |
| size_t buflen); | |
| typedef enum { | |
| QCRYPTO_BLOCK_OPEN_NO_IO = (1 << 0), | |
| QCRYPTO_BLOCK_OPEN_DETACHED = (1 << 1), | |
| } QCryptoBlockOpenFlags; | |
| /** | |
| * qcrypto_block_open: | |
| * @options: the encryption options | |
| * @optprefix: name prefix for options | |
| * @readfunc: callback for reading data from the volume | |
| * @opaque: data to pass to @readfunc | |
| * @flags: bitmask of QCryptoBlockOpenFlags values | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Create a new block encryption object for an existing | |
| * storage volume encrypted with format identified by | |
| * the parameters in @options. | |
| * | |
| * This will use @readfunc to initialize the encryption | |
| * context based on the volume header(s), extracting the | |
| * master key(s) as required. | |
| * | |
| * If @flags contains QCRYPTO_BLOCK_OPEN_NO_IO then | |
| * the open process will be optimized to skip any parts | |
| * that are only required to perform I/O. In particular | |
| * this would usually avoid the need to decrypt any | |
| * master keys. The only thing that can be done with | |
| * the resulting QCryptoBlock object would be to query | |
| * metadata such as the payload offset. There will be | |
| * no cipher or ivgen objects available. | |
| * | |
| * If @flags contains QCRYPTO_BLOCK_OPEN_DETACHED then | |
| * the open process will be optimized to skip the LUKS | |
| * payload overlap check. | |
| * | |
| * If any part of initializing the encryption context | |
| * fails an error will be returned. This could be due | |
| * to the volume being in the wrong format, a cipher | |
| * or IV generator algorithm that is not supported, | |
| * or incorrect passphrases. | |
| * | |
| * Returns: a block encryption format, or NULL on error | |
| */ | |
| QCryptoBlock *qcrypto_block_open(QCryptoBlockOpenOptions *options, | |
| const char *optprefix, | |
| QCryptoBlockReadFunc readfunc, | |
| void *opaque, | |
| unsigned int flags, | |
| Error **errp); | |
| typedef enum { | |
| QCRYPTO_BLOCK_CREATE_DETACHED = (1 << 0), | |
| } QCryptoBlockCreateFlags; | |
| /** | |
| * qcrypto_block_create: | |
| * @options: the encryption options | |
| * @optprefix: name prefix for options | |
| * @initfunc: callback for initializing volume header | |
| * @writefunc: callback for writing data to the volume header | |
| * @opaque: data to pass to @initfunc and @writefunc | |
| * @flags: bitmask of QCryptoBlockCreateFlags values | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Create a new block encryption object for initializing | |
| * a storage volume to be encrypted with format identified | |
| * by the parameters in @options. | |
| * | |
| * This method will allocate space for a new volume header | |
| * using @initfunc and then write header data using @writefunc, | |
| * generating new master keys, etc as required. Any existing | |
| * data present on the volume will be irrevocably destroyed. | |
| * | |
| * If @flags contains QCRYPTO_BLOCK_CREATE_DETACHED then | |
| * the open process will set the payload_offset_sector to 0 | |
| * to specify the starting point for the read/write of a | |
| * detached LUKS header image. | |
| * | |
| * If any part of initializing the encryption context | |
| * fails an error will be returned. This could be due | |
| * to the volume being in the wrong format, a cipher | |
| * or IV generator algorithm that is not supported, | |
| * or incorrect passphrases. | |
| * | |
| * Returns: a block encryption format, or NULL on error | |
| */ | |
| QCryptoBlock *qcrypto_block_create(QCryptoBlockCreateOptions *options, | |
| const char *optprefix, | |
| QCryptoBlockInitFunc initfunc, | |
| QCryptoBlockWriteFunc writefunc, | |
| void *opaque, | |
| unsigned int flags, | |
| Error **errp); | |
| /** | |
| * qcrypto_block_amend_options: | |
| * @block: the block encryption object | |
| * | |
| * @readfunc: callback for reading data from the volume header | |
| * @writefunc: callback for writing data to the volume header | |
| * @opaque: data to pass to @readfunc and @writefunc | |
| * @options: the new/amended encryption options | |
| * @force: hint for the driver to allow unsafe operation | |
| * @errp: error pointer | |
| * | |
| * Changes the crypto options of the encryption format | |
| * | |
| */ | |
| int qcrypto_block_amend_options(QCryptoBlock *block, | |
| QCryptoBlockReadFunc readfunc, | |
| QCryptoBlockWriteFunc writefunc, | |
| void *opaque, | |
| QCryptoBlockAmendOptions *options, | |
| bool force, | |
| Error **errp); | |
| /** | |
| * qcrypto_block_calculate_payload_offset: | |
| * @create_opts: the encryption options | |
| * @optprefix: name prefix for options | |
| * @len: output for number of header bytes before payload | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Calculate the number of header bytes before the payload in an encrypted | |
| * storage volume. The header is an area before the payload that is reserved | |
| * for encryption metadata. | |
| * | |
| * Returns: true on success, false on error | |
| */ | |
| bool | |
| qcrypto_block_calculate_payload_offset(QCryptoBlockCreateOptions *create_opts, | |
| const char *optprefix, | |
| size_t *len, | |
| Error **errp); | |
| /** | |
| * qcrypto_block_get_info: | |
| * @block: the block encryption object | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Get information about the configuration options for the | |
| * block encryption object. This includes details such as | |
| * the cipher algorithms, modes, and initialization vector | |
| * generators. | |
| * | |
| * Returns: a block encryption info object, or NULL on error | |
| */ | |
| QCryptoBlockInfo *qcrypto_block_get_info(QCryptoBlock *block, | |
| Error **errp); | |
| /** | |
| * @qcrypto_block_decrypt: | |
| * @block: the block encryption object | |
| * @offset: the position at which @iov was read | |
| * @buf: the buffer to decrypt | |
| * @len: the length of @buf in bytes | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Decrypt @len bytes of cipher text in @buf, writing | |
| * plain text back into @buf. @len and @offset must be | |
| * a multiple of the encryption format sector size. | |
| * | |
| * Returns 0 on success, -1 on failure | |
| */ | |
| int qcrypto_block_decrypt(QCryptoBlock *block, | |
| uint64_t offset, | |
| uint8_t *buf, | |
| size_t len, | |
| Error **errp); | |
| /** | |
| * @qcrypto_block_encrypt: | |
| * @block: the block encryption object | |
| * @offset: the position at which @iov will be written | |
| * @buf: the buffer to decrypt | |
| * @len: the length of @buf in bytes | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Encrypt @len bytes of plain text in @buf, writing | |
| * cipher text back into @buf. @len and @offset must be | |
| * a multiple of the encryption format sector size. | |
| * | |
| * Returns 0 on success, -1 on failure | |
| */ | |
| int qcrypto_block_encrypt(QCryptoBlock *block, | |
| uint64_t offset, | |
| uint8_t *buf, | |
| size_t len, | |
| Error **errp); | |
| /** | |
| * qcrypto_block_get_cipher: | |
| * @block: the block encryption object | |
| * | |
| * Get the cipher to use for payload encryption | |
| * | |
| * Returns: the cipher object | |
| */ | |
| QCryptoCipher *qcrypto_block_get_cipher(QCryptoBlock *block); | |
| /** | |
| * qcrypto_block_get_ivgen: | |
| * @block: the block encryption object | |
| * | |
| * Get the initialization vector generator to use for | |
| * payload encryption | |
| * | |
| * Returns: the IV generator object | |
| */ | |
| QCryptoIVGen *qcrypto_block_get_ivgen(QCryptoBlock *block); | |
| /** | |
| * qcrypto_block_get_kdf_hash: | |
| * @block: the block encryption object | |
| * | |
| * Get the hash algorithm used with the key derivation | |
| * function | |
| * | |
| * Returns: the hash algorithm | |
| */ | |
| QCryptoHashAlgo qcrypto_block_get_kdf_hash(QCryptoBlock *block); | |
| /** | |
| * qcrypto_block_get_payload_offset: | |
| * @block: the block encryption object | |
| * | |
| * Get the offset to the payload indicated by the | |
| * encryption header, in bytes. | |
| * | |
| * Returns: the payload offset in bytes | |
| */ | |
| uint64_t qcrypto_block_get_payload_offset(QCryptoBlock *block); | |
| /** | |
| * qcrypto_block_get_sector_size: | |
| * @block: the block encryption object | |
| * | |
| * Get the size of sectors used for payload encryption. A new | |
| * IV is used at the start of each sector. The encryption | |
| * sector size is not required to match the sector size of the | |
| * underlying storage. For example LUKS will always use a 512 | |
| * byte sector size, even if the volume is on a disk with 4k | |
| * sectors. | |
| * | |
| * Returns: the sector in bytes | |
| */ | |
| uint64_t qcrypto_block_get_sector_size(QCryptoBlock *block); | |
| /** | |
| * qcrypto_block_free: | |
| * @block: the block encryption object | |
| * | |
| * Release all resources associated with the encryption | |
| * object | |
| */ | |
| void qcrypto_block_free(QCryptoBlock *block); | |
| G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlock, qcrypto_block_free) | |
| #endif /* QCRYPTO_BLOCK_H */ |