Next: tpm2_key_protector_clear, Previous: test, Up: Command-line commands [Contents][Index]
Initialize the TPM2 key protector to unseal the key for the cryptomount
(see cryptomount) command. There are two supported modes,
SRK(srk) and NV index(nv), to be specified by the option
-m. The default mode is SRK. The main difference between SRK mode
and NV index mode is the storage of the sealed key. For SRK mode, the sealed
key is stored in a file while NV index mode stores the sealed key in the
non-volatile memory inside TPM with a given NV index.
The -p and -b options are used to supply the PCR list and bank that the key is sealed with. The PCR list is a comma-separated list, e.g., ’0,2,4,7,9’, to represent the involved PCRs, and the default is ’7’. The PCR bank is chosen by selecting a hash algorithm. The current supported PCR banks are SHA1, SHA256, SHA384, and SHA512, and the default is SHA256.
The -c option is introduced to enable the "capping" of a specified list of PCRs. This feature addresses scenarios where a user wants to ensure a sealed key cannot be unsealed again after its initial use. When the -c option is employed, and the key is successfully unsealed, the TPM2 key protector automatically extends the selected PCRs with an EV_SEPARATOR event. This action cryptographically alters the PCR values, thereby preventing the associated key from being unsealed in any subsequent attempts until those specific PCRs are reset to their original state, which typically occurs during a system reboot. In general, it is sufficient to extend one associated PCR to cap the key.
It’s noteworthy that a key sealed against PCR 8 naturally incorporates a "capping" behavior, even without explicitly using a -c option. This is because GRUB measures all commands into PCR 8, including those from configuration files. As a result, the value of PCR 8 changes with virtually every command execution during the boot process. Consequently, a key sealed against PCR 8 can only be unsealed once in a given boot session, as any subsequent GRUB command will alter PCR 8, invalidating the unsealing policy and effectively "capping" the key.
Some options are only available for the specific mode. The SRK-specific options are -T, -k, -a, and -s. On the other hand, the NV index-specific option is -n.
The key file for SRK mode can be supplied with either -T or -k. Those two options were used to distinguish the file formats but are same now. There are two supported file formats: raw format and TPM 2.0 Key File format. When using the key file in the raw format, the -p and -b options are necessary for the non-default PCR list or bank. On the other hand, when using the key file in TPM 2.0 Key File format, the the parameters for the TPM commands are written in the file, and there is no need to set the PCR list(-p) and bank(-b). In general, TPM 2.0 Key File format is preferred due to the simplified GRUB command options and the authorized policy support
Besides the key file, there are two options, -a and -s, to
tweak the TPM Storage Root Key (SRK). The SRK can be either created at
runtime or stored in the non-volatile memory. When creating SRK at runtime,
GRUB provides the SRK template to the TPM to create the key. There are two SRK
templates for the -a option, ECC and RSA, and the default is ECC.
If the SRK is stored in a specific handle, e.g. 0x81000001, the
-s option can be used to set the handle to notify GRUB to load
the SRK from the given handle.
The only NV index-specific option is the -n option which is used to set the NV index containing the sealed key. Then GRUB can load the sealed key and unseal it with the given PCR list and bank.
Next: tpm2_key_protector_clear, Previous: test, Up: Command-line commands [Contents][Index]