[Skiboot] [PATCH v5 1/4] doc: add opal secure variable documentation
Eric Richter
erichte at linux.ibm.com
Thu Oct 31 09:48:36 AEDT 2019
This patch contains the work-in-progress documentation for the
secure variable design in OPAL. Future revisions of this patch
set will (hopefully) add new pieces of documentation here.
V3:
- removed metadata
- removed get_size
- updated _get semantics for size queries
- added/expanded device tree properties
V4:
- updated for new device tree changes
V5:
- removed incorrect ibm,secureboot changes
- rewrote bindings using a different format
- moved secvar documentation under ibm,opal
Signed-off-by: Eric Richter <erichte at linux.ibm.com>
---
doc/device-tree/ibm,opal/secvar/binding.rst | 205 ++++++++++++++++++++
doc/opal-api/opal-secvar.rst | 192 ++++++++++++++++++
2 files changed, 397 insertions(+)
create mode 100644 doc/device-tree/ibm,opal/secvar/binding.rst
create mode 100644 doc/opal-api/opal-secvar.rst
diff --git a/doc/device-tree/ibm,opal/secvar/binding.rst b/doc/device-tree/ibm,opal/secvar/binding.rst
new file mode 100644
index 00000000..7c0ec23e
--- /dev/null
+++ b/doc/device-tree/ibm,opal/secvar/binding.rst
@@ -0,0 +1,205 @@
+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:
+ "ibm,secvar-v1"
+
+ This property refers to the compatibility of the overall secvar design.
+ This covers the required nodes and properties within the secvar node,
+ as well as the features available via the secvar OPAL API functions.
+
+- 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.
+
+- os-secure-enforcing
+
+ Usage:
+ optional
+
+ Definition:
+
+ This property 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 is
+ created by the backend, it is up to the backend to define the
+ required state of the secure variables should be.
+
+ 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.
+
+ The property does not store any meaningful data.
+
+- 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.
+
+
+/ibm,opal/secvar/backend node bindings
+--------------------------------------
+
+The secvar node must define a child node for the current running backend.
+
+This node should contain any backend-specific logic that may need to be
+consumed by kernels, users, etc.
+
+Any additional non-required properties should be documented by their
+respective backend.
+
+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.
+
+ Furthermore, it defines any additional, non-required properties
+ within this node.
+
+
+
+Example
+-------
+
+.. code-block:: dts
+
+ /ibm,opal/secvar {
+ compatible = "ibm,secvar-v1";
+
+ status = "okay";
+ os-secure-enforcing;
+ max-var-size = <0x1000>;
+ max-var-key-len = <0x400>
+
+ backend {
+ compatible = "ibm,edk2-compat-v1";
+ };
+
+ };
+
+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 |
++-----------------+-----------------------------------------------+
+
diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
new file mode 100644
index 00000000..f07c570a
--- /dev/null
+++ b/doc/opal-api/opal-secvar.rst
@@ -0,0 +1,192 @@
+OPAL Secure Variable API
+========================
+
+Overview
+--------
+
+In order to support host OS secure boot on POWER systems, the platform needs
+some form of tamper-resistant persistant storage for authorized public keys.
+Furthermore, these keys must be retrieveable by the host kernel, and new
+keys must be able to be submitted.
+
+OPAL exposes an abstracted "variable" API, in which these keys can be stored
+and retrieved. At a high level, ``opal_secvar_get`` retrieves a specific
+variable corresponding to a particular key. ``opal_secvar_get_next`` can be
+used to iterate through the keys of the stored variables.
+``opal_secvar_enqueue_update`` can be used to submit a new variable for
+processing on next boot.
+
+OPAL_SECVAR_GET
+===============
+::
+
+ #define OPAL_SECVAR_GET 176
+
+``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
+key.
+
+
+Parameters
+----------
+::
+
+ char *key
+ uint64_t key_len
+ void *data
+ uint64_t *data_size
+
+``key``
+ a buffer used to associate with the variable data. May
+be any encoding, but must not be all zeroes
+
+``key_len``
+ size of the key buffer in bytes
+
+``data``
+ return buffer to store the data blob of the requested variable if
+a match was found. May be set to NULL to only query the size into
+``data_size``
+
+``data_size``
+ reference to the size of the ``data`` buffer. OPAL sets this to
+the size of the requested variable if found.
+
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the requested data blob was copied successfully. ``data`` was NULL,
+and the ``data_size`` value was set successfully
+
+``OPAL_PARAMETER``
+ ``key`` is NULL.
+ ``key_len`` is zero.
+ ``data_size`` is NULL.
+
+``OPAL_EMPTY``
+ no variable with the supplied ``key`` was found
+
+``OPAL_PARTIAL``
+ the buffer size provided in ``data_size`` was insufficient.
+``data_size`` is set to the minimum required size.
+
+``OPAL_UNSUPPORTED``
+ secure variables are not supported by the platform
+
+``OPAL_RESOURCE``
+ secure variables are supported, but did not initialize properly
+
+OPAL_SECVAR_GET_NEXT
+====================
+::
+
+ #define OPAL_SECVAR_GET_NEXT 177
+
+``OPAL_SECVAR_GET_NEXT`` returns the key of the next variable in the secure
+variable bank in sequence.
+
+Parameters
+----------
+::
+
+ char *key
+ uint64_t *key_len
+ uint64_t key_buf_size
+
+
+``key``
+ name of the previous variable or empty. The key of the next
+variable in sequence will be copied to ``key``. If passed as empty,
+returns the first variable in the bank
+
+``key_len``
+ length in bytes of the key in the ``key`` buffer. OPAL sets
+this to the length in bytes of the next variable in sequence
+
+``key_buf_size``
+ maximum size of the ``key`` buffer. The next key will not be
+copied if this value is less than the length of the next key
+
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the key and length of the next variable in sequence was copied
+successfully
+
+``OPAL_PARAMETER``
+ ``key`` or ``key_length`` is NULL.
+ ``key_size`` is zero.
+ ``key_length`` is impossibly large. No variable with the associated
+``key`` was found
+
+``OPAL_EMPTY``
+ end of list reached
+
+``OPAL_PARTIAL``
+ the size specified in ``key_size`` is insufficient for the next
+variable's key length. ``key_length`` is set to the next variable's
+length, but ``key`` is untouched
+
+``OPAL_UNSUPPORTED``
+ secure variables are not supported by the platform
+
+``OPAL_RESOURCE``
+ secure variables are supported, but did not initialize properly
+
+OPAL_SECVAR_ENQUEUE_UPDATE
+==========================
+::
+
+ #define OPAL_SECVAR_ENQUEUE_UPDATE 178
+
+``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
+queue for processing on next boot.
+
+Parameters
+----------
+::
+
+ char *key
+ uint64_t key_len
+ void *data
+ uint64_t data_size
+
+``key``
+ a buffer used to associate with the variable data. May
+be any encoding, but must not be all zeroes
+
+``key_len``
+ size of the key buffer in bytes
+
+``data``
+ buffer containing the blob of data to enqueue
+
+``data_size``
+ size of the ``data`` buffer
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the variable was appended to the update queue bank successfully
+
+``OPAL_PARAMETER``
+ ``key`` or ``data`` was NULL.
+ ``key`` was empty.
+ ``key_len`` or ``data_size`` was zero.
+ ``key_len``, ``data_size`` is larger than the maximum size
+
+``OPAL_NO_MEM``
+ OPAL was unable to allocate memory for the variable update
+
+``OPAL_HARDWARE``
+ OPAL was unable to write the update to persistant storage
+
+``OPAL_UNSUPPORTED``
+ secure variables are not supported by the platform
+
+``OPAL_RESOURCE``
+ secure variables are supported, but did not initialize properly
--
2.21.0
More information about the Skiboot
mailing list