[PATCH 8/8] doc: rollback: anti-rollback verification

[seanedmond@linux.microsoft.com]

From: Sean Edmond <seanedmond@microsoft.com>

Add documentation for anti-rollback verification, optional properties in
FIT image, and UCLASS_ROLLBACK device.

Signed-off-by: Sean Edmond <seanedmond@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@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