Received: from list by lists.gnu.org with archive (Exim 4.71) id 1VPbPP-0007ER-Gm for mharc-grub-devel@gnu.org; Fri, 27 Sep 2013 13:00:51 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:45484) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VPbPL-0007EI-UQ for grub-devel@gnu.org; Fri, 27 Sep 2013 13:00:50 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VPbPJ-00080y-JB for grub-devel@gnu.org; Fri, 27 Sep 2013 13:00:47 -0400 Received: from mail-yh0-x249.google.com ([2607:f8b0:4002:c01::249]:39286) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VPbPI-00080k-TN for grub-devel@gnu.org; Fri, 27 Sep 2013 13:00:45 -0400 Received: by mail-yh0-f73.google.com with SMTP id z20so279990yhz.4 for ; Fri, 27 Sep 2013 10:00:44 -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=oMmSbjapk8v/nxfn6Pr37SYzM/k6/9sIjhItMfVeZms=; b=jKXKl4/JBUvDlBRwbfsNDxcMwaeH83q78PMJCBQe+3gGtQlSj57ecCMcDlp1mM7h1g 75wiE3e67Ib043zghkYHK1WVcfveWfYAjbNgg4M5OqZqvYzNwouDm0owDwa12kEfpEt5 s6OVpFvA5UitIQDMWFnex1RS7nf1haBiIIoymNtHffZjH1N1JlC4iH/oTdHDRqejyhdg NcUO/ajlCpzeAJIxX0pARYA+nhHFdTmYjeZn/ZpCEy00D8hxOmLgHus+xXN3Wf5AryBU V4e1M5wk85AhwIp4+eHXUoeRpwuJulzkW81DG888EzZBa2MsShtOt903uz9qrmoXbj+m RJcA== 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=oMmSbjapk8v/nxfn6Pr37SYzM/k6/9sIjhItMfVeZms=; b=f08v50rsvKCqeU/1zA6hsAEprlcgYYGtWMH1AInHWey4BqjZ/XI6ebW+Fhx8/1Y3AU Fho1Esf9eDTIXB5b7zizDXg0pJfdgac9TApete0h+yS1LNYjr8+2wGeq8soI1ykXlDUF ZFW/YJDVAlEZFv0UxxQLAc+ZMr+UgIFUaefFOl7hSDfLoxk89UTeLfEWUlIo7y3W58Qi UnMmwV1jIYY6D7nrz73dJKkLVVHoDrU3Q6Izjgmj3kyAN90WbCK22+XYMUImeHa/cPiB T4Ml1bYzxVih6JeyJPhyscHFZDwPZKecjuHKr5+EoPDXqA6ilx3ZaxBcIzGXQ9zy7n9w LDCg== X-Gm-Message-State: ALoCoQnJyWkf3y3wGL3ezHBLbPrUgC6kJ3MLLPV0+OQh/Tekg78dIdjivRbLsORSEngkjSjkExXGXBipLwauhXjqw4ej60zFtoogXMHHUdsFTHo2ff2W4j8vxVtEqtab+3ZFNBETcbbJrSvUwFcadV7BEVrK3V0lKRE+APGyDKBgQNJ80P0D8bM1yqyaRc/9gPR0N1pmT74zQxU8if+2QF4G5tll0PvAZbQ2HVfngy0g8CcK+7Cn5bI= X-Received: by 10.236.111.73 with SMTP id v49mr1344248yhg.46.1380301244199; Fri, 27 Sep 2013 10:00:44 -0700 (PDT) Received: from corp2gmr1-2.hot.corp.google.com (corp2gmr1-2.hot.corp.google.com [172.24.189.93]) by gmr-mx.google.com with ESMTPS id a49si878144yhc.5.1969.12.31.16.00.00 (version=TLSv1.1 cipher=AES128-SHA bits=128/128); Fri, 27 Sep 2013 10:00:44 -0700 (PDT) Received: from yinz.mtv.corp.google.com (yinz.mtv.corp.google.com [172.17.81.122]) by corp2gmr1-2.hot.corp.google.com (Postfix) with ESMTP id E7A5A5A427E; Fri, 27 Sep 2013 10:00:43 -0700 (PDT) Received: by yinz.mtv.corp.google.com (Postfix, from userid 184367) id 8E769C0936; Fri, 27 Sep 2013 10:00:43 -0700 (PDT) From: Jon McCune To: grub-devel@gnu.org Subject: [PATCH v0] Additional security-relevant documentation Date: Fri, 27 Sep 2013 10:00:37 -0700 Message-Id: <1380301237-19071-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:4002:c01::249 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: Fri, 27 Sep 2013 17:00:50 -0000 Tested with 'make html dvi pdf ps info'. I think the output looks reasonable in each case, but feedback is welcomed. One known issue is that while grub-install does not accept --pubkey, there is some awkward discussion of wrapping grub-mkimage. Commands associated with check_signatures: * High-level discussion in new section "Security and signatures" * Environment variable check_signatures * New documentation for commands distrust, trust, list_trusted, verify_detached * Modifications to documentation for load_env, save_env, hashsum Signed-off-by: Jon McCune --- docs/grub.texi | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 218 insertions(+), 2 deletions(-) diff --git a/docs/grub.texi b/docs/grub.texi index 2bf0d8b..6fd9722 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -96,6 +96,7 @@ This edition documents version @value{VERSION}. * 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 * Platform limitations:: The list of platform-specific limitations * Platform-specific operations:: Platform-specific operations * Supported kernels:: The list of supported kernels @@ -2756,6 +2757,7 @@ These variables have special meaning to GRUB. @menu * biosnum:: +* check_signatures:: * chosen:: * color_highlight:: * color_normal:: @@ -2809,6 +2811,27 @@ For an alternative approach which also changes BIOS drive mappings for the chain-loaded system, @pxref{drivemap}. +@node check_signatures +@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}). Presently it +is necessary to write a custom wrapper around @command{grub-mkimage} +using the @code{--grub-mkimage} flag to @command{grub-install}. + + @node chosen @subsection chosen @@ -3458,6 +3481,7 @@ you forget a command, you can run the command @command{help} * cryptomount:: Mount a crypto device * date:: Display or set current date and time * devicetree:: Load a device tree blob +* distrust:: Remove a pubkey from trusted keys * drivemap:: Map a drive to another * echo:: Display a line of text * eval:: Evaluate agruments as GRUB commands @@ -3475,6 +3499,7 @@ you forget a command, you can run the command @command{help} * linux:: Load a Linux kernel * linux16:: Load a Linux kernel (16-bit mode) * list_env:: List variables in environment block +* list_trusted:: List trusted public keys * loadfont:: Load font files * load_env:: Load variables from environment block * loopback:: Make a device from a filesystem image @@ -3506,9 +3531,11 @@ you forget a command, you can run the command @command{help} * source:: Read a configuration file in same context * test:: Check file types and compare values * true:: Do nothing, successfully +* trust:: Add public key to list of trusted keys * unset:: Unset an environment variable * uppermem:: Set the upper memory size @comment * vbeinfo:: List available video modes +* verify_detached:: Verify detached digital signature * videoinfo:: List available video modes @end menu @@ -3779,6 +3806,16 @@ but rather replaces it completely. @ref{GNU/Linux}. @end deffn +@node distrust +@subsection distrust + +@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. +@end deffn @node drivemap @subsection drivemap @@ -3937,7 +3974,8 @@ list of @var{hash name} pairs in the same format as used by UNIX @command{md5sum} command. Option @option{--prefix} may be used to give directory where files are located. Hash verification stops after the first mismatch was found unless option @option{--keep-going} -was given. +was given. The exit code @code{$?} is set to 0 if hash verification +is successful. If it fails, @code{$?} is set to a nonzero value. @end deffn @@ -4046,16 +4084,50 @@ The @option{-f} 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. +@end deffn @node load_env @subsection load_env -@deffn Command load_env [@option{-f} file] +@deffn Command load_env [@option{-f} file] [@option{-s}] [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 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}). + +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. + +When used with care, @option{-s} 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 +information. @end deffn @@ -4305,6 +4377,16 @@ Save the named variables from the environment to the environment block file. The @option{-f} 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. @end deffn @@ -4614,6 +4696,20 @@ Do nothing, successfully. This is mainly useful in control constructs such as @code{if} and @code{while} (@pxref{Shell-like scripting}). @end deffn +@node trust +@subsection trust + +@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}. Note that if +@code{check_signatures=enforce} when this command is run, then +@var{pubkey_file} must itself be signed such that an already-loaded +public key (@pxref{list_trusted}) can validate that signature. A +public key hierarchy can thus be constructed. +@xref{Security and signatures} for more information. +@end deffn + @node unset @subsection unset @@ -4640,6 +4736,25 @@ only on PC BIOS platforms. @end ignore +@node verify_detached +@subsection verify_detached + +@deffn Command verify_detached file signature_file [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 +(@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. + +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. +@end deffn + @node videoinfo @subsection videoinfo @@ -5003,6 +5118,101 @@ 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., GNU Coreboot or UEFI Secure Boot) validates +@file{core.img}. + +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 +3072-bit keys are supported. A signing key can be generated as +follows: + +@example +gpg --gen-key +@end example + +The corresponding public key must be embedded in @file{core.img} when +executing the @command{grub-mkimage} command (typically as part of +@command{grub-install}, @pxref{Invoking grub-install}) utility. This +can be done using the @code{--pubkey} option to @command{grub-mkimage} +and manually specifying that the modules required for signature +verification be embedded in @file{core.img}. For example: + +@example +# First, wrap grub-mkimage to include your public key(s). +cat < /root/grub-mkimage-pubkey.sh +#!/bin/sh +/usr/bin/grub-mkimage --pubkey=/boot/pubkey.gpg $@@ +EOF +chmod +x /root/grub-mkimage-pubkey.sh +# Then, invoke grub-install, explicitly including the `verify' +# module and its dependencies (as verify cannot signature-check +# itself). +grub-install \ + --grub-mkimage=/root/grub-mkimage-pubkey.sh \ + --modules="verify gcry_rsa gcry_dsa gcry_sha256 hashsum"\ +"gcry_sha1 mpi echo loadenv" \ + /dev/sda +@end example + +An individual file can be signed as follows: + +@example +gpg --detach-sign /path/to/file +@end example + +For successful validation of all of GRUB's subcomponents and the +loaded OS kernel, they must all be signed. One way to accomplish this +is the following (after having already produced the desired +@file{grub.cfg} file, e.g., by running @command{grub-mkconfig} +(@pxref{Invoking grub-mkconfig}): + +@example +@group +# Edit /dev/shm/passphrase.txt to contain your signing key's passphrase +for i in `find /boot -name "*.cfg" -or -name "*.lst" -or \ + -name "*.mod" -or -name "vmlinuz*" -or -name "initrd*" -or \ + -name "grubenv"`; +do + gpg --batch --detach-sign --passphrase-fd 0 $i < \ + /dev/shm/passphrase.txt +done +shred /dev/shm/passphrase.txt +@end group +@end example + +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. + +Note that signature checking does @strong{not} prevent an attacker +with (serial, physical, ...) console access from dropping manually to +the GRUB console and executing: + +@example +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., GNU 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 @@ -5440,6 +5650,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{Security and signatures} for an example +use case. @end table -- 1.8.4