README

******************************************************************************
* 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://hg.code.sf.net/p/tboot/code.

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 verification from the MLE to the kernel/VMM
   and dom0, using policies similar to the LCP called as Verified Launch Policy 
   and also store the policies in TPM NV.
   These policies can be created and managed by the tb_polgen tool and
   provisioned into TPM NV using the lcptools. For more details, see Verified 
   Launched Policy guide in docs/ directory.


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  For Grub, the new tboot module must be added as the 'kernel' in the grub.conf file.
   For Grub2, the new tboot module must be added as the 'multiboot' 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 Modules can be downloaded from this webiste:
   https://software.intel.com/en-us/articles/intel-trusted-execution-technology/
   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 logging levels (note that the default is all);
   any combination of "err", "warn", "info", "detail" can be used:
       loglvl=err,warn,info,detail|all|none

   To achieve a faster S3 resume, suggest to use loglvl=err or loglvl=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  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.

o  tboot provides a better AP wakeup mechanism based on cpu MWAIT feature for
   OS/VMM. This mechanism is defaultly disabled, and could be enabled with
   tboot command line option:
       ap_wake_mwait=true|false

   Once this mechanism is enabled, system will boot faster and will NOT require
   VT to be enabled. But before enabling this option, please make sure the
   OS/VMM has already support it, otherwise system can never boot up. Confirm
   it via finding lines like below in the OS/VMM booting log:
       TBOOT: found shared page at ....
         ...
         flags: 0x0000000x
   
o  tboot support a new PCR usage called Details / Authorities PCR Mapping(DA).
   DA can be enabled by below tboot command line option (note: default is
   legacy):
       pcr_map=da|legacy

   With DA PCR Mapping enabled it separates detailed measurements, stored in
   PCR17, from authorities measurements stored in PCR18.

   "Details" measurements include hashes of all components participating in
   establishing of trusted execution environment and due to very nature of hash
   algorithm change of any component entail change of final PCR17 value.

   "Authorities" measurements include hashes of some unique identifying
   properties of signing authorities such as public signature verification
   keys. This enables authority issue an update of component without affecting
   of final PCR18 value, because updated component is signed in the same way as
   old one.

o  Previously tboot tried to avoid including any reserved e820 region (in 1M
   ~4GB) into PMR low region to avoid possible SMM hang. So all e820 RAM regions
   after the first reserved one(above 1MB) will be discarded.

   It was found that some platforms reserve low memory regions to mitigate some
   hardware issues. Including such kind of reserved e820 regions into PMR low
   region does not cause SMM hang.

   Below tboot command line option can be used to mitigate the cases that large
   amount of RAM(sometime > 3GB) marked as reserved(discarded from OS/VMM usable
   RAM size) by tboot because some reserved e820 regions occurred in very low
   memory(notes: default is 0, means no mitigation for unwanted memory losing):
       min_ram=0xXXXXXXXX

   During 1MB~4GB, only the first RAM region with size less than <min_ram> byte
   and all following RAM regions will be discarded.

   The min_ram option gives a way to do fine-grain tuning on specific platforms. 

   A suggested practical value for min_ram is 32M(0x2000000).

o  Tboot provides support to launch Revocation ACM (RACM) to revoke old buggy
   SINIT version if following command line option is used (default vaule is
   false):
       call_racm=true|false|check

   RACM is also loaded into memory via bootload like grub or syslinux, and is
   launched with getsec[ENTERACCS] instruction. Below is a example GRUB entry
   for RACM launch:

       title RACM Launch
           root (hd0,1)
           kernel /tboot.gz logging=serial,vga,memory call_racm=true
           module /racm.bin

   Tboot will always warm reset platform after RACM was launched & executed.
   Whether RACM launch has succeeded or not could be checked via doing a tboot
   launch with "call_racm=check" right after the warm reset. This tboot launch
   will end with halt right after the RACM launch result was output, and the
   system need manually reset.

o  Tboot support EFI boot via grub2 multiboot2 protocol. 

   In Fedora 18/19, the OS should be installed and booted in EFI mode first,
   then:

       Under tboot code root folder: make; make install

       Copy appropriate SINIT for platform into /boot.

       Run: grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

       Create directory /boot/efi/EFI/fedora/x86_64-efi, and copy
       multiboot2.mod and relocator.mod from /usr/lib/grub/x86_64-efi into it.

       Reboot to choose tboot grub option for TXT launch.

   In Centos 7, the OS should be installed and booted in EFI mode first,
   then:
       Under tboot code root folder: make; make install

       Copy appropriate SINIT for platform into /boot.

       Run: grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg

       Create directory /boot/efi/EFI/centos/x86_64-efi, and copy
       multiboot2.mod and relocator.mod from /usr/lib/grub/x86_64-efi into it.

       If there aren't multiboot2.mod and relocator.mod in directory /usr/lib/grub/x86_64-efi,
       Run: yum install grub2-efi-modules

       Reboot to choose tboot grub option for TXT launch.

   Linux launch works already. Xen for trad BIOS still work and Xen EFI is not
   going to work until we can get a version with Daniel Kiper's multiboot2
   changes in it -- and then we'll need to make some trivial changes to the
   20_xen_tboot file. Grub2 is required for all of this.

