diff options
author | Eric Richter <erichte@linux.ibm.com> | 2019-11-04 22:20:07 -0600 |
---|---|---|
committer | Oliver O'Halloran <oohall@gmail.com> | 2019-11-07 17:46:33 +1100 |
commit | 04f0cdb9bbb04f0d6295165a3a218d6d234dbee6 (patch) | |
tree | 985b1ff402dd6beb2559ce2ff34618ce9a44ae73 /doc/opal-api/opal-secvar.rst | |
parent | 7af08f2f094b55e9ec901429146b65f998df1838 (diff) | |
download | skiboot-04f0cdb9bbb04f0d6295165a3a218d6d234dbee6.zip skiboot-04f0cdb9bbb04f0d6295165a3a218d6d234dbee6.tar.gz skiboot-04f0cdb9bbb04f0d6295165a3a218d6d234dbee6.tar.bz2 |
doc: add opal secure variable documentation
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@linux.ibm.com>
[oliver: whitespace error fixes, removed old backend node docs]
Signed-off-by: Oliver O'Halloran <oohall@gmail.com>
---
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
V6:
- moved os-secureboot-enforcing to ibm,secureboot
- removed backend node from secvar node
- updated documentation on secvar node compatible
Diffstat (limited to 'doc/opal-api/opal-secvar.rst')
-rw-r--r-- | doc/opal-api/opal-secvar.rst | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst new file mode 100644 index 0000000..f07c570 --- /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 |