Re: [PATCH v0] Additional security-relevant documentation

[Andrey Borzenkov]

Oh, I just really meant document new option to load_env. But thank you
for the efforts!

В Fri, 27 Sep 2013 10:00:37 -0700
Jon McCune <address@hidden> пишет:

>  * Security::                    Authentication and authorisation
> +* Security and signatures::     Verifying digital signatures in GRUB

I think it should in subsection. Top level Security which includes
subsections Authentication and authorization (current Security) and
Signature verification. There are possibly more topics in the future
and it will unclutter top level menu.

>  @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}.
>  
>  
> address@hidden check_signatures
> address@hidden check_signatures
> +
> +This variable controls whether GRUB enforces digital signature
> +validation (@pxref{Security and signatures}) on all loaded files.  If
> address@hidden, 

That looks and sounds strange (to me at least) - how would you pronounce
this sentence? "If set to @samp{enforce}" looks enough, it is in
the description of variable so context in unambiguous.  

> address@hidden to load another file @file{foo} (e.g., a loadable
> +module, a configuration file, or a Linux kernel) implicitly invokes
> address@hidden foo foo.sig} (@pxref{verify_detached}).
> address@hidden 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
> address@hidden).  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
> address@hidden (@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}.
> +

I have a feeling that all this does not belong here, but in Signature
verification section.

> +
>  @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

May be it's better start new section Security related commands.
Commands are already indexed, so there is no need to have one long
list. Grouping them by functions makes it easier to browse.

>  
> address@hidden distrust
> address@hidden distrust
> +
> address@hidden Command distrust pubkey_id
> +Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys.

I was not able to do it. It is absolutely unclear which part of
list_trusted output should be used as input to this command. If you
know how it works, please document it with examples.

> +These keys are used to validate signatures when
> address@hidden (@pxref{check_signatures}), and by some
> +invocations of @command{verify_detached} (@pxref{verify_detached}).
> address@hidden and signatures} for more information.
> address@hidden deffn
>  

Is it necessary to repeat the same over and over again in every command
description. Reference to section where they are described seems to be
enough.
>  
> address@hidden list_trusted
> address@hidden list_trusted
> +
> address@hidden Command list_trusted
> +List all public keys trusted by GRUB for validating signatures. 

Please document what is actually output (fingerprint) and how it can be
used in distrust to forget the key.

>                                                                 These
> +public keys are used implicitly when environment variable
> address@hidden (@pxref{check_signatures}), and by some
> +invocations of @command{verify_detached}.  @xref{Security and
> +signatures} for more information.
> address@hidden deffn
>  

repetition?

>  @node load_env
>  @subsection load_env
>  
> address@hidden Command load_env address@hidden file]
> address@hidden Command load_env address@hidden file] address@hidden 
> [whitelisted_variable_name] @dots{}

I think it is better to document long options. They make scripts also
more readable.

> address@hidden trust
> address@hidden trust
> +
> address@hidden 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}.

When @var{check_signatures} is set to @samp{enforce}.

>                                                   Note that if
> address@hidden when this command is run, then
> address@hidden must itself be signed

Really? Code explicitly disables all filters (including signature
verification) and quick test allows me to trust key without having
valid trusted key. I do not know if this is intentional.

>                                           such that an already-loaded
> +public key (@pxref{list_trusted}) can validate that signature.  A
> +public key hierarchy can thus be constructed.
> address@hidden and signatures} for more information.
> address@hidden deffn
> +
>  
>  @node unset
>  @subsection unset
> @@ -4640,6 +4736,25 @@ only on PC BIOS platforms.
>  @end ignore
>  
>  
> address@hidden verify_detached
> address@hidden verify_detached
> +
> address@hidden Command verify_detached file signature_file [pubkey_file]
> +Verifies a GPG-style detached signature, where the signed file is
> address@hidden, and the signature itself is in file @var{signature_file}.
> +Optionally, a specific public key to use can be specified using
> address@hidden  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.

Same. Not tested, but code explicitly disables all filters when reading
all three files.

> address@hidden Security and signatures
> address@hidden 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. 

theme files, font files and whatever else including arguments to hash
checks. Really, "all" means "all", there is no need to explicitly list
what it comprises.

>                                                             This
> +document does @strong{not} cover how to ensure that your platform's
> +firmware (e.g., GNU Coreboot or UEFI Secure Boot) validates
> address@hidden
> +
> +GRUB uses GPG-style detached signatures (meaning that a file
> address@hidden 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:
> +
> address@hidden
> +gpg --gen-key
> address@hidden example
> +

I think path to keyring is needed here to make it obvious you can have
more than one.

> +The corresponding public key must be embedded in @file{core.img} when
> +executing the @command{grub-mkimage} command (typically as part of
> address@hidden, @pxref{Invoking grub-install}) utility.

grub-mkimage is internal implementation detail. It should not be
mentioned here.

>                                                                  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:
> +
> address@hidden
> +# First, wrap grub-mkimage to include your public key(s).
> +cat <<EOF > /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
> address@hidden example
> +

Nor should this example really be included.

> +An individual file can be signed as follows:
> +
> address@hidden
> +gpg --detach-sign /path/to/file
> address@hidden example
> +

Should not you specify path to keyring?

> +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
> address@hidden file, e.g., by running @command{grub-mkconfig}
> +(@pxref{Invoking grub-mkconfig}):
> +
> address@hidden
> address@hidden
> +# 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
> address@hidden group
> address@hidden example
> +

Not sure if this belongs here. Either it has to be integrated in
grub-install and documented there or anyone with minimal shell
programming skills can do it. Nor is this example correct, as it does
not mention theme files, font files, locale files and others.

> +
> address@hidden address@hidden
> +Use @var{program} as @command{grub-mkimage}.  This is primarily useful
> +for advanced users who wish to provide custom arguments to
> address@hidden

For me the main usage is to be able to run grub-install from build
directory without installing it. I do not know if this omitted
intentionally, but this is advanced option not required for normal
usage.