[PATCH] tpm: Document UEFI event log quirks

[PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 2843 bytes --]

There are some weird quirks when it comes to UEFI event log. Provide a
brief introduction to TPM event log mechanism and describe the quirks
and how they can be sorted out.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
---
 Documentation/security/tpm/tpm-eventlog.rst | 53 +++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 Documentation/security/tpm/tpm-eventlog.rst

diff --git a/Documentation/security/tpm/tpm-eventlog.rst b/Documentation/security/tpm/tpm-eventlog.rst
new file mode 100644
index 000000000000..2ca8042bdb17
--- /dev/null
+++ b/Documentation/security/tpm/tpm-eventlog.rst
@@ -0,0 +1,53 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+TPM Event Log
+=============
+
+| Authors:
+| Stefan Berger <stefanb@linux.vnet.ibm.com>
+
+This document briefly describes what TPM log is and how it is handed
+over from the preboot firmware to the operating system.
+
+Introduction
+============
+
+The preboot firmware maintains an event log that gets new entries every
+time something gets hashed by it to any of the PCR registers. The events
+are segregated by their type and contain the value of the hashed PCR
+register. Typically, the preboot firmware will hash the components to
+who execution is to be handed over or actions relevant to the boot
+process.
+
+The main application for this is remote attestation and the reason why
+it is useful is nicely put in the very first section of [1]:
+
+"Attestation is used to provide information about the platform’s state
+to a challenger. However, PCR contents are difficult to interpret;
+therefore, attestation is typically more useful when the PCR contents
+are accompanied by a measurement log. While not trusted on their own,
+the measurement log contains a richer set of information than do the PCR
+contents. The PCR contents are used to provide the validation of the
+measurement log."
+
+UEFI event log
+==============
+
+UEFI provided event log has a few somewhat weird quirks.
+
+Before calling ExitBootServices() Linux EFI stub copies the event log to
+a custom configuration table defined by the stub itself. Unfortanely,
+the events generated by ExitBootServices() do end up to the table.
+
+The firmware provides so called final events configuration table to sort
+out this issue. Events gets mirrored to this table after the first time
+EFI_TCG2_PROTOCOL.GetEventLog() gets called.
+
+This introduces another problem: nothing guarantees that it is not
+called before the stub gets to run. Thus, it needs to copy the final
+events table preboot size to the custom configuration table so that
+kernel offset it later on.
+
+[1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
+[2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c
-- 
2.20.1

Re: [PATCH] tpm: Document UEFI event log quirks

[Randy Dunlap]

On 7/3/19 9:11 AM, Jarkko Sakkinen wrote:
> There are some weird quirks when it comes to UEFI event log. Provide a
> brief introduction to TPM event log mechanism and describe the quirks
> and how they can be sorted out.
> 
> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
> ---
>  Documentation/security/tpm/tpm-eventlog.rst | 53 +++++++++++++++++++++
>  1 file changed, 53 insertions(+)
>  create mode 100644 Documentation/security/tpm/tpm-eventlog.rst
> 
> diff --git a/Documentation/security/tpm/tpm-eventlog.rst b/Documentation/security/tpm/tpm-eventlog.rst
> new file mode 100644
> index 000000000000..2ca8042bdb17
> --- /dev/null
> +++ b/Documentation/security/tpm/tpm-eventlog.rst
> @@ -0,0 +1,53 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============
> +TPM Event Log
> +=============
> +
> +| Authors:
> +| Stefan Berger <stefanb@linux.vnet.ibm.com>
> +
> +This document briefly describes what TPM log is and how it is handed
> +over from the preboot firmware to the operating system.
> +
> +Introduction
> +============
> +
> +The preboot firmware maintains an event log that gets new entries every
> +time something gets hashed by it to any of the PCR registers. The events
> +are segregated by their type and contain the value of the hashed PCR
> +register. Typically, the preboot firmware will hash the components to
> +who execution is to be handed over or actions relevant to the boot
> +process.
> +
> +The main application for this is remote attestation and the reason why
> +it is useful is nicely put in the very first section of [1]:
> +
> +"Attestation is used to provide information about the platform’s state
> +to a challenger. However, PCR contents are difficult to interpret;
> +therefore, attestation is typically more useful when the PCR contents
> +are accompanied by a measurement log. While not trusted on their own,
> +the measurement log contains a richer set of information than do the PCR
> +contents. The PCR contents are used to provide the validation of the
> +measurement log."
> +
> +UEFI event log
> +==============
> +
> +UEFI provided event log has a few somewhat weird quirks.
> +
> +Before calling ExitBootServices() Linux EFI stub copies the event log to
> +a custom configuration table defined by the stub itself. Unfortanely,

                                                            Unfortunately,

> +the events generated by ExitBootServices() do end up to the table.
> +
> +The firmware provides so called final events configuration table to sort
> +out this issue. Events gets mirrored to this table after the first time
> +EFI_TCG2_PROTOCOL.GetEventLog() gets called.
> +
> +This introduces another problem: nothing guarantees that it is not
> +called before the stub gets to run. Thus, it needs to copy the final
> +events table preboot size to the custom configuration table so that
> +kernel offset it later on.

?  kernel can offset it later on.

> +
> +[1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
> +[2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c
> 


-- 
~Randy

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

On Wed, 2019-07-03 at 09:45 -0700, Randy Dunlap wrote:
> > +This introduces another problem: nothing guarantees that it is not
> > +called before the stub gets to run. Thus, it needs to copy the final
> > +events table preboot size to the custom configuration table so that
> > +kernel offset it later on.
> 
> ?  kernel can offset it later on.

EFI stub calculates the total size of the events in the final events
table at the time.

Later on, TPM driver uses this offset to copy only the events that
were actually generated after ExitBootServices():

/*
 * Copy any of the final events log that didn't also end up in the
 * main log. Events can be logged in both if events are generated
 * between GetEventLog() and ExitBootServices().
 */
memcpy((void *)log->bios_event_log + log_size,
       final_tbl->events + log_tbl->final_events_preboot_size,
       efi_tpm_final_log_size);

What would be a better way to describe this?

/Jarkko

Re: [PATCH] tpm: Document UEFI event log quirks

[Randy Dunlap]

On 7/5/19 3:15 AM, Jarkko Sakkinen wrote:
> On Wed, 2019-07-03 at 09:45 -0700, Randy Dunlap wrote:
>>> +This introduces another problem: nothing guarantees that it is not
>>> +called before the stub gets to run. Thus, it needs to copy the final
>>> +events table preboot size to the custom configuration table so that
>>> +kernel offset it later on.

     (so that)
     the kernel can use that final table preboot size as an events table
     offset later on.

>>
>> ?  kernel can offset it later on.
> 
> EFI stub calculates the total size of the events in the final events
> table at the time.
> 
> Later on, TPM driver uses this offset to copy only the events that
> were actually generated after ExitBootServices():
> 
> /*
>  * Copy any of the final events log that didn't also end up in the
>  * main log. Events can be logged in both if events are generated
>  * between GetEventLog() and ExitBootServices().
>  */
> memcpy((void *)log->bios_event_log + log_size,
>        final_tbl->events + log_tbl->final_events_preboot_size,
>        efi_tpm_final_log_size);
> 
> What would be a better way to describe this?

Yeah, I think I see what it's doing, how it's using that.
See above.

OK?

-- 
~Randy

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

On Sun, 2019-07-07 at 12:33 -0700, Randy Dunlap wrote:
> On 7/5/19 3:15 AM, Jarkko Sakkinen wrote:
> > On Wed, 2019-07-03 at 09:45 -0700, Randy Dunlap wrote:
> > > > +This introduces another problem: nothing guarantees that it is not
> > > > +called before the stub gets to run. Thus, it needs to copy the final
> > > > +events table preboot size to the custom configuration table so that
> > > > +kernel offset it later on.
> 
>      (so that)
>      the kernel can use that final table preboot size as an events table
>      offset later on.
> 
> > > ?  kernel can offset it later on.
> > 
> > EFI stub calculates the total size of the events in the final events
> > table at the time.
> > 
> > Later on, TPM driver uses this offset to copy only the events that
> > were actually generated after ExitBootServices():
> > 
> > /*
> >  * Copy any of the final events log that didn't also end up in the
> >  * main log. Events can be logged in both if events are generated
> >  * between GetEventLog() and ExitBootServices().
> >  */
> > memcpy((void *)log->bios_event_log + log_size,
> >        final_tbl->events + log_tbl->final_events_preboot_size,
> >        efi_tpm_final_log_size);
> > 
> > What would be a better way to describe this?
> 
> Yeah, I think I see what it's doing, how it's using that.
> See above.
> 
> OK?

Your propsal looks legit, thank you. I'll send an update that
tries to address yours and Jordan's feedback.

/Jarkko 

Re: [PATCH] tpm: Document UEFI event log quirks

[Jordan Hand]

On 7/3/19 9:11 AM, Jarkko Sakkinen wrote:
> There are some weird quirks when it comes to UEFI event log. Provide a
> brief introduction to TPM event log mechanism and describe the quirks
> and how they can be sorted out.
> 
> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
> ---
>   Documentation/security/tpm/tpm-eventlog.rst | 53 +++++++++++++++++++++
>   1 file changed, 53 insertions(+)
>   create mode 100644 Documentation/security/tpm/tpm-eventlog.rst
> 
> diff --git a/Documentation/security/tpm/tpm-eventlog.rst b/Documentation/security/tpm/tpm-eventlog.rst
> new file mode 100644
> index 000000000000..2ca8042bdb17
> --- /dev/null
> +++ b/Documentation/security/tpm/tpm-eventlog.rst
> @@ -0,0 +1,53 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============
> +TPM Event Log
> +=============
> +
> +| Authors:
> +| Stefan Berger <stefanb@linux.vnet.ibm.com>
> +
> +This document briefly describes what TPM log is and how it is handed
> +over from the preboot firmware to the operating system.
> +
> +Introduction
> +============
> +
> +The preboot firmware maintains an event log that gets new entries every
> +time something gets hashed by it to any of the PCR registers. The events
> +are segregated by their type and contain the value of the hashed PCR
> +register. Typically, the preboot firmware will hash the components to
> +who execution is to be handed over or actions relevant to the boot
> +process.
> +
> +The main application for this is remote attestation and the reason why
> +it is useful is nicely put in the very first section of [1]:
> +
> +"Attestation is used to provide information about the platform’s state
> +to a challenger. However, PCR contents are difficult to interpret;
> +therefore, attestation is typically more useful when the PCR contents
> +are accompanied by a measurement log. While not trusted on their own,
> +the measurement log contains a richer set of information than do the PCR
> +contents. The PCR contents are used to provide the validation of the
> +measurement log."
> +
> +UEFI event log
> +==============
> +
> +UEFI provided event log has a few somewhat weird quirks.
> +
> +Before calling ExitBootServices() Linux EFI stub copies the event log to
> +a custom configuration table defined by the stub itself. Unfortanely,
> +the events generated by ExitBootServices() do end up to the table.

                                               do not

> +
> +The firmware provides so called final events configuration table to sort
> +out this issue. Events gets mirrored to this table after the first time
> +EFI_TCG2_PROTOCOL.GetEventLog() gets called.
> +
> +This introduces another problem: nothing guarantees that it is not
> +called before the stub gets to run. Thus, it needs to copy the final
> +events table preboot size to the custom configuration table so that
> +kernel offset it later on.

This doesn't really explain what the size will be used for. Matthew's 
patch description for "tpm: Don't duplicate events from the final event 
log in the TCG2 log" outlines this well. You could maybe word it 
differently but I think the information is necessary:

"We can avoid this problem by looking at the size of the Final Event Log 
just before we call ExitBootServices() and exporting this to the main 
kernel. The kernel can then skip over all events that occured before
ExitBootServices() and only append events that were not also logged to 
the main log."

> +
> +[1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
> +[2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c
> 
Thanks,
Jordan

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

On Wed, 2019-07-03 at 10:08 -0700, Jordan Hand wrote:
> > +This introduces another problem: nothing guarantees that it is not
> > +called before the stub gets to run. Thus, it needs to copy the final
> > +events table preboot size to the custom configuration table so that
> > +kernel offset it later on.
> 
> This doesn't really explain what the size will be used for. Matthew's 
> patch description for "tpm: Don't duplicate events from the final event 
> log in the TCG2 log" outlines this well. You could maybe word it 
> differently but I think the information is necessary:
> 
> "We can avoid this problem by looking at the size of the Final Event Log 
> just before we call ExitBootServices() and exporting this to the main 
> kernel. The kernel can then skip over all events that occured before
> ExitBootServices() and only append events that were not also logged to 
> the main log."

Not exactly sure what is missing from my paragraph. The way I see it has
more information as it states what is used at as the vessel for
exportation (the custom configuration table).

Maybe something like:

"Thus, it nees to save the final events table size at the time to the
custom configuration table so that the TPM driver can later on skip the
events generated during the preboot time."

/Jarkko

Re: [PATCH] tpm: Document UEFI event log quirks

[Jordan Hand]

On 7/5/19 3:26 AM, Jarkko Sakkinen wrote:
> On Wed, 2019-07-03 at 10:08 -0700, Jordan Hand wrote:
>>> +This introduces another problem: nothing guarantees that it is not
>>> +called before the stub gets to run. Thus, it needs to copy the final
>>> +events table preboot size to the custom configuration table so that
>>> +kernel offset it later on.
>>
>> This doesn't really explain what the size will be used for. Matthew's
>> patch description for "tpm: Don't duplicate events from the final event
>> log in the TCG2 log" outlines this well. You could maybe word it
>> differently but I think the information is necessary:
>>
>> "We can avoid this problem by looking at the size of the Final Event Log
>> just before we call ExitBootServices() and exporting this to the main
>> kernel. The kernel can then skip over all events that occured before
>> ExitBootServices() and only append events that were not also logged to
>> the main log."
> 
> Not exactly sure what is missing from my paragraph. The way I see it has
> more information as it states what is used at as the vessel for
> exportation (the custom configuration table).
> 
> Maybe something like:
> 
> "Thus, it nees to save the final events table size at the time to the
> custom configuration table so that the TPM driver can later on skip the
> events generated during the preboot time."
> 
Yes, that sounds more clear to me.

Thanks,
Jordan

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

On Sun, 2019-07-07 at 21:10 -0700, Jordan Hand wrote:
> > "Thus, it nees to save the final events table size at the time to the
> > custom configuration table so that the TPM driver can later on skip the
> > events generated during the preboot time."
> > 
> Yes, that sounds more clear to me.
> 
> Thanks,
> Jordan

Awesome, thank you.

/Jarkko

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

> +| Authors:
> +| Stefan Berger <stefanb@linux.vnet.ibm.com>

I was looking how the rst formatting went from Stefan's
document. This one is authored by me.

/Jarkko

Re: [PATCH] tpm: Document UEFI event log quirks

[Matthew Garrett]

On Wed, Jul 3, 2019 at 9:11 AM Jarkko Sakkinen
<jarkko.sakkinen@linux.intel.com> wrote:
> +Before calling ExitBootServices() Linux EFI stub copies the event log to
> +a custom configuration table defined by the stub itself. Unfortanely,
> +the events generated by ExitBootServices() do end up to the table.

"Unfortunately, the events generated by ExitBootServices() occur after
this and don't end up in the table"?

Re: [PATCH] tpm: Document UEFI event log quirks

[Jarkko Sakkinen]

On Mon, Jul 08, 2019 at 01:43:14PM -0700, Matthew Garrett wrote:
> On Wed, Jul 3, 2019 at 9:11 AM Jarkko Sakkinen
> <jarkko.sakkinen@linux.intel.com> wrote:
> > +Before calling ExitBootServices() Linux EFI stub copies the event log to
> > +a custom configuration table defined by the stub itself. Unfortanely,
> > +the events generated by ExitBootServices() do end up to the table.
> 
> "Unfortunately, the events generated by ExitBootServices() occur after
> this and don't end up in the table"?

Oops, it is a typo, thanks :-)

/Jarkko