├── CONTRIBUTING.md ├── LICENSE.md ├── QUICKSTART.md ├── README.md ├── blueprints ├── AMD_Grub_Late_Launch.md ├── AMD_Landing_Zone.md ├── AMD_coreboot_DRTM_payload.md ├── Linux_Late_Launch.md ├── Measured_Secure_Boot.md ├── README.md └── TXT_Grub_Late_Launch.md ├── documentation ├── Architecture.md ├── CI_infrastracture.md ├── CI_jobs.md ├── DevelopersGuide.md ├── FAQ.md ├── Glossary.md ├── Late_Launch_Overview.md ├── README.md ├── UseCases.md ├── gitlab_CI.md ├── gitlab_runner.md └── images │ ├── Arch_Flow.png │ ├── Arch_Flow.xml │ ├── Architectural_Flow.png │ ├── Architectural_Flow.xml │ ├── SoftwareArch.png │ ├── SoftwareArch.xml │ └── registered_local_runner.png ├── presentations ├── PSEC-2018.pdf └── README.md ├── references ├── AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf ├── README.md ├── intel-txt-preliminary-architecture.pdf └── intel-txt-software-development-guide.pdf ├── roadmap └── Roadmap.pdf ├── specifications └── secure-launch-specification.rst └── steering-committee └── Community-Meeting-June17-2021.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to TrenchBoot 2 | 3 | We love your input! We want to make contributing to this project as easy and 4 | transparent as possible, whether it's: 5 | 6 | - Reporting a bug 7 | - Discussing the current state of the code 8 | - Submitting a fix 9 | - Proposing new features 10 | - Becoming a maintainer 11 | 12 | ## Project Structure 13 | 14 | The functionality being developed under TrenchBoot are cross-cutting 15 | capabilities that span multiple open source projects. The role of TrenchBoot 16 | is to function as both a development as well as a cross-project integration 17 | project. As such it maintains a set of repository clones of upstream 18 | project(s) that TrenchBoot conducts development within. 19 | 20 | ### Upstream Repository 21 | 22 | For each upstream repoository within TrenchBoot will have at least one maintainer. 23 | The maintainer(s) will have merge permissions and responsible for maintaining 24 | adherence to upstream practices. When necessary, they are responsible for 25 | maintaining out-of-tree capabilities developed by TrenchBoot. 26 | 27 | #### Upstream Focus 28 | 29 | One of the primary objectives for TrenchBoot is to deliver interoperable launch 30 | integrity capabilities to existing open source projects involved with the 31 | system boot cycle. Under this objective, all development against an upstream 32 | project must comply with upstream coding style and strive to minimize 33 | disruption/breakage of upstream capabilities. 34 | 35 | #### Out of Tree Maintenance 36 | 37 | There may be a case that a TrenchBoot capability may encounter a slow adoption 38 | by an upstream project which results in multiple upstream releases without the 39 | capability merged. As such the capability in question must be kept in sync with 40 | upstream changes. While this situation is not desired, it is likely to occur 41 | and will be the responsibility of the respective TrenchBoot maintainer(s). 42 | 43 | ### TrenchBoot Original Repositories 44 | 45 | While the focus is on delivering capabilities into upstream projects, it is 46 | possible that a new or derivative code base may result to fulfill a role in a 47 | cross-cutting capability. The maintainer(s) for these code bases will be 48 | responsible for establishing coding styles and licensing that ensure compliance 49 | with all other TrenchBoot relevant projects. 50 | 51 | ## Development 52 | 53 | We use github to host the project, to include tracking issues and feature 54 | requests, as well as accept pull requests. 55 | 56 | ### Development Flow Overview 57 | 58 | Pull requests are the best way to propose changes to the project (we use 59 | [Github Flow](https://guides.github.com/introduction/flow/index.html)). We 60 | actively welcome your pull requests: 61 | 62 | 1. Fork the repo and create your branch from `master`. 63 | 2. If you've added code that should be tested, add tests. 64 | 3. If you've changed APIs, update the documentation. 65 | 4. Ensure the test suite passes. 66 | 5. Make sure your code lints. 67 | 6. Issue that pull request! 68 | 69 | ### Contribution Licensing 70 | 71 | TrenchBoot is a cross-community integration project consisting of project 72 | repositories along with upstream project repositories. All contributions to a 73 | repository are made under the license that covers all work in that repository. 74 | 75 | ### Issue Tracking 76 | 77 | Report issues, e.g. bugs, feature requests, etc., using Github's 78 | [issues](https://github.com/briandk/transcriptase-atom/issues) 79 | 80 | **Great Issues** tend to have: 81 | 82 | - A quick summary and/or background 83 | - For bug reports include: 84 | - Steps to reproduce for bugs 85 | - Be specific! 86 | - Give sample code if you can. 87 | - What you expected would happen 88 | - What actually happens 89 | - Notes (possibly including why you think this might be happening, or stuff 90 | you tried that didn't work) 91 | - For feature requests include: 92 | - An outline of how the feature would work 93 | - Any dependecies the feature would require 94 | - The benefit the feature will provide 95 | 96 | ### Coding Style 97 | 98 | Markdown documents should be formatted to 80 columns to the extent possible. 99 | Exception to the 80 column is when column limitation breaks markdown rendering. 100 | 101 | Contributions targeting upstream project repositories will follow the upstream 102 | project's coding style rules. 103 | 104 | ## License 105 | [![License: CC BY 4.0](https://i.creativecommons.org/l/by/4.0/88x31.png) 106 | ](https://creativecommons.org/licenses/by/4.0/) This work is licensed under a 107 | [Creative Commons Attribution 4.0 International 108 | License](ttp://creativecommons.org/licenses/by/4.0/). By contributing you 109 | agree that your contributions will be licensed under the Creative Commons 110 | Attribution 4.0 International License. Feel free to contact the maintainers if 111 | that's a concern. 112 | 113 | ## Contacting Maintainers 114 | 115 | TrenchBoot is maintained by: 116 | - Daniel P. Smith 117 | 118 | # References 119 | This document was adapted from the this open-source [contribution 120 | template](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62/) 121 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | ## creative commons 2 | 3 | # Attribution 4.0 International 4 | 5 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. 6 | 7 | ### Using Creative Commons Public Licenses 8 | 9 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. 10 | 11 | * __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). 12 | 13 | * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). 14 | 15 | ## Creative Commons Attribution 4.0 International Public License 16 | 17 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 18 | 19 | ### Section 1 – Definitions. 20 | 21 | a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 22 | 23 | b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 24 | 25 | c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 26 | 27 | d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 28 | 29 | e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 30 | 31 | f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 32 | 33 | g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 34 | 35 | h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. 36 | 37 | i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 38 | 39 | j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 40 | 41 | k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 42 | 43 | ### Section 2 – Scope. 44 | 45 | a. ___License grant.___ 46 | 47 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 48 | 49 | A. reproduce and Share the Licensed Material, in whole or in part; and 50 | 51 | B. produce, reproduce, and Share Adapted Material. 52 | 53 | 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 54 | 55 | 3. __Term.__ The term of this Public License is specified in Section 6(a). 56 | 57 | 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 58 | 59 | 5. __Downstream recipients.__ 60 | 61 | A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 62 | 63 | B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 64 | 65 | 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 66 | 67 | b. ___Other rights.___ 68 | 69 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 70 | 71 | 2. Patent and trademark rights are not licensed under this Public License. 72 | 73 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 74 | 75 | ### Section 3 – License Conditions. 76 | 77 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 78 | 79 | a. ___Attribution.___ 80 | 81 | 1. If You Share the Licensed Material (including in modified form), You must: 82 | 83 | A. retain the following if it is supplied by the Licensor with the Licensed Material: 84 | 85 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 86 | 87 | ii. a copyright notice; 88 | 89 | iii. a notice that refers to this Public License; 90 | 91 | iv. a notice that refers to the disclaimer of warranties; 92 | 93 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 94 | 95 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 96 | 97 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 98 | 99 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 100 | 101 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 102 | 103 | 4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License. 104 | 105 | ### Section 4 – Sui Generis Database Rights. 106 | 107 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 108 | 109 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 110 | 111 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and 112 | 113 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 114 | 115 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 116 | 117 | ### Section 5 – Disclaimer of Warranties and Limitation of Liability. 118 | 119 | a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ 120 | 121 | b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ 122 | 123 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 124 | 125 | ### Section 6 – Term and Termination. 126 | 127 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 128 | 129 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 130 | 131 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 132 | 133 | 2. upon express reinstatement by the Licensor. 134 | 135 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 136 | 137 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 138 | 139 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 140 | 141 | ### Section 7 – Other Terms and Conditions. 142 | 143 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 144 | 145 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. 146 | 147 | ### Section 8 – Interpretation. 148 | 149 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 150 | 151 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 152 | 153 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 154 | 155 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 156 | 157 | > Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. 158 | > 159 | > Creative Commons may be contacted at creativecommons.org 160 | -------------------------------------------------------------------------------- /QUICKSTART.md: -------------------------------------------------------------------------------- 1 | # Quick Start Guide 2 | 3 | A quick start guide to getting a Linux system running with the latest Secure 4 | Launch bits from TrenchBoot. Note that this is a bare bones document meant to help 5 | someone get up and running with Secure Launch. It does not contain detailed 6 | descriptions of all the technologies and terminology involved in doing a 7 | Secure Launch. The repository this document resides in as well as the 8 | Linux Secure Launch documentation submitted with the Linux patch sets 9 | (under Documentation/security/launch-integrity/) contain a plethora of other 10 | resources and information that can be used to understand the Secure Launch 11 | technology more broadly. 12 | 13 | For topics not addressed by this document, please contact TrenchBoot developers 14 | via the community site: 15 | 16 | - [Community](https://trenchboot.org/community) 17 | 18 | ## Platforms 19 | 20 | The current patchset (version 11) only supports Intel TXT. AMD SKINIT support 21 | is in the works and coming soon. 22 | 23 | An Intel system (desktop, server, laptop) needs to be a vPro SKU in order to 24 | have TXT support available. Generally speaking, vPro systems will advertise this 25 | with a sticker somewhere on the unit. Intel TXT support usually needs to be 26 | enabled in the firmware setup program. It depends on both the TPM and VTd being 27 | enabled. The details on how to do this are system specific. To see if the CPU 28 | supports TXT, run the following (SMX (Safe Mode Extensions) indicates the CPU 29 | does support TXT): 30 | 31 | `# grep smx /proc/cpuinfo` 32 | 33 | Also note, the TrenchBoot project has a hardware test matrix though only the 34 | Intel systems are relevant at present: 35 | 36 | - [Test Matrix](https://trenchboot.org/documentation/test_matrix/) 37 | 38 | ## Linux 39 | 40 | TrenchBoot is an active open-source project for system launch integrity, from 41 | which the Secure Launch feature is being upstreamed to the Linux kernel. 42 | 43 | The following repository and branch have the latest release of the Secure 44 | Launch feature. This is a vanilla Linux kernel based off a torvalds/master branch 45 | snapshot at the time time patch set was assembled. The patches could be 46 | applied to different distros of Linux, probably requiring some rebasing: 47 | 48 | - [Latest Linux Patch Set Version 11](https://github.com/TrenchBoot/linux/tree/linux-sl-master-9-12-24-v11) 49 | 50 | The Secure Launch feature is enabled through a Kconfig setting and can 51 | be found here using e.g. `make menuconfig`: 52 | 53 | `"Processor type and features" -> "[ ] Secure Launch support"` 54 | 55 | The Linux Secure Launch in-tree documentation mentioned in the first section 56 | contains other instructions on properly configuring a Secure Launch kernel. 57 | 58 | ## GRUB 59 | 60 | Each recent release of the Linux patches is accompanied by a GRUB branch 61 | in TrenchBoot that works with the specified version. The branch for version 62 | 9 can be found here: 63 | 64 | - [GRUB for Version 11](https://github.com/TrenchBoot/grub/tree/grub-sl-2.12-v11) 65 | 66 | This version of GRUB is based off of upstream GRUB 2.12 with the patches to 67 | support the Secure Launch feature. The folloing is a basic set of instructions 68 | for bulding a standalone version of UEFI GRUB on this branch: 69 | 70 | ``` 71 | $ cd 72 | $ ./bootstrap 73 | $ mkdir build 74 | $ cd build 75 | $ ../configure --with-platform=efi --target=x86_64 76 | $ make 77 | $ ./grub-mkimage -O x86_64-efi -o grubx64.efi -p /EFI/redhat -d grub-core all_video boot btrfs cat chain configfile echo efifwsetup efinet ext2 fat font gfxmenu gfxterm gzio halt hfsplus iso9660 jpeg loadenv loopback lvm mdraid09 mdraid1x minicmd normal part_apple part_msdos part_gpt password_pbkdf2 png reboot regexp search search_fs_uuid search_fs_file search_label serial sleep syslinuxcfg test tftp video xfs backtrace http linux usb usbserial_common usbserial_pl2303 usbserial_ftdi usbserial_usbdebug keylayouts at_keyboard multiboot2 78 | ``` 79 | 80 | The final command will produce the UEFI GRUB image `grubx64.efi` needed. 81 | 82 | ## Configuration 83 | 84 | There is a new GRUB command that instructs GRUB to initiate a Secure Launch called 85 | `slaunch`. This is an example of a GRUB menuentry that would be used to do a Secure 86 | Launch of the Linux kernel: 87 | 88 | ``` 89 | menuentry 'Linux with Secure Launch 6.11.0-rc7-master-v11' --unrestricted { 90 | load_video 91 | insmod gzio 92 | insmod part_gpt 93 | insmod xfs 94 | if [ x$feature_platform_search_hint = xy ]; then 95 | search --no-floppy --fs-uuid --set=root bba24662-776e-4396-9b1e-9ee5606d79b8 96 | else 97 | search --no-floppy --fs-uuid --set=root bba24662-776e-4396-9b1e-9ee5606d79b8 98 | fi 99 | slaunch 100 | linux /vmlinuz-6.11.0-rc7-master-v11 root=/dev/mapper/root ro crashkernel=auto resume=/dev/mapper/swap rd.lvm.lv=my/root rd.lvm.lv=my/swap rhgb console=ttyS0,115200n8 console=tty0 LANG=en_US.UTF-8 101 | initrd /initrd-6.11.0-rc7-master-v11.img 102 | slaunch_module /txt-sinit-for-given-platform 103 | } 104 | ``` 105 | 106 | Note this example contains the optional `slaunch_module` command that tells GRUB to load an 107 | external SINIT ACM for this configuration. In general, server platforms contain an existing 108 | SINIT ACM in the firmware and this line is not needed. For client platforms, an external one 109 | is required to be supplied. The SINIT ACM for a given platform can be acquired from Intel: 110 | 111 | - [Intel SINIT ACM information](https://www.intel.com/content/www/us/en/developer/articles/tool/intel-trusted-execution-technology.html) 112 | 113 | ## Validation 114 | 115 | There are a number of ways to validate that a successful Secure Launch was done. Using serial 116 | logging or `dmesg`, search for the string "TXT" after booting: 117 | 118 | ``` 119 | [root@my-system ~]# dmesg | grep TXT 120 | [ 0.000094] slaunch: Intel TXT setup complete 121 | [ 2.617782] slaunch: TXT AP startup vector address updated 122 | ``` 123 | 124 | That indicates a successful Secure Launch boot. Another way is to display the Secure Launch 125 | TPM event log. This can be done as follows after booting (note only the tail end of the log 126 | is shown here for brevity, the rest is snippped): 127 | 128 | ``` 129 | [root@my-system ~]# cat /sys/kernel/security/slaunch/eventlog | hexdump -C 130 | ... 131 | [snip] 132 | ... 133 | 00000490 a3 e2 de 6b fb 1f 79 ef c9 5e de bf ef bf 92 fb |...k..y..^......| 134 | 000004a0 fc b2 89 ea 64 c1 d7 d2 99 fb 49 e6 12 00 00 00 |....d.....I.....| 135 | 000004b0 4d 65 61 73 75 72 65 64 20 53 4c 52 20 54 61 62 |Measured SLR Tab| 136 | 000004c0 6c 65 12 00 00 00 02 05 00 00 01 00 00 00 0b 00 |le..............| 137 | 000004d0 cd 64 bf e1 70 96 4c ce 53 2f 2f 7a 85 85 fe f0 |.d..p.L.S//z....| 138 | 000004e0 05 22 40 f6 62 18 bf 94 2a 2f 3d 14 b1 25 60 31 |."@.b...*/=..%`1| 139 | 000004f0 18 00 00 00 4d 65 61 73 75 72 65 64 20 62 6f 6f |....Measured boo| 140 | 00000500 74 20 70 61 72 61 6d 65 74 65 72 73 11 00 00 00 |t parameters....| 141 | 00000510 02 05 00 00 01 00 00 00 0b 00 18 7d 80 8f 2c ca |...........}..,.| 142 | 00000520 03 bf a7 54 ff 1d 16 6d 49 51 25 f6 bc ec 46 dc |...T...mIQ%...F.| 143 | 00000530 23 a7 39 a8 db 96 28 8e d4 1d 16 00 00 00 4d 65 |#.9...(.......Me| 144 | 00000540 61 73 75 72 65 64 20 4b 65 72 6e 65 6c 20 69 6e |asured Kernel in| 145 | 00000550 69 74 72 64 12 00 00 00 02 05 00 00 01 00 00 00 |itrd............| 146 | 00000560 0b 00 11 02 09 6f c6 1d 78 11 87 1a 93 49 10 2f |.....o..x....I./| 147 | 00000570 14 69 dd 45 b8 c3 03 e7 e6 80 6e 21 9b 87 47 90 |.i.E......n!..G.| 148 | 00000580 d6 27 1c 00 00 00 4d 65 61 73 75 72 65 64 20 4b |.'....Measured K| 149 | 00000590 65 72 6e 65 6c 20 63 6f 6d 6d 61 6e 64 20 6c 69 |ernel command li| 150 | 000005a0 6e 65 12 00 00 00 02 05 00 00 01 00 00 00 0b 00 |ne..............| 151 | 000005b0 b2 29 3f 3c da 25 4a 78 61 be 76 91 3e 06 f9 5d |.)?<.%Jxa.v.>..]| 152 | 000005c0 7d 6b 0d 75 6b 30 74 0c 26 b2 76 96 1e 60 19 a5 |}k.uk0t.&.v..`..| 153 | 000005d0 18 00 00 00 4d 65 61 73 75 72 65 64 20 55 45 46 |....Measured UEF| 154 | 000005e0 49 20 6d 65 6d 6f 72 79 20 6d 61 70 11 00 00 00 |I memory map....| 155 | 000005f0 04 05 00 00 01 00 00 00 0b 00 00 00 00 00 00 00 |................| 156 | 00000600 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 157 | * 158 | 00008000 159 | ``` 160 | The final measurements starting with the description "Measured..." are put in the 161 | log by the Secure Launch kernel code after successfully running. During a poweroff, 162 | restart or a kexec of another kernel, the following log lines will show TXT being 163 | properly disabled and SMX mode being exited.: 164 | 165 | ``` 166 | [ 696.907094] slaunch: TXT clear secrets bit and unlock memory complete. 167 | [ 696.914827] slaunch: TXT SEXIT complete. 168 | ``` 169 | 170 | ## Troubleshooting 171 | 172 | Covering all the possible reasons why a Secure Launch might fail is beyond the scope 173 | of this document. If problems are encountered, the first thing to check is the firmware 174 | setting on the system: 175 | 176 | - Is the TPM enabled? 177 | - Are VTx and VTd enabled? 178 | - Is TXT enabled? 179 | 180 | The next thing to check depending on the failure mode is the serial log or `dmesg` for 181 | any errors traced out that might indicate what went wrong. 182 | 183 | TXT also provides a sticky error register that will contain any previous error coming 184 | from TXT or the Secure Launch kernel. If there was an error, the TXT error register can 185 | be read using a GRUB command from within a GRUB shell on reboot. Drop into a GRUB shell 186 | by typing `c` at the GRUB menu and run: 187 | 188 | ``` 189 | grub> slaunch 190 | grub> slaunch_state 191 | Secure launcher: Intel TXT 192 | TXT.STS: 0x0000000000004092 193 | SENTER.DONE.STS: 0 194 | SEXIT.DONE.STS: 1 195 | MEM-CONFIGLOCK.STS: 0 196 | PRIVATEOPEN.STS: 1 197 | TXT.LOCALITY1.OPEN.STS: 0 198 | TXT.LOCALITY2.OPEN.STS: 0 199 | TXT.ESTS: 0x00 200 | TXT_RESET.STS: 0 201 | TXT.E2STS: 0x0000000000000000 202 | SECRETS.STS: 0 203 | TXT.ERRORCODE: 0x00000000 204 | TXT.DIDVID: 0x00000001b0078086 205 | VID: 0x8086 206 | DID: 0xb007 207 | RID: 0x0001 208 | ID-EXT: 0x0000 209 | TXT.VER.FSBIF: 0xffffffff 210 | TXT.VER.QPIIF: 0x9d003000 211 | DEBUG.FUSE: 1 212 | TXT.SINIT.BASE: 0x77ec0000 213 | ``` 214 | 215 | This shows a number of the TXT register values including `TXT.ERRORCODE` which is the 216 | one of interest. In this case the error is `0x0000000` meaning there was no previous 217 | error. An error of the form `0xc0008XXX` is coming from the Secure Launch kernel code. 218 | The errors are detailed in the Linux documentation and listed in the main header file: 219 | 220 | - [SL Error Codes](https://github.com/TrenchBoot/linux/blob/linux-sl-master-9-12-24-v11/include/linux/slaunch.h#L108) 221 | 222 | Errors coming from other sources like the CPU or the SINIT ACM have different forms. 223 | Consult the TXT documentation from Intel to determine what the error means. 224 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | ``` 3 | _____ _ ____ _ 4 | |_ _| __ ___ _ __ ___| |__ | __ ) ___ ___ | |_ 5 | | || '__/ _ \ '_ \ / __| '_ \| _ \ / _ \ / _ \| __| 6 | | || | | __/ | | | (__| | | | |_) | (_) | (_) | |_ 7 | |_||_| \___|_| |_|\___|_| |_|____/ \___/ \___/ \__| 8 | 9 | ``` 10 | 11 | TrenchBoot is a framework that allows individuals and projects to build 12 | security engines to perform launch integrity actions for their systems. The 13 | framework builds upon Boot Integrity Technologies (BITs) that establish one or 14 | more Roots of Trust (RoT) from which a degree of confidence that integrity 15 | actions were not subverted is derived. 16 | 17 | 18 | ## Where to Start: 19 | 20 | * [General Architecture](documentation/Architecture.md) - A top level overview of TrenchBoot 21 | * [Use Case Definition](documentation/UseCases.md) - A collection of example use cases 22 | * [Developers Guide](documentation/DevelopersGuide.md) - A developers guide that explains the internals of TrenchBoot 23 | 24 | -------------------------------------------------------------------------------- /blueprints/AMD_Grub_Late_Launch.md: -------------------------------------------------------------------------------- 1 | AMD Grub Late Launcher 2 | ====================== 3 | 4 | ## Purpose 5 | 6 | The intent of this project is to extend Grub with the ability to call the AMD 7 | SKINIT instruction. 8 | 9 | ## Background 10 | 11 | The AMD SKINIT instruction is a means to initiate a "late launch" that 12 | establishes a Dynamic Root of Trust Measurement (DRTM). The instruction call 13 | requires the system to be in a specific state as enumerated below, 14 | * SVM check, either the `EFER.SVME` bit is set to 1 or the feature flag `CPUID 15 | Fn8000_0001_ECX[SKINIT]` is set to 1 16 | * The CPU must be in protected mode 17 | * All microcode needs to be unloaded 18 | 19 | ## Approach 20 | 21 | Grub will be extended with the following capabilities, 22 | * An SKINIT relocator that will, 23 | 1. set protected mode 24 | 2. enable APIC 25 | 3. verify no machine check in progress 26 | 4. clear machine check regs 27 | 5. SKINIT as final instruction 28 | * A late launch loader that will, 29 | 1. load kernel starting at 0x100000, compatibility with a Linux Secure Loader 30 | 2. verify SVM is supported 31 | 3. disable all TPM localities 32 | 4. evict microcode 33 | 5. send INIT IPI to all APs 34 | -------------------------------------------------------------------------------- /blueprints/AMD_Landing_Zone.md: -------------------------------------------------------------------------------- 1 | AMD Landing Zone 2 | ================ 3 | 4 | ## Purpose 5 | 6 | The intent of this project is to implement the earliest code that is launched by 7 | a DL Event on AMD platforms. 8 | 9 | ## Background 10 | 11 | Contrary to the TXT solution, SKINIT is a single CPU instruction after which the 12 | execution is passed to the user-provided block of code, called Secure Loader in 13 | AMD documents. To some extent, this code can be treated as the AMD equivalent of 14 | ACM, except that it doesn't have to be signed by the CPU vendor. 15 | 16 | SKINIT extends PCR17 with the hash of SL, which size is specified in the SL 17 | header (maximum of 64K - 1), protects SLB (Secure Launch Block, always 64K) 18 | against DMA access from the devices, puts the CPU in defined execution state and 19 | jumps to the entry point also specified in the header. At the entry point to the 20 | SL the CPU works in flat 32-bit protected mode with paging disabled. Most 21 | general purpose registers are cleared. Interrupts are disabled (held pending 22 | until re-enabled), including NMI, SMI and INIT. Refer to [AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) 23 | for more details. 24 | 25 | Landing Zone is an implementation of Secure Loader. 26 | 27 | ## Approach 28 | 29 | This is a high-level overview of tasks performed by Landing Zone: 30 | 1. set GDT and segment registers (only CS and SS are valid after SKINIT) 31 | 2. enable Long Mode (optional) 32 | 3. initialize TPM interface 33 | 4. initialize TPM event log 34 | * log what was done by SKINIT 35 | 5. extend PCR18 with the hash of data passed by the bootloader to the LZ 36 | * log that event 37 | 6. obtain information about the kernel from the data provided by a bootloader, 38 | most notably: 39 | * kernel location 40 | * kernel size 41 | * entry point 42 | 7. extend PCR17 with the hash of the kernel 43 | * log that event 44 | 8. set CPU registers according to the kernel boot protocol 45 | 9. jump to the entry point of kernel 46 | 47 | ### Things that yet have to be implemented 48 | 49 | #### DMA protection must be extended to cover any additional code and data 50 | 51 | This includes mainly kernel and zero page. As of now, it is impossible to do 52 | this securely. 53 | 54 | [AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) 55 | states that it should be done with DEV (Device Exclusion Vector), but that is no 56 | longer implemented on new CPUs, except for initial SLB protection (starting with 57 | Family 17h, even that protection is handled differently). 58 | 59 | DEV was surpassed by the [IOMMU](https://www.amd.com/system/files/TechDocs/48882_IOMMU_3.05_PUB.pdf). 60 | It is much more capable than DEV, but it also requires more data and code to set 61 | up. Those are not atomic operations, data must be first written to memory by the 62 | CPU, then CPU sends information to the IOMMU that it can parse that data, and 63 | only then the IOMMU actually reads that memory. A rogue device could potentially 64 | modify that data in the meantime, so it all should happen in the protected part 65 | of the memory. 66 | 67 | The issue is that IOMMU is also treated as a device, so it cannot access the 68 | memory protected by the DEV (or what's left of it). There are two possible 69 | options, both of which result in window of opportunity for unauthorized change 70 | of the memory: 71 | * turn off the SLB protection before sending commands to the IOMMU 72 | * build IOMMU structures outside of SLB 73 | 74 | The second approach requires also that the space for those structures is 75 | reserved and that LZ knows about its location. 76 | 77 | ## Build options 78 | 79 | There are 3 configurable options, specified as command line parameters for 80 | `make`. All of them are disabled by default, they can be enabled by running 81 | `make =y`, where `` is one of the flags listed below. Note that 82 | between builds with different sets of options you **must** run `make clean`. 83 | 84 | * **LTO** - link time optimizations. Generally reduces the size of resulting 85 | binary and execution time, but the exact difference is hard to predict. 86 | * **32** - do not jump to 64b mode. Saves 7*4 KB by not producing paging tables, 87 | and some additional space because of shorter GDT and less strict padding. 88 | * **DEBUG** - enable debug output on serial port (0x3f8). Increases the size by 89 | about 1.3 KB. 90 | -------------------------------------------------------------------------------- /blueprints/AMD_coreboot_DRTM_payload.md: -------------------------------------------------------------------------------- 1 | # PoC: coreboot with payload started through DRTM (AMD) 2 | 3 | This proof of concept shows how TrenchBoot can be used to start coreboot 4 | payload. One of use cases may be to root chain of trust in hardware on platforms 5 | that don't support SRTM, or require proprietary tools and/or documentation that 6 | isn't publicly available. 7 | 8 | PC Engines apu2 platform is used in this PoC. Software stack consists of: 9 | 10 | - coreboot, 11 | - SKL, 12 | - Tianocore edk2 payload. 13 | 14 | ## Modifications done to support this PoC 15 | 16 | ### coreboot 17 | 18 | - Build system now includes SKL 19 | - Added under `payloads` directory, perhaps this is not a proper place for it 20 | - Enabled through `Chipset/Launch DRTM payload before the real one` in config, 21 | available only for enabled platforms (depends on `CPU_AMD_PI`) 22 | - Enabled SMMSTORE 23 | - 256KB of append only storage for UEFI authenticated variables 24 | - IOMMU is always enabled if DRTM payload is used 25 | - Enforced on mainboard level due to specific implementation of runtime 26 | configuration options 27 | - Loading and creating boot information tags for SKL 28 | - Code is built only for `CPU_AMD_PI` - CPU family 16h 29 | - Probably could be make to work on other AMD platforms with minimal changes 30 | 31 | ### SKL 32 | 33 | - Support for simple payload - just base, size, entry point and argument: 34 | 35 | ```c 36 | struct skl_tag_boot_simple_payload { 37 | struct skl_tag_hdr hdr; 38 | u32 base; 39 | u32 size; 40 | u32 entry; 41 | u32 arg; 42 | } __packed; 43 | ``` 44 | 45 | ### Tianocore 46 | 47 | - SKINIT driver - discover if SKINIT was used, set GIF in that case 48 | - Performed early in DXE because other drivers (including SMMSTORE 49 | initialization) require enabled interrupts 50 | - IOMMU driver - enable DMA access for devices that require and request it 51 | - Heavily used by drivers to access storage (USB, AHCI) 52 | - Uses `EDKII_IOMMU_PROTOCOL` 53 | - Many simplifications done, e.g. no differentiation between read and write 54 | permissions, no proper unmapping of device page tables, every invalidation 55 | uses `INVALIDATE_IOMMU_ALL` when smaller, targeted flushing would suffice 56 | 57 | ## TODOs 58 | 59 | - (coreboot) information about DRTM TPM log location isn't passed to SKL 60 | - (coreboot) SKL hash(es) aren't passed to SKL 61 | - (SKL?) SMM is not measured 62 | - (UEFI) APs are not started securely (i.e. without INIT) yet 63 | - (UEFI) Tables exposed by coreboot (ACPI, SMBIOS) are not measured 64 | - (UEFI) Polishing of IOMMU driver 65 | 66 | ## Building 67 | 68 | Clone coreboot repository, checkout appropriate branch and clone submodules: 69 | 70 | ```shell 71 | $ git clone https://github.com/pcengines/coreboot.git 72 | $ cd coreboot 73 | $ git checkout drtm_payload 74 | $ git submodule update --init --checkout 75 | ``` 76 | 77 | Build using `coreboot-sdk` container: 78 | 79 | ```shell 80 | $ docker run --rm -it -v $PWD:/home/coreboot/coreboot \ 81 | -w /home/coreboot/coreboot -e USER_ID=$USER_ID -e GROUP_ID=$GROUP_ID \ 82 | coreboot/coreboot-sdk:0ad5fbd48d /bin/bash 83 | $ cp configs/config.pcengines_apu2_drtm_payload .config 84 | $ make olddefconfig 85 | $ make 86 | ``` 87 | 88 | This should produce `build/coreboot.rom` that is to be flashed into apu2. Make 89 | sure you have a way of recovering through external flashing. 90 | 91 | Note that first boot takes few seconds to initialize SMMSTORE area, for release 92 | builds this results in pause after `skl_main() is about to exit`, before any 93 | output from UEFI appears. Do not be alarmed by this. 94 | 95 | ## Issues 96 | 97 | - (UEFI) Support for AuthenticatedVariables is not discovered 98 | - (UEFI) TPM driver returns error 99 | -------------------------------------------------------------------------------- /blueprints/Linux_Late_Launch.md: -------------------------------------------------------------------------------- 1 | Linux Late Launch Kernel 2 | ======================== 3 | 4 | ## Summary 5 | 6 | The Linux kernel will be extended to make it function as the late launch kernel 7 | for both AMD (Secure Loader) and Intel TXT (Measured Launch Environment). 8 | 9 | ## Background 10 | 11 | The late launch process provides a means to measure a target execution 12 | environment and then jump into the environment as presribed by the CPU's late 13 | launch protocol. This process provides a means by which to a establish a 14 | hardware-based Root of Trust for Measurement (RTM). The implementation here 15 | will provide a means to launch the Linux kernel as an RTM envrionment to enable 16 | building trust in a platform's launch. 17 | 18 | ## Approach 19 | 20 | A preliminary approach is as follows, 21 | * Create a late-launch landing zone (LZ) in 64k real code section of Linux 22 | kernel header 23 | * Sanitize any CPU state passed through late launch 24 | * Verify LZ signature with pubkey 25 | * Verify measurement from LZ signature against CRTM 26 | * (AMD) Create/Setup TPM Event log 27 | * Extend hash of pubkey into PCR 18, record in event log 28 | * This aligns to TXT's DA scheme 29 | * Parse Linux header to detect relevant details about kernel 30 | * DEV/DMAR protect remainder of Linux kernel 31 | * Extend hash of Linux kernel into PCR 17, record in event log 32 | * Prepare and then handoff to Linux kernel proper 33 | * Need to support Legacy/CSM and UEFI environments 34 | * Add a new start/launch path to Linux kernel 35 | * Secure rendezvous APUs 36 | * Process system state passed up from LZ 37 | * e.g. memory map, etc. 38 | * Setup Linux state for handover to mainline start up 39 | * Jump into mainline start up 40 | -------------------------------------------------------------------------------- /blueprints/Measured_Secure_Boot.md: -------------------------------------------------------------------------------- 1 | Measured Secure Boot 2 | ==================== 3 | 4 | ## Purpose 5 | 6 | To build a Measured Secure Boot (MSB) implementation that uses a hardware based 7 | Root of Trust for Measurement (RTM) from which to build a Root of Trust for 8 | Verification (RTV). 9 | 10 | ## Background 11 | 12 | To date the only supported Late Launch environment is the tboot project which 13 | is maintained by Intel for their Intel TXT capability. While tboot provides a 14 | complete capability, it is limited and has a number of deficiencies. While it 15 | would be possible to build a Measured Secure Boot solution around tboot, it 16 | will still be limited in comparison to approach provided by this blueprint. 17 | 18 | Before detailing the approach and the improvements it provides, it is good to 19 | understand how the tboot environment works. Before tboot can run, it must be 20 | loaded into memory along with the target kernel it will launch into by either a 21 | legacy multiboot compliant bootloader or by an UEFI boot manager. Tboot itself 22 | is composed of two main parts, pre-launch and post-launch execution paths. Below 23 | is a top-level execution flow for tboot from boot loader/manager to the trusted 24 | kernel that will be given control. 25 | 26 | ``` 27 | |-- tboot --| 28 | boot ldr/mngr --load--> pre-launch --SENTER--> post-launch --launch--> trusted kernel 29 | ``` 30 | 31 | In terms of integrity policy, tboot policy can only be used to measure and 32 | verify any multiboot modules loaded by the boot loader/manager. Typically tboot 33 | policy is used in one of two manners, enforcing and non-enforcing. In both 34 | cases the policy is used to control what tboot will measure and which PCRs 35 | those measurements are stored. When an enforcing policy is in place, the 36 | measurements are compared with values populated in the policy and will take 37 | a selected action when the measurements do not match. With a non-enforcing 38 | policy, measurement comparison is not done and it is left to the trusted 39 | kernel to take action on the measurements. This means if advanced actions other 40 | than measurement verification is desired, then the trusted kernel must be aware 41 | and made to take the actions. 42 | 43 | ## Approach 44 | 45 | The x86 Late Launch capability will be used to establish an RTM using a Dynamic 46 | Root of Trust Measurement (DRTM) that will include the device owner's RSA 47 | public key. The Late Launch will start a TrenchBoot Security Engine (TSE) that 48 | is capable of simple measurement verification similar to tboot, but will be 49 | able to do advance actions such as a KMIP attestation for device encryption 50 | key. 51 | 52 | MSB will consist of an enhancement to the GNU GRUB bootloader (grub), an 53 | extended Linux kernel, and the uroot initramfs environment. The enhancement to 54 | grub will be to add TPM 1.2/2.0 support along with relocators for AMD and Intel 55 | Late Launch instructions. The Linux kernel will be extend to function as a 56 | post-launch kernel that will run the TSE. Details for each of these are 57 | documented in their own respective blueprints. Finally, below is the execution 58 | flow for MSB for comparison with tboot's execution flow above. 59 | ``` 60 | grub --SENTER/SKINIT--> Linux/TSE --kexec--> trusted kernel 61 | ``` 62 | -------------------------------------------------------------------------------- /blueprints/README.md: -------------------------------------------------------------------------------- 1 | Blueprints 2 | ========== 3 | 4 | Here you will find the design artifacts for built, in progress, and planned 5 | security engine components. 6 | -------------------------------------------------------------------------------- /blueprints/TXT_Grub_Late_Launch.md: -------------------------------------------------------------------------------- 1 | TXT Grub Late Launcher 2 | ====================== 3 | 4 | ## Purpose 5 | 6 | The intent of this project is to extend Grub with the ability to call the Intel 7 | SENTER instruction. 8 | 9 | ## Background 10 | 11 | The Intel SENTER instruction is a means to initiate a "late launch" that 12 | establishes a Dynamic Root of Trust Measuremnt (DRTM). The instruction call 13 | requires the system to be in a specific state as enumerated below, 14 | 15 | ## Approach 16 | 17 | Grub will be extended with the following capabilities, 18 | * An SENTER relocator that will, 19 | 1. set protected mode 20 | 2. enable cache 21 | 3. enable native FPU error reporting 22 | 4. ensure not in virtual-8086 mode 23 | 5. verify no machine check in progress 24 | 6. parse GETSEC[PARAMETERS] 25 | 7. clear machine check regs 26 | 5. senter as final instruction 27 | * Extend the late launch loader, 28 | 1. Determine CPU type and select SKINIT or SENTER path 29 | 1. load ACM and verify it matches platform 30 | 2. verify SENTER is supported 31 | 3. build pagetable for MLE 32 | -------------------------------------------------------------------------------- /documentation/Architecture.md: -------------------------------------------------------------------------------- 1 | 2 | General Architecture 3 | ==================== 4 | 5 | The general execution flow for TrenchBoot is broken into three phases, 6 | Bootstrap, Intermediate, and Runtime. The Bootstrap phase primarily consists of 7 | the existing bootstrap technology, e.g. UEFI, grub, UEFI shim, etc. For 8 | TrenchBoot the bootstrap technologies that have an integrity function, referred 9 | to as a Boot Integrity Technology (BIT), are of primary interest. The 10 | Intermediate phase is that which the TrenchBoot Loader executes to establish 11 | the launch integrity of the system. The last phase is the Runtime phase and is 12 | where the target runtime, hypervisor, operating system, etc, is 13 | given control over the system. 14 | 15 | ![Architecture Execution Flow](images/Architectural_Flow.png) 16 | 17 | 18 | # TrenchBoot Security Engine 19 | 20 | At the heart of the TrenchBoot Loader is the TrenchBoot Security Engine. The 21 | Security Engine is responsible for processing any evidence collected by the 22 | BITs, collecting new evidence as needed, evaluating all evidence according to 23 | a security policy, and executing appropriate enforcement actions. The components 24 | that enable this and their relationship can be seen in the top level diagram 25 | below. 26 | 27 | ![Architecture Execution Flow](images/Arch_Flow.png) 28 | 29 | ## Evidence 30 | 31 | A core concept in TrenchBoot is that of evidence. For TrenchBoot, evidence is a 32 | record of an event that occurred within the system. The typical form for these 33 | records is a cryptographic hash of the system state that was the result of this 34 | event. This cryptographic hash is often referred to as a measurement. 35 | 36 | ## Boot Integrity Technology 37 | 38 | Boot Integrity Technologies (BITs) are software or hardware capabilities that are 39 | responsible for a portion of system launch. Specifically these capabilities 40 | attempt to establish and/or enforce a degree of integrity that the correct 41 | logic was used to launch the system. 42 | 43 | ## BIT Augmentation 44 | 45 | There may be BITs that need be directly or indirectly extended to 46 | enable or enhance their usage for launching a TrenchBoot environment. 47 | 48 | ## BIT Ingestion 49 | 50 | A TrenchBoot Security Engine must be capable of supporting a variety of evidence 51 | formats for the various BITs supported. Translation of these various formats allows 52 | TrenchBoot to maintain normalized data structures for evidence collected. This 53 | allows the functionality in Security Processor to only have to reason about 54 | normalized data without specialized logic for different data formats. 55 | 56 | ## Security Processor 57 | 58 | At the heart of a TrenchBoot Security Engine is the Security Processor. The 59 | Security Processor consist of the logical components that will consume a launch 60 | policy and take one or more actions to evaluate the state of the system 61 | necessary to enforce the policy. This may include, but is not limited to, collecting 62 | additional evidence, making attestation assertions, retrieving encryption keys, 63 | and file/block/drive decryption. The enforcement of the security policy will 64 | result in a full, partial, or failed boot of the system. 65 | 66 | ## Launch/Hand Off 67 | 68 | Ultimately TrenchBoot's responsibility is to launch a target environment. As 69 | such it must be equipped with the various ways required to launch those target 70 | environments. 71 | -------------------------------------------------------------------------------- /documentation/CI_infrastracture.md: -------------------------------------------------------------------------------- 1 | TrenchBoot CI infrastructure 2 | ============================ 3 | 4 | Pipelines 5 | --- 6 | 7 | ### Upstream 8 | 9 | * [nixos-trenchboot-configs](https://gitlab.com/trenchboot1/3mdeb/nixos-trenchboot-configs/-/pipelines) 10 | * [landing-zone](https://gitlab.com/trenchboot1/trenchboot/landing-zone/-/pipelines) 11 | * [grub-tb](https://gitlab.com/trenchboot1/trenchboot/grub/-/pipelines) 12 | * [linux-tb](https://gitlab.com/trenchboot1/trenchboot/linux/-/pipelines) 13 | * [meta-trenchboot](https://gitlab.com/trenchboot1/3mdeb/meta-trenchboot/-/pipelines) 14 | 15 | ### Development 16 | 17 | * [landing-zone](https://gitlab.com/trenchboot1/3mdeb/landing-zone/-/pipelines) 18 | * [grub-tb](https://gitlab.com/trenchboot1/3mdeb/grub/-/pipelines) 19 | * [linux-tb](https://gitlab.com/trenchboot1/3mdeb/linux/-/pipelines) 20 | 21 | --- 22 | 23 | Job descriptions 24 | --- 25 | 26 | * [nixos-trenchboot-configs](CI_jobs.md#nixos-trenchboot-configs) 27 | * [landing-zone](CI_jobs.md#landing-zone) 28 | * [grub-tb](CI_jobs.md#grub-tb) 29 | * [linux-tb](CI_jobs.md#linux-tb) 30 | * [meta-trenchboot](CI_jobs.md#meta-trenchboot) 31 | -------------------------------------------------------------------------------- /documentation/CI_jobs.md: -------------------------------------------------------------------------------- 1 | # Jobs description 2 | 3 | ## landing-zone 4 | 5 | ### build_debug_disabled 6 | 7 | Job builds landing-zone with disabled debug option. 8 | 9 | ### build_debug_enabled 10 | 11 | Job builds landing-zone with enabled debug option. 12 | 13 | ### build_nixpgs_debug_disabled 14 | 15 | Job triggers building landing-zone NixOS package with disabled debug option. 16 | 17 | ### build_nixpkgs_debug_enabled 18 | 19 | Job triggers building landing-zone NixOS package with enabled debug option. 20 | 21 | --- 22 | 23 | ## grub-tb 24 | 25 | ### build_and_install 26 | 27 | Job builds TrenchBoot version of the GRUB. Then installs the GRUB in the docker 28 | and checks if required modules are available. 29 | 30 | ### build_nixpkg 31 | 32 | Job triggers building the GRUB package for the NixOS. 33 | 34 | --- 35 | 36 | ## linux-tb 37 | 38 | ### build 39 | 40 | Job builds linux kernel with the secure launch driver. 41 | 42 | ### build_nixpkg 43 | 44 | Job triggers building the NixOS package of the TrenchBoot linux kernel. 45 | 46 | --- 47 | 48 | ## nixos-trenchboot-configs 49 | 50 | ### build_lz_debug_disabled_local 51 | 52 | Job builds NixOS landing-zone package with disabled debug option. 53 | 54 | ### build_lz_debug_enabled_local 55 | 56 | Job builds NixOS landing-zone package with enabled debug option. 57 | 58 | ### build_grub 59 | 60 | Job builds NixOS package of the TrenchBoot GRUB. 61 | 62 | ### build_linux 63 | 64 | Job builds NixOS package of the TrenchBoot linux kernel. 65 | 66 | --- 67 | 68 | ## meta-trenchboot 69 | 70 | ### build 71 | 72 | Job builds legacy Yocto TrenchBoot for the PC Engines apu2. 73 | 74 | ### build_uefi 75 | 76 | Job builds UEFI Yocto TrenchBoot image for generic x86-64 hardware. 77 | 78 | ### test_boot_apu2 79 | 80 | Job installs the legacy Yocto TrenchBoot image on the the PC Engines apu2. 81 | Then boot the platform without and with DRTM. In the end the job verifies, 82 | if PCR values correspond to manually extended. 83 | 84 | ### test_boot_asrock 85 | 86 | Job installs the UEFI Yocto TrenchBoot image on the the ASRock-R1000V. 87 | Then boot the platform without and with DRTM. In the end the job verifies, 88 | if PCR values correspond to manually extended. 89 | 90 | ### test_boot_supermicro 91 | 92 | Job installs the UEFI Yocto TrenchBoot image on the Supermicro M11SDV-8CT-LN4F. 93 | Then boot the platform without and with DRTM. In the end the job verifies, 94 | if PCR values correspond to manually extended. 95 | 96 | --- 97 | 98 | ## Test infrastructure 99 | 100 | * [PC Engines apu2](https://www.pcengines.ch/apu2.htm) 101 | * [ASRock-R1000V](https://www.asrockind.com/en-gb/4X4%20BOX-R1000V) 102 | * [Supermicro M11SDV-8CT-LN4F](https://www.supermicro.com/en/products/motherboard/M11SDV-8CT-LN4F) 103 | -------------------------------------------------------------------------------- /documentation/DevelopersGuide.md: -------------------------------------------------------------------------------- 1 | Developers Guide 2 | ================ 3 | 4 | TrenchBoot is a framework that provides for users the ability to select the 5 | kernel and security engine components appropriate for their target environment. 6 | This developers guide focuses on the software components of TrenchBoot and the 7 | build system used to compose TrenchBoot launchable images. 8 | 9 | ## TrenchBoot Linux/u-root Configuration 10 | 11 | A TrenchBoot launchable image consists of a TrenchBoot Linux kernel with a 12 | TrenchBoot u-root initramfs embedded within the image. When building for a target, 13 | the boot capabilities and BITs that will be supported will result in different 14 | launchable images. The diagram below provides a simple visual depiction of this 15 | setup. 16 | 17 | ![Top level software architecture](images/SoftwareArch.png) 18 | 19 | As a result of the build process, one or more kernel images may be generated. 20 | By convention these kernels will be labeled as such: 21 | 22 | * bzImage.uefi: An image built to be launch by a UEFI environment 23 | * bzImage.skinit: An image built to be launched with AMD's SKINIT instruction 24 | * bzImage.senter: An image built to be launched with Intel's SENTER instruction 25 | * bzImage.bios: An image build to be launched by a legacy BIOS boot loader 26 | -------------------------------------------------------------------------------- /documentation/FAQ.md: -------------------------------------------------------------------------------- 1 | TrenchBoot FAQ 2 | ============== 3 | 4 | 1. [Why does TrenchBoot use an intermediate 5 | launcher?](#1-why-does-trenchboot-use-an-intermediate-launcher) 6 | 2. [What are the benefits of measurement over signature 7 | validation?](#2-what-are-the-benefits-of-measurement-over-signature-validation) 8 | 3. [What do I need to incorporate TrenchBoot into my 9 | system?](#3-what-do-i-need-to-incorporate-trenchboot-into-my-system) 10 | 4. [Where do I start if I want to help with 11 | contributions?](#4-where-do-i-start-if-i-want-to-help-with-contributions) 12 | 13 | 14 | ## 1. Why does TrenchBoot use an intermediate launcher? 15 | 16 | For Linux systems doing both verified(secure) and measured boot, there is an 17 | intermediary that handles the security enforcement. For verified boot it is the 18 | UEFI shim loader and for measured boot it is tboot. TrenchBoot replaces these 19 | intermediary loaders with a common Linux-based loader that provides a rich 20 | security processing framework. One role that TrenchBoot does not fulfill is 21 | that the UEFI shim also serves as a trust delegation point that transitions 22 | from Microsoft Authority to Distribution/Installer/No Authority. The response 23 | why this is not of concern will be addressed in Question 2. 24 | 25 | 26 | ## 2. What are the benefits of measurement over signature validation? 27 | 28 | It is important to understand that one solution is not necessarily more 29 | beneficial over the other. Measurement and Verification each have their merits 30 | and it is important to understand the environment and requirements of the 31 | solution. In the case of verification, it provides a one-time strong assertion 32 | to origination and correctness that relies on Authorities and Control which 33 | becomes brittle when dealing with delegating control. For example when 34 | verification is being used as the Root of Trust that the transitive trust 35 | builds upon, these solutions are strongest when the ecosystem is closed and 36 | under control of a core entity. Where as measurement provides for establishing 37 | a strong assertion to correctness that can be repeatedly extended and verified. 38 | It therefore relies on the ability to know what correct is and to securely 39 | verify measurement with expected correctness. 40 | 41 | 42 | ## 3. What do I need to incorporate TrenchBoot into my system? 43 | 44 | TrenchBoot is a framework that allows you to build a Linux kernel with a 45 | tailored, embedded initramfs that functions as an intermediate loader to launch 46 | your system. You will need to use the build system to select the security 47 | engine components you desire, provide any necessary configurations, and build 48 | an instance of the loader. After that, you configure your system boot to launch 49 | the loader. 50 | 51 | 52 | ## 4. Where do I start if I want to help with contributions? 53 | 54 | The [TrenchBoot 55 | Blueprints](/blueprints) 56 | are how feature requests are collected for the project. Check if there is a 57 | blueprint that is of interested, if not, submit a blueprint via a pull request 58 | for a feature you would like to see implemented. 59 | -------------------------------------------------------------------------------- /documentation/Glossary.md: -------------------------------------------------------------------------------- 1 | Glossary 2 | ======== 3 | 4 | Provided are definitions of terms used throughout TrenchBoot's documents and 5 | designs to encourage a common vocabulary and understanding. 6 | 7 | # Table of Contents 8 | 9 | * [Dynamic Launch](#dynamic-launch) 10 | * [Explicit Trust](#explicit-trust) 11 | * [Implicit Trust](#implicit-trust) 12 | * [Root of Trust](#root-of-trust) 13 | * [Static Launch](#static-launch) 14 | * [Transitive Trust](#transitive-trust) 15 | * [Trust](#trust) 16 | * [Trust Anchor](#trust-anchor) 17 | * [Trust Boundary](#trust-boundary) 18 | * [Trustee](#trustee) 19 | * [Trustor](#trustor) 20 | 21 |
22 | 23 | #### Dynamic Launch: 24 | A system launch that can be done repeatedly with the execution code able to 25 | reside at different locations in memory. This is sometimes referred to as a 26 | "Late Launch". 27 | 28 | #### Explicit Trust: 29 | When a trustor has explicitly established a degree of trust with a trustee. 30 | 31 | #### Implicit Trust: 32 | When a trustor has relied upon a trustee to establish a degree of trust with 33 | another trustee. 34 | 35 | #### Root of Trust: 36 | An idempotent mechanism whereby the result is used to assert a fact about the 37 | entity it acted upon. 38 | 39 | #### Static Launch: 40 | A system launch that is a one time execution with the execution code at a fixed 41 | location in memory. 42 | 43 | #### Transitive Trust: 44 | An operation conducted by a trustor that consists of one or more mechanisms 45 | used to assess one or more facts about a trustee before allowing the trustee to 46 | be included within the trustor's trust boundary and delegated the authority to 47 | act as a trustor. 48 | 49 | #### Trust: 50 | Assured reliance on the properties, ability, strength, or truth of an entity. 51 | 52 | #### Trust Anchor: 53 | The result of a Root of Trust mechanism that is a fact being relied upon to assert 54 | correctness, e.g. trustworthiness. 55 | 56 | #### Trust Boundary: 57 | A demarcation that identifies a subset of entities as those that a trustor has 58 | explicitly or implicitly established as trustworthy. 59 | 60 | #### Trustee: 61 | An entity that is trusted by another entity. 62 | 63 | #### Trustor: 64 | An entity that establishes a degree of trust of another entity. 65 | 66 | -------------------------------------------------------------------------------- /documentation/Late_Launch_Overview.md: -------------------------------------------------------------------------------- 1 | Introduction to Late Launch 2 | =========================== 3 | 4 | This is an introduction of the "Late Launch" process on x86-based systems to 5 | establish a Dynamic Root of Trust for Measurement (DRTM). Late Launch is 6 | another name for a Dynamic Launch of a system for x86-based platforms. As such 7 | it is good to understand the difference between a Static Launch and a Dynamic 8 | Launch on x86 platforms. For x86 the fixed location used for a Static Launch 9 | is known as the reset vector which maps to SPI flash storage. A Dynamic Launch 10 | is achieved with a light-weight processor bootstrap initiated through a CPU 11 | instruction. For Intel the capability that provides this is called TXT and is 12 | initiated with the GETSEC[SENTER], summarily SENTER, instruction. For AMD it is considered part 13 | of AMD's secure virtualization (AMD-V) and is initiated with the SKINIT 14 | instruction. 15 | 16 | An important function of x86 Late Launch CPU instructions is that they 17 | "measure" the execution code provided for the launch. This action of "measure" 18 | is accomplished by taking a cryptographic hash using an algorithm supported by 19 | the TCG's Trusted Platform Module (TPM) so that it may store the measurement 20 | within one of the TPM's Platform Configuration Registers (PCR). This initial 21 | measurement, referred to as the Core Root of Trust Measurement (CRTM), is the 22 | trust anchor for the DRTM. 23 | 24 | While the Intel and AMD implementations of Late Launch both achieve a DRTM, 25 | how their implementations arrive at a DRTM are significantly different. As a 26 | result each will be addressed separately. 27 | 28 | ## Intel Trusted eXecution Technology (TXT) 29 | 30 | For TXT, Intel set about a holistic approach\[[1](#1)\] that 31 | introduced the Safer Mode Extensions (SMX) instruction set. As a result TXT 32 | provides for advanced security capabilities such as measuring System Management 33 | Mode (SMM) when an SMI Transfer Monitor (STM) is in place. The TXT process is 34 | built around the SINIT Authenticated Code Module (ACM) and a Measured Launch 35 | Environment (MLE). The ACM is a binary provided by Intel and the MLE is a 36 | software solution typically provided by the OS provider. Details about the ACM 37 | and the MLE are explained in the "Intel TXT Measured Launch Environment 38 | Developer's Guide". \[[2](#2)\] 39 | 40 | ### SENTER Procedure 41 | 42 | From the moment when the SENTER instruction is invoked until execution control 43 | is handed to the MLE, a series of computations are completed by the CPU and 44 | then by the ACM to generate integrity assertions in the form of measurements 45 | about the platform environment as well as the MLE that will be given control. 46 | Details about the CPU's role in the launch can be found in the Intel Software 47 | Developer's Manual (SDM) under Vol. 2D 6.2.3 para 3 and 6.3 GETSEC[SENTER]. 48 | \[[3](#3)\] The primary role for the CPU is to establish an 49 | environment that minimizes the ability of external tampering and taking the 50 | CRTM used for the DRTM. Below is an outline of the internal steps that the CPU 51 | takes when the SENTER instruction is initial invoked, 52 | 53 | 1. Inhibit processor response to external events: INIT, A20M, NMI, and SMI. 54 | 2. Establish and check the location and size of the ACM to be executed by the ILP. 55 | 3. Check for the existence of an Intel® TXT-capable chipset. 56 | 4. Verify the current power management configuration is acceptable. 57 | 5. Broadcast a message to enable protection of memory and I/O from the activities of other processor agents. 58 | 6. Load the designated ACM into the authenticated code execution area. 59 | 7. Isolate the content of the authenticated code execution area from further state modification by external agents. 60 | 8. Authenticate the ACM. 61 | 9. Updated the TPM with the ACM's hash. 62 | 10. Initialize processor state based on the ACM header information. 63 | 11. Unlock the Intel® TXT-capable chipset private configuration register space and TPM locality 3 space. 64 | 12. Begin execution in the ACM at the defined entry point. 65 | 66 | ### TXT ACM 67 | 68 | The ACM is the portion that is responsible for implementing the advanced 69 | security capabilities provided by TXT. To achieve this, the CPU provides a 70 | highly privileged execution mode that is capable of inspecting System 71 | Management Mode (SMM) memory (SMRAM), this is needed to allow the measurement 72 | of the STI. As a result it is highly important that only authorized code is allowed 73 | to execute in this mode. This is handled in step 8., the authentication of 74 | the ACM. The details of this process can be found in section A.1.2 of the MLE 75 | Developers Guide. \[[2](#2)\] The ACM is entrusted with a series of responsibilities, 76 | ones of particular note are IOMMU protecting the MLE, 77 | measuring the MLE, and the enforcement of the Launch Control Policy (LCP), 78 | 79 | #### Launch Control Policy 80 | 81 | One of the capabilities provided by the ACM is the LCP Engine. The LCP is a 82 | rarely used mechanism to enforce that a known environment is being used. Within 83 | the ACM is an LCP engine that will look for a LCP in a designated TPM NVRAM 84 | address. The LCP allows for defining expected values for TPM PCRs and/or the 85 | expected hash value of the MLE. If a policy check fails, then the LCP Policy 86 | Engine will trigger the ACM to error exit from the SENTER instruction. 87 | 88 | ### Measured Launch Environment 89 | 90 | The final component in the Intel TXT process is the MLE, a software component 91 | that is responsible for the secure setup and execution of the target runtime. 92 | As the ACM conducted a transitive trust extension to the MLE, the MLE should 93 | similar conduct a transitive trust extension to bring the target runtime within 94 | the SMX trust boundary by protecting the runtime's memory from tampering, 95 | measuring the runtime, and optionally enforcing policy to ensure only 96 | authorized runtimes are allowed to execute. 97 | 98 | ## AMD Secure Startup 99 | 100 | The AMD approach is a simpler one that allows more control over code executed 101 | by the SKINIT instruction, to include environment setup and measurements, but 102 | unlike Intel's ACM, execution is limited to the same accesses as 103 | superprivileged mode. This means it is not possible to obtain a measurement of 104 | SMRAM at the time of the late launch. Therefore the trust boundary of SKINIT 105 | still bound to the SRTM. To use the Secure Startup capability, a Secure Loader 106 | (SL) image must be loaded and passed to SKINIT. Details about building an SL 107 | and calling the SKINIT instruction can be found in the AMD ARM64 Architecture 108 | Programmer's Manual, Volume 2. \[[2](#4)\] 109 | 110 | ### SKINIT Procedure 111 | 112 | When the SKINIT instruction is executed, the base address for the SL is passed 113 | in the EAX register. The CPU will then execute the following sequence, 114 | 115 | 1. Reinitialize the processor state similar to INIT signal 116 | 2. Enter 32bit protected mode with paging disabled 117 | 3. Clear all general purpose registers except, 118 | * EAX: start address of SL 119 | * EDX: CPU model, family, and stepping 120 | 4. Secures registers, 121 | * Most Machine Specific Registers (MSRs) retain their values (except those 122 | which might compromise SVM protections) 123 | * EFER MSR is cleared 124 | * setting DPD, R_INIT and DIS_A20M flags in the VM_CR register unconditionally to 1 125 | 4. Page align EAX and use as the start address for 64KBytes of DEV protection 126 | 5. Securely initializes Application Processors (APs) 127 | * clears Global Interrupt Flag (GIF) 128 | * setting DPD, R_INIT and DIS_A20M flags in the VM_CR register 129 | 6. Transmit SL image to TPM for hash, any failure will trigger SKINIT failure 130 | 7. Clear the GIF on the BootStrap Processor (BSP) which disables all interrupts, 131 | including NMI, SMI, and INIT 132 | 8. Update ESP to point at SL stack (SLB base + 65536) 133 | 9. Add SL entry offset to SL base and jump to that address 134 | 135 | ### Secure Loader 136 | 137 | In the AMD world, the initial code executed by the SKINIT instruction is the 138 | Secure Loader (SL). The SL is an Owner provided code base that is responsible 139 | for securely initializing the system and handover to a Security Kernel (SK). 140 | The SL must meet two primary conditions, 141 | 142 | 1. SL image's first two words contain the entry point offset and image size 143 | 2. SL image and stack must be less than 64KBytes 144 | 3. SL image must be loaded page aligned 145 | 146 | Upon execution, the SL is responsible for protecting the remainder of the 147 | execution environment through measurement and memory protection of the SK to which it 148 | will be handing over control. 149 | 150 | ### Security Kernel 151 | 152 | For AMD Secure Startup the last component is the SK. The SK can be an 153 | intermediate kernel or a target runtime kernel. The situation that drives the 154 | need for an intermediate kernel is for solutions that need to do more complex 155 | security verification and/or hand-off to target runtime kernel that cannot be 156 | implemented in less than 64Kbytes. 157 | 158 | # Foot Notes 159 | ###### 1. 160 | Grawrock, D. (2006). The Intel safer computing initiative. Hillsboro, Or.: 161 | Intel Press.
162 | https://books.google.com/books?id=WmGjSgAACAAJ 163 | 164 | ###### 2. 165 | Intel® Trusted Execution Technology (Intel® TXT) 166 | Software Development Guide: 167 | Measured Launched Environment Developer’s Guide 168 | 169 | https://www.intel.com/content/dam/www/public/us/en/documents/guides/intel-txt-software-development-guide.pdf 170 | 171 | ###### 3. 172 | Intel® 64 and IA-32 Architectures 173 | Software Developer’s Manual, 174 | Combined Volumes: 175 | 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D and 4 176 | 177 | https://software.intel.com/sites/default/files/managed/39/c5/325462-sdm-vol-1-2abcd-3abcd.pdf 178 | 179 | ###### 4. 180 | AMD64 Architecture 181 | Programmer’s Manual 182 | Volume 2: 183 | System Programming 184 | 185 | https://www.amd.com/system/files/TechDocs/24593.pdf 186 | -------------------------------------------------------------------------------- /documentation/README.md: -------------------------------------------------------------------------------- 1 | Documentation 2 | ============= 3 | 4 | Here you will find documentation for building and using security engine 5 | components. 6 | -------------------------------------------------------------------------------- /documentation/UseCases.md: -------------------------------------------------------------------------------- 1 | TrenchBoot Use Cases 2 | ==================== 3 | 4 | TrenchBoot is meant to be a universal framework to enable building integrity in 5 | the launch process of systems. To relate to real world usage, it is good to 6 | have a set of use cases that explain a subset of situations where TrenchBoot is 7 | applicable and how it would work in those situations. Below are a series of use 8 | cases that are actively being investigated and/or worked on. 9 | 10 | 11 | ## Crowd Sourcing Integrity 12 | 13 | There is currently no known public authority available to verify BIOS/Firmware 14 | PCR values. TrenchBoot would like to become such an authority but there is the 15 | challenge of how to obtain all these values in a manner that provide assurance 16 | to the authenticity of the values. Crowd sourcing provides the best means to 17 | collect the largest and most diverse set of values. The challenge with crowd 18 | sourcing the values is how to establish authenticity of the values. This 19 | challenge can be overcome with a TrenchBoot based live CD that establishes an 20 | attestation identity provisioned by a TrenchBoot Attestation Certificate 21 | Authority (ACA). 22 | 23 | ## Network Attestation Launch 24 | 25 | An individual or enterprise may not want to allow a system to boot on their 26 | network unless it is running a known configuration. When TrenchBoot is 27 | installed onto a system it will work in conjunction with a TrenchBoot ACA 28 | (public or private instance) that provides a key management service. TrenchBoot 29 | will hold a portion of a Shamir Secret Sharing key with another portion held by 30 | the key management service. For the system to boot it will attest to the key 31 | management service to obtain a key fragment that will allow it to unlock the system 32 | disk. 33 | 34 | ## Travel Laptop 2FA Launch 35 | 36 | When travelling there are times when an individual loses positive control of 37 | their device. During these times attackers can launch physical access attacks. 38 | For this configuration TrenchBoot will "double chain wrap" the encryption key 39 | for decrypting the system where each chain wrap correlates to an authentication 40 | factor. Working internal to external, the system drive key is encrypted with 41 | the first wrap key that is in turn encrypted with the second wrap key. The 42 | first wrap key is stored on a removable token device, e.g. YubiKey, and the 43 | second wrap key is sealed in a TPM NVRAM slot. For a system to boot it must 44 | have launched with the correct firmware and the token must be present. 45 | -------------------------------------------------------------------------------- /documentation/gitlab_CI.md: -------------------------------------------------------------------------------- 1 | # GitlabCI configuration documentation 2 | 3 | ## Preparation 4 | 5 | ### GitHub 6 | 7 | * Create account for CI bot 8 | - grant `Admin` access to this bot in the repositories you will want to use 9 | GitLabCI with 10 | 11 | ### GitLab 12 | 13 | * Create account for CI bot 14 | 15 | ## Configuration 16 | 17 | ### GitLabCI for GitHub integration 18 | 19 | The process is descriebd in the 20 | [official documentation](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/github_integration.html). 21 | 22 | Following projects were integrated: 23 | 24 | * `TrenchBoot` GitHub repositories: 25 | - [grub](https://github.com/trenchboot/grub) 26 | - [landing-zone](https://github.com/trenchboot/landing-zone) 27 | - [linux](https://github.com/trenchboot/linux) 28 | 29 | * `3mdeb` GitHub repositories: 30 | - [grub](https://github.com/3mdeb/grub) 31 | - [landing-zone](https://github.com/3mdeb/landing-zone) 32 | - [linux](https://github.com/3mdeb/linux) 33 | - [meta-trenchboot](https://github.com/3mdeb/meta-trenchboot) 34 | - [nixos-trenchboot-configs](https://github.com/3mdeb/nixos-trenchboot-configs) 35 | 36 | ### CI/CD variables 37 | 38 | Following variables are used on the 39 | [trenchboot1 group level](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd) 40 | (they are used by both the repositories in `TrenchBoot` and `3mdeb` subgroups): 41 | - `CACHIX_AUTHTOKEN` - authotken to push nix artifacts to the 42 | [3mdeb cachix](https://app.cachix.org/cache/3mdeb) 43 | - `CACHIX_SIGNING_KEY` - signing key to sign the artifacts pushed to the 44 | [3mdeb cachix](https://app.cachix.org/cache/3mdeb) 45 | - `RTE_IP_1000V` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) 46 | connected to the `Asrock R1000V` board 47 | - `RTE_IP_APU2` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) 48 | connected to the `APU2` board 49 | - `RTE_IP_SUPERMICRO` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) 50 | connected to the `Supermicro m11sdv-8ct-ln4f` board 51 | - `YOCTO_CACHE_PATH` - local path where the Yocto cache is stored in the local 52 | `HTTP` server 53 | - `YOCTO_HTTP_CACHE_IP` - local IP address of the HTTP cache server 54 | - `YOCTO_HTTP_CACHE_RSYNC_KEY`- private SSH key used to populate the Yocto 55 | downloads/sstate cache on the local server using `rsync` 56 | - `YOCTO_HTTP_CACHE_USER` - username to the local HTTP cache server 57 | 58 | Following variables are used on the 59 | [trenchboot1/3mdeb subgroup level](https://gitlab.com/trenchboot1): 60 | - `GITHUB_GROUP` - gitlab group prefix for `3mdeb` repositories 61 | - `GITHUB_GROUP` - github group prefix for `3mdeb` repositories 62 | 63 | Following variables are used on the 64 | [trenchboot1/trenchboot subgroup level](https://gitlab.com/trenchboot1): 65 | - `GITHUB_GROUP` - gitlab group prefix for `TrenchBoot` repositories 66 | - `GITHUB_GROUP` - github group prefix for `TrenchBoot` repositories 67 | 68 | Thanks to the group variables, we can have the same `.gitlab-ci.yml` content 69 | for both groups, and adjust some variables (like prefixes) there. 70 | 71 | ### Setting up local runners 72 | 73 | Follow the [gitlab-runner](gitlab_runner.md) documentation. 74 | -------------------------------------------------------------------------------- /documentation/gitlab_runner.md: -------------------------------------------------------------------------------- 1 | # Running 2 | 3 | Use `docker-compose` script from the [trenchboot-ci](https://github.com/3mdeb/trenchboot-ci/tree/master/gitlab-runner) 4 | repository: 5 | 6 | ```bash 7 | docker-compose up 8 | ``` 9 | 10 | On first run you will see there is no config file: 11 | 12 | ``` 13 | gitlab-runner1_1 | ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory builds=0 14 | gitlab-runner1_1 | ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory builds=0 15 | ``` 16 | 17 | You need to perform the [registration](#register). 18 | 19 | # Registration 20 | 21 | 1. Go to [CI/CD](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd) settings 22 | in your group. 23 | 24 | 1. Go to the `Set up a group Runner manually` section and set the 25 | `registration token` as environmental variable: 26 | 27 | ```bash 28 | export REGISTRATION_TOKEN="QZgfyepK2_t3SshRgX2K" 29 | ``` 30 | 31 | 1. Register using the [script](https://github.com/3mdeb/trenchboot-ci/blob/master/gitlab-runner/gitlab-runner-register.sh): 32 | 33 | ```bash 34 | ./gitlab-runner-register.sh 35 | 36 | Runtime platform arch=amd64 os=linux pid=142 revision=ce065b93 version=12.10.1 37 | Running in system-mode. 38 | 39 | Registering runner... succeeded runner=QZgfyepK 40 | Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! 41 | ``` 42 | 43 | 1. The containter logs should become: 44 | 45 | ``` 46 | gitlab-runner1_1 | Configuration loaded builds=0 47 | ``` 48 | 49 | 1. The runner should be available in the 50 | [CI/CD group settings](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd#runners-settings) 51 | 52 | ![images/registered_local_runner.png](images/registered_local_runner.png) 53 | 54 | 1. Refer to the 55 | [register documentation](https://docs.gitlab.com/runner/register/index.html) 56 | if needed. 57 | 58 | # Usage 59 | 60 | Local runner can run the exact same jobs as a shared runnners in the cloud. 61 | Typically, we will want to mark some specific jobs to run on the local runner 62 | instead. Examples of such jobs: 63 | - local infastructure acces required, 64 | - extensive hardware requirementes (shared runners have limited resources). 65 | 66 | In the [gitlab-runner-register.sh](https://github.com/3mdeb/trenchboot-ci/blob/master/gitlab-runner/gitlab-runner-register.sh) 67 | we are providing a list of tags as one of the arguments: 68 | 69 | ```bash 70 | --tag-list local \ 71 | ``` 72 | 73 | In this case, we mark our runner with a `local` tag. We can mark a specific job 74 | (in a `.gitlab-ci.yml` file) with the same tag, to make sure it will always run 75 | on a local runner, rather the shared (cloud one). The syntax is: 76 | 77 | ```bash 78 | tags: 79 | - local 80 | ``` 81 | 82 | Please refer to the 83 | [tags description in the official documentation](https://docs.gitlab.com/ee/ci/yaml/#tags). 84 | -------------------------------------------------------------------------------- /documentation/images/Arch_Flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/documentation/images/Arch_Flow.png -------------------------------------------------------------------------------- /documentation/images/Arch_Flow.xml: -------------------------------------------------------------------------------- 1 | 7ZlZj9MwEIB/TR+pEjtXH3eXhSJxSYvg2UncxMKJi+NuW349dmLnqF0oNLBI0H2oM+Mjnm/GM/Uu4F11eMnRtnzDckwXwMsPC/h8AYDvJaH8UpJjJwlXoBMUnOS60yB4IF+xGamlO5LjZtJRMEYF2U6FGatrnImJDHHO9tNuG0anq25RgS3BQ4aoLf1EclF20iT0Bvkak6I0K/ue1qQo+1xwtqv1egsAN+2nU1fIzKX7NyXK2X4kgvcLeMcZE12rOtxhqmxrzNaNe3FG2783x7W4ZACA3YhHRHfYvHL7YuJojNFuB6sB3gLe7ksi8MMWZUq7l/ilrBQVlU++bG4IpXeMMt6ONZuXclaLF6giVHnEGtNHLEiGtEI7gB/I50Zw9hmbKWpWS82tvS2900fMBT6MRHqbLzGrsOBH2UVrDTvtkT2B/cA3jrWsHLGFgRYi7VNFP/VgV9nQpj1jZuAwc0SF3v/E3tGXHTOKZ01rmRvZwU+2h0EpW4X+bmdJjeABZztOhNr4fV0QaT3dQ75iejpKyrrljXhO8qH6+3Xycoqo/UiNoizH0BtKilrqBFNrN/JVSF18UA/dDDO4CYj8qZ8EvuUnYeDyE28GP7kgGkcW7w8PRSdHTdmjQtpQmTQE5g4LViTP1Yxqjq2auToU6ihfdqcnWKa4zm9UW02tbBEvFcz2iAeJbNVMZKVZTnVcY6SWD9SbDY7TPQkkCFPr+onqv6Fk+1GPVe31GRdKMpxlLs9IkzAIvXmIQxhMiEOTq0bEfegg7vcZ5wrisUX89tWHPqq5Cc1XdYGb1oaW6jtR618QtZdGp3Ww48jNJo9XqTcTG5BMoxECBxvgYBPNEIwrC81bxisZWl+lcS0M94+yZKkzfAEgE3PZkRJJiv+YUtohfZ32gr7OeLcTVB3z1+LcgDM4ozQKo3lwBjGY4AxCOwk7cSYz4DS15YjnkCxPmb3nLMNNw/i/FW9B/ITx5vsWoNdoV8ssI2ewMKyRrLGB906V1v8Soih6SkTBX1OgqBVJg6dFireMnUWK3xaiWP76UovJbsEVnPMQJ7mzYE1ACqOZzsr+vDKcIbQ4O3+vJDNgDv8azGLPPqHjCeRoKEXBz4AcFaIr76nqzWC1WobTNOjZaKPQRgvCGdDaBef/CP49ERx4Jyf1n4zg5D/mP4Q5XD0dZjsdt78er61+xja94O4ldJge4WTjPEqjLMHpZh7Txycp0rfvanzXXY0/x12NnSNvdkUlN9OlmOvu0k4d+2wEnLl0O3+XNoPZk/gkgcHQUYN6jgz2C3ep8nG4Dm91o/85wPtv -------------------------------------------------------------------------------- /documentation/images/Architectural_Flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/documentation/images/Architectural_Flow.png -------------------------------------------------------------------------------- /documentation/images/Architectural_Flow.xml: -------------------------------------------------------------------------------- 1 | 7Vnbkps4EP0aPyYFkrn4MZ5MLlWzVVOZqdrdRxka0EZGLMiX2a9fCUkGDJ7YMcSp3dgPRkf3PkfdLTzDd+v9x5IU2W88BjZDTryf4fczhFwn9OSPQl404uNQA2lJY9OoAZ7oP2B7GnRDY6g6DQXnTNCiC0Y8zyESHYyUJd91myWcdWctSAo94CkirI/+TmORaTT0nAb/BDTN7MyuY2pWJPqalnyTm/lmCCf1R1eviR3LtK8yEvNdC8L3M3xXci7003p/B0zZ1ppN9/twovaw7hJycU4HpDtsCduAXbHPZNdlwuUIcoHixRjF/3vDbcWbqqbsnWyAgmLfVMqnVP0u5Q4qIcUhWzxmpAI7rFyKHlm3M1Y4TIKkQQr1WAkoZH0BJV2DgNJAj015ucuogKeCRKr9Ts2Fl5lYM1ly1TrpHqy0dJmxO854WU+EE099zX4+kDVlSqufgG1B0IiYCtt/LstbKFUNe8domktQcDWj3CX/Cq2B/fpz2FubC0OPGgj2Lchw8xG43Fv5IpvYWu+tOUnmIOEG2TXCRKGRU9YWpW9AYg5Dehi+EYR8MJoY1geeSB+fc8nhGmJKBPySyDUSQWFwY43MJ9LIl00uJJO/5HGNPDwvvLE8/AF5HFFWB0yIjZm/yUqHhZhAmESXsNC3dxTCKhnJY2N8bO/mgLbsHQyYez6CtV2vZ12IZW5jirwUGU95Tth9gy4b+ztdW8Oeij8U/NYzpT9tTS4X1qpSRVv3FwjxYixONoJLqJn3gSvRaybPZewU5d/BZMU3ZQQdZQpSpiA6kDLZq2yXwIig2266eBVv/hS8uS3WNFGjc9MIoS0DPdlZLAR9Fuw1YDwaTNdHTuuIZA4r9tHRYZ27C4vYYfTCTM8jQg9LOY/j8GSkjOl2MFBKryPeEB0uVKSMQCVO/Vhpx6kKkp8Tcd1wKOI+aw6Qcwi9h5CrB+5OJuF63ScC8VVe3YMwnl+iQ2Ok98ZCJ4OtXAHN0+da6KgBHiARRsQG+WIcszPkaEK0wqOF6EUvg1v4/QDtDkQMvLje89gcf2rP85qjGN0rneV5rEU7rie8VQRAE0Vu1A7dTocIU3fg4nZMhD8TE8H/K2NFvYx1wP1Mla+OcHscjmXLz8/n3hj/S2S6x2TOneCHkWkd6s+b4EjTRpl6OSkRslbU5quq6OY0Q6nOddM+cBLXm7pRNpUkCYouEumPzaZif+V7I2VTGPXemfqDLzyG8inXGSF8LKaJ48ErV/Bg+jv4SWqmv6Qdp8fzuXN8SdPJRO+S9n2DjXjju/79+bcdmfME0aakQtn6Pk9pfvar0ut8CviX+ZT+sQ8WK8cZ6djjHrEO6h16Nwz7h967PPLJYvMfndZF80covv8X -------------------------------------------------------------------------------- /documentation/images/SoftwareArch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/documentation/images/SoftwareArch.png -------------------------------------------------------------------------------- /documentation/images/SoftwareArch.xml: -------------------------------------------------------------------------------- 1 | 3Vltc9soEP41/ngZvdrKxziXpJ1L5zKTzlz76QZJWKJBwodQYvfX3yJA745lR20ztcdjsbAL7PPALmjhXme7O4626ScWY7pwrHi3cP9cOI5tBZfwJyV7JVl6nhIknMS6USN4JN+x0dTSksS46DQUjFFBtl1hxPIcR6IjQ5yzl26zDaPdXrcowQPBY4ToUPoPiUWqpIFvNfIPmCSp6dm2dE2IoqeEszLX/S0cd1N9VHWGjC3dvkhRzF5aIvdm4V5zxoR6ynbXmErfGrcpvdsDtfW4Oc7FJIVAaTwjWmIz5GpgYm+cUU0HSwVr4a5fUiLw4xZFsvYF4AdZKjIKJRseN4TSa0YZr3TN5EHOcnGLMkIlI65ZRiLo5BHlBfx9etQNNBFsD8qF4OwJG1M5y6FmrQeLucC7gzO2az8CPzHLsOB7aKIVLrXnNTMdT5dfGpx9Q8O0hXGtiDS3ktp041940C4ed7cz8PZnGHeUriXgzpJCX+uQw1Min/7CPK8W1h2BWgua4mGjAVxAqa18jPaUAG78OGahAvg+rAU1i/8uBVjB4+DGCAeb6O3ggqllFOBwMw/Ctt2D2LcHENveCMS14lsgdk+CuKyW+vtF2MdB7M2CcOCE7nI5D8Ku/ysR9iYi3IJs+V8pd/TKS38UlZuuoIHtbXeVR0y9gfwelWAQhaDuWGYbmMXygEwtloyRKKqwVvUKUxMQncm00J1ZY+EBLyO5g0g6EIi/V5QkOdQJtp1Cqnh1GVrWPKRy3C6p3GAYGWx/jFTuDKRaDYDBMaQkusi4SFnCckRvGum6G5hbQOIdEV+k+MLXpa+65hsWYq9dikrBQNTYvmfS62ofaAP7AdNnLOEZgUQNW471dbfD1FjJI9xZQgLxBIuWaAgOxxQJ8ty1/hZHn5zwvL4CcB5fyYQTiiFl0dPnlOS9jOiUNfI6euBSvv+ix1UVvlbtHP9sJJzJSLQTpJFVYGSTAdM9PDCSi8PB2++nXWrwWqud2fYMOVbXkOf3DKkpDwwBmmjfaraVDYpXBhz0+rHdHh2VxYactU8n8fXyd+CrPRtf3SFfbWvxCwnr93l2LmG9vqHljyGs5/QXhjMrYc0C/pH5kUmbSU4ER9mm+D2zI19+Jx2fqs9MeZDnd/nhroZ5kDOyoPp8PSc62/bx7a4+/pSc7tccTjJyJzh2BGo2ycnXFMfznjc52vNXXUd77sDRY35ezeHn4TH13YWVOtm56IUP3xQfMCcwdXkCVimRjkQmKqnmq/OjzUieah8A9edEG6+XHnmr4Mxos+rlWda0aHNOQPAG1JrlbLM6nB7rOkOZd3TyMRvcFErNfvaxlyOrXgXOkjYxUEkoMZLw+8cMJfiixBtiaqGrpsFhleJJhuhTlcCBmJ+oFBJWvKoCwvYke4yEbVwMIqu+dW4HCy06khf0rzMyEscVrRnUbGi1T6Ygw/nknXHu2ON09xGz/x+97JjjBs1eTY/yJKve1bQ9brx7j0JMH1hBBGHSyyETgmWSHbJiXV9xjgX68QunqrOrYqveKcm+kClsyE5uR2s9HhhXAtOMKAGnA8Fv7zDi/9pOsIPfxTZPpiYZPwtwy+sCvhzebrnOEG83OBluKDYvsFS8aN4Sujf/Aw== -------------------------------------------------------------------------------- /documentation/images/registered_local_runner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/documentation/images/registered_local_runner.png -------------------------------------------------------------------------------- /presentations/PSEC-2018.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/presentations/PSEC-2018.pdf -------------------------------------------------------------------------------- /presentations/README.md: -------------------------------------------------------------------------------- 1 | Presentations 2 | ============= 3 | 4 | Here you will find presentations given on TrenchBoot, sorted by reverse chronology. 5 | 6 | ### [Improving the Security of Edge Computing Services](https://fosdem.org/2020/schedule/event/firmware_itsoecs/) 7 | *Piotr Król*, 3mdeb & *Daniel Kiper*, Oracle
8 | FOSDEM, February 2020, Brussels
9 | :book: slides: [part1](https://fosdem.org/2020/schedule/event/firmware_itsoecs/attachments/slides/3816/export/events/attachments/firmware_itsoecs/slides/3816/improving_the_security_of_edge_computing_services_20200201_pk.pdf) — [part2](https://fosdem.org/2020/schedule/event/firmware_itsoecs/attachments/slides/3817/export/events/attachments/firmware_itsoecs/slides/3817/fosdem_trenchboot_20200201_dk.pdf)
10 | :movie_camera: [video](https://video.fosdem.org/2020/K.4.601/firmware_itsoecs.mp4) 11 | 12 | ### Secure Virtual Network Appliance with TrenchBoot 13 | *Piotr Król*, 3mdeb
14 | Embedded Linux Conference Europe, Oct 2019, Lyons
15 | :movie_camera: [demo video](https://www.youtube.com/watch?time_continue=112&v=KHddgelN7fI)
16 | :book: [description](https://cloud.3mdeb.com/index.php/s/XfBfMBbrE7SZRKY#pdfviewer) 17 | 18 | ### [TrenchBoot: Open DRTM implementation for AMD platforms](https://osfc.io/talks/trenchboot-open-drtm-implementation-for-amd-platforms) 19 | *Piotr Król*, 3mdeb
20 | Open Source Firmware Conference, September 2019, Mountain View, CA
21 | :book: [slides](https://osfc.io/uploads/talk/paper/16/TrenchBoot_-_Open_DRTM_implementation_for_AMD_platforms.pdf)
22 | :movie_camera: [video](https://www.youtube.com/watch?v=9NcVjsSu59w) 23 | 24 | ### [Linux kernel secure launch dive-in](https://linuxplumbersconf.org/event/4/sessions/69/) 25 | *Daniel Kiper, Ross Philipson*, Oracle & *Daniel P. Smith*, Apertus Solutions
26 | Linux Plumbers Conference, August 2019, Lisbon
27 | :movie_camera: [video](https://www.youtube.com/watch?v=u8XxDov-JNE&t=1h10m20s) 28 | 29 | ### [TrenchBoot: How to nicely boot system with Intel TXT and AMD SVM](https://sched.co/RHb0) 30 | *Daniel Kiper*, Oracle & *Daniel P. Smith*, Apertus Solutions
31 | Linux Security Summit, August 2019, San Diego, CA
32 | :book: [slides](https://static.sched.com/hosted_files/lssna19/75/trenchboot_ot_lss_20190815.final.ds.dk.pdf)
33 | :movie_camera: [video](https://youtube.com/watch?v=DbpCU9iSi4g) 34 | 35 | ### [How TrenchBoot is Enabling Measured Launch for Open-Source Platform Security](https://sched.co/PFWC) 36 | *Daniel P. Smith*, Apertus Solutions
37 | Xen Summit, July 2019, Chicago, IL
38 | :movie_camera: [video](https://youtube.com/watch?v=f0LZFSq4Ack) 39 | 40 | ### Trustworthy OE Devices and Software Supply Chain Integrity 41 | *Christopher Clark, Rich Persaud, Daniel P. Smith*, OpenXT
42 | Embedded Linux Conference Europe, Oct 2018, Edinburgh
43 | :book: [slide](https://elinux.org/images/4/46/ELCE2018-poster-Persaud-OpenXT.pdf) 44 | 45 | ### [TrenchBoot](https://www.platformsecuritysummit.com/2018/speaker/smith/) 46 | *Daniel P. Smith*, Apertus Solutions
47 | Platform Security Summit, May 2018, Fairfax, VA
48 | :book: [slides](https://www.platformsecuritysummit.com/2018/speaker/smith/PSEC2018-TrenchBoot-Daniel-Smith.pdf)
49 | :movie_camera: [video](https://www.youtube.com/watch?v=nKsD1QWVGtk) 50 | -------------------------------------------------------------------------------- /references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf -------------------------------------------------------------------------------- /references/README.md: -------------------------------------------------------------------------------- 1 | References 2 | ========== 3 | 4 | Here you will find reference knowledge explaining concepts and theory behind 5 | TrenchBoot. 6 | -------------------------------------------------------------------------------- /references/intel-txt-preliminary-architecture.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/references/intel-txt-preliminary-architecture.pdf -------------------------------------------------------------------------------- /references/intel-txt-software-development-guide.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/references/intel-txt-software-development-guide.pdf -------------------------------------------------------------------------------- /roadmap/Roadmap.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TrenchBoot/documentation/50c82921e395a6723d8fe249a74c8f80a877628d/roadmap/Roadmap.pdf -------------------------------------------------------------------------------- /specifications/secure-launch-specification.rst: -------------------------------------------------------------------------------- 1 | 2 | .. include:: 3 | 4 | ########################### 5 | Secure Launch Specification 6 | ########################### 7 | 8 | .. class:: center 9 | 10 | **Version:** 0.6.0-draft 11 | 12 | .. class:: center 13 | 14 | **Authors:** 15 | 16 | .. class:: center 17 | 18 | **Daniel P. Smith** (Apertus Solutions) 19 | **Ross Philipson** (Oracle) 20 | **Krystian Hebel** (3mdeb) 21 | 22 | .. sectnum:: 23 | 24 | .. contents:: Table of Contents 25 | 26 | Introduction 27 | ============ 28 | 29 | Like many cross-platform capabilities implemented by different manufacturers, 30 | each vendor may have their own unique way of implementing any one of these 31 | capabilities. Dynamic Launch is no different in this manner. To handle this, 32 | the TrenchBoot project is striving to provide a unified approach to using 33 | Dynamic Launch across different platforms. One aspect of Dynamic Launch that 34 | varies across platforms is the launch related data. For example, on Intel there 35 | is a series of Intel defined configuration data structures that must be 36 | present, as well as a user-defined data structure. Whereas on AMD, only the 37 | layout of an AMD Secure Loader Block (SLB) is defined and thus, any 38 | configuration structures are SLB implementation specific. 39 | 40 | To provide a unified experience in passing configuration and other meta-data to 41 | a TrenchBoot Secure Launch entry point for a kernel, this specification 42 | provides the platform-agnostic Secure Launch Resource Table (SLRT) along with 43 | details on how it will be implemented for each platform supported. 44 | 45 | Terminology 46 | =========== 47 | 48 | Requirements Language 49 | --------------------- 50 | 51 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, 52 | **"SHALL NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, 53 | and **"OPTIONAL"** in this document are to be interpreted as described in 54 | :rfc:`2119`. 55 | 56 | 57 | Acronyms 58 | -------- 59 | 60 | :DCE: Dynamic Configuration Environment (*eg. Intel ACM/AMD SLB*) 61 | :DLE: Dynamic Launch Event (*eg. Intel GETSEC[SENTER]/AMD SKINIT*) 62 | :DLME: Dynamic Launch Measured Environment (*eg. Operating System/Hypervisor*) 63 | :DRTM: Dynamic Root of Trust Measurement 64 | :SLRT: Secure Launch Resource Table 65 | 66 | 67 | Secure Launch Architecture 68 | ========================== 69 | 70 | 71 | Secure Launch aware Bootloader 72 | ------------------------------ 73 | 74 | A bootloader is Secure Launch aware if it understands how to load or provide a 75 | DLE (Dynamic Launch Event) Handler and configure an SLRT. 76 | 77 | .. note:: 78 | Throughout this specification the term bootloader will be used to 79 | generically refer to the sofware responsible for loading the OS. This may be 80 | an x86 bootloader such as GRUB, an embedded system bootloader such as Das 81 | U-Boot, or an arbitrary UEFI OS Loader. 82 | 83 | Bootloader Types 84 | ~~~~~~~~~~~~~~~~ 85 | 86 | A Secure Launch aware bootloader can be categorized as one of three types, 87 | 88 | :monolithic: This is a bootloader that contains the DLE Handler. 89 | :initializing: This is a bootloader that loads an external DLE Handler and 90 | executes a supplemental bootloader. 91 | :supplemental: This is a bootloader that is capable of calling a DLE Handler. 92 | 93 | Dynamic Launch Event Handler 94 | ---------------------------- 95 | 96 | The DLE Handler consumes the SLRT and invokes the platform's DLE. The Secure 97 | Launch specification seeks to standardize the invocation interface for the DLE 98 | Handler to be implemented by each platform supported by TrenchBoot. The 99 | specification provides a well-defined interface for DLE Handler and bootloader 100 | implementors to follow to ensure interoperability between implementations. 101 | 102 | Secure Launch Resource Table 103 | ---------------------------- 104 | 105 | The SLRT is a platform-agnostic, standard format for providing information to 106 | the DLE Handler and for passing D-RTM relevant information across the DLE to be 107 | available for use by the DCE and the DLME. The table **SHALL** be initialized 108 | by a bootloader and any subsequent bootloaders in the boot chain **MAY** append 109 | entries to the table. While the table is designed to be implementation 110 | agnostic, the reality of D-RTM hardware will drive a difference in the 111 | construction and setup of the table. 112 | 113 | Secure Launch Entry 114 | ------------------- 115 | 116 | The SL Entry (Secure Launch Entry) is a kernel entry point for the DLME that is 117 | aware of the intricacies of the platform's D-RTM implementation. Its interface 118 | is dictated by the platform's Dynamic Launch implementation. The SL Entry is 119 | responsible for bringing the system up from its Dynamic Launch state to a 120 | suitable state for transitioning control to the DLME kernel. Before 121 | transferring control to the standard code path, the SL Entry **SHALL** use the 122 | SLRT to establish an integrity assessment of the platform. 123 | 124 | Sequence 125 | -------- 126 | 127 | :: 128 | 129 | | Monolithic Bootloader | 130 | | | 131 | | | 132 | Initializing Supplemental DLE SL 133 | Bootloader Bootloader Handler SLRT Entry 134 | ------+------- -----+------ ----+---- ----+---- ---+--- 135 | | | | | | 136 | | | | | | 137 | | | | | 138 | | Load into Memory | | | 139 | +---------------------------------->| | | 140 | | | | | 141 | | | | | 142 | | Initialize Table | | 143 | +------------------------------------------------->| | 144 | | | | 145 | | Invoke | | | | 146 | +---------------->| | | | 147 | | Update | | | 148 | +---------------->| | | 149 | | | | | 150 | | Lookup | | | 151 | | Handler | | | 152 | +---------------->| | | 153 | | | | | 154 | | Invoke | | | 155 | +---------------->| | | 156 | | | | 157 | | Read | | 158 | | Table | | 159 | +------------->| | 160 | | | | 161 | | | | 162 | | | 163 | | Dynamic Launch Event | 164 | +--------------------------->| 165 | | 166 | | | 167 | | | 168 | | Read | 169 | | Table | 170 | |<------------+ 171 | | | 172 | 173 | Secure Launch Interfaces 174 | ======================== 175 | 176 | There are two interfaces to be defined here, the DLE Handler Specifications and 177 | the SLRT Specification. 178 | 179 | DLE Handler Specification 180 | ------------------------- 181 | 182 | The DLE Handler Specification defines the invocation interface for the DLE Handler. 183 | 184 | Platform Requirements 185 | ~~~~~~~~~~~~~~~~~~~~~ 186 | 187 | | **1** - x86 Platforms 188 | | **1.1** - The DLE Handler **MAY** be invoked with the CPU in either 32bit 189 | | protected mode or 64bit long mode 190 | | **1.2** - The SLRT **SHALL** be passed to the DLE Handler in the EDI/RDI CPU 191 | | register 192 | | **1.3** - All other registers besides EDI/RDI are not guarenteed 193 | | **1.4** - The invoking code **SHALL** use a long jump to the DLE Handler 194 | | **1.5** - The DLE Handler **SHALL NOT** return control on error 195 | | 196 | | **2** - Arm Platforms 197 | | **2.1** - *Reserved* 198 | 199 | 200 | SLRT Specification 201 | ------------------ 202 | 203 | This specification details the construction of the SLRT, and how that table 204 | will be passed to a Secure Launch entry point for each supported hardware 205 | platform. 206 | 207 | The SLRT **SHALL** be initialized by a bootloader and any subsequent 208 | bootloaders in the boot chain **MAY** append entries to the table. While the 209 | table is designed to be agnostic, the reality of DRTM hardware will drive 210 | differences in the construction and populating the table. Outlined here 211 | are a set of common, general requirements that all platforms should be 212 | able to meet. The supplemental sections will cover any idiosyncrasies for the 213 | various platforms and environments supported. 214 | 215 | Platform Requirements 216 | --------------------- 217 | 218 | | **1** - General Requirements 219 | | **1.1** - The SLRT **MUST** begin with the magic value `0x4452544d`. 220 | | **1.2** - A properly formatted SLRT **SHALL** consist of a table header, 221 | | zero or more table entries, and an end entry. 222 | | **1.3** - The SLRT **SHOULD** be in contiguous physical memory. 223 | | **1.3.1** - A preallocated, fixed size table is **OPTIONAL** through the use 224 | | of the `max_size` field. 225 | | **1.4** - The SLRT **SHALL** be aligned to a four-byte boundary. 226 | | 227 | | **2** - UEFI Environmnents 228 | | **2.1** - The SLRT **SHALL** be registed in the UEFI SystemTable. 229 | | **2.1.2** - The GUID for registering the table **MUST BE** 230 | | `877a9b2a-0385-45d1-a034-9dac9c9e565f`. 231 | | **2.2** - All UEFI OS Loaders **SHALL** record an EFI Config record with an 232 | | UEFI Config Entry for each measureable configuration action or 233 | | information provide to the DLME kernel. 234 | | **2.3** - The UEFI OS Loader is responsible for calling ExitBootServices() 235 | | **SHALL** be responsible for calling the DLE Handler. 236 | | **2.3.1** - The address for the SLRT **MUST** be passed via an architecture 237 | | specific register. 238 | | 239 | | **3** - x86 Platforms 240 | | **3.1** - The SLRT **MUST** be constructed within the 4G boundary. 241 | | **3.1.1** - On Intel TXT platforms the location of the SLRT **SHALL** be 242 | | stored in the OS2MLE structure, see Appendix B 243 | | **3.1.2** - On AMD platforms the location of the SLRT **SHALL** be stored in 244 | | the Secure Kernel Loader (SKL) configuration table 245 | | 246 | | **4** - Arm Platforms 247 | | **4.1** - *Reserved* 248 | 249 | SLRT Structure 250 | -------------- 251 | 252 | The SLRT is constructed from a header at the beginning, followed by a list of 253 | Tag-Length-Value (TLV) entries. Provided below is a description of the header 254 | and the possible entry types that may be found in the table. For general 255 | portability, the definitions of each entry contain a representative C 256 | structure. 257 | 258 | Versioning Scheme 259 | ~~~~~~~~~~~~~~~~~ 260 | 261 | The SLRT supports revisioning at two depths, at the table level and at the individual 262 | entry level. The table level revision is found in the SLRT header and conveys the format 263 | of the SLRT header as well as what SLRT entries may be appear in the table. The entry 264 | level revisioning is for those that are expected may need future expansion. 265 | 266 | Revision Table 267 | ^^^^^^^^^^^^^^ 268 | 269 | This table contains the list of versions for this revision of the specification. 270 | 271 | +-------------------+----------+ 272 | | | Revision | 273 | +===================+==========+ 274 | | SLR Table| 0x01 | 275 | +-------------------+----------+ 276 | | D-RTM Policy Entry| 0x01 | 277 | +-------------------+----------+ 278 | | UEFI Config Entry| 0x01 | 279 | +-------------------+----------+ 280 | 281 | Core Entries 282 | ~~~~~~~~~~~~ 283 | 284 | The core table entries are the set of entries that are platform and 285 | architecture agnostic. 286 | 287 | SLRT Header 288 | ^^^^^^^^^^^ 289 | 290 | The SLRT Header **SHALL** be located at the beginning of the table and provides 291 | the core information regarding the construction of the table. 292 | 293 | :magic: SLRT identifier, expected value is `0x4452544d`. 294 | :revision: Indentifies the SLRT specification revision used. 295 | :architecture: Identifies the platform architecture and DL implementation. 296 | :size: Total size of the table 297 | :max_size: The maximum size of the memory block. 298 | 299 | .. code-block:: c 300 | :linenos: 1 301 | 302 | struct slr_table { 303 | u32 magic; 304 | u16 revision; 305 | u16 architecture; 306 | u32 size; 307 | u32 max_size; 308 | /* entries[] */ 309 | }; 310 | 311 | SLRT Entry Header 312 | ^^^^^^^^^^^^^^^^^ 313 | 314 | The SLRT is a TLV list requiring every entry to have an identifying tag and the 315 | size of the entry. The SLRT Entry Header provides that representation and is 316 | present at the beginning of every entry. 317 | 318 | :tag: Entry identifier. 319 | :size: Size of the entry. 320 | 321 | .. code-block:: c 322 | :linenos: 1 323 | 324 | struct slr_entry_hdr { 325 | u32 tag; 326 | u32 size; 327 | }; 328 | 329 | SLRT Entry Tag Types 330 | """""""""""""""""""" 331 | 332 | The list of valid entry tags. 333 | 334 | .. code-block:: c 335 | :linenos: 1 336 | 337 | #define SLR_ENTRY_INVALID 0x0000 338 | #define SLR_ENTRY_DL_INFO 0x0001 339 | #define SLR_ENTRY_LOG_INFO 0x0002 340 | #define SLR_ENTRY_DRTM_POLICY 0x0003 341 | #define SLR_ENTRY_INTEL_INFO 0x0004 342 | #define SLR_ENTRY_AMD_INFO 0x0005 343 | #define SLR_ENTRY_ARM_INFO 0x0006 344 | #define SLR_ENTRY_UEFI_INFO 0x0007 345 | #define SLR_ENTRY_UEFI_CONFIG 0x0008 346 | #define SLR_ENTRY_END 0xffff 347 | 348 | Dynamic Launch Configuration 349 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 350 | 351 | :REQUIRED: This entry **MUST** be present. 352 | 353 | This is the main configuration entry, providing the necessary information to 354 | invoke the DLE Handler and for the DLE Handler to invoke the DL. 355 | 356 | :tag: SLR_ENTRY_DL_INFO 357 | :dce_size: The size of the DCE. 358 | :dce_base: The base address where the DCE is located. 359 | :dlme_size: The size of the DLME. 360 | :dlme_base: The base address where the DLME is located. 361 | :dlme_entry: The offset into the DLME of the entry point. 362 | :bl_context: Allows the bootloader to provide a reference to a context object. 363 | :dl_handler: The address to the entry point for the DLE Handler. 364 | 365 | .. code-block:: c 366 | :linenos: 1 367 | 368 | struct slr_entry_dl_info { 369 | struct slr_entry_hdr hdr; 370 | u64 dce_size; 371 | u64 dce_base; 372 | u64 dlme_size; 373 | u64 dlme_base; 374 | u64 dlme_entry; 375 | struct slr_bl_context bl_context; 376 | u64 dl_handler; 377 | }; 378 | 379 | Boot Loader Context 380 | """"""""""""""""""" 381 | 382 | There may be a situation where the bootloader will need to leave a context 383 | object containing platform specific information or helper callbacks for the DLE 384 | Handler to use. 385 | 386 | .. note:: 387 | It is out-of-scope for this specification, but it is advised that if a 388 | platform or a bootloader requires the use of a context object, they should 389 | standardize their context object to enable independent DLE Handlers 390 | 391 | :bootloader: An identifier the bootloader should use for ident and version. 392 | :context: Address of the context object. 393 | 394 | .. code-block:: c 395 | :linenos: 1 396 | 397 | struct slr_bl_context { 398 | u16 bootloader; 399 | u16 reserved[3]; 400 | u64 context; 401 | }; 402 | 403 | DRTM TPM Event Log 404 | ^^^^^^^^^^^^^^^^^^ 405 | 406 | :REQUIRED: This entry **MUST** be present. 407 | 408 | This entry describes where and what type of TPM event log should be used. 409 | 410 | .. note:: 411 | On most platforms, the TCG UEFI TPM event log format should be used. The 412 | ability to specify alternatives is to support older platforms that are not 413 | aware of the modern event log format or can support multiple formats. 414 | 415 | :tag: SLR_ENTRY_LOG_INFO 416 | :format: The type of TPM event log format to use. 417 | :size: The size allocated for the log. 418 | :addr: The base address where the log should reside. 419 | 420 | .. code-block:: c 421 | :linenos: 1 422 | 423 | struct slr_entry_log_info { 424 | struct slr_entry_hdr hdr; 425 | u16 format; 426 | u16 reserved; 427 | u32 size; 428 | u64 addr; 429 | }; 430 | 431 | D-RTM Measurement Policy 432 | ^^^^^^^^^^^^^^^^^^^^^^^^ 433 | 434 | :REQUIRED: This entry **MUST** be present and have the required entries. 435 | 436 | The measurement policy is for conveying to the SL Entry on what it should 437 | measure, where that entity is located, which PCR the measurement should be 438 | stored, and how the event should be identified in the TPM event log. 439 | 440 | .. warning:: 441 | The SL Entry **SHALL** fail if it determines an invalid policy is present. 442 | 443 | :tag: SLR_ENTRY_ENTRY_POLICY 444 | :revision: A revision field to identify the version of policy being used. 445 | :nr_entries: The total number of policy entries in the array. 446 | 447 | .. code-block:: c 448 | :linenos: 1 449 | 450 | struct slr_entry_policy { 451 | struct slr_entry_hdr hdr; 452 | u16 reserved[2]; 453 | u16 revision; 454 | u16 nr_entries; 455 | struct slr_policy_entry policy_entries[]; 456 | }; 457 | 458 | 459 | DRTM Policy Entry 460 | """"""""""""""""" 461 | 462 | A policy entry represents an entity that the SL Entry is being requested to 463 | measure. As an SL Entry is able to measure an attribute of the launch 464 | environment, that attribute will be published as an entity type. A generic 465 | "unspecified" entity type is also available for measuring a range of memory. 466 | 467 | .. note:: 468 | In the current version (one) of the specification, `TPM_EVENT_INFO_LENGTH` is 469 | defined as 32 bytes. All unused bytes **MUST** be set to `\0`, but the string 470 | **MAY** not be terminated with `\0` if it fills the whole `evt_info`. 471 | 472 | :pcr: PCR to store the measurement. 473 | :entity_type: Identifies the entity type of the entry. 474 | :flags: Flag field to store state for this entry. 475 | :size: The size of entity if not flagged as implicit. 476 | :entity: The address to measure. 477 | :evt_info: Label to be recorded in TPM Event Log. 478 | 479 | .. code-block:: c 480 | :linenos: 1 481 | 482 | struct slr_policy_entry { 483 | u16 pcr; 484 | u16 entity_type; 485 | u16 flags; 486 | u16 reserved; 487 | u64 size; 488 | u64 entity; 489 | char evt_info[TPM_EVENT_INFO_LENGTH]; 490 | }; 491 | 492 | D-RTM Policy Entry Entity Types 493 | ''''''''''''''''''''''''''''''' 494 | 495 | The list of valid entity types for D-RTM Policy entries. 496 | 497 | .. code-block:: c 498 | :linenos: 1 499 | 500 | #define SLR_ET_UNSPECIFIED 0x0000 501 | #define SLR_ET_SLRT 0x0001 502 | #define SLR_ET_LINUX_BOOT_PARAMS 0x0002 503 | #define SLR_ET_LINUX_SETUP_DATA 0x0003 504 | #define SLR_ET_CMDLINE 0x0004 505 | #define SLR_ET_UEFI_MEMMAP 0x0005 506 | #define SLR_ET_RAMDISK 0x0006 507 | #define SLR_ET_MULTIBOOT2_INFO 0x0007 508 | #define SLR_ET_MULTIBOOT2_MODULE 0x0008 509 | // values 0x0009-0x000f reserved for future use 510 | // TXT-specific: 511 | #define SLR_ET_TXT_OS2MLE 0x0010 512 | #define SLR_ET_UNUSED 0xffff 513 | 514 | `SLR_ET_UNUSED` can be used if an entry in the DRTM Policy is to be ignored. 515 | Note that **RECOMMENDED** solution is to just not include the entry in question, 516 | this entity type is left as a final resort if entry has to be removed after SLRT 517 | was created in memory and defragmenting it after removing an entry isn't 518 | feasible. 519 | 520 | D-RTM Policy Entry Flags 521 | '''''''''''''''''''''''' 522 | 523 | The list of valid flags for D-RTM Policy entries. 524 | 525 | .. note:: 526 | `SLR_POLICY_FLAG_MEASURED` **MAY** be used by DCE and/or DLME to mark which 527 | entries were measured, in case not all of them are measured at the same time. 528 | For example, limited in size DCE can use TPM commands for hashing instead of 529 | calculating the hashes to save space. DLME usually doesn't have strict size 530 | constraints, so it may include functions that are much faster than sending 531 | the data to be hashed by TPM. In such cases, `SLR_POLICY_FLAG_MEASURED` is 532 | set by DCE for entries it measures, and DLME skips those. Another example is 533 | a complex DLME like a Linux kernel that doesn't have TPM drivers available at 534 | the point where first measurements are taken. In that case kernel may 535 | calculate the hash earlier and send it to the TPM after drivers become 536 | available, but that **MUST** happen before execution is passed to another, 537 | not measured (as reflected by PCR value) component. Note that all entries 538 | **MUST** be measured in order. 539 | 540 | Some of the entry types can have `SLR_POLICY_IMPLICIT_SIZE` flag set. Such 541 | entries have their `size` specified as zero, and they **SHALL** be measured 542 | as described in Appendix A. 543 | 544 | .. code-block:: c 545 | :linenos: 1 546 | 547 | #define SLR_POLICY_FLAG_MEASURED 0x1 548 | #define SLR_POLICY_IMPLICIT_SIZE 0x2 549 | 550 | Intel TXT Platforms 551 | ~~~~~~~~~~~~~~~~~~~ 552 | 553 | When on Intel platforms specific information needs to be conveyed to Secure 554 | Launch. 555 | 556 | Intel TXT Info 557 | ^^^^^^^^^^^^^^ 558 | 559 | :REQUIRED: This entry **MUST** be present on Intel platforms. 560 | 561 | Intel TXT requires for the pre-launch environment to pass MSR and MTRR state 562 | across to the post-launch environment. 563 | 564 | :tag: SLR_ENTRY_INTEL_INFO 565 | :txt_heap: Base address where the TXT heap resides. 566 | :saved_misc_enable_msr: Saved misc enable MSR values. 567 | :saved_bsp_mtrrs: Saved BSP MTRRs. 568 | 569 | .. code-block:: c 570 | :linenos: 1 571 | 572 | struct slr_entry_intel_info { 573 | struct slr_entry_hdr hdr; 574 | u64 txt_heap; 575 | u64 saved_misc_enable_msr; 576 | struct txt_mtrr_state saved_bsp_mtrrs; 577 | }; 578 | 579 | Saved MTRR State 580 | """""""""""""""" 581 | 582 | .. note:: 583 | In the current version (one) of the specification, 584 | `TXT_VARIABLE_MTRRS_LENGTH` is defined as 32 entries. All fields in unused 585 | entries **MUST** be set to 0. 586 | 587 | :code:`struct slr_txt_mtrr_state` 588 | 589 | :default_mem_type: The default memory type for regions not covered by an MTRR. 590 | :mtrr_vcnt: Number of variable MTRR pairs in the mtrr_pair array. 591 | :mtrr_pair: Array of variable MTRR pairs to restore post launch. 592 | 593 | :code:`struct slr_txt_mtrr_pair` 594 | 595 | :mtrr_physbase: Physical base address for variable MTRR. 596 | :mtrr_physmask: Physical mask for the variable MTRR. 597 | 598 | .. code-block:: c 599 | :linenos: 1 600 | 601 | struct slr_txt_mtrr_pair { 602 | u64 mtrr_physbase; 603 | u64 mtrr_physmask; 604 | }; 605 | 606 | struct slr_txt_mtrr_state { 607 | u64 default_mem_type; 608 | u64 mtrr_vcnt; 609 | struct txt_mtrr_pair mtrr_pair[TXT_VARIABLE_MTRRS_LENGTH]; 610 | }; 611 | 612 | AMD Secure Launch Platforms 613 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 614 | 615 | AMD SKINIT Info 616 | ^^^^^^^^^^^^^^^ 617 | 618 | :REQUIRED: This entry **MUST** be present on AMD platforms. 619 | 620 | The three fields following `slr_entry_hdr` form `setup_data` structure[1] used 621 | to pass data to Linux and the rest of the fields are its data (the structure is 622 | covered in more detail in the "Measuring the Linux setup_data" section of this 623 | specification). This avoids the need to pass SLRT address separately from the 624 | Linux boot parameters. 625 | 626 | :tag: SLR_ENTRY_AMD_INFO 627 | :next: 628 | Pointer to the next `setup_data` structure, or NULL if this is the last one. 629 | :type: Type of the entry (**MUST** be equal to `SETUP_SECURE_LAUNCH`). 630 | :len: Length of the following data. 631 | :slrt_size: Size of the SLRT in bytes. 632 | :slrt_base: Physical address of the SLRT. 633 | :boot_params_base: 634 | Physical address of boot parameters, format depends on target kernel. 635 | :psp_version: 636 | When applicable, version of PSP that participates in DRTM, 0 otherwise. 637 | 638 | .. code-block:: c 639 | :linenos: 1 640 | 641 | #define SETUP_SECURE_LAUNCH 10 642 | 643 | struct slr_entry_amd_info { 644 | struct slr_entry_hdr hdr; 645 | u64 next; 646 | u32 type; 647 | u32 len; 648 | u64 slrt_size; 649 | u64 slrt_base; 650 | u64 boot_params_base; 651 | u16 psp_version; 652 | u16 reserved[3]; 653 | }; 654 | 655 | ARM DRTM Environments 656 | ~~~~~~~~~~~~~~~~~~~~~ 657 | 658 | ARM Info 659 | ^^^^^^^^ 660 | 661 | A placeholder for info specific to ARM D-RTM environments. 662 | 663 | .. code-block:: c 664 | :linenos: 1 665 | 666 | struct slr_entry_arm_info { 667 | struct slr_entry_hdr hdr; 668 | }; 669 | 670 | UEFI Environments 671 | ~~~~~~~~~~~~~~~~~ 672 | 673 | To support UEFI bootloaders that may do additional configuration of the Secure 674 | Launch kernel, the UEFI SLRT entries provide a means to convey any operational 675 | configurations they may have done. 676 | 677 | UEFI Info 678 | ^^^^^^^^^ 679 | 680 | A placeholder for info specific to UEFI environments. 681 | 682 | .. code-block:: c 683 | :linenos: 1 684 | 685 | struct slr_entry_uefi_info { 686 | struct slr_entry_hdr hdr; 687 | }; 688 | 689 | UEFI Config 690 | ^^^^^^^^^^^ 691 | 692 | :OPTIONAL: This entry **SHOULD** be present on UEFI systems. 693 | 694 | This entry can be considered a D-RTM measurement policy for UEFI. It will 695 | declare that the UEFI bootloader has made configurations changes that should be 696 | measured. 697 | 698 | :tag: SLR_ENTRY_UEFI_CONFIG 699 | :revision: A revision field to identify the version of config being used. 700 | :nr_entries: The total number of configuration entries present. 701 | 702 | .. code-block:: c 703 | :linenos: 1 704 | 705 | struct slr_entry_uefi_config { 706 | struct slr_entry_hdr hdr; 707 | u16 reserved[2]; 708 | u16 revision; 709 | u16 nr_entries; 710 | struct slr_uefi_cfg_entry uefi_cfg_entries[]; 711 | }; 712 | 713 | UEFI Config Entry 714 | """""""""""""""" 715 | 716 | :OPTIONAL: This entry **SHOULD** be present on UEFI systems. 717 | 718 | A config entry represents an entity that the UEFI bootloader is requesting to 719 | be measured. 720 | 721 | .. note:: 722 | In the current version (one) of the specification, `TPM_EVENT_INFO_LENGTH` is 723 | defined as 32 bytes. All unused bytes **MUST** be set to `\0`, but the string 724 | **MAY** not be terminated with `\0` if it fills the whole `evt_info`. 725 | 726 | :pcr: PCR to store the measurement. 727 | :size: The size to measure. 728 | :cfg: The address or value to measure. 729 | :evt_info: Label to be recorded in TPM Event Log. 730 | 731 | .. code-block:: c 732 | :linenos: 1 733 | 734 | struct slr_uefi_cfg_entry { 735 | u16 pcr; 736 | u16 reserved; 737 | u32 size; 738 | u64 cfg; /* address or value */ 739 | char evt_info[TPM_EVENT_INFO_LENGTH]; 740 | } __packed; 741 | 742 | 743 | Appendix A: Recommendations for Measuring the DRTM Policy 744 | ===================================== 745 | 746 | While the D-RTM TPM event log is itself proof of the D-RTM policy used by 747 | Secure Launch, there may be motivation for the policy itself to be incorporated 748 | into the measurement chain. While this section does not address the possible 749 | motivations or the validity of those motivations, a possible use of the policy 750 | measurement can be used as the value to cap the D-RTM PCRs. Regardless of 751 | motivations, this appendix is to provide guidance on how the policy might be 752 | measured in a meaningful way. 753 | 754 | TPM Extend Operation 755 | -------------------- 756 | 757 | For clarity, the extend operation, denoted here on out as E(), is an order 758 | preserving, recursive, mapping function. Operation marked by | operator is a 759 | concatenation, not a logical OR. Consider any hash function, denoted as H(), 760 | the extend operation is defined as: 761 | 762 | | Given, 763 | | 0 = sizeof(H) bytes of 0 764 | | Objs = [ Obj_0, ..., Obj_n ] 765 | | Then, 766 | | E(Objs) = { 767 | | E_0 = H( 0 | H(Obj_0) ) 768 | | E_n = H( E_(n-1) | H(Obj_n) ) 769 | | } 770 | 771 | Measuring the Policy 772 | -------------------- 773 | 774 | Measuring the policy is not as simple as hashing the block of memory containing 775 | the policy. This will not work as the policy may contain memory addresses that 776 | have the potential to change on the next launch of the system. As a result 777 | there is a potential for the next launch not to have the same memory addresses 778 | in the policy, which would in turn render a different measurement. 779 | 780 | To make a meaningful measurement of the policy, the measurement must capture 781 | what entities were to be measured and what order they were to be measured. To 782 | capture the first half, the measurement must contain enough of a DRTM policy 783 | entry to capture its uniqueness. Considering DRTM Policy Entry above, a 784 | combination of PCR, Entity Type, and Event Info yields a unique identity for 785 | the entry. To capture ordering of the policy events, the extend operation can 786 | be used to render a unique value that reflects the order of the policy events. 787 | 788 | Using this logic, the resulting operation to measure the policy would be as: 789 | 790 | | Given, 791 | | Entry_n = PCR_n | EntityType_n | EventInfo_n 792 | | Policy = [ Entry_0, ..., Entry_n ] 793 | | Then, 794 | | M_policy = E(Policy) 795 | 796 | The result, `M_policy`, will be a hash of the policy that can then be extended 797 | into one, or more if using as a cap value, PCR(s). 798 | 799 | .. note:: 800 | The SLRT specification version doesn't require measuring the policy, neither 801 | does it have appropriate policy entry type for that measurement. 802 | 803 | Measuring the SLRT 804 | ------------------ 805 | 806 | If there is a need to measure the SLRT, the recommendation is that the vendor 807 | info table, i.e. one of `SLR_ENTRY_INTEL_INFO`, `SLR_ENTRY_AMD_INFO` or 808 | `SLR_ENTRY_ARM_INFO`, is the only one that should be measured. The remainder of 809 | the SLRT is meta-data, addresses and sizes. Note the size of what to measure is 810 | not set. The flag `SLR_POLICY_IMPLICIT_SIZE` leaves it to the measuring code to 811 | choose and use proper structure's size. The structure is measured as a whole, 812 | together with its header. 813 | 814 | Measuring the Linux setup_data 815 | ------------------------------ 816 | 817 | Single linked list of `struct setup_data` is a way to pass extensible boot 818 | parameters and other data from bootloader to Linux kernel. 819 | 820 | :next: Pointer to next `setup_data` structure, or NULL if this is the last one 821 | :type: Type of entry 822 | :len: Length of following data 823 | :data: Parameters passed from bootloader 824 | 825 | .. code-block:: c 826 | :linenos: 1 827 | 828 | struct setup_data { 829 | u64 next; 830 | u32 type; 831 | u32 len; 832 | u8 data[]; 833 | }; 834 | 835 | The above structure is limited by maximum size that can be specified, as well as 836 | by the fact that data must be immediately following the header. To handle these 837 | situations, a `setup_indirect` structure was added in later Linux boot protocol: 838 | 839 | :type: Type of entry, logically ORed with `SETUP_INDIRECT` 840 | :len: Length of data 841 | :addr: Pointer to data 842 | 843 | .. code-block:: c 844 | :linenos: 1 845 | 846 | struct setup_indirect { 847 | u32 type; 848 | u32 reserved; /* Reserved, must be set to zero. */ 849 | u64 len; 850 | u64 addr; 851 | }; 852 | 853 | If indirect entries are used, the `setup_indirect` is put as `setup_data->data`, 854 | and `setup_data->type` is set to `SETUP_INDIRECT`. 855 | 856 | Pointer to the first `setup_data` is saved in DRTM Policy Entry. As these 857 | structures consist of physical addresses and other metadata that may change 858 | between boots, only the actual data is measured. For direct entries this is 859 | `data`, and for indirect -- memory pointed by `addr`. All `setup_data`s are 860 | measured in order, each as a separate entry in the TPM event log. 861 | 862 | Measuring OS to MLE data 863 | ------------------------ 864 | 865 | The SLRT defined OS-MLE heap structure has no fields to measure. It just has 866 | addresses and sizes and a scratch buffer. As such, this entry is skipped as of 867 | now, but this may change in the future versions. 868 | 869 | Measuring Multiboot2 boot information 870 | ------------------------------------- 871 | 872 | Multiboot2 information data structure contains set of Tag-Length-Value (TLV) 873 | entries, however, for the sake of measurement it can be treated as a consecutive 874 | range of memory. Only the total length of this structure is important, it can be 875 | read from first field of that structure, i.e. `u32 total_size`. This is how the 876 | kernel obtains the size, so measuring code should also use it, hence this entity 877 | has `SLR_POLICY_IMPLICIT_SIZE` flag set. 878 | 879 | 880 | Appendix B: Intel TXT OS2MLE 881 | ============================ 882 | 883 | The Intel TXT specification[2] provides a provision for the pre-launch environment to 884 | pass information to the post-launch environment. The specification does not define 885 | this structure, leaving that to the implementation, but provides an allocation for 886 | it in the TXT Heap definition. This area is referred to as the OS2MLE structure. 887 | 888 | The OS2MLE structure for Secure Launch is defined as follows, 889 | 890 | :version: Revision of the os2mle table 891 | :boot_params_addr: 892 | Physical address of boot parameters, format depends on target kernel 893 | :slrt: Physical address of the SLRT 894 | :txt_info: 895 | Physical address of TXT info, located in SLRT (simply a convenience to avoid 896 | parsing SLRT in assembly) 897 | :ap_wake_block: 898 | Physical address of a block of memory where the APs are parked after waking 899 | them up post launch 900 | :ap_wake_block_size: Size of the block mentioned above 901 | :mle_scratch: Scratch area for use by SL Entry early code 902 | 903 | .. code-block:: c 904 | :linenos: 1 905 | 906 | struct os2mle { 907 | u32 version; 908 | u32 reserved; 909 | u64 boot_params_addr; 910 | u64 slrt; 911 | u64 txt_info; 912 | u32 ap_wake_block; 913 | u32 ap_wake_block_size; 914 | u8 mle_scratch[64]; 915 | }; 916 | 917 | [1] https://www.kernel.org/doc/html/v6.12/arch/x86/boot.html#details-of-header-fields 918 | [2] https://www.intel.com/content/www/us/en/content-details/315168/intel-trusted-execution-technology-intel-txt-software-development-guide.html?wapkw=txt 919 | -------------------------------------------------------------------------------- /steering-committee/Community-Meeting-June17-2021.md: -------------------------------------------------------------------------------- 1 | 2 | ## Agenda/Notes 3 | 4 | * Outreach and Engagement 5 | * TrenchBoot Developers Forum 6 | * Determine time period and/or dates 7 | - Piotr feels every 12 mo would be quite long 8 | - is six months too short to discuss things 9 | - thinks sept. we should have something 10 | - OSFC planned for Dec. 11 | - Rich, should do it when things get cold and are locked up 12 | - Do TB talks at multiple events 13 | - We should have an internal event, but maybe make it a DRTM event 14 | - DK, LPC at end of 24Sept 15 | - Should have confirmation by the end of June for LPC MC 16 | - should have slots available for TB talks 17 | 18 | * Select chairman to oversee planning/coordination 19 | - Piotr we would like to help but cannot do it alone 20 | - will engage IBM POWER about sponsoring 21 | - Rich recommends bring the topic up at DRTM related meetings and try to find a corporate sponsor 22 | 23 | * TrenchBoot website 24 | * Identify content that would like to be on the site 25 | - Piotr: coreboot is hooking to rss feeds that feed into blog 26 | - will look at what coreboot implementation 27 | - will look at mkdocs setup to move TB documentation over to 28 | - DanK: will speak with a colleague, will have a response when back from vacation 29 | 30 | * Discuss approach to maintenance/development 31 | - should apply GH auto fixes 32 | 33 | * TrenchBoot Social Media 34 | * Review social media accounts and strategy 35 | * Twitter 36 | * LinkedIn project site/group 37 | * Others? 38 | 39 | * Project 40 | * Moving AMD support forward 41 | * LZ renaming 42 | - Piotr thinks AMD should be involved in TB AMD related topics 43 | - we should also try to get them involved with the call 44 | - Rich, this is a public meeting, may need to have NDA meeting 45 | 46 | * LZ IOMMU approach adoption 47 | - Ross: just adopt current proposed approach as a starting place 48 | - yes the pitsaw card could be used 49 | - Piotr, the current approach is better than nothing 50 | - are there tests? 51 | - Kanth: can the pitsaw card be used to test iommu for txt, can be used for AMD 52 | 53 | * DRTM log approach adoption 54 | - Piotr: based on TCG spec 55 | - this is where the HCL will be useful 56 | - can test Ross changes for linux kernel 57 | - will work on "legacy mode" support 58 | - Ross: need to handle system without the ACPI table 59 | - can make so that the ACPI table is preferred approach then fail back to non-ACPI table 60 | - for the LZ will need to also be made to handle non-ACPI table situation (legacy mode) 61 | - will work on "legacy mode" support 62 | - Daniel: merge the PR 63 | - has been confirmed on pc-engines 64 | 65 | * iPXE support 66 | - Piotr: submitted patches but rejected as too big 67 | - https://github.com/ipxe/ipxe/pull/300 68 | - we should care about iPXE 69 | 70 | * Upcoming v2 LKML submission 71 | - Ross: it looks like it will be going out tomorrow (6/18/2021) 72 | 73 | * GRUB submission 74 | - Daniel K: currently working with Lukasz and will looking to submit in July 75 | - will be working with 3mdeb on aligning AMD changes 76 | 77 | * Deployment/Adoption support 78 | * TrenchBoot Hardware Compatibility List 79 | * How to check if my hardware is supported or can be supported? 80 | - Piotr: resource constrained but we need something very basic 81 | - what all should be checked, log, pcrs, etc 82 | - this is QubesOS HCL as an example 83 | - https://www.qubes-os.org/hcl/ 84 | - list of hardware for people to get started with 85 | - Rich: 86 | - there are a lot of things that make you feel better but not gain much 87 | - maybe skip over that and focus on community 88 | - biggest issues will be with hardware that is not MS certified 89 | - both OXT and Qubes HCL are not correct because every system has quirks 90 | 91 | * TrenchBoot Canonical Demo 92 | 93 | * TrenchBoot as AEM for QubesOS 94 | - Piotr: would be good to assist with anit-evil maid demo 95 | 96 | * Test automation (Kanth) 97 | - Rich suggest this is a place for Qemu support for DRTM to enable software based testing 98 | - at tdf txt lead mentioned txt test suite in FWUPD 99 | - we should get OEM testing 100 | - could TB lead DRTM test suite development 101 | - if there isn't one, who is willing to fund its development 102 | - live cd is not enough, need to build a cross-community project 103 | - this can be a theme for the DRTM event 104 | - Piotr agrees that this FWUPD testing support is desired 105 | - Kanth, Oracle will be increasing supported platforms and would like to see automated testing/validation 106 | - Oracle would be interested in helping with building a DRTM test framework 107 | - Daniel K: GRUB does not have automated testing but it is in progress 108 | - thinks it would be quite easy to introduce tests for preamble 109 | 110 | * Additional Topics (time permitting) 111 | * DRTM/TrenchBoot for Arm 112 | - Stuart: Beta spec will be public by fall and possible reference implementation 113 | - Rich: coordinate a TB event around Arm event/announcement 114 | 115 | * Plan for SMM 116 | - intel whitepaper on SMM DRTM protection 117 | 118 | * Integration with FWUPD hardware security test 119 | 120 | * General Business 121 | * Open floor for community members 122 | 123 | * Next meeting 124 | - Piotr we missed several topics 125 | - discuss getting more resources 126 | - fobnail 127 | - testing 128 | - Rich we should not do meetings during the summer and do out-of-band discussions (chat/email) 129 | - perhaps use OSFC TB slack 130 | - Will be done virtually via TB slack channel 131 | 132 | --------------------------------------------------------------------------------