From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1VZQRk-00072c-9j for mharc-grub-devel@gnu.org; Thu, 24 Oct 2013 15:19:52 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42117) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VZQRa-00071R-7R for grub-devel@gnu.org; Thu, 24 Oct 2013 15:19:50 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VZQRR-0001j3-N5 for grub-devel@gnu.org; Thu, 24 Oct 2013 15:19:42 -0400 Received: from mail-ea0-x22a.google.com ([2a00:1450:4013:c01::22a]:62724) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VZQRR-0001ir-8O for grub-devel@gnu.org; Thu, 24 Oct 2013 15:19:33 -0400 Received: by mail-ea0-f170.google.com with SMTP id q10so1201689eaj.1 for ; Thu, 24 Oct 2013 12:19:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=message-id:date:from:user-agent:mime-version:to:subject:references :in-reply-to:content-type; bh=U6jsfyIuFrore6yLYRS1DyyhqzzRQnhsTNG8H3BFcfE=; b=pPMqrQCWcP1cfhaufI4NeS43uxhFgxmZwoT15wSme9muiOJTTFXDlXEvc8Fgul7mD3 RcDI5pClsoIoHvQaXrVWMiUkEP5Tkqu2Un8dVm5biujZ8730JxoqYvGI22403lIJBsHG NtmYvY9w+snIT8he5y42DII7onkyeAp1SXiEk9qE0O/Yz96Z1iyTSVSeJ46gUDgKDAvd ZDriRx79NJiYS+z+NsYOpTNlTZ8kg2R3W/IP/cqJ37x1St+p9k3k9Mdi9WIk6us/hYwP aCrUyEVPZiyvAVrUxuUt6HCw3eg3TlsdtUcAQltkxZx8BWiwctRDQlMNG+9UKx7DTW0x 5YLg== X-Received: by 10.14.2.200 with SMTP id 48mr3795989eef.88.1382642372473; Thu, 24 Oct 2013 12:19:32 -0700 (PDT) Received: from [192.168.1.16] (31-249.1-85.cust.bluewin.ch. [85.1.249.31]) by mx.google.com with ESMTPSA id j7sm7921458eeo.15.2013.10.24.12.19.31 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 24 Oct 2013 12:19:31 -0700 (PDT) Message-ID: <526972C2.9020509@gmail.com> Date: Thu, 24 Oct 2013 21:19:30 +0200 From: =?UTF-8?B?VmxhZGltaXIgJ8+GLWNvZGVyL3BoY29kZXInIFNlcmJpbmVua28=?= User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20131005 Icedove/17.0.9 MIME-Version: 1.0 To: grub-devel@gnu.org Subject: Re: [PATCH v3] Documentation cleanup in response to ML discussion. References: <1382397355-20609-1-git-send-email-jonmccune@google.com> In-Reply-To: <1382397355-20609-1-git-send-email-jonmccune@google.com> X-Enigmail-Version: 1.5.1 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="----enig2JXPRMWWCMORXCVBEQXQN" X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:4013:c01::22a 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, 24 Oct 2013 19:19:50 -0000 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) ------enig2JXPRMWWCMORXCVBEQXQN Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Go ahead On 22.10.2013 01:15, Jon McCune wrote: > [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=3Denforce with check_signatures set to e= nforce > [v1] Move detailed discussion of using signatures out of check_signatu= res 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 >=20 > Signed-off-by: Jon McCune > --- > docs/grub.texi | 197 ++++++++++++++++++++++++++++++++-----------------= -------- > 1 file changed, 112 insertions(+), 85 deletions(-) >=20 > diff --git a/docs/grub.texi b/docs/grub.texi > index 40eb9ed..8b0b76b 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 sig= natures > * Platform limitations:: The list of platform-specific limitati= ons > * 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 > =20 > This variable controls whether GRUB enforces digital signature > -validation (@pxref{Security and signatures}) on all loaded files. If > -@code{check_signatures=3Denforce}, 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}. > =20 > @node chosen > @subsection chosen > @@ -3998,10 +3984,15 @@ but rather replaces it completely. > =20 > @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=3Denforce} (@pxref{check_signatures}), and by s= ome > -invocations of @command{verify_detached} (@pxref{verify_detached}). > -@xref{Security and signatures} for more information. > +@var{pubkey_id} is the last four bytes (eight hexadecimal digits) of > +the GPG v4 key id, which is also the output of @command{list_trusted} > +(@pxref{list_trusted}). Outside of GRUB, the key id can be obtained > +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 > =20 > @node drivemap > @@ -4264,56 +4255,58 @@ This command is only available on x86 systems. > @node list_env > @subsection list_env > =20 > -@deffn Command list_env [@option{-f} file] > +@deffn Command list_env [@option{--file} file] > List all variables in the environment block file. @xref{Environment b= lock}. > =20 > -The @option{-f} option overrides the default location of the environme= nt > -block. > +The @option{--file} option overrides the default location of the > +environment block. > @end deffn > =20 > @node list_trusted > @subsection list_trusted > =20 > @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=3Denforce} (@pxref{check_signatures}), and by s= ome > -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 v4 key fingerprint format (i.e., the output of > +@code{gpg --fingerprint}). The least significant four bytes (last > +eight hexadecimal digits) 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 > =20 > @node load_env > @subsection load_env > =20 > -@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 environmen= t. > @xref{Environment block}. > =20 > -The @option{-f} option overrides the default location of the environme= nt > +The @option{--file} option overrides the default location of the envir= onment > block. > =20 > -The @option{-s} (long form @option{--skip-sig}) option skips signature= > -checking even when the value of @code{check_signatures=3Denforce} > -(@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}). > =20 > 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. > =20 > -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=3Dno},= > -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 into critical > +environment variables from the file, such as setting > +@code{check_signatures=3Dno}, modifying @code{prefix} to boot from an > +unexpected location or not at all, etc. > =20 > -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 > =20 > @@ -4558,22 +4551,22 @@ Remove a loaded @var{module}. > @node save_env > @subsection save_env > =20 > -@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}. > =20 > -The @option{-f} option overrides the default location of the environme= nt > +The @option{--file} option overrides the default location of the envir= onment > block. > =20 > -This command will operate successfully even when > -@code{check_signatures=3Denforce} (@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 > =20 > =20 > @@ -4886,11 +4879,17 @@ as @code{if} and @code{while} (@pxref{Shell-lik= e scripting}). > @node trust > @subsection trust > =20 > -@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 > list of trusted public keys. These keys are used to validate digital > -signatures when @code{check_signatures=3Denforce}. > -@xref{Security and signatures} for more information. > +signatures when environment variable @code{check_signatures} is set to= > +@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 > =20 > =20 > @@ -4922,20 +4921,21 @@ only on PC BIOS platforms. > @node verify_detached > @subsection verify_detached > =20 > -@deffn Command verify_detached file signature_file [pubkey_file] > +@deffn Command verify_detached [@option{--skip-sig}] file signature_fi= le [pubkey_file] > Verifies a GPG-style detached signature, where the signed file is > @var{file}, and the signature itself is in file @var{signature_file}. > 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 > -tried. Note that, when @code{check_signatures=3Denforce}, an explicit= ly > -identified @var{pubkey_file} must itself be signed by an > -already-trusted key. > +tried. =20 > =20 > 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. > @end deffn > =20 > @node videoinfo > @@ -5234,7 +5234,15 @@ test from coreutils. > environment variables and commands are listed in the same order. > =20 > @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 > =20 > By default, the boot loader interface is accessible to anyone with phy= sical > access to the console: anyone can select and edit any menu entry, and = anyone > @@ -5301,17 +5309,34 @@ generating configuration files with authenticat= ion. You can use > adding @kbd{set superusers=3D} and @kbd{password} or @kbd{password_pbk= df2} > commands. > =20 > -@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 > -@file{core.img}. > +@node Using digital signatures > +@section Using digital signatures in GRUB > + > +GRUB's @file{core.img} can optionally provide enforcement that all fil= es > +subsequently read from disk are covered by a valid digital signature. > +This document does @strong{not} cover how to ensure that your > +platform's firmware (e.g., Coreboot) validates @file{core.img}. > + > +If environment variable @code{check_signatures} > +(@pxref{check_signatures}) is set to @code{enforce}, then every > +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}). Pres= ently it > +@comment is necessary to write a custom wrapper around @command{grub-m= kimage} > +@comment using the @code{--grub-mkimage} flag to @command{grub-install= }. > =20 > GRUB uses GPG-style detached signatures (meaning that a file > @file{foo.sig} will be produced when file @file{foo} is signed), and > @@ -5353,10 +5378,11 @@ See also: @ref{check_signatures}, @ref{verify_d= etached}, @ref{trust}, > @ref{list_trusted}, @ref{distrust}, @ref{load_env}, @ref{save_env}. > =20 > Note that internally signature enforcement is controlled by setting > -the environment variable @code{check_signatures=3Denforce}. Passing o= ne > -or more @code{--pubkey} options to @command{grub-mkimage} implicitly > -sets @code{check_signatures=3Denforce} 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. > =20 > Note that signature checking does @strong{not} prevent an attacker > with (serial, physical, ...) console access from dropping manually to > @@ -5366,12 +5392,13 @@ the GRUB console and executing: > set check_signatures=3Dno > @end example > =20 > -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. > =20 > @node Platform limitations > @chapter Platform limitations >=20 ------enig2JXPRMWWCMORXCVBEQXQN Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.15 (GNU/Linux) Comment: Using GnuPG with Icedove - http://www.enigmail.net/ iF4EAREKAAYFAlJpcsIACgkQNak7dOguQgmnJQEAwwyg4IoajgGmPIQOaU9qHkE7 tm38KVS2mON//7CSL7gA/inHLcyYwNuV4ug59LPDY+6+Nyt1Vjxx7kWZ6CpUDWYj =/TRx -----END PGP SIGNATURE----- ------enig2JXPRMWWCMORXCVBEQXQN--