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.

  This property also contains a generic “ibm,secvar-backend” compatible, which defines the basic-level compatibility of the secvar implementation. This includes the basic behavior of the API (excluding the data format), and the expected device tree properties contained in this node.

• format

  Usage:

  required

  Value type:

  string

  This property defines the format of data passed in and out of the secvar API. In most cases, this should be the same string as the backend-specific string in compatible.

  The format defined by this string should be documented by the corresponding backend.

• 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:

  <u64>

  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:

  <u64>

  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:

  <u64>

  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

/ibm,opal/secvar {
        compatible = "ibm,secvar-backend" "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.