Advanced Encryption

Throughout this page all examples using /dev/disk should be replaced with the correct storage device name of your systems LUKS partition.

You can find your correct storage device and partition like so (Keep in mind your output might look slightly different to the example shown)

Aeon@localhost:~> lsblk
NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
zram0         253:0    0    15G  0 disk  [SWAP]
nvme0n1       259:0    0 953.9G  0 disk  
├─nvme0n1p1   259:1    0     4G  0 part  /boot/efi
└─nvme0n1p2   259:2    0 949.9G  0 part  <--- This one!
 └─aeon_root 254:0    0 949.9G  0 crypt /home
                                        ...

This page is intended for advanced users only.

Incorrectly applying some changes discussed here can result in your system becoming unbootable and your data being impossible to recover.

If you do not know what you are doing, it's best to ignore all the information on this page.

---

General Recommendations

More Credentials can equal less Security

The LUKS cryptography stack used in Aeon allows for any valid credential to unlock the system's encrypted disk partition.

Therefore, only add more credentials if you are confident you can securely store them from potential attackers.

Always keep one Recovery Key or Passphrase

Hardware-based credentials like TPM 2.0 and FIDO2 are secure, reliable, and convenient, but should only be used alongside at least one recovery key or passphrase.

This is because hardware-based credentials are vulnerable to a number of hardware-specific risks:

• Hardware can fail
• FIDO2 keys can be lost
• TPM measurements can become mismatched after certain updates

Also, many tools, including Aeon's installer and systemd-cryptenroll, expect a passphrase or recovery key and may prompt for it during security sensitive functions, such as during reinstallation or changing credentials.

Therefore, make sure there is at least one key slot containing a recovery key or passphrase at all times.

---

Key Slot Layout

For users adding or removing credentials for their LUKS encryption, it's important to understand Aeon's default credentials are set up.

It's not recommended to wipe any of these key slots unless you know precisely what you are doing.

You can check the structure of your systems key slots by running:

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk

For installations using default mode

• Key Slot 0: Empty (was used for temporary credentials during Installation)
• Key Slot 1: TPM 2.0 Key
• Key Slot 2: Recovery Key

For installations using fallback mode

• Key Slot 0: Empty (was used for temporary credentials during Installation)
• Key Slot 1: Passphrase
• Key Slot 2: Recovery Key

---

Complete re-enrollment of TPM2

NOTE: This section is meant for installations using default mode, if you installed in fallback mode everything in this section will be irrelevant for you.

If your TPM2 has been reset/cleared, it's no longer usable for automatically unlocking the encrypted disk partition during boot, because the link to the operating system is missing. To re-enroll it, the entry must first be properly removed, including the policy.

This command will un-enroll the old TPM2 entry:

Aeon@localhost:~> sudo sdbootutil unenroll --method=tpm2

You may optionally check the key slots. Only recovery should be enrolled.

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk
SLOT TYPE
   2 recovery

We now need re-enroll:

Aeon@localhost:~> sudo sdbootutil --ask-pin enroll --method=tpm2

When prompted for the recovery key, enter the original recovery key you received during installation. If you enter a different key, the original key will be used to manually unlock the encrypted disk partition, but the new one will be used to remeasure boot integrity.

You can optionally use:

Aeon@localhost:~> sudo PIN=key sdbootutil enroll --method=tpm2

This should only be used for debugging and testing purposes as bash history will leave your recovery key visible in plain text.

---

Adding additional credentials

Adding additional credentials is mostly useful in fallback mode to provide alternative methods for authenticating or as a precursor to removing credentials that are no longer of use.

In default mode, the main purpose for adding additional credentials is to designate them as an alternative/replacement recovery key.

Passphrase

To add an additional passphrase for unlocking the encrypted disk partition:

Aeon@localhost:~> sudo 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.

A recovery key is designed to be used as a fallback if the hardware-based credentials are unavailable, they may also be used in place of regular passphrases whenever required.

This command generates and enrolls a new recovery key: It will not remove your old one.

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk --recovery-key

Once generated, the new recovery key will appear with a corresponding QR code for it that you may scan with your phone.

FIDO2 tokens

FIDO2 tokens that supports the "HMAC-Secret" extension can be used with Aeon.

The following example would enroll a FIDO2 token to an encrypted LUKS2 block device.

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk --fido2-device=auto

In order to be used for unlocking the encrypted disk partition, you will need to modify /etc/crypttab adding the extra setting ,fido2-device=auto then rebuild the initrd.

Aeon@localhost:~> sudo vim /etc/crypttab

Make the file look like one of the following. Instructions vary depending on wether you installed in default mode or fallback mode:

Instructions for default mode installations.

Before:

Aeon@localhost:~> cat /etc/crypttab
...
aeon_root UUID=XXXX-XXXX-XXXX-XXXX-XXXX none x-initrd.attach,tpm2-device=auto,tpm2-measure-pcr=yes

After:

Aeon@localhost:~> cat /etc/crypttab
...
aeon_root UUID=XXXX-XXXX-XXXX-XXXX-XXXX none x-initrd.attach,tpm2-device=auto,tpm2-measure-pcr=yes,fido2-device=auto

Rebuild initrd:

Aeon@localhost:~> sudo sdbootutil mkinitrd

Instructions for fallback mode installations.

Before:

Aeon@localhost:~> cat /etc/crypttab
...
aeon_root UUID=XXXX-XXXX-XXXX-XXXX-XXXX none x-initrd.attach

After:

Aeon@localhost:~> cat /etc/crypttab
...
aeon_root UUID=XXXX-XXXX-XXXX-XXXX-XXXX none x-initrd.attach,fido2-device=auto

Rebuild initrd:

Aeon@localhost:~> sudo transactional-update initrd

---

Removing credentials

NOTE: Do not attempt to remove the final credential as that may result in an unbootable system and data loss!

Any credential used for unlocking the encrypted disk partition can be removed by running:

Aeon@localhost:~> sudo systemd-cryptenroll --wipe-slot=$NUM /dev/disk

Where $NUM is the number of the key slot identified by:

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk

In default mode, it's strongly recommended to wipe the TPM 2.0 key slot before the last recovery key, as a passphrase or recovery key is required to enroll new credentials.

---

Designating New Recovery Keys

Recovery keys do not have to be the computer generated passphrases as created during Installation or with systemd-cryptenroll --recovery-key

Any passphrase or FIDO2 key slot can also be designated as a recovery key.

Aeon@localhost:~> echo '{"type":"systemd-recovery","keyslots":["$NUM"]}' | sudo /usr/sbin/cryptsetup token import /dev/disk

Where $NUM is the number of the key slot desired to be used as a recovery key.

The key slot number you wish to use can be identified with:

Aeon@localhost:~> sudo systemd-cryptenroll /dev/disk

This allows for advanced use cases like using a hardware FIDO2 key as a recovery key to avoid needing to type a long passphrase in the event of the boot chain security not being validated.