[M] Change in coreboot[master]: [WIP] Documentation/measured_boot.md: document new TPM options

[Sergii Dmytruk (Code Review)]

Attention is currently required from: Michał Żygowski, Maciej Pijanowski, Krystian Hebel.

Hello Michał Żygowski, Maciej Pijanowski, Krystian Hebel,

I'd like you to do a code review.
Please visit

https://review.coreboot.org/c/coreboot/+/68752

to review the following change.

Change subject: [WIP] Documentation/measured_boot.md: document new TPM options
......................................................................

[WIP] Documentation/measured_boot.md: document new TPM options

Change-Id: I6dae8e95c59b440c75e13473eefc4c2cf4fd369b
Ticket: https://ticket.coreboot.org/issues/426
Signed-off-by: Sergii Dmytruk 
---
M Documentation/security/vboot/measured_boot.md
1 file changed, 95 insertions(+), 30 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/68752/1

diff --git a/Documentation/security/vboot/measured_boot.md b/Documentation/security/vboot/measured_boot.md
index 8601bcc..07144d1 100644
--- a/Documentation/security/vboot/measured_boot.md
+++ b/Documentation/security/vboot/measured_boot.md
@@ -49,20 +49,43 @@
 [srtm]: srtm.png

### TCPA eventlog
-coreboot makes use of its own TCPA log implementation. Normally the eventlog
-specification can be found via the TCG homepage:
+There are three supported formats of event logs:
+* coreboot-specific format.
+* [TPM1.2 Specification][TPM12] (section 3.3.3).
+* [TPM2.0 Specification][TPM20] (section 3.3.4).

-[UEFI Specification](https://trustedcomputinggroup.org/resource/tcg-efi-platform-specification/)
+[TPM12]: https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClientImplementat...
+[TPM20]: https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_PFP_r1p05_...

-[BIOS Specification](https://www.trustedcomputinggroup.org/wp-content/uploads/TCG_PCClientImpleme...)
+#### coreboot-specific format
+```c
+struct tcpa_entry {
+	uint32_t pcr;           /* PCR number. */
+	char digest_type[10];   /* Hash algorithm name. */
+	uint8_t digest[64];     /* Digest (tail can be unused). */
+	uint32_t digest_length; /* Number of digest bytes used. */
+	char name[50];          /* Description of what was hashed. */
+} __packed;

-Both of them are not representing firmware measurements in a generalized way.
-Therefore we have to implement our own solution.
+struct tcpa_table {
+	uint16_t max_entries;
+	uint16_t num_entries;
+	struct tcpa_entry entries[0];
+} __packed;
+```

-We decided to provide an easy to understand TCPA log which can be read out
-from the operating system and firmware itself.
+Single hash per PCR. No magic number or any other way of recognizing it.
+Endianness isn't specified.

-#### Table Format
+In principle can hold any hash with 512 bits or less. In practice,
+SHA-1 (for TPM1) and SHA-256 (TPM2) are used.
+
+Can be parsed by `cbmem`.
+
+Use NEED_VBOOT_COMPATIBILITY or USE_TPM_LOG_CB kconfig option to select this
+format.
+
+##### Console dump format
 The first column describes the PCR index used for measurement.
 The second column is the hash of the raw data. The third column contains
 the hash algorithm used in the operation. The last column provides
@@ -70,6 +93,42 @@
 came from, CBFS or FMAP, then the name used to look up the data
 (region or file name).

+#### TPM 1.2 format
+Single hash per PCR (always SHA-1). First entry serves as a header, provides
+ID and version. Always little endian.
+
+Can be parsed by at least `cbmem` and Linux (exports in both text and binary
+forms).
+
+Data in vendor info section of the header:
+```c
+uint16_t max_entries;
+uint16_t num_entries;
+```
+In endianness of the firmware. Not meant to be stable.
+
+Use USE_TPM_LOG_TPM12 kconfig option to select this format.
+
+#### TPM 2.0 format
+One or more hashes per PCR, but implementation is limited to single hash (SHA-1,
+SHA-256, SHA-384 or SHA-512). First entry is overall compatible with TPM 1.2 and
+serves as a header with ID, version and number of hashing algorithms used.
+Always little endian.
+
+Can be parsed by at least `cbmem`, Linux (exports only binary form) and
+[Skiboot][skiboot].
+
+[skiboot]: https://github.com/open-power/skiboot/
+
+Data in vendor info section of the header:
+```c
+uint16_t max_entries;
+uint16_t num_entries;
+```
+In endianness of the firmware. Not meant to be stable.
+
+Use USE_TPM_LOG_TPM2 kconfig option to select this format.
+
 #### Example:
 ```bash
 PCR-2 e8f2b57c9ec5ea06d1bbd3240a753974d4c3e7c8cd305c20a8ea26eed906dc89 SHA256 [FMAP: COREBOOT CBFS: bootblock]
@@ -120,28 +179,23 @@
 environment is necessary.

## Platform Configuration Register
-Normally PCR 0-7 are reserved for firmware usage. In coreboot we use just 4 PCR
-banks in order to store the measurements. coreboot uses the SHA-1 or SHA-256
-hash algorithm depending on the TPM specification for measurements. PCR-4 to
-PCR-7 are left empty.
+Normally PCR 0-7 are reserved for firmware usage. In coreboot we use just 3 or 4
+PCR banks in order to store the measurements. PCR-4 to PCR-7 are left empty.

-### PCR-0
-_Hash:_ SHA1
+### If NEED_VBOOT_COMPATIBILITY kconfig option is selected by the mainboard
+vboot-specific (non-standard) PCR usage.

-_Description:_ Google vboot GBB flags.
+* PCR-0 - SHA1 of Google vboot GBB flags.
+* PCR-1 - SHA1/SHA256 of Google vboot GBB HWID.
+* PCR-2 - SHA1/SHA256 of Core Root of Trust for Measurement which includes all stages,
+          data and blobs.
+* PCR-3 - SHA1/SHA256 of runtime data like hwinfo.hex or MRC cache.

-### PCR-1
-_Hash:_ SHA1/SHA256
+### If NEED_VBOOT_COMPATIBILITY kconfig option is NOT selected by the mainboard
+See [TPM1.2 Specification][TPM12] (section 3.3.3) and
+[TPM2.0 Specification][TPM20] (section 3.3.4) for PCR assignment information.

-_Description:_ Google vboot GBB HWID.
-
-### PCR-2
-_Hash:_ SHA1/SHA256
-
-_Description:_ Core Root of Trust for Measurement which includes all stages,
-data and blobs.
-
-### PCR-3
-_Hash:_ SHA1/SHA256
-
-_Description:_ Runtime data like hwinfo.hex or MRC cache.
+* PCR-1 - SHA1 of Google vboot GBB flags, SHA1/SHA256 of Google vboot GBB HWID.
+* PCR-2 - SHA1/SHA256 of Core Root of Trust for Measurement which includes all stages,
+          data and blobs.
+* PCR-3 - SHA1/SHA256 of runtime data like hwinfo.hex or MRC cache.