diff mbox series

[RFC,v2,2/8] doc: add opal secvar documentation

Message ID 20190411224551.29401-3-erichte@linux.ibm.com
State RFC
Headers show
Series Initial Skiboot Secure Variable Support | expand

Checks

Context Check Description
snowpatch_ozlabs/snowpatch_job_snowpatch-skiboot-dco success Signed-off-by present
snowpatch_ozlabs/snowpatch_job_snowpatch-skiboot success Test snowpatch/job/snowpatch-skiboot on branch master
snowpatch_ozlabs/apply_patch success Successfully applied on branch master (ff79070d1c4cdc38f2ecb42e45b8322cb1efb819)

Commit Message

Eric Richter April 11, 2019, 10:45 p.m. UTC
This patch contains all the relevant documentation for the secure variable
support in OPAL. This may be split and squashed with their relevant
implementations in the future, but kept separate for now.

Notably missing at the moment is the documentation for the SECBOOT PNOR
partition usage, which will be included in a future revision.

v2:
 - removed k_ prefix on all parameters
 - changed all uint64_t types to their actual intended type
 - added a new overview preamble, work in progress

Signed-off-by: Eric Richter <erichte@linux.ibm.com>
---
 doc/opal-api/opal-secvar.rst | 188 +++++++++++++++++++++++++++++++++++
 1 file changed, 188 insertions(+)
 create mode 100644 doc/opal-api/opal-secvar.rst

Comments

Michael Ellerman April 17, 2019, 7:13 a.m. UTC | #1
Hi Eric,

A query below ...

Eric Richter <erichte@linux.ibm.com> writes:
> This patch contains all the relevant documentation for the secure variable
> support in OPAL. This may be split and squashed with their relevant
> implementations in the future, but kept separate for now.
>
> Notably missing at the moment is the documentation for the SECBOOT PNOR
> partition usage, which will be included in a future revision.
>
...
> +OPAL_SECVAR_GET
> +===============
> +::
> +
> +   #define OPAL_SECVAR_GET                         170
> +
> +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
> +name and vendor guid.
> +
> +Parameters
> +----------
> +::
> +
> +   char16_t *name
> +   guid_t   *vendor
> +   uint32_t *attributes
> +   uint64_t *data_size
> +   void     *data
> +
> +``name``
> +   the name of the requested variable as a 16-bit char
> +
> +``vendor``
> +   the vendor guid of the requested variable
> +
> +``attributes``
> +   optional bitfield reference to be set by OPAL for attributes

I understand the UCS-2 name and guid come from UEFI, but is that really
something we need to bake into the OPAL API?

It seems the (name + vendor) essentially form a key, so could we just
make the API take a key as a byte array? That way we're not tying the
OPAL API or implementation to any details of UEFI, while still allowing
the user of the API (the kernel) to use UEFI style keys if it wants to.

So eg. the parameters for OPAL_SECVAR_GET would be:

   char     *key
   uint32_t key_len
   uint32_t *attributes
   uint64_t *data_size
   void     *data


The kernel could construct the key as the concatenation of the UCS-2
name & vendor or vice versa, or a simple byte string or whatever it
likes.

cheers
diff mbox series

Patch

diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
new file mode 100644
index 00000000..382b9eb4
--- /dev/null
+++ b/doc/opal-api/opal-secvar.rst
@@ -0,0 +1,188 @@ 
+OPAL Secure Variables
+=====================
+
+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 name+vendor guid pair (see "types" below).
+``opal_secvar_get_next`` can be used to iterate through the stored
+variables. ``opal_secvar_enqueue_update`` can be used to submit a new
+variable for processing on next boot.
+
+Types
+-----
+
+This document uses the following non-standard types:
+::
+
+   char16_t - 16-bit char, in little endian ucs2
+   guid_t   - 16-byte UUID blob
+
+
+OPAL_SECVAR_GET
+===============
+::
+
+   #define OPAL_SECVAR_GET                         170
+
+``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
+name and vendor guid.
+
+Parameters
+----------
+::
+
+   char16_t *name
+   guid_t   *vendor
+   uint32_t *attributes
+   uint64_t *data_size
+   void     *data
+
+``name``
+   the name of the requested variable as a 16-bit char
+
+``vendor``
+   the vendor guid of the requested variable
+
+``attributes``
+   optional bitfield reference to be set by OPAL for attributes
+related to the variable data
+
+``data_size``
+   reference to the size of the ``data`` 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 request only the size
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   data from the requested variable was copied successfully, or
+``data`` was set to NULL and the ``data_size`` was set to the
+requested variable's size
+
+``OPAL_PARAMETER``
+   ``name``, ``vendor`` or ``data_size`` are invalid buffers,
+contain invalid values
+
+``OPAL_EMPTY``
+   no variable with the supplied ``name`` and ``vendor`` was found
+
+``OPAL_PARTIAL``
+   the buffer size provided in ``data_size`` is too small for the
+requested variable
+
+``OPAL_UNSUPPORTED``
+   secure variable support is disabled
+
+OPAL_SECVAR_GET_NEXT
+====================
+::
+
+   #define OPAL_SECVAR_GET_NEXT                        171
+
+``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next
+variable in the secure variable bank in sequence.
+
+Parameters
+----------
+::
+
+   size_t   *name_size
+   char16_t *name
+   guid_t   *vendor
+
+``name_size``
+   size of the ``name`` buffer. OPAL sets this to the size of the
+next variable in sequence
+
+``name``
+   name of the previous variable or empty. The name of the next
+variable in sequence will be copied to ``name``
+
+``vendor``
+   vendor guid of the previous variable or empty. The vendor of the
+next vendor in sequence will be copied to ``vendor``
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  the name and vendor of the next variable in sequence was copied
+successfully
+
+``OPAL_PARAMETER``
+  ``name`` or ``vendor`` are invalid buffers, or were not found.
+``name_size`` is an invalid value. A variable matching the
+supplied non-empty ``name`` and ``vendor`` was not found
+
+``OPAL_EMPTY``
+  end of list reached
+
+``OPAL_PARTIAL``
+  the size specified in ``name_size`` is insufficient for the next
+variable's name size
+
+``OPAL_HARDWARE``
+  secure variable support is disabled
+
+OPAL_SECVAR_ENQUEUE_UPDATE
+==========================
+::
+
+   #define OPAL_SECVAR_ENQUEUE_UPDATE                    172
+
+``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
+queue for processing on next boot.
+
+Parameters
+----------
+::
+
+   char16_t *name
+   guid_t   *vendor
+   uint32_t  attributes
+   size_t    data_size
+   void     *data
+
+``name``
+   the name of the submitted variable as a 16-bit char
+
+``vendor``
+   the vendor guid of the submitted variable
+
+``attributes``
+   bitfield of attributes
+
+``data_size``
+   size of the buffer to copy from ``data``
+
+``data``
+   blob of data to be stored
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+   the variable was appended to the update queue bank successfully
+
+``OPAL_PARAMETER``
+   ``name``, ``vendor`` or ``data`` are invalid buffers.
+``name`` is empty. ``data_size`` is an invalid value. ``data_size``
+was set to zero (potentially an unsupported deletion attempt)
+
+``OPAL_NO_MEM``
+   OPAL was unable to allocate memory for the variable
+
+``OPAL_UNSUPPORTED``
+   secure variable support is disabled