Before adding information about how GRUB is signed with an appended
signature scheme, it's worth adding some information about how it
can currently be signed for UEFI.
Signed-off-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Read secure boot mode from 'ibm,secure-boot' property and if the secure boot
mode is set to 2 (enforce), enter lockdown. Else it is considered as disabled.
There are three secure boot modes. They are
0 - disabled
No signature verification is performed. This is the default.
1 - audit
Signature verification is performed and if signature verification fails,
display the errors and allow the boot to continue.
2 - enforce
Lockdown the GRUB. Signature verification is performed and if signature
verification fails, display the errors and stop the boot.
Now, only support disabled and enforce.
Signed-off-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Prior to the addition of the X.509 public key support for appended signature,
current PGP signature relied on the GPG public key. Changing the enum name
from "OBJ_TYPE_PUBKEY" to "OBJ_TYPE_GPG_PUBKEY" to differentiate between x509
certificate based appended signature and GPG certificate based PGP signature.
Signed-off-by: Alastair D'Silva <alastair@d-silva.org>
Signed-off-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Correct some outdated links to various websites and change
http to https in a few places.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Update the Future section of the GRUB manual to reflect
current work on the 2.x series.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add documentation for new libgcrypt modules imported into GRUB.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Update chapter name from "Outline" to "Platform-specific operations" to
improve readability. Also slightly improve some wording in this section.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
A Unified Kernel Image (UKI) is a single UEFI PE file that combines
a UEFI boot stub, a Linux kernel image, an initrd, and further resources.
The uki command will locate where the UKI file is and create a GRUB menu
entry to load it.
The Unified Kernel Image Specification: https://uapi-group.org/specifications/specs/unified_kernel_image/
Signed-off-by: Alec Brown <alec.r.brown@oracle.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The BootLoaderSpec (BLS) defines a scheme where different bootloaders can
share a format for boot items and a configuration directory that accepts
these common configurations as drop-in files.
The BLS Specification: https://uapi-group.org/specifications/specs/boot_loader_specification/
Signed-off-by: Peter Jones <pjones@redhat.com>
Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Will Thompson <wjt@endlessm.com>
Signed-off-by: Alec Brown <alec.r.brown@oracle.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Xen traditionally allows customizing guest behavior by passing arguments
to the VM kernel via the kernel command line. This is no longer possible
when using GRUB with Xen, as the kernel command line is decided by the
GRUB configuration file within the guest, not data passed to the guest
by Xen.
To work around this limitation, enable GRUB to parse a command line
passed to it by Xen, and expose data from the command line to the GRUB
configuration as environment variables. These variables can be used in
the GRUB configuration for any desired purpose, such as extending the
kernel command line passed to the guest. The command line format is
inspired by the Linux kernel's command line format.
To reduce the risk of misuse, abuse, or accidents in production, the
command line will only be parsed if it consists entirely of 7-bit ASCII
characters, only alphabetical characters and underscores are permitted
in variable names, and all variable names must start with the string
"xen_grub_env_". This also allows room for expanding the command line
arguments accepted by GRUB in the future, should other arguments end up
becoming desirable in the future.
Signed-off-by: Aaron Rainbolt <arraybolt3@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The option can be used to suppress output if we only want to test the
return value of the command.
Also, mention this option in the documentation.
Signed-off-by: Michael Chang <mchang@suse.com>
Signed-off-by: Maxim Suhanov <dfirblog@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This commit adds the grub_cryptodisk_erasesecrets() function to wipe
master keys from all cryptodisks. This function is EFI-only.
Since there is no easy way to "force unmount" a given encrypted disk,
this function renders all mounted cryptodisks unusable. An attempt to
read them will return garbage.
This is why this function must be used in "no way back" conditions.
Currently, it is used when unloading the cryptodisk module and when
performing the "exit" command (it is often used to switch to the next
EFI application). This function is not called when performing the
"chainloader" command, because the callee may return to GRUB. For this
reason, users are encouraged to use "exit" instead of "chainloader" to
execute third-party boot applications.
This function does not guarantee that all secrets are wiped from RAM.
Console output, chunks from disk read requests and other may remain.
This function does not clear the IV prefix and rekey key for geli disks.
Also, this commit adds the relevant documentation improvements.
Signed-off-by: Maxim Suhanov <dfirblog@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Document the --cryptodisk-only argument. Also, document the
"cryptocheck" command invoked when that argument is processed.
Signed-off-by: Maxim Suhanov <dfirblog@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add the long options of tpm2_key_protect_init along with the short options.
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This commit updates the NV index mode section and the grub-protect
section to reflect the recent changes in TPM2 key protector and
grub-protect.
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Extract the logic to handle the file buffer from the SRK recover
function to prepare to load the sealed key from the NV index handle,
so the NV index mode can share the same code path in the later patch.
The SRK recover function now only reads the file and sends the file
buffer to the new function.
Besides this, to avoid introducing more options for the NV index mode,
the file format is detected automatically before unmarshaling the data,
so there is no need to use the command option to specify the file format
anymore. In other words, "-T" and "-k" are the same now.
Also update grub.text to address the change.
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The user may need to inspect the TPM 2.0 PCR values with the GRUB shell,
so the new tpm2_dump_pcr command is added to print all PCRs of the
specified bank.
Also update the document for the new command.
Signed-off-by: Gary Lin <glin@suse.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Update documentation to capture that all memrw commands, the minicmd
dump command, and raw memory dumping via hexdump are restricted when
lockdown is enabled. This aligns to recent GRUB code updates.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Document which filesystems are not allowed when lockdown
is enabled to align to recent GRUB changes.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
GRUB documentation states:
GRUB_OS_PROBER_SKIP_LIST
List of space-separated FS UUIDs of filesystems to be ignored from
os-prober output. For efi chainloaders it’s <UUID>@<EFI FILE>
But the actual behaviour does not match this description.
GRUB_OS_PROBER_SKIP_LIST="<UUID>"
does nothing. In order to skip non-EFI bootloaders, you must set
GRUB_OS_PROBER_SKIP_LIST="<UUID>@<DEVICE>"
which is both absurd, <UUID> and <DEVICE> are redundant, and wrong,
<DEVICE> such as /dev/sd* may not be persistent across boots.
Also, any non-word character is accepted as a separator, including "-"
and "@" which may be present in UUIDs. This can cause false positives
because of partial UUID match.
This patch fixes these flaws while retaining some backward compatibility
with previous behaviour which may be expected by existing setups:
- also accept <UUID>@/dev/* (with warning) for non-EFI bootloaders,
- also accept comma and semicolon as separator.
Fixes: 55e706c9 (Add GRUB_OS_PROBER_SKIP_LIST to selectively skipping systems)
Signed-off-by: Pascal Hambourg <pascal@plouf.fr.eu.org>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This appears to be a relic from GRUB legacy that used a --dumb option for
its terminal command. The proper way to do this in GRUB2 is to set the
terminal to "dumb" via the terminfo command.
Fixes: https://savannah.gnu.org/bugs/?66302
Reported-by: Jernej Jakob <jernej.jakob+savgnu@gmail.com>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Support for @lbracechar{} and @rbracechar{} was added in GNU Texinfo 5.0
but many older systems may have versions lower than this. Use @{ and @}
to support a wider range of GNU Texinfo versions.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The GRUB may use TPM to verify the integrity of boot components and the
result can determine whether a previously sealed key can be released. If
everything checks out, showing nothing has been tampered with, the key
is released and GRUB unlocks the encrypted root partition for the next
stage of booting.
However, the liberal Command Line Interface (CLI) can be misused by
anyone in this case to access files in the encrypted partition one way
or another. Despite efforts to keep the CLI secure by preventing utility
command output from leaking file content, many techniques in the wild
could still be used to exploit the CLI, enabling attacks or learning
methods to attack. It's nearly impossible to account for all scenarios
where a hack could be applied.
Therefore, to mitigate potential misuse of the CLI after the root device
has been successfully unlocked via TPM, the user should be required to
authenticate using the LUKS password. This added layer of security
ensures that only authorized users can access the CLI reducing the risk
of exploitation or unauthorized access to the encrypted partition.
Fixes: CVE-2024-49504
Signed-off-by: Michael Chang <mchang@suse.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
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>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
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>
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>
Document libtasn1 in docs/grub-dev.texi and add the upgrade steps.
Also add the patches to make libtasn1 compatible with GRUB code.
Signed-off-by: Gary Lin <glin@suse.com>
Reviewed-by: Vladimir Serbinenko <phcoder@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
Correct the documentation for the grub.cfg searching via network that
will be done based on ethernet type, -01, which was missing, and a given
MAC address.
Fixes: https://savannah.gnu.org/bugs/?65152
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Correct documentation for UEFI secure boot to remove statement that
chainloader does not work with secure boot. This was fixed by the commit
6d05264 (kern/efi/sb: Add chainloaded image as shim's verifiable object).
Fixes: https://savannah.gnu.org/bugs/?62004
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Correct documentation for pxe_default_server, pxe_default_gatway and
pxe_blksize. Only pxe_default_server is actually used (alias for
net_default_server). So, capture this and remove the other two.
Fixes: https://savannah.gnu.org/bugs/?54480
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add documentation for all GRUB modules contained in the source code tree.
When possible, cross-references to additional detail on commands was added
from their corresponding module documentation. In addition, documentation
for the file command was added.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The fdtdump command allows dumping arbitrary device tree properties
and saving them to a variable similar to the smbios command.
This is useful in scripts where further actions such as selecting
a kernel or loading another device tree depend on the compatible
or model values of the device tree provided by the firmware.
For now only the root level properties of the dtb are exposed.
Signed-off-by: Tobias Heider <tobias.heider@canonical.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add functionality to disable command line interface access and editing of GRUB
menu entries if GRUB image is built with --disable-cli.
Signed-off-by: Alec Brown <alec.r.brown@oracle.com>
Reviewed-by: Vladimir Serbinenko <phcoder@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The EROFS [1] is a lightweight read-only filesystem designed for performance
which has already been shipped in most Linux distributions as well as widely
used in several scenarios, such as Android system partitions, container
images and rootfs for embedded devices.
This patch brings in the EROFS uncompressed support. Now, it's possible to
boot directly through GRUB with an EROFS rootfs.
Support for the EROFS compressed files will be added later.
[1] https://erofs.docs.kernel.org
Signed-off-by: Yifan Zhao <zhaoyifan@sjtu.edu.cn>
Tested-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Gao Xiang <hsiangkao@linux.alibaba.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Give the user a chance to re-enter their cryptodisk passphrase after a typo,
rather than immediately failing (and likely dumping them into a GRUB shell).
By default, we allow 3 tries before giving up. A value in the
cryptodisk_passphrase_tries environment variable will override this default.
The user can give up early by entering an empty passphrase, just as they
could before this patch.
Signed-off-by: Forest <forestix@nom.one>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Improve the documentation of the bli module and explain in more detail what
it does. Make clear that GPT formatted drives are expected and other
partition formats are ignored. Also reorder and reword this section a bit.
Signed-off-by: Oliver Steffen <osteffen@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
It has been reported that makeinfo version 4.13a complains and returns
error when menus for chapter structuring commands are not present. It
is also known that newer makeinfos, such as version 6.7, will create
default menus when needed. Since the menu will be created regardless,
explicitly create it to support older makeinfo versions. This also
enables building to be successful when an older makeinfo is installed
because in that case info files are attempted to be generated with the
"all" target.
Reported-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Olaf Hering <olaf@aepfle.de>
The @xref command is meant to be used at the beginning of a sentence
because its expansion creates a "See " prefix on all output formats, and
on older makeinfo versions is strict about enforcing a "." or "," after
the command. The @ref command has no such restriction and is just the
link, which allows more control over output. This also fixes an issue
where there was a repeated "see" in the output.
Reported-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Olaf Hering <olaf@aepfle.de>
A list of improvements:
* Remove reference to "initial ramdisk" and replace with "initrd". This
then covers the case of ramdisk and ramfs, which is the usual method
with kernels 2.6 and newer.
* Add sentence with URL to initrd documentation Linux kernel.
* Add a section documenting how to have the initrd command generate
a new-style initrd via a specially crafted argument and include an example.
* Update initrd16 to refer to the initrd section and make note that
initrd16 is only on the pc platform.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The cat command should not be used to print binary data because it can
show bytes not in the binary data and not show bytes that are in the data,
which can lead to confusion. This happens because cat does some processing
of the data stream, namely trying to decode substrings as UTF-8.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Also reword a prior sentence to be more clear.
Fixes: 5a3d2b4742df (docs: Add debugging chapter to development documentation)
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
When referring to initrd16 the link for initrd16 should be used, not a link
for initrd. Also, correct the spelling of additionally and add a comma after
it to correct its grammatical usage.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Small set of wording and grammatical edits which did not make it in time
for the original review of the chapter.
Signed-off-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Currently booting the system is prevented when call to EFI firmware
hash_log_extend_event() returns unknown error. Solve this by following
convention used in commit a4356538d (commands/tpm: Don't propagate
measurement failures to the verifiers layer).
Let the system to be bootable by default when unknown TPM error is
encountered. Check environment variable tpm_fail_fatal to fallback to
previous behaviour.
Signed-off-by: Michał Grzelak <mchl.grzlk@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Debugging GRUB can be tricky and require arcane knowledge. This will
help those unfamiliar with the process to get started debugging GRUB
with less effort.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
