[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-block] [PULL 060/100] docs: document encryption options for qcow,
From: |
Kevin Wolf |
Subject: |
[Qemu-block] [PULL 060/100] docs: document encryption options for qcow, qcow2 and luks |
Date: |
Fri, 7 Jul 2017 19:08:15 +0200 |
From: "Daniel P. Berrange" <address@hidden>
Expand the image format docs to cover the new options for
the qcow, qcow2 and luks disk image formats
Reviewed-by: Alberto Garcia <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Signed-off-by: Daniel P. Berrange <address@hidden>
Message-id: address@hidden
Signed-off-by: Max Reitz <address@hidden>
---
qemu-doc.texi | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 115 insertions(+), 8 deletions(-)
diff --git a/qemu-doc.texi b/qemu-doc.texi
index d2986cb..48af515 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -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:
address@hidden 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
address@hidden 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.
+
address@hidden 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}).
+
address@hidden encrypt.cipher-alg
+
+Name of the cipher algorithm and key length. Currently defaults
+to @code{aes-256}. Only used when @code{encrypt.format=luks}.
+
address@hidden encrypt.cipher-mode
+
+Name of the encryption mode to use. Currently defaults to @code{xts}.
+Only used when @code{encrypt.format=luks}.
+
address@hidden encrypt.ivgen-alg
+
+Name of the initialization vector generator algorithm. Currently defaults
+to @code{plain64}. Only used when @code{encrypt.format=luks}.
+
address@hidden 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}.
+
address@hidden encrypt.hash-alg
+
+Name of the hash algorithm to use for PBKDF algorithm
+Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
+
address@hidden 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}
+
address@hidden 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}.
+
address@hidden encrypt.key-secret
+
+Provides the ID of a @code{secret} object that contains the encryption
+key (@code{encrypt.format=aes}).
+
address@hidden table
+
address@hidden luks
+
+LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
+
+Supported options:
address@hidden @code
+
address@hidden key-secret
+
+Provides the ID of a @code{secret} object that contains the passphrase.
+
address@hidden cipher-alg
+
+Name of the cipher algorithm and key length. Currently defaults
+to @code{aes-256}.
+
address@hidden cipher-mode
+
+Name of the encryption mode to use. Currently defaults to @code{xts}.
+
address@hidden ivgen-alg
+
+Name of the initialization vector generator algorithm. Currently defaults
+to @code{plain64}.
+
address@hidden ivgen-hash-alg
+
+Name of the hash algorithm to use with the initialization vector generator
+(if required). Defaults to @code{sha256}.
+
address@hidden hash-alg
+
+Name of the hash algorithm to use for PBKDF algorithm
+Defaults to @code{sha256}.
+
address@hidden iter-time
+
+Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
+Defaults to @code{2000}.
+
@end table
@item vdi
--
1.8.3.1
- [Qemu-block] [PULL 052/100] qcow2: extend specification to cover LUKS encryption, (continued)
- [Qemu-block] [PULL 052/100] qcow2: extend specification to cover LUKS encryption, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 050/100] qcow2: make qcow2_encrypt_sectors encrypt in place, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 055/100] iotests: enable tests 134 and 158 to work with qcow (v1), Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 054/100] qcow2: add iotests to cover LUKS encryption support, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 048/100] qcow: make encrypt_sectors encrypt in place, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 051/100] qcow2: convert QCow2 to use QCryptoBlock for encryption, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 056/100] block: rip out all traces of password prompting, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 059/100] qcow2: report encryption specific image information, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 053/100] qcow2: add support for LUKS encryption format, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 061/100] iotests: 181 does not work for all formats, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 060/100] docs: document encryption options for qcow, qcow2 and luks,
Kevin Wolf <=
- [Qemu-block] [PULL 062/100] mirror: Fix inconsistent backing AioContext for after mirroring, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 058/100] block: pass option prefix down to crypto layer, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 057/100] block: remove all encryption handling APIs, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 063/100] specs/qcow2: fix bitmap granularity qemu-specific note, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 064/100] specs/qcow2: do not use wording 'bitmap header', Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 065/100] hbitmap: improve dirty iter, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 067/100] block: fix bdrv_dirty_bitmap_granularity signature, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 066/100] tests: add hbitmap iter test, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 068/100] block/dirty-bitmap: add deserialize_ones func, Kevin Wolf, 2017/07/07
- [Qemu-block] [PULL 069/100] qcow2-refcount: rename inc_refcounts() and make it public, Kevin Wolf, 2017/07/07