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