******************************************************************************
* This version of tboot will not work with Xen versions <3.4 (c/s < 19115)   *
******************************************************************************

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.33.

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

Updates to the mercurial repository are automatically sent to the mailing list
tboot-changelog@lists.sourceforge.net.

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 Building:
-------------------------
o  The trousers sub-project has been removed (it was using an out-of-date
   version and was often problematic to build).  Instead, the trosuers and
   trousers-devel packages must already be installed in order to build the
   lcptools sub-project.  Most distrubtions either provide these packages
   by default or optionally; otherwise they can be found on various package
   sites and manually installed.


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 enable VT-d and
   the TXT code in Linux will force this if it is not specified.  Support is
   now part of the 2.6.32 kernel.

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 vga logging is set, the vga_delay parameter can be used to specify the
   number of seconds to pause after every screenful of output.  It is
   specified as:
       vga_delay=<secs>

   If serial logging is set, the serial port settings can be configured with
   the following parameters:
       serial=<baud>[/<clock_hz>][,<DPS>[,<io-base>[,<irq>[,<serial-bdf>
              [,<bridge-bdf>]]]]]

   The default values for these are:  serial=115200,8n1,0x3f8.

o  Disabling legacy USB SMIs:
   By default, tboot will disable legacy USB SMIs, which allows it to avoid
   wasting memory due to DMA protection.  By disabling SMIs, tboot can DMA
   protect all memory, even the BIOS reserved regions (since even though there
   may be USB buffers in them, no SMIs will be generated).  However, this has
   effect of disabling a USB keyboard until the VMM/kernel starts a USB stack.
   This behavior can be disabled by setting the command line option "no_usb"
   to false (e.g. "no_usb=false").

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 or E820_RESERVED 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'.
