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.
#define OPAL_SECVAR_GET 176
OPAL_SECVAR_GET
call retrieves a data blob associated with the supplied key.
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.
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 foundOPAL_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
#define OPAL_SECVAR_GET_NEXT 177
OPAL_SECVAR_GET_NEXT
returns the key of the next variable in the secure variable bank in sequence.
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
OPAL_SUCCESS
the key and length of the next variable in sequence was copied
successfully
OPAL_PARAMETER
key
orkey_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
#define OPAL_SECVAR_ENQUEUE_UPDATE 178
OPAL_SECVAR_ENQUEUE
call appends the supplied variable data to the queue for processing on next boot.
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
OPAL_SUCCESS
the variable was appended to the update queue bank successfully
OPAL_PARAMETER
key
ordata
was NULL.key
was empty.key_len
ordata_size
was zero.key_len
,data_size
is larger than the maximum sizeOPAL_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