vbatts/grub
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Documentation cleanup in response to ML discussion.

Browse source 
[v0] Accepted with modifications by phcoder@
 [v1] Introduce subsections within Security
 [v1] Correct errors regarding public key files not being automatically signature-checked in trust and verify_detached
 [v1] Replace check_signatures=enforce with check_signatures set to enforce
 [v1] Move detailed discussion of using signatures out of check_signatures environment variable description
 [v1] Use long form for option flags to security-relevant commands
 [v2] Explain the key fingerprint format for distrust and list_trusted.
 [v2] Eliminates references to grub-mkimage and UEFI Secure Boot.
 [v3] Updates in response to addition of --skip-sig to trust and verify_detached
 [  ] Restore @xref for cross-references at the start of sentences
This commit is contained in:
Jon McCune 2013-10-25 08:31:36 -07:00
parent af81ed880d
commit c16535a845
2 changed files with 115 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
2013-10-25 Jon McCune <jonmccune@google.com>
* docs/grub.texi: Cleanup security documentation around signatures.
2013-10-25 Vladimir Serbinenko <phcoder@gmail.com> 2013-10-25 Vladimir Serbinenko <phcoder@gmail.com>
* conf/Makefile.common (CPPFLAGS_KERNEL): Add -DGRUB_KERNEL=1. * conf/Makefile.common (CPPFLAGS_KERNEL): Add -DGRUB_KERNEL=1.

195
docs/grub.texi
View file

