| 1 | ================================ |
| 2 | LUKS volume with detached header |
| 3 | ================================ |
| 4 | |
| 5 | Introduction |
| 6 | ============ |
| 7 | |
| 8 | This document gives an overview of the design of LUKS volume with detached |
| 9 | header and how to use it. |
| 10 | |
| 11 | Background |
| 12 | ========== |
| 13 | |
| 14 | The LUKS format has ability to store the header in a separate volume from |
| 15 | the payload. We could extend the LUKS driver in QEMU to support this use |
| 16 | case. |
| 17 | |
| 18 | Normally a LUKS volume has a layout: |
| 19 | |
| 20 | :: |
| 21 | |
| 22 | +-----------------------------------------------+ |
| 23 | | | | | |
| 24 | disk | header | key material | disk payload data | |
| 25 | | | | | |
| 26 | +-----------------------------------------------+ |
| 27 | |
| 28 | With a detached LUKS header, you need 2 disks so getting: |
| 29 | |
| 30 | :: |
| 31 | |
| 32 | +--------------------------+ |
| 33 | disk1 | header | key material | |
| 34 | +--------------------------+ |
| 35 | +---------------------+ |
| 36 | disk2 | disk payload data | |
| 37 | +---------------------+ |
| 38 | |
| 39 | There are a variety of benefits to doing this: |
| 40 | |
| 41 | * Secrecy - the disk2 cannot be identified as containing LUKS |
| 42 | volume since there's no header |
| 43 | * Control - if access to the disk1 is restricted, then even |
| 44 | if someone has access to disk2 they can't unlock |
| 45 | it. Might be useful if you have disks on NFS but |
| 46 | want to restrict which host can launch a VM |
| 47 | instance from it, by dynamically providing access |
| 48 | to the header to a designated host |
| 49 | * Flexibility - your application data volume may be a given |
| 50 | size and it is inconvenient to resize it to |
| 51 | add encryption.You can store the LUKS header |
| 52 | separately and use the existing storage |
| 53 | volume for payload |
| 54 | * Recovery - corruption of a bit in the header may make the |
| 55 | entire payload inaccessible. It might be |
| 56 | convenient to take backups of the header. If |
| 57 | your primary disk header becomes corrupt, you |
| 58 | can unlock the data still by pointing to the |
| 59 | backup detached header |
| 60 | |
| 61 | Architecture |
| 62 | ============ |
| 63 | |
| 64 | Take the qcow2 encryption, for example. The architecture of the |
| 65 | LUKS volume with detached header is shown in the diagram below. |
| 66 | |
| 67 | There are two children of the root node: a file and a header. |
| 68 | Data from the disk payload is stored in the file node. The |
| 69 | LUKS header and key material are located in the header node, |
| 70 | as previously mentioned. |
| 71 | |
| 72 | :: |
| 73 | |
| 74 | +-----------------------------+ |
| 75 | Root node | foo[luks] | |
| 76 | +-----------------------------+ |
| 77 | | | |
| 78 | file | header | |
| 79 | | | |
| 80 | +---------------------+ +------------------+ |
| 81 | Child node |payload-format[qcow2]| |header-format[raw]| |
| 82 | +---------------------+ +------------------+ |
| 83 | | | |
| 84 | file | file | |
| 85 | | | |
| 86 | +----------------------+ +---------------------+ |
| 87 | Child node |payload-protocol[file]| |header-protocol[file]| |
| 88 | +----------------------+ +---------------------+ |
| 89 | | | |
| 90 | | | |
| 91 | | | |
| 92 | Host storage Host storage |
| 93 | |
| 94 | Usage |
| 95 | ===== |
| 96 | |
| 97 | Create a LUKS disk with a detached header using qemu-img |
| 98 | -------------------------------------------------------- |
| 99 | |
| 100 | Shell commandline:: |
| 101 | |
| 102 | # qemu-img create --object secret,id=sec0,data=abc123 -f luks \ |
| 103 | -o cipher-alg=aes-256,cipher-mode=xts -o key-secret=sec0 \ |
| 104 | -o detached-header=true test-header.img |
| 105 | # qemu-img create -f qcow2 test-payload.qcow2 200G |
| 106 | # qemu-img info 'json:{"driver":"luks","file":{"filename": \ |
| 107 | "test-payload.img"},"header":{"filename":"test-header.img"}}' |
| 108 | |
| 109 | Set up a VM's LUKS volume with a detached header |
| 110 | ------------------------------------------------ |
| 111 | |
| 112 | Qemu commandline:: |
| 113 | |
| 114 | # qemu-system-x86_64 ... \ |
| 115 | -object '{"qom-type":"secret","id":"libvirt-3-format-secret", \ |
| 116 | "data":"abc123"}' \ |
| 117 | -blockdev '{"driver":"file","filename":"/path/to/test-header.img", \ |
| 118 | "node-name":"libvirt-1-storage"}' \ |
| 119 | -blockdev '{"node-name":"libvirt-1-format","read-only":false, \ |
| 120 | "driver":"raw","file":"libvirt-1-storage"}' \ |
| 121 | -blockdev '{"driver":"file","filename":"/path/to/test-payload.qcow2", \ |
| 122 | "node-name":"libvirt-2-storage"}' \ |
| 123 | -blockdev '{"node-name":"libvirt-2-format","read-only":false, \ |
| 124 | "driver":"qcow2","file":"libvirt-2-storage"}' \ |
| 125 | -blockdev '{"node-name":"libvirt-3-format","driver":"luks", \ |
| 126 | "file":"libvirt-2-format","header":"libvirt-1-format","key-secret": \ |
| 127 | "libvirt-3-format-secret"}' \ |
| 128 | -device '{"driver":"virtio-blk-pci","bus":XXX,"addr":YYY,"drive": \ |
| 129 | "libvirt-3-format","id":"virtio-disk1"}' |
| 130 | |
| 131 | Add LUKS volume to a VM with a detached header |
| 132 | ---------------------------------------------- |
| 133 | |
| 134 | 1. object-add the secret for decrypting the cipher stored in |
| 135 | LUKS header above:: |
| 136 | |
| 137 | # virsh qemu-monitor-command vm '{"execute":"object-add", \ |
| 138 | "arguments":{"qom-type":"secret", "id": \ |
| 139 | "libvirt-4-format-secret", "data":"abc123"}}' |
| 140 | |
| 141 | 2. block-add the protocol node for LUKS header:: |
| 142 | |
| 143 | # virsh qemu-monitor-command vm '{"execute":"blockdev-add", \ |
| 144 | "arguments":{"node-name":"libvirt-1-storage", "driver":"file", \ |
| 145 | "filename": "/path/to/test-header.img" }}' |
| 146 | |
| 147 | 3. block-add the raw-drived node for LUKS header:: |
| 148 | |
| 149 | # virsh qemu-monitor-command vm '{"execute":"blockdev-add", \ |
| 150 | "arguments":{"node-name":"libvirt-1-format", "driver":"raw", \ |
| 151 | "file":"libvirt-1-storage"}}' |
| 152 | |
| 153 | 4. block-add the protocol node for disk payload image:: |
| 154 | |
| 155 | # virsh qemu-monitor-command vm '{"execute":"blockdev-add", \ |
| 156 | "arguments":{"node-name":"libvirt-2-storage", "driver":"file", \ |
| 157 | "filename":"/path/to/test-payload.qcow2"}}' |
| 158 | |
| 159 | 5. block-add the qcow2-drived format node for disk payload data:: |
| 160 | |
| 161 | # virsh qemu-monitor-command vm '{"execute":"blockdev-add", \ |
| 162 | "arguments":{"node-name":"libvirt-2-format", "driver":"qcow2", \ |
| 163 | "file":"libvirt-2-storage"}}' |
| 164 | |
| 165 | 6. block-add the luks-drived format node to link the qcow2 disk |
| 166 | with the LUKS header by specifying the field "header":: |
| 167 | |
| 168 | # virsh qemu-monitor-command vm '{"execute":"blockdev-add", \ |
| 169 | "arguments":{"node-name":"libvirt-3-format", "driver":"luks", \ |
| 170 | "file":"libvirt-2-format", "header":"libvirt-1-format", \ |
| 171 | "key-secret":"libvirt-2-format-secret"}}' |
| 172 | |
| 173 | 7. hot-plug the virtio-blk device finally:: |
| 174 | |
| 175 | # virsh qemu-monitor-command vm '{"execute":"device_add", \ |
| 176 | "arguments": {"driver":"virtio-blk-pci", \ |
| 177 | "drive": "libvirt-3-format", "id":"virtio-disk2"}} |
| 178 | |
| 179 | TODO |
| 180 | ==== |
| 181 | |
| 182 | 1. Support the shared detached LUKS header within the VM. |