Re: [PATCH v21 33/33] docs: Document TPM2 key protector

[Stefan Berger]

On 11/4/24 2:32 AM, Gary Lin via Grub-devel wrote:
> Update the user manual to address TPM2 key protector including the two
> related commands, tpm2_key_protector_init and tpm2_key_protector_clear,
> and the user-space utility: grub-protect.
>
> Signed-off-by: Gary Lin <glin@suse.com>
> ---

> +@example
> +# @kbd{dd if=/dev/urandom of=luks.key bs=1 count=128}
> +# @kbd{cryptsetup luksAddKey /dev/sda2 luks.key --pbkdf=pbkdf2 --hash=sha512}
> +@end example
> +
> +@subsection SRK mode
> +
> +To unlock the partition with SRK mode, assume that the sealed key is in
> +@file{(hd0,gpt1)/efi/grub/sealed.tpm}, the following GRUB commands
> +unseal the disk key with SRK mode and supply it to @command{cryptomount}.
> +
> +@example
> +grub> @kbd{tpm2_key_protector_init --keyfile=(hd0,gpt1)/efi/grub/sealed.tpm}
> +grub> @kbd{cryptomount -u <UUID> -P tpm2}
> +@end example

You may also want to give an example with --tpm2key= because it will go 
along with the grub-protect --tpm2key option that you show. And you may 
want to point that out to the user one when showing grub-protect with 
--tpm2key, because otherwise the key created by grub-protect --tpm2key 
cannot be read since the key formats (there are 2 key formats) do not 
match and you'd need some sort of trouble shooting section...

For my tests on ppc64 I have been using this here on Linux:

sudo grub-protect \
        --action=add \
        --protector=tpm2 \
        --tpm2-pcrs=1,2,3 \
        --tpm2key \
        --tpm2-keyfile=luks.key \
        --tpm2-outfile=/boot/grub/sealed.tpm \
        --tpm2-asymmetric=RSA2048

and this here in grub.cfg:

        insmod key_protector
        insmod luks2

        tpm2_key_protector_init 
--tpm2key=(ieee1275/disk,gpt2)/grub/sealed.tpm
        cryptomount -u 3fe533ee-d1cc-464d-81dc-2818e7939fc9 -P tpm2


this here on RHEL on pSeries partition:

	tpm2_key_protector_init 
--tpm2key=(ieee1275//vdevice/v-scsi@3000006b/disk@8100000000000000,msdos2)/grub2/sealed.tpm

> +
> +There are two programs to create the sealed key for SRK mode: 
> @command{grub-protect}
> +and @command{pcr-oracle} (@url{https://github.com/okirch/pcr-oracle}).
> +
> +The following sample command uses @command{grub-protect} to seal the random
> +key, @file{luks.key}, with PCR 0, 2, 4 and 7 in TPM 2.0 Key File format.
> +
> +@example
> +@group
> +# @kbd{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}
> +@end group
> +@end example
> +