[PATCH v2 12/14] doc: Add signing to the FIT spec
Simon Glass
sjg at chromium.org
Fri Jun 23 14:22:12 CEST 2023
Move this properties into the main spec.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
(no changes since v1)
doc/usage/fit/signature.rst | 64 ------------
doc/usage/fit/source_file_format.rst | 147 ++++++++++++++++++++++++++-
2 files changed, 146 insertions(+), 65 deletions(-)
diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst
index 7d8292ece867..0804bffd1edc 100644
--- a/doc/usage/fit/signature.rst
+++ b/doc/usage/fit/signature.rst
@@ -82,70 +82,6 @@ If you like you can look at the public key also::
$ openssl rsa -in keys/dev.key -pubout
-Device Tree Bindings
---------------------
-The following properties are required in the FIT's signature node(s) to
-allow the signer to operate. These should be added to the .its file.
-Signature nodes sit at the same level as hash nodes and are called
-signature-1, signature-2, etc.
-
-algo
- Algorithm name (e.g. "sha1,rsa2048")
-
-key-name-hint
- Name of key to use for signing. The keys will normally be in
- a single directory (parameter -k to mkimage). For a given key <name>, its
- private key is stored in <name>.key and the certificate is stored in
- <name>.crt.
-
-When the image is signed, the following properties are added (mandatory):
-
-value
- The signature data (e.g. 256 bytes for 2048-bit RSA)
-
-When the image is signed, the following properties are optional:
-
-timestamp
- Time when image was signed (standard Unix time_t format)
-
-signer-name
- Name of the signer (e.g. "mkimage")
-
-signer-version
- Version string of the signer (e.g. "2013.01")
-
-comment
- Additional information about the signer or image
-
-padding
- The padding algorithm, it may be pkcs-1.5 or pss,
- if no value is provided we assume pkcs-1.5
-
-For config bindings (see Signed Configurations below), the following
-additional properties are optional:
-
-sign-images
- A list of images to sign, each being a property of the conf
- node that contains then. The default is "kernel,fdt" which means that these
- two images will be looked up in the config and signed if present.
-
-For config bindings, these properties are added by the signer:
-
-hashed-nodes
- A list of nodes which were hashed by the signer. Each is
- a string - the full path to node. A typical value might be::
-
- hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
- "/images/kernel/hash-1", "/images/fdt-1",
- "/images/fdt-1/hash-1";
-
-hashed-strings
- The start and size of the string region of the FIT that was hashed
-
-Example: See :doc:`sign-images` for an example image tree source file and
-sign-configs.its for config signing.
-
-
Public Key Storage
------------------
In order to verify an image that has been signed with a public key we need to
diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index f1cc1bc4931c..1f6c33834b6a 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -385,6 +385,10 @@ hash-1
Each hash sub-node represents separate hash or checksum
calculated for node's data according to specified algorithm.
+signature-1
+ Each signature sub-node represents separate signature
+ calculated for node's data according to specified algorithm.
+
Hash nodes
----------
@@ -418,6 +422,91 @@ algo
value
Actual checksum or hash value.
+Image-signature nodes
+---------------------
+
+::
+
+ o signature-1
+ |- algo = "algorithm name"
+ |- key-name-hint = "key name"
+ |- value = [hash or checksum value]
+
+
+Mandatory properties
+~~~~~~~~~~~~~~~~~~~~
+
+_`FIT Algorithm`:
+
+algo
+ Algorithm name. Supported algoriths and their value sizes are shown below.
+ Note that the hash is specified separately from the signing algorithm, so
+ it is possible to mix and match any SHA algorithm with any signing
+ algorithm. The size of the signature relates to the signing algorithm, not
+ the hash, since it is the hash that is signed.
+
+ ==================== ============ =========================================
+ Sub-image type Size (bytes) Meaning
+ ==================== ============ =========================================
+ sha1,rsa2048 256 SHA1 hash signed with 2048-bit
+ Rivest–Shamir–Adleman algorithm
+ sha1,rsa3072 384 SHA1 hash signed with 2048-bit RSA
+ sha1,rsa4096 512 SHA1 hash signed with 2048-bit RSA
+ sha1,ecdsa256 32 SHA1 hash signed with 256-bit Elliptic
+ Curve Digital Signature Algorithm
+ sha256,...
+ sha384,...
+ sha512,...
+ ==================== ============ =========================================
+
+key-name-hint
+ Name of key to use for signing. The keys will normally be in
+ a single directory (parameter -k to mkimage). For a given key <name>, its
+ private key is stored in <name>.key and the certificate is stored in
+ <name>.crt.
+
+sign-images
+ A list of images to sign, each being a property of the conf
+ node that contains then. The default is "kernel,fdt" which means that these
+ two images will be looked up in the config and signed if present. This is
+ used by mkimage to determine which images to sign.
+
+The following properies are added as part of signing, and are mandatory:
+
+value
+ Actual signature value. This is added by mkimage.
+
+hashed-nodes
+ A list of nodes which were hashed by the signer. Each is
+ a string - the full path to node. A typical value might be::
+
+ hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
+ "/images/kernel/hash-1", "/images/fdt-1",
+ "/images/fdt-1/hash-1";
+
+hashed-strings
+ The start and size of the string region of the FIT that was hashed. The
+ start is normally 0, indicating the first byte of the string table. The size
+ indicates the number of bytes hashed as part of signing.
+
+The following properies are added as part of signing, and are optional:
+
+timestamp
+ Time when image was signed (standard Unix time_t format)
+
+signer-name
+ Name of the signer (e.g. "mkimage")
+
+signer-version
+ Version string of the signer (e.g. "2013.01")
+
+comment
+ Additional information about the signer or image
+
+padding
+ The padding algorithm, it may be pkcs-1.5 or pss,
+ if no value is provided we assume pkcs-1.5
+
'/configurations' node
----------------------
@@ -447,6 +536,13 @@ Mandatory nodes
configuration-sub-node-unit-name
At least one of the configuration sub-nodes is required.
+Optional nodes
+~~~~~~~~~~~~~~
+
+signature-1
+ Each signature sub-node represents separate signature
+ calculated for the configuration according to specified algorithm.
+
Configuration nodes
-------------------
@@ -460,7 +556,7 @@ Each configuration has the following structure::
|- loadables = "loadables sub-node unit-name"
|- script = "
|- compatible = "vendor,board-style device tree compatible string"
-
+ o signature-1 {...}
Mandatory properties
~~~~~~~~~~~~~~~~~~~~
@@ -512,6 +608,55 @@ Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
not* be specified in a configuration node.
+Configuration-signature nodes
+-----------------------------
+
+::
+
+ o signature-1
+ |- algo = "algorithm name"
+ |- key-name-hint = "key name"
+ |- sign-images = "path1", "path2";
+ |- value = [hash or checksum value]
+ |- hashed-strings = <0 len>
+
+
+Mandatory properties
+~~~~~~~~~~~~~~~~~~~~
+
+algo
+ See `FIT Algorithm`_.
+
+key-name-hint
+ Name of key to use for signing. The keys will normally be in
+ a single directory (parameter -k to mkimage). For a given key <name>, its
+ private key is stored in <name>.key and the certificate is stored in
+ <name>.crt.
+
+The following properies are added as part of signing, and are mandatory:
+
+value
+ Actual signature value. This is added by mkimage.
+
+The following properies are added as part of signing, and are optional:
+
+timestamp
+ Time when image was signed (standard Unix time_t format)
+
+signer-name
+ Name of the signer (e.g. "mkimage")
+
+signer-version
+ Version string of the signer (e.g. "2013.01")
+
+comment
+ Additional information about the signer or image
+
+padding
+ The padding algorithm, it may be pkcs-1.5 or pss,
+ if no value is provided we assume pkcs-1.5
+
+
Examples
--------
--
2.41.0.162.gfafddb0af9-goog
More information about the U-Boot
mailing list