ef834aa2b2
QAPI's 'prefix' feature can make the connection between enumeration
type and its constants less than obvious. It's best used with
restraint.
QCryptoHashAlgorithm has a 'prefix' that overrides the generated
enumeration constants' prefix to QCRYPTO_HASH_ALG.
We could simply drop 'prefix', but then the prefix becomes
QCRYPTO_HASH_ALGORITHM, which is rather long.
We could additionally rename the type to QCryptoHashAlg, but I think
the abbreviation "alg" is less than clear.
Rename the type to QCryptoHashAlgo instead. The prefix becomes to
QCRYPTO_HASH_ALGO.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Acked-by: Daniel P. Berrangé <berrange@redhat.com>
Message-ID: <20240904111836.3273842-12-armbru@redhat.com>
[Conflicts with merge commit 7bbadc60b5 resolved]
330 lines
11 KiB
C
330 lines
11 KiB
C
/*
|
|
* 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 */
|