From c85814db1af65eb7c2350162411ac74a557f75cf Mon Sep 17 00:00:00 2001 From: JMARyA Date: Mon, 16 Dec 2024 16:20:32 +0100 Subject: [PATCH] add sbctl + systemd-cryptenroll --- technology/applications/Applications.md | 2 + technology/linux/mkinitcpio.md | 46 +++++-- technology/linux/sbctl.md | 57 ++++++++ .../linux/systemd/systemd-cryptenroll.md | 130 ++++++++++++++++++ 4 files changed, 221 insertions(+), 14 deletions(-) create mode 100644 technology/linux/sbctl.md create mode 100644 technology/linux/systemd/systemd-cryptenroll.md diff --git a/technology/applications/Applications.md b/technology/applications/Applications.md index 36d6fe3..9b556b4 100644 --- a/technology/applications/Applications.md +++ b/technology/applications/Applications.md @@ -249,6 +249,8 @@ rev: 2024-12-10 - [mergerfs](../linux/filesystems/MergerFS.md) - [sshfs](../linux/filesystems/SSHFS.md) - [wine](../windows/Wine.md) +- [sbctl](../linux/sbctl.md) +- [systemd-cryptenroll](../linux/systemd/systemd-cryptenroll.md) ## Development - [act](./development/act.md) diff --git a/technology/linux/mkinitcpio.md b/technology/linux/mkinitcpio.md index 3229342..21d8ab7 100644 --- a/technology/linux/mkinitcpio.md +++ b/technology/linux/mkinitcpio.md @@ -1,5 +1,7 @@ --- obj: concept +arch-wiki: https://wiki.archlinux.org/title/Mkinitcpio +rev: 2024-12-16 --- # mkinitcpio @@ -8,20 +10,11 @@ The initial ramdisk is in essence a very small environment (early userspace) whi ## Configuration The primary configuration file for _mkinitcpio_ is `/etc/mkinitcpio.conf`. Additionally, preset definitions are provided by kernel packages in the `/etc/mkinitcpio.d` directory (e.g. `/etc/mkinitcpio.d/linux.preset`). -`MODULES` -Kernel modules to be loaded before any boot hooks are run. - -`BINARIES` -Additional binaries to be included in the initramfs image. - -`FILES` -Additional files to be included in the initramfs image. - -`HOOKS` -Hooks are scripts that execute in the initial ramdisk. - -`COMPRESSION` -Used to compress the initramfs image. +- `MODULES` : Kernel modules to be loaded before any boot hooks are run. +- `BINARIES` : Additional binaries to be included in the initramfs image. +- `FILES` : Additional files to be included in the initramfs image. +- `HOOKS` : Hooks are scripts that execute in the initial ramdisk. +- `COMPRESSION` : Used to compress the initramfs image. ### MODULES The `MODULES` array is used to specify modules to load before anything else is done. @@ -61,3 +54,28 @@ The default `HOOKS` setting should be sufficient for most simple, single disk se | **lvm2** | Adds the device mapper kernel module and the `lvm` tool to the image. | | **fsck** | Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and `/usr` if separate) prior to mounting. If added after the **autodetect** hook, only the helper specific to your root file system will be added. Usage of this hook is **strongly** recommended, and it is required with a separate `/usr` partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace. | | **filesystems** | This includes necessary file system modules into your image. This hook is **required** unless you specify your file system modules in `MODULES`. | + +### UKI +A Unified Kernel Image (UKI) is a single executable file that can be directly booted by UEFI firmware or automatically sourced by boot-loaders. + +In essence, a UKI combines all the necessary components for the operating system to start up, including: +- EFI stub loader +- Kernel command line +- Microcode updates +- Initramfs image (initial RAM file system) +- Kernel image itself +- Splash screen + +To enable the UKI edit `/etc/mkinitcpio.d/linux.preset`: + +```sh +default_uki="/boot/EFI/Linux/arch-linux.efi" + +fallback_uki="/boot/EFI/Linux/arch-linux-fallback.efi" +``` + +Build the Unified Kernel Image: + +```sh +mkinitcpio --allpresets +``` diff --git a/technology/linux/sbctl.md b/technology/linux/sbctl.md new file mode 100644 index 0000000..e6403a9 --- /dev/null +++ b/technology/linux/sbctl.md @@ -0,0 +1,57 @@ +--- +obj: application +repo: https://github.com/Foxboron/sbctl +rev: 2024-12-16 +--- + +# sbctl (Secure Boot Manager) +sbctl intends to be a user-friendly secure boot key manager capable of setting up secure boot, offer key management capabilities, and keep track of files that needs to be signed in the boot chain. + +## Usage +Install the necessary packages: +```sh +pacman -S sbctl sbsigntools +``` + +Check that Secure Boot "Setup Mode" is "Enabled" in UEFI: +```sh +sbctl status +``` + +Create your own signing keys: +```sh +sbctl create-keys +``` + +Sign the systemd bootloader: +```sh +sbctl sign -s \ + -o /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed \ + /usr/lib/systemd/boot/efi/systemd-bootx64.efi +``` + +Enroll your custom keys: +```sh +sbctl enroll-keys + +# Enroll and include Microsoft Keys +sbctl enroll-keys --microsoft +``` + +Sign EFI files: +```sh +sbctl sign -s /boot/EFI/Linux/arch-linux.efi +sbctl sign -s /boot/EFI/Linux/arch-linux-fallback.efi +sbctl sign -s /efi/EFI/systemd/systemd-bootx64.efi +sbctl sign -s /efi/EFI/Boot/bootx64.efi +``` + +Verify signature of EFI files: +```sh +sbctl verify +``` + +Resign everything: +```sh +sbctl sign-all +``` diff --git a/technology/linux/systemd/systemd-cryptenroll.md b/technology/linux/systemd/systemd-cryptenroll.md new file mode 100644 index 0000000..de126dc --- /dev/null +++ b/technology/linux/systemd/systemd-cryptenroll.md @@ -0,0 +1,130 @@ +--- +obj: application +arch-wiki: https://wiki.archlinux.org/title/Systemd-cryptenroll +rev: 2024-12-16 +--- + +# systemd-cryptenroll +systemd-cryptenroll allows enrolling smartcards, FIDO2 tokens and Trusted Platform Module security chips into LUKS devices, as well as regular passphrases. These devices are later unlocked by `systemd-cryptsetup@.service`, using the enrolled tokens. + +## Usage + +### **List keyslots** +systemd-cryptenroll can list the keyslots in a LUKS device, similar to cryptsetup luksDump, but in a more user-friendly format. + +```sh +$ systemd-cryptenroll /dev/disk + +SLOT TYPE + 0 password + 1 tpm2 +``` + +### **Erasing keyslots** + +```sh +systemd-cryptenroll /dev/disk --wipe-slot=SLOT +``` + +Where `SLOT` can be: +- A single keyslot index +- A type of keyslot, which will erase all keyslots of that type. Valid types are `empty`, `password`, `recovery`, `pkcs11`, `fido2`, `tpm2` +- A combination of all of the above, separated by commas +- The string `all`, which erases all keyslots on the device. This option can only be used when enrolling another device or passphrase at the same time. + +The `--wipe-slot` operation can be used in combination with all enrollment options, which is useful to update existing device enrollments: + +```sh +systemd-cryptenroll /dev/disk --wipe-slot=fido2 --fido2-device=auto +``` + +### **Enrolling passphrases** +#### Regular password +This is equivalent to `cryptsetup luksAddKey`. + +```sh +systemd-cryptenroll /dev/disk --password +``` + +#### Recovery key +Recovery keys are mostly identical to passphrases, but are computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The key uses a character set that is easy to type in, and may be scanned off screen via a QR code. + +A recovery key is designed to be used as a fallback if the hardware tokens are unavailable, and can be used in place of regular passphrases whenever they are required. + +```sh +systemd-cryptenroll /dev/disk --recovery-key +``` + +### Enrolling hardware devices +The `--type-device` options must point to a valid device path of their respective type. A list of available devices can be obtained by passing the list argument to this option. Alternatively, if you only have a single device of the desired type connected, the auto option can be used to automatically select it. + +#### PKCS#11 tokens or smartcards +The token or smartcard must contain a RSA key pair, which will be used to encrypt the generated key that will be used to unlock the volume. + +```sh +systemd-cryptenroll /dev/disk --pkcs11-token-uri=device +``` + +#### FIDO2 tokens +Any FIDO2 token that supports the "hmac-secret" extension can be used with systemd-cryptenroll. The following example would enroll a FIDO2 token to an encrypted LUKS2 block device, requiring only user presence as authentication. + +```sh +systemd-cryptenroll /dev/disk --fido2-device=device --fido2-with-client-pin=no +``` + +In addition, systemd-cryptenroll supports using the token's built-in user verification methods: +- `--fido2-with-user-presence` defines whether to verify the user presence (i.e. by tapping the token) before unlocking, defaults to `yes` +- `--fido2-with-user-verification` defines whether to require user verification before unlocking, defaults to `no` + +By default, the cryptographic algorithm used when generating a FIDO2 credential is es256 which denotes Elliptic Curve Digital Signature Algorithm (ECDSA) over NIST P-256 with SHA-256. If desired and provided by the FIDO2 token, a different cryptographic algorithm can be specified during enrollment. + +Suppose that a previous FIDO2 token has already been enrolled and the user wishes to enroll another, the following generates an eddsa credential which denotes EdDSA over Curve25519 with SHA-512 and authenticates the device with a previous enrolled token instead of a password. + +```sh +systemd-cryptenroll /dev/disk --fido2-device=device --fido2-credential-algorithm=eddsa --unlock-fido2-device=auto +``` + +#### Trusted Platform Module +systemd-cryptenroll has native support for enrolling LUKS keys in TPMs. It requires the following: +- `tpm2-tss` must be installed, +- A LUKS2 device (currently the default type used by cryptsetup), +- If you intend to use this method on your root partition, some tweaks need to be made to the initramfs + +To begin, run the following command to list your installed TPMs and the driver in use: + +```sh +systemd-cryptenroll --tpm2-device=list +``` + +> **Tip**: If your computer has multiple TPMs installed, specify the one you wish to use with `--tpm2-device=/path/to/tpm2_device` in the following steps. + +A key may be enrolled in both the TPM and the LUKS volume using only one command. The following example generates a new random key, adds it to the volume so it can be used to unlock it in addition to the existing keys, and binds this new key to PCR 7 (Secure Boot state): + +```sh +systemd-cryptenroll --tpm2-device=auto /dev/sdX +``` + +where `/dev/sdX` is the full path to the encrypted LUKS volume. Use `--unlock-key-file=/path/to/keyfile` if the LUKS volume is unlocked by a keyfile instead of a passphrase. + +> Note: It is possible to require a PIN to be entered in addition to the TPM state being correct. Simply add the option `--tpm2-with-pin=yes` to the command above and enter the PIN when prompted. + +To check that the new key was enrolled, dump the LUKS configuration and look for a systemd-tpm2 token entry, as well as an additional entry in the Keyslots section: + +```sh +cryptsetup luksDump /dev/sdX +``` + +To test that the key works, run the following command while the LUKS volume is closed: + +```sh +systemd-cryptsetup attach mapping_name /dev/sdX none tpm2-device=auto +``` + +where `mapping_name` is your chosen name for the volume once opened. + +##### Modules +If your TPM requires a kernel module, edit `/etc/mkinitcpio.conf` and edit the `MODULES` line to add the module used by your TPM. For instance: + +```sh +MODULES=(tpm_tis) +```