1. TrustedGRUB Quick Installation Guide
1.1 Download from Sourceforge
http://sourceforge.net/projects/trustedgrub
# tar -xzf TrustedGRUB-<ver>.tgz # cd TrustedGRUB-<ver> # ./build_tgrub.sh
Follow the installation instructions printed by the script.
2. Trusted GRUB
2.1 Introduction
This file describes the extensions necessary to transform a standard GRUB into a version that offers TCG support for granting the integrity of the boot process. This is done by measuring all critical components during the boot process, i.e., stage2 of GRUB, the OS kernel or OS modules, together with their parameters. Please note that stage1 has not to be checked here (it wouldn't even be possible), because it has already been measured by the TCG extension itself. Since the TCG extensions are passive, it has no direct ability to check if the bootloader (and the OS kernel/modules) actually is correct, this can only be done indirectly by using the seal/unseal functions of the TCG chip (for details on this topic, you should have a look at the TCG specifications or on other documents describing TCG abilities).
2.2 Authors
The Trusted GRUB extensions have been performed by
Marcel Selhorst <m.selhorst@…>, Sirrix AG security technologies, Bochum
Christian Stueble <c.stueble@…>, Sirrix AG security technologies, Bochum
Oliver Altmeyer <oaltmeyer@…>, Saarland University, Saarbruecken
The Microkernel patch is from Adam Lackorzynski <adam@…>
2.3 Features
- Updated to latest GRUB Release 0.9.7
- Including password dialog support
- Including patches for running L4 microkernels (e.g., fiasco)
- New Software-SHA1-implementation
- Improved checkfile option with software measurements
- TPM Support with TPM detection
- TPM hashing improvements
- New "sha1"-commandline utility
- New "verify_pcr" utility to verify the correctness of GRUB
- New "create_sha1" utility
- NTFS-read support
- Ext4 support
2.4 Measurements (in short)
- PCR 4 contains MBR information and stage1
- PCR 8 contains bootloader information stage2 part1
- PCR 9 contains bootloader information stage2 part2
- PCR 12 contains all commandline arguments from menu.lst and those entered in the shell
- PCR 13 contains all files checked via the checkfile-routine
- PCR 14 contains all files which are actually loaded (e.g., Linux kernel, initrd, modules...)
NOTE: In case you booted via a CD-image, PCR-8 will be empty and PCR-9 will contain the whole measurement of the stage2_eltorito-boot-image.
2.5 Requirements
In order to install the TCG-enhanced TrustedGRUB, you need
- Some Linux tools (patch, aclocal, automake, make, gcc 3.x or gcc 4.x)
- A computer which has TCG enhancements according to TCG specs. v1.1b / v1.2, since SHA1-calculations are extended into PC-Registers of the TPM.
Note: You can use Trusted GRUB without a TPM chip, since the SHA1-calculation is done in software now, you can use all the functions provided by Trusted GRUB (e.g., checkfile...), but you will have no storage for these values and therefore afterwards no possibility to verify the integrity.
2.6 Known Bugs
- On some TPM-Bios implementations, Trusted GRUB does not run if the TPM is disabled in the BIOS. This has occured only on IBM Thinkpad T41p, yet.
- On some HP notebook machines, Trusted GRUB is not able to extend the PCRs of the TPM due to a missing feature "TCG_PASS_THROUGH_TO_TPM" inside the BIOS.
If you find any bugs, please contact the author Marcel Selhorst <m.selhorst@…>
2.7 Installation of TrustedGRUB, general steps
To compile and install TrustedGRUB, please run
# ./build_tgrub.sh
Additional parameters for the build_tgrub-script can be listed with
# ./build_tgrub.sh --help
and as root:
# make install
Furthermore, please make sure, to copy the file "default", which comes with this package, into the directory, where your "menu.lst" is.
NOTE: Please make sure, that no *1_5-files are in your /boot/grub-directory. The only valid files in there are stage1, stage2, default, menu.lst / grub.conf.
2.8 Additional Compile Options
Trusted GRUB has three modes of operations (selectable only before compilation!)
1) Normal mode: simply compile and TrustedGRUB runs silently
2) Debug mode: compiles additional debug information into Trusted GRUB.
3) SHA1 mode: compiles addition runtime SHA1-information into Trusted GRUB. During the boot process, Trusted GRUB will show the measured SHA1-result for every measured file loaded
To select mode 2 or mode 3, edit the file stage2/Makefile.am and look for the line
# tGRUB: add -DDEBUG or -DSHOW_SHA1
STAGE2_CFLAGS = $(INCLUDES)
For mode 2) replace the line with
STAGE2_CFLAGS = $(INCLUDES) -DDEBUG
For mode 3) replace the line with
STAGE2_CFLAGS = $(INCLUDES) -DSHOW_SHA1
Note: Please do not compile -DDEBUG and -DSHOW_SHA1 together, since the resulting output displayed will interfere. You can also use the build-script to specify these parameters.
2.9 Installation of TrustedGRUB, installing the bootloader
# rm /boot/grub/stage* # rm /boot/grub/*1_5 # cp stage1/stage1 /boot/grub # cp stage2/stage2 /boot/grub # ./grub/grub # root (hdX,Y) // Your boot partition # setup (hdX) // Your harddisc where to install Trusted GRUB # quit
If that fails (on some HP notebooks), just use the grub-install-utility under util
# cd util # chmod a+x grub-install # grub-install /dev/hdX
3. New TrustedGRUB Commands
3.1 Password check
GRUB has been extended to ask the user for a password by appending the parameter "--with-password-dialog" to a module. GRUB will then prompt for a password and will replace the original parameter with "password=<yourpassword>". This is needful for some microkernel based projects in order to do pre-boot authentication.
3.2 Checkfile
The syntax of checkfile is as follows:
checkfile (hd?,?)/somewhere/check.file
Pay attention that the drive parameter (hd?,?) and the path are correct, if they are not, TrustedGRUB is not able to boot! The check file itself contains a list of tuples of arbitrary length (but the check file MUST NOT be larger than 8096 Bytes) with a well-defined syntax, as follows:
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
