Signed-off-by: Hyman Huang <yong.hu...@smartx.com>
---
MAINTAINERS | 1 +
docs/devel/luks-detached-header.rst | 182 ++++++++++++++++++++++++++++
2 files changed, 183 insertions(+)
create mode 100644 docs/devel/luks-detached-header.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index a24c2b51b6..e8b03032ab 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3422,6 +3422,7 @@ Detached LUKS header
M: Hyman Huang <yong.hu...@smartx.com>
S: Maintained
F: tests/qemu-iotests/tests/luks-detached-header
+F: docs/devel/luks-detached-header.rst
D-Bus
M: Marc-André Lureau <marcandre.lur...@redhat.com>
diff --git a/docs/devel/luks-detached-header.rst
b/docs/devel/luks-detached-header.rst
new file mode 100644
index 0000000000..15e9ccde1d
--- /dev/null
+++ b/docs/devel/luks-detached-header.rst
@@ -0,0 +1,182 @@
+================================
+LUKS volume with detached header
+================================
+
+Introduction
+============
+
+This document gives an overview of the design of LUKS volume with detached
+header and how to use it.
+
+Background
+==========
+
+The LUKS format has ability to store the header in a separate volume from
+the payload. We could extend the LUKS driver in QEMU to support this use
+case.
+
+Normally a LUKS volume has a layout:
+
+::
+
+ +-----------------------------------------------+
+ | | | |
+ disk | header | key material | disk payload data |
+ | | | |
+ +-----------------------------------------------+
+
+With a detached LUKS header, you need 2 disks so getting:
+
+::
+
+ +--------------------------+
+ disk1 | header | key material |
+ +--------------------------+
+ +---------------------+
+ disk2 | disk payload data |
+ +---------------------+
+
+There are a variety of benefits to doing this:
+
+ * Secrecy - the disk2 cannot be identified as containing LUKS
+ volume since there's no header
+ * Control - if access to the disk1 is restricted, then even
+ if someone has access to disk2 they can't unlock
+ it. Might be useful if you have disks on NFS but
+ want to restrict which host can launch a VM
+ instance from it, by dynamically providing access
+ to the header to a designated host
+ * Flexibility - your application data volume may be a given
+ size and it is inconvenient to resize it to
+ add encryption.You can store the LUKS header
+ separately and use the existing storage
+ volume for payload
+ * Recovery - corruption of a bit in the header may make the
+ entire payload inaccessible. It might be
+ convenient to take backups of the header. If
+ your primary disk header becomes corrupt, you
+ can unlock the data still by pointing to the
+ backup detached header
+
+Architecture
+============
+
+Take the qcow2 encryption, for example. The architecture of the
+LUKS volume with detached header is shown in the diagram below.
+
+There are two children of the root node: a file and a header.
+Data from the disk payload is stored in the file node. The
+LUKS header and key material are located in the header node,
+as previously mentioned.
+
+::
+
+ +-----------------------------+
+ Root node | foo[luks] |
+ +-----------------------------+
+ | |
+ file | header |
+ | |
+ +---------------------+ +------------------+
+ Child node |payload-format[qcow2]| |header-format[raw]|
+ +---------------------+ +------------------+
+ | |
+ file | file |
+ | |
+ +----------------------+ +---------------------+
+ Child node |payload-protocol[file]| |header-protocol[file]|
+ +----------------------+ +---------------------+
+ | |
+ | |
+ | |
+ Host storage Host storage
+
+Usage
+=====
+
+Create a LUKS disk with a detached header using qemu-img
+--------------------------------------------------------
+
+Shell commandline::
+
+# qemu-img create --object secret,id=sec0,data=abc123 -f luks \
+> -o cipher-alg=aes-256,cipher-mode=xts -o key-secret=sec0 \
+> -o detached-header=true test-header.img
+# qemu-img create -f qcow2 test-payload.qcow2 200G
+# qemu-img info 'json:{"driver":"luks","file":{"filename": \
+> "test-payload.img"},"header":{"filename":"test-header.img"}}'
+
+Set up a VM's LUKS volume with a detached header
+------------------------------------------------
+
+Qemu commandline::
+
+# qemu-system-x86_64 ... \
+> -object '{"qom-type":"secret","id":"libvirt-3-format-secret", \
+> "data":"abc123"}' \
+> -blockdev '{"driver":"file","filename":"/path/to/test-header.img", \
+> "node-name":"libvirt-1-storage"}' \
+> -blockdev '{"node-name":"libvirt-1-format","read-only":false, \
+> "driver":"raw","file":"libvirt-1-storage"}' \
+> -blockdev '{"driver":"file","filename":"/path/to/test-payload.qcow2", \
+> "node-name":"libvirt-2-storage"}' \
+> -blockdev '{"node-name":"libvirt-2-format","read-only":false, \
+> "driver":"qcow2","file":"libvirt-2-storage"}' \
+> -blockdev '{"node-name":"libvirt-3-format","driver":"luks", \
+> "file":"libvirt-2-format","header":"libvirt-1-format","key-secret": \
+> "libvirt-3-format-secret"}' \
+> -device '{"driver":"virtio-blk-pci","bus":XXX,"addr":YYY,"drive": \
+> "libvirt-3-format","id":"virtio-disk1"}'
+
+Add LUKS volume to a VM with a detached header
+----------------------------------------------
+
+1. object-add the secret for decrypting the cipher stored in
+ LUKS header above::
+
+# virsh qemu-monitor-command vm '{"execute":"object-add", \
+> "arguments":{"qom-type":"secret", "id": \
+> "libvirt-4-format-secret", "data":"abc123"}}'
+
+2. block-add the protocol node for LUKS header::
+
+# virsh qemu-monitor-command vm '{"execute":"blockdev-add", \
+> "arguments":{"node-name":"libvirt-1-storage", "driver":"file", \
+> "filename": "/path/to/test-header.img" }}'
+
+3. block-add the raw-drived node for LUKS header::
+
+# virsh qemu-monitor-command vm '{"execute":"blockdev-add", \
+> "arguments":{"node-name":"libvirt-1-format", "driver":"raw", \
+> "file":"libvirt-1-storage"}}'
+
+4. block-add the protocol node for disk payload image::
+
+# virsh qemu-monitor-command vm '{"execute":"blockdev-add", \
+> "arguments":{"node-name":"libvirt-2-storage", "driver":"file", \
+> "filename":"/path/to/test-payload.qcow2"}}'
+
+5. block-add the qcow2-drived format node for disk payload data::
+
+# virsh qemu-monitor-command vm '{"execute":"blockdev-add", \
+> "arguments":{"node-name":"libvirt-2-format", "driver":"qcow2", \
+> "file":"libvirt-2-storage"}}'
+
+6. block-add the luks-drived format node to link the qcow2 disk
+ with the LUKS header by specifying the field "header"::
+
+# virsh qemu-monitor-command vm '{"execute":"blockdev-add", \
+> "arguments":{"node-name":"libvirt-3-format", "driver":"luks", \
+> "file":"libvirt-2-format", "header":"libvirt-1-format", \
+> "key-secret":"libvirt-2-format-secret"}}'
+
+7. hot-plug the virtio-blk device finally::
+
+# virsh qemu-monitor-command vm '{"execute":"device_add", \
+> "arguments": {"driver":"virtio-blk-pci", \
+> "drive": "libvirt-3-format", "id":"virtio-disk2"}}
+
+TODO
+====
+
+1. Support the shared detached LUKS header within the VM.
--
2.39.3
