Invoking grub-protect (GNU GRUB Manual 2.14)

24.8 Invoking grub-protect

The program grub-protect protects a disk encryption key with a specified key protector.

--help: Print a summary of the command-line options and exit.
--version: Print the version number of GRUB and exit.
-a add|remove
--action=add|remove: Add or remove a key protector to or from a key.
-p protector
--protector=protector: Set the key protector. Currently, ‘tpm2’ is the only supported key protector.
--tpm2-asymmetric=type: Choose the the type of SRK. The valid options are ‘RSA’ (‘RSA2048’) and ‘ECC’ (‘ECC_NIST_P256’).(default: ‘ECC’)
--tpm2-bank=alg: Choose bank of PCRs used to authorize key release: ‘SHA1’, ‘SHA256’, ‘SHA384’, or ‘SHA512’. (default: ‘SHA256’)
--tpm2-device=device: Set the path to the TPM2 device. (default: ‘/dev/tpm0’)
--tpm2-evict: Evict a previously persisted SRK from the TPM, if any.
--tpm2-keyfile=file: Set the path to a file that contains the cleartext key to protect.
--tpm2-outfile=file: Set the path to the file that will contain the key after sealing (must be accessible to GRUB during boot).
--tpm2-pcrs=pcrs: Set a comma-separated list of PCRs used to authorize key release e.g., ‘7,11’. Please be aware that PCR 0~7 are used by the firmware and the measurement result may change after a firmware update (for baremetal systems) or a package (OVMF/SLOF) update in the VM host. This may lead to the failure of key unsealing. (default: ‘7’)
--tpm2-srk=handle: Set the SRK handle, e.g. ‘0x81000000’, if the SRK is to be made persistent.
--tpm2-nvindex=handle: Set the handle, e.g. ‘0x81000000’ or ‘0x1000000’, for NV index mode.
--tpm2key: Use TPM 2.0 Key File format.

’Add’ action
’Remove’ action

24.8.1 ’Add’ action

Before sealing the key, please check the TPM PCR usage (see TPM PCR usage) to choose a proper set of PCRs.

Assume that there is a key file, luks.key, to be sealed with PCR 0, 2, 4, and 7, and here is the grub-protect command to create the sealed key file:

# grub-protect --action=add \
               --protector=tpm2 \
               --tpm2-pcrs=0,2,4,7 \
               --tpm2key \
               --tpm2-keyfile=luks.key \
               --tpm2-outfile=/boot/efi/efi/grub/sealed.tpm

Then, GRUB can unlock the target partition with the following commands:

grub> tpm2_key_protector_init -T (hd0,gpt1)/efi/grub/sealed.tpm
grub> cryptomount -u <UUID> -P tpm2

Besides writing the PCR-sealed key into a file, grub-protect can write the sealed key into TPM non-volatile memory. Here is the grub-protect command to write the sealed key into the NV index handle ‘0x1000000’.

# grub-protect --action=add \
               --protector=tpm2 \
               --tpm2-pcrs=0,2,4,7 \
               --tpm2key \
               --tpm2-keyfile=luks.key \
               --tpm2-nvindex=0x1000000

Later, GRUB can fetch the key from ‘0x1000000’.

grub> tpm2_key_protector_init --mode=nv --nvindex=0x1000000
grub> cryptomount -u <UUID> -P tpm2

In most of cases, the user only needs to create the key with the ‘add’ action. If auto-unlocking is unwanted, just remove the file and the tpm2_key_protector_init command and invoke the cryptomount command without -P tpm2.

24.8.2 ’Remove’ action

The ‘remove’ action is used to remove the handles for NV index mode and the persistent SRK.

Handles for NV index mode
Persistent SRK

24.8.2.1 Handles for NV index mode

There are two types of TPM handles supported by NV index mode: persistent handles and NV index handles, and tpm2_getcap can be used to check the existing handles.

To display the list of existing persistent handles:

# tpm2_getcap handles-persistent
- 0x81000000

Similarly, to display the list of existing NV index handles:

# tpm2_getcap handles-nv-index
- 0x1000000

If the sealed key at an NV index handle is not needed anymore, the user can remove the handle with --tpm2-nvindex and --tpm2-evict. For example, this command removes the data from NV index ‘0x1000000’:

# grub-protect --action=remove \
               --protector=tpm2 \
               --tpm2-evict \
               --tpm2-nvindex 0x1000000 \

24.8.2.2 Persistent SRK

There are two supported SRKs in grub-protect: ‘RSA’ and ‘ECC’. Due to slower key generation, some users of the ‘RSA’ SRK may prefer making it persistent so that the TPM can skip the SRK generation when GRUB tries to unseal the key.

The available persistent handles can be checked with tpm2_getcap.

# tpm2_getcap properties-variable
...
TPM2_PT_HR_PERSISTENT: 0x0
TPM2_PT_HR_PERSISTENT_AVAIL: 0x41
...

In this system, there is no persistent handle. A TPM handle is an unsigned 32-bit integer, and the persistent handles starts with ‘0x81’. Here we choose the well-known persistent handle: ‘0x81000000’.

# grub-protect --action=add \
               --protector=tpm2 \
               --tpm2-pcrs=0,2,4,7 \
               --tpm2-asymmetric=RSA \
               --tpm2-srk=0x81000000 \
               --tpm2key \
               --tpm2-keyfile=luks.key \
               --tpm2-outfile=/boot/efi/efi/grub/sealed.tpm

The additional --tpm2-asymmetric=RSA and --tpm2-srk=0x81000000 options are used to make the key sealed with the RSA SRK and store the SRK in ‘0x81000000’.

For the tpm2_key_protector_init command, the additional -s 0x81000000 informs the TPM2 key protector to fetch the SRK from ‘0x81000000’.

grub> tpm2_key_protector_init -s 0x81000000 -T (hd0,gpt1)/efi/grub/sealed.tpm
grub> cryptomount -u <UUID> -P tpm2

After making the SRK handle persistent, we can check the status of the persistent handles with tpm2_getcap.

# tpm2_getcap properties-variable
...
TPM2_PT_HR_PERSISTENT: 0x1
TPM2_PT_HR_PERSISTENT_AVAIL: 0x40
...
# tpm2_getcap handles-persistent
- 0x81000000

The sealed key can be removed once the user does not want to use the TPM2 key protector anymore. Here is the command to remove the persistent SRK handle (‘0x81000000’) with --tpm2-srk and --tpm2-evict.

# grub-protect --action=remove \
               --protector=tpm2 \
               --tpm2-srk 0x81000000 \
               --tpm2-evict