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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Secure and Trusted Boot Library (LibSTB) Documentation — skiboot 4d27f03
documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Device Tree" href="device-tree.html" />
<link rel="prev" title="Virtual Accelerator Switchboard (VAS)" href="vas.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="device-tree.html" title="Device Tree"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="vas.html" title="Virtual Accelerator Switchboard (VAS)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">skiboot 4d27f03
documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="secure-and-trusted-boot-library-libstb-documentation">
<span id="stb-overview"></span><h1>Secure and Trusted Boot Library (LibSTB) Documentation<a class="headerlink" href="#secure-and-trusted-boot-library-libstb-documentation" title="Permalink to this headline">¶</a></h1>
<p><em>LibSTB</em> provides APIs to support Secure Boot and Trusted Boot in skiboot.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">Secure</span> <span class="pre">Boot:</span> <span class="pre">verify</span> <span class="pre">and</span> <span class="pre">enforce.</span></code></dt>
<dd>When the system is booting in secure mode, Secure Boot MUST ensure that
only trusted code is executed during system boot by verifying if the
code is signed with trusted keys and halting the system boot if the
verification fails.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Trusted</span> <span class="pre">Boot:</span> <span class="pre">measure</span> <span class="pre">and</span> <span class="pre">record.</span></code></dt>
<dd>When the system is booting in trusted mode, Trusted Boot MUST create
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.</dd>
</dl>
<p>In order to support Secure and Trusted Boot, the flash driver calls libSTB to
verify and measure the code it fetches from PNOR.</p>
<p>LibSTB is initialized by calling <em>secureboot_init()</em>, see <code class="docutils literal notranslate"><span class="pre">libstb/secureboot.h</span></code>.</p>
<div class="section" id="secure-boot">
<h2>Secure Boot<a class="headerlink" href="#secure-boot" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">Requirements:</span></code></dt>
<dd><ol class="first last arabic simple">
<li>CVC-verify service to verify signed firmware code.</li>
</ol>
</dd>
</dl>
<p>Secure boot is initialized by calling <em>secureboot_init()</em> and its API is quite
simple, see <code class="docutils literal notranslate"><span class="pre">libstb/secureboot.h</span></code>.</p>
<p>The flash driver calls <code class="docutils literal notranslate"><span class="pre">secureboot_verify()</span></code> to verify if the fetched firmware
blob is properly signed with keys trusted by the platform owner. This
verification is performed only when the system is booting in secure mode. If
the verification fails, it enforces a halt of the system boot.</p>
<p>The verification itself is performed by the <a class="reference internal" href="#container-verification-code"><span class="std std-ref">Container Verification Code</span></a>,
precisely the <em>CVC-verify</em> service, which requires both the fetched code and the
hardware key hash trusted by the platform owner.</p>
<p>The secure mode status, hardware key hash and hardware key hash size
information is found in the device tree, see
<a class="reference internal" href="device-tree/ibm,secureboot.html#device-tree-ibm-secureboot"><span class="std std-ref">doc/device-tree/ibm,secureboot.rst</span></a>.</p>
<div class="section" id="signing-firmware-code">
<span id="id1"></span><h3>Signing Firmware Code<a class="headerlink" href="#signing-firmware-code" title="Permalink to this headline">¶</a></h3>
<p>Fimware code is signed using the <code class="docutils literal notranslate"><span class="pre">sb-signing-utils</span></code> utilities by running it
standalone or just calling op-build. The latter will automatically sign the
various firmware components that comprise the PNOR image if SECUREBOOT is
enabled for the platform.</p>
<p>The signing utilities also allow signing firmware code using published hardware
keys (a.k.a. imprint keys, only for development) or production hardware keys,
see <a class="reference external" href="https://github.com/open-power/sb-signing-utils">sb-signing-utils</a>.</p>
<p>The hardware keys are the root keys. The signing tool uses three hardware keys
to sign up to three firmware keys, which are then used to sign the firmware
code. The resulting signed firmware code is then assembled following the secure
boot container format. All the information required to verify the signatures is
placed in the first 4K reserved for the container header (e.g. public keys,
hashes and signatures). The firmware code itself is placed in the container
payload.</p>
</div>
</div>
<div class="section" id="container-verification-code">
<span id="id2"></span><h2>Container Verification Code<a class="headerlink" href="#container-verification-code" title="Permalink to this headline">¶</a></h2>
<p>The <em>Container Verification Code</em> (a.k.a. ROM code) is stored in a secure
memory region and it provides basic Secure and Trusted Boot services for the
entire firmware stack. See <cite>doc/device-tree/ibm,secureboot.rst
<device-tree/ibm,secureboot></cite> and <cite>doc/device-tree/ibm,cvc.rst
<device-tree/ibm,cvc></cite>.</p>
<p>LibSTB uses function wrappers to call into each CVC service, see
<code class="docutils literal notranslate"><span class="pre">libstb/cvc.h</span></code>.</p>
<div class="section" id="cvc-verify-service">
<h3>CVC-verify Service<a class="headerlink" href="#cvc-verify-service" title="Permalink to this headline">¶</a></h3>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">call_cvc_verify</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">hw_key_hash</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">hw_key_hash_size</span><span class="p">,</span> <span class="n">__be64</span> <span class="o">*</span><span class="n">log</span><span class="p">)</span>
</pre></div>
</div>
<p>This function wrapper calls into the <em>CVC-verify</em>, which verifies if the
firmware code provided in <code class="docutils literal notranslate"><span class="pre">@buf</span></code> is properly signed with the keys trusted by
the platform owner. Its parameters are documented in <code class="docutils literal notranslate"><span class="pre">libstb/cvc.h</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">@hw_key_hash</span></code> is used to check if the firware keys used to sign
the firmware blob can be trusted.</p>
<p><code class="docutils literal notranslate"><span class="pre">@log</span></code> is optional. If the verification fails, the caller can interpret
it to find out what checks has failed.</p>
<p>Enforcement is caller’s responsibility.</p>
</div>
<div class="section" id="cvc-sha512-service">
<h3>CVC-sha512 Service<a class="headerlink" href="#cvc-sha512-service" title="Permalink to this headline">¶</a></h3>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">call_cvc_sha512</span><span class="p">(</span><span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">data</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">data_len</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">digest</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">digest_size</span><span class="p">)</span>
</pre></div>
</div>
<p>This function wrapper calls into the <em>CVC-sha512</em>, which calculates the
sha512 hash of what is provided in @data. Its parameters are documented in
<code class="docutils literal notranslate"><span class="pre">libstb/cvc.h</span></code>.</p>
</div>
</div>
<div class="section" id="trusted-boot">
<h2>Trusted Boot<a class="headerlink" href="#trusted-boot" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">Requirements:</span></code></dt>
<dd><ol class="first last arabic simple">
<li>TPM device and TPM driver. See devices supported in
<a class="reference internal" href="device-tree/tpm.html#device-tree-tpm"><span class="std std-ref">doc/device-tree/tpm.rst</span></a>.</li>
<li>TCG Software Stack (TSS) to send commands to the TPM device.</li>
<li>Firmware Event Log driver to add new events to the log. Event log
address and size information is found in the device tree, see
<a class="reference internal" href="device-tree/tpm.html#device-tree-tpm"><span class="std std-ref">doc/device-tree/tpm.rst</span></a>.</li>
<li>CVC-sha512 service to calculate the sha512 hash of the data that
will be measured.</li>
</ol>
</dd>
</dl>
<p>The Trusted Boot API is quite simple, see <code class="docutils literal notranslate"><span class="pre">libstb/trustedboot.h</span></code>.</p>
<p>The flash driver calls <code class="docutils literal notranslate"><span class="pre">trustedboot_measure()</span></code> to measure the firmware code
fetched from PNOR and also record its measurement in two places. This is
performed only when the system is booting in trusted mode (information found in
the device tree, see <a class="reference internal" href="device-tree/ibm,secureboot.html#device-tree-ibm-secureboot"><span class="std std-ref">doc/device-tree/ibm,secureboot.rst</span></a>).</p>
<p>Once the firmware code is measured by calling the <em>CVC-sha512</em> service, its
measurement is first recorded in a TPM PCR statically defined for each event.
In order to record it, the skiboot TCG Software Stack (TSS) API is called to
extend the measurement into the PCR number of both the sha1 and sha256 banks.
The skiboot TSS is a light TSS implementation and its source code is shared
between hostboot and skiboot, see <code class="docutils literal notranslate"><span class="pre">libstb/tss/trustedbootCmds.H</span></code>.</p>
<p>PCR extend is an TPM 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
records the hash of this new string in the PCR.</p>
<p>The measurement is also recorded in the event log. The <code class="docutils literal notranslate"><span class="pre">TpmLogMgr_addEvent()</span></code>
function is called to add the measurement to the log, see
<code class="docutils literal notranslate"><span class="pre">libstb/tss/tpmLogMgr.H</span></code>.</p>
<p>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.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Secure and Trusted Boot Library (LibSTB) Documentation</a><ul>
<li><a class="reference internal" href="#secure-boot">Secure Boot</a><ul>
<li><a class="reference internal" href="#signing-firmware-code">Signing Firmware Code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#container-verification-code">Container Verification Code</a><ul>
<li><a class="reference internal" href="#cvc-verify-service">CVC-verify Service</a></li>
<li><a class="reference internal" href="#cvc-sha512-service">CVC-sha512 Service</a></li>
</ul>
</li>
<li><a class="reference internal" href="#trusted-boot">Trusted Boot</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="vas.html"
title="previous chapter">Virtual Accelerator Switchboard (VAS)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="device-tree.html"
title="next chapter">Device Tree</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/stb.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="device-tree.html" title="Device Tree"
>next</a> |</li>
<li class="right" >
<a href="vas.html" title="Virtual Accelerator Switchboard (VAS)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">skiboot 4d27f03
documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2016-2017, IBM, others.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>
|
