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