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