@ -98,8 +98,7 @@ This edition documents version @value{VERSION}.
* Environment:: GRUB environment variables * Environment:: GRUB environment variables
* Commands:: The list of available builtin commands * Commands:: The list of available builtin commands
* Internationalisation:: Topics relating to language support * Internationalisation:: Topics relating to language support
* Security:: Authentication and authorisation * Security:: Authentication, authorisation, and signatures
* Security and signatures:: Verifying digital signatures in GRUB
* Platform limitations:: The list of platform-specific limitations * Platform limitations:: The list of platform-specific limitations
* Platform-specific operations:: Platform-specific operations * Platform-specific operations:: Platform-specific operations
* Supported kernels:: The list of supported kernels * Supported kernels:: The list of supported kernels
@ -3006,20 +3005,7 @@ chain-loaded system, @pxref{drivemap}.
@subsection check_signatures @subsection check_signatures
This variable controls whether GRUB enforces digital signature This variable controls whether GRUB enforces digital signature
validation (@pxref{Security and signatures}) on all loaded files. If validation on loaded files. @xref{Using digital signatures}.
@code{check_signatures=enforce}, then every attempt by the GRUB
@file{core.img} to load another file @file{foo} (e.g., a loadable
module, a configuration file, or a Linux kernel) implicitly invokes
@code{verify_detached foo foo.sig} (@pxref{verify_detached}).
@code{foo.sig} must contain a valid digital signature over the
contents of @code{foo}, which can be verified with a public key
currently trusted by GRUB (@pxref{list_trusted}, @pxref{trust}, and
@pxref{distrust}). If validation fails, then file @file{foo} cannot
be opened. This failure may halt or otherwise impact the boot
process. An initial trusted public key can be embedded within the
GRUB @file{core.img} using the @code{--pubkey} option to
@command{grub-mkimage} (@pxref{Invoking grub-install}).
@node chosen @node chosen
@subsection chosen @subsection chosen
@ -3998,10 +3984,15 @@ but rather replaces it completely.
@deffn Command distrust pubkey_id @deffn Command distrust pubkey_id
Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys. Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys.
These keys are used to validate signatures when @var{pubkey_id} is the last four bytes (eight hexadecimal digits) of
@code{check_signatures=enforce} (@pxref{check_signatures}), and by some the GPG v4 key id, which is also the output of @command{list_trusted}
invocations of @command{verify_detached} (@pxref{verify_detached}). (@pxref{list_trusted}). Outside of GRUB, the key id can be obtained
@pxref{Security and signatures} for more information. using @code{gpg --fingerprint}).
These keys are used to validate signatures when environment variable
@code{check_signatures} is set to @code{enforce}
(@pxref{check_signatures}), and by some invocations of
@command{verify_detached} (@pxref{verify_detached}). @xref{Using
digital signatures}, for more information.
@end deffn @end deffn
@node drivemap @node drivemap
@ -4264,56 +4255,58 @@ This command is only available on x86 systems.
@node list_env @node list_env
@subsection list_env @subsection list_env
@deffn Command list_env [@option{-f} file] @deffn Command list_env [@option{--file} file]
List all variables in the environment block file. @xref{Environment block}. List all variables in the environment block file. @xref{Environment block}.
The @option{-f} option overrides the default location of the environment The @option{--file} option overrides the default location of the
block. environment block.
@end deffn @end deffn
@node list_trusted @node list_trusted
@subsection list_trusted @subsection list_trusted
@deffn Command list_trusted @deffn Command list_trusted
List all public keys trusted by GRUB for validating signatures. These List all public keys trusted by GRUB for validating signatures.
public keys are used implicitly when environment variable The output is in GPG's v4 key fingerprint format (i.e., the output of
@code{check_signatures=enforce} (@pxref{check_signatures}), and by some @code{gpg --fingerprint}). The least significant four bytes (last
invocations of @command{verify_detached}. @pxref{Security and eight hexadecimal digits) can be used as an argument to
signatures} for more information. @command{distrust} (@pxref{distrust}).
@xref{Using digital signatures}, for more information about uses for
these keys.
@end deffn @end deffn
@node load_env @node load_env
@subsection load_env @subsection load_env
@deffn Command load_env [@option{-f} file] [@option{-s}] [whitelisted_variable_name] @dots{} @deffn Command load_env [@option{--file} file] [@option{--skip-sig}] [whitelisted_variable_name] @dots{}
Load all variables from the environment block file into the environment. Load all variables from the environment block file into the environment.
@xref{Environment block}. @xref{Environment block}.
The @option{-f} option overrides the default location of the environment The @option{--file} option overrides the default location of the environment
block. block.
The @option{-s} (long form @option{--skip-sig}) option skips signature The @option{--skip-sig} option skips signature checking even when the
checking even when the value of @code{check_signatures=enforce} value of environment variable @code{check_signatures} is set to
(@pxref{check_signatures}). @code{enforce} (@pxref{check_signatures}).
If one or more variable names are provided as arguments, they are If one or more variable names are provided as arguments, they are
interpreted as a whitelist of variables to load from the environment interpreted as a whitelist of variables to load from the environment
block file. Variables set in the file but not present in the block file. Variables set in the file but not present in the
whitelist are ignored. whitelist are ignored.
The @option{-s} option should be used with care, and should always be The @option{--skip-sig} option should be used with care, and should
used in concert with a whitelist of acceptable variables whose values always be used in concert with a whitelist of acceptable variables
should be set. Failure to employ a carefully constructed whitelist whose values should be set. Failure to employ a carefully constructed
could result in reading a malicious value of critical environment whitelist could result in reading a malicious value into critical
variables from the file, such as setting @code{check_signatures=no}, environment variables from the file, such as setting
modifying @code{prefix} to boot from an unexpected location or not at @code{check_signatures=no}, modifying @code{prefix} to boot from an
all, etc. unexpected location or not at all, etc.
When used with care, @option{-s} and the whitelist enable an When used with care, @option{--skip-sig} and the whitelist enable an
administrator to configure a system to boot only signed administrator to configure a system to boot only signed
configurations, but to allow the user to select from among multiple configurations, but to allow the user to select from among multiple
configurations, and to enable ``one-shot'' boot attempts and configurations, and to enable ``one-shot'' boot attempts and
``savedefault'' behavior. @pxref{Security and signatures} for more ``savedefault'' behavior. @xref{Using digital signatures}, for more
information. information.
@end deffn @end deffn
@ -4558,22 +4551,22 @@ Remove a loaded @var{module}.
@node save_env @node save_env
@subsection save_env @subsection save_env
@deffn Command save_env [@option{-f} file] var @dots{} @deffn Command save_env [@option{--file} file] var @dots{}
Save the named variables from the environment to the environment block file. Save the named variables from the environment to the environment block file.
@xref{Environment block}. @xref{Environment block}.
The @option{-f} option overrides the default location of the environment The @option{--file} option overrides the default location of the environment
block. block.
This command will operate successfully even when This command will operate successfully even when environment variable
@code{check_signatures=enforce} (@pxref{check_signatures}), since it @code{check_signatures} is set to @code{enforce}
writes to disk and does not alter the behavior of GRUB based on any (@pxref{check_signatures}), since it writes to disk and does not alter
contents of disk that have been read. It is possible to modify a the behavior of GRUB based on any contents of disk that have been
digitally signed environment block file from within GRUB using this read. It is possible to modify a digitally signed environment block
command, such that its signature will no longer be valid on subsequent file from within GRUB using this command, such that its signature will
boots. Care should be taken in such advanced configurations to avoid no longer be valid on subsequent boots. Care should be taken in such
rendering the system unbootable. @pxref{Security and signatures} for advanced configurations to avoid rendering the system
more information. unbootable. @xref{Using digital signatures}, for more information.
@end deffn @end deffn
@ -4886,11 +4879,17 @@ as @code{if} and @code{while} (@pxref{Shell-like scripting}).
@node trust @node trust
@subsection trust @subsection trust
@deffn Command trust pubkey_file @deffn Command trust [@option{--skip-sig}] pubkey_file
Read public key from @var{pubkey_file} and add it to GRUB's internal Read public key from @var{pubkey_file} and add it to GRUB's internal
list of trusted public keys. These keys are used to validate digital list of trusted public keys. These keys are used to validate digital
signatures when @code{check_signatures=enforce}. signatures when environment variable @code{check_signatures} is set to
@pxref{Security and signatures} for more information. @code{enforce}. Note that if @code{check_signatures} is set to
@code{enforce} when @command{trust} executes, then @var{pubkey_file}
must itself be properly signed. The @option{--skip-sig} option can be
used to disable signature-checking when reading @var{pubkey_file}
itself. It is expected that @option{--skip-sig} is useful for testing
and manual booting. @xref{Using digital signatures}, for more
information.
@end deffn @end deffn
@ -4922,20 +4921,21 @@ only on PC BIOS platforms.
@node verify_detached @node verify_detached
@subsection verify_detached @subsection verify_detached
@deffn Command verify_detached file signature_file [pubkey_file] @deffn Command verify_detached [@option{--skip-sig}] file signature_file [pubkey_file]
Verifies a GPG-style detached signature, where the signed file is Verifies a GPG-style detached signature, where the signed file is
@var{file}, and the signature itself is in file @var{signature_file}. @var{file}, and the signature itself is in file @var{signature_file}.
Optionally, a specific public key to use can be specified using Optionally, a specific public key to use can be specified using
@var{pubkey_file}. Otherwise, public keys from GRUB's trusted keys @var{pubkey_file}. When environment variable @code{check_signatures}
is set to @code{enforce}, then @var{pubkey_file} must itself be
properly signed by an already-trusted key. An unsigned
@var{pubkey_file} can be loaded by specifying @option{--skip-sig}.
If @var{pubkey_file} is omitted, then public keys from GRUB's trusted keys
(@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}) are (@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}) are
tried. Note that, when @code{check_signatures=enforce}, an explicitly tried.
identified @var{pubkey_file} must itself be signed by an
already-trusted key.
Exit code @code{$?} is set to 0 if the signature validates Exit code @code{$?} is set to 0 if the signature validates
successfully. If validation fails, it is set to a non-zero value. successfully. If validation fails, it is set to a non-zero value.
@xref{Using digital signatures}, for more information.
@pxref{Security and signatures} for more information.
@end deffn @end deffn
@node videoinfo @node videoinfo
@ -5234,7 +5234,15 @@ test from coreutils.
environment variables and commands are listed in the same order. environment variables and commands are listed in the same order.
@node Security @node Security
@chapter Authentication and authorisation @chapter Security
@menu
* Authentication and authorisation:: Users and access control
* Using digital signatures:: Booting digitally signed code
@end menu
@node Authentication and authorisation
@section Authentication and authorisation in GRUB
By default, the boot loader interface is accessible to anyone with physical By default, the boot loader interface is accessible to anyone with physical
access to the console: anyone can select and edit any menu entry, and anyone access to the console: anyone can select and edit any menu entry, and anyone
@ -5301,17 +5309,34 @@ generating configuration files with authentication. You can use
adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2} adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
commands. commands.
@node Security and signatures @node Using digital signatures
@chapter Security considerations when using digital signatures @section Using digital signatures in GRUB
GRUB's @file{core.img} can optionally provide enforcement that all GRUB's @file{core.img} can optionally provide enforcement that all files
files subsequently read from disk are covered by a valid digital subsequently read from disk are covered by a valid digital signature.
signature. This includes GRUB configuration files, the GRUB This document does @strong{not} cover how to ensure that your
environment block, GRUB loadable modules and their dependency files, platform's firmware (e.g., Coreboot) validates @file{core.img}.
and loaded operating system files such as a Linux kernel. This
document does @strong{not} cover how to ensure that your platform's If environment variable @code{check_signatures}
firmware (e.g., Coreboot) validates (@pxref{check_signatures}) is set to @code{enforce}, then every
@file{core.img}. attempt by the GRUB @file{core.img} to load another file @file{foo}
implicitly invokes @code{verify_detached foo foo.sig}
(@pxref{verify_detached}). @code{foo.sig} must contain a valid
digital signature over the contents of @code{foo}, which can be
verified with a public key currently trusted by GRUB
(@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}). If
validation fails, then file @file{foo} cannot be opened. This failure
may halt or otherwise impact the boot process.
@comment Unfortunately --pubkey is not yet supported by grub-install,
@comment but we should not bring up internal detail grub-mkimage here
@comment in the user guide (as opposed to developer's manual).
@comment An initial trusted public key can be embedded within the GRUB
@comment @file{core.img} using the @code{--pubkey} option to
@comment @command{grub-mkimage} (@pxref{Invoking grub-install}). Presently it
@comment is necessary to write a custom wrapper around @command{grub-mkimage}
@comment using the @code{--grub-mkimage} flag to @command{grub-install}.
GRUB uses GPG-style detached signatures (meaning that a file GRUB uses GPG-style detached signatures (meaning that a file
@file{foo.sig} will be produced when file @file{foo} is signed), and @file{foo.sig} will be produced when file @file{foo} is signed), and
@ -5353,10 +5378,11 @@ See also: @ref{check_signatures}, @ref{verify_detached}, @ref{trust},
@ref{list_trusted}, @ref{distrust}, @ref{load_env}, @ref{save_env}. @ref{list_trusted}, @ref{distrust}, @ref{load_env}, @ref{save_env}.
Note that internally signature enforcement is controlled by setting Note that internally signature enforcement is controlled by setting
the environment variable @code{check_signatures=enforce}. Passing one the environment variable @code{check_signatures} equal to
or more @code{--pubkey} options to @command{grub-mkimage} implicitly @code{enforce}. Passing one or more @code{--pubkey} options to
sets @code{check_signatures=enforce} in @file{core.img} prior to @command{grub-mkimage} implicitly defines @code{check_signatures}
processing any configuration files. equal to @code{enforce} in @file{core.img} prior to processing any
configuration files.
Note that signature checking does @strong{not} prevent an attacker Note that signature checking does @strong{not} prevent an attacker
with (serial, physical, ...) console access from dropping manually to with (serial, physical, ...) console access from dropping manually to
@ -5366,12 +5392,13 @@ the GRUB console and executing:
set check_signatures=no set check_signatures=no
@end example @end example
To prevent this, password-protection (@pxref{Security}) is essential. To prevent this, password-protection (@pxref{Authentication and
Note that even with GRUB password protection, GRUB itself cannot authorisation}) is essential. Note that even with GRUB password
prevent someone with physical access to the machine from altering that protection, GRUB itself cannot prevent someone with physical access to
machine's firmware (e.g., Coreboot or BIOS) configuration to cause the machine from altering that machine's firmware (e.g., Coreboot
the machine to boot from a different (attacker-controlled) device. or BIOS) configuration to cause the machine to boot from a different
GRUB is at best only one link in a secure boot chain. (attacker-controlled) device. GRUB is at best only one link in a
secure boot chain.
@node Platform limitations @node Platform limitations
@chapter Platform limitations @chapter Platform limitations