Add Multi-Factor Authentication (MFA) key protector
cover Add Multi-Factor Authentication (MFA) key protector
This patch series introduces the Multi-Factor Authentication (MFA) key protector module to GRUB.
Currently, GRUB supports unlocking encrypted partitions (e.g., LUKS) via single-factor methods such as a passphrase, a key file, or the key unsealed by TPM2. To enhance security, this series implements a split-key architecture where the final disk encryption key is derived by combining partial keys from two distinct sources. This ensures that compromising a single factor (e.g., stealing a USB drive with a key file) is insufficient to unlock the disk.
The mfa module acts as a meta-protector that orchestrates the retrieval of key segments from two underlying key protectors. The final key is constructed by concatenating the output of Factor 1 and Factor 2.
To support this, the series also introduces two basic key protectors:
- File key protector: Reads a key (or partial key) from a file on disk.
- Password key protector: Prompts the user for a passphrase (or uses a static string).
A typical workflow involves combining a key file stored on an external drive with a user-supplied passphrase:
file_key_protector_init -k (hd0,gpt1)/efi/grub/keyfile.bin mfa_key_protector_init -1 file -2 password cryptomount -u <UUID> -P mfa
Alternatively, the key file can be sealed with the TPM.
tpm2_key_protector_init -T (hd0,gpt1)/efi/grub/sealed.tpm mfa_key_protector_init -1 tpm2 -2 password cryptomount -u <UUID> -P mfa
NOTE: Password key protector is initialized implicitly so
'pw_key_protector_init' is usually omitted.
Gary Lin (3):
key_protector: Add MFA key protector
docs: Add documentation for MFA key protector
tests: Add mfa_key_protector_test
Makefile.util.def | 6 + docs/grub.texi | 188 +++++++++++ grub-core/Makefile.core.def | 5 + grub-core/commands/mfa.c | 576 ++++++++++++++++++++++++++++++++ tests/mfa_key_protector_test.in | 123 +++++++ 5 files changed, 898 insertions(+) create mode 100644 grub-core/commands/mfa.c create mode 100644 tests/mfa_key_protector_test.in
Signature · 7 lines
2.51.0 _______________________________________________ Grub-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/grub-devel
PATCH 1/3 key_protector: Add MFA key protector
This patch introduces the MFA key protector to provide multi-factor authentication for encrypted partitions.
The MFA protector does not store the disk key itself; instead, it relies on a split-key architecture where the disk key is divided into two parts stored in different underlying key protectors. When unlocking the partition, the module retrieves partial keys from specified protectors and derives the final disk key.
To specify the underlying key protectors, use 'mfa_key_protector_init' with options --protector1 (or -1) and --protector2 (or -2). The sequence is crucial: the final key is reconstructed by combining intermediate keys in the exact order specified.
Additionally, the 'mfa' module provides two basic key protectors:
* password: Prompts the user for input.
* file: Retrieves the key from a specified file path.
Example: (file + password):
- Create a combined disk key:
$ dd if=/dev/random of=keyfile.bin bs=1 count=64 $ echo -n "TOP SECRET" > user-pass.txt $ cat keyfile.bin user-pass.txt > luks-key.bin
- Enroll the key into LUKS:
# cryptsetup luksAddKey --new-keyfile luks-key.bin /dev/disk/by-uuid/...
- GRUB commands:
file_key_protector_init -k (hd1,gpt1)/keyfile/keyfile.bin mfa_key_protector_init -1 file -2 password cryptomount -u <UUID> -P mfa
The result:
Retrieving MFA key 1 from 'file' key protector Retrieving MFA key 2 from 'password' key protector Enter MFA passphrase:
Attempting to decrypt master key...
Slot "1" opened
The MFA key protector fetches the first half of the key from the key file and requests the passphrase as the second half. With the full disk key, GRUB unlocks the partition successfully.
--- grub-core/Makefile.core.def | 5 + grub-core/commands/mfa.c | 576 ++++++++++++++++++++++++++++++++++++ 2 files changed, 581 insertions(+) create mode 100644 grub-core/commands/mfa.c
grub-core/Makefile.core.def +5 -0
@@ -1072,6 +1072,11 @@ module = { common = commands/memrw.c; }; +module = { + name = mfa; + common = commands/mfa.c; +}; + module = { name = minicmd; common = commands/minicmd.c;
grub-core/commands/mfa.c new file +576 -0
576 lines not on this page · raw message
Signature · 7 lines
2.51.0 _______________________________________________ Grub-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/grub-devel
PATCH 2/3 docs: Add documentation for MFA key protector
In reply to Gary Lin via Grub-develThis patch adds the documentation for the Multi-Factor Authentication (MFA) key protector and explains the split-key architecture.
Additionally, the following new commands are documented in the command section:
* mfa_key_protector_init / mfa_key_protector_clear
* file_key_protector_init / file_key_protector_clear
* pw_key_protector_init / pw_key_protector_clear
--- docs/grub.texi | 188 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+)
docs/grub.texi +188 -0
@@ -6688,6 +6688,8 @@ you forget a command, you can run the command @command{help} * false:: Do nothing, unsuccessfully * fdtdump:: Retrieve device tree information * file:: Test the provided file against a type +* file_key_protector_init:: Initialize the file key protector +* file_key_protector_clear:: Clear the file key protector * fwsetup:: Reboot into the firmware setup menu * gdbinfo:: Provide info for debugging with GDB * gettext:: Translate a string
@@ -6710,6 +6712,8 @@ you forget a command, you can run the command @command{help} * lsmem:: List free and allocated memory blocks * lsmemregions:: List memory regions * md5sum:: Compute or check MD5 hash +* mfa_key_protector_init:: Initialize the MFA key protector +* mfa_key_protector_clear:: Clear the MFA key protector * module:: Load module for multiboot kernel * multiboot:: Load multiboot compliant kernel * nativedisk:: Switch to native disk drivers
@@ -6721,6 +6725,8 @@ you forget a command, you can run the command @command{help} * plainmount:: Open device encrypted in plain mode * play:: Play a tune * probe:: Retrieve device info +* pw_key_protector_init:: Initialize the password key protector +* pw_key_protector_clear:: Clear the password key protector * rdmsr:: Read values from model-specific registers * read:: Read user input * reboot:: Reboot your computer
@@ -7560,6 +7566,40 @@ hibernated image @end deffn +@node file_key_protector_init +@subsection file_key_protector_init + +@deffn Command file_key_protector_init [ @option{--key-file} | @option{-k} @var{file_path}][ @option{--keyfile-offset} | @option{-O} @var{offset}][ @option{--keyfile-size} | @option{-S} @var{size}] +Initialize the file key protector. + +This command configures the file key protector, which allows GRUB to read a +cryptographic key (or a part of a key) from a file on the disk. This is commonly +used in conjunction with the MFA key protector @xref{MFA key protector} or for +automatic disk unlocking via a key file. + +The @option{-k} option specifies the path to the key file (@var{file_path}). +The @option{-O} option skips the first @var{offset} bytes of the file. The key data is +read starting from this offset. The default is 0. +The @option{-S} option reads exactly @var{size} bytes of data from the file to +use as the key. If this option is not specified, the entire file is typically used. + +Example: +@example +file_key_protector_init -k (hd0,gpt1)/efi/grub/keyfile.bin -O 512 -S 64 +@end example + +In this example, the file key protector reads 64 bytes from @file{keyfile.bin}, +starting at offset 512. +@end deffn + +@node file_key_protector_clear +@subsection file_key_protector_clear + +@deffn Command file_key_protector_clear +Clear the file key protector if previously initialized. +@end deffn + + @node fwsetup @subsection fwsetup
@@ -7863,6 +7903,43 @@ Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum} (@pxref{hashsum}) for full description. @end deffn +@node mfa_key_protector_init +@subsection mfa_key_protector_init + +@deffn Command mfa_key_protector_init [ @option{--protector1} | @option{-1} @var{protector1}] [@option{--protector2} | @option{-2} @var{protector2}] +Initialize the Multi-Factor Authentication (MFA) key protector. + +The MFA key protector provides two-factor authentication for unlocking encrypted +partitions (e.g., LUKS). It does not store the disk key itself but relies on a +split-key architecture. The final disk key is derived by combining partial keys +retrieved from two other specified key protectors. + +The options @option{--protector1} (or @option{-1}) and @option{--protector2} +(or @option{-2}) specify the names of the two underlying key protectors to use +(for example, @samp{file} and @samp{password}). + +The order of the protectors is crucial. The MFA key protector reconstructs the +final key by concatenating the key from the first protector (@var{protector1}) +with the key from the second protector (@var{protector2}). + +Example: +@example +file_key_protector_init -k (hd0,gpt1)/efi/grub/keyfile.bin +mfa_key_protector_init -1 file -2 password +cryptomount -u <UUID> -P mfa +@end example + +In this example, the first part of the key is read from a file, and the second +part is requested from the user via a password prompt. +@end deffn + +@node mfa_key_protector_clear +@subsection mfa_key_protector_clear + +@deffn Command mfa_key_protector_clear +Clear the MFA key protector if previously initialized. +@end deffn + @node module @subsection module
@@ -8086,6 +8163,28 @@ The option @option{--part-uuid} is currently only implemented for MSDOS and GPT @end deffn +@node pw_key_protector_init +@subsection pw_key_protector_init + +@deffn Command pw_key_protector_init [ @option{--password} | @option{-p} @var{password}] +Initialize the password key protector. This allows providing a static +password to the @command{cryptomount} command, enabling non-interactive +unlocking. The option @option{--password} (or @option{-p}) sets the +password in clear text. + +NOTE: In general, there is no need to invoke this command. By default, the +password key protector is initialized implicitly and prompts the user for +input interactively. +@end deffn + +@node pw_key_protector_clear +@subsection pw_key_protector_clear + +@deffn Command pw_key_protector_clear +Clear the password key protector if previously initialized. +@end deffn + + @node rdmsr @subsection rdmsr
@@ -9218,6 +9317,7 @@ environment variables and commands are listed in the same order. * Measured Boot:: Measuring boot components * Lockdown:: Lockdown when booting on a secure setup * TPM2 key protector:: Managing disk key with TPM2 key protector +* MFA key protector:: Managing disk key with MFA key protector * Signing certificate and hash files:: Certificate and hash file signing * Signing GRUB itself:: Ensuring the integrity of the GRUB core image * Hardening:: Configuration and customization to maximize security
@@ -10030,6 +10130,94 @@ which increases the risk of password leakage during the process. Moreover, the superuser list must be well maintained, and the password used cannot be synchronized with LUKS key rotation. +@node MFA key protector +@section Multi-Factor Authentication (MFA) key protector + +The MFA key protector enhances the security of encrypted partitions (such as LUKS) +by enforcing a split-key architecture. Unlike standard key protectors that store +or retrieve a single static key, the MFA protector derives the disk unlocking key +by combining partial keys from two distinct sources. + +This approach ensures that an attacker cannot unlock the encrypted disk if they +compromise only one of the factors (for example, stealing a USB drive with a key +file but lacking the passphrase). + +The MFA key protector acts as a logic layer on top of other existing key +protectors. It requires two underlying key protectors, referred to as +@var{Protector 1} and @var{Protector 2}. + +@enumerate +@item +@var{Protector 1} retrieves the first segment of the key (e.g., from a file). +@item +@var{Protector 2} retrieves the second segment of the key (e.g., from user input). +@item +The MFA key protector concatenates these segments to reconstruct the final disk key. +@end enumerate + +For a complete reference on the command syntax and options, please see +@ref{mfa_key_protector_init}. + +@subsection Example Workflow + +Here are the sample commands to create a LUKS key (@file{luks.key}) by +concatenating a 64-byte random file (@file{keyfile.bin}) and a user +passphrase and enroll the key into the target partition (sda2). + +@example +# Generate the random key file +@kbd{dd if=/dev/random of=keyfile.bin bs=1 count=64} + +# Combine the key file and the user password +@kbd{cp keyfile.bin luks.key} +@kbd{read -p "password :" -s password && printf "%s" "$password" >> luks.key } + +# Enroll the combined key into LUKS +@kbd{cryptsetup luksAddKey /dev/sda2 luks.key} +@end example + +To unlock the partition, the underlying key protectors must be initialized +first. The @command{file_key_protector_init} command configures the file +protector by specifying the path to the key file (@file{keyfile.bin}). Note +that the password key protector is initialized implicitly and requires no +specific setup command. + +Once configured, use @command{mfa_key_protector_init} to define the order of +the factors. Finally, when @command{cryptomount} is invoked with @option{-P mfa}, +GRUB retrieves the key file (Factor 1) and prompts the user for the +passphrase (Factor 2). + +@example +grub> @kbd{file_key_protector_init -k (hd0,gpt1)/efi/grub/keyfile.bin} +grub> @kbd{mfa_key_protector_init -1 file -2 password} +grub> @kbd{cryptomount -u <UUID> -P mfa} +@end example + +Alternatively, the key file (@file{keyfile.bin}) can be sealed with the TPM +to enhance security. + +@example +@group +@kbd{grub-protect --action=add \ + --protector=tpm2 \ + --tpm2-pcrs=0,2,4,7 \ + --tpm2key \ + --tpm2-keyfile=keyfile.bin \ + --tpm2-outfile=/boot/efi/efi/grub/sealed.tpm} +@end group +@end example + +In this scenario, the MFA key protector is configured to retrieve the first +key segment from the tpm2 key protector and the second from the password key +protector. + +@example +grub> @kbd{tpm2_key_protector_init -T (hd0,gpt1)/efi/grub/sealed.tpm} +grub> @kbd{mfa_key_protector_init -1 tpm2 -2 password} +grub> @kbd{cryptomount -u <UUID> -P mfa} +@end example + + @node Signing certificate and hash files @section Signing certificate and hash files X.509 certificate (public key) files and hash files (binary/certificate hash files)
Signature · 7 lines
2.51.0 _______________________________________________ Grub-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/grub-devel
PATCH 3/3 tests: Add mfa_key_protector_test
In reply to Gary Lin via Grub-develAdd a new test script, tests/mfa_key_protector_test.in, to verify the functionality of the Multi-Factor Authentication (MFA) key protector.
This test performs the following steps:
1. Creates a LUKS2 encrypted partition using a combined key derived from a random key file (Factor 1) and a passphrase (Factor 2).
2. Configures GRUB with the mfa module, initializing the file key protector for Factor 1 and the password key protector for Factor 2.
3. Verifies that "cryptomount -a --protector mfa" successfully combines the factors to unlock the volume.
--- Makefile.util.def | 6 ++ tests/mfa_key_protector_test.in | 123 ++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 tests/mfa_key_protector_test.in
Makefile.util.def +6 -0
@@ -1305,6 +1305,12 @@ script = { common = tests/tpm2_key_protector_test.in; }; +script = { + testcase = native; + name = mfa_key_protector_test; + common = tests/mfa_key_protector_test.in; +}; + program = { testcase = native; name = example_unit_test;
tests/mfa_key_protector_test.in new file +123 -0
123 lines not on this page · raw message
Signature · 7 lines
2.51.0 _______________________________________________ Grub-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/grub-devel