.. _device-tree/ibm,opal/secvar:

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

.. code-block:: dts

	/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.