Re: [PATCH] docs/devel: Add introduction to LUKS volume with detached header

["Daniel P. Berrangé" <berrange@redhat.com>]

On Tue, Feb 20, 2024 at 12:04:42AM +0800, Hyman Huang wrote:
> Signed-off-by: Hyman Huang <yong.huang@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.huang@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.lureau@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

The new file neeeds adding to an index. We don't have anywhere for crypto
yet, so I'm starting a crypto section thus:

    diff --git a/docs/devel/crypto.rst b/docs/devel/crypto.rst
    new file mode 100644
    index 0000000000..39b1c910e7
    --- /dev/null
    +++ b/docs/devel/crypto.rst
    @@ -0,0 +1,10 @@
    +.. _crypto-ref:
    +
    +====================
    +Cryptography in QEMU
    +====================
    +
    +.. toctree::
    +   :maxdepth: 2
    +
    +   luks-detached-header
    diff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst
    index 5636e9cf1d..4ac7725d72 100644
    --- a/docs/devel/index-internals.rst
    +++ b/docs/devel/index-internals.rst
    @@ -20,3 +20,4 @@ Details about QEMU's various subsystems including how to add features to them.
        vfio-iommufd
        writing-monitor-commands
        virtio-backends
    +   crypto


> @@ -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"}}'

This needs indentation by 2 spaces, and the ">" can be dropped.
The same for all examples that follow.

I'm going to make those changes and queue this patch, since
they're trivial.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|