Trusted Platform Module

This article or section needs expansion.

Reason: Needs clarification about usage difference between TPM 1.2 and 2.0, Evil Maid attack defense and Trusted boot. PCR registers sealing and using in combination with LUKS. (Discuss in Talk:Trusted Platform Module)

Trusted Platform Module (TPM) is an international standard for a secure cryptoprocessor, which is a dedicated microprocessor designed to secure hardware by integrating cryptographic keys into devices.

In practice a TPM can be used for various different security applications such as secure boot, key storage and random number generation.

TPM is naturally supported only on devices that have TPM hardware support. If your hardware has TPM support but it is not showing up, it might need to be enabled in the BIOS settings.

Versions

There are two very different TPM specifications: 2.0 and 1.2, which also use different software stacks. This article only describes TPM 2.0, for the older TPM 1.2 see /1.2.

TPM 2.0 allows direct access via /dev/tpm0 (one client at a time), kernel-managed access via /dev/tpmrm0, or managed access through the tpm2-abrmd resource manager daemon. According to a systemd project member, using tpm2-abrmd is no longer recommended. There are two choices of userspace tools, tpm2-tools by Intel and ibm-tss^AUR by IBM.

TPM 2.0 requires UEFI boot; BIOS or Legacy boot systems can only use TPM 1.2.

Some TPM chips can be switched between 2.0 and 1.2 through a firmware upgrade (which can be done only a limited number of times).

Usage

This article or section needs expansion.

Reason: This section is a stub. You can help by expanding it with information on how to set up and use a TPM 2.0 device. (Discuss in Talk:Trusted Platform Module)

Many informative resources to learn how to configure and make use of TPM 2.0 services in daily applications are available from the tpm2-software community.

Checking support

A TPM 2.0 chip has been a requirement for computers certified to run Windows 10 since 2016-07-28.[1] Linux has support for TPM 2.0 since version 3.20[2] and should not require any other steps to be enabled on a default Arch install.

Two ways to verify whether TPM 2.0 is setup without specific software:

checking the logs, e.g., by running journalctl -k --grep=tpm as root
read the value of /sys/class/tpm/tpm0/device/description[3] or /sys/class/tpm/tpm0/tpm_version_major

Data-at-rest encryption with LUKS

There are two methods for unlocking a LUKS volume using a TPM. You can use Clevis or #systemd-cryptenroll.

