Lncvrt/grub
1
0 Fork 0
mirror of https://git.savannah.gnu.org/git/grub.git synced 2026-10-21 14:59:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
11,083 Commits 28 Branches 23 Tags
34824806ac6302f91e8cabaa41308eaced25725f
Commit Graph
4 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
Hernan Gatta 5f6a2fd513 util/grub-protect: Add new tool 
To utilize the key protectors framework, there must be a way to protect
full-disk encryption keys in the first place. The grub-protect tool
includes support for the TPM2 key protector but other protectors that
require setup ahead of time can be supported in the future.

For the TPM2 key protector, the intended flow is for a user to have
a LUKS 1 or LUKS 2-protected fully-encrypted disk. The user then creates
a new LUKS key file, say by reading /dev/urandom into a file, and creates
a new LUKS key slot for this key. Then, the user invokes the grub-protect
tool to seal this key file to a set of PCRs using the system's TPM 2.0.
The resulting sealed key file is stored in an unencrypted partition such
as the EFI System Partition (ESP) so that GRUB may read it. The user also
has to ensure the cryptomount command is included in GRUB's boot script
and that it carries the requisite key protector (-P) parameter.

Sample usage:

  $ dd if=/dev/urandom of=luks-key bs=1 count=32
  $ sudo cryptsetup luksAddKey /dev/sdb1 luks-key --pbkdf=pbkdf2 --hash=sha512

To seal the key with TPM 2.0 Key File (recommended):

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

Or, to seal the key with the raw sealed key:

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

Then, in the boot script, for TPM 2.0 Key File:

  tpm2_key_protector_init --tpm2key=(hd0,gpt1)/efi/grub/sealed.tpm
  cryptomount -u <SDB1_UUID> -P tpm2

Or, for the raw sealed key:

  tpm2_key_protector_init --keyfile=(hd0,gpt1)/efi/grub/sealed.key --pcrs=0,2,4,7,9
  cryptomount -u <SDB1_UUID> -P tpm2

The benefit of using TPM 2.0 Key File is that the PCR set is already
written in the key file, so there is no need to specify PCRs when
invoking tpm2_key_protector_init.

Signed-off-by: Hernan Gatta <hegatta@linux.microsoft.com>
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
 2024-11-28 21:50:55 +01:00
Hernan Gatta ad0c52784a cryptodisk: Support key protectors 
Add a new parameter to cryptomount to support the key protectors framework: -P.
The parameter is used to automatically retrieve a key from specified key
protectors. The parameter may be repeated to specify any number of key
protectors. These are tried in order until one provides a usable key for any
given disk.

Signed-off-by: Hernan Gatta <hegatta@linux.microsoft.com>
Signed-off-by: Michael Chang <mchang@suse.com>
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
 2024-11-28 21:50:55 +01:00
Hernan Gatta 48e230c317 key_protector: Add TPM2 Key Protector 
The TPM2 key protector is a module that enables the automatic retrieval
of a fully-encrypted disk's unlocking key from a TPM 2.0.

The theory of operation is such that the module accepts various
arguments, most of which are optional and therefore possess reasonable
defaults. One of these arguments is the keyfile/tpm2key parameter, which
is mandatory. There are two supported key formats:

1. Raw Sealed Key (--keyfile)
   When sealing a key with TPM2_Create, the public portion of the sealed
   key is stored in TPM2B_PUBLIC, and the private portion is in
   TPM2B_PRIVATE. The raw sealed key glues the fully marshalled
   TPM2B_PUBLIC and TPM2B_PRIVATE into one file.

2. TPM 2.0 Key (--tpm2key)
   The following is the ASN.1 definition of TPM 2.0 Key File:

   TPMPolicy ::= SEQUENCE {
     CommandCode   [0] EXPLICIT INTEGER
     CommandPolicy [1] EXPLICIT OCTET STRING
   }

   TPMAuthPolicy ::= SEQUENCE {
     Name    [0] EXPLICIT UTF8STRING OPTIONAL
     Policy  [1] EXPLICIT SEQUENCE OF TPMPolicy
   }

   TPMKey ::= SEQUENCE {
     type        OBJECT IDENTIFIER
     emptyAuth   [0] EXPLICIT BOOLEAN OPTIONAL
     policy      [1] EXPLICIT SEQUENCE OF TPMPolicy OPTIONAL
     secret      [2] EXPLICIT OCTET STRING OPTIONAL
     authPolicy  [3] EXPLICIT SEQUENCE OF TPMAuthPolicy OPTIONAL
     description [4] EXPLICIT UTF8String OPTIONAL,
     rsaParent   [5] EXPLICIT BOOLEAN OPTIONAL,
     parent      INTEGER
     pubkey      OCTET STRING
     privkey     OCTET STRING
   }

  The TPM2 key protector only expects a "sealed" key in DER encoding,
  so "type" is always 2.23.133.10.1.5, "emptyAuth" is "TRUE", and
  "secret" is empty. "policy" and "authPolicy" are the possible policy
  command sequences to construct the policy digest to unseal the key.
  Similar to the raw sealed key, the public portion (TPM2B_PUBLIC) of
  the sealed key is stored in "pubkey", and the private portion
  (TPM2B_PRIVATE) is in "privkey".

  For more details: https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html

