From nobody Thu Nov 14 07:03:01 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1708358867; cv=none; d=zohomail.com; s=zohoarc; b=BV49t1Oy+D6HrU1+R1NlT91IU66snJq1w2zKG7CANNV2UGND/ssY0lGcavCaIsGgzwKOuR7XWJO/7BMZdfotU1msKaNv/9s2X4cPorPVCkfVWAGt90b/JpLX3rgOcDsV/bgLndBjj/xXOLrD1VNJXXGXMAUfJhCXsHN3TSOBlXs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1708358867; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=3RO+D3YekMGBsu2bIZAO9/jWE9gPB9Zx0zWLkbEMK5E=; b=FuJS8qKyIY4Y9dpVYRNS0QLynpoCFEHvEM5V3Mh56bziuXwIta9CHjVObel/0Tg402xdnTLAJahcdxxOz+8mkR4ngSUH7/KFHi3J+qNOmMoWDdutVmWIPGkTTlgfA0un4xq1ex3HlqYL3RWz65xUt332MfeDdyPZ5DxxxaQfPMs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1708358866801705.5313393631913; Mon, 19 Feb 2024 08:07:46 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rc6AZ-0006eb-4X; Mon, 19 Feb 2024 11:07:03 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rc6AU-0006eA-B8 for qemu-devel@nongnu.org; Mon, 19 Feb 2024 11:06:59 -0500 Received: from mail-oo1-xc29.google.com ([2607:f8b0:4864:20::c29]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rc6AQ-00049t-8k for qemu-devel@nongnu.org; Mon, 19 Feb 2024 11:06:58 -0500 Received: by mail-oo1-xc29.google.com with SMTP id 006d021491bc7-59a31c14100so1622356eaf.0 for ; Mon, 19 Feb 2024 08:04:51 -0800 (PST) Received: from anolis-dev.zelin.local ([221.122.98.162]) by smtp.gmail.com with ESMTPSA id p48-20020a056a0026f000b006e466479e90sm1752224pfw.166.2024.02.19.08.04.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 19 Feb 2024 08:04:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=smartx-com.20230601.gappssmtp.com; s=20230601; t=1708358690; x=1708963490; darn=nongnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=3RO+D3YekMGBsu2bIZAO9/jWE9gPB9Zx0zWLkbEMK5E=; b=IOurrxB6JzVO9KPe606CY+/bukQadEpv8wMkPJb8MpB0frCm+3dx9Bi2jrWA4eNw9A XP8d6yi8wrcPb2Dt5cPvelYiD/r4cAKlNMcQ0DfWWxf3Be6+/AWOmy8R4Exlvp382kSF F6ezDVnix3c+OP2zijPCrpzR/vBkdX6RQuP/zdkDyzcQ39nLhixYlt9UzUnnfqhCyXRo jhvg6lSVWubTdn9SeW9ozejPtMe4U2TVvdbJAckuhhOt1ZSZlW7mZH9HKr7ojk/h3HM9 /SCjxerATT2IUNy5RkQ1r+XK4JcfhgzHd12SSIRXR4uUyW2L5A6qA5ZlXtfWUJ/712qG 3zTw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1708358690; x=1708963490; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=3RO+D3YekMGBsu2bIZAO9/jWE9gPB9Zx0zWLkbEMK5E=; b=LCe+hUY+C/zuxxAPxOJfwgFYLyjFcuEbpk9ErXy5sct5NVV7fyY4X3899LDkCl9Ufj iLuW/4Jya1WHIj0/Q+N0OI0HU6iN9n0dgNDfK1Obk4BZQxk9dTFn5LRPY/4l/hqlOAsl KXKwJwQFO2kS5NFKBVqBnHKFKVf/tK7eyUTjkqdLbCfafNu779vpHZQ39hOm1Ejkqk9e g62j//iRdfOcSxJkW9VPcaM1KsJPveHWrL9Z5OfcUttnYaZgKsDicwU3v6+9TBxd05go /I4WcrupO24JAB0NxjGKHC3cuZ5nN0wIQBoiTYuS5OZ0DVfaAV6vzIDmt4ovUsVOE20d AkhQ== X-Gm-Message-State: AOJu0Yxh96Nb5sF6aibNMpQMh1dHzLpApCqw3UrXnBd1Uk2AkNrBEA8e LTljMPiFK+kZBhVXd7R0ySkdt7eczwtglMl+e+OkiecxXci6aSvPtHnJTd1kAe58nXE1OujrWSP vwPk= X-Google-Smtp-Source: AGHT+IHkku5k8rDOA5w03o1+XzOqjtx5gIkDbeFcFCG72Cprz497rARH3wA7AzDQlwZIPn7bwZcxNw== X-Received: by 2002:a05:6358:63a7:b0:17a:e013:9586 with SMTP id k39-20020a05635863a700b0017ae0139586mr14460380rwh.29.1708358689310; Mon, 19 Feb 2024 08:04:49 -0800 (PST) From: Hyman Huang To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Daniel=20P=20=2E=20Berrang=C3=A9?= , Markus Armbruster , Kevin Wolf , Hanna Reitz , Eric Blake , yong.huang@smartx.com Subject: [PATCH] docs/devel: Add introduction to LUKS volume with detached header Date: Tue, 20 Feb 2024 00:04:42 +0800 Message-Id: X-Mailer: git-send-email 2.39.3 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: none client-ip=2607:f8b0:4864:20::c29; envelope-from=yong.huang@smartx.com; helo=mail-oo1-xc29.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_NONE=0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @smartx-com.20230601.gappssmtp.com) X-ZM-MESSAGEID: 1708358869087100003 Signed-off-by: Hyman Huang --- 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 S: Maintained F: tests/qemu-iotests/tests/luks-detached-header +F: docs/devel/luks-detached-header.rst =20 D-Bus M: Marc-Andr=C3=A9 Lureau 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D +LUKS volume with detached header +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D + +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This document gives an overview of the design of LUKS volume with detached +header and how to use it. + +Background +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D + +Create a LUKS disk with a detached header using qemu-img +-------------------------------------------------------- + +Shell commandline:: + +# qemu-img create --object secret,id=3Dsec0,data=3Dabc123 -f luks \ +> -o cipher-alg=3Daes-256,cipher-mode=3Dxts -o key-secret=3Dsec0 \ +> -o detached-header=3Dtrue 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 +=3D=3D=3D=3D + +1. Support the shared detached LUKS header within the VM. --=20 2.39.3