[PATCH] Documentation: rk35xx: add secure boot documentation

[Michael Tretter <m.tretter@pengutronix.de>]

While barebox supports secure boot on rk3588, user documentation how to
sign images and enable secure boot is still lacking.

Add this documentation, now.

While at it, add some documentation for the Rockchip image header, too,
to explain how the signature guarantees the integrity and authenticity
of the included barebox image.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
---
 Documentation/boards/rk35xx.rst | 108 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/Documentation/boards/rk35xx.rst b/Documentation/boards/rk35xx.rst
index fe74e10870eb..0fbc58a46332 100644
--- a/Documentation/boards/rk35xx.rst
+++ b/Documentation/boards/rk35xx.rst
@@ -151,3 +151,111 @@ For base functionality, it probably requires only porting the
 Linux clk and pinctrl drivers as well as the boilerplate needed
 for every SoC. Reach out to the :ref:`mailing list <feedback>`
 if you have unsupported hardware.
+
+Rockchip Secure Boot
+--------------------
+
+Rockchip Secure Boot is a Rockchip feature to ensure the integrity and
+legitimacy of the firmware running on a device. The Bootrom verifies that the
+header of a loaded Rockchip image contains a public key that matches a sha265
+hash that is stored in the OTP fuses of the SoC and a signature that can be
+verified with this public key.
+
+This allows to verify that the image has been signed by the owner of the
+private key that was authorized when secure boot was activated on the board.
+
+The Rockchip header especially contains the public key as a Modulus, Exponent,
+and NP triple, and hashes over each code sector in this image. The signature
+comprises the entire rkimage header except for the signature itself. Thus the
+signature verifies that the hashes over the code sectors are trustworthy and,
+indirectly, the code sectors are trustworthy ::
+
+    0x0 +---------------------------------+      -
+        | Magic                           |      |
+   0x78 +---------------------------------+      |
+        | sector                          |--+   | Signed Area
+        | hash                            +  |   |
+  0x200 +---------------------------------+  |   |
+        | Modulus                         |  |   |
+        | Exponent                        |  |   |
+        | NP                              |  |   |
+  0x600 +---------------------------------+  |   -
+        | Signature                       |  |
+  0x800 +---------------------------------+  |
+        | ...                             |  |
+        +---------------------------------+  |
+        | Barebox Prebootloader (PBL)     |<-+
+        | Piggydata (Main Barebox Binary) |
+        +---------------------------------+
+
+The public key is not stored in the OTP due to size reasons, but instead a
+sha256 hash over the public key as contained in the rkimage is stored in the
+OTP. The Bootrom verifies that the hash in the OTP matches the hash of the
+public key.
+
+Signing Rockchip Images
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Bootrom allows to use RSA-2048 or RSA-4096 keys for verification.
+
+Generate an RSA key pair for image signing and verification::
+
+  $ openssl genrsa -f4 -out <key.pem> 4096
+
+Enable ``CONFIG_ARCH_ROCKCHIP_IMAGE_SIGNED`` and let
+``CONFIG_ARCH_ROCKCHIP_IMAGE_SIGN_KEY`` point to your generated PEM file.
+
+The Rockchip images generated by the barebox build are now signed with the
+configured key.
+
+The ``rk-otp.sh`` script prints the sha256 hash of a key in a PEM file or a key
+embedded into an rkimage. You may verify that the image is actually signed with
+your key by comparing the output of the following two commands::
+
+  $ scripts/rk-otp.sh <key.pem>
+  $ scripts/rk-otp.sh <rkimage>
+
+Secure Boot
+^^^^^^^^^^^
+
+The barebox ``rksecure`` command allows to burn a hash into the OTP and enable
+secure boot at runtime.
+
+Since the secure OTP are only accessible from the secure world, barebox cannot
+directly access the OTP area. In order to write or read the secure OTP from
+barebox, you need an OP-TEE with the rksecure PTA. See the OP-TEE documentation
+how to enable this PTA.
+
+.. note::
+
+   The OP-TEE rksecure PTA is only available in Upstream OP-TEE.
+   Rockchips Downstream OP-TEE blob does not support writing the OTP area and
+   enabling Secure Boot.
+
+Enable the ``rksecure`` command by enabling the following config variables::
+
+  CONFIG_CMD_RKSECURE
+  CONFIG_OPTEE_RKSECURE
+
+The Bootrom also boots signed images if secure boot is not enabled. Thus, you
+may boot the same image used with and without secure boot enabled devices.
+
+You may use the ``rksecure`` command to retrieve the current secure boot status
+and the burned hash from a device::
+
+  barebox$ rksecure -i
+
+To enable secure boot on a device, run the following command. ``<hash>`` is the
+hash returned by the ``rk-otp.sh`` script and ``<bits>`` needs to match the bit
+length of the RSA key that you use for image signing::
+
+  barebox$ rksecure -x <hash> -b <bits> -l
+
+.. warn::
+
+   Once you executed this command on a device, the Bootrom will
+   reject any image that has not been signed with the appropriate RSA key.
+
+You may check the secure boot status again with ``rksecure -i`` and try
+booting an unsigned or corrupted image to verify secure boot is actually
+enabled.

---
base-commit: 019d102038a64e6b6e8f445cbfd2d15e68d0ec3f
change-id: 20260511-rockchip-secure-boot-doc-ac49c14a8e52

Best regards,
-- 
Michael Tretter <m.tretter@pengutronix.de>