Change in coreboot[master]: Documentation/security/intel: add Boot Guard related documentation
Michał Żygowski has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/43405 )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Documentation/security/intel: add Boot Guard related documentation
Signed-off-by: Michał Żygowski michal.zygowski@3mdeb.com Change-Id: Ifd7d4a4e4054652a5876c7e1ca1c1a1ecb73e176 --- M Documentation/security/index.md A Documentation/security/intel/bootguard.md 2 files changed, 247 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/05/43405/1
diff --git a/Documentation/security/index.md b/Documentation/security/index.md index c9cb4a7..5605148 100644 --- a/Documentation/security/index.md +++ b/Documentation/security/index.md @@ -14,6 +14,10 @@ - [Intel TXT Initial Boot Block](intel/txt_ibb.md) - [Intel Authenticated Code Modules](intel/acm.md)
+## Intel Boot Guard + +- [Intel Boot Guard](intel/bootguard.md) + ## SMM
- [System Management Mode](smm.md) diff --git a/Documentation/security/intel/bootguard.md b/Documentation/security/intel/bootguard.md new file mode 100644 index 0000000..78d342b --- /dev/null +++ b/Documentation/security/intel/bootguard.md @@ -0,0 +1,243 @@ +# Intel Boot Guard + +Intel Boot Guard allows: + +1. Integrity verification and measurement of the early boot code. +2. Assuring that only authorized firmware can be executed, which can then be + considered trusted. +3. Providing a hardware-rooted Root of Trust for measurement and/or + verification. + +Intel Boot Guard requirements: + +1. Intel Boot Guard requires a **TPM** to measure parts of the firmware before + it's run on the BSP in case of profiles performing measurements. +2. Intel Boot Guard requires signed **Authenticated Code Modules** ([ACM]s), + provided by Intel. These ACMs are different for platforms without Intel TXT. +3. Intel Boot Guard is told to require a **Boot Guard capable CPU** (check on + Intel ARK). Experiments showed that it is not true. Intel 4th generation + processor or newer is sufficient. All that is required is a provisioned ME + firmware for Boot Guard and an ACM. +4. Intel ME has to be in Manufacturing Mode in order to enable Boot Guard. When + the Manufacturing Mode is disabled the FPFs are blown and it is impossible + to change the Boot Guard status (either enabled with keys you do not have + access to or permanently disabled). + +## Authenticated Code Modules + +The ACMs are Intel digitally signed modules that contain code to be run +before the traditional x86 CPU reset vector. + +More details can be found here: [Intel ACM]. + +## Modified bootflow with Intel Boot Guard + +With Intel Boot Guard the first instruction executed on the BSP isn't the +*reset vector*, but the [Intel ACM]. + +It initializes the TPM and measures parts of the firmware, the IBB. + +### Marking the Initial Boot Block + +Individual files in the CBFS can be marked as IBB in similar manner +as in Intel TXT. + +More details can be found in the [Intel TXT IBB] chapter. + +The difference here is that the IBB elements are removed from [FIT table] as +they are not required for Boot Guard. The newly implemented tool to create Boot +Guard manifests, ibmptool (part of cbfstool), handles creation of signed +manifests and calculates the hash of the IBB based on the [FIT] entries. IBB +must complete the memory initialization according to specification, but in +coreboot's case it is not needed, as the verified and measured boot mode may +start in bootblock already. Covering bootblock, verstage (and FSP-T +optionally) is sufficient. + +### Measurements + +The IBBs (Initial Boot Blocks) are measured into TPM's PCR7 by the Boot Guard +[ACM] before the CPU reset vector is executed. The extend operation is +controlled by flags filled for each IBB segment by ibpmtool. Boot Guard also +allows to specify the Locality (0 or 3) from which the TPM starts up and +measures the IBB. To indentify the regions that need to be measured, the [FIT] +contains one ore multiple *Type 7* entries, that point to the IBBs. + +## Boot Guard capable firmware building and options + +In order to build coreboot with Boot Guard support, few preparation steps are +required. + +1. Boot Guard requires 2 RSA keys from user: OEM Root key (for Key Manifest) + and Boot Policy key (for Boot Policy Manifest). The hash of the public part + of Boot Policy gets signed inside Key Manifest by OEM Root key. This allows + the OEM Root key owner to authorize many Boot Policy keys by simply + delivering a signed Key Manifest to end-user. The coreboot's implementation + allows to specify whether the Key Manifest should be built or a ready one to + be included. + + In order to create the keys OpenSSL may be used: + ``` + openssl genrsa -out OEM_Root_key_private.pem 2048 + openssl rsa -in OEM_Root_key_private.pem -outform PEM -pubout -out OEM_Root_key_public.pem + openssl genrsa -out BPM_key_private.pem 2048 + openssl rsa -in BPM_key_private.pem -outform PEM -pubout -out BPM_key_public.pem + ``` + + Boot Guard supports only RSA2048 for now, but it may change in the future. + +2. Obtain the Boot Guard ACM for your microarchitecture/platform. UEFITool is + able to detect the Boot Guard ACM in the firmware. +3. In menuconfig go to Security submenu and select Intel Boot Guard. Then enter + the Boot Guard submenu which appears after selecting previous option. +4. Provide path and filename to Boot Policy key and the ACM. In case you + already have a signed Key Manifest provide path to the file. Otherwise you + will have to change the Key Manifest source to build a Key Manifest. +5. Provide a Key Manifest Key ID (it must match the ID in the ME firmware + image). +6. Fill the ACM revocation value. Values of 0 and 1 are for engineering samples + and are not available for public use, production ACMs have value of 2. If + there were no revocations earlier it is safe to leave the default. + Revocations will be explained later. +7. Fill the Boot Guard ACM location in CBFS. The ACM must be 64k or 128k + aligned and be placed in the top most 2MB under 4GB in memory space. +8. Build the coreboot image. + +### ME provisioning + +Boot Guard requires provisioning of the ME firmware image. That is, ME firmware +must be configured with OEM Root key public hash, the Key Manifest Key ID and +the Boot Guard profile number. Currently it is only possible with Flash Image +Tool included in ME firmware kit available under CNDA. + +The OEM Root key public hash can be retrieved from the coreboot build log. The +ibpmtool prints the manifests content after it finishes its job. The OEM Root +Key hash is printed after dumping Key Manifest: + +``` +FYI: Hash of the KM public key (modulus only): + + B7 94 7B 36 D2 74 74 A5 B0 44 22 23 99 BE 57 07 + FA 84 97 0D 74 A7 8F 6F D0 6F 66 06 8C 41 D3 81 +``` + +For Skylake and Kaby Lake only modulus part of the RSA key is provided as OEM +Root Key public hash. For other microarchitectures the exponent is also +included in public hash calculation. + +As a last step provide the Key Manifest Key ID to the Flash Image Tool, the +same ID as provided to coreboot's menu config and enable desired Boot Guard +profile. Note, profiles 1 and 1 are no longer available since Coffee Lake. + +### ME fusing + +Blowing the FPFs with Boot Guard configuration requires specialized tool called +Flash Programming Tool which is distributed under CNDA. The fusing process is +achieved by closing the Manufacturing process. + +### Firmware layout requirements + +There are certain requirements about the firmware layout. + +1. IBB must reside in top most 4MB under 4GB in memory space. [FIT table], + microcode and Boot Guard Manifests are also expected to reside in this + range. +2. Boot Guard [ACM] must reside in top most 2MB under 4GB in memory space. + Additionally it must be aligned to 64 or 128 kilobytes (32 kilobytes is also + supported but not recommended as [ACM] size may be larger in the future). + +For Coffee Lake and newer microarchitectures, these requirements apply to +top most 8MB under 4GB in memory space. + +## Revocation + +Boot Guard has a few revocation mechanisms designed to keep the platform secure +from downgrading the firmware to vulnerable version. There are 3 main +revocation mechanisms: + +1. [ACM] SVN revocation +2. Kay Manifest (KM) SVN revocation +3. Boot Policy Manifest (BPM) SVN revocation + +### ACM SVN revocation + +The rule is simple. Each ACM has its Security Version Number (SVN). Production +ACMs start at SVN equal to 2. Each newer ACM executed on the hardware can bump +the ACM SVN present in FPFs. If the ACM SVN in FPF is higher than the ACM SVN +in the blob it will not be executed and enforcement logic will be triggered. In +the opposite situation the ACM SVN may be bumped to higher number in FPFs. It +is controlled by the ACMSVN_Auth field in Boot Policy Manifest. If the +ACMSVN_Auth in Boot Policy Manifest is equal to the ACM SVN in the blob and +ACMSVN_Auth is higher than the current ACM SVN in FPF, ACM SVN in FPFs will be +bumped. + +The ACMSVN_Auth value can be controlled by menuconfig option in Boot Guard +submenu. + +### KM SVN revocation + +The KM SVN follows the same rules as the ACM SVN revocation. The difference +here is that by default KM SVN starts at value of 0. OEM, firmware owner may +authorize new Kay Manifests by simply increasing the KM SVN number when +assembling a Key Manifest. + +The Key Manifest revocation value can be controlled by menuconfig option in +Boot Guard submenu. + +### BPM SVN revocation + +The BPM SVN follows the same rules as the KM SVN revocation. + +The Boot Policy Manifest revocation value can be controlled by menuconfig +option in Boot Guard submenu. + +## Boot Guard manifests optional fields + +Boot Guard Manifests have a few optional fields: + +1. Platform Manufacturer's Key Manifest version. +2. Platform Manufacturer's Boot Policy version. +3. Post IBB hash. +4. Platform Manufacturer's structure. + +The first two are just version numbers used by platform manufacturer's +purposes. They are present in according manifests and are not used by Boot +Guard. Free for one's use. + +Post IBB hash was intended to use as verification of code that is executed +after IBB. It may serve as another custom field for example to keep a hash +of vboot key or other firmware component. + +Platform Manufacturer's structure is an optional part of Boot Policy Manifest. +Currently it is not supported by ibpmtool and shouldn't be used to avoid +errors. ibpmtool assumes that there is no Platform Manufacturer's structure in +Boot Policy Manifest, so dumping one with ibpmtool will give false results. + +## TODO list + +There are still some Boot Guard features not covered by current implementation: + +1. Utilize VT-d and set PMRs in manifests to protect IBB from DMA. +2. Allow to set the TPM measurement option in IBB element flag in ibpmtool. +3. vboot does not work with Boot Guard. The amount of data that needs to be + fetched from SPI flash to verify RW partition is too huge to fit in NEM and + platform simply hangs. vboot needs per-file verification in order to work + with Boot Guard. Current working alternative is ELTAN's vboot. +4. Verify support for Boot Guard- and TXT-enabled systems prior to Coffee Lake. +5. Implement support for Converged Boot Guard and TXT. +6. Enforce the firmware layout requirements in the build system to avoid + user input errors. +7. Implement Platform Manufacturer's structure parsing in ibmptool. +8. Implement a simple Boot Guard library that will dump its status and errors. +9. Implement a TPM event log entry for Boot Guard measurement. +10. Boot Guard for Apollo Lake and newer Atom series processors seems to be a + little bit different. It will need additional effort to work. +11. Implement open-source CAR setup for Boot Guard enabled platforms. Currently + we lack a working implementation for Boot Guard flow (Boot Guard releases + CPUs from reset where IBB is already in cache and MTRRs are set for IBB + elements). For he time being FSP-T must be used. + +[Intel TXT IBB]: txt_ibb.md +[FIT]: ../../soc/intel/fit.md +[Intel ACM]: acm.md +[ACM]: acm.md +[FIT table]: ../../soc/intel/fit.
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/43405 )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Patch Set 1:
(19 comments)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... File Documentation/security/intel/bootguard.md:
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 13: **TPM** I recommend to use *TPM* to emphasize a word. (Italics is often better readable than bold as LaTeX.)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 15: **Authenticated Code Modules** Ditto.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 17: told rumored
Or:
Officially Intel Boot Guard requires a “Boot Guard capable CPU” (check on Intel ARK).
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 17: **Boot Guard capable CPU** Ditto.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 43: as in Intel TXT. Please re-flow for 80(?) characters.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 63: ore or
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 63: that point pointing
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 74: The coreboot's implementation With the article, no possessive(?) s is required.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 90: Security *Security*
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 110: CNDA NDA?
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 112: The : ibpmtool You can remove the article.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 116: ``` : FYI: Hash of the KM public key (modulus only): : : B7 94 7B 36 D2 74 74 A5 B0 44 22 23 99 BE 57 07 : FA 84 97 0D 74 A7 8F 6F D0 6F 66 06 8C 41 D3 81 : ``` Indent by four spaces for marking it up as a code block. Then you can get rid of ```, and it’s a little shorter.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 128: menu config Above you spell it *menuconfig*.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 129: 1 and 1 Does the second number need to differ?
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 179: OEM, firmware owner Do you mean:
OEM or firmware owner may …
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 197: 1. Platform Manufacturer's Key Manifest version. : 2. Platform Manufacturer's Boot Policy version. : 3. Post IBB hash. : 4. Platform Manufacturer's structure. Please remove the dots at the end.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 222: huge big
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 235: flow (Boot Guard releases : CPUs from reset where IBB is already in cache and MTRRs are set for IBB : elements). Please add a dot after *flow*, and directly after *elements*.
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 237: he the
Michael Niewöhner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/43405 )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Patch Set 1:
(2 comments)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... File Documentation/security/intel/bootguard.md:
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 8: hardware-rooted hardware-based?
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 110: CNDA
NDA?
CNDA = "Corporate NDA"
Michael Niewöhner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/43405 )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Patch Set 1:
(6 comments)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... File Documentation/security/intel/bootguard.md:
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 22: Mode is disabled the FPFs are blown and it is impossible : to change the Boot Guard status (either enabled with keys you do not have : access to or permanently disabled maybe document somewhere that bootguard can be tested without blowing the fuses. add a warning, this should be done before EOM gets activated; also document the different ways of applying EOM (automatic commit when the acls are set accordingly vs. using MEManuf vs. IFPT)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 158: Kay Key
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 163: its Security its own
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 180: Kay Key
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 180: SVN number number number ;)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 184: Boot Guard *Boot Guard*
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/43405 )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... File Documentation/security/intel/bootguard.md:
https://review.coreboot.org/c/coreboot/+/43405/1/Documentation/security/inte... PS1, Line 22: Mode is disabled the FPFs are blown and it is impossible : to change the Boot Guard status (either enabled with keys you do not have : access to or permanently disabled
maybe document somewhere that bootguard can be tested without blowing the fuses. […]
AFAIK it's not possible to do so on all platforms. Only those where ME/TXE has UEP (Unified Emulation Partition).
Stefan Reinauer has abandoned this change. ( https://review.coreboot.org/c/coreboot/+/43405?usp=email )
Change subject: Documentation/security/intel: add Boot Guard related documentation ......................................................................
Abandoned
-
Angel Pons (Code Review) -
Michael Niewöhner (Code Review)
-
Michał Żygowski (Code Review)
-
Paul Menzel (Code Review)
-
Stefan Reinauer (Code Review)