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