[sw, rom_ext_signer] update the documentation
Signed-off-by: Silvestrs Timofejevs <silvestrst@lowrisc.org>
diff --git a/sw/host/rom_ext_image_tools/signer/README.md b/sw/host/rom_ext_image_tools/signer/README.md
index 8c18fc9..eb2ca32 100644
--- a/sw/host/rom_ext_image_tools/signer/README.md
+++ b/sw/host/rom_ext_image_tools/signer/README.md
@@ -8,9 +8,9 @@
deliver security updates - OpenTitan design provisions the Extension ROM
(ROM_EXT) that lives in the flash memory.
-ROM_EXT consists of a [manifest][rom-ext-manifest] and the image itself. When
+ROM_EXT consists of a [manifest][1] and the image itself. When
the image is generated - the manifest data is "blank". The responsibility of
-ROM_EXT signer is to update the manifest, sign the image and add the
+the ROM_EXT signer is to update the manifest, sign the image and add the
signature to it.
## Tooling
@@ -24,7 +24,12 @@
system) and mature community driven database (crates.io), makes it easy and
cheap (in terms of effort) to find, integrate and use relevant functionality.
-** This makes rust great for host side tooling **
+**This makes rust great for host side tooling**
+
+# Current state
+
+**Please note that this change is work in progress, and can be tracked via:
+https://github.com/lowRISC/opentitan/issues/5232**
# Design
@@ -44,30 +49,41 @@
into Rust structures) using `hjson_serde` and `serde` crates.
Configuration file contains data for all of the fields that need updating in
-the manifest before signing.
+the manifest before signing. Some manifest fields are unfeasible to specify
+in the configuration file - these are binary blobs such as a private key in DER
+format. Instead the file paths to these are specified.
-Please note that signature key modulus and signature key public exponent are
-extracted separately. The configuration file has a link to the private key,
-and public key is extracted from it via `ring` library.
+Please note that some field values are known upfront, however other must be
+obtained at runtime. Fields like (but not limited to) signature public modulus
+and signature key public exponent are extracted separately.
-Generic (u32 or u64) integers are defines as an array. This is done to make
-updating the manifest easier. Complex fields such as "Peripheral Lockdown
-Info" have a separate data structure, and are spliced into the image separately.
+Complex fields such as "Peripheral Lockdown Info" have a separate data
+structure.
## Image manipulation (updating the manifest)
-Reads the binary image of the disk. It uses the parsed configuration to
-update the manifest before signing, and is responsible for generating the signed
-file.
+The manifest fields must be updated prior to signing, and then the signature
+itself has to be written into the respective manifest field.
+
+- Reads the binary image of the disk
+- Reads and parses the configuration of the disk
+- Reads the files specified in the configuration of the disk
+- Updates the manifest fields
+- Signs the updated image
+- Updated the manifest signature field with the generated signature
+- Writes the updated image to disk
## Image signing
-TODO
+Signing is done via mundane cryptographic library:
+https://crates.io/crates/mundane
+
+For signing details such as signing scheme, please see [manifest][1]
+documentation.
## "Receipt" production
-TODO
+TBD
-<!-- Links -->
-[csm-secure-boot]: {{< relref "doc/security/specs/secure_boot" >}}
-[rom-ext-manifest]: {{< relref "sw/device/rom_exts/docs/manifest" >}}
+
+[1]: /sw/device/rom_exts/docs/manifest.md
