190 lines
5.9 KiB
ReStructuredText
190 lines
5.9 KiB
ReStructuredText
.. _device-tree/ibm,opal/secvar:
|
|
|
|
Secvar Binding
|
|
==============
|
|
|
|
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.
|
|
|
|
|
|
/ibm,opal/secvar node bindings
|
|
------------------------------
|
|
|
|
Node: secvar
|
|
|
|
Description: Container of secvar related properties.
|
|
|
|
The node name must be "secvar".
|
|
|
|
It is implemented as a child of the node "/ibm,opal".
|
|
|
|
The node is optional, will be defined if the platform supports secure
|
|
variables. It will not be created if the system does not.
|
|
|
|
Properties:
|
|
|
|
- compatible
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
string
|
|
|
|
Definition:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
- format
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
string
|
|
|
|
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.
|
|
|
|
The format defined by this string should be documented by the corresponding
|
|
backend.
|
|
|
|
- status
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
string
|
|
|
|
Definition:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Failures are NOT caused by malformed data loaded or processed in either
|
|
storage or backend drivers, as these are faults correctable by a user.
|
|
|
|
- update-status
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
<u64>
|
|
|
|
Definition:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
- max-var-size
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
<u64>
|
|
|
|
Definition:
|
|
|
|
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.
|
|
|
|
As this may depend on the persistant storage devices in use, this
|
|
value is determined by the storage driver, and may differ across
|
|
platforms.
|
|
|
|
- max-var-key-len
|
|
|
|
Usage:
|
|
required
|
|
Value type:
|
|
<u64>
|
|
|
|
Definition:
|
|
|
|
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.
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: dts
|
|
|
|
/ibm,opal/secvar {
|
|
compatible = "ibm,secvar-backend" "ibm,edk2-compat-v1";
|
|
|
|
status = "okay";
|
|
max-var-size = <0x1000>;
|
|
max-var-key-len = <0x400>
|
|
};
|
|
|
|
Update Status Code Table
|
|
------------------------
|
|
|
|
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.
|
|
|
|
+-----------------+-----------------------------------------------+
|
|
| update-status | Generic Reason |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_SUCCESS | Updates were found and processed successfully |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_EMPTY | No updates were found, none processed |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_PARAMETER | Malformed, or unexpected update data blob |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_PERMISSION | Update failed to apply, possible auth failure |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_HARDWARE | Misc. storage-related error |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_RESOURCE | Out of space (reported by storage |
|
|
+-----------------+-----------------------------------------------+
|
|
| OPAL_NO_MEM | Out of memory |
|
|
+-----------------+-----------------------------------------------+
|
|
|
|
|
|
On Enforcing Secure Mode
|
|
------------------------
|
|
|
|
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.
|
|
|
|
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.
|