Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Deleted] #712

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 122 additions & 103 deletions src/installation/guides/fde.md
Original file line number Diff line number Diff line change
@@ -1,132 +1,131 @@
# Full Disk Encryption

**Warning**: Your drive's block device and other information may be different,
so make sure it is correct.
**Warning**: This guide uses `/dev/vda` as the example device name, Your drive's block device and other information may be different, so make sure it is correct.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop the sda to vda change everywhere.

  1. It's a personal preference that doesn't need to be reconsidered with every update.
  2. Most people deploying full-disk encryption are probably doing so on real hardware, so sda is more likely then vda to be relevant anyway.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We aren't here to save people from themselves when following a destructive guide that describes optional and advanced configuration. The example commands should be generally meaningful , not have bogus placeholders that require replacement.


## Partitioning

Boot a live image and login.

Create a single physical partition on the disk using
[cfdisk](https://man.voidlinux.org/cfdisk), marking it as bootable. For an MBR
system, the partition layout should look like the following.
For a BIOS/MBR system, Create a single physical partition on the disk using
[cfdisk](https://man.voidlinux.org/cfdisk) with a `dos` label type, Mark it as bootable.
Now the partition layout should look similar to the following.
Comment on lines +9 to +11
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For a BIOS/MBR system, Create a single physical partition on the disk using
[cfdisk](https://man.voidlinux.org/cfdisk) with a `dos` label type, Mark it as bootable.
Now the partition layout should look similar to the following.
For a BIOS system, create a single physical partition on the disk using
[cfdisk](https://man.voidlinux.org/cfdisk) with a `dos` label type. Make sure to mark the partition bootable.
The layout should look like the following.

Again, "like" to "similar to" is a preference change that we don't need to make.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's the point of a review. The point is to avoid making stylistic changes to an existing guide when there is no functional purpose for them.

BIOS/MBR is unnecessary because you already instruct people to make a 'dos' label, which is the nomenclature for MBR in the partition program.


```
# fdisk -l /dev/sda
Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors
# fdisk -l /dev/vda
Disk /dev/vda: 48 GiB, 51539607552 bytes, 100663296 sectors
Comment on lines +14 to +15
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop

Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x4d532059

Device Boot Start End Sectors Size Id Type
/dev/sda1 * 2048 100663295 100661248 48G 83 Linux
/dev/vda1 * 2048 100663295 100661248 48G 83 Linux
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop

```

UEFI systems will need the disk to have a GPT disklabel and an EFI system
partition. The required size for this may vary depending on needs, but 100M
should be enough for most cases. For an EFI system, the partition layout should
look like the following.
look similar to the following.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop


```
# fdisk -l /dev/sda
Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors
# fdisk -l /dev/vda
Disk /dev/vda: 48 GiB, 51539607552 bytes, 100663296 sectors
Comment on lines +32 to +33
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop

Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: EE4F2A1A-8E7F-48CA-B3D0-BD7A01F6D8A0

Device Start End Sectors Size Type
/dev/sda1 2048 264191 262144 128M EFI System
/dev/sda2 264192 100663262 100399071 47.9G Linux filesystem
/dev/vda1 2048 264191 262144 128M EFI System
/dev/vda2 264192 100663262 100399071 47.9G Linux filesystem
Comment on lines +41 to +42
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop

```

## Encrypted volume configuration

[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2, yet GRUB
releases before 2.06 only had support for LUKS1. Therefore, it might make sense
to force LUKS1 if you wish to achieve better compatibility.
[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2, GRUB
2.06 introduced support for LUKS2, but did not add support for the LUKS2 default
cryptographic algorithm, [Argon2i](https://en.wikipedia.org/wiki/Argon2).
Therefore, for compatibility reasons it might make sense to use LUKS1 until GRUB
receives support for Argon2i.
Comment on lines +47 to +51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2, GRUB
2.06 introduced support for LUKS2, but did not add support for the LUKS2 default
cryptographic algorithm, [Argon2i](https://en.wikipedia.org/wiki/Argon2).
Therefore, for compatibility reasons it might make sense to use LUKS1 until GRUB
receives support for Argon2i.
[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2. Although GRUB
2.06 introduced support for LUKS2, it did not add support for the default
[Argon2i](https://en.wikipedia.org/wiki/Argon2) cryptographic algorithm.
Using LUKS1 with GRUB may be desirable until GRUB supports Argon2i.


Keep in mind the encrypted volume will be `/dev/sda2` on EFI systems, since
`/dev/sda1` is taken up by the EFI partition.
**Warning**: If the password for the encrypted partition is lost it will become near (or completely) impossible to recover any data or the password
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop; people attempting full disk encryption should already know that they need to remember the passwords they set.


```
# cryptsetup luksFormat --type luks1 /dev/sda1

WARNING!
========
This will overwrite data on /dev/sda1 irrevocably.
On legacy BIOS systems this command would use `/dev/vda1`.

Are you sure? (Type uppercase yes): YES
Enter passphrase:
Verify passphrase:
```
# cryptsetup luksFormat --type luks1 /dev/vda2
```

Once the volume is created, it needs to be opened. Replace `voidvm` with an
appropriate name. Again, this will be `/dev/sda2` on EFI systems.
Once the volume is created, it needs to be opened. `voidvm` is a example name
you can replace it with a name of your choosing. Again, this will be `/dev/vda1` on legacy BIOS systems.

```
# cryptsetup luksOpen /dev/sda1 voidvm
Enter passphrase for /dev/sda1:
# cryptsetup open /dev/vda2 voidvm
```
Comment on lines -55 to 66
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest a more generic approach to the BIOS/UEFI split:

To avoid overwriting the wrong partition, set an environment variable to the partition that will be encrypted. For UEFI systems:

export LUKSPART=/dev/sda2

For BIOS systems:

export LUKSPART=/dev/sda1

Next, format and then open the LUKS volume. In this example, the LUKS volume will be opened as voidvm, but the name can be replaced as desired.

# cryptsetup luksFormat --type luks1 "${LUKSPART}"
# cryptsetup open "${LUKSPART}" voidvm


Once the LUKS container is opened, create the LVM volume group using that
partition.
### LVM

Once the LUKS partition is opened you can create a [LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)) volume group using that
partition.
LVM is optional and may have its advantages or disadvantages depending on your system configuration.

The volume group name is not required to be the same as the LUKS partition name chosen above,
But for consistency purposes it may be easier to use the same name for the volume group.

```
# vgcreate voidvm /dev/mapper/voidvm
Volume group "voidvm" successfully created
```

There should now be an empty volume group named `voidvm`.

Next, logical volumes need to be created for the volume group. For this example,
I chose 10G for `/`, 2G for `swap`, and will assign the rest to `/home`.
Next, logical volumes need to be created for the volume group.
For this example, All of the available space is assigned to `/`.

The name chosen using `--name` should be noted because it will be used when mounting the partition, For example, `/dev/voidvm/root`.

```
# lvcreate --name root -L 10G voidvm
Logical volume "root" created.
# lvcreate --name swap -L 2G voidvm
Logical volume "swap" created.
# lvcreate --name home -l 100%FREE voidvm
Logical volume "home" created.
# lvcreate --name root -l 100%FREE voidvm
```

Next, create the filesystems. The example below uses XFS as a personal
preference of the author. Any filesystem [supported by
### Filesystem creation

Next, create the filesystems. The example below uses Btrfs. Any filesystem [supported by
GRUB](https://www.gnu.org/software/grub/manual/grub/grub.html#Features) will
work.

On systems using LVM the root filesystem would be created on `/dev/voidvm/root`.

```
# mkfs.btrfs /dev/mapper/voidvm
```

On UEFI systems the EFI partition also needs the filesystem created.

```
# mkfs.xfs -L root /dev/voidvm/root
meta-data=/dev/voidvm/root isize=512 agcount=4, agsize=655360 blks
...
# mkfs.xfs -L home /dev/voidvm/home
meta-data=/dev/voidvm/home isize=512 agcount=4, agsize=2359040 blks
...
# mkswap /dev/voidvm/swap
Setting up swapspace version 1, size = 2 GiB (2147479552 bytes)
# mkfs.vfat -F32 /dev/vda1
```
Comment on lines -75 to 108
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop all of these changes.

  1. LVM is an illustrative example of general purpose volume management atop LUKS.
  2. Adding btrfs atop LVM doesn't make much sense because it comingles competing concepts of volume management. If there is a place for btrfs on LUKS, it is not atop LVM. If there is a place to describe a btrfs-on-LUKS setup, it is as a subsection of a general btrfs guide, not here.
  3. Again, we retain the original XFS preference to avoid non-substantive changes in voice every time somebody touches the guide.

However, you should still note the need to format the EFI system partition, so add a note after the XFS formatting commands:

On UEFI systems, format the EFI System Partition as FAT32.

# mkfs.vfat -F32 /dev/sda1


## System installation

Next, setup the chroot and install the base system.
Next, mount the root partition, On a LVM configuration this would be `/dev/voidvm/root`

```
# mount /dev/mapper/voidvm /mnt
```

Next, some extra directories need to be mounted.

```
# mount /dev/voidvm/root /mnt
# for dir in dev proc sys run; do mkdir -p /mnt/$dir ; mount --rbind /$dir /mnt/$dir ; mount --make-rslave /mnt/$dir ; done
# mkdir -p /mnt/home
# mount /dev/voidvm/home /mnt/home
```

On a UEFI system, the EFI system partition also needs to be mounted.
On a UEFI system, the `/efi` directory needs to be created and EFI system partition needs to be mounted.

```
# mkfs.vfat /dev/sda1
# mkdir -p /mnt/boot/efi
# mount /dev/sda1 /mnt/boot/efi
# mkdir /mnt/efi
# mount /dev/vda1 /mnt/efi
Comment on lines -115 to +128
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop all of these changes.

```

Copy the RSA keys from the installation medium to the target root directory:
Expand All @@ -136,34 +135,28 @@ Copy the RSA keys from the installation medium to the target root directory:
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/
```

Before we enter the chroot to finish up configuration, we do the actual install.
Do not forget to use the [appropriate repository
URL](../../xbps/repositories/index.md#the-main-repository) for the type of
system you wish to install.
Before entering the chroot to finish up configuration, it is time to perform the actual install.
Do not forget to use the [appropriate repository URL](../../xbps/repositories/index.md#the-main-repository)
for the type of system you wish to install.

Legacy BIOS systems use the `grub` package instead of `grub-x86_64-efi`. For LVM users, The `lvm2` package is required.
Comment on lines -139 to +142
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this change.


```
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system lvm2 cryptsetup grub
[*] Updating `https://repo-default.voidlinux.org/current/x86_64-repodata' ...
x86_64-repodata: 1661KB [avg rate: 2257KB/s]
130 packages will be downloaded:
...
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system cryptsetup grub-x86_64-efi
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this change.

```

UEFI systems will have a slightly different package selection. The installation
command for a UEFI system will be as follows.
Before entering the chroot, Copy a DNS configuration file from live system to allow internet connection in the chroot.

```
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system cryptsetup grub-x86_64-efi lvm2
# cp /etc/resolv.conf /mnt/etc/
Comment on lines -152 to +151
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's clean this up a bit:

For UEFI systems, also install necessary GRUB support.

xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt grub-x86_64-efi

```

When it's done, we can enter the `chroot` and finish up the configuration.
Now you can enter the [chroot(1)](https://man.voidlinux.org/chroot.1) and continue configuring the system.

```
# chroot /mnt
# chown root:root /
# chmod 755 /
# passwd root
# echo voidvm > /etc/hostname
# echo AHOSTNAME > /etc/hostname
Comment on lines 157 to +159
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this change, but add the resolv.conf copy before the chroot command.

The chown/chmod are probably superfluous, but it is almost costless to run them and potentially costly should the permissions be wrong.

```

and, for glibc systems only:
Expand All @@ -176,44 +169,51 @@ and, for glibc systems only:

### Filesystem configuration

The next step is editing `/etc/fstab`, which will depend on how you configured
and named your filesystems. For this example, the file should look like this:
Before continuing with filesystem configuration you need to get your [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s,
This can be done using utilities such as: [lsblk(8)](https://man.voidlinux.org/lsblk.8) or [blkid(8)](https://man.voidlinux.org/blkid.8).

The next step is editing `/etc/fstab`,
The UUID needed for `/etc/fstab` is the `/dev/mapper/voidvm` UUID on non-LVM configurations and `/dev/voidvm/root` UUID on LVM configurations

```
# blkid -o value -s UUID /dev/mapper/voidvm
```

```
# <file system> <dir> <type> <options> <dump> <pass>
tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0
/dev/voidvm/root / xfs defaults 0 0
/dev/voidvm/home /home xfs defaults 0 0
/dev/voidvm/swap swap swap defaults 0 0
UUID=ADD-UUID-FROM-BLKID-COMMAND-HERE / btrfs defaults 0 0
Comment on lines -179 to +185
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop these changes.

```


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop

UEFI systems will also have an entry for the EFI system partition.

```
/dev/sda1 /boot/efi vfat defaults 0 0
# blkid -o value -s UUID /dev/vda1
```

```
UUID=ADD-UUID-FROM-BLKID-COMMAND-HERE /efi vfat defaults 0 0
Comment on lines 189 to +196
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean up a bit:

UEFI systems will also have an entry for the EFI system partition. This may look like:

/dev/sda1	/boot/efi	vfat	defaults	0	0

Alternatively, you can replace the device node /dev/sda1 with a UUID, producing a line like:

UUID=<your-uuid>	/boot/efi	vfat	defaults	0	0

where the value of <your-uuid> is taken from the output of the command

# blkid -o value -s UUID /dev/sda1

```

### GRUB configuration

Next, configure GRUB to be able to unlock the filesystem. Add the following line
to `/etc/default/grub`:
Next, configure GRUB to be able to unlock the encrypted filesystem:

```
GRUB_ENABLE_CRYPTODISK=y
# echo "GRUB_ENABLE_CRYPTODISK=y" >> /etc/default/grub
```

Next, the kernel needs to be configured to find the encrypted device. First,
find the UUID of the device.
get the UUID of the device, Again this would be `/dev/vda1` on legacy BIOS systems.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
get the UUID of the device, Again this would be `/dev/vda1` on legacy BIOS systems.
get the UUID of the device referred to by the `$LUKSPART` variable defined as described above.


```
# blkid -o value -s UUID /dev/sda1
135f3c06-26a0-437f-a05e-287b036440a4
# blkid -o value -s UUID /dev/vda2
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# blkid -o value -s UUID /dev/vda2
# blkid -o value -s UUID "${LUKSPART}"

```

Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add
`rd.lvm.vg=voidvm rd.luks.uuid=<UUID>` to it. Make sure the UUID matches the one
for the `sda1` device found in the output of the
[blkid(8)](https://man.voidlinux.org/blkid.8) command above.
Next, Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add
`rd.luks.uuid=ADD-UUID-FROM-BLKID-COMMAND-HERE` to it, If you are on a LVM configuration
also add `rd.lvm.vg=voidvm`.
Comment on lines +214 to +216
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Next, Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add
`rd.luks.uuid=ADD-UUID-FROM-BLKID-COMMAND-HERE` to it, If you are on a LVM configuration
also add `rd.lvm.vg=voidvm`.
Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add
`rd.lvm.vg=voidvm rd.luks.uuid=<UUID>` to it. Make sure the UUID matches the one
for the [blkid(8)](https://man.voidlinux.org/blkid.8) command above.


## LUKS key setup

Expand All @@ -223,16 +223,12 @@ a random key.

```
# dd bs=1 count=64 if=/dev/urandom of=/boot/volume.key
64+0 records in
64+0 records out
64 bytes copied, 0.000662757 s, 96.6 kB/s
```

Next, add the key to the encrypted volume.
Next, add the key to the encrypted volume. Again, this would be `/dev/vda1` on legacy BIOS systems.

```
# cryptsetup luksAddKey /dev/sda1 /boot/volume.key
Enter any existing passphrase:
# cryptsetup luksAddKey /dev/vda2 /boot/volume.key
```

Change the permissions to protect generated the key.
Expand All @@ -242,11 +238,15 @@ Change the permissions to protect generated the key.
# chmod -R g-rwx,o-rwx /boot
```

This keyfile also needs to be added to `/etc/crypttab`. Again, this will be
`/dev/sda2` on EFI systems.
This keyfile also needs to be added to `/etc/crypttab`. Again, this would be
`/dev/vda1` on legacy BIOS systems.

```
voidvm /dev/sda1 /boot/volume.key luks
# blkid -o value -s UUID /dev/vda2
```

```
voidvm UUID=ADD-UUID-FROM-BLKID-COMMAND-HERE /boot/volume.key luks
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Refer to the LUKSPART variable to avoid repeatedly noting the distinction between BIOS and UEFI.

```

And then the keyfile and `crypttab` need to be included in the initramfs. Create
Expand All @@ -260,8 +260,13 @@ install_items+=" /boot/volume.key /etc/crypttab "

Next, install the boot loader to the disk.

For legacy BIOS systems:
```
# grub-install --target=i386-pc /dev/vda
```
For UEFI systems:
```
# grub-install /dev/sda
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id="Void"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id="Void"
# grub-install --target=x86_64-efi --bootloader-id="Void"

I assume it isn't necessary to specify a path to /boot/efi and I recommend against the change from /boot/efi to /efi. However, I don't know anything about GRUB, so --efi-directory=/boot/efi may still be required.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The disadvantage is that you have to specify the alternative path for GRUB.

The possibility of an Evil Maid attack has nothing to do with the mount point of the EFI system partition. You add no defense by mounting it somewhere else.

Copy link
Contributor

@abenson abenson Oct 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this guide, /boot is encrypted already, so I'm not sure what you mean. ESP is going to be subject to Evil Maid no matter where it gets mounted, since itsn't encrypted.

```

Ensure an initramfs is generated:
Expand All @@ -270,10 +275,24 @@ Ensure an initramfs is generated:
# xbps-reconfigure -fa
```

Exit the `chroot`, unmount the filesystems, and reboot the system.
Exit the `chroot`, unmount the filesystems.

```
# exit
# umount -R /mnt
```

If you are using a LVM configuration you will need to run the following commands before continuing with the rest of the commands.

```
# lvchange -an voidvm

# cryptsetup close /dev/voidvm/root
```

Finally, Close the encrypted partition and reboot the system.

```
# cryptsetup close /dev/mapper/voidvm
Comment on lines +283 to +296
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does any of this matter? If so:

Suggested change
```
If you are using a LVM configuration you will need to run the following commands before continuing with the rest of the commands.
```
# lvchange -an voidvm
# cryptsetup close /dev/voidvm/root
```
Finally, Close the encrypted partition and reboot the system.
```
# cryptsetup close /dev/mapper/voidvm
# lvchange -an voidvm
# cryptsetup close /dev/mapper/voidvm

Otherwise, just drop all of this and go straight to the reboot.

# reboot
```