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 and OEM systems that are Intel(R) TXT
-capable as well as the Intel(R) TXT Technology Enabling Platform (TEP).
It also supports Intel Software Development Platforms (SDPs) that are
TXT-capable.

This version of tboot only supports the Xen virtual machine monitor.  For which
versions of Xen support tboot, please see Xen's mailing list and source code
repository.


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(R) 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(R) 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(R) 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).  TXT LCP will
   be documented in a separate specification to be released shortly.  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 (available with systems that support TXT) must be added to the
   grub.conf boot config as the last module, e.g.:
       title Xen 3.2 w/ Intel(R) Trusted Execution Technology
           root (hd0,1)
           kernel /tboot.gz
           module /xen.gz vtd=1 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_16.BIN

o  It is optional to include 'vtd=1' on Xen's command line, though omitting it
   has been found to cause dom0 to fail to boot on some systems.  In the
   current version of tboot, if it is set then Xen will not be able to resume
   from S3.  In newer (than 3.2) versions of Xen, this is enabled by default
   and is specified by the 'iommu' command line argument.

o  Progress of the launch process is indicated via debug printk's to
   COM1 (hardcoded).  These appear before the normal "(XEN)" output and are
   prefixed by "TBOOT:".  Though tboot does initialize the COM port, it is
   best if this is also done by GRUB - grub.conf should have:
       serial --speed=115200 --unit=0
       terminal console serial


Interesting Items of Note:
--------------------------
o  A Xen 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 0x1003000 (16MB).

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-test project contains a Linux kernel module that reads some of
   the TXT registers and also verifies the memory protections.  It
   will also display the tboot boot log, in case a system does not have
   serial support.  It also contains a Linux application that will read and
   display some of the TXT registers and state.