Using either method, an encrypted volume or volumes may be unlocked using keys stored in a TPM, either automatically at boot or manually at a later time. Using a TPM for this purpose ensures that your drives will not unlock unless certain conditions are met, such as your firmware not having been modified and Secure Boot not having been disabled (see #Accessing PCR registers).

Warning: If you use this method on your root volume, this means that, as long as the previously mentioned certain conditions are met, your computer will unlock automatically at boot without needing to enter an encryption password.

This means that access to data is protected in case only the encrypted disk is stolen, but not in case the whole PC gets stolen.
Be aware that this method makes you more vulnerable to cold boot attacks, because even if your computer has been powered off for a long time (ensuring the memory is completely cleared), an attacker could simply turn it on and wait for the TPM to load the key automatically. This may be a concern for high-value targets.

systemd-cryptenroll

This article or section is a candidate for merging with systemd-cryptenroll#Trusted Platform Module.

Notes: systemd-cryptenroll has a separate article now. (Discuss in Talk:Trusted Platform Module#move systemd-cryptenroll to separate article)

systemd-cryptenroll(1) 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 (see systemd-cryptsetup-generator for advanced configuration) :
- mkinitcpio users : enable the systemd and sd-encrypt hooks.
  - NOTE: Order of the entries in the hooks is important. A nonstandard ordering can make the system unbootable (you will need to rebuild the initrd using arch-chroot to recover). See an example of the correct order here.
- dracut users : enable the tpm2-tss module.

To begin, run the following command to list your installed TPMs and the driver in use:

$ 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):

# 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.

Refer to systemd-cryptenroll(1) and https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/ for common PCR measurements in Linux. Adjust the --tpm2-pcrs=7 default as necessary (parameters are separated by the + symbol).

Warning:

Make sure Secure Boot is active and in user mode when binding to PCR 7, otherwise, unauthorized boot devices could unlock the encrypted volume.
The state of PCR 7 can change if firmware certificates change, which can risk locking the user out. This can be implicitly done by fwupd [4] or explicitly by rotating Secure Boot keys.

The combination of PCRs to bind to depends on the individual case to balance usability and lock-down. For example, you may require UEFI firmware updates without manual intervention to the Secure Boot state, or different boot devices. As another example, Microsoft's Bitlocker prefers PCR 7+11, but may also use other PCR combinations.

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:

# cryptsetup luksDump /dev/sdX

To test that the key works, run the following command while the LUKS volume is closed:

# systemd-cryptsetup attach mapping_name /dev/sdX - tpm2-device=auto

where mapping_name is your chosen name for the volume once opened.

See Dm-crypt/System configuration#crypttab and Dm-crypt/System configuration#Trusted Platform Module and FIDO2 keys in order to unlock the volume at boot time.

Note:

While you may specify the UUID of your LUKS volume in place of the pathname in /etc/crypttab, the systemd-cryptenroll command itself currently only supports pathnames

To remove a key enrolled using this method, run:

# systemd-cryptenroll /dev/sdX --wipe-slot=slot_number

where slot_number is the numeric LUKS slot number in which your TPM key is stored.

Alternatively, run:

# systemd-cryptenroll /dev/sdX --wipe-slot=tpm2

to remove all TPM-associated keys from your LUKS volume.

See systemd-cryptenroll(1) and crypttab(5) for more information and examples.

SSH

For TPM sealed SSH keys, there are two options:

ssh-tpm-agent — ssh-agent compatible agent using TPM backed keys.

https://github.com/Foxboron/ssh-tpm-agent || ssh-tpm-agent-git^AUR

See Store ssh keys inside the TPM: ssh-tpm-agent.

tpm2-pkcs11 — PKCS#11 interface for Trusted Platform Module 2.0 hardware.

https://github.com/tpm2-software/tpm2-pkcs11 || tpm2-pkcs11

See SSH configuration and Using a TPM for SSH authentication (2020-01).

GnuPG

This article or section needs expansion.

Reason: Add instructions for probing the TPM to find out which keys it supports. (Discuss in Talk:Trusted Platform Module)

GnuPG, since version 2.3, supports moving compatible keys into the TPM. See Using a TPM with GnuPG 2.3 for the instructions.

Other good examples of TPM 2.0 usage

Configuring Secure Boot + TPM 2 (2018-06, Debian)
Using the TPM - It's Not Rocket Science (Anymore) - Johannes Holland & Peter Huewe (2020-11, Youtube): examples for OpenSSL with tpm2-tss-engine

Accessing PCR registers

Platform Configuration Registers (PCR) contain hashes that can be read at any time but can only be written via the extend operation, which depends on the previous hash value, thus making a sort of blockchain. They are intended to be used for platform hardware and software integrity checking between boots (e.g. protection against Evil Maid attack). They can be used to unlock encryption keys and proving that the correct OS was booted.

The TCG PC Client Specific Platform Firmware Profile Specification defines the registers in use, and The Linux TPM PCR Registry assigns Linux system components using them.

The registers are:

PCR	Use	Notes
PCR0	Core System Firmware executable code (aka Firmware)	May change if you upgrade your UEFI
PCR1	Core System Firmware data (aka UEFI settings)
PCR2	Extended or pluggable executable code
PCR3	Extended or pluggable firmware data	Set during Boot Device Select UEFI boot phase
PCR4	Boot Manager Code and Boot Attempts	Measures the boot manager and the devices that the firmware tried to boot from
PCR5	Boot Manager Configuration and Data	Can measure configuration of boot loaders; includes the GPT Partition Table
PCR6	Resume from S4 and S5 Power State Events
PCR7	Secure Boot State	Contains the full contents of PK/KEK/db, as well as the specific certificates used to validate each boot application[5]
PCR8¹	Hash of the kernel command line	Supported by grub and systemd-boot
PCR9¹	Hash of the initrd and EFI Load Options	Linux measures the initrd and EFI Load Options, essentially the kernel cmdline options.
PCR10¹	Reserved for Future Use
PCR11¹	Hash of the Unified kernel image	see systemd-stub(7)
PCR12¹	Overridden kernel command line, Credentials	see systemd-stub(7)
PCR13¹	System Extensions	see systemd-stub(7)
PCR14¹	shim's MokList, MokListX, and MokSBState.	[6]
PCR15¹		Unused
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.

Use case defined by the OS and might change between various Linux distros and Windows devices.

On Windows, BitLocker uses PCR8-11 (Legacy) or PCR11-14 (UEFI) for its own purposes. Documentation from tianocore[7].

tpm2-totp facilitates this check with a human observer and dedicated trusted device.

The current PCR values can be listed with systemd-analyze(1):

$ systemd-analyze pcrs

Or, alternatively with tpm2_pcrread(1) from tpm2-tools:

# tpm2_pcrread

Troubleshooting

TPM2 LUKS2 unlocking still asking for password

If you followed the instruction described above for automatically unlocking luks2 devices with enrolled keys in a TPM2 hardware module, but still receive a prompt to input a password during the initramfs boot stage. You may need to early load the kernel module (you can obtain its name with systemd-cryptenroll --tpm2-device=list) that is responsible for handling your specific TPM2 module.

Versions

Usage

Checking support

Data-at-rest encryption with LUKS

systemd-cryptenroll

SSH

GnuPG

Other good examples of TPM 2.0 usage

Accessing PCR registers

Troubleshooting

TPM2 LUKS2 unlocking still asking for password

See also