o  Tboot support TPM NV measuring via extended Verified Launch Tboot Policy.

   This works only for TPM1.2 by far.

   TPM NV measuring is defaultly disabled, need below cmdline option to enable:
       measure_nv=true

   When NV measuring is enabled, it will get all NV measuring policy entry from
   the tboot policy structure. Every NV policy entry will specify:
       nv_index: TPM NV index to measure and verify
       pcr:      PCR to be extended with the NV measurement
       mod_num:  Tell how to measure the nv
         = TB_POL_MOD_NUM_NV: hash then extend, no size limitation on NV index
         = TB_POL_MOD_NUM_NV_RAW: extend w/o hash, size should equal hash size
       hash_type:
         = any: no verification needed
         = image: need verify per hashs list.
       hashs:    hash list. optional.

   There is one default NV policy entry, which will try to read NV 0x40000010
   and extend it into pcr 22 without hashing.

   The nv_index to be measured must be defined with OWNERWRITE permission,
   otherwise the verification will fail, and nothing will be extended into pcr.

o  Tboot provides support to TPM2 module, and following command line option is
   used to select TPM2 extend policy.
       extpol=agile|embedded|sha1|sha256|sm3|...

   When "agile" policy is selected, ACM will use specific TPM2 commands to compute
   hashes and extend all existing PCR banks at the expense of possible
   performance loss.

   For "embedded" policy, ACM will use algorithms supported by tboot to compute
   hashes and then will use TPM2_PCR_Extend commands to extend them into PCRs.
   If PCRs utilizing hash algorithms not supported by SW are discovered, they
   will be capped with "1" value. This policy when selected will ensure maximum
   possible performance at the expense of possible capping of some of the PCRs.

   Other policy, like "sha1", "sha256", etc., only represent one single algorithm.
   It means tboot will use this algorithm to compute hash and use TPM2_PCR_Extend
   to extend it into PCRs.

o  Recovering from measured launch failures.
   When there's an error during SENTER, the system usually reboots.
   Since the underlying cause is some sort of configuration error, the system can 
   end up in a loop rebooting endlessly after each attempted measured launch. In 
   some environments it make more sense to fall back to booting the kernel directly 
   so that the system comes up and is remotely accessible. After that the issue can 
   be diagnosed and the system power-cycled to clear the error. To enable this 
   behavior, a command line option can be used:
         ignore_prev_err=false|true  // defaults to true

   The option defaults to true, which preserves the original behavior i.e. try a 
   measured launch even if the previous measured launch had errors.
   Setting the value to false will check if the previous measured launch was 
   successful by inspecting the TXT.ERRORCODE value. If measured launch failed,
   tboot will launch the kernel directly without trying to perform a measured launch.

   Note: TXT.ERRORCODE is only cleared if the system is power cycled. A reboot is not
   sufficient to clear the error code.

o  Force TPM2 legacy log format.
   Some SINITs have a bug where they don't extend the MLE hash to the event log.
   This makes it impossible to verify the measurement chain for PCR 17. However,
   if we force them to use the legacy (not TCG standardized) TPM2 log format,
   the SINITs in question log all the inputs to PCR 17 to the event log. This
   setting provides a way to force use of the legacy log format for TPM 2 systems:
           force_tpm2_legacy_log=false|true  // defaults to false

o  Opt-in the vtd dmar table save/restore process
   With recent kernel (4.16.3 in fedora28), the acpi table seems changed by
   kernel. So function restore_vtd_dmar_table() will not work as expected to
   find the vtd dmar table and restore it in S3 resume, instead, the system will
   run into a hang or a reset.

   To solve the S3 issue but still keep vtd dmar table save/restore process for
   specific case, add below option:
       save_vtd=false|true  // defaults to false
 
PCR Usage:
---------
o  Legacy PCR mapping

PCR 17 :
   It will be extended with the following values (in this order):
       -  The values as documented in the MLE Developers Manual
       -  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
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 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
   The default tboot policy will extend, in order, the SHA-1 hashes of all
   modules (other than 0) into PCR 19.

o  Details / Authorities PCR Mapping(DA)

PCR 17 (Details):
   It will be extended with the following values (in this order):
       -  The values as documented in the MLE Developers Manual
       -  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 18 (Authorities):
   It will be extended with the following values (in this order):
      -  The values as documented in the MLE Developers Manual
      -  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
PCR * : tboot policy may specify modules' measurements to be extended into
        PCRs specified in the policy
   The default tboot policy will extend, in order, the SHA-1 hashes of all
   modules (other than 0) into PCR 17.


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 0x1000000 (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. If OS/VMM support tboot's new AP wakeup
   mechanism based on MWAIT, then VT is not required to be enabled.

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


Contributing to the project:
---------------------------

Contributions to any files in this project require the contributor(s) to
certify the following:

    Developer's Certificate of Origin 1.1

    By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or

    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or

    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.

    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.

If the above can be certified by the contributor(s), then he/they should
include a signed-off-by line along with the changes that indicate this:
    Signed-off-by: John Developer <jdev@yoyodyne.org>