Unofficial mirror of https://sourceforge.net/p/tboot
License
tklengyel/tboot
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
****************************************************************************** * 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 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>
Releases
No releases published
Packages 0
No packages published