diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 0000000..c4093fb --- /dev/null +++ b/.codespellrc @@ -0,0 +1,4 @@ +[codespell] +exclude-file = .codespellx +ignore-words-list = FPT,FTP,fpt,ftp,HSI +skip=*.svg,*.json diff --git a/.codespellx b/.codespellx new file mode 100644 index 0000000..e69de29 diff --git a/.conform.yaml b/.conform.yaml new file mode 100644 index 0000000..f96e4e0 --- /dev/null +++ b/.conform.yaml @@ -0,0 +1,16 @@ +--- +policies: + - type: commit + spec: + header: + length: 80 + imperative: false + invalidLastCharacters: . + body: + required: false + dco: true + gpg: + required: true + spellcheck: + locale: US + maximumOfOneCommit: false diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 1b3f36f..cc14a5a 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,3 +1,4 @@ +--- name: ci on: push: diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..fff0e71 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,196 @@ +--- +# Documentation: +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + +# Default state for all rules +default: false + +# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time +MD001: true + +# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading +MD002: + # Heading level + level: 1 + +# MD003/heading-style/header-style - Heading style + +MD003: + # Heading style + # # ATX style H1 + style: "atx" + +# MD004/ul-style - Unordered list style +MD004: + # List style + style: "sublist" + +# MD005/list-indent - Inconsistent indentation for list items at the same level +MD005: true + +# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line +MD006: true + +# MD007/ul-indent - Unordered list indentation +MD007: + # Spaces for indent + indent: 4 + # Whether to indent the first level of the list + start_indented: false + +# MD009/no-trailing-spaces - Trailing spaces +MD009: + # Spaces for line break + br_spaces: 2 + # Allow spaces for empty lines in list items + list_item_empty_lines: false + # Include unnecessary breaks + strict: false + +# MD010/no-hard-tabs - Hard tabs +MD010: + # Include code blocks + code_blocks: false + # Number of spaces for each hard tab + spaces_per_tab: 1 + +# MD011/no-reversed-links - Reversed link syntax +MD011: true + +# MD012/no-multiple-blanks - Multiple consecutive blank lines +MD012: + # Consecutive blank lines + maximum: 1 +# MD013/line-length - Line length +# +MD013: + # Number of characters + line_length: 80 + # Number of characters for headings + heading_line_length: 80 + # Number of characters for code blocks + code_block_line_length: 160 + # Include code blocks + code_blocks: false + # Include tables + tables: false + # Include headings + headings: true + # Strict length checking (e.g. allow for longer URLs) + strict: false + # Stern length checking + stern: false + +# MD014/commands-show-output - Dollar signs used before commands without showing output +# TODO: set false for now but we should consider enabling it +# https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code +MD014: false + +# MD018/no-missing-space-atx - No space after hash on atx style heading +MD018: true + +# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading +MD019: true + +# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines +MD022: + # Blank lines above heading + lines_above: 1 + # Blank lines below heading + lines_below: 1 + +# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line +MD023: true + +# MD025/single-title/single-h1 - Multiple top-level headings in the same document +# TODO: consider enabling it + +# MD026/no-trailing-punctuation - Trailing punctuation in heading +MD026: + # Punctuation characters + punctuation: ".,;:!。，；：！" + +# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol +MD027: true + +# MD028/no-blanks-blockquote - Blank line inside blockquote +MD028: true + +# MD029/ol-prefix - Ordered list item prefix +MD029: + # List style + style: "one_or_ordered" + +# MD030/list-marker-space - Spaces after list markers +MD030: + # Spaces for single-line unordered list items + ul_single: 1 + # Spaces for single-line ordered list items + ol_single: 1 + # Spaces for multi-line unordered list items + ul_multi: 1 + # Spaces for multi-line ordered list items + ol_multi: 1 + +# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines +MD031: + # Include list items + list_items: true + +# MD033/no-inline-html - Inline HTML +# MD033: +# # Allowed elements +# allowed_elements: ["br", "center", "img", "script", "form", "input"] + +# MD034/no-bare-urls - Bare URL used +MD034: true + +# MD035/hr-style - Horizontal rule style +MD035: + # Horizontal rule style + style: "---" + +# MD037/no-space-in-emphasis - Spaces inside emphasis markers +MD037: true + +# MD038/no-space-in-code - Spaces inside code span elements +MD038: true + +# MD039/no-space-in-links - Spaces inside link text +MD039: true + +# MD040/fenced-code-language - Fenced code blocks should have a language specified +MD040: true + +# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading +MD041: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD042/no-empty-links - No empty links +MD042: true + +# MD046/code-block-style - Code block style +MD046: + # Block style + style: "fenced" + +# MD047/single-trailing-newline - Files should end with a single newline character +MD047: true + +# MD048/code-fence-style - Code fence style +MD048: + # Code fence style + style: "backtick" + +# MD049/emphasis-style - Emphasis style should be consistent +MD049: + # Emphasis style should be consistent + style: "underscore" + +# MD050/strong-style - Strong style should be consistent +MD050: + # Strong style should be consistent + style: "asterisk" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..9988a1a --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,67 @@ +--- +default_stages: [pre-commit] + +default_install_hook_types: [pre-commit, commit-msg] + +exclude: (^vendor/|.*\.pdf$) + +ci: + autoupdate_commit_msg: 'pre-commit: autoupdate hooks' + autofix_prs: false + # docker is not supported on pre-commit.ci + skip: [lychee-docker] + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: check-added-large-files + - id: check-merge-conflict + - id: check-symlinks + - id: detect-private-key + - id: end-of-file-fixer + - id: trailing-whitespace + exclude: ^.*\.patch$ + - id: mixed-line-ending + exclude: ^.*\.patch$ + + - repo: https://github.com/talos-systems/conform + rev: v0.1.0-alpha.30 + hooks: + - id: conform + stages: + - commit-msg + + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + + - repo: https://github.com/adrienverge/yamllint + rev: v1.35.1 + hooks: + - id: yamllint + args: [-c=.yamllint] + + - repo: https://github.com/3mdeb/hooks + rev: v0.1.2 + hooks: + - id: namespell + args: [--fix] + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.41.0 + hooks: + - id: markdownlint + - id: markdownlint-fix + + - repo: https://github.com/lycheeverse/lychee + rev: v0.15.1 + hooks: + - id: lychee-docker + # Optionally include additional CLI arguments + args: [ + "--no-progress", "--exclude", "file://", "--exclude", "0.0.0.0", + "--exclude", ".git", "--include-verbatim", "--timeout", "10", + "--exclude-all-private", "-m", "10" + ] diff --git a/.yamllint b/.yamllint new file mode 100644 index 0000000..1a23bc1 --- /dev/null +++ b/.yamllint @@ -0,0 +1,16 @@ +--- +extends: default + +rules: + comments: + require-starting-space: true + ignore-shebangs: true + min-spaces-from-content: 2 + document-start: + present: true + level: error + indentation: + spaces: 2 + line-length: disable + truthy: + check-keys: false diff --git a/CNAME b/CNAME index a441a9b..75bf026 100644 --- a/CNAME +++ b/CNAME @@ -1 +1 @@ -trenchboot.org \ No newline at end of file +trenchboot.org diff --git a/LICENSE.md b/LICENSE.md index d7244c0..51fd889 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,159 +1,334 @@ -## creative commons +# creative commons # Attribution 4.0 International -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. - -### Using Creative Commons Public Licenses - -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. - -* __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). - -* __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). +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. + +## Using Creative Commons Public Licenses + +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. + +- **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). + +- **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). ## Creative Commons Attribution 4.0 International Public License -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. - -### Section 1 – Definitions. - -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. - -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. - -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. - -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. - -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. +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. + +### Section 1 – Definitions + +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. + +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. + +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. + +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. + +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. + +f. **Licensed Material** means the artistic or literary work, database, or other +material to which the Licensor applied this Public License. -f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. +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. -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. +h. **Licensor** means the individual(s) or entity(ies) granting rights under +this Public License. -h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. +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. -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. +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. -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. +k. **You** means the individual or entity exercising the Licensed Rights under +this Public License. Your has a corresponding meaning. -k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. +### Section 2 – Scope -### Section 2 – Scope. +a. _**License grant.**_ -a. ___License grant.___ +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: - 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: + A. reproduce and Share the Licensed Material, in whole or in part; and - A. reproduce and Share the Licensed Material, in whole or in part; and + B. produce, reproduce, and Share Adapted Material. - B. produce, reproduce, and Share Adapted Material. +1. **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. - 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. +1. **Term.** The term of this Public License is specified in Section 6(a). - 3. __Term.__ The term of this Public License is specified in Section 6(a). +1. **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. - 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. +1. **Downstream recipients.** - 5. __Downstream recipients.__ + 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. - 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. + 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. - 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. +1. **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). - 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). +b. _**Other rights.**_ -b. ___Other rights.___ +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. - 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. +1. Patent and trademark rights are not licensed under this Public License. - 2. Patent and trademark rights are not licensed under this Public License. +1. 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. - 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. +### Section 3 – License Conditions -### Section 3 – License Conditions. +Your exercise of the Licensed Rights is expressly made subject to the following +conditions. -Your exercise of the Licensed Rights is expressly made subject to the following conditions. +a. _**Attribution.**_ -a. ___Attribution.___ +1. If You Share the Licensed Material (including in modified form), You must: - 1. If You Share the Licensed Material (including in modified form), You must: + A. retain the following if it is supplied by the Licensor with the Licensed + Material: - A. retain the following if it is supplied by the Licensor with the Licensed Material: + 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); - 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); + ii. a copyright notice; - ii. a copyright notice; + iii. a notice that refers to this Public License; - iii. a notice that refers to this Public License; + iv. a notice that refers to the disclaimer of warranties; - iv. a notice that refers to the disclaimer of warranties; + v. a URI or hyperlink to the Licensed Material to the extent reasonably + practicable; - v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + B. indicate if You modified the Licensed Material and retain an indication of + any previous modifications; and - B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + 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. - 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. +1. 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. - 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. +1. If requested by the Licensor, You must remove any of the information required + by Section 3(a)(1)(A) to the extent reasonably practicable. - 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. +1. 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. - 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. +### Section 4 – Sui Generis Database Rights -### Section 4 – Sui Generis Database Rights. +Where the Licensed Rights include Sui Generis Database Rights that apply to Your +use of the Licensed Material: -Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: +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; -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; +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 -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 +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. -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. +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. -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. +### Section 5 – Disclaimer of Warranties and Limitation of Liability -### Section 5 – Disclaimer of Warranties and Limitation of Liability. +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.** -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.__ +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.** -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.__ +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. -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. +### Section 6 – Term and Termination -### Section 6 – Term and Termination. +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. -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. +b. Where Your right to use the Licensed Material has terminated under Section +6(a), it reinstates: -b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: +1. automatically as of the date the violation is cured, provided it is cured + within 30 days of Your discovery of the violation; or - 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or +1. upon express reinstatement by the Licensor. - 2. upon express reinstatement by the Licensor. +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. - 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. - -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. +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. d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. -### Section 7 – Other Terms and Conditions. - -a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. - -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. - -### Section 8 – Interpretation. - -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. - -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. - -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. - -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. - -> 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. +### Section 7 – Other Terms and Conditions + +a. The Licensor shall not be bound by any additional or different terms or +conditions communicated by You unless expressly agreed. + +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. + +### Section 8 – Interpretation + +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. + +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. + +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. + +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. + +> 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. > -> Creative Commons may be contacted at creativecommons.org +> > Creative Commons may be contacted at creativecommons.org diff --git a/_config.yml b/_config.yml deleted file mode 100644 index dd33aba..0000000 --- a/_config.yml +++ /dev/null @@ -1 +0,0 @@ -name: TrenchBoot diff --git a/docs/CNAME b/docs/CNAME index a441a9b..75bf026 100644 --- a/docs/CNAME +++ b/docs/CNAME @@ -1 +1 @@ -trenchboot.org \ No newline at end of file +trenchboot.org diff --git a/docs/FAQ.md b/docs/FAQ.md index f274466..01d92be 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,51 +1,51 @@ # TrenchBoot FAQ 1. [Why does TrenchBoot use an intermediate launcher?](#1-why-does-trenchboot-use-an-intermediate-launcher) -2. [What are the benefits of measurement over signature validation?](#2-what-are-the-benefits-of-measurement-over-signature-validation) -3. [What do I need to incorporate TrenchBoot into my system?](#3-what-do-i-need-to-incorporate-trenchboot-into-my-system) -4. [Where do I start if I want to help with contributions?](#4-where-do-i-start-if-i-want-to-help-with-contributions) +1. [What are the benefits of measurement over signature validation?](#2-what-are-the-benefits-of-measurement-over-signature-validation) +1. [What do I need to incorporate TrenchBoot into my system?](#3-what-do-i-need-to-incorporate-trenchboot-into-my-system) +1. [Where do I start if I want to help with contributions?](#4-where-do-i-start-if-i-want-to-help-with-contributions) ## 1. Why does TrenchBoot use an intermediate launcher? -For Linux systems doing both verified(secure) and measured boot, there is an -intermediary that handles the security enforcement. For verified boot it is the -UEFI shim loader and for measured boot it is tboot. TrenchBoot replaces these -intermediary loaders with a common Linux-based loader that provides a rich -security processing framework. One role that TrenchBoot does not fulfill is -that the UEFI shim also serves as a trust delegation point that transitions -from Microsoft Authority to Distribution/Installer/No Authority. The response -why this is not of concern will be addressed in Question 2. - +For Linux systems doing both verified(secure) and measured boot, there +is an intermediary that handles the security enforcement. For verified +boot it is the UEFI shim loader and for measured boot it is tboot. +TrenchBoot replaces these intermediary loaders with a common +Linux-based loader that provides a rich security processing framework. +One role that TrenchBoot does not fulfill is that the UEFI shim also +serves as a trust delegation point that transitions from Microsoft +Authority to Distribution/Installer/No Authority. The response why +this is not of concern will be addressed in Question 2. ## 2. What are the benefits of measurement over signature validation? -It is important to understand that one solution is not necessarily more -beneficial over the other. Measurement and Verification each have their merits -and it is important to understand the environment and requirements of the -solution. In the case of verification, it provides a one-time strong assertion -to origination and correctness that relies on Authorities and Control which -becomes brittle when dealing with delegating control. For example when -verification is being used as the Root of Trust that the transitive trust -builds upon, these solutions are strongest when the ecosystem is closed and -under control of a core entity. Where as measurement provides for establishing -a strong assertion to correctness that can be repeatedly extended and verified. -It therefore relies on the ability to know what correct is and to securely -verify measurement with expected correctness. - - -## 3. What do I need to incorporate TrenchBoot into my system? - -TrenchBoot is a framework that allows you to build a Linux kernel with a -tailored, embedded initramfs that functions as an intermediate loader to launch -your system. You will need to use the build system to select the security -engine components you desire, provide any necessary configurations, and build -an instance of the loader. After that, you configure your system boot to launch -the loader. - +It is important to understand that one solution is not necessarily +more beneficial over the other. Measurement and Verification each have +their merits and it is important to understand the environment and +requirements of the solution. In the case of verification, it provides +a one-time strong assertion to origination and correctness that relies +on Authorities and Control which becomes brittle when dealing with +delegating control. For example when verification is being used as the +Root of Trust that the transitive trust builds upon, these solutions +are strongest when the ecosystem is closed and under control of a core +entity. Where as measurement provides for establishing a strong +assertion to correctness that can be repeatedly extended and verified. +It therefore relies on the ability to know what correct is and to +securely verify measurement with expected correctness. + +## 3. What do I need to incorporate TrenchBoot into my system? + +TrenchBoot is a framework that allows you to build a Linux kernel with +a tailored, embedded initramfs that functions as an intermediate +loader to launch your system. You will need to use the build system to +select the security engine components you desire, provide any +necessary configurations, and build an instance of the loader. After +that, you configure your system boot to launch the loader. ## 4. Where do I start if I want to help with contributions? -The [TrenchBoot Blueprints](https://github.com/TrenchBoot/documentation/tree/master/blueprints) -are how feature requests are collected for the project. Check if there is a -blueprint that is of interested, if not, submit a blueprint via a pull request -for a feature you would like to see implemented. +The +[TrenchBoot Blueprints](https://github.com/TrenchBoot/documentation/tree/master/blueprints) +are how feature requests are collected for the project. Check if there +is a blueprint that is of interested, if not, submit a blueprint via a +pull request for a feature you would like to see implemented. diff --git a/docs/assets/3mdeb_logo.svg b/docs/assets/3mdeb_logo.svg index c90cfde..07b05a5 100644 --- a/docs/assets/3mdeb_logo.svg +++ b/docs/assets/3mdeb_logo.svg @@ -103,4 +103,4 @@ id="circle22" style="fill:#38d430" /> - \ No newline at end of file + diff --git a/docs/assets/style.css b/docs/assets/style.css index 82db720..16080e2 100644 --- a/docs/assets/style.css +++ b/docs/assets/style.css @@ -1,4 +1,3 @@ - @import url("https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600"); /* use image for color theme */ diff --git a/docs/blueprints/.pages.yml b/docs/blueprints/.pages.yml deleted file mode 100644 index 678e656..0000000 --- a/docs/blueprints/.pages.yml +++ /dev/null @@ -1,2 +0,0 @@ -nav: - - ... \ No newline at end of file diff --git a/docs/blueprints/AMD_Grub_Late_Launch.md b/docs/blueprints/AMD_Grub_Late_Launch.md index 03ec9f8..cb48130 100644 --- a/docs/blueprints/AMD_Grub_Late_Launch.md +++ b/docs/blueprints/AMD_Grub_Late_Launch.md @@ -1,33 +1,34 @@ -AMD Grub Late Launcher -====================== +# AMD Grub Late Launcher ## Purpose -The intent of this project is to extend Grub with the ability to call the AMD -SKINIT instruction. +The intent of this project is to extend Grub with the ability to call +the AMD SKINIT instruction. ## Background The AMD SKINIT instruction is a means to initiate a "late launch" that -establishes a Dynamic Root of Trust Measurement (DRTM). The instruction call -requires the system to be in a specific state as enumerated below, - * SVM check, either the `EFER.SVME` bit is set to 1 or the feature flag `CPUID - Fn8000_0001_ECX[SKINIT]` is set to 1 - * The CPU must be in protected mode - * All microcode needs to be unloaded +establishes a Dynamic Root of Trust Measurement (DRTM). The +instruction call requires the system to be in a specific state as +enumerated below, + +- SVM check, either the `EFER.SVME` bit is set to 1 or the feature + flag `CPUID Fn8000_0001_ECX[SKINIT]` is set to 1 +- The CPU must be in protected mode ## Approach Grub will be extended with the following capabilities, - * An SKINIT relocator that will, + +- Extend the late launch loader, + 1. determine CPU type and select SKINIT or SENTER path + 1. load kernel (with modules, if applicable) as usual + 1. verify SVM is supported + 1. load Secure Kernel Loader and check if it is valid + 1. allocate and fill Secure Launch Resource Table + 1. send INIT IPI to all APs + 1. disable all TPM localities +- An SKINIT relocator that will, 1. set protected mode - 2. enable APIC - 3. verify no machine check in progress - 4. clear machine check regs - 5. SKINIT as final instruction - * A late launch loader that will, - 1. load kernel starting at 0x100000, compatibility with a Linux Secure Loader - 2. verify SVM is supported - 3. disable all TPM localities - 4. evict microcode - 5. send INIT IPI to all APs + 1. set registers as required by SKINIT + 1. execute SKINIT as final instruction diff --git a/docs/blueprints/AMD_Landing_Zone.md b/docs/blueprints/AMD_Landing_Zone.md deleted file mode 100644 index bd9ac92..0000000 --- a/docs/blueprints/AMD_Landing_Zone.md +++ /dev/null @@ -1,89 +0,0 @@ -AMD Landing Zone -================ - -## Purpose - -The intent of this project is to implement the earliest code that is launched by -a DL Event on AMD platforms. - -## Background - -Contrary to the TXT solution, SKINIT is a single CPU instruction after which the -execution is passed to the user-provided block of code, called Secure Loader in -AMD documents. To some extent, this code can be treated as the AMD equivalent of -ACM, except that it doesn't have to be signed by the CPU vendor. - -SKINIT extends PCR17 with the hash of SL, which size is specified in the SL -header (maximum of 64K - 1), protects SLB (Secure Launch Block, always 64K) -against DMA access from the devices, puts the CPU in defined execution state and -jumps to the entry point also specified in the header. At the entry point to the -SL the CPU works in flat 32-bit protected mode with paging disabled. Most -general purpose registers are cleared. Interrupts are disabled (held pending -until re-enabled), including NMI, SMI and INIT. Refer to [AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) -for more details. - -Landing Zone is an implementation of Secure Loader. - -## Approach - -This is a high-level overview of tasks performed by Landing Zone: -1. set GDT and segment registers (only CS and SS are valid after SKINIT) -2. enable Long Mode (optional) -3. initialize TPM interface -4. initialize TPM event log - * log what was done by SKINIT -5. extend PCR18 with the hash of data passed by the bootloader to the LZ - * log that event -6. obtain information about the kernel from the data provided by a bootloader, - most notably: - * kernel location - * kernel size - * entry point -7. extend PCR17 with the hash of the kernel - * log that event -8. set CPU registers according to the kernel boot protocol -9. jump to the entry point of kernel - -### Things that yet have to be implemented - -#### DMA protection must be extended to cover any additional code and data - -This includes mainly kernel and zero page. As of now, it is impossible to do -this securely. - -[AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) -states that it should be done with DEV (Device Exclusion Vector), but that is no -longer implemented on new CPUs, except for initial SLB protection (starting with -Family 17h, even that protection is handled differently). - -DEV was surpassed by the [IOMMU](https://www.amd.com/system/files/TechDocs/48882_IOMMU_3.05_PUB.pdf). -It is much more capable than DEV, but it also requires more data and code to set -up. Those are not atomic operations, data must be first written to memory by the -CPU, then CPU sends information to the IOMMU that it can parse that data, and -only then the IOMMU actually reads that memory. A rogue device could potentially -modify that data in the meantime, so it all should happen in the protected part -of the memory. - -The issue is that IOMMU is also treated as a device, so it cannot access the -memory protected by the DEV (or what's left of it). There are two possible -options, both of which result in window of opportunity for unauthorized change -of the memory: -* turn off the SLB protection before sending commands to the IOMMU -* build IOMMU structures outside of SLB - -The second approach requires also that the space for those structures is -reserved and that LZ knows about its location. - -## Build options - -There are 3 configurable options, specified as command line parameters for -`make`. All of them are disabled by default, they can be enabled by running -`make =y`, where `` is one of the flags listed below. Note that -between builds with different sets of options you **must** run `make clean`. - -* **LTO** - link time optimizations. Generally reduces the size of resulting - binary and execution time, but the exact difference is hard to predict. -* **32** - do not jump to 64b mode. Saves 7*4 KB by not producing paging tables, - and some additional space because of shorter GDT and less strict padding. -* **DEBUG** - enable debug output on serial port (0x3f8). Increases the size by - about 1.3 KB. diff --git a/docs/blueprints/AMD_Secure_Kernel_Loader.md b/docs/blueprints/AMD_Secure_Kernel_Loader.md new file mode 100644 index 0000000..d3666b2 --- /dev/null +++ b/docs/blueprints/AMD_Secure_Kernel_Loader.md @@ -0,0 +1,105 @@ +# AMD Secure Kernel Loader + +## Purpose + +The intent of this project is to implement the earliest code that is +launched by a DL Event on AMD platforms. + +## Background + +Contrary to the TXT solution, SKINIT is a single CPU instruction after +which the execution is passed to the user-provided block of code, +called Secure Loader in AMD documents. To some extent, this code can +be treated as the AMD equivalent of ACM, except that it doesn't have +to be signed by the CPU vendor. + +SKINIT extends PCR17 with the hash of SL (Secure Loader), which size +is specified in the SL header (maximum of 64K - 1), protects SLB +(Secure Launch Block, always 64K) against DMA access from the devices, +puts the CPU in defined execution state and jumps to the entry point +also specified in the header. At the entry point to the SL the CPU +works in flat 32-bit protected mode with paging disabled. Most general +purpose registers are cleared. Interrupts are disabled (held pending +until re-enabled), including NMI, SMI and INIT. Refer to +[AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) +for more details. + +Secure Kernel Loader (SKL) is an implementation of Secure Loader. + +## Approach + +This is a high-level overview of tasks performed by Secure Kernel +Loader: + +1. set GDT and segment registers (only CS and SS are valid after + SKINIT) +1. set up pagetables and enable Long Mode (optional, see `BITS` in + [Build options](#build-options)) +1. initialize TPM interface +1. initialize TPM event log + - log what was done by SKINIT +1. extend PCR18 with the hash of SLRT (Secure Launch Resource Table) + passed by the bootloader to the SKL + - log that event +1. obtain information about the kernel from SLRT provided by a + bootloader, most notably: + - kernel location + - kernel size + - entry point +1. extend PCR17 with the hash of the kernel + - log that event +1. set CPU registers according to the kernel boot protocol +1. jump to the entry point of kernel + +### Things that yet have to be implemented + +#### DMA protection must be extended to cover any additional code and data + +This includes mainly kernel and its configuration data passed from a +bootloader, to a lesser extend also modules (kernel could set the +protections for modules, it doesn't have to be done by SKL). As of +now, it is impossible to do this securely. + +[AMD APM Vol 2](../references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf) +states that it should be done with DEV (Device Exclusion Vector), but +that is no longer implemented on new CPUs, except for initial SLB +protection (starting with Family 17h, even that protection is handled +differently). + +DEV was surpassed by the +[IOMMU](https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/specifications/48882_IOMMU.pdf). +It is much more capable than DEV, but it also requires more data and +code to set up. Those are not atomic operations, data must be first +written to memory by the CPU, then CPU sends information to the IOMMU +that it can parse that data, and only then the IOMMU actually reads +that memory. A rogue device could potentially modify that data in the +meantime, so it all should happen in the protected part of the memory. + +The issue is that IOMMU is also treated as a device, so it cannot +access the memory protected by the DEV (or what's left of it). There +are two possible options, both of which result in window of +opportunity for unauthorized change of the memory: + +- turn off the SLB protection before sending commands to the IOMMU +- build IOMMU structures outside of SLB + +The second approach requires also that the space for those structures +is reserved and that SKL knows about its location. + +## Build options + +There are 3 configurable options, specified as command line parameters +for `make`. All of them are disabled by default, they can be enabled +by running `make =`, where `` is one of the flags +listed below. Note that between builds with different sets of options +you _must_ run `make clean`. + +- `LTO` - link time optimizations. Generally reduces the size of + resulting binary and execution time, but the exact difference is + hard to predict. Possible values: `n` (default), `y`. +- `BITS` - choose between 64b and 32b mode for SKL. 32b mode saves + 7\*4 KB by not producing paging tables, but due to lower number of + available registers, the code itself is about 0.5 KB larger, so net + gain is just under 28 KB. Possible values: `64` (default), `32`. +- `DEBUG` - enable debug output on serial port (0x3f8). Increases the + size by about 1.3 KB. Possible values: `n` (default), `y`. diff --git a/docs/blueprints/Linux_Late_Launch.md b/docs/blueprints/Linux_Late_Launch.md index f0fe0a1..6c338d8 100644 --- a/docs/blueprints/Linux_Late_Launch.md +++ b/docs/blueprints/Linux_Late_Launch.md @@ -1,39 +1,40 @@ -Linux Late Launch Kernel -======================== +# Linux Late Launch Kernel ## Summary -The Linux kernel will be extended to make it function as the late launch kernel -for both AMD (Secure Loader) and Intel TXT (Measured Launch Environment). +The Linux kernel will be extended to make it function as the late +launch kernel for both AMD (Secure Loader) and Intel TXT (Measured +Launch Environment). ## Background The late launch process provides a means to measure a target execution -environment and then jump into the environment as presribed by the CPU's late -launch protocol. This process provides a means by which to a establish a -hardware-based Root of Trust for Measurement (RTM). The implementation here -will provide a means to launch the Linux kernel as an RTM envrionment to enable -building trust in a platform's launch. +environment and then jump into the environment as presribed by the +CPU's late launch protocol. This process provides a means by which to +a establish a hardware-based Root of Trust for Measurement (RTM). The +implementation here will provide a means to launch the Linux kernel as +an RTM environment to enable building trust in a platform's launch. ## Approach A preliminary approach is as follows, - * Create a late-launch landing zone (LZ) in 64k real code section of Linux - kernel header - * Sanitize any CPU state passed through late launch - * Verify LZ signature with pubkey - * Verify measurement from LZ signature against CRTM - * (AMD) Create/Setup TPM Event log - * Extend hash of pubkey into PCR 18, record in event log - * This aligns to TXT's DA scheme - * Parse Linux header to detect relevant details about kernel - * DEV/DMAR protect remainder of Linux kernel - * Extend hash of Linux kernel into PCR 17, record in event log - * Prepare and then handoff to Linux kernel proper - * Need to support Legacy/CSM and UEFI environments - * Add a new start/launch path to Linux kernel - * Secure rendezvous APUs - * Process system state passed up from LZ - * e.g. memory map, etc. - * Setup Linux state for handover to mainline start up - * Jump into mainline start up + +- Create a late-launch landing zone (LZ) in 64k real code section of + Linux kernel header +- Sanitize any CPU state passed through late launch +- Verify LZ signature with pubkey +- Verify measurement from LZ signature against CRTM +- (AMD) Create/Setup TPM Event log +- Extend hash of pubkey into PCR 18, record in event log +- This aligns to TXT's DA scheme +- Parse Linux header to detect relevant details about kernel +- DEV/DMAR protect remainder of Linux kernel +- Extend hash of Linux kernel into PCR 17, record in event log +- Prepare and then handoff to Linux kernel proper +- Need to support Legacy/CSM and UEFI environments +- Add a new start/launch path to Linux kernel +- Secure rendezvous APUs +- Process system state passed up from LZ + + e.g. memory map, etc. +- Setup Linux state for handover to mainline start up +- Jump into mainline start up diff --git a/docs/blueprints/Measured_Secure_Boot.md b/docs/blueprints/Measured_Secure_Boot.md index b031b41..290bda4 100644 --- a/docs/blueprints/Measured_Secure_Boot.md +++ b/docs/blueprints/Measured_Secure_Boot.md @@ -1,61 +1,65 @@ -Measured Secure Boot -==================== +# Measured Secure Boot ## Purpose -To build a Measured Secure Boot (MSB) implementation that uses a hardware based -Root of Trust for Measurement (RTM) from which to build a Root of Trust for -Verification (RTV). +To build a Measured Secure Boot (MSB) implementation that uses a +hardware based Root of Trust for Measurement (RTM) from which to build +a Root of Trust for Verification (RTV). ## Background -To date the only supported Late Launch environment is the tboot project which -is maintained by Intel for their Intel TXT capability. While tboot provides a -complete capability, it is limited and has a number of deficiencies. While it -would be possible to build a Measured Secure Boot solution around tboot, it -will still be limited in comparison to approach provided by this blueprint. - -Before detailing the approach and the improvements it provides, it is good to -understand how the tboot environment works. Before tboot can run, it must be -loaded into memory along with the target kernel it will launch into by either a -legacy multiboot compliant bootloader or by an UEFI boot manager. Tboot itself -is composed of two main parts, pre-launch and post-launch execution paths. Below -is a top-level execution flow for tboot from boot loader/manager to the trusted +To date the only supported Late Launch environment is the tboot +project which is maintained by Intel for their Intel TXT capability. +While tboot provides a complete capability, it is limited and has a +number of deficiencies. While it would be possible to build a Measured +Secure Boot solution around tboot, it will still be limited in +comparison to approach provided by this blueprint. + +Before detailing the approach and the improvements it provides, it is +good to understand how the tboot environment works. Before tboot can +run, it must be loaded into memory along with the target kernel it +will launch into by either a legacy multiboot compliant bootloader or +by an UEFI boot manager. Tboot itself is composed of two main parts, +pre-launch and post-launch execution paths. Below is a top-level +execution flow for tboot from boot loader/manager to the trusted kernel that will be given control. -``` +```text |-- tboot --| boot ldr/mngr --load--> pre-launch --SENTER--> post-launch --launch--> trusted kernel ``` -In terms of integrity policy, tboot policy can only be used to measure and -verify any multiboot modules loaded by the boot loader/manager. Typically tboot -policy is used in one of two manners, enforcing and non-enforcing. In both -cases the policy is used to control what tboot will measure and which PCRs -those measurements are stored. When an enforcing policy is in place, the -measurements are compared with values populated in the policy and will take -a selected action when the measurements do not match. With a non-enforcing -policy, measurement comparison is not done and it is left to the trusted -kernel to take action on the measurements. This means if advanced actions other -than measurement verification is desired, then the trusted kernel must be aware -and made to take the actions. +In terms of integrity policy, tboot policy can only be used to measure +and verify any multiboot modules loaded by the boot loader/manager. +Typically tboot policy is used in one of two manners, enforcing and +non-enforcing. In both cases the policy is used to control what tboot +will measure and which PCRs those measurements are stored. When an +enforcing policy is in place, the measurements are compared with +values populated in the policy and will take a selected action when +the measurements do not match. With a non-enforcing policy, +measurement comparison is not done and it is left to the trusted +kernel to take action on the measurements. This means if advanced +actions other than measurement verification is desired, then the +trusted kernel must be aware and made to take the actions. ## Approach -The x86 Late Launch capability will be used to establish an RTM using a Dynamic -Root of Trust Measurement (DRTM) that will include the device owner's RSA -public key. The Late Launch will start a TrenchBoot Security Engine (TSE) that -is capable of simple measurement verification similar to tboot, but will be -able to do advance actions such as a KMIP attestation for device encryption -key. - -MSB will consist of an enhancement to the GNU GRUB bootloader (grub), an -extended Linux kernel, and the uroot initramfs environment. The enhancement to -grub will be to add TPM 1.2/2.0 support along with relocators for AMD and Intel -Late Launch instructions. The Linux kernel will be extend to function as a -post-launch kernel that will run the TSE. Details for each of these are -documented in their own respective blueprints. Finally, below is the execution -flow for MSB for comparison with tboot's execution flow above. -``` +The x86 Late Launch capability will be used to establish an RTM using +a Dynamic Root of Trust Measurement (DRTM) that will include the +device owner's RSA public key. The Late Launch will start a TrenchBoot +Security Engine (TSE) that is capable of simple measurement +verification similar to tboot, but will be able to do advance actions +such as a KMIP attestation for device encryption key. + +MSB will consist of an enhancement to the GNU GRUB bootloader (grub), +an extended Linux kernel, and the uroot initramfs environment. The +enhancement to grub will be to add TPM 1.2/2.0 support along with +relocators for AMD and Intel Late Launch instructions. The Linux +kernel will be extend to function as a post-launch kernel that will +run the TSE. Details for each of these are documented in their own +respective blueprints. Finally, below is the execution flow for MSB +for comparison with tboot's execution flow above. + +```shell grub --SENTER/SKINIT--> Linux/TSE --kexec--> trusted kernel ``` diff --git a/docs/blueprints/TXT_Grub_Late_Launch.md b/docs/blueprints/TXT_Grub_Late_Launch.md index 5452c22..dbc3582 100644 --- a/docs/blueprints/TXT_Grub_Late_Launch.md +++ b/docs/blueprints/TXT_Grub_Late_Launch.md @@ -1,31 +1,32 @@ -TXT Grub Late Launcher -====================== +# TXT Grub Late Launcher ## Purpose -The intent of this project is to extend Grub with the ability to call the Intel -SENTER instruction. +The intent of this project is to extend Grub with the ability to call +the Intel SENTER instruction. ## Background -The Intel SENTER instruction is a means to initiate a "late launch" that -establishes a Dynamic Root of Trust Measuremnt (DRTM). The instruction call -requires the system to be in a specific state as enumerated below, +The Intel SENTER instruction is a means to initiate a "late launch" +that establishes a Dynamic Root of Trust Measurement (DRTM). The +instruction call requires the system to be in a specific state as +enumerated below, ## Approach Grub will be extended with the following capabilities, - * An SENTER relocator that will, - 1. set protected mode - 2. enable cache - 3. enable native FPU error reporting - 4. ensure not in virtual-8086 mode - 5. verify no machine check in progress - 6. parse GETSEC[PARAMETERS] - 7. clear machine check regs - 5. senter as final instruction - * Extend the late launch loader, - 1. Determine CPU type and select SKINIT or SENTER path + +- A late launch loader that will, + 1. verify SENTER is supported 1. load ACM and verify it matches platform - 2. verify SENTER is supported - 3. build pagetable for MLE + 1. build pagetable for MLE + 1. set types of cache as required by TXT + 1. enable native FPU error reporting + 1. verify no machine check in progress + 1. parse GETSEC\[PARAMETERS\] + 1. clear machine check registers + 1. allocate and fill Secure Launch Resource Table +- An SENTER relocator that will, + 1. set protected mode + 1. set registers as required by SENTER + 1. execute GETSEC\[SENTER\] as final instruction diff --git a/docs/blueprints/index.md b/docs/blueprints/index.md index 78fec93..d9a0bab 100644 --- a/docs/blueprints/index.md +++ b/docs/blueprints/index.md @@ -1,6 +1,6 @@ # Blueprints -Here you will find the design artifacts for built, in progress, and planned -security engine components. +Here you will find the design artifacts for built, in progress, and +planned security engine components. {nav} diff --git a/docs/code.md b/docs/code.md deleted file mode 100644 index 6166cff..0000000 --- a/docs/code.md +++ /dev/null @@ -1,14 +0,0 @@ -# Code Repositories - -Core project repositories for TrenchBoot project. - -* [GRUB SecureLaunch for Intel](https://github.com/TrenchBoot/grub/tree/intel-txt) - * Latest snapshot of Intel TXT support for GRUB -* [GRUB SecureLaunch for AMD](https://github.com/TrenchBoot/grub/tree/trenchboot_support_2.04) - * Latest snapshot of AMD SKINIT support for GRUB -* [Linux 5.13 SecureLaunch for Intel and AMD](https://github.com/TrenchBoot/linux/tree/linux-sl-5.13-amd) - * Latest snapshot Linux Secure Launch for Intel & AMD -* [Secure Kernel Loader](https://github.com/TrenchBoot/secure-kernel-loader) - * Implementation of the AMD Secure Loader specification for SKINIT -* [Tools for Linux SecureLaunch](https://github.com/TrenchBoot/sltools) - * A suite of tools for development, debugging, and launch status. diff --git a/docs/community.md b/docs/community.md index b26ae84..8a58ffa 100644 --- a/docs/community.md +++ b/docs/community.md @@ -1,6 +1,5 @@ +# How to get in contact with the team -How to get in contact with the team. - -* [TrenchBoot Google Group](https://groups.google.com/g/trenchboot-devel) -* [Twitter](https://twitter.com/TrenchBoot) -* [#trenchboot channel on OSFW Slack](https://slack.osfw.dev) +- [TrenchBoot Google Group](https://groups.google.com/g/trenchboot-devel) +- [Twitter](https://twitter.com/TrenchBoot) +- [#trenchboot channel on OSFW Slack](https://slack.osfw.dev) diff --git a/docs/dev-docs/CONTRIBUTING.md b/docs/dev-docs/CONTRIBUTING.md new file mode 100644 index 0000000..71a66f0 --- /dev/null +++ b/docs/dev-docs/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# Contributing to TrenchBoot + +We love your input! We want to make contributing to this project as +easy and transparent as possible, whether it's: + +- Reporting a bug +- Discussing the current state of the code +- Submitting a fix +- Proposing new features +- Becoming a maintainer + +## Project Structure + +The functionality being developed under TrenchBoot are cross-cutting +capabilities that span multiple open source projects. The role of +TrenchBoot is to function as both a development as well as a +cross-project integration project. As such it maintains a set of +repository clones of upstream project(s) that TrenchBoot conducts +development within. + +### Upstream Repository + +For each upstream repository within TrenchBoot will have at least one +maintainer. The maintainer(s) will have merge permissions and +responsible for maintaining adherence to upstream practices. When +necessary, they are responsible for maintaining out-of-tree +capabilities developed by TrenchBoot. + +#### Upstream Focus + +One of the primary objectives for TrenchBoot is to deliver +interoperable launch integrity capabilities to existing open source +projects involved with the system boot cycle. Under this objective, +all development against an upstream project must comply with upstream +coding style and strive to minimize disruption/breakage of upstream +capabilities. + +#### Out of Tree Maintenance + +There may be a case that a TrenchBoot capability may encounter a slow +adoption by an upstream project which results in multiple upstream +releases without the capability merged. As such the capability in +question must be kept in sync with upstream changes. While this +situation is not desired, it is likely to occur and will be the +responsibility of the respective TrenchBoot maintainer(s). + +### TrenchBoot Original Repositories + +While the focus is on delivering capabilities into upstream projects, +it is possible that a new or derivative code base may result to +fulfill a role in a cross-cutting capability. The maintainer(s) for +these code bases will be responsible for establishing coding styles +and licensing that ensure compliance with all other TrenchBoot +relevant projects. + +## Development + +We use github to host the project, to include tracking issues and +feature requests, as well as accept pull requests. + +### Development Flow Overview + +Pull requests are the best way to propose changes to the project (we +use +[Github Flow](https://guides.github.com/introduction/flow/index.html)). +We actively welcome your pull requests: + +1. Fork the repo and create your branch from `master`. +1. If you've added code that should be tested, add tests. +1. If you've changed APIs, update the documentation. +1. Ensure the test suite passes. +1. Make sure your code lints. +1. Issue that pull request! + +### Contribution Licensing + +TrenchBoot is a cross-community integration project consisting of +project repositories along with upstream project repositories. All +contributions to a repository are made under the license that covers +all work in that repository. + +### Issue Tracking + +Report issues, e.g. bugs, feature requests, etc., using Github's +[issues](https://github.com/briandk/transcriptase-atom/issues) + +**Great Issues** tend to have: + +- A quick summary and/or background +- For bug reports include: + + Steps to reproduce for bugs + - Be specific! + - Give sample code if you can. + + What you expected would happen + + What actually happens + + Notes (possibly including why you think this might be happening, + or stuff you tried that didn't work) +- For feature requests include: + + An outline of how the feature would work + + Any dependencies the feature would require + + The benefit the feature will provide + +### Coding Style + +Markdown documents should be formatted to 80 columns to the extent +possible. Exception to the 80 column is when column limitation breaks +markdown rendering. + +Contributions targeting upstream project repositories will follow the +upstream project's coding style rules. + +## License + +[![License: CC BY 4.0](https://i.creativecommons.org/l/by/4.0/88x31.png)](https://creativecommons.org/licenses/by/4.0/) +This work is licensed under a +[Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). +By contributing you agree that your contributions will be licensed +under the Creative Commons Attribution 4.0 International License. Feel +free to contact the maintainers if that's a concern. + +## Contacting Maintainers + +TrenchBoot is maintained by: + +- Daniel P. Smith + +# References + +This document was adapted from the this open-source +[contribution template](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62/) diff --git a/docs/dev-docs/DevelopersGuide.md b/docs/dev-docs/DevelopersGuide.md new file mode 100644 index 0000000..ec775b9 --- /dev/null +++ b/docs/dev-docs/DevelopersGuide.md @@ -0,0 +1,28 @@ +# Developers Guide + +TrenchBoot is a framework that provides for users the ability to +select the kernel and security engine components appropriate for their +target environment. This developers guide focuses on the software +components of TrenchBoot and the build system used to compose +TrenchBoot launchable images. + +## TrenchBoot Linux/u-root Configuration + +A TrenchBoot launchable image consists of a TrenchBoot Linux kernel +with a TrenchBoot u-root initramfs embedded within the image. When +building for a target, the boot capabilities and BITs that will be +supported will result in different launchable images. The diagram +below provides a simple visual depiction of this setup. + +![Top level software architecture](../img/SoftwareArch.png) + +As a result of the build process, one or more kernel images may be +generated. By convention these kernels will be labeled as such: + +- bzImage.uefi: An image built to be launch by a UEFI environment +- bzImage.skinit: An image built to be launched with AMD's SKINIT + instruction +- bzImage.senter: An image built to be launched with Intel's SENTER + instruction +- bzImage.bios: An image build to be launched by a legacy BIOS boot + loader diff --git a/docs/dev-docs/Late_Launch_Overview.md b/docs/dev-docs/Late_Launch_Overview.md new file mode 100644 index 0000000..f1b4727 --- /dev/null +++ b/docs/dev-docs/Late_Launch_Overview.md @@ -0,0 +1,196 @@ +# Introduction to Late Launch + +This is an introduction of the "Late Launch" process on x86-based +systems to establish a Dynamic Root of Trust for Measurement (DRTM). +Late Launch is another name for a Dynamic Launch of a system for +x86-based platforms. As such it is good to understand the difference +between a Static Launch and a Dynamic Launch on x86 platforms. For x86 +the fixed location used for a Static Launch is known as the reset +vector which maps to SPI flash storage. A Dynamic Launch is achieved +with a light-weight processor bootstrap initiated through a CPU +instruction. For Intel the capability that provides this is called TXT +and is initiated with the GETSEC\[SENTER\], summarily SENTER, +instruction. For AMD it is considered part of AMD's secure +virtualization (AMD-V) and is initiated with the SKINIT instruction. + +An important function of x86 Late Launch CPU instructions is that they +"measure" the execution code provided for the launch. This action of +"measure" is accomplished by taking a cryptographic hash using an +algorithm supported by the TCG's Trusted Platform Module (TPM) so that +it may store the measurement within one of the TPM's Platform +Configuration Registers (PCR). This initial measurement, referred to +as the Core Root of Trust Measurement (CRTM), is the trust anchor for +the DRTM. + +While the Intel and AMD implementations of Late Launch both achieve a +DRTM, how their implementations arrive at a DRTM are significantly +different. As a result each will be addressed separately. + +## Intel Trusted eXecution Technology (TXT) + +For TXT, Intel set about a holistic approach\[^1\] that introduced the +Safer Mode Extensions (SMX) instruction set. As a result TXT provides +for advanced security capabilities such as measuring System Management +Mode (SMM) when an SMI Transfer Monitor (STM) is in place. The TXT +process is built around the SINIT Authenticated Code Module (ACM) and +a Measured Launch Environment (MLE). The ACM is a binary provided by +Intel and the MLE is a software solution typically provided by the OS +provider. Details about the ACM and the MLE are explained in the +"Intel TXT Measured Launch Environment Developer's Guide"\[^2\]. + +### SENTER Procedure + +From the moment when the SENTER instruction is invoked until execution +control is handed to the MLE, a series of computations are completed +by the CPU and then by the ACM to generate integrity assertions in the +form of measurements about the platform environment as well as the MLE +that will be given control. Details about the CPU's role in the launch +can be found in the Intel Software Developer's Manual (SDM) under Vol. +2D 6.2.3 para 3 and 6.3 GETSEC\[SENTER\]\[^3\]. The primary role for +the CPU is to establish an environment that minimizes the ability of +external tampering and taking the CRTM used for the DRTM. Below is an +outline of the internal steps that the CPU takes when the SENTER +instruction is initial invoked, + +1. Inhibit processor response to external events: INIT, A20M, NMI, and + SMI. +1. Establish and check the location and size of the authenticated code + module to be executed by the ILP. +1. Check for the existence of an Intel® TXT-capable chipset. +1. Verify the current power management configuration is acceptable. +1. Broadcast a message to enable protection of memory and I/O from the + activities of other processor agents. +1. Load the designated AC module into the authenticated code execution + area. +1. Isolate the content of the authenticated code execution area from + further state modification by external agents. +1. Authenticate the AC module. +1. Updated the Trusted Platform Module (TPM) with the authenticated + code module's hash. +1. Initialize processor state based on the authenticated code module + header information. +1. Unlock the Intel® TXT-capable chipset private configuration + register space and TPM locality 3 space. +1. Begin execution in the authenticated code module at the defined + entry point. + +### TXT ACM + +The ACM is the portion that is responsible for implementing the +advanced security capabilities provided by TXT. To achieve this, the +CPU provides a highly privileged execution mode that is capable of +inspecting System Management Mode (SMM) memory (SMRAM), this is needed +to allow the measurement of the STI. As a result it is highly +important that only authorized code is allowed to execute in this +mode. This is handled in step 8., the authentication of the ACM. The +details of this process can be found in section A.1.2 of the MLE +Developers Guide.\[^2\] The ACM is entrusted with a series of +responsibilities, ones of particular note are IOMMU protecting the +MLE, measuring the MLE, and the enforcement of the Launch Control +Policy (LCP). + +#### Launch Control Policy + +One of the capabilities provided by the ACM is the LCP Engine. The LCP +is a rarely used mechanism to enforce that a known environment is +being used. Within the ACM is an LCP engine that will look for a LCP +in a designated TPM NVRAM address. The LCP allows for defining +expected values for TPM PCRs and/or the expected hash value of the +MLE. If a policy check fails, then the LCP Policy Engine will trigger +the ACM to error exit from the SENTER instruction. + +### Measured Launch Environment + +The final component in the Intel TXT process is the MLE, a software +component that is responsible for the secure setup and execution of +the target runtime. As the ACM conducted a transitive trust extension +to the MLE, the MLE should similarly conduct a transitive trust +extension to bring the target runtime within the SMX trust boundary by +protecting the runtime's memory from tampering, measuring the runtime, +and optionally enforcing policy to ensure only authorized runtimes are +allowed to execute. + +## AMD Secure Startup + +The AMD approach is a simpler one that allows more control over code +executed by the SKINIT instruction, to include environment setup and +measurements, but unlike Intel's ACM, execution is limited to the same +accesses as superprivileged mode. This means it is not possible to +obtain a measurement of SMRAM at the time of the late launch. +Therefore the trust boundary of SKINIT still bound to the SRTM. To use +the Secure Startup capability, a Secure Loader (SL) image must be +loaded and passed to SKINIT. Details about building an SL and calling +the SKINIT instruction can be found in the AMD ARM64 Architecture +Programmer's Manual, Volume 2\[^4\]. + +### SKINIT Procedure + +When the SKINIT instruction is executed, the base address for the SL +is passed in the EAX register. The CPU will then execute the following +sequence, + +1. Reinitialize the processor state similar to INIT signal. +1. Enter 32bit protected mode with paging disabled. +1. Clear all general purpose registers except, + - EAX: start address of SL, + - EDX: CPU model, family, and stepping. +1. Secures registers, + - Most MSRs retain their values (except those which might + compromise SVM protections), + - EFER MSR is cleared, + - setting DPD, R_INIT and DIS_A20M flags in the VM_CR register + unconditionally to 1. +1. Page align EAX and use as the start address for 64KBytes of DEV + protection. +1. Securely initializes AP(s), + - clears Global Interrupt Flag (GIF), + - setting DPD, R_INIT and DIS_A20M flags in the VM_CR register. +1. Transmit SL image to TPM for hash, any failure will trigger SKINIT + failure. +1. Clear the GIF on the BSP which disables all interrupts, including + NMI, SMI, and INIT. +1. Update ESP to point at SL stack (SLB base + 65536). +1. Add SL entry offset to SL base and jump to that address. + +### Secure Loader + +In the AMD world, the initial code executed by the SKINIT instruction +is the Secure Loader (SL). The SL is an Owner provided code base that +is responsible for securely initializing the system and handover to a +Security Kernel (SK). The SL must meet three primary conditions, + +1. SL image's first two words (each 16bit) contain the entry point + offset and size of measured part of the image (code and initialized + data). +1. SL code and data (including stack) must be less than 64KBytes. +1. SL image must be loaded page aligned. + +Upon execution, the SL is responsible for protecting the remainder of +the execution environment through measurement and memory protection of +the SK to which it will be handing over control. + +### Security Kernel + +For AMD Secure Startup the last component is the SK. The SK can be an +intermediate kernel or a target runtime kernel. The situation that +drives the need for an intermediate kernel is for solutions that need +to do more complex security verification and/or hand-off to target +runtime kernel that cannot be implemented in less than 64Kbytes. + +## Foot Notes + +\[^1\]: Grawrock, D. (2006). The Intel safer computing initiative. +Hillsboro, Or.: Intel Press.
+ + +\[^2\]: Intel® Trusted Execution Technology (Intel® TXT) Software +Development Guide: Measured Launched Environment Developer’s +Guide
+ + +\[^3\]: Intel® 64 and IA-32 Architectures Software Developer’s Manual, +Combined Volumes: 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D and 4
+ + +\[^4\]: AMD64 Architecture Programmer’s Manual Volume 2: System +Programming
diff --git a/docs/dev-docs/code.md b/docs/dev-docs/code.md new file mode 100644 index 0000000..21f6d24 --- /dev/null +++ b/docs/dev-docs/code.md @@ -0,0 +1,14 @@ +# Code Repositories + +Core project repositories for TrenchBoot project. + +- [GRUB SecureLaunch for Intel](https://github.com/TrenchBoot/grub/tree/intel-txt) + + Latest snapshot of Intel TXT support for GRUB +- [GRUB SecureLaunch for AMD](https://github.com/TrenchBoot/grub/tree/trenchboot_support_2.04) + + Latest snapshot of AMD SKINIT support for GRUB +- [Linux 5.13 SecureLaunch for Intel and AMD](https://github.com/TrenchBoot/linux/tree/linux-sl-5.13-amd) + + Latest snapshot Linux Secure Launch for Intel & AMD +- [Secure Kernel Loader](https://github.com/TrenchBoot/secure-kernel-loader) + + Implementation of the AMD Secure Loader specification for SKINIT +- [Tools for Linux SecureLaunch](https://github.com/TrenchBoot/sltools) + + A suite of tools for development, debugging, and launch status. diff --git a/docs/dev-docs/index.md b/docs/dev-docs/index.md new file mode 100644 index 0000000..d95d88b --- /dev/null +++ b/docs/dev-docs/index.md @@ -0,0 +1,6 @@ +# TrenchBoot Documentation + +Here you will find documentation for building and deploying security +engine components. + +{nav} diff --git a/docs/documentation/.pages.yml b/docs/documentation/.pages.yml deleted file mode 100644 index d3b2b13..0000000 --- a/docs/documentation/.pages.yml +++ /dev/null @@ -1,3 +0,0 @@ -title: TrenchBoot Documentation -nav: - - ... \ No newline at end of file diff --git a/docs/documentation/Architecture.md b/docs/documentation/Architecture.md deleted file mode 100644 index a9976a7..0000000 --- a/docs/documentation/Architecture.md +++ /dev/null @@ -1,70 +0,0 @@ - -General Architecture -==================== - -The general execution flow for TrenchBoot is broken into three phases, -Bootstrap, Intermediate, and Runtime. The Bootstrap phase primarily consists of -the existing bootstrap technology, e.g. UEFI, grub, UEFI shim, etc. For -TrenchBoot the bootstrap technologies that have an integrity function, referred -to as a Boot Integrity Technology (BIT), are of primary interest. The -Intermediate phase is that which the TrenchBoot Loader executes to establish -the launch integrity of the system. The last phase is the Runtime phase and is -where the target runtime, hypervisor, operating system, etc, is -given control over the system. - -![Architecture Execution Flow](/img/Architectural_Flow.png) - - -# TrenchBoot Security Engine - -At the heart of the TrenchBoot Loader is the TrenchBoot Security Engine. The -Security Engine is responsible for processing any evidence collected by the -BITs, collecting new evidence as needed, evaluating all evidence according to -a security policy, and executing appropriate enforcement actions. The components -that enable this and their relationship can be seen in the top level diagram -below. - -![Architecture Execution Flow](/img/Arch_Flow.png) - -## Evidence - -A core concept in TrenchBoot is that of evidence. For TrenchBoot, evidence is a -record of an event that occurred within the system. The typical form for these -records is a cryptographic hash of the system state that was the result of this -event. This cryptographic hash is often referred to as a measurement. - -## Boot Integrity Technology - -Boot Integrity Technologies (BITs) are software or hardware capabilities that are -responsible for a portion of system launch. Specifically these capabilities -attempt to establish and/or enforce a degree of integrity that the correct -logic was used to launch the system. - -## BIT Augmentation - -There may be BITs that need be directly or indirectly extended to -enable or enhance their usage for launching a TrenchBoot environment. - -## BIT Ingestion - -A TrenchBoot Security Engine must be capable of supporting a variety of evidence -formats for the various BITs supported. Translation of these various formats allows -TrenchBoot to maintain normalized data structures for evidence collected. This -allows the functionality in Security Processor to only have to reason about -normalized data without specialized logic for different data formats. - -## Security Processor - -At the heart of a TrenchBoot Security Engine is the Security Processor. The -Security Processor consist of the logical components that will consume a launch -policy and take one or more actions to evaluate the state of the system -necessary to enforce the policy. This may include, but is not limited to, collecting -additional evidence, making attestation assertions, retrieving encryption keys, -and file/block/drive decryption. The enforcement of the security policy will -result in a full, partial, or failed boot of the system. - -## Launch/Hand Off - -Ultimately TrenchBoot's responsibility is to launch a target environment. As -such it must be equipped with the various ways required to launch those target -environments. diff --git a/docs/documentation/CI_infrastracture.md b/docs/documentation/CI_infrastracture.md deleted file mode 100644 index 7b08803..0000000 --- a/docs/documentation/CI_infrastracture.md +++ /dev/null @@ -1,30 +0,0 @@ -TrenchBoot CI infrastructure -============================ - -Pipelines ---- - -### Upstream - -* [nixos-trenchboot-configs](https://gitlab.com/trenchboot1/3mdeb/nixos-trenchboot-configs/-/pipelines) -* [landing-zone](https://gitlab.com/trenchboot1/trenchboot/landing-zone/-/pipelines) -* [grub-tb](https://gitlab.com/trenchboot1/trenchboot/grub/-/pipelines) -* [linux-tb](https://gitlab.com/trenchboot1/trenchboot/linux/-/pipelines) -* [meta-trenchboot](https://gitlab.com/trenchboot1/3mdeb/meta-trenchboot/-/pipelines) - -### Development - -* [landing-zone](https://gitlab.com/trenchboot1/3mdeb/landing-zone/-/pipelines) -* [grub-tb](https://gitlab.com/trenchboot1/3mdeb/grub/-/pipelines) -* [linux-tb](https://gitlab.com/trenchboot1/3mdeb/linux/-/pipelines) - ---- - -Job descriptions ---- - -* [nixos-trenchboot-configs](CI_jobs.md#nixos-trenchboot-configs) -* [landing-zone](CI_jobs.md#landing-zone) -* [grub-tb](CI_jobs.md#grub-tb) -* [linux-tb](CI_jobs.md#linux-tb) -* [meta-trenchboot](CI_jobs.md#meta-trenchboot) diff --git a/docs/documentation/CI_jobs.md b/docs/documentation/CI_jobs.md deleted file mode 100644 index 75ba2ad..0000000 --- a/docs/documentation/CI_jobs.md +++ /dev/null @@ -1,102 +0,0 @@ -# Jobs description - -## landing-zone - -### build_debug_disabled - -Job builds landing-zone with disabled debug option. - -### build_debug_enabled - -Job builds landing-zone with enabled debug option. - -### build_nixpgs_debug_disabled - -Job triggers building landing-zone NixOS package with disabled debug option. - -### build_nixpkgs_debug_enabled - -Job triggers building landing-zone NixOS package with enabled debug option. - ---- - -## grub-tb - -### build_and_install - -Job builds TrenchBoot version of the GRUB. Then installs the GRUB in the docker -and checks if required modules are available. - -### build_nixpkg - -Job triggers building the GRUB package for the NixOS. - ---- - -## linux-tb - -### build - -Job builds linux kernel with the secure launch driver. - -### build_nixpkg - -Job triggers building the NixOS package of the TrenchBoot linux kernel. - ---- - -## nixos-trenchboot-configs - -### build_lz_debug_disabled_local - -Job builds NixOS landing-zone package with disabled debug option. - -### build_lz_debug_enabled_local - -Job builds NixOS landing-zone package with enabled debug option. - -### build_grub - -Job builds NixOS package of the TrenchBoot GRUB. - -### build_linux - -Job builds NixOS package of the TrenchBoot linux kernel. - ---- - -## meta-trenchboot - -### build - -Job builds legacy Yocto TrenchBoot for the PC Engines apu2. - -### build_uefi - -Job builds UEFI Yocto TrenchBoot image for generic x86-64 hardware. - -### test_boot_apu2 - -Job installs the legacy Yocto TrenchBoot image on the the PC Engines apu2. -Then boot the platform without and with DRTM. In the end the job verifies, -if PCR values correspond to manually extended. - -### test_boot_asrock - -Job installs the UEFI Yocto TrenchBoot image on the the ASRock-R1000V. -Then boot the platform without and with DRTM. In the end the job verifies, -if PCR values correspond to manually extended. - -### test_boot_supermicro - -Job installs the UEFI Yocto TrenchBoot image on the Supermicro M11SDV-8CT-LN4F. -Then boot the platform without and with DRTM. In the end the job verifies, -if PCR values correspond to manually extended. - ---- - -## Test infrastructure - -* [PC Engines apu2](https://www.pcengines.ch/apu2.htm) -* [ASRock-R1000V](https://www.asrockind.com/en-gb/4X4%20BOX-R1000V) -* [Supermicro M11SDV-8CT-LN4F](https://www.supermicro.com/en/products/motherboard/M11SDV-8CT-LN4F) diff --git a/docs/documentation/CONTRIBUTING.md b/docs/documentation/CONTRIBUTING.md deleted file mode 100644 index a48286e..0000000 --- a/docs/documentation/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ -# Contributing to TrenchBoot - -We love your input! We want to make contributing to this project as easy and -transparent as possible, whether it's: - -- Reporting a bug -- Discussing the current state of the code -- Submitting a fix -- Proposing new features -- Becoming a maintainer - -## Project Structure - -The functionality being developed under TrenchBoot are cross-cutting -capabilities that span multiple open source projects. The role of TrenchBoot -is to function as both a development as well as a cross-project integration -project. As such it maintains a set of repository clones of upstream -project(s) that TrenchBoot conducts development within. - -### Upstream Repository - -For each upstream repository within TrenchBoot will have at least one maintainer. -The maintainer(s) will have merge permissions and responsible for maintaining -adherence to upstream practices. When necessary, they are responsible for -maintaining out-of-tree capabilities developed by TrenchBoot. - -#### Upstream Focus - -One of the primary objectives for TrenchBoot is to deliver interoperable launch -integrity capabilities to existing open source projects involved with the -system boot cycle. Under this objective, all development against an upstream -project must comply with upstream coding style and strive to minimize -disruption/breakage of upstream capabilities. - -#### Out of Tree Maintenance - -There may be a case that a TrenchBoot capability may encounter a slow adoption -by an upstream project which results in multiple upstream releases without the -capability merged. As such the capability in question must be kept in sync with -upstream changes. While this situation is not desired, it is likely to occur -and will be the responsibility of the respective TrenchBoot maintainer(s). - -### TrenchBoot Original Repositories - -While the focus is on delivering capabilities into upstream projects, it is -possible that a new or derivative code base may result to fulfill a role in a -cross-cutting capability. The maintainer(s) for these code bases will be -responsible for establishing coding styles and licensing that ensure compliance -with all other TrenchBoot relevant projects. - -## Development - -We use github to host the project, to include tracking issues and feature -requests, as well as accept pull requests. - -### Development Flow Overview - -Pull requests are the best way to propose changes to the project (we use -[Github Flow](https://guides.github.com/introduction/flow/index.html)). We -actively welcome your pull requests: - -1. Fork the repo and create your branch from `master`. -2. If you've added code that should be tested, add tests. -3. If you've changed APIs, update the documentation. -4. Ensure the test suite passes. -5. Make sure your code lints. -6. Issue that pull request! - -### Contribution Licensing - -TrenchBoot is a cross-community integration project consisting of project -repositories along with upstream project repositories. All contributions to a -repository are made under the license that covers all work in that repository. - -### Issue Tracking - -Report issues, e.g. bugs, feature requests, etc., using Github's -[issues](https://github.com/briandk/transcriptase-atom/issues) - -**Great Issues** tend to have: - -- A quick summary and/or background -- For bug reports include: - - Steps to reproduce for bugs - - Be specific! - - Give sample code if you can. - - What you expected would happen - - What actually happens - - Notes (possibly including why you think this might be happening, or stuff - you tried that didn't work) -- For feature requests include: - - An outline of how the feature would work - - Any dependecies the feature would require - - The benefit the feature will provide - -### Coding Style - -Markdown documents should be formatted to 80 columns to the extent possible. -Exception to the 80 column is when column limitation breaks markdown rendering. - -Contributions targeting upstream project repositories will follow the upstream -project's coding style rules. - -## License -[![License: CC BY 4.0](https://i.creativecommons.org/l/by/4.0/88x31.png) -](https://creativecommons.org/licenses/by/4.0/) This work is licensed under a -[Creative Commons Attribution 4.0 International -License](http://creativecommons.org/licenses/by/4.0/). By contributing you -agree that your contributions will be licensed under the Creative Commons -Attribution 4.0 International License. Feel free to contact the maintainers if -that's a concern. - -## Contacting Maintainers - -TrenchBoot is maintained by: - - Daniel P. Smith - -# References -This document was adapted from the this open-source [contribution -template](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62/) diff --git a/docs/documentation/DevelopersGuide.md b/docs/documentation/DevelopersGuide.md deleted file mode 100644 index f159e90..0000000 --- a/docs/documentation/DevelopersGuide.md +++ /dev/null @@ -1,25 +0,0 @@ -Developers Guide -================ - -TrenchBoot is a framework that provides for users the ability to select the -kernel and security engine components appropriate for their target environment. -This developers guide focuses on the software components of TrenchBoot and the -build system used to compose TrenchBoot launchable images. - -## TrenchBoot Linux/u-root Configuration - -A TrenchBoot launchable image consists of a TrenchBoot Linux kernel with a -TrenchBoot u-root initramfs embedded within the image. When building for a target, -the boot capabilities and BITs that will be supported will result in different -launchable images. The diagram below provides a simple visual depiction of this -setup. - -![Top level software architecture](/img/SoftwareArch.png) - -As a result of the build process, one or more kernel images may be generated. -By convention these kernels will be labeled as such: - -* bzImage.uefi: An image built to be launch by a UEFI environment -* bzImage.skinit: An image built to be launched with AMD's SKINIT instruction -* bzImage.senter: An image built to be launched with Intel's SENTER instruction -* bzImage.bios: An image build to be launched by a legacy BIOS boot loader diff --git a/docs/documentation/Late_Launch_Overview.md b/docs/documentation/Late_Launch_Overview.md deleted file mode 100644 index 0c31659..0000000 --- a/docs/documentation/Late_Launch_Overview.md +++ /dev/null @@ -1,183 +0,0 @@ -Introduction to Late Launch -=========================== - -This is an introduction of the "Late Launch" process on x86-based systems to -establish a Dynamic Root of Trust for Measurement (DRTM). Late Launch is -another name for a Dynamic Launch of a system for x86-based platforms. As such -it is good to understand the difference between a Static Launch and a Dynamic -Launch on x86 platforms. For x86 the fixed location used for a Static Launch -is known as the reset vector which maps to SPI flash storage. A Dynamic Launch -is achieved with a light-weight processor bootstrap initiated through a CPU -instruction. For Intel the capability that provides this is called TXT and is -initiated with the GETSEC[SENTER], summarily SENTER, instruction. For AMD it is considered part -of AMD's secure virtualization (AMD-V) and is initiated with the SKINIT -instruction. - -An important function of x86 Late Launch CPU instructions is that they -"measure" the execution code provided for the launch. This action of "measure" -is accomplished by taking a cryptographic hash using an algorithm supported by -the TCG's Trusted Platform Module (TPM) so that it may store the measurement -within one of the TPM's Platform Configuration Registers (PCR). This initial -measurement, referred to as the Core Root of Trust Measurement (CRTM), is the -trust anchor for the DRTM. - -While the Intel and AMD implementations of Late Launch both achieve a DRTM, -how their implementations arrive at a DRTM are significantly different. As a -result each will be addressed separately. - -## Intel Trusted eXecution Technology (TXT) - -For TXT, Intel set about a holistic approachi\[[1](#1)\] that -introduced the Safer Mode Extensions (SMX) instruction set. As a result TXT -provides for advanced security capabilities such as measuring System Management -Mode (SMM) when an SMI Transfer Monitor (STM) is in place. The TXT process is -built around the SINIT Authenticated Code Module (ACM) and a Measured Launch -Environment (MLE). The ACM is a binary provided by Intel and the MLE is a -software solution typically provided by the OS provider. Details about the ACM -and the MLE are explained in the "Intel TXT Measured Launch Environment -Developer's Guide". \[[2](#2)\] - -### SENTER Procedure - -From the moment when the SENTER instruction is invoked until execution control -is handed to the MLE, a series of computations are completed by the CPU and -then by the ACM to generate integrity assertions in the form of measurements -about the platform environment as well as the MLE that will be given control. -Details about the CPU's role in the launch can be found in the Intel Software -Developer's Manual (SDM) under Vol. 2D 6.2.3 para 3 and 6.3 GETSEC[SENTER]. -\[[3](#3)\] The primary role for the CPU is to establish an -environment that minimizes the ability of external tampering and taking the -CRTM used for the DRTM. Below is an outline of the internal steps that the CPU -takes when the SENTER instruction is initial invoked, - -1. Inhibit processor response to external events: INIT, A20M, NMI, and SMI. -2. Establish and check the location and size of the authenticated code module to be executed by the ILP. -3. Check for the existence of an Intel® TXT-capable chipset. -4. Verify the current power management configuration is acceptable. -5. Broadcast a message to enable protection of memory and I/O from the activities of other processor agents. -6. Load the designated AC module into the authenticated code execution area. -7. Isolate the content of the authenticated code execution area from further state modification by external agents. -8. Authenticate the AC module. -9. Updated the Trusted Platform Module (TPM) with the authenticated code module's hash. -10. Initialize processor state based on the authenticated code module header information. -11. Unlock the Intel® TXT-capable chipset private configuration register space and TPM locality 3 space. -12. Begin execution in the authenticated code module at the defined entry point. - -### TXT ACM - -The ACM is the portion that is responsible for implementing the advanced -security capabilities provided by TXT. To achieve this, the CPU provides a -highly privileged execution mode that is capable of inspecting System -Management Mode (SMM) memory (SMRAM), this is needed to allow the measurement -of the STI. As a result it is highly important that only authorized code is allowed -to execute in this mode. This is handled in step 8., the authentication of -the ACM. The details of this process can be found in section A.1.2 of the MLE -Developers Guide. \[[2](#2)\] The ACM is entrusted with a series of responsibilities, -ones of particular note are IOMMU protecting the MLE, -measuring the MLE, and the enforcement of the Launch Control Policy (LCP), - -#### Launch Control Policy - -One of the capabilities provided by the ACM is the LCP Engine. The LCP is a -rarely used mechanism to enforce that a known environment is being used. Within -the ACM is an LCP engine that will look for a LCP in a designated TPM NVRAM -address. The LCP allows for defining expected values for TPM PCRs and/or the -expected hash value of the MLE. If a policy check fails, then the LCP Policy -Engine will trigger the ACM to error exit from the SENTER instruction. - -### Measured Launch Environment - -The final component in the Intel TXT process is the MLE, a software component -that is responsible for the secure setup and execution of the target runtime. -As the ACM conducted a transitive trust extension to the MLE, the MLE should -similar conduct a transitive trust extension to bring the target runtime within -the SMX trust boundary by protecting the runtime's memory from tampering, -measuring the runtime, and optionally enforcing policy to ensure only -authorized runtimes are allowed to execute. - -## AMD Secure Startup - -The AMD approach is a simpler one that allows more control over code executed -by the SKINIT instruction, to include environment setup and measurements, but -unlike Intel's ACM, execution is limited to the same accesses as -superprivileged mode. This means it is not possible to obtain a measurement of -SMRAM at the time of the late launch. Therefore the trust boundary of SKINIT -still bound to the SRTM. To use the Secure Startup capability, a Secure Loader -(SL) image must be loaded and passed to SKINIT. Details about building an SL -and calling the SKINIT instruction can be found in the AMD ARM64 Architecture -Programmer's Manual, Volume 2. \[[2](#4)\] - -### SKINIT Procedure - -When the SKINIT instruction is executed, the base address for the SL is passed -in the EAX register. The CPU will then execute the following sequence, - -1. Reinitialize the processor state similar to INIT signal -2. Enter 32bit protected mode with paging disabled -3. Clear all general purpose registers except, - * EAX: start address of SL - * EDX: CPU model, family, and stepping -4. Secures registers, - * Most MSRs retain their values (except those which might compromise SVM protections) - * EFER MSR is cleared - * setting DPD, R_INIT and DIS_A20M flags in the VM_CR register unconditionally to 1 -4. Page align EAX and use as the start address for 64KBytes of DEV protection -5. Securely initializes AP(s) - * clears Global Interrupt Flag (GIF) - * setting DPD, R_INIT and DIS_A20M flags in the VM_CR register -6. Transmit SL image to TPM for hash, any failure will trigger SKINIT failure -7. Clear the GIF on the BSP which disables all interrupts, including NMI, SMI, and INIT -8. Update ESP to point at SL stack (SLB base + 65536) -9. Add SL entry offset to SL base and jump to that address - -### Secure Loader - -In the AMD world, the initial code executed by the SKINIT instruction is the -Secure Loader (SL). The SL is an Owner provided code base that is responsible -for securely initializing the system and handover to a Security Kernel (SK). -The SL must meet two primary conditions, - -1. SL image's first two words contain the entry point offset and image size -2. SL image and stack must be less than 64KBytes -3. SL image must be loaded page aligned - -Upon execution, the SL is responsible for protecting the remainder of the -execution environment through measurement and memory protection of the SK to which it -will be handing over control. - -### Security Kernel - -For AMD Secure Startup the last component is the SK. The SK can be an -intermediate kernel or a target runtime kernel. The situation that drives the -need for an intermediate kernel is for solutions that need to do more complex -security verification and/or hand-off to target runtime kernel that cannot be -implemented in less than 64Kbytes. - -# Foot Notes -#### 1. -Grawrock, D. (2006). The Intel safer computing initiative. Hillsboro, Or.: -Intel Press.
-https://books.google.com/books?id=WmGjSgAACAAJ - -#### 2. -Intel® Trusted Execution Technology (Intel® TXT) -Software Development Guide: -Measured Launched Environment Developer’s Guide - -https://www.intel.com/content/dam/www/public/us/en/documents/guides/intel-txt-software-development-guide.pdf - -#### 3. -Intel® 64 and IA-32 Architectures -Software Developer’s Manual, -Combined Volumes: -1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D and 4 - -https://software.intel.com/sites/default/files/managed/39/c5/325462-sdm-vol-1-2abcd-3abcd.pdf - -#### 4. -AMD64 Architecture -Programmer’s Manual -Volume 2: -System Programming - -https://www.amd.com/system/files/TechDocs/24593.pdf diff --git a/docs/documentation/UseCases.md b/docs/documentation/UseCases.md deleted file mode 100644 index d9f98b0..0000000 --- a/docs/documentation/UseCases.md +++ /dev/null @@ -1,44 +0,0 @@ -TrenchBoot Use Cases -==================== - -TrenchBoot is meant to be a universal framework to enable building integrity in -the launch process of systems. To relate to real world usage, it is good to -have a set of use cases that explain a subset of situations where TrenchBoot is -applicable and how it would work in those situations. Below are a series of use -cases that are actively being investigated and/or worked on. - - -## Crowd Sourcing Integrity - -There is currently no known public authority available to verify BIOS/Firmware -PCR values. TrenchBoot would like to become such an authority but there is the -challenge of how to obtain all these values in a manner that provide assurance -to the authenticity of the values. Crowd sourcing provides the best means to -collect the largest and most diverse set of values. The challenge with crowd -sourcing the values is how to establish authenticity of the values. This -challenge can be overcome with a TrenchBoot based live CD that establishes an -attestation identity provisioned by a TrenchBoot Attestation Certificate -Authority (ACA). - -## Network Attestation Launch - -An individual or enterprise may not want to allow a system to boot on their -network unless it is running a known configuration. When TrenchBoot is -installed onto a system it will work in conjunction with a TrenchBoot ACA -(public or private instance) that provides a key management service. TrenchBoot -will hold a portion of a Shamir Secret Sharing key with another portion held by -the key management service. For the system to boot it will attest to the key -management service to obtain a key fragment that will allow it to unlock the system -disk. - -## Travel Laptop 2FA Launch - -When travelling there are times when an individual loses positive control of -their device. During these times attackers can launch physical access attacks. -For this configuration TrenchBoot will "double chain wrap" the encryption key -for decrypting the system where each chain wrap correlates to an authentication -factor. Working internal to external, the system drive key is encrypted with -the first wrap key that is in turned encrypted with the second wrap key. The -first wrap key is stored on a removable token device, e.g. YubiKey, and the -second wrap key is sealed in a TPM NVRAM slot. For a system to boot it must -have launched with the correct firmware and the token must be present. diff --git a/docs/documentation/gitlab_CI.md b/docs/documentation/gitlab_CI.md deleted file mode 100644 index 8a5b4a0..0000000 --- a/docs/documentation/gitlab_CI.md +++ /dev/null @@ -1,73 +0,0 @@ -# GitlabCI configuration documentation - -## Preparation - -### GitHub - -* Create account for CI bot - - grant `Admin` access to this bot in the repositories you will want to use - GitLabCI with - -### GitLab - -* Create account for CI bot - -## Configuration - -### GitLabCI for GitHub integration - -The process is descriebd in the -[official documentation](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/github_integration.html). - -Following projects were integrated: - -* `TrenchBoot` GitHub repositories: - - [grub](https://github.com/trenchboot/grub) - - [landing-zone](https://github.com/trenchboot/landing-zone) - - [linux](https://github.com/trenchboot/linux) - -* `3mdeb` GitHub repositories: - - [grub](https://github.com/3mdeb/grub) - - [landing-zone](https://github.com/3mdeb/landing-zone) - - [linux](https://github.com/3mdeb/linux) - - [meta-trenchboot](https://github.com/3mdeb/meta-trenchboot) - - [nixos-trenchboot-configs](https://github.com/3mdeb/nixos-trenchboot-configs) - -### CI/CD variables - -Following variables are used on the -[trenchboot1 group level](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd) -(they are used by both the repositories in `TrenchBoot` and `3mdeb` subgroups): -- `CACHIX_AUTHTOKEN` - authotken to push nix artifacts to the - [3mdeb cachix](https://app.cachix.org/cache/3mdeb) -- `CACHIX_SIGNING_KEY` - signing key to sign the artifacts pushed to the - [3mdeb cachix](https://app.cachix.org/cache/3mdeb) -- `RTE_IP_1000V` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) - connected to the `Asrock R1000V` board -- `RTE_IP_APU2` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) - connected to the `APU2` board -- `RTE_IP_SUPERMICRO` - local IP of the [RTE](https://3mdeb.com/products/open-source-hardware/rte/) - connected to the `Supermicro m11sdv-8ct-ln4f` board -- `YOCTO_CACHE_PATH` - local path where the Yocto cache is stored in the local - `HTTP` server -- `YOCTO_HTTP_CACHE_IP` - local IP address of the HTTP cache server -- `YOCTO_HTTP_CACHE_RSYNC_KEY`- private SSH key used to populate the Yocto - downloads/sstate cache on the local server using `rsync` -- `YOCTO_HTTP_CACHE_USER` - username to the local HTTP cache server - -Following variables are used on the -[trenchboot1/3mdeb subgroup level](https://gitlab.com/trenchboot1): -- `GITHUB_GROUP` - gitlab group prefix for `3mdeb` repositories -- `GITHUB_GROUP` - github group prefix for `3mdeb` repositories - -Following variables are used on the -[trenchboot1/trenchboot subgroup level](https://gitlab.com/trenchboot1): -- `GITHUB_GROUP` - gitlab group prefix for `TrenchBoot` repositories -- `GITHUB_GROUP` - github group prefix for `TrenchBoot` repositories - -Thanks to the group variables, we can have the same `.gitlab-ci.yml` content -for both groups, and adjust some variables (like prefixes) there. - -### Setting up local runners - -Follow the [gitlab-runner](gitlab_runner.md) documentation. diff --git a/docs/documentation/gitlab_runner.md b/docs/documentation/gitlab_runner.md deleted file mode 100644 index 0b7d09f..0000000 --- a/docs/documentation/gitlab_runner.md +++ /dev/null @@ -1,83 +0,0 @@ -# Running - -Use `docker-compose` script from the [trenchboot-ci](https://github.com/3mdeb/trenchboot-ci/tree/master/gitlab-runner) -repository: - -```bash -docker-compose up -``` - -On first run you will see there is no config file: - -``` -gitlab-runner1_1 | ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory builds=0 -gitlab-runner1_1 | ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory builds=0 -``` - -You need to perform the [registration](#register). - -# Registration - -1. Go to [CI/CD](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd) settings - in your group. - -1. Go to the `Set up a group Runner manually` section and set the - `registration token` as environmental variable: - - ```bash - export REGISTRATION_TOKEN="QZgfyepK2_t3SshRgX2K" - ``` - -1. Register using the [script](https://github.com/3mdeb/trenchboot-ci/blob/master/gitlab-runner/gitlab-runner-register.sh): - - ```bash - ./gitlab-runner-register.sh - - Runtime platform arch=amd64 os=linux pid=142 revision=ce065b93 version=12.10.1 - Running in system-mode. - - Registering runner... succeeded runner=QZgfyepK - Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! - ``` - -1. The containter logs should become: - - ``` - gitlab-runner1_1 | Configuration loaded builds=0 - ``` - -1. The runner should be available in the - [CI/CD group settings](https://gitlab.com/groups/trenchboot1/-/settings/ci_cd#runners-settings) - - ![/img/registered_local_runner.png](/img/registered_local_runner.png) - -1. Refer to the - [register documentation](https://docs.gitlab.com/runner/register/index.html) - if needed. - -# Usage - -Local runner can run the exact same jobs as a shared runnners in the cloud. -Typically, we will want to mark some specific jobs to run on the local runner -instead. Examples of such jobs: -- local infastructure acces required, -- extensive hardware requirementes (shared runners have limited resources). - -In the [gitlab-runner-register.sh](https://github.com/3mdeb/trenchboot-ci/blob/master/gitlab-runner/gitlab-runner-register.sh) -we are providing a list of tags as one of the arguments: - -```bash ---tag-list local \ -``` - -In this case, we mark our runner with a `local` tag. We can mark a specific job -(in a `.gitlab-ci.yml` file) with the same tag, to make sure it will always run -on a local runner, rather the shared (cloud one). The syntax is: - -```bash - tags: - - local -``` - -Please refer to the -[tags description in the official documentation](https://docs.gitlab.com/ee/ci/yaml/#tags). diff --git a/docs/documentation/index.md b/docs/documentation/index.md deleted file mode 100644 index 27d0d9e..0000000 --- a/docs/documentation/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# TrenchBoot Documentation - -Here you will find documentation for building and using security engine -components. - -{nav} diff --git a/docs/documentation/test_matrix.md b/docs/documentation/test_matrix.md deleted file mode 100644 index 5fa6be6..0000000 --- a/docs/documentation/test_matrix.md +++ /dev/null @@ -1,87 +0,0 @@ -# Hardware test matrix - -## Modern (as of 2024) test results - -These results are based on the use of TrenchBoot in combination with [AEM][aem] -on the specified hardware running [Qubes OS][qubesos]. The tests were carried -out either automatically via [openQA][openqa] using [this test][aem-test] or -manually by [installing][aem-install] and [verifying][aem-verify] AEM with -TrenchBoot. The procedure is very similar in both cases: - -1. Installation of ACMs on Intel platforms or SKL on AMD platforms. -2. Installation of TrenchBoot's versions of AEM, Xen and GRUB2 (necessary until - all of the changes are upstreamed). -3. AEM setup procedure which is detailed in its [README][aem-readme]. -4. Reboot so that AEM has a chance to seal the secrets taking values of DRTM - PCRs into account. -5. Reboot once again to verify that AEM has successfully unsealed the secrets - and PCR values are correct with respect to TPM event log. -6. An extra manual step in both cases (openQA only prints event log) is to - check that hashes from the log correspond to on-disk files. - -Devices and configurations on which TrenchBoot is known to work (availability -years can be approximate; automatic tests don't override manual tests): - -| Tested device | TPM family | Available | Notes | -|:---------------------------------------------------------------------------------------------:|:----------:|:----------:|:-----:| -| Asus KGPE-D16
(AMD Opteron family 15h models 00h-0fh server)
(v0.4 by [@SergiiDmytruk]) | TPM 1.2 | 2005-2015 | stock BIOS | -| Dell OptiPlex 9010
(v0.3 by openQA) | TPM 1.2 | 2012-2017 | coreboot SeaBIOS firmware | -| HP Thin Client t630
(v0.4 by [@krystian-hebel]) | TPM 2.0 | 2016-2020 | CSM legacy boot
BIOS updates in 2024 | -| Supermicro M11SDV-8CT
(AMD EPYC 3000 Snowy Owl server)
(v0.4 by openQA) | TPM 2.0 | 2019-today | CSM legacy boot | - -[aem]: https://github.com/TrenchBoot/qubes-antievilmaid -[qubesos]: https://www.qubes-os.org/ -[openqa]: https://open.qa/ -[aem-test]: https://github.com/TrenchBoot/openqa-tests-qubesos/blob/3mdeb-lab/tests/aem_hw.pm -[aem-install]: https://blog.3mdeb.com/2023/2023-09-27-aem_phase2/#installation-procedure -[aem-verify]: https://blog.3mdeb.com/2024/2024-01-12-aem_phase3/#testing -[aem-readme]: https://github.com/QubesOS/qubes-antievilmaid/blob/main/README -[@SergiiDmytruk]: https://github.com/SergiiDmytruk -[@krystian-hebel]: https://github.com/krystian-hebel - -## Legacy (before 2022) test results - -The origin of the following results is not always known. AMD platforms used to -be tested on [CI][ci] via [testing-trenchboot]. - -Devices and configurations on which TrenchBoot is known to work (availability -years can be approximate): - -| Tested device | TPM family | Available | Notes | -|:---------------------------------------------------------------------------:|:----------:|:----------:|:-----:| -| Intel Kaby Lake server | TPM 2.0 | 2016-2020 | UEFI firmware | -| Intel Skylake server | TPM 2.0 | 2015-2019 | UEFI firmware | -| Intel Tiger Lake client | TPM 2.0 | 2020-2023 | UEFI firmware | -| PC Engines APU2 platform series
(AMD family 16h models 30h-3fh embedded) | TPM 1.2 | 2016-2023 | coreboot firmware | -| PC Engines APU2 platform series
(AMD family 16h models 30h-3fh embedded) | TPM 2.0 | 2016-2023 | coreboot firmware | - -Devices and configurations on which TrenchBoot is known to not work: - -| Tested device | TPM family | Notes | -|:---------------------------------------------------------------------------:|:----------:|:-----:| -| [Asus KGPE-D16][kgpe]
(AMD Opteron family 15h models 00h-0fh server) | TPM 2.0 | coreboot firmware TPM issue | -| [Supermicro M11SDV-8CT][m11]
(AMD EPYC 3000 Snowy Owl server) | TPM 2.0 | UEFI boot | - -[ci]: https://gitlab.com/trenchboot1/3mdeb/meta-trenchboot/-/pipelines -[testing-trenchboot]: https://github.com/3mdeb/testing-trenchboot -[kgpe]: https://github.com/TrenchBoot/trenchboot-issues/issues/27 -[m11]: https://github.com/TrenchBoot/trenchboot-issues/issues/28 - -## Hardware quirks and workarounds - -These are difficulties/things of note one has to face when using these platforms -today. They were probably more usable years ago, but something has changed in -software that nobody tested on these devices and now experience isn't very -smooth. - -| Device | Notes | -|:---------------------------------------------------------------------------:|:-----:| -| Asus KGPE-D16
(AMD Opteron family 15h models 00h-0fh server) | IOMMU has no extended features: can't use `INVALIDATE_IOMMU_ALL` in SKL. | -| Dell OptiPlex 9010 | 1. Installer has issues rebooting without `reboot=pci` kernel option. | -| (continued) | 2. Xen sometimes has issues rebooting, boot cycle is the workaround. | -| HP Thin Client t630 | Starting Qubes OS installation in legacy mode requires extra steps ([see][qubesos-t630-install]). | -| Supermicro M11SDV-8CT
(AMD EPYC 3000 Snowy Owl server) | Problematic USB controller for Qubes OS ([resets the system][qubesos-m11-reset]). | -| (continued) | Works without `sys-usb` VM or if USB controller is disabled. | - -[qubesos-m11-reset]: https://github.com/QubesOS/qubes-issues/issues/8322#issuecomment-1904423204 -[qubesos-t630-install]: https://github.com/TrenchBoot/TrenchBoot.github.io/pull/30#discussion_r1570519887 diff --git a/docs/events.md b/docs/events.md index b245aff..dc3d7a4 100644 --- a/docs/events.md +++ b/docs/events.md @@ -4,38 +4,75 @@ Events that TrenchBoot appeared on. ## Worldwide conferences -* Open Source Firmware Conference 2020 - * Video: [TrenchBoot DRTM features for AMD platforms](https://vimeo.com/488140434) - * [Slides](slides/TrenchBoot_DRTM_features_for_AMD_platforms.pdf) -* UEFI Plugfest 2020 - * Video: [TrenchBoot and GRUB - A Quick Introduction](https://www.youtube.com/watch?v=8yd2c18R7u0) - * [Slides](slides/TrenchBoot_UEFI_plugfest_2020.pdf) -* Xen Project Developer and Design Summit 2020 - * Video: [Xen system boot attestation with DRTM and TPM2](https://www.youtube.com/watch?v=SwByVrw7-08) - * [Slides](slides/Xen-system-boot-attestation-with-DRTM-and-TPM2.pdf) -* Platform Security Summit 2019 - * Video: [Less-Insecure Network Edge Virtualization with Low Size, Weight and Power]() - * [Slides](slides/Less_Insecure_Network_Edge_Virtualization_with_Low_Size_Weight_and_Power.pdf) -* Xen Project Developer and Design Summit 2019 - * Video: [How TrenchBoot is Enabling Measured Launch for Open-Source Platform Security](https://www.youtube.com/watch?v=f0LZFSq4Ack) - * [Slides](slides/How_TrenchBoot_is_Enabling_Measured_Launch_for_Open-Source_Platform_Security.pdf) -* Linux Plumbers Conference 2019 - * Video: [TrenchBoot - How to Nicely Boot System with Intel TXT and AMD SVM](https://www.youtube.com/watch?v=DbpCU9iSi4g) - * [Slides](slides/trenchboot_lpc_20190906.final.dk.pdf) -* Linux Security Summit 2019 - * Video: [TrenchBoot - How to Nicely Boot System with Intel TXT and AMD SVM](https://www.youtube.com/watch?v=DbpCU9iSi4g) - * [Slides](slides/trenchboot_How_to_nicely_boot_system_with_Intel_TXT_and_AMD_SVM.pdf) -* Open Source Firmware Conference 2019 - * Video: [TrenchBoot - Open DRTM implementation for AMD platforms](https://www.youtube.com/watch?v=9NcVjsSu59w) - * [Slides](slides/TrenchBoot-Open_DRTM_implementation_for_AMD_platforms.pdf) -* Grub2 and 3mdeb "minisummit" 2019 - * Video: [AMD TrenchBoot support in GRUB2](https://www.youtube.com/watch?v=V1Pate0JeJo) - * [Slides](slides/AMD-TrenchBoot-support-in-GRUB2.pdf) -* Platform Security Summit 2018 - * Video: [TrenchBoot and System Boot Integrity](https://www.youtube.com/watch?v=nKsD1QWVGtk) - * [Slides](slides/PSEC2018-TrenchBoot-Daniel-Smith.pdf) +- Xen Project Summit 2024 + + Video: + [Challenges and Status of Enabling TrenchBoot in Xen Hypervisor](https://www.youtube.com/watch?v=RVK52BCM-ZM) + + [Slides](slides/trenchboot_in_xen_2024.pdf) +- FOSDEM 2024 + + Video: + [Trenchboot - project status update](https://video.fosdem.org/2024/aw1126/fosdem-2024-3724-trenchboot-project-status-update.av1.webm) + + [Slides (DRTM Status)](slides/DRTM-presentation-FOSDEM_2024.pdf) + + [Slides (Trenchboot AEM Status)](slides/TrenchBoot_AEM_Project_Status_fosdem_2024.pdf) +- Xen Developer & Design Summit 2023 + + Video: + [Paving the Path for TrenchBoot DRTM in Xen Hypervisor](https://www.youtube.com/watch?v=A9GrlQsQc7Q?start=8152) + + [Slides](slides/Paving_the_Path_for_TrenchBoot_DRTM_in_Xen_Hypervisor.pdf) +- Qubes OS Summit 2022 + + Video: + [TrenchBoot - The only AEM-way to boot Qubes OS](https://www.youtube.com/watch?v=A9GrlQsQc7Q&t=17440s) + + [Slides](slides/TrenchBoot-the-only-AEM-way-to-boot-Qubes-OS_2022.pdf) +- Linux Plumbers Conference 2022 + + Video: + [TrenchBoot Update](https://www.youtube.com/watch?v=FFh3fWvVv0o) + + [Slides](slides/TrenchBoot%20-%20LPC%202022%20-%20Final.pdf) +- FOSDEM 2021 + + Video: + [Secure Upgrades with DRTM](https://video.fosdem.org/2021/D.firmware/firmware_suwd.webm) +- Open Source Firmware Conference 2020 + + Video: + [TrenchBoot DRTM features for AMD platforms](https://vimeo.com/488140434) + + [Slides](slides/TrenchBoot_DRTM_features_for_AMD_platforms.pdf) +- UEFI Plugfest 2020 + + Video: + [TrenchBoot and GRUB - A Quick Introduction](https://www.youtube.com/watch?v=8yd2c18R7u0) + + [Slides](slides/TrenchBoot_UEFI_plugfest_2020.pdf) +- Xen Project Developer and Design Summit 2020 + + Video: + [Xen system boot attestation with DRTM and TPM2](https://www.youtube.com/watch?v=SwByVrw7-08) + + [Slides](slides/Xen-system-boot-attestation-with-DRTM-and-TPM2.pdf) +- FOSDEM 2020 + + Video : + [Improving the Security of Edge Computing Services](https://video.fosdem.org/2020/K.4.601/firmware_itsoecs.mp4) + + [Slides (part1)](slides/improving_the_security_of_edge_computing_services_fosdem_2020_part1.pdf) + + [Slides (part2)](slides/fosdem_trenchboot_2020_part2.pdf) +- Platform Security Summit 2019 + + [Slides](slides/Less_Insecure_Network_Edge_Virtualization_with_Low_Size_Weight_and_Power.pdf) +- Xen Project Developer and Design Summit 2019 + + Video: + [How TrenchBoot is Enabling Measured Launch for Open-Source Platform Security](https://www.youtube.com/watch?v=f0LZFSq4Ack) + + [Slides](slides/How_TrenchBoot_is_Enabling_Measured_Launch_for_Open-Source_Platform_Security.pdf) +- Linux Plumbers Conference 2019 + + Video: + [TrenchBoot - How to Nicely Boot System with Intel TXT and AMD SVM](https://www.youtube.com/watch?v=DbpCU9iSi4g) + + [Slides](slides/trenchboot_lpc_20190906.final.dk.pdf) +- Linux Security Summit 2019 + + Video: + [TrenchBoot - How to Nicely Boot System with Intel TXT and AMD SVM](https://www.youtube.com/watch?v=DbpCU9iSi4g) + + [Slides](slides/trenchboot_How_to_nicely_boot_system_with_Intel_TXT_and_AMD_SVM.pdf) +- Open Source Firmware Conference 2019 + + Video: + [TrenchBoot - Open DRTM implementation for AMD platforms](https://www.youtube.com/watch?v=9NcVjsSu59w) + + [Slides](slides/TrenchBoot-Open_DRTM_implementation_for_AMD_platforms.pdf) +- Grub2 and 3mdeb "minisummit" 2019 + + Video: + [AMD TrenchBoot support in GRUB2](https://www.youtube.com/watch?v=V1Pate0JeJo) + + [Slides](slides/AMD-TrenchBoot-support-in-GRUB2.pdf) +- Platform Security Summit 2018 + + Video: + [TrenchBoot and System Boot Integrity](https://www.youtube.com/watch?v=nKsD1QWVGtk) + + [Slides](slides/PSEC2018-TrenchBoot-Daniel-Smith.pdf) ## TrenchBoot events -* [Linux Secure Launch - TrenchBoot Summit 2021](https://www.youtube.com/watch?v=xZoCtNV8Qs0) -* [TrenchBoot Developers Forum 2021](https://www.youtube.com/watch?v=qWMRcfQdc6c) +- [Linux Secure Launch - TrenchBoot Summit 2021](https://www.youtube.com/watch?v=xZoCtNV8Qs0) +- [TrenchBoot Developers Forum 2021](https://www.youtube.com/watch?v=qWMRcfQdc6c) diff --git a/docs/img/Arch_Flow.xml b/docs/img/Arch_Flow.xml index 0073089..99a52e8 100644 --- a/docs/img/Arch_Flow.xml +++ b/docs/img/Arch_Flow.xml @@ -1 +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 \ No newline at end of file +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 diff --git a/docs/img/Architectural_Flow.xml b/docs/img/Architectural_Flow.xml index f8f2795..b8a4308 100644 --- a/docs/img/Architectural_Flow.xml +++ b/docs/img/Architectural_Flow.xml @@ -1 +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 \ No newline at end of file +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 diff --git a/docs/img/SoftwareArch.xml b/docs/img/SoftwareArch.xml index 21d6dc4..5b7a2d0 100644 --- a/docs/img/SoftwareArch.xml +++ b/docs/img/SoftwareArch.xml @@ -1 +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== \ No newline at end of file +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== diff --git a/docs/img/qubes_aem_1st_boot.png b/docs/img/qubes_aem_1st_boot.png new file mode 100644 index 0000000..0e50994 Binary files /dev/null and b/docs/img/qubes_aem_1st_boot.png differ diff --git a/docs/img/qubes_aem_install.png b/docs/img/qubes_aem_install.png new file mode 100644 index 0000000..c1dd1ce Binary files /dev/null and b/docs/img/qubes_aem_install.png differ diff --git a/docs/img/qubes_aem_setup.png b/docs/img/qubes_aem_setup.png new file mode 100644 index 0000000..8c0e37b Binary files /dev/null and b/docs/img/qubes_aem_setup.png differ diff --git a/docs/img/qubes_aem_setup_fail.png b/docs/img/qubes_aem_setup_fail.png new file mode 100644 index 0000000..0ec6118 Binary files /dev/null and b/docs/img/qubes_aem_setup_fail.png differ diff --git a/docs/index.md b/docs/index.md index 8037683..2fe05e1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,27 +1,40 @@ --- + hide: - - navigation - - toc + +- navigation +- toc + --- -![](/img/logo.svg){ class="center" } +# Home + +![](img/logo.svg){ class="center" } -TrenchBoot is a framework that allows individuals and projects to build -security engines to perform launch integrity actions for their systems. The -framework builds upon Boot Integrity Technologies (BITs) that establish one or -more Roots of Trust (RoT) from which a degree of confidence that integrity -actions were not subverted is derived. +TrenchBoot is a framework that allows individuals and projects to +build security engines to perform launch integrity actions for their +systems. The framework builds upon Boot Integrity Technologies (BITs) +that establish one or more Roots of Trust (RoT) from which a degree of +confidence that integrity actions were not subverted is derived. ## Where to Start -* [General Architecture](documentation/Architecture.md) - A top level overview of TrenchBoot -* [Use Case Definition](documentation/UseCases.md) - A collection of example use cases -* [Developers Guide](documentation/DevelopersGuide.md) - A developers guide that explains the internals of TrenchBoot +- [User Documentation](user-docs/index.md) - Requirements and quick + start guides +- [General Architecture](theory/Architecture.md) - A top level + overview of TrenchBoot +- [Use Case Definition](theory/UseCases.md) - A collection of example + use cases +- [Developers Guide](dev-docs/DevelopersGuide.md) - A developers guide + that explains the internals of TrenchBoot ## Contributors -![Apertus Solutions](/assets/apertus_logo.svg){: style="width:400px;" class="center" } +![Apertus Solutions](assets/apertus_logo.svg) {: style="width:400px;" +class="center" } -![Oracle](/assets/oracle_logo.svg){: style="width:400px;" class="center" } +![Oracle](assets/oracle_logo.svg){: style="width:400px;" +class="center" } -![3mdeb Embedded System Consulting](/assets/3mdeb_logo.svg){: style="width:400px;" class="center" } +![3mdeb Embedded System Consulting](assets/3mdeb_logo.svg) {: +style="width:400px;" class="center" } diff --git a/docs/references/README.md b/docs/references/README.md index 8e194b5..d2ff079 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -1,5 +1,6 @@ -References -========== +# References -Here you will find reference knowledge explaining concepts and theory behind -TrenchBoot. +Here you will find reference knowledge explaining concepts and theory +behind TrenchBoot. + +{nav} diff --git a/docs/slides/DRTM-presentation-FOSDEM_2024.pdf b/docs/slides/DRTM-presentation-FOSDEM_2024.pdf new file mode 100644 index 0000000..1ac50cf Binary files /dev/null and b/docs/slides/DRTM-presentation-FOSDEM_2024.pdf differ diff --git a/docs/slides/Paving_the_Path_for_TrenchBoot_DRTM_in_Xen_Hypervisor.pdf b/docs/slides/Paving_the_Path_for_TrenchBoot_DRTM_in_Xen_Hypervisor.pdf new file mode 100644 index 0000000..21a3600 Binary files /dev/null and b/docs/slides/Paving_the_Path_for_TrenchBoot_DRTM_in_Xen_Hypervisor.pdf differ diff --git a/docs/slides/TrenchBoot - LPC 2022 - Final.pdf b/docs/slides/TrenchBoot - LPC 2022 - Final.pdf new file mode 100644 index 0000000..cb1cbcc Binary files /dev/null and b/docs/slides/TrenchBoot - LPC 2022 - Final.pdf differ diff --git a/docs/slides/TrenchBoot-the-only-AEM-way-to-boot-Qubes-OS_2022.pdf b/docs/slides/TrenchBoot-the-only-AEM-way-to-boot-Qubes-OS_2022.pdf new file mode 100644 index 0000000..da1b13e Binary files /dev/null and b/docs/slides/TrenchBoot-the-only-AEM-way-to-boot-Qubes-OS_2022.pdf differ diff --git a/docs/slides/TrenchBoot_AEM_Project_Status_fosdem_2024.pdf b/docs/slides/TrenchBoot_AEM_Project_Status_fosdem_2024.pdf new file mode 100644 index 0000000..3f44c6d Binary files /dev/null and b/docs/slides/TrenchBoot_AEM_Project_Status_fosdem_2024.pdf differ diff --git a/docs/slides/TrenchBoot_Anti_Evil_Maid__Roadmap.pdf b/docs/slides/TrenchBoot_Anti_Evil_Maid__Roadmap.pdf new file mode 100644 index 0000000..d831c8c Binary files /dev/null and b/docs/slides/TrenchBoot_Anti_Evil_Maid__Roadmap.pdf differ diff --git a/docs/slides/fosdem_trenchboot_2020_part2.pdf b/docs/slides/fosdem_trenchboot_2020_part2.pdf new file mode 100644 index 0000000..6c6103f Binary files /dev/null and b/docs/slides/fosdem_trenchboot_2020_part2.pdf differ diff --git a/docs/slides/improving_the_security_of_edge_computing_services_fosdem_2020_part1.pdf b/docs/slides/improving_the_security_of_edge_computing_services_fosdem_2020_part1.pdf new file mode 100644 index 0000000..86feaa3 Binary files /dev/null and b/docs/slides/improving_the_security_of_edge_computing_services_fosdem_2020_part1.pdf differ diff --git a/docs/slides/trenchboot_in_xen_2024.pdf b/docs/slides/trenchboot_in_xen_2024.pdf new file mode 100644 index 0000000..8e7433d Binary files /dev/null and b/docs/slides/trenchboot_in_xen_2024.pdf differ diff --git a/docs/specifications/Secure_Launch.md b/docs/specifications/Secure_Launch.md index c5887e6..3d6acad 100644 --- a/docs/specifications/Secure_Launch.md +++ b/docs/specifications/Secure_Launch.md @@ -1,8 +1,13 @@ -Secure Launch Specification -=========================== +# Secure Launch Specification -The Secure Launch specification describes a common approach for implementing -Dynamic Launch. This specification is to enable any conforming bootloader to be -able to initiate a Dynamic Launch of any conforming OS kernel. +The Secure Launch specification describes a common approach for +implementing Dynamic Launch. This specification is to enable any +conforming bootloader to be able to initiate a Dynamic Launch of any +conforming OS kernel. - + diff --git a/docs/specifications/index.md b/docs/specifications/index.md index 12e1b93..cb44d69 100644 --- a/docs/specifications/index.md +++ b/docs/specifications/index.md @@ -3,4 +3,3 @@ TrenchBoot developed specifications. {nav} - diff --git a/docs/steering-committee/.pages.yml b/docs/steering-committee/.pages.yml index 678e656..7e0af53 100644 --- a/docs/steering-committee/.pages.yml +++ b/docs/steering-committee/.pages.yml @@ -1,2 +1,3 @@ +--- nav: - - ... \ No newline at end of file + - ... diff --git a/docs/steering-committee/Community-Meeting-June17-2021.md b/docs/steering-committee/Community-Meeting-June17-2021.md index 12de6d7..8b4d58d 100644 --- a/docs/steering-committee/Community-Meeting-June17-2021.md +++ b/docs/steering-committee/Community-Meeting-June17-2021.md @@ -1,131 +1,172 @@ +# Community Meeting June 17 2021 ## Agenda/Notes -* Outreach and Engagement - * TrenchBoot Developers Forum - * Determine time period and/or dates - - Piotr feels every 12 mo would be quite long +- Outreach and Engagement + + + TrenchBoot Developers Forum + + - Determine time period and/or dates + + + Piotr feels every 12 mo would be quite long - is six months too short to discuss things - thinks sept. we should have something - OSFC planned for Dec. - - Rich, should do it when things get cold and are locked up + + Rich, should do it when things get cold and are locked up - Do TB talks at multiple events - - We should have an internal event, but maybe make it a DRTM event - - DK, LPC at end of 24Sept + - We should have an internal event, but maybe make it a DRTM + event + + DK, LPC at end of 24Sept - Should have confirmation by the end of June for LPC MC - should have slots available for TB talks - - * Select chairman to oversee planning/coordination - - Piotr we would like to help but cannot do it alone + + - Select chairman to oversee planning/coordination + + + Piotr we would like to help but cannot do it alone - will engage IBM POWER about sponsoring - - Rich recommends bring the topic up at DRTM related meetings and try to find a corporate sponsor + + Rich recommends bring the topic up at DRTM related meetings + and try to find a corporate sponsor - * TrenchBoot website - * Identify content that would like to be on the site - - Piotr: coreboot is hooking to rss feeds that feed into blog + + TrenchBoot website + + - Identify content that would like to be on the site + + + Piotr: coreboot is hooking to rss feeds that feed into blog - will look at what coreboot implementation - will look at mkdocs setup to move TB documentation over to - - DanK: will speak with a colleague, will have a response when back from vacation + + DanK: will speak with a colleague, will have a response when + back from vacation + + - Discuss approach to maintenance/development + + + should apply GH auto fixes + + + TrenchBoot Social Media - * Discuss approach to maintenance/development - - should apply GH auto fixes + - Review social media accounts and strategy + + Twitter + + LinkedIn project site/group + + Others? - * TrenchBoot Social Media - * Review social media accounts and strategy - * Twitter - * LinkedIn project site/group - * Others? +- Project -* Project - * Moving AMD support forward - * LZ renaming - - Piotr thinks AMD should be involved in TB AMD related topics + + Moving AMD support forward + + - LZ renaming + + + Piotr thinks AMD should be involved in TB AMD related topics - we should also try to get them involved with the call - - Rich, this is a public meeting, may need to have NDA meeting - - * LZ IOMMU approach adoption - - Ross: just adopt current proposed approach as a starting place + + Rich, this is a public meeting, may need to have NDA meeting + + - LZ IOMMU approach adoption + + + Ross: just adopt current proposed approach as a starting place - yes the pitsaw card could be used - - Piotr, the current approach is better than nothing + + Piotr, the current approach is better than nothing - are there tests? - - Kanth: can the pitsaw card be used to test iommu for txt, can be used for AMD - - * DRTM log approach adoption - - Piotr: based on TCG spec + + Kanth: can the pitsaw card be used to test iommu for txt, can + be used for AMD + + - DRTM log approach adoption + + + Piotr: based on TCG spec - this is where the HCL will be useful - can test Ross changes for linux kernel - will work on "legacy mode" support - - Ross: need to handle system without the ACPI table - - can make so that the ACPI table is preferred approach then fail back to non-ACPI table - - for the LZ will need to also be made to handle non-ACPI table situation (legacy mode) + + Ross: need to handle system without the ACPI table + - can make so that the ACPI table is preferred approach then + fail back to non-ACPI table + - for the LZ will need to also be made to handle non-ACPI + table situation (legacy mode) - will work on "legacy mode" support - - Daniel: merge the PR + + Daniel: merge the PR - has been confirmed on pc-engines - * iPXE support - - Piotr: submitted patches but rejected as too big - - https://github.com/ipxe/ipxe/pull/300 + - iPXE support + + + Piotr: submitted patches but rejected as too big + - - we should care about iPXE - * Upcoming v2 LKML submission + + Upcoming v2 LKML submission + - Ross: it looks like it will be going out tomorrow (6/18/2021) - * GRUB submission - - Daniel K: currently working with Lukasz and will looking to submit in July - - will be working with 3mdeb on aligning AMD changes - - * Deployment/Adoption support - * TrenchBoot Hardware Compatibility List - * How to check if my hardware is supported or can be supported? + + GRUB submission + + - Daniel K: currently working with Lukasz and will looking to + submit in July + + will be working with 3mdeb on aligning AMD changes + + + Deployment/Adoption support + + - TrenchBoot Hardware Compatibility List + + + How to check if my hardware is supported or can be supported? - Piotr: resource constrained but we need something very basic - - what all should be checked, log, pcrs, etc - - this is QubesOS HCL as an example - - https://www.qubes-os.org/hcl/ - - list of hardware for people to get started with + + what all should be checked, log, pcrs, etc + + this is QubesOS HCL as an example + - + + list of hardware for people to get started with - Rich: - - there are a lot of things that make you feel better but not gain much + + there are a lot of things that make you feel better but + not gain much - maybe skip over that and focus on community - - biggest issues will be with hardware that is not MS certified - - both OXT and Qubes HCL are not correct because every system has quirks - - * TrenchBoot Canonical Demo - - * TrenchBoot as AEM for QubesOS - - Piotr: would be good to assist with anit-evil maid demo - - * Test automation (Kanth) - - Rich suggest this is a place for Qemu support for DRTM to enable software based testing - - at tdf txt lead mentioned txt test suite in FWUPD - - we should get OEM testing - - could TB lead DRTM test suite development - - if there isn't one, who is willing to fund its development - - live cd is not enough, need to build a cross-community project - - this can be a theme for the DRTM event + + biggest issues will be with hardware that is not MS + certified + + both OXT and Qubes HCL are not correct because every + system has quirks + + - TrenchBoot Canonical Demo + + - TrenchBoot as AEM for QubesOS + + + Piotr: would be good to assist with anit-evil maid demo + + + Test automation (Kanth) + + - Rich suggest this is a place for Qemu support for DRTM to enable + software based testing + + at tdf txt lead mentioned txt test suite in FWUPD + + we should get OEM testing + + could TB lead DRTM test suite development + + if there isn't one, who is willing to fund its development + + live cd is not enough, need to build a cross-community project + + this can be a theme for the DRTM event - Piotr agrees that this FWUPD testing support is desired - - Kanth, Oracle will be increasing supported platforms and would like to see automated testing/validation - - Oracle would be interested in helping with building a DRTM test framework - - Daniel K: GRUB does not have automated testing but it is in progress - - thinks it would be quite easy to introduce tests for preamble - -* Additional Topics (time permitting) - * DRTM/TrenchBoot for Arm - - Stuart: Beta spec will be public by fall and possible reference implementation - - Rich: coordinate a TB event around Arm event/announcement - - * Plan for SMM + - Kanth, Oracle will be increasing supported platforms and would + like to see automated testing/validation + + Oracle would be interested in helping with building a DRTM + test framework + - Daniel K: GRUB does not have automated testing but it is in + progress + + thinks it would be quite easy to introduce tests for preamble + +- Additional Topics (time permitting) + + + DRTM/TrenchBoot for Arm + + - Stuart: Beta spec will be public by fall and possible reference + implementation + - Rich: coordinate a TB event around Arm event/announcement + + + Plan for SMM + - intel whitepaper on SMM DRTM protection - - * Integration with FWUPD hardware security test -* General Business - * Open floor for community members - - * Next meeting + + Integration with FWUPD hardware security test + +- General Business + + + Open floor for community members + + + Next meeting + - Piotr we missed several topics - - discuss getting more resources - - fobnail - - testing - - Rich we should not do meetings during the summer and do out-of-band discussions (chat/email) - - perhaps use OSFC TB slack + + discuss getting more resources + + fobnail + + testing + - Rich we should not do meetings during the summer and do + out-of-band discussions (chat/email) + + perhaps use OSFC TB slack - Will be done virtually via TB slack channel - diff --git a/docs/steering-committee/index.md b/docs/steering-committee/index.md index 24b4171..5c441cd 100644 --- a/docs/steering-committee/index.md +++ b/docs/steering-committee/index.md @@ -1,6 +1,6 @@ -# Steering Commitee Meetings +# Steering Committee Meetings -Here you will find the meeting minutes from the Steering Committiee and -Community Meetings. +Here you will find the meeting minutes from the Steering Committiee +and Community Meetings. {nav} diff --git a/docs/theory/Architecture.md b/docs/theory/Architecture.md new file mode 100644 index 0000000..34fefc9 --- /dev/null +++ b/docs/theory/Architecture.md @@ -0,0 +1,72 @@ +# General Architecture + +The general execution flow for TrenchBoot is broken into three phases, +Bootstrap, Intermediate, and Runtime. The Bootstrap phase primarily +consists of the existing bootstrap technology, e.g. UEFI, grub, UEFI +shim, etc. For TrenchBoot the bootstrap technologies that have an +integrity function, referred to as a Boot Integrity Technology (BIT), +are of primary interest. The Intermediate phase is that which the +TrenchBoot Loader executes to establish the launch integrity of the +system. The last phase is the Runtime phase and is where the target +runtime, hypervisor, operating system, etc, is given control over the +system. + +![Architecture Execution Flow](../img/Architectural_Flow.png) + +# TrenchBoot Security Engine + +At the heart of the TrenchBoot Loader is the TrenchBoot Security +Engine. The Security Engine is responsible for processing any evidence +collected by the BITs, collecting new evidence as needed, evaluating +all evidence according to a security policy, and executing appropriate +enforcement actions. The components that enable this and their +relationship can be seen in the top level diagram below. + +![Architecture Execution Flow](../img/Arch_Flow.png) + +## Evidence + +A core concept in TrenchBoot is that of evidence. For TrenchBoot, +evidence is a record of an event that occurred within the system. The +typical form for these records is a cryptographic hash of the system +state that was the result of this event. This cryptographic hash is +often referred to as a measurement. + +## Boot Integrity Technology + +Boot Integrity Technologies (BITs) are software or hardware +capabilities that are responsible for a portion of system launch. +Specifically these capabilities attempt to establish and/or enforce a +degree of integrity that the correct logic was used to launch the +system. + +## BIT Augmentation + +There may be BITs that need to be directly or indirectly extended to +enable or enhance their usage for launching a TrenchBoot environment. + +## BIT Ingestion + +A TrenchBoot Security Engine must be capable of supporting a variety +of evidence formats for the various BITs supported. Translation of +these various formats allows TrenchBoot to maintain normalized data +structures for evidence collected. This allows the functionality in +Security Processor to only have to reason about normalized data +without specialized logic for different data formats. + +## Security Processor + +At the heart of a TrenchBoot Security Engine is the Security +Processor. The Security Processor consist of the logical components +that will consume a launch policy and take one or more actions to +evaluate the state of the system necessary to enforce the policy. This +may include, but is not limited to, collecting additional evidence, +making attestation assertions, retrieving encryption keys, and +file/block/drive decryption. The enforcement of the security policy +will result in a full, partial, or failed boot of the system. + +## Launch/Hand Off + +Ultimately TrenchBoot's responsibility is to launch a target +environment. As such it must be equipped with the various ways +required to launch those target environments. diff --git a/docs/documentation/Glossary.md b/docs/theory/Glossary.md similarity index 55% rename from docs/documentation/Glossary.md rename to docs/theory/Glossary.md index 240a643..c456e83 100644 --- a/docs/documentation/Glossary.md +++ b/docs/theory/Glossary.md @@ -1,49 +1,61 @@ -Glossary -======== +# Glossary -Provided are definitions of terms used throughout TrenchBoot's documents and -designs to encourage a common vocabulary and understanding. +Provided are definitions of terms used throughout TrenchBoot's +documents and designs to encourage a common vocabulary and +understanding. ## Dynamic Launch -A system launch that can be done repeatedly with the execution code able to -reside at different locations in memory. This is sometimes referred to as a -"Late Launch". + +A system launch that can be done repeatedly with the execution code +able to reside at different locations in memory. This is sometimes +referred to as a "Late Launch". ## Explicit Trust -When a trustor has explicitly established a degree of trust with a trustee. + +When a trustor has explicitly established a degree of trust with a +trustee. ## Implicit Trust -When a trustor has relied upon a trustee to establish a degree of trust with -another trustee. + +When a trustor has relied upon a trustee to establish a degree of +trust with another trustee. ## Root of Trust -An idempotent mechanism whereby the result is used to assert a fact about the -entity it acted upon. + +An idempotent mechanism whereby the result is used to assert a fact +about the entity it acted upon. ## Static Launch -A system launch that is a one time execution with the execution code at a fixed -location in memory. + +A system launch that is a one time execution with the execution code +at a fixed location in memory. ## Transitive Trust -An operation conducted by a trustor that consists of one or more mechanisms -used to assess one or more facts about a trustee before allowing the trustee to -be included within the trustor's trust boundary and delegated the authority to -act as a trustor. + +An operation conducted by a trustor that consists of one or more +mechanisms used to assess one or more facts about a trustee before +allowing the trustee to be included within the trustor's trust +boundary and delegated the authority to act as a trustor. ## Trust -Assured reliance on the properties, ability, strength, or truth of an entity. + +Assured reliance on the properties, ability, strength, or truth of an +entity. ## Trust Anchor -The result of a Root of Trust mechanism that is a fact being relied upon to assert -correctness, e.g. trustworthiness. + +The result of a Root of Trust mechanism that is a fact being relied +upon to assert correctness, e.g. trustworthiness. ## Trust Boundary -A demarcation that identifies a subset of entities as those that a trustor has -explicitly or implicitly established as trustworthy. + +A demarcation that identifies a subset of entities as those that a +trustor has explicitly or implicitly established as trustworthy. ## Trustee + An entity that is trusted by another entity. ## Trustor -An entity that establishes a degree of trust of another entity. +An entity that establishes a degree of trust of another entity. diff --git a/docs/theory/UseCases.md b/docs/theory/UseCases.md new file mode 100644 index 0000000..bef2b44 --- /dev/null +++ b/docs/theory/UseCases.md @@ -0,0 +1,46 @@ +# TrenchBoot Use Cases + +TrenchBoot is meant to be a universal framework to enable building +integrity in the launch process of systems. To relate to real world +usage, it is good to have a set of use cases that explain a subset of +situations where TrenchBoot is applicable and how it would work in +those situations. Below are a series of use cases that are actively +being investigated and/or worked on. + +## Crowd Sourcing Integrity + +There is currently no known public authority available to verify +BIOS/Firmware PCR values. TrenchBoot would like to become such an +authority but there is the challenge of how to obtain all these values +in a manner that provide assurance to the authenticity of the values. +Crowd sourcing provides the best means to collect the largest and most +diverse set of values. The challenge with crowd sourcing the values is +how to establish authenticity of the values. This challenge can be +overcome with a TrenchBoot based live CD that establishes an +attestation identity provisioned by a TrenchBoot Attestation +Certificate Authority (ACA). + +## Network Attestation Launch + +An individual or enterprise may not want to allow a system to boot on +their network unless it is running a known configuration. When +TrenchBoot is installed onto a system it will work in conjunction with +a TrenchBoot ACA (public or private instance) that provides a key +management service. TrenchBoot will hold a portion of a Shamir Secret +Sharing key with another portion held by the key management service. +For the system to boot it will attest to the key management service to +obtain a key fragment that will allow it to unlock the system disk. + +## Travel Laptop 2FA Launch + +When travelling there are times when an individual loses positive +control of their device. During these times attackers can launch +physical access attacks. For this configuration TrenchBoot will +"double chain wrap" the encryption key for decrypting the system where +each chain wrap correlates to an authentication factor. Working +internal to external, the system drive key is encrypted with the first +wrap key that is in turned encrypted with the second wrap key. The +first wrap key is stored on a removable token device, e.g. YubiKey, +and the second wrap key is sealed in a TPM NVRAM slot. For a system to +boot it must have launched with the correct firmware and the token +must be present. diff --git a/docs/theory/index.md b/docs/theory/index.md new file mode 100644 index 0000000..f4e9df8 --- /dev/null +++ b/docs/theory/index.md @@ -0,0 +1,6 @@ +# TrenchBoot Documentation + +Here you will find theoretical background for TrenchBoot project, such +as DRTM and its implementations, as well as design artifacts. + +{nav} diff --git a/docs/user-docs/index.md b/docs/user-docs/index.md new file mode 100644 index 0000000..8e3e7f9 --- /dev/null +++ b/docs/user-docs/index.md @@ -0,0 +1,6 @@ +# Getting started + +Here you will find documentation for installing and using security +engine components. + +{nav} diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md new file mode 100644 index 0000000..83e6969 --- /dev/null +++ b/docs/user-docs/install_aem.md @@ -0,0 +1,165 @@ +# Installing TrenchBoot AEM in Qubes OS + +This document shows how to install Anti Evil Maid from packages +produced by 3mdeb as part of +[Trenchboot as Anti Evil Maid project](https://docs.dasharo.com/projects/trenchboot-aem-v2/). +If you wish to build the components yourself, please refer to +documentation for developers instead. + +## Disclaimer + +As of now, only legacy boot is supported. These instructions +WON'T WORK under UEFI. You have been +warned. + +## Installation + +To install, you have to first add a new repository and import a public +part of a key that was used to sign RPM packages. + +### Adding AEM repository + +To add a new repository, create in dom0 as root +`/etc/yum.repos.d/aem.repo` with the following content: + +```text +[aem] +name = Anti Evil Maid based on TrenchBoot +baseurl = https://dl.3mdeb.com/rpm/QubesOS/r4.2/current/dom0/fc37 +gpgcheck = 1 +gpgkey = https://dl.3mdeb.com/rpm/QubesOS/r4.2/current/dom0/fc37/RPM-GPG-KEY-tb-aem +enabled = 1 +``` + +The key specified in the file must be downloaded and imported to RPM: + +```bash +qvm-run --pass-io sys-net \ + 'curl -L https://dl.3mdeb.com/rpm/QubesOS/r4.2/current/dom0/fc37/RPM-GPG-KEY-tb-aem' \ + > RPM-GPG-KEY-tb-aem +sudo rpm --import RPM-GPG-KEY-tb-aem +``` + +Now it should be possible to download and install packages from AEM +repository. + +### Installing prerequisite packages + +As some of the packages are also available in standard QubesOS +repositories, potentially in newer versions, those must be temporarily +disabled during invocation of `qubes-dom0-update`, as shown in the +following commands. If any of the packages that are part of AEM are +updated in standard repos, you will have to choose between using new +versions or having working AEM, at least until new AEM release is +published or the code gets merged upstream. If you decide to restore +AEM after an update broke it, you will have to repeat the installation +of overwritten package with `--action=reinstall` added to +`qubes-dom0-update`, if it wasn’t present before. + +Start by installing prerequisite packages. Those are not part of newly +added repository, but `qubes-dom0-current-testing`: + +```bash +sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing \ + oathtool \ + openssl \ + qrencode \ + tpm-extra \ + trousers-changer \ + tpm-tools +``` + +Next set of new packages comes from AEM repository, to avoid conflicts +other repositories are disabled for this call: + +```bash +sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem \ + grub2-tools-extra \ + secure-kernel-loader +``` + +This is followed by reinstalling additional packages. A reinstall is +required because currently installed version is equal (or it may be +higher in the future) than those provided by AEM. + +```bash +sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ + python3-xen \ + xen \ + xen-hypervisor \ + xen-libs \ + xen-licenses \ + xen-runtime \ + grub2-common \ + grub2-pc \ + grub2-pc-modules \ + grub2-tools \ + grub2-tools-minimal +``` + +### Updating GRUB + +Booting on legacy systems (AEM currently doesn’t support UEFI) +requires manual installation of GRUB2 to the MBR of disk where Qubes +OS is stored. In the example below it is `/dev/sda`, yours may be +different. Remember that GRUB2 must be installed on disk and not on +partition, so don’t use `sda1`, `nvme0n1p1` etc. + +```bash +sudo grub2-install /dev/sda +``` + +### Installing main AEM package + +Finally, `anti-evil-maid` package may be installed: + +```bash +sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem anti-evil-maid +``` + +## Provisioning + +All packages are in place. Before we can proceed with provisioning +AEM, the TPM must be cleared in the BIOS. Some platforms may require +disabling Intel Trusted Execution Technology (TXT) in order to clear +TPM. After you clear the TPM, remember to enable Intel TXT back, +otherwise AEM will not work. Once TPM is cleared, perform the TPM +setup: + +```bash +sudo anti-evil-maid-tpm-setup +``` + +![](../img/qubes_aem_setup.png) + +You will be prompted to set the SRK password, it is a password to +access TPM’s nonvolatile storage where the AEM secrets will be sealed. +If you failed to clear the TPM, you will be shown a message like this: + +![](../img/qubes_aem_setup_fail.png) + +In that case, try clearing the TPM and run +`sudo anti-evil-maid-tpm-setup` again. + +Now all that's left is proper installation of AEM. There are different +options, refer to `anti-evil-maid-install -h` for examples. In the +simplest case, AEM is installed on boot partition (not disk, i.e. +`sda1` instead of `sda` etc.) of Qubes OS. This can be done with a +simple command: + +```bash +sudo anti-evil-maid-install /dev/sda1 +``` + +![](../img/qubes_aem_install.png) + +After that, reboot the platform. On first boot you will be asked for +SRK password, followed by another question for disk encryption +password, after which a screen mentioning absent secret file will be +shown: + +![](../img/qubes_aem_1st_boot.png) + +This is expected on the first boot after installation or an update to +one or more of measured components (GRUB, Xen, dom0 kernel and +initramfs). diff --git a/docs/user-docs/requirements.md b/docs/user-docs/requirements.md new file mode 100644 index 0000000..9d586b3 --- /dev/null +++ b/docs/user-docs/requirements.md @@ -0,0 +1,41 @@ +# TrenchBoot hardware requirements + +TrenchBoot by itself doesn't have any special requirements, just use +the requirements of target OS or hypervisor as a base. However, the +same can't be said about vendors DRTM implementation, and those differ +between vendors. + +## Intel + +For Intel, you need a TXT-capable chipset and TXT-capable CPU. In +addition, a TPM is required. It shouldn't make a difference whether it +is a discrete chip (dTPM) or firmware TPM (fTPM) running in a CPU's +trusted execution environment, but version (1.2 or 2.0) must be +supported by the processor, or more specifically, the SINIT +Authenticated Code Module (ACM) for given CPU family. Refer to +[Late Launch Overview](../dev-docs/Late_Launch_Overview.md) for more +information about the role and source of ACM. + +Depending on firmware, TXT may need to be manually enabled in setup. + +## AMD + +On AMD, DRTM implementation is tightly connected to Secure Virtual +Machine (SVM) extensions. This is a virtualization technology included +in all recent (last decade or even longer) CPUs. Contrary to Intel, a +discrete TPM (dTPM) is required on AMD, but its version doesn't matter +\- the counterpart to ACM (which must be signed by Intel) is +implemented by TrenchBoot with support for both TPM 1.2 and 2.0. + +Depending on firmware, SVM (which may be labeled also as +virtualization or AMD-V) may need to be manually enabled in setup. + +## Caveats + +While the above information summarizes requirements provided by +respective vendors, it doesn't necessarily mean that the platform +meeting those conditions will fully work. It is possible that the +firmware doesn't initialize all of the parts required by DRTM, or ACM +is buggy, or there is an issue with microcode that doesn't properly +start a dynamic launch event. A list of such quirks can be found +[here](test_matrix.md/#hardware-quirks-and-workarounds). diff --git a/docs/user-docs/test_matrix.md b/docs/user-docs/test_matrix.md new file mode 100644 index 0000000..efc530e --- /dev/null +++ b/docs/user-docs/test_matrix.md @@ -0,0 +1,107 @@ +# Hardware test matrix + +## Modern (as of 2024) test results + +These results are based on the use of TrenchBoot in combination with +[AEM] on the specified hardware running [Qubes OS][qubesos]. The tests +were carried out either automatically via [openQA] using +[this test][aem-test] or manually by [installing][aem-install] and +[verifying][aem-verify] AEM with TrenchBoot. The procedure is very +similar in both cases: + +1. Installation of ACMs on Intel platforms or SKL on AMD platforms. +1. Installation of TrenchBoot's versions of AEM, Xen and GRUB2 + (necessary until all of the changes are upstreamed). +1. AEM setup procedure which is detailed in its [README][aem-readme]. +1. Reboot so that AEM has a chance to seal the secrets taking values + of DRTM PCRs into account. +1. Reboot once again to verify that AEM has successfully unsealed the + secrets and PCR values are correct with respect to TPM event log. +1. An extra manual step in both cases (openQA only prints event log) + is to check that hashes from the log correspond to on-disk files. + +Devices and configurations on which TrenchBoot is known to work +(availability years can be approximate; automatic tests don't override +manual tests): + +| Tested device | TPM family | Available | Notes | +| :-----------------------------------------------------: | :--------: | :------------------------------------: | :-----: | +| Asus KGPE-D16
(AMD Opteron family 15h models 00h-0fh | | | | +| server)
(v0.4 by [@SergiiDmytruk]) | TPM 1.2 | 2005-2015 | stock | +| BIOS | | Dell OptiPlex 9010
(v0.3 by openQA) | TPM 1.2 | +| coreboot SeaBIOS firmware, bad 1st entry in event log | | HP Thin | | +| Client t630
(v0.4 by [@krystian-hebel]) | TPM 2.0 | 2016-2020 | CSM | +| legacy boot
BIOS updates in 2024 | | | | + +Devices and configurations on which TrenchBoot is known to not work: + +| Tested device | TPM family | Available | Notes | +| :----------------------------------------------------------------: | :--------: | :--------: | :--------------------------------: | +| Supermicro M11SDV-8CT
(AMD EPYC 3000 Snowy Owl server)
(v0.4 | | | | +| by openQA) | TPM 2.0 | 2019-today | CSM legacy boot,
unexpected PCR | +| values | | | | + +## Legacy (before 2022) test results + +The origin of the following results is not always known. AMD platforms +used to be tested on [CI] via [testing-trenchboot]. + +Devices and configurations on which TrenchBoot is known to work +(availability years can be approximate): + +| Tested device | TPM family | Available | Notes | +| :--------------------------------------------------------------: | :---------------: | :---------------: | :-----------: | +| Intel Kaby Lake server | TPM 2.0 | 2016-2020 | UEFI firmware | +| Intel Skylake server | TPM 2.0 | 2015-2019 | UEFI firmware | +| Tiger Lake client | TPM 2.0 | 2020-2023 | UEFI firmware | +| APU2 platform series
(AMD family 16h models 30h-3fh embedded) | TPM | | | +| 1.2 | 2016-2023 | coreboot firmware | | +| series
(AMD family 16h models 30h-3fh embedded) | TPM 2.0 | | | +| 2016-2023 | coreboot firmware | | | + +Devices and configurations on which TrenchBoot is known to not work: + +| Tested device | TPM family | Notes | +| :--------------------------------------------------------------: | :--------: | :-------------------------: | +| [Asus KGPE-D16][kgpe]
(AMD Opteron family 15h models 00h-0fh | | | +| server) | TPM 2.0 | coreboot firmware TPM issue | +| [Supermicro M11SDV-8CT][m11]
(AMD EPYC 3000 Snowy Owl server) | TPM | | +| 2.0 | UEFI boot | | + +## Hardware quirks and workarounds + +These are difficulties/things of note one has to face when using these +platforms today. They were probably more usable years ago, but +something has changed in software that nobody tested on these devices +and now experience isn't very smooth. + +| Device | Notes | +| :--------------------------------------------------------------------: | :-------------------------------------: | +| Asus KGPE-D16
(AMD Opteron family 15h models 00h-0fh server) | | +| IOMMU has no extended features: can't use `INVALIDATE_IOMMU_ALL` in | | +| SKL. | | +| without `reboot=pci` kernel option. | | +| has issues rebooting, boot cycle is the workaround. | | +| 3. First entry in DRTM TPM event log contains the result of PCR extend | | +| operation instead of its input due to ACM bug. | | +| Starting Qubes OS installation in legacy mode requires extra steps | | +| ([see][qubesos-t630-install]). | | +| 3000 Snowy Owl server) | Problematic USB controller for Qubes OS | +| ([resets the system][qubesos-m11-reset]). | | +| without `sys-usb` VM or if USB controller is disabled. | | + +[@krystian-hebel]: https://github.com/krystian-hebel +[@sergiidmytruk]: https://github.com/SergiiDmytruk +[aem]: https://github.com/TrenchBoot/qubes-antievilmaid +[aem-install]: https://blog.3mdeb.com/2023/2023-09-27-aem_phase2/#installation-procedure +[aem-readme]: https://github.com/QubesOS/qubes-antievilmaid/blob/main/README +[aem-test]: https://github.com/TrenchBoot/openqa-tests-qubesos/blob/3mdeb-lab/tests/aem_hw.pm +[aem-verify]: https://blog.3mdeb.com/2024/2024-01-12-aem_phase3/#testing +[ci]: https://gitlab.com/trenchboot1/3mdeb/meta-trenchboot/-/pipelines +[kgpe]: https://github.com/TrenchBoot/trenchboot-issues/issues/27 +[m11]: https://github.com/TrenchBoot/trenchboot-issues/issues/28 +[openqa]: https://open.qa/ +[qubesos]: https://www.qubes-os.org/ +[qubesos-m11-reset]: https://github.com/QubesOS/qubes-issues/issues/8322#issuecomment-1904423204 +[qubesos-t630-install]: https://github.com/TrenchBoot/TrenchBoot.github.io/pull/30#discussion_r1570519887 +[testing-trenchboot]: https://github.com/3mdeb/testing-trenchboot diff --git a/mkdocs.yml b/mkdocs.yml index 3279494..42b5905 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,4 @@ +--- # Project information site_name: TrenchBoot site_url: https://trenchboot.org @@ -7,43 +8,80 @@ repo_name: TrenchBoot Issues repo_url: https://github.com/TrenchBoot/trenchboot-issues edit_uri: "" # Copyright -copyright: Copyright © 2018 - 2021 TrenchBoot Developers +copyright: Copyright © 2018 - 2024 TrenchBoot Developers nav: - - Home: index.md - - Events: + - Home: index.md + - Events: - events.md - upcoming_events.md - - Specifications: - - ... | specifications/*.md - - Code: code.md - - Documentation: - - ... | documentation/*.md - - ... | blueprints/*.md - - Steering Committee: - - ... | steering-committee/*.md - - FAQ: FAQ.md - - Community: community.md + - Specifications: + - specifications/index.md + - specifications/Secure_Launch.md + - Documentation: + - Getting started: + - user-docs/index.md + - user-docs/requirements.md + # - installing - Linux + - user-docs/install_aem.md + # - troubleshooting + - user-docs/test_matrix.md + - For developers: + - dev-docs/index.md + - dev-docs/CONTRIBUTING.md + - dev-docs/code.md + - dev-docs/Late_Launch_Overview.md + - dev-docs/DevelopersGuide.md + - Theory: + - theory/index.md + - theory/UseCases.md + - theory/Architecture.md + - theory/Glossary.md + - Blueprints: + - blueprints/index.md + - blueprints/TXT_Grub_Late_Launch.md + - blueprints/AMD_Grub_Late_Launch.md + - blueprints/AMD_Secure_Kernel_Loader.md + - blueprints/Linux_Late_Launch.md + - blueprints/Measured_Secure_Boot.md + - References: + - references/README.md + # TODO: make these open in new tab. + # https://github.com/squidfunk/mkdocs-material/issues/889#issuecomment-582297142 + # works but throws a warning about file not found in the documentation + # files. Another option is JS that adds target="_blank" attribute to + # all links to PDF. + - AMD64 Architecture Programmers Manual Volume 2 Ch15.27: + references/AMD64-Architecture-Programmers-Manual_Volume-2_Ch15.27.pdf + - Intel TXT Preliminary Architecture Specification: + references/intel-txt-preliminary-architecture.pdf + - Intel TXT Software Development Guide: + references/intel-txt-software-development-guide.pdf + - Steering Committee: + - steering-committee/index.md + - steering-committee/Community-Meeting-June17-2021.md + - TrenchBoot FAQ: FAQ.md + - Community: community.md use_directory_urls: true theme: - name: material - logo: img/logo.svg - favicon: img/favicon.ico - language: en - palette: - scheme: slate - primary: grey - font: - text: Source Sans Pro - code: Roboto Mono - features: - - navigation.instant - - navigation.tabs - - navigation.tabs.sticky - - navigation.indexes - - header.autohide + name: material + logo: img/logo.svg + favicon: img/favicon.ico + language: en + palette: + scheme: slate + primary: grey + font: + text: Source Sans Pro + code: Roboto Mono + features: + - navigation.instant + - navigation.tabs + - navigation.tabs.sticky + - navigation.indexes + - header.autohide extra: social: