readme.tgrub

一个可以引导多个操作系统的启动程序

   fedb1cff009e115f7f5f7b4533667a787798832d (hd0,1)/test1.file
   485214eab2de87284de9d4e323e428bf60e0aa77 (hd0,1)/grub-0.92.tar.bz2
   a6e171e989849dd44735a513c4270a0837c09174 (hd0,1)/test2.file
The first component is a 40 byte alphanumeric value, which marks the SHA1 hash
value of the succeeding file (the value can be created by either "sha1sum" under
Linux or the program create_sha1, which comes with this distribution), followed
by a single white space character.
The second component has to be the absolute path (together with the
drive reference) of the file corresponding to the hash value, followed by a
new line character ('\n').
Please make sure that the syntax of your check file is absolutely correct (do
NOT forget the newline character at the end of the last entry), otherwise
TrustedGRUB is not able to boot.
The integrity of all files listed in this check file is checked when your
system is booted by comparing the referenced hash values to newly computed
ones. If some of the values do not match, a warning is displayed, leaving you
the choice of either continue booting a maybe contaminated system or stopping
the boot process.
All files, which are checked via the checkfile-option are extended into PCR 13.

=== 3.3 sha1 ===

The syntax of sha1 is as follows:

    sha1 (hd?,?)/somewhere/hash/my/file

This command line utility simply measures the SHA1 hash of the given file and prints
the result.

== 4. New TrustedGRUB Utilities==

=== 4.1 util/create_sha1 ===

Together with the TrustedGRUB files, the archive that you have downloaded contains a
file called create_sha1.c. It will be compiled and stored in grub-0.97/util.
The task of this program is to support the usage of TrustedGRUB's checkfile option,
by creating a SHA1 hash value whose format is the same as the function
load_checkfile (within the file boot.c) uses.
In order to use this program, you should execute it with

 Usage: ./util/create_sha1 {filename}

The resulting hash value is displayed on the screen, copy this string (together
with the complete file name) to your check file (as described before).
'''Note:''' Since we perform regular SHA1 here, you can also use the Linux tool
"sha1sum" for this calculation

=== 4.2 util/verify_pcr ===

The "verify_pcr"-tool is intended to check, if a PCR register is extended correctly
with the given files. For example, if you have a checkfile containing 5 entries,
all the files are hashed and extended into PCR 13. The corresponding value of PCR13
can be verified with this utility. Execute the command with the following parameters:

 Usage: ./util/verify_pcr  <pcr initial value {NULL | 20 byte hex}> {filenames-1 ... filenames-n}

 Example: All files which are actually loaded are hashed and extended into PCR 14.

If you boot your Linux, this PCR would contain the Linux kernel (and probably initrd-files).
In order to check if the result is correct, use:

 # ./util/verify_pcr NULL /boot/vmlinuz
 *******************************************************************************
 * Result for PCR: d0 df 5b 82 c2 a8 1a ac 17 0e ff 80 fa 79 fb d2 f2 3e 17 01 *
 *******************************************************************************

which will display the value, which has to be in your PCR. You can then check the
according value with

 # cat /sys/class/misc/tpm0/device/pcrs | grep PCR-14
 PCR-14: D0 DF 5B 82 C2 A8 1A AC 17 0E FF 80 FA 79 FB D2 F2 3E 17 01

'''Note:''' Be sure to give the correct order of your files as they are listed in your menu.lst.
Otherwise the result will not be correct.


Update:
-------
The Verification of the commandline-parameters (as loaded through the menu.lst)
as well as those entered via the bash-like command console are measured into PCR 12.
Since GRUB parses those commands and replaces tabs into 2 spaces, make sure to append
those changes to your references as well in order to come up with the same hash value.
It is planned to write a utility, which will perform the exact GRUB parsing and to
calculate the resulting hash in the PCR for you in near future.

== 5. General Information ==

=== 5.1 General view on how TrustedGRUB works ===

The goal of TrustedGRUB is to install a chain of trust, i.e., every component
measures the integrity of the succeeding component. Concretely, this looks like
the following ("<-" means "is checked by"):
   BIOS integrity        <-  TCG extension
   GRUB stage1           <-  TCG extension
   start of GRUB stage2  <-  GRUB stage1
   rest of GRUB stage2   <-  file start.S as part of GRUB stage2
   OS kernel (modules)   <-  file boot.c as part of GRUB stage2
This chain of trust can be extended by making GRUB stage2 able to measure the
integrity of arbitrary files. This is done by a newly added command named
checkfile which can either be used within the file menu.lst or via the GRUB
interface during the boot process.


