192 lines
4.7 KiB
ReStructuredText
192 lines
4.7 KiB
ReStructuredText
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
|