xemu-project/xemu
1
0
Fork 0
mirror of https://github.com/xemu-project/xemu.git synced 2024-11-23 11:39:53 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: document encryption options for qcow, qcow2 and luks

Browse Source 
Expand the image format docs to cover the new options for
the qcow, qcow2 and luks disk image formats

Reviewed-by: Alberto Garcia <berto@igalia.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Message-id: 20170623162419.26068-21-berrange@redhat.com
Signed-off-by: Max Reitz <mreitz@redhat.com>
This commit is contained in:
Daniel P. Berrange 2017-06-23 17:24:19 +01:00 committed by Max Reitz
parent 0a12f6f80e
commit 12f7efd02e
1 changed files with 115 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
qemu-doc.texi
View File

@ -540,10 +540,20 @@ File name of a base image (see @option{create} subcommand)
@item backing_fmt
Image format of the base image
@item encryption
If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
This option is deprecated and equivalent to @code{encrypt.format=aes}
The use of encryption in qcow and qcow2 images is considered to be flawed by
modern cryptography standards, suffering from a number of design problems:
@item encrypt.format
If this is set to @code{luks}, it requests that the qcow2 payload (not
qcow2 header) be encrypted using the LUKS format. The passphrase to
use to unlock the LUKS key slot is given by the @code{encrypt.key-secret}
parameter. LUKS encryption parameters can be tuned with the other
@code{encrypt.*} parameters.
If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
The encryption key is given by the @code{encrypt.key-secret} parameter.
This encryption format is considered to be flawed by modern cryptography
standards, suffering from a number of design problems:
@itemize @minus
@item The AES-CBC cipher is used with predictable initialization vectors based
@ -558,10 +568,45 @@ original file must then be securely erased using a program like shred,
though even this is ineffective with many modern storage technologies.
@end itemize
Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
it will go away in a future release. Users are recommended to use an
alternative encryption technology such as the Linux dm-crypt / LUKS
system.
The use of this is no longer supported in system emulators. Support only
remains in the command line utilities, for the purposes of data liberation
and interoperability with old versions of QEMU. The @code{luks} format
should be used instead.
@item encrypt.key-secret
Provides the ID of a @code{secret} object that contains the passphrase
(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).
@item encrypt.cipher-alg
Name of the cipher algorithm and key length. Currently defaults
to @code{aes-256}. Only used when @code{encrypt.format=luks}.
@item encrypt.cipher-mode
Name of the encryption mode to use. Currently defaults to @code{xts}.
Only used when @code{encrypt.format=luks}.
@item encrypt.ivgen-alg
Name of the initialization vector generator algorithm. Currently defaults
to @code{plain64}. Only used when @code{encrypt.format=luks}.
@item encrypt.ivgen-hash-alg
Name of the hash algorithm to use with the initialization vector generator
(if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
@item encrypt.hash-alg
Name of the hash algorithm to use for PBKDF algorithm
Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
@item encrypt.iter-time
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.
@item cluster_size
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
@ -636,7 +681,69 @@ Supported options:
@item backing_file
File name of a base image (see @option{create} subcommand)
@item encryption
If this option is set to @code{on}, the image is encrypted.
This option is deprecated and equivalent to @code{encrypt.format=aes}
@item encrypt.format
If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
The encryption key is given by the @code{encrypt.key-secret} parameter.
This encryption format is considered to be flawed by modern cryptography
standards, suffering from a number of design problems enumerated previously
against the @code{qcow2} image format.
The use of this is no longer supported in system emulators. Support only
remains in the command line utilities, for the purposes of data liberation
and interoperability with old versions of QEMU.
Users requiring native encryption should use the @code{qcow2} format
instead with @code{encrypt.format=luks}.
@item encrypt.key-secret
Provides the ID of a @code{secret} object that contains the encryption
key (@code{encrypt.format=aes}).
@end table
@item luks
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
Supported options:
@table @code
@item key-secret
Provides the ID of a @code{secret} object that contains the passphrase.
@item cipher-alg
Name of the cipher algorithm and key length. Currently defaults
to @code{aes-256}.
@item cipher-mode
Name of the encryption mode to use. Currently defaults to @code{xts}.
@item ivgen-alg
Name of the initialization vector generator algorithm. Currently defaults
to @code{plain64}.
@item ivgen-hash-alg
Name of the hash algorithm to use with the initialization vector generator
(if required). Defaults to @code{sha256}.
@item hash-alg
Name of the hash algorithm to use for PBKDF algorithm
Defaults to @code{sha256}.
@item iter-time
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
Defaults to @code{2000}.
@end table
@item vdi