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
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Secvar Binding — skiboot 80e2b1d
documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/classic.css" />
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="ibm,opal/sensor-groups" href="sensor-groups.html" />
<link rel="prev" title="power-mgt/psr" href="power-mgt/psr.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="sensor-groups.html" title="ibm,opal/sensor-groups"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="power-mgt/psr.html" title="power-mgt/psr"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 80e2b1d
documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >Device Tree</a> »</li>
<li class="nav-item nav-item-2"><a href="../ibm%2Copal.html" accesskey="U">ibm,opal</a> »</li>
<li class="nav-item nav-item-this"><a href="">Secvar Binding</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="secvar-binding">
<span id="device-tree-ibm-opal-secvar"></span><h1>Secvar Binding<a class="headerlink" href="#secvar-binding" title="Permalink to this headline">¶</a></h1>
<p>This device tree binding describes the status of secure variable support,
including any size values, or values relating to the secure state of the
system.</p>
<section id="ibm-opal-secvar-node-bindings">
<h2>/ibm,opal/secvar node bindings<a class="headerlink" href="#ibm-opal-secvar-node-bindings" title="Permalink to this headline">¶</a></h2>
<p>Node: secvar</p>
<p>Description: Container of secvar related properties.</p>
<p>The node name must be “secvar”.</p>
<p>It is implemented as a child of the node “/ibm,opal”.</p>
<p>The node is optional, will be defined if the platform supports secure
variables. It will not be created if the system does not.</p>
<p>Properties:</p>
<ul>
<li><p>compatible</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p>string</p>
</dd>
</dl>
<p>Definition:</p>
<p>This property defines the compatibility of the current running
backend. This defines the binary format of the data buffers passed
via the related secvar OPAL API functions. This also defines the
expected behavior of how updates should be processed, such as how
key updates should be signed, what the key hierarchy is, what
algorithms are in use, etc.</p>
<p>This value also determines how a user can signal a desire to require
all further images to require signature validations. See the
“On Enforcing Secure Mode” section below.</p>
<p>This property also contains a generic “ibm,secvar-backend” compatible,
which defines the basic-level compatibility of the secvar implementation.
This includes the basic behavior of the API (excluding the data format),
and the expected device tree properties contained in this node.</p>
</li>
<li><p>format</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p>string</p>
</dd>
</dl>
<p>This property defines the format of data passed in and out of the secvar
API. In most cases, this should be the same string as the backend-specific
string in compatible.</p>
<p>The format defined by this string should be documented by the corresponding
backend.</p>
</li>
<li><p>status</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p>string</p>
</dd>
</dl>
<p>Definition:</p>
<p>This property states the general status of secure variable support. This
will be set to “okay” if the secvar OPAL API should be working as expected,
and there were no unrecoverable faults in the basic secure variable
initialization logic.</p>
<p>This property may be set to “fail” if the platform does not properly
select the drivers to use. Failures may also occur if the storage devices
are inaccessible for some reason.</p>
<p>Failures are NOT caused by malformed data loaded or processed in either
storage or backend drivers, as these are faults correctable by a user.</p>
</li>
<li><p>update-status</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u64></p>
</dd>
</dl>
<p>Definition:</p>
<p>This property should contain the status code of the update processing
logic, as returned by the backend. This value is intended to be
consumed by userspace tools to confirm updates were processed as
intended.</p>
<p>The value contained in this property should adhere to the table below.
Any additional error states that may be specific to a backend should
be stored in the backend node.</p>
</li>
<li><p>max-var-size</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u64></p>
</dd>
</dl>
<p>Definition:</p>
<p>This is the maximum buffer size accepted for secure variables. The API
will reject updates larger than this value, and storage drivers must
reject loading variables larger than this value.</p>
<p>As this may depend on the persistant storage devices in use, this
value is determined by the storage driver, and may differ across
platforms.</p>
</li>
<li><p>max-var-key-len</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u64></p>
</dd>
</dl>
<p>Definition:</p>
<p>This is the maximum size permitted for the key of a variable. As the
value is a constant, it should be the same across platforms unless
changed in code.</p>
</li>
</ul>
</section>
<section id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<div class="highlight-dts notranslate"><div class="highlight"><pre><span></span><span class="err">/ibm,opal/</span><span class="nc">secvar</span> <span class="p">{</span>
<span class="nf">compatible</span> <span class="o">=</span> <span class="s">"ibm,secvar-backend" "ibm,edk2-compat-v1"</span><span class="p">;</span>
<span class="nf">status</span> <span class="o">=</span> <span class="s">"okay"</span><span class="p">;</span>
<span class="nf">max-var-size</span> <span class="o">=</span> <span class="p"><</span><span class="mh">0x1000</span><span class="p">>;</span>
<span class="nf">max-var-key-len</span> <span class="o">=</span> <span class="p"><</span><span class="mh">0x400</span><span class="p">></span>
<span class="err">}</span><span class="p">;</span>
</pre></div>
</div>
</section>
<section id="update-status-code-table">
<h2>Update Status Code Table<a class="headerlink" href="#update-status-code-table" title="Permalink to this headline">¶</a></h2>
<p>The update status property should be set by the backend driver to a value
that best fits its error condition. The following table defines the
general intent of each error code, check backend specific documentation
for more detail.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 27%" />
<col style="width: 73%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>update-status</p></td>
<td><p>Generic Reason</p></td>
</tr>
<tr class="row-even"><td><p>OPAL_SUCCESS</p></td>
<td><p>Updates were found and processed successfully</p></td>
</tr>
<tr class="row-odd"><td><p>OPAL_EMPTY</p></td>
<td><p>No updates were found, none processed</p></td>
</tr>
<tr class="row-even"><td><p>OPAL_PARAMETER</p></td>
<td><p>Malformed, or unexpected update data blob</p></td>
</tr>
<tr class="row-odd"><td><p>OPAL_PERMISSION</p></td>
<td><p>Update failed to apply, possible auth failure</p></td>
</tr>
<tr class="row-even"><td><p>OPAL_HARDWARE</p></td>
<td><p>Misc. storage-related error</p></td>
</tr>
<tr class="row-odd"><td><p>OPAL_RESOURCE</p></td>
<td><p>Out of space (reported by storage</p></td>
</tr>
<tr class="row-even"><td><p>OPAL_NO_MEM</p></td>
<td><p>Out of memory</p></td>
</tr>
</tbody>
</table>
</section>
<section id="on-enforcing-secure-mode">
<h2>On Enforcing Secure Mode<a class="headerlink" href="#on-enforcing-secure-mode" title="Permalink to this headline">¶</a></h2>
<p>The os-secureboot-enforcing property in /ibm,secureboot/ is created by the
backend if the owner has expressed a desire for boot loaders, kernels, etc
to require any images to be signed by an appropriate key stored in secure
variables. As this property is created by the backend, it is up to the
backend to define what the required state of the secure variables should
be to enter this mode.</p>
<p>For example, we may want to only enable secure boot if we have a top-
level “Platform Key”, so this property is created by the backend if
by the end of update processing, a “PK” variable exists. By enrolling a
PK, the system will be in “secure mode” until the PK is deleted.</p>
</section>
</section>
<div class="clearer"></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="#">Secvar Binding</a><ul>
<li><a class="reference internal" href="#ibm-opal-secvar-node-bindings">/ibm,opal/secvar node bindings</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#update-status-code-table">Update Status Code Table</a></li>
<li><a class="reference internal" href="#on-enforcing-secure-mode">On Enforcing Secure Mode</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="power-mgt/psr.html"
title="previous chapter">power-mgt/psr</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="sensor-groups.html"
title="next chapter">ibm,opal/sensor-groups</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/device-tree/ibm,opal/secvar.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#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="sensor-groups.html" title="ibm,opal/sensor-groups"
>next</a> |</li>
<li class="right" >
<a href="power-mgt/psr.html" title="power-mgt/psr"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 80e2b1d
documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >Device Tree</a> »</li>
<li class="nav-item nav-item-2"><a href="../ibm%2Copal.html" >ibm,opal</a> »</li>
<li class="nav-item nav-item-this"><a href="">Secvar Binding</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2016-2017, IBM, others.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>
|