=== 5.2 Additional memory in use ===

TrustedGRUB needs some extra memory space compared to GRUB, because it has to create
a segment for TCG (within files stage1.S, start.S and asm.S). Within the file
asm.S, this segment is also used to store data which have to be transmitted
when switching between protected and real mode.
The (additional) memory regions in use are
   (stage1.S) 0x80000 - 0x800?? ... TCG segment
   (start.S)  0x80000 - 0x800?? ... TCG segment
   (asm.S)    0x80000 - 0x8F0?? ... TCG segment and data storage


=== 5.3 Modifications in stage1.S ===

Stage1 has the task to check the integrity of stage2. Because it only loads
the first sector of stage2, it is only able to check this small piece of
code.
In order to perform this task, stage1 is extended in a way that it uses
two functions provided by the TCG chip:

  1.) The code of (the first sector) of stage2 is hashed with a SHA-1
      algorithm. The starting address of the code is 0x8000, its length is
      512 bytes.
  2.) The resulting hash value is written to PCR (Platform Configuration
      Register) 8. More precisely, the former content of this register (which
      actually is 0) is concatenated to the new value, then hashed with SHA1
      and finally written again to PCR 8.
Due to the PC architecture, the size of the boot sector (where stage1 is
located) is limited to 512 bytes. But the original stage1 is already very
close to this limit, leaving very few space for the TCG extensions. Because
of this, it was necessary (in the current version of TrustedGRUB) to eliminate the CHS-
code. This results in the problem that we support only LBA-discs now.


=== 5.4 Modifications in start.S ===

start.S contains the code for the first sector of GRUB's stage2. Its only task
is to load of stage2. Therefore, the TCG extension now has to measure the
rest of stage2.
The changes here are widely the same as in stage1, with the differences that
the entry point for the code which has to be checked is a address 0x8200 and
that the result is written into PCR 9.

=== 5.5 Modifications in start_eltorito.S ===

When booting TrustedGRUB from a CD-ROM, the bootloader is not splitted into
several stages. Instead, there exists one large file "stage2_eltorito" containing 
both stages of TrustedGRUB. 
In order to measure TrustedGRUB, start_eltorito.S has
been extended in a way, that it measures the whole stage2_eltorito-image and
extends the result into PCR 9.

'''Note:''' When booting from CD, the content of PCR 8 is empty, since the whole
bootloader is measured at once into PCR 9.

=== 5.6 Other modifications ===

All modifications have been commented with
    /* BEGIN TCG EXTENSION */
              ...
    /* END TCG EXTENSION */

Mainly, in "stage2/disc_io.c" the functions grub_open, grub_read and grub_close have been
extended to do the SHA1-measurement during the loadage of files. In detail:

    grub_open  --> sha1_init
    grub_read  --> sha1_update
    grub_close --> sha1_finish

The SHA1-functions are placed in a separate file stage2/sha1.c.
Furthermore, the file "boot.c" contains the new features "calculate_sha1", "update_pcr"
and all loading parts have been modified to correctly load the files and calculate
the corresponding SHA1-value.

"stage2/cmdline.c" contains the new measurements of all commandline-parameters

"stage2/builtins.c" contains the new command line utilities "checkfile" and "sha1"

"stage2/stage2.c" has been extended to check for a TPM and to activate the SHA1-measurements

"stage2/asm.S" contains the Assembler-routines needed for communication with the TPM

"stage2/Makefile.am" had to be modified, since we had to add our sha1-function for compiling

=== 5.7 File list ===

The following list presents the files that have been modified to add TCG
support to GRUB. For details on the modifications see sections below.

  - grub-0.97/stage1/stage1.S
  - grub-0.97/stage1/tgrub.h
  - grub-0.97/stage2/asm.S
  - grub-0.97/stage2/boot.c
  - grub-0.97/stage2/builtins.c
  - grub-0.97/stage2/char_io.c
  - grub-0.97/stage2/cmdline.c
  - grub-0.97/stage2/common.c
  - grub-0.97/stage2/disk_io.c
  - grub-0.97/stage2/Makefile.am
  - grub-0.97/stage2/sha1.c
  - grub-0.97/stage2/shared.h
  - grub-0.97/stage2/stage2.c
  - grub-0.97/stage2/start.S
  - grub-0.97/stage2/start_eltorito.S
  - grub-0.97/grub/asmstub.c
  - grub-0.97/util/create_sha1.c
  - grub-0.97/util/verify_pcr.c
  - grub-0.97/util/sha1.c