[Libguestfs] [libguestfs PATCH 2/3] introduce the "clevis_luks_unlock" API
Richard W.M. Jones
rjones at redhat.com
Tue Jun 28 14:57:01 UTC 2022
On Tue, Jun 28, 2022 at 01:54:17PM +0200, Laszlo Ersek wrote:
> Introduce a new guestfs API called "clevis_luks_unlock". At the libguestfs
> level, it is quite simple; it wraps the "clevis luks unlock" guest command
> (implemented by the "clevis-luks-unlock" executable, which is in fact a
> shell script).
>
> The complexity is instead in the network-based disk encryption
> (Clevis/Tang) scheme. Useful documentation:
>
> - https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/security_hardening/index#configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening
> - https://github.com/latchset/clevis#clevis
> - https://github.com/latchset/tang#tang
>
> The package providing "clevis-luks-unlock" is usually called
> "clevis-luks", occasionally "clevis". Some distros don't package clevis at
> all. Add the new API under a new option group (which may not be available)
> called "clevisluks".
>
> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1809453
> Signed-off-by: Laszlo Ersek <lersek at redhat.com>
> ---
> daemon/Makefile.am | 1 +
> generator/actions_core.ml | 38 +++++++++++++
> generator/proc_nr.ml | 1 +
> daemon/clevis-luks.c | 58 ++++++++++++++++++++
> appliance/packagelist.in | 4 ++
> lib/MAX_PROC_NR | 2 +-
> lib/guestfs.pod | 19 +++++--
> 7 files changed, 118 insertions(+), 5 deletions(-)
>
> diff --git a/daemon/Makefile.am b/daemon/Makefile.am
> index bbd49f9ea1e0..f50faecd6930 100644
> --- a/daemon/Makefile.am
> +++ b/daemon/Makefile.am
> @@ -96,10 +96,11 @@ guestfsd_SOURCES = \
> btrfs.c \
> caml-stubs.c \
> cap.c \
> checksum.c \
> cleanups.c \
> + clevis-luks.c \
> cmp.c \
> command.c \
> command.h \
> compress.c \
> copy.c \
> diff --git a/generator/actions_core.ml b/generator/actions_core.ml
> index 807150615426..1b1fdcf77209 100644
> --- a/generator/actions_core.ml
> +++ b/generator/actions_core.ml
> @@ -9718,6 +9718,44 @@ and I<not> the name of the underlying block device." };
> style = RErr, [String (Pathname, "dir"); String (FileOut, "filename")], [];
> visibility = VInternal;
> shortdesc = "read directories entries";
> longdesc = "Internal function for readdir." };
>
> + { defaults with
> + name = "clevis_luks_unlock"; added = (1, 49, 3);
> + style = RErr,
> + [String (Device, "device"); String (PlainString, "mapname")],
PlainString because we create the device from the mapname, we're not
passing (this) device in as a parameter, so this is correct.
However do we never need any optional parameters? cryptsetup_open has
[OBool "readonly"; OString "crypttype"].
> + [];
> + optional = Some "clevisluks";
> + test_excuse = "needs networking and a configured Tang server";
> + shortdesc = "open an encrypted LUKS block device with Clevis and Tang";
> + longdesc = "\
> +This command opens a block device that has been encrypted according to the Linux
> +Unified Key Setup (LUKS) standard, using network-bound disk encryption (NBDE).
> +
> +C<device> is the encrypted block device.
> +
> +The appliance will connect to the Tang servers noted in the tree of Clevis pins
> +that is bound to a keyslot of the LUKS header. The Clevis pin tree may comprise
> +C<sss> (redudancy) pins as internal nodes (optionally), and C<tang> pins as
> +leaves. C<tpm2> pins are not supported. The appliance unlocks the encrypted
> +block device by combining responses from the Tang servers with metadata from the
> +LUKS header; there is no C<key> parameter.
> +
> +This command will fail if networking has not been enabled for the appliance.
> +Refer to C<guestfs_set_network>.
> +
> +The command creates a new block device called F</dev/mapper/mapname>. Reads and
> +writes to this block device are decrypted from and encrypted to the underlying
> +C<device> respectively. Close the decrypted block device with
> +C<guestfs_cryptsetup_close>.
> +
> +C<mapname> cannot be C<\"control\"> because that name is reserved by
> +device-mapper.
> +
> +If this block device contains LVM volume groups, then calling
> +C<guestfs_lvm_scan> with the C<activate> parameter C<true> will make them
> +visible.
> +
> +Use C<guestfs_list_dm_devices> to list all device mapper devices." };
Some lines here are longer than 80 characters, which might cause
problems. Be better to stick to a bit less than 80 chars.
> ]
> diff --git a/generator/proc_nr.ml b/generator/proc_nr.ml
> index bdced51c9acd..edd9bd99d2da 100644
> --- a/generator/proc_nr.ml
> +++ b/generator/proc_nr.ml
> @@ -512,10 +512,11 @@ let proc_nr = [
> 507, "luks_uuid";
> 508, "cryptsetup_open";
> 509, "cryptsetup_close";
> 510, "internal_list_rpm_applications";
> 511, "internal_readdir";
> +512, "clevis_luks_unlock"
> ]
>
> (* End of list. If adding a new entry, add it at the end of the list
> * above. Do not modify anything below this line.
> *----------------------------------------------------------------------
> diff --git a/daemon/clevis-luks.c b/daemon/clevis-luks.c
> new file mode 100644
> index 000000000000..d3d970d78098
> --- /dev/null
> +++ b/daemon/clevis-luks.c
> @@ -0,0 +1,58 @@
> +/* libguestfs - the guestfsd daemon
> + * Copyright (C) 2009-2022 Red Hat Inc.
> + *
> + * This program is free software; you can redistribute it and/or modify
> + * it under the terms of the GNU General Public License as published by
> + * the Free Software Foundation; either version 2 of the License, or
> + * (at your option) any later version.
> + *
> + * This program is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> + * GNU General Public License for more details.
> + *
> + * You should have received a copy of the GNU General Public License
> + * along with this program; if not, write to the Free Software
> + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
> + */
> +
> +#include <config.h>
> +
> +#include "daemon.h"
> +#include "actions.h"
> +#include "optgroups.h"
> +
> +#define MAX_ARGS 8
> +
> +int
> +optgroup_clevisluks_available (void)
> +{
> + return prog_exists ("clevis-luks-unlock");
> +}
> +
> +int
> +do_clevis_luks_unlock (const char *device, const char *mapname)
> +{
> + const char *argv[MAX_ARGS];
> + size_t i = 0;
> + int r;
> + CLEANUP_FREE char *err = NULL;
> +
> + ADD_ARG (argv, i, "clevis");
> + ADD_ARG (argv, i, "luks");
> + ADD_ARG (argv, i, "unlock");
> + ADD_ARG (argv, i, "-d");
> + ADD_ARG (argv, i, device);
> + ADD_ARG (argv, i, "-n");
> + ADD_ARG (argv, i, mapname);
> + ADD_ARG (argv, i, NULL);
> +
> + r = commandv (NULL, &err, argv);
> + if (r == -1) {
> + reply_with_error ("%s: %s: %s", device, mapname, err);
> + return -1;
> + }
> +
> + udev_settle ();
> + return 0;
> +}
> diff --git a/appliance/packagelist.in b/appliance/packagelist.in
> index 77a07acc6ad0..0b79edcdd55d 100644
> --- a/appliance/packagelist.in
> +++ b/appliance/packagelist.in
> @@ -21,10 +21,11 @@ dnl ./configure --with-extra-packages="gdb valgrind [etc]"
>
> dnl Basically the same with a few minor tweaks.
> ifelse(UBUNTU,1,`define(`DEBIAN',1)')
>
> ifelse(REDHAT,1,
> + clevis-luks
> cryptsetup
> cryptsetup-luks dnl old name used before Fedora 17
> dhclient
> gfs-utils
> gfs2-utils
> @@ -51,10 +52,11 @@ ifelse(REDHAT,1,
>
> ifelse(DEBIAN,1,
> bsdmainutils
> dnl old name used in Jessie and earlier
> btrfs-tools
> + clevis-luks
> cryptsetup
> dash
> extlinux
> dnl gfs-tools, gfs2-tools have been renamed to gfs2-utils
> gfs-tools
> @@ -90,10 +92,11 @@ dnl iproute has been renamed to iproute2
> )
>
> ifelse(ARCHLINUX,1,
> cdrkit
> cdrtools
> + clevis
> cryptsetup
> dhclient
> dhcpcd
> gptfdisk
> grub
> @@ -117,10 +120,11 @@ ifelse(ARCHLINUX,1,
> ifelse(SUSE,1,
> dnl It seems no other augeas package depends on it.
> augeas-lenses
> btrfsprogs
> cdrkit-cdrtools-compat
> + clevis
> cryptsetup
> dhcpcd
> dhcp-client
> glibc-locale
> gptfdisk
> diff --git a/lib/MAX_PROC_NR b/lib/MAX_PROC_NR
> index c0556fb20f37..4d0e90cbcbaf 100644
> --- a/lib/MAX_PROC_NR
> +++ b/lib/MAX_PROC_NR
> @@ -1 +1 @@
> -511
> +512
> diff --git a/lib/guestfs.pod b/lib/guestfs.pod
> index 1ad44e7c2878..e10bf1fbec30 100644
> --- a/lib/guestfs.pod
> +++ b/lib/guestfs.pod
> @@ -589,15 +589,26 @@ devices. For LUKS it returns the string C<crypto_LUKS>.
> For Windows BitLocker it returns C<BitLocker>.
>
> Then open these devices by calling L</guestfs_cryptsetup_open>.
> Obviously you will require the passphrase!
>
> +Passphrase-less unlocking is supported for LUKS (not BitLocker)
> +block devices that have been encrypted with network-bound disk
> +encryption (NBDE), using Clevis on the Linux guest side, and
> +Tang on a separate Linux server. Open such devices with
> +L</guestfs_clevis_luks_unlock>. The appliance will need
> +networking enabled (refer to L</guestfs_set_network>) and actual
> +connectivity to the Tang servers noted in the C<tang> Clevis
> +pins that are bound to the LUKS header. (This includes the
> +ability to resolve the names of the Tang servers.)
> +
> Opening an encrypted device creates a new device mapper device
> -called F</dev/mapper/mapname> (where C<mapname> is the
> -string you supply to L</guestfs_cryptsetup_open>).
> -Reads and writes to this mapper device are decrypted from and
> -encrypted to the underlying block device respectively.
> +called F</dev/mapper/mapname> (where C<mapname> is the string
> +you supply to L</guestfs_cryptsetup_open> or
> +L</guestfs_clevis_luks_unlock>). Reads and writes to this mapper
> +device are decrypted from and encrypted to the underlying block
> +device respectively.
>
> LVM volume groups on the device can be made visible by calling
> L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>.
> The logical volume(s) can now be mounted in the usual way.
Looks generally OK.
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html
More information about the Libguestfs
mailing list