******************************************************************************
* This version of tboot will not work with Xen versions <3.4 (c/s < 19115)   *
* or the below-referenced Linux patches                                      *
******************************************************************************

Trusted Boot (tboot) is an open source, pre- kernel/VMM module that uses
Intel(R) Trusted Execution Technology (Intel(R) TXT) to perform a measured
and verified launch of an OS kernel/VMM.

This version of tboot supports Intel (both retail and Software Development
Platforms (SDPs)) and OEM systems that are Intel TXT-capable.

This version of tboot only supports both the Xen virtual machine monitor
(versions >= 3.4) and Linux kernel versions >= 2.6.20.

The mercurial source code repository for this project is located at:
http://www.bughost.org/repos.hg/tboot.hg.


Overview of Tboot Functionality:
--------------------------------
o  Measured Launch.  If the processor is detected as being TXT-capable
   and enabled then the code will attempt to perform a measured launch.  If
   the measured launch process fails (processor is not capable, TXT is not
   enabled, missing SINIT, corrupted data, etc.)) then it will fall-through
   to a non-TXT boot.

o  Teardown of measured environment.  When the system is shutdown, the
   measured environment will be torn down properly.  This support S3/S4/S5
   sleep states.

o  Reset data protection.  Intel TXT hardware prevents access to secrets
   if the system is reset without clearing them from memory (as part of a
   TXT teardown).  This code will support this by setting the flag indicating
   that memory should be so protected during the measured launch and clearing
   the flag just before teardown.

o  Protection of TXT memory ranges.  Intel TXT reserves certain regions of
   RAM for its use and also defines several MMIO regions.  These regions
   (excluding the TXT public configuration space) are protected from use by
   any domains (including dom0).

o  Intel TXT Launch Control Policy (LCP) tools.  The lcptools project
   contains a set of tools (and basic documentation) that can be used to
   create and provision TXT Launch Control policies.  LCP uses TPM
   non-volatile storage (TPM NV) to hold a launch policy, which the SINIT AC
   module reads and uses to enforce which measured launched environments
   (MLEs) (e.g. tboot) can be launched (based on a SHA-1 hash).  These
   tools require a TPM Software Stack (TSS) that supports the Tspi_NV_* API.
   Versions of the TrouSerS project >0.3.0 support them.

o  Verified Launch.  Tboot will extend verifcation from the MLE to the VMM
   and dom0, using policies similar to the LCP and also stored in TPM NV.
   These policies can be created and managed by the tb_polgen tool and
   provisioned into TPM NV using the lcptools.


Instructions for Use:
---------------------
o  The new tboot module must be added as the 'kernel' in the grub.conf file.
   The existing 'kernel' entry should follow as a 'module'.  The SINIT AC
   module must be added to the grub.conf boot config as the last module, e.g.:
       title Xen w/ Intel(R) Trusted Execution Technology
           root (hd0,1)
           kernel /tboot.gz logging=serial,vga,memory
           module /xen.gz iommu=required dom0_mem=524288 com1=115200,8n1
           module /vmlinuz-2.6.18-xen root=/dev/VolGroup00/LogVol00 ro
           module /initrd-2.6.18-xen.img
           module /Q35_SINIT_17.BIN

o  The appropriate SINIT AC Module can be downloaded from the tboot SourceForge
   project site.  The current version of tboot (both in the repository and
   .tar.gz) requires version 17 or greater of the SINIT AC module.  It will
   not work with some previous SINIT ACMs nor will it work on the TEP.

o  For Xen:  newer versions of Xen support the 'iommu=required' command line
   option, which causes Xen to fail to run if there is any error in
   programming the VT-d engines.  This is the most secure configuration.
   Older versions of Xen used the param 'vtd=1' or 'iommu=1', which enables
   VT-d but does not fail if it cannot be enabled.

o  For Linux:  the 'intel_iommu=on' command line option will enabled VT-d.
   There is currently no way to force its use, but this will be added later.
   The Linux kernel patches can be found on the LKML archives at:
       http://lkml.org/lkml/2009/3/31/22
       http://lkml.org/lkml/2009/3/31/23
       http://lkml.org/lkml/2009/3/31/24

o  Progress of the launch process is indicated via debug printk's using three
   different logging methods:
       serial - logging is traced over a COM/serial port to a remote console
       vga    - logging is traced to the local screen
       memory - logging is traced to a memory location
   
   These three methods are not mutually exclusive - any combination can be
   enabled. Logging is enabled with command line parameters to tboot. The first
   parameter enables or disables all logging (note that the default is all):
       loglvl=all|none
   
   The next parameter is used to configure the various logging targets; any 
   combination can be used (note that when the parameter is not set, serial 
   is the default):
       logging=vga,serial,memory
   
   If serial logging is set, a third parameter can be used to configure the
   serial port settings. All of the options beyond baud rate are optional:
       serial=baud[/clock_hz][,DPS[,io_base]]
   
   The clock_hz allows setting different crystal frequencies, DPS sets the
   data/parity/stop bits, and io_base sets the IO port for the device. The
   baud rate can also be set to "auto" allowing any current settings for the
   serial port to be left intact (e.g. if the serial port has already been
   configured by grub). If this parameter is omitted the default is 
   effectively the following for a legacy PC COM1:
       serial=115200/115200,8n1,0x3f8

o  tboot will attempt to seal the module measurements using the TPM so that if
   it is put into S3 it can restore the correct PCR values on resume.  In order
   for this to work, the TPM must be owned and the SRK auth must be set to all
   0s.  This can be done using the '-z' flag to tpm_takeownership.  If the
   tboot policy being used is 'nonfatal' and the seal operation fails, tboot
   will continue the boot.  However, for 'continue' or 'halt' policy types,
   tboot will halt the boot.


PCR Usage:
---------
PCR 17 : as documented in the MLE Developers Manual
PCR 18 :
   It will be extended with the following values (in this order):
       -  SHA-1 hash of tboot (as calculated by lcp_mlehash)
       -  SHA-1 hash of:  tboot policy control value (4 bytes) |
                          SHA-1 hash of tboot policy (20 bytes)
          : where the hash of the tboot policy will be 0s if
            TB_POLCTL_EXTEND_PCR17 is clear
       -  SHA-1 hash of first module in grub.conf (e.g. Xen or Linux kernel)
PCR * : tboot policy may specify modules' measurements to be extended into
        PCRs specified in the policy


Interesting Items of Note:
--------------------------
o  A Xen or Linux version that does not support tboot can still be launched by
   tboot, however it will not protect any of the TXT memory nor tboot itself.
   And it will hang on reboot/shutdown.  Aside from this, it will behave
   normally.

o  Tboot will copy and alter the e820 table provided by GRUB to "reserve"
   its own memory plus the TXT memory regions.  These are marked as
   E820_UNUSABLE so that the patched Xen code can prevent them from
   being assigned to dom0.  The e820 table is not altered if the measured
   launch fails for any reason.

o  Tboot is always built 32bit and runs in protected mode without PAE or
   paging enabled.  Tboot loads and executes at 0x803000 (8MB).

o  The code requires that VT be enabled as well as TXT.  This is because
   the mechanism for bringing up the APs uses VMX to create a mini-VM in
   order to trap on INIT-SIPI-SIPI.

o  The tools/txt-stat project is a Linux application that reads some of
   the TXT registers and will display the tboot boot log if tboot was run
   with 'logging=memory'.
