From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1VWrzA-0006in-3D for mharc-grub-devel@gnu.org; Thu, 17 Oct 2013 14:07:48 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48825) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VWrz6-0006hy-AO for grub-devel@gnu.org; Thu, 17 Oct 2013 14:07:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VWrz3-0000VG-L3 for grub-devel@gnu.org; Thu, 17 Oct 2013 14:07:44 -0400 Received: from mail-pb0-x24a.google.com ([2607:f8b0:400e:c01::24a]:33705) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VWrz2-0000Un-UO for grub-devel@gnu.org; Thu, 17 Oct 2013 14:07:41 -0400 Received: by mail-pb0-f74.google.com with SMTP id rq2so274119pbb.1 for ; Thu, 17 Oct 2013 11:07:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=from:to:cc:subject:date:message-id; bh=ov5rUOJO7a9snuWTWyXIDck12pnN1SFsJh2enTsghtQ=; b=fcx1NVFOrnPg+ROCmU+hKz8+D5NADvRdzfUhfoNHQ3T6MFZ+MdMoVl1Yro1GZzvwYw TM2/072bh5mqskWwyMnk+uc+2YMloOsqul7FvV9nBCkJCP+b8Jmv0TbmWr4AMmtghe82 NjUWFhci2ahLX8leaHo1xuteu89BLayCuGu5LTqBLPmFiQVrzB4mBUwvEBTHTSb9Hi+c rr24EQsjjBnpJMKlnv4NNELHUKvlJhgOMGCfboreuSHWGlTv+EVhr4xD+fehcObYs10s A2jIQPAe/Od7xEv6ivK+mVN2e7Y5vbxgxGuzbzndCOeslVFqRTOUVQW1kzyGjp6f3wwE BQDA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=ov5rUOJO7a9snuWTWyXIDck12pnN1SFsJh2enTsghtQ=; b=IA9laTWIwg6kmBbwuyB/a+it/0PPDo/P+5enuq07gBiiiolKfpe2P0ylanRN5PHcBO dLHFhLPTTBlJZzHJ9qmI4xduWcpMzLg60au1z77cLnOwduxKksV1DYBSRynOO7VwjNoS aAjEqdyMDhfCsN9/T32WM/7Mzp/E2DyRAJESNFYnPNPCHUDF70Hen2O5WyIqSbJTWq0d eguSk7YsP1CMdKOv+DfnxsvU9PDShr1VU8JRgsJ/CFuqmVhKqyPb0XHQxdEGgS7L1m1v YImDeodH6cvAnSJf7Urq8omAxg6L2XuSfQZN5hUrZSF37VKljQhuyqtiYP2xRPeAK0Zi 1/Mw== X-Gm-Message-State: ALoCoQmplx/ASUjxOuMHNqf3YWq7r724liHWtL+85Ni2q8n2XawNTdvUbZEeOeFjky6Cq2DVXm2l7GPYydasvwJ9FgH5oJ/j7k87LYv1BjoKSdmiv3+A873UH7QkOhnXkmyz55BhpTQ53tl5q1mOD6+DDfkSvf3uhN6unwg7eJc8suyg/+zel7+hNKhs1C2lEDOFAkUNdE8b1so7VgxnZqEq9MzIly1cklvLT81Pfdy4GscdbtNziPA= X-Received: by 10.66.136.47 with SMTP id px15mr3471660pab.28.1382033259794; Thu, 17 Oct 2013 11:07:39 -0700 (PDT) Received: from corp2gmr1-1.hot.corp.google.com (corp2gmr1-1.hot.corp.google.com [172.24.189.92]) by gmr-mx.google.com with ESMTPS id t42si4799197yhm.3.1969.12.31.16.00.00 (version=TLSv1.1 cipher=AES128-SHA bits=128/128); Thu, 17 Oct 2013 11:07:39 -0700 (PDT) Received: from yinz.mtv.corp.google.com (yinz.mtv.corp.google.com [172.17.81.122]) by corp2gmr1-1.hot.corp.google.com (Postfix) with ESMTP id 774A931C1E7; Thu, 17 Oct 2013 11:07:39 -0700 (PDT) Received: by yinz.mtv.corp.google.com (Postfix, from userid 184367) id 1DE8FC0AB1; Thu, 17 Oct 2013 11:07:39 -0700 (PDT) From: Jon McCune To: grub-devel@gnu.org Subject: [PATCH v1] Security-relevant documentation cleanup in response to ML discussion. Date: Thu, 17 Oct 2013 11:07:31 -0700 Message-Id: <1382033251-29852-1-git-send-email-jonmccune@google.com> X-Mailer: git-send-email 1.8.4 X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2607:f8b0:400e:c01::24a Cc: Jon McCune X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list Reply-To: The development of GNU GRUB List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 17 Oct 2013 18:07:47 -0000 - Introduce subsections within Security - Correct errors regarding public key files not being automatically signature-checked in trust and verify_detached - Replace check_signatures=enforce with check_signatures set to enforce - Move detailed discussion of using signatures out of check_signatures environment variable description - Use long form for option flags to security-relevant commands - Explain the key fingerprint format for distrust and list_trusted. Signed-off-by: Jon McCune --- docs/grub.texi | 203 ++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 123 insertions(+), 80 deletions(-) diff --git a/docs/grub.texi b/docs/grub.texi index 40eb9ed..0845183 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -98,8 +98,7 @@ This edition documents version @value{VERSION}. * Environment:: GRUB environment variables * Commands:: The list of available builtin commands * Internationalisation:: Topics relating to language support -* Security:: Authentication and authorisation -* Security and signatures:: Verifying digital signatures in GRUB +* Security:: Authentication, authorisation, and signatures * Platform limitations:: The list of platform-specific limitations * Platform-specific operations:: Platform-specific operations * Supported kernels:: The list of supported kernels @@ -3006,20 +3005,7 @@ chain-loaded system, @pxref{drivemap}. @subsection check_signatures This variable controls whether GRUB enforces digital signature -validation (@pxref{Security and signatures}) on all loaded files. If -@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}). - +validation on loaded files. @xref{Using digital signatures}. @node chosen @subsection chosen @@ -3998,10 +3984,15 @@ but rather replaces it completely. @deffn Command distrust pubkey_id Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys. -These keys are used to validate signatures when -@code{check_signatures=enforce} (@pxref{check_signatures}), and by some -invocations of @command{verify_detached} (@pxref{verify_detached}). -@xref{Security and signatures} for more information. +Note that @var{pubkey_id} is the last eight hexadecimal digits +of the output of @command{list_trusted} (@pxref{list_trusted}). This +is the same as the least significant four bytes of the GPG key +fingerprint (e.g., output of @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 @node drivemap @@ -4264,56 +4255,58 @@ This command is only available on x86 systems. @node 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}. -The @option{-f} option overrides the default location of the environment -block. +The @option{--file} option overrides the default location of the +environment block. @end deffn @node list_trusted @subsection list_trusted @deffn Command list_trusted -List all public keys trusted by GRUB for validating signatures. These -public keys are used implicitly when environment variable -@code{check_signatures=enforce} (@pxref{check_signatures}), and by some -invocations of @command{verify_detached}. @xref{Security and -signatures} for more information. +List all public keys trusted by GRUB for validating signatures. +The output is in GPG's key fingerprint format (e.g., the output of +@code{gpg --fingerprint}). The last eight hexadecimal digits (least +significant four bytes) can be used as an argument to +@command{distrust} (@pxref{distrust}). +@xref{Using digital signatures}, for more information about uses for +these keys. @end deffn @node 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. @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. -The @option{-s} (long form @option{--skip-sig}) option skips signature -checking even when the value of @code{check_signatures=enforce} -(@pxref{check_signatures}). +The @option{--skip-sig} option skips signature checking even when the +value of environment variable @code{check_signatures} is set to +@code{enforce} (@pxref{check_signatures}). If one or more variable names are provided as arguments, they are interpreted as a whitelist of variables to load from the environment block file. Variables set in the file but not present in the whitelist are ignored. -The @option{-s} option should be used with care, and should always be -used in concert with a whitelist of acceptable variables whose values -should be set. Failure to employ a carefully constructed whitelist -could result in reading a malicious value of critical environment -variables from the file, such as setting @code{check_signatures=no}, -modifying @code{prefix} to boot from an unexpected location or not at -all, etc. +The @option{--skip-sig} option should be used with care, and should +always be used in concert with a whitelist of acceptable variables +whose values should be set. Failure to employ a carefully constructed +whitelist could result in reading a malicious value of critical +environment variables from the file, such as setting +@code{check_signatures=no}, modifying @code{prefix} to boot from an +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 configurations, but to allow the user to select from among multiple configurations, and to enable ``one-shot'' boot attempts and -``savedefault'' behavior. @xref{Security and signatures} for more +``savedefault'' behavior. @xref{Using digital signatures}, for more information. @end deffn @@ -4558,22 +4551,22 @@ Remove a loaded @var{module}. @node 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. @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. -This command will operate successfully even when -@code{check_signatures=enforce} (@pxref{check_signatures}), since it -writes to disk and does not alter the behavior of GRUB based on any -contents of disk that have been read. It is possible to modify a -digitally signed environment block file from within GRUB using this -command, such that its signature will no longer be valid on subsequent -boots. Care should be taken in such advanced configurations to avoid -rendering the system unbootable. @xref{Security and signatures} for -more information. +This command will operate successfully even when environment variable +@code{check_signatures} is set to @code{enforce} +(@pxref{check_signatures}), since it writes to disk and does not alter +the behavior of GRUB based on any contents of disk that have been +read. It is possible to modify a digitally signed environment block +file from within GRUB using this command, such that its signature will +no longer be valid on subsequent boots. Care should be taken in such +advanced configurations to avoid rendering the system +unbootable. @xref{Using digital signatures}, for more information. @end deffn @@ -4889,8 +4882,14 @@ as @code{if} and @code{while} (@pxref{Shell-like scripting}). @deffn Command trust pubkey_file 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 -signatures when @code{check_signatures=enforce}. -@xref{Security and signatures} for more information. +signatures when environment variable @code{check_signatures} is set to +@code{enforce}. Note that this command implicitly disables +signature-checking when reading @var{pubkey_file} itself. Thus, to +construct a public key hierarchy at runtime, one must use +@command{verify_detached} (@pxref{verify_detached}) and explicitly +write their @code{grub.cfg} to check the result before invoking +@command{trust}. @xref{Using digital signatures}, for more +information. @end deffn @@ -4928,14 +4927,19 @@ Verifies a GPG-style detached signature, where the signed file is Optionally, a specific public key to use can be specified using @var{pubkey_file}. Otherwise, public keys from GRUB's trusted keys (@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}) are -tried. Note that, when @code{check_signatures=enforce}, an explicitly -identified @var{pubkey_file} must itself be signed by an -already-trusted key. +tried. + +Note that the option of providing a @var{pubkey_file} is primarily for +testing, as the @var{pubkey_file} is never signature-checked itself, +even if there are already one or more trusted public keys loaded into +GRUB, and environment variable @code{check_signatures} is set to +@code{enforce}. Exit code @code{$?} is set to 0 if the signature validates successfully. If validation fails, it is set to a non-zero value. -@xref{Security and signatures} for more information. +@xref{Using digital signatures}, for more information, including a +discussion of dynamically loading a public key hierarchy. @end deffn @node videoinfo @@ -5234,7 +5238,15 @@ test from coreutils. environment variables and commands are listed in the same order. @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 access to the console: anyone can select and edit any menu entry, and anyone @@ -5301,18 +5313,41 @@ generating configuration files with authentication. You can use adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2} commands. -@node Security and signatures -@chapter Security considerations when using digital signatures - -GRUB's @file{core.img} can optionally provide enforcement that all -files subsequently read from disk are covered by a valid digital -signature. This includes GRUB configuration files, the GRUB -environment block, GRUB loadable modules and their dependency files, -and loaded operating system files such as a Linux kernel. This -document does @strong{not} cover how to ensure that your platform's -firmware (e.g., Coreboot) validates +@node Using digital signatures +@section Using digital signatures in GRUB + +GRUB's @file{core.img} can optionally provide enforcement that files +subsequently read from disk are covered by a valid digital signature. +This includes all files, with the following exceptions: the public key +file specified as an argument to @command{trust} (@pxref{trust}), and +the public key file optionally specified as an argument to direct +invocation of @command{verify_detached} (@pxref{verify_detached}). +This document does @strong{not} cover how to ensure that your +platform's firmware (e.g., Coreboot or UEFI Secure Boot) validates @file{core.img}. +If environment variable @code{check_signatures} +(@pxref{check_signatures}) is set to @code{enforce}, then every +attempt (modulo the exceptions mentioned above) 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). + +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}). Presently it +is necessary to write a custom wrapper around @command{grub-mkimage} +using the @code{--grub-mkimage} flag to @command{grub-install}. + GRUB uses GPG-style detached signatures (meaning that a file @file{foo.sig} will be produced when file @file{foo} is signed), and currently supports the DSA signing algorithm. Both 2048-bit and @@ -5353,10 +5388,11 @@ See also: @ref{check_signatures}, @ref{verify_detached}, @ref{trust}, @ref{list_trusted}, @ref{distrust}, @ref{load_env}, @ref{save_env}. Note that internally signature enforcement is controlled by setting -the environment variable @code{check_signatures=enforce}. Passing one -or more @code{--pubkey} options to @command{grub-mkimage} implicitly -sets @code{check_signatures=enforce} in @file{core.img} prior to -processing any configuration files. +the environment variable @code{check_signatures} equal to +@code{enforce}. Passing one or more @code{--pubkey} options to +@command{grub-mkimage} implicitly defines @code{check_signatures} +equal to @code{enforce} in @file{core.img} prior to processing any +configuration files. Note that signature checking does @strong{not} prevent an attacker with (serial, physical, ...) console access from dropping manually to @@ -5366,12 +5402,13 @@ the GRUB console and executing: set check_signatures=no @end example -To prevent this, password-protection (@pxref{Security}) is essential. -Note that even with GRUB password protection, GRUB itself cannot -prevent someone with physical access to the machine from altering that -machine's firmware (e.g., Coreboot or BIOS) configuration to cause -the machine to boot from a different (attacker-controlled) device. -GRUB is at best only one link in a secure boot chain. +To prevent this, password-protection (@pxref{Authentication and +authorisation}) is essential. Note that even with GRUB password +protection, GRUB itself cannot prevent someone with physical access to +the machine from altering that machine's firmware (e.g., Coreboot +or BIOS) configuration to cause the machine to boot from a different +(attacker-controlled) device. GRUB is at best only one link in a +secure boot chain. @node Platform limitations @chapter Platform limitations @@ -5809,6 +5846,12 @@ mounted on Recheck the device map, even if @file{/boot/grub/device.map} already exists. You should use this option whenever you add/remove a disk into/from your computer. + +@item --grub-mkimage=@var{program} +Use @var{program} as @command{grub-mkimage}. This is primarily useful +for advanced users who wish to provide custom arguments to +@command{grub-mkimage}. @xref{Using digital signatures}, for an example +use case. @end table -- 1.8.4