[PATCH 8/8] doc: rollback: anti-rollback verification
seanedmond at linux.microsoft.com
seanedmond at linux.microsoft.com
Tue Sep 12 11:47:31 CEST 2023
From: Sean Edmond <seanedmond at microsoft.com>
Add documentation for anti-rollback verification, optional properties in
FIT image, and UCLASS_ROLLBACK device.
Signed-off-by: Sean Edmond <seanedmond at microsoft.com>
---
doc/develop/driver-model/index.rst | 1 +
doc/develop/driver-model/rollback-info.rst | 42 +++++++++++++++++
doc/usage/fit/signature.rst | 53 +++++++++++++++++++---
doc/usage/fit/source_file_format.rst | 21 ++++++++-
4 files changed, 108 insertions(+), 9 deletions(-)
create mode 100644 doc/develop/driver-model/rollback-info.rst
diff --git a/doc/develop/driver-model/index.rst b/doc/develop/driver-model/index.rst
index 8e12bbd936..bb2d2e8a5d 100644
--- a/doc/develop/driver-model/index.rst
+++ b/doc/develop/driver-model/index.rst
@@ -25,6 +25,7 @@ subsystems
pci-info
pmic-framework
remoteproc-framework
+ rollback-info
serial-howto
soc-framework
spi-howto
diff --git a/doc/develop/driver-model/rollback-info.rst b/doc/develop/driver-model/rollback-info.rst
new file mode 100644
index 0000000000..06ba4584a9
--- /dev/null
+++ b/doc/develop/driver-model/rollback-info.rst
@@ -0,0 +1,42 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Rollback Driver Guide
+=====================
+
+Rollback protection is required when there is a need to retire
+previous versions of FIT images due to security flaws in them.
+See :doc:`../../usage/fit/signature` for details on rollback protection.
+
+The rollback driver is intended to provide tamper-evident storage using
+a UCLASS_ROLLBACK device. It exposes the following APIs which are
+used in the FIT verification process (if FIT_ROLLBACK_CHECK is set):
+- rollback_idx_get()
+- rollback_idx_set()
+
+A TPM based rollback device has been provided as an example. Users could
+create their own UCLASS_ROLLBACK device to access proprietary secure storage.
+
+TPM 2.0 based rollback devices
+------------
+
+A TPM-based rollback device has been provided as a reference. It can be
+enabled with:
+- DM_ROLLBACK
+- ROLLBACK_TPM
+
+The tpm based rollback device should be added as a child node of the TPM in
+the u-boot device tree. You should provide the property "rollback-nv-index"
+to set the TPM's NV index (if no "rollback-nv-index" is provided, an NV index
+of 0 is assumed). For example:
+
+ tpm2 {
+ compatible = "sandbox,tpm2";
+
+ rollback at 1 {
+ compatible = "tpm,rollback";
+ rollback-nv-index = <0x1001007>;
+ };
+ };
+
+Note, the ROLLBACK_TPM device does not set any policy. Consumers of this
+driver should add a policy to make it more secure.
\ No newline at end of file
diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst
index 0804bffd1e..30dd529c29 100644
--- a/doc/usage/fit/signature.rst
+++ b/doc/usage/fit/signature.rst
@@ -674,14 +674,53 @@ Sign the fitImage with the hardware key::
"model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \
-K u-boot.dtb -N pkcs11 -r fitImage
+Roll-back Protection
+-----------------------------------------
-Future Work
------------
-
-- Roll-back protection using a TPM is done using the tpm command. This can
- be scripted, but we might consider a default way of doing this, built into
- bootm.
-
+Rollback protection is required when there is a need to retire
+previous versions of FIT images due to security flaws in them.
+
+This feature is realized by adding a rollback index as a property
+in the FIT image. Every time a security flaw is discovered, the
+rollback index is incremented. For example:
+
++-------------+----------------+
+| FIT version | Rollback index |
++=============+================+
+| 1.0 | 0 |
++-------------+----------------+
+| 1.1 | 0 |
++-------------+----------------+
+| 2.0 | 0 |
++-------------+----------------+
+| Security issue found! |
++-------------+----------------+
+| 1.2 | 1 |
++-------------+----------------+
+| 2.1 | 1 |
++-------------+----------------+
+
+Each sub-image node inside /images node has an optional rollback rollback_index
+("rollback"). This version number is part of signed data and is incremented as
+security flaws are discovered and fixed. If no "rollback" property is present
+in the FIT image, a rollback index of 0 is assumed.
+
+U-Boot stores the last seen "rollback" for a given image type in platform
+specific tamper-evident storage (using a UCLASS_ROLLBACK device).
+See :doc:`../../develop/driver-model/rollback-info` for more information on
+rollback devices.
+
+As part of signature verification, U-Boot enforces rollback
+protection if enabled (with FIT_ROLLBACK_CHECK). The rollback index stored in secure
+storage is validated with "rollback" in the sub-image node. If the counter
+in the FIT image is lower than the counter in platform secure storage, image
+validation has failed. If both counters match or the image counter is
+higher than that in the platform secure storage, the image validation is
+successful. If the rollback index has increased, U-Boot stores the new
+value in secure storage.
+
+A grace version can be enabled with FIT_ROLLBACK_CHECK_GRACE, which will accept
+a FIT image with an anti-rollback version one less than number in secure storage.
Possible Future Work
--------------------
diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index b2b1e42bd7..149447b856 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -389,6 +389,16 @@ signature-1
Each signature sub-node represents separate signature
calculated for node's data according to specified algorithm.
+Optional properties
+~~~~~~~~~~~~~~~~~~~~
+
+rollback
+ The rollback index (used for anti rollback protection) specified
+ as a 64-bit value. For example a rollback index of 1 is sepcified as:
+
+ rollback = <0 1>
+
+ If no "rollback" property is present, a rollback index of 0 is assumed.
Hash nodes
----------
@@ -507,7 +517,6 @@ padding
The padding algorithm, it may be pkcs-1.5 or pss,
if no value is provided we assume pkcs-1.5
-
'/configurations' node
----------------------
@@ -524,12 +533,20 @@ The 'configurations' node has the following structure::
...
-Optional property
+Optional properties
~~~~~~~~~~~~~~~~~
default
Selects one of the configuration sub-nodes as a default configuration.
+rollback
+ The rollback index (used for anti rollback protection) specified
+ as a 64-bit value. For example a rollback index of 1 is sepcified as:
+
+ rollback = <0 1>
+
+ If no "rollback" property is present, a rollback index of 0 is assumed.
+
Mandatory nodes
~~~~~~~~~~~~~~~
--
2.40.0
More information about the U-Boot
mailing list