1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
.. _stb-overview:
================================
Secure and Trusted Boot Overview
================================
Just as a quick reference::
Secure boot: verify and enforce.
Trusted boot: measure and record.
Secure boot seeks to protect system integrity from execution of malicious
code during boot. The authenticity and integrity of every code is verified
by its predecessor code before it is executed. If the verification fails, the
boot process is aborted.
Trusted boot does not perform enforcement. Instead it creates artifacts during
system boot to prove that a particular chain of events have happened during
boot. Interested parties can subsequently assess the artifacts to check whether
or not only trusted events happened and then make security decisions. These
artifacts comprise a log of measurements and the digests extended into the TPM PCRs.
Platform Configuration Registers (PCRs) are registers in the Trusted Platform
Module (TPM) that are shielded from direct access by the CPU.
Trusted boot measures and maintains in an Event Log a record of all boot
events that may affect the security state of the platform. A measurement is
calculated by hashing the data of a given event. When a new measurement is
added to the Event Log, the same measurement is also sent to the TPM, which
performs an extend operation to incrementally update the existing digest stored
in a PCR.
PCR extend is an operation that uses a hash function to combine a new
measurement with the existing digest saved in the PCR. Basically, it
concatenates the existing PCR value with the received measurement, and then
stores the hash of this string in the PCR.
The TPM may maintain multiple banks of PCRs, where a PCR bank is a collection of
PCRs that are extended with the same hash algorithm. TPM 2.0 has a SHA1 bank
and a SHA256 bank with 24 PCRs each.
When the system boot is complete, each non-zero PCR value represents one or more
events measured during the boot in chronological order. Interested parties
can make inferences about the system's state by using an attestation tool to
remotely compare the PCR values of a TPM against known good values, and also
identify unexpected events by replaying the Event Log against known good Event
Log entries.
Implementation in skiboot
-------------------------
Libstb implements an API for secure and trusted boot, which is used to verify
and measure images retrieved from PNOR. The libstb interface is documented
in ``libstb/stb.h``
The example below shows how libstb can be used to add secure and trusted
boot support for a platform:
::
stb_init();
start_preload_resource(RESOURCE_ID_CAPP, 0, capp_ucode_info.lid, &capp_ucode_info.size);
sb_verify(id, buf, len);
tb_measure(id, buf, len);
start_preload_resource(RESOURCE_ID_KERNEL, 0, KERNEL_LOAD_BASE, &kernel_size);
sb_verify(id, buf, len);
tb_measure(id, buf, len);
stb_final();
First, ``stb_init()`` must be called to initialize libstb. Basically, it reads both
secure mode and trusted mode flags and loads drivers accordingly. In P8, secure
mode and trusted mode are read from the *ibm,secureboot* device tree node (see
:ref:`device-tree/ibm,secureboot`).
If either secure mode or trusted mode is on, ``stb_init()`` loads a driver (romcode
driver) to access the verification and SHA512 functions provided by the code
stored in the secure ROM at manufacture time. Both secure boot and trusted boot
depends on the romcode driver to access the ROM code. If trusted mode is on,
``stb_init()`` loads a TPM device driver compatible with the tpm device tree node
and also initializes the existing event log in skiboot. For device tree bindings
for the TPM, see :ref:`device-tree/tpm`.
Once libstb is initialized in the platform, ``sb_verify()`` and ``tb_measure()`` can
used as shown in the example above to respectively verify and measure images
retrieved from PNOR. If a platform claims secure and trusted boot support, then
``sb_verify()`` and ``tb_measure()`` is called for all images retrieved from PNOR.
``sb_verify()`` and ``tb_measure()`` do nothing if libstb is not initialized in the
platform since both secure mode and trusted mode are off by default.
Finally, ``stb_final()`` must be called when no more images need to be retrieved
from PNOR in order to indicate that secure boot and trusted boot have completed
in skiboot. When stb_final() is called, basically it records eight *EV_SEPARATOR*
events in the event log (one for each PCR through 0 to 7) and extends the PCR
through 0 to 7 of both SHA1 and SHA256 PCR banks with the digest of *0xFFFFFFFF*.
Additionally, ``stb_final()`` also frees resources allocated for secure boot and
trusted boot.
Verifying an image
~~~~~~~~~~~~~~~~~~
If secure mode is on, ``sb_verify()`` verifies the integrity and authenticity of an
image by calling the ``ROM_verify()`` function from the ROM code via romcode driver. In
general terms, this verification will pass only if the following conditions are
satisfied. Otherwise the boot process is aborted.
1. Secure boot header is properly built and attached to the image. When
``sb_verify()`` is called, the ROM code verifies all the secure boot header
fields, including the keys, hashes and signatures. The secure boot header
and the image are also collectively referred to as secure boot container, or
just container. As the secure boot header is the container header and the
image is the container payload.
2. The public hardware keys of the container header match with the hw-key-hash
read from the device tree. The way that secure boot is designed, this
assertion ensures that only images signed by the owner of the hw-key-hash
will pass the verification. The hw-key-hash is a hash of three hardware
public keys stored in *SEEPROM* at manufacture time and written to the device
tree at boot time.
Measuring an image
~~~~~~~~~~~~~~~~~~
``tb_measure()`` measures an image retrieved from PNOR if trusted mode is on, but
only if the provided image is included in the *resource_map* whitelist. This
whitelist defines for each expected image to what PCR the measurement must be
recorded and extended. ``tb_measure()`` returns an error if the provided image is
not included in the *resource_map* whitelist.
For the sake of simplicity we say that ``tb_measure()`` measures an image, but
calculating the digest of a given image is just one of the steps performed by
``tb_measure()``.
Steps performed by ``tb_measure()`` if trusted mode is on:
1. Measure the provided image for each PCR bank: SHA1 and SHA256. If secure
mode is on and the image is a container, parse the container header to get
the SHA512 hash of the container payload (*sw-payload-hash* field). Otherwise,
call the ROM code via romcode driver to calculate the SHA512 hash of the
image at boot time. In both cases, the SHA512 hash is truncated to match the
size required by each PCR bank: SHA1 bank PCRs are 20 bytes and SHA256 bank
PCRs are 32 bytes.
2. Record a new event in the event log for the mapped PCR. Call the tpmLogMgr
API to generate a new event and record it in the event log. The new event is
generated for the mapped PCR and it also contains a digest list with both
SHA1 and SHA256 measurements obtained in step 1.
3. Extend the measurements into the mapped PCR. Call the TCG Software Stack
(TSS) API to extend both measurements obtained in step 1 into the mapped PCR
number. The SHA1 measurement is extended to the SHA1 PCR bank and the SHA256
measurement is extended to the SHA256 PCR bank. However, they are extended
to the same PCR number on each bank.
Since this TSS implementation supports multibank, it does the marshalling of
both SHA1 and SHA256 measurements into a single TPM extend command and then
it sends the command to the TPM device via TPM device driver.
Both TSS and tpmLogMgr APIs are implemented by hostboot, but their source code
are added to skiboot. The TSS and tpmLogMgr interfaces are defined in
``libstb/tss/trustedbootCmds.H`` and ``libstb/tss/tpmLogMgr.H``, respectively.
|
