[Skiboot] [PATCH v2 5/9] doc: add opal secure variable documentation
Eric Richter
erichte at linux.ibm.com
Wed Jun 26 08:02:11 AEST 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.
Signed-off-by: Eric Richter <erichte at linux.ibm.com>
---
doc/device-tree/ibm,secureboot.rst | 10 ++
doc/device-tree/secvar.rst | 40 +++++
doc/opal-api/opal-secvar.rst | 267 +++++++++++++++++++++++++++++
3 files changed, 317 insertions(+)
create mode 100644 doc/device-tree/secvar.rst
create mode 100644 doc/opal-api/opal-secvar.rst
diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst
index 42c4ed7d..b4729a9d 100644
--- a/doc/device-tree/ibm,secureboot.rst
+++ b/doc/device-tree/ibm,secureboot.rst
@@ -21,6 +21,13 @@ Required properties
It described by the ibm,cvc child
node.
+ ibm,secureboot-v3 : The container-verification-code
+ is stored in a reserved memory.
+ It described by the ibm,cvc child
+ node. Secure variables are
+ supported. `secvar` node should
+ be created.
+
secure-enabled: this property exists when the firmware stack is booting
in secure mode (hardware secure boot jumper asserted).
@@ -33,6 +40,9 @@ Required properties
hw-key-hash-size: hw-key-hash size
+ secvar: this node is created if the platform supports secure
+ variables. Contains information about the current
+ secvar status, see 'secvar.rst'.
Obsolete properties
-------------------
diff --git a/doc/device-tree/secvar.rst b/doc/device-tree/secvar.rst
new file mode 100644
index 00000000..5bfe932e
--- /dev/null
+++ b/doc/device-tree/secvar.rst
@@ -0,0 +1,40 @@
+.. _device-tree/ibm,secureboot/secvar:
+
+secvar
+======
+
+The ``secvar`` node provides secure variable information for the secure
+boot of the target OS.
+
+Required properties
+-------------------
+
+.. code-block:: none
+
+ compatible: this property is set based on the current secure
+ variable scheme as set by the platform.
+
+ version: this property contains the minor version number
+ for the selected secure variable compatible. This
+ value should only be incremented for additive
+ features.
+
+ status: set to "fail" if the secure variables could not
+ be initialized, validated, or some other
+ catastrophic failure.
+
+ update-status: contains the return code of the update queue
+ process run during initialization. Signifies if
+ updates were processed or not, and if there was
+ an error.
+
+Example
+-------
+
+.. code-block:: dts
+
+ secvar {
+ compatible = "ibm,edk2-compat-v1";
+ version = <0x1>;
+ status = "okay";
+ };
diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
new file mode 100644
index 00000000..46aad0af
--- /dev/null
+++ b/doc/opal-api/opal-secvar.rst
@@ -0,0 +1,267 @@
+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 173
+
+``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
+key.
+
+
+Parameters
+----------
+::
+
+ char *key
+ uint64_t key_len
+ void *metadata
+ uint64_t *metadata_size
+ 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
+
+``metadata``
+ return buffer to store any additional data specific to the
+active variable scheme. This may not be used for certain schemes.
+May be set to NULL to ignore returning the buffer only if
+``metadata_size`` is also NULL.
+
+``metadata_size``
+ reference to the size of the ``metadata`` buffer. OPAL sets this if
+the buffer size is insufficient for the requested variable
+
+``data``
+ return buffer to store the data blob of the requested variable if
+a match was found. May be set to NULL to ignore returning the buffer
+only if ``data_size`` is also NULL.
+
+``data_size``
+ reference to the size of the ``data`` buffer. OPAL sets this if
+the buffer size is insufficient for the requested variable
+
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the requested metadata and/or data blobs were copied successfully
+
+``OPAL_PARAMETER``
+ ``key`` is NULL. ``key_len`` is zero. buffer and size pointers for
+metadata or data retrieval are not both NULL or non-NULL
+
+``OPAL_EMPTY``
+ no variable with the supplied ``key`` was found
+
+``OPAL_PARTIAL``
+ the buffer size provided in either or both of ``metadata_size`` or
+``data_size`` was insufficient. Insufficient value 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_SIZE
+====================
+::
+
+ #define OPAL_SECVAR_GET_SIZE 174
+
+``OPAL_SECVAR_GET_SIZE`` call retrieves the sizes of the metadata and/or
+data blobs associated with a given key. Convenience function to use
+as it returns the same size information as an insufficient
+``opal_secvar_get`` call.
+
+
+Parameters
+----------
+::
+
+ char *key
+ uint64_t key_len
+ uint64_t *metadata_size
+ 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
+
+``metadata_size``
+ reference to store the size of the metadata buffer associated with
+the ``key`` if found. May be NULL to ignore
+
+``data_size``
+ reference to store the size of the data buffer associated with
+the ``key`` if found. May be NULL to ignore
+
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the requested ``key`` exists, and the requested size values were
+copied successfully
+
+``OPAL_PARAMETER``
+ ``key`` is NULL. ``key_len`` is zero. Both size pointers are NULL
+
+``OPAL_EMPTY``
+ no variable with the supplied ``key`` was found
+
+``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 175
+
+``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_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_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 176
+
+``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 *metadata
+ uint64_t metadata_size
+ 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
+
+``metadata``
+ buffer containing the additional data specific to the
+active variable scheme. This may not be used for certain schemes.
+May be set to NULL to not set any metadata
+
+``metadata_size``
+ size of the ``metadata`` buffer
+
+``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``, ``metadata_size`` or ``data_size``
+were larger than their respective maximums
+
+``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.20.1
More information about the Skiboot
mailing list