This sealed key file is created via the grub-protect tool. The tool
utilizes the TPM's sealing functionality to seal (i.e., encrypt) an
unlocking key using a Storage Root Key (SRK) to the values of various
Platform Configuration Registers (PCRs). These PCRs reflect the state
of the system as it boots. If the values are as expected, the system
may be considered trustworthy, at which point the TPM allows for a
caller to utilize the private component of the SRK to unseal (i.e.,
decrypt) the sealed key file. The caller, in this case, is this key
protector.

The TPM2 key protector registers two commands:

  - tpm2_key_protector_init: Initializes the state of the TPM2 key
                             protector for later usage, clearing any
                             previous state, too, if any.

  - tpm2_key_protector_clear: Clears any state set by tpm2_key_protector_init.

The way this is expected to be used requires the user to, either
interactively or, normally, via a boot script, initialize/configure
the key protector and then specify that it be used by the "cryptomount"
command (modifications to this command are in a different patch).

For instance, to unseal the raw sealed key file:

  tpm2_key_protector_init --keyfile=(hd0,gpt1)/efi/grub/sealed-1.key
  cryptomount -u <PART1_UUID> -P tpm2

  tpm2_key_protector_init --keyfile=(hd0,gpt1)/efi/grub/sealed-2.key --pcrs=7,11
  cryptomount -u <PART2_UUID> -P tpm2

Or, to unseal the TPM 2.0 Key file:

  tpm2_key_protector_init --tpm2key=(hd0,gpt1)/efi/grub/sealed-1.tpm
  cryptomount -u <PART1_UUID> -P tpm2

  tpm2_key_protector_init --tpm2key=(hd0,gpt1)/efi/grub/sealed-2.tpm --pcrs=7,11
  cryptomount -u <PART2_UUID> -P tpm2

If a user does not initialize the key protector and attempts to use it
anyway, the protector returns an error.

Before unsealing the key, the TPM2 key protector follows the "TPMPolicy"
sequences to enforce the TPM policy commands to construct a valid policy
digest to unseal the key.

For the TPM 2.0 Key files, "authPolicy" may contain multiple "TPMPolicy"
sequences, the TPM2 key protector iterates "authPolicy" to find a valid
sequence to unseal key. If "authPolicy" is empty or all sequences in
"authPolicy" fail, the protector tries the one from "policy". In case
"policy" is also empty, the protector creates a "TPMPolicy" sequence
based on the given PCR selection.

For the raw sealed key, the TPM2 key protector treats the key file as a
TPM 2.0 Key file without "authPolicy" and "policy", so the "TPMPolicy"
sequence is always based on the PCR selection from the command
parameters.

This commit only supports one policy command: TPM2_PolicyPCR. The
command set will be extended to support advanced features, such as
authorized policy, in the later commits.

Cc: James Bottomley <jejb@linux.ibm.com>
Signed-off-by: Hernan Gatta <hegatta@linux.microsoft.com>
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
 2024-11-28 21:50:55 +01:00
Hernan Gatta 5d260302da key_protector: Add key protectors framework 
A key protector encapsulates functionality to retrieve an unlocking key
for a fully-encrypted disk from a specific source. A key protector
module registers itself with the key protectors framework when it is
loaded and unregisters when unloaded. Additionally, a key protector may
accept parameters that describe how it should operate.

The key protectors framework, besides offering registration and
unregistration functions, also offers a one-stop routine for finding and
invoking a key protector by name. If a key protector with the specified
name exists and if an unlocking key is successfully retrieved by it, the
function returns to the caller the retrieved key and its length.

Cc: Vladimir Serbinenko <phcoder@gmail.com>
Signed-off-by: Hernan Gatta <hegatta@linux.microsoft.com>
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
 2024-11-28 21:50:55 +01:00