diff --git a/doc/device-tree/ibm,opal/secvar/binding.rst b/doc/device-tree/ibm,opal/secvar/binding.rst new file mode 100644 index 000000000000..bc86fb2b08f2 --- /dev/null +++ b/doc/device-tree/ibm,opal/secvar/binding.rst @@ -0,0 +1,169 @@ +secvar Binding +============== + +This device tree binding describes the status of secure variable support, +including any size values, or values relating to the secure state of the +system. + + +/ibm,opal/secvar node bindings +------------------------------ + +Node: secvar + +Description: Container of secvar related properties. + +The node name must be "secvar". + +It is implemented as a child of the node "/ibm,opal". + +The node is optional, will be defined if the platform supports secure +variables. It will not be created if the system does not. + +Properties: + +- compatible + + Usage: + required + Value type: + string + + Definition: + + This property defines the compatibility of the current running + backend. This defines the binary format of the data buffers passed + via the related secvar OPAL API functions. This also defines the + expected behavior of how updates should be processed, such as how + key updates should be signed, what the key hierarchy is, what + algorithms are in use, etc. + + This value also determines how a user can signal a desire to require + all further images to require signature validations. See the + "On Enforcing Secure Mode" section below. + +- status + + Usage: + required + Value type: + string + + Definition: + + This property states the general status of secure variable support. This + will be set to "okay" if the secvar OPAL API should be working as expected, + and there were no unrecoverable faults in the basic secure variable + initialization logic. + + This property may be set to "fail" if the platform does not properly + select the drivers to use. Failures may also occur if the storage devices + are inaccessible for some reason. + + Failures are NOT caused by malformed data loaded or processed in either + storage or backend drivers, as these are faults correctable by a user. + +- update-status + + Usage: + required + Value type: + + + Definition: + + This property should contain the status code of the update processing + logic, as returned by the backend. This value is intended to be + consumed by userspace tools to confirm updates were processed as + intended. + + The value contained in this property should adhere to the table below. + Any additional error states that may be specific to a backend should + be stored in the backend node. + + +- max-var-size + + Usage: + required + Value type: + + + Definition: + + This is the maximum buffer size accepted for secure variables. The API + will reject updates larger than this value, and storage drivers must + reject loading variables larger than this value. + + As this may depend on the persistant storage devices in use, this + value is determined by the storage driver, and may differ across + platforms. + +- max-var-key-len + + Usage: + required + Value type: + + + Definition: + + This is the maximum size permitted for the key of a variable. As the + value is a constant, it should be the same across platforms unless + changed in code. + + +Example +------- + +.. code-block:: dts + + /ibm,opal/secvar { + compatible = "ibm,edk2-compat-v1"; + + status = "okay"; + max-var-size = <0x1000>; + max-var-key-len = <0x400> + }; + +Update Status Code Table +------------------------ + +The update status property should be set by the backend driver to a value +that best fits its error condition. The following table defines the +general intent of each error code, check backend specific documentation +for more detail. + ++-----------------+-----------------------------------------------+ +| update-status | Generic Reason | ++-----------------|-----------------------------------------------+ +| OPAL_SUCCESS | Updates were found and processed successfully | ++-----------------|-----------------------------------------------+ +| OPAL_EMPTY | No updates were found, none processed | ++-----------------|-----------------------------------------------+ +| OPAL_PARAMETER | Malformed, or unexpected update data blob | ++-----------------|-----------------------------------------------+ +| OPAL_PERMISSION | Update failed to apply, possible auth failure | ++-----------------|-----------------------------------------------+ +| OPAL_HARDWARE | Misc. storage-related error | ++-----------------|-----------------------------------------------+ +| OPAL_RESOURCE | Out of space (reported by storage | ++-----------------|-----------------------------------------------+ +| OPAL_NO_MEM | Out of memory | ++-----------------+-----------------------------------------------+ + + +On Enforcing Secure Mode +------------------------ + +The os-secureboot-enforcing property in /ibm,secureboot/ is created by the +backend if the owner has expressed a desire for boot loaders, kernels, etc +to require any images to be signed by an appropriate key stored in secure +variables. As this property is created by the backend, it is up to the +backend to define what the required state of the secure variables should +be to enter this mode. + +For example, we may want to only enable secure boot if we have a top- +level "Platform Key", so this property is created by the backend if +by the end of update processing, a "PK" variable exists. By enrolling a +PK, the system will be in "secure mode" until the PK is deleted. diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst index 42c4ed7dc32d..3113b3f28d8c 100644 --- a/doc/device-tree/ibm,secureboot.rst +++ b/doc/device-tree/ibm,secureboot.rst @@ -33,6 +33,11 @@ Required properties hw-key-hash-size: hw-key-hash size + os-secureboot-enforcing: + this property is created by the secure variable backend + if it detects a desire by the owner to requre any + images (e.g. kernels) to be signed by an appropriate + key stored in secure variables. Obsolete properties ------------------- diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst new file mode 100644 index 000000000000..f07c570a8ec7 --- /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