Trusted Platform Module
Athena OS leverages the system’s TPM 2.0 (Trusted Platform Module) to measure and attest the integrity of the boot chain: firmware, bootloader, kernel, and in some cases even the disk encryption policy.
This is called measured boot: each critical component is hashed and recorded in TPM registers called PCRs (Platform Configuration Registers).
Those measurements can then be used to:
- Decide whether to release secrets (like disk decryption keys).
- Detect tampering in firmware, bootloader, or kernel.
- Prove to the OS that the machine booted in a trusted state.
Athena OS integrates this with features like:
What is a TPM?
Section titled “What is a TPM?”A TPM is a hardware security chip. It can:
- Store secrets (keys) in a way that software alone can’t just read out.
- “Seal” secrets to a known-good system state, defined by PCR values.
- Detect when firmware/bootloader/kernel changed unexpectedly, including malicious changes.
In Athena OS, this means:
- Your encryption key can be released automatically only if the system still matches the trusted boot measurements.
- If someone tampers with your bootloader or kernel, the TPM refuses to release that key.
PCRs (Platform Configuration Registers)
Section titled “PCRs (Platform Configuration Registers)”PCRs are small registers in the TPM that hold cryptographic measurements of the boot process.
Each PCR corresponds to a different stage or component. Values are “extended”, not overwritten, so they form an audit trail of what actually booted.
| PCR | Description | Extended by |
|---|---|---|
| PCR0 | Core System Firmware executable code (aka Firmware). May change if you upgrade your UEFI. | Firmware |
| PCR1 | Core System Firmware data (aka UEFI settings; configured boot order, for example) | Firmware |
| PCR2 | Extended or pluggable executable code (aka OpROMs) | Firmware |
| PCR3 | Extended or pluggable firmware data. Set during Boot Device Select UEFI boot phase. | Firmware |
| PCR4 | Boot Manager Code and Boot Attempts. Measures the boot manager and the devices that the firmware tried to boot from. | Firmware |
| PCR5 | Boot Manager Configuration and Data. Can measure configuration of boot loaders; includes the GPT Partition Table. | Firmware |
| PCR6 | Resume from S4 and S5 Power State Events | Firmware |
| PCR7 | Secure Boot State. Contains the full contents of PK/KEK/db, as well as the specific certificates used to validate each boot application | Firmware, shim (adds MokList, MokListX, and MokSBState) |
| PCR8 | Hash of the kernel command line | GRUB |
| PCR9 | Hash of the initramfs and EFI Load Options | Linux (measures the initramfs and EFI Load Options, essentially the kernel cmdline options) |
| PCR10 | Reserved for Future Use | |
| PCR11 | Hash of the Unified kernel image | systemd-stub |
| PCR12 | Overridden kernel command line, Credentials | systemd-stub |
| PCR13 | System Extensions | systemd-stub |
| PCR14 | shim’s MokList, MokListX, and MokSBState. | shim |
| PCR15 | Hash of the LUKS volume key | systemd-cryptsetup |
| PCR16 | Debug. May be used and reset at any time. May be absent from an official firmware release. | |
| PCR23 | Application Support. The OS can set and reset this PCR. |
Why PCRs matter
Section titled “Why PCRs matter”Secrets (like your LUKS decryption key) can be sealed to specific PCR values.
That means: “only release this secret if PCRx, PCRy, PCRz, … match what they were when I enrolled.”
If anything in the boot chain changes - new firmware, unsigned bootloader, injected kernel, malicious initramfs - those PCR values change, and the TPM refuses to release the secret.
This protects you even if:
- The attacker has physical access.
- The drive is stolen.
- Someone tries an “evil maid” attack by swapping your bootloader.
PCR enforcing
Section titled “PCR enforcing”To improve integrity checks in Athena at firmware, boot and kernel level, after Athena OS installation, set up the PCRs you wish, for example PCR7 and PCR15, by running:
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7+15 /dev/nvme0n1p5and providing the LUKS password.
The command will add that information in a TPM keyslot.
In this manner, on the next boots, until the integrity of your firmware, boot loader and kernel is not tampered, you will automatically get into Athena OS without entering the LUKS passphrase.
A good initial approach would be to add PCR7 and PCR11, in order to not be too much strict:
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-public-key=/etc/systemd/tpm2-pcr-initrd-public-key.pem --tpm2-public-key-pcrs=11 --tpm2-pcrs=7 /dev/nvme0n1p5If you are interested to set more PCRs, refer to the table above for details and assign their ID number to the --tpm2-pcrs parameter.
Keyslot management
Section titled “Keyslot management”To view the list of all created keyslots in TPM, run:
sudo cryptsetup luksDump /dev/nvme0n1p5To remove specific TPM slots, run:
sudo systemd-cryptenroll --wipe-slot=1,3If you want to remove all the TPM slots:
sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/sdXNTPM policy signing for PCR11
Section titled “TPM policy signing for PCR11”During UKI generation, Athena OS automatically signs the TPM measurement policy so that the Unified Kernel Image (UKI) can participate in measured boot and support automatic LUKS unlocks bound to PCR 11.
This is handled by the system’s UKI build script, which calls ukify with TPM measurement keys:
--pcr-private-key /etc/systemd/tpm2-pcr-private-key-system.pem \--pcr-public-key /etc/systemd/tpm2-pcr-public-key-system.pem \--phases enter-initrdThose key pairs are generated during installation and used to sign the boot measurement policy. That signature allows the TPM to verify and attest the authenticity of the measurements extending into PCR 11, which records the unified kernel image.
In practice, this means:
- The TPM can validate that the UKI itself has not been replaced or tampered with.
- When a LUKS key slot is sealed to PCR 11 (for example,
--tpm2-public-key-pcrs=11 --tpm2-pcrs=7+15), it will automatically unlock only if the booted UKI matches the trusted, signed measurement policy. - Any unsigned or modified UKI will change PCR11, causing the TPM to refuse to release the decryption key and instead prompt for your passphrase.
Athena OS defines these UKI signing parameters in its build script:
PHASES_SYSTEM="enter-initrd"PHASES_INITRD="enter-initrd"Only the early boot stage (enter-initrd) is measured, ensuring safe and reproducible TPM-bound behavior while maintaining system integrity.
This approach integrates seamlessly with Athena’s Secure Boot and Measured Boot pipeline.
Multiple TPM key slots - Which one unlocks?
Section titled “Multiple TPM key slots - Which one unlocks?”You can add more than one TPM2-based key slot to your encrypted disk.
Each slot can use different PCRs (Platform Configuration Registers). These are numbers that represent what parts of your system are measured into the TPM when you boot.
For example:
| Slot | PCRs Used | What It Checks |
|---|---|---|
| 0 | 1, 5, 7 | Firmware + Bootloader + Kernel |
| 1 | 7 | Only the Kernel / UKI |
| 2 | 1–6, 8, 10 | Almost the entire boot chain |
When you start your computer:
- systemd-cryptsetup tries every TPM key slot in order.
- Each slot asks the TPM: “Do the PCR values still match what I was sealed with?”
- The first slot whose PCRs match will unseal the secret key and unlock the disk.
- Slots whose PCRs no longer match (because the firmware or kernel changed) are ignored.
In plain English:
The disk will unlock as long as one TPM key slot still matches your current boot state.
This means you can safely create:
- a strict slot tied to everything (detects tampering), and
- a relaxed slot (for example, PCR 7 only) that still works after firmware updates.
If a stricter slot fails but the relaxed one matches, your system still boots. You just lose the extra tamper-evidence until you re-enroll the strict slot.
”Why did my machine suddenly ask for the LUKS passphrase?”
Section titled “”Why did my machine suddenly ask for the LUKS passphrase?””Scenario:
- Yesterday it auto-unlocked via TPM.
- Today it dropped to a password prompt.
This is expected when PCR measurements change.
Typical reasons:
- Firmware/UEFI update
- Kernel/initramfs update (especially if you switched kernels manually or modified initramfs)
- Secure Boot policy / shim MOK changes
- Real tampering with bootloader or kernel
When that happens:
- The TPM says “this isn’t the same platform state I trust.”
- The TPM will not unseal the stored LUKS key.
- The boot process falls back to asking you for the passphrase you set at install time.
After you successfully boot with the manual passphrase, you can safely re-enroll a fresh TPM key binding to match the new trusted state:
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7+9+11+14 /dev/nvme0n1p5Keep that passphrase safe. If you lose it and PCRs no longer match, you’re locked out.
If you clear or wipe the TPM, you destroy sealed secrets, including Windows BitLocker keys on dual-boot systems. Back up your BitLocker recovery key before doing anything that resets TPM state.
Relationship to Secure Boot & UKI
Section titled “Relationship to Secure Boot & UKI”- Secure Boot makes sure only signed boot components are executed.
- Measured Boot (PCRs) records what actually ran.
- UKI (Unified Kernel Image) puts the kernel, initramfs, and command line into one signed artifact measured into PCR11.
Athena OS uses all of these together. The end result: tampering with firmware, shim, kernel, initramfs, or kernel parameters is detectable, and can directly block access to secrets.