diff mbox series

[16/16] tools: Add man pages for fdt_sign and fdt_check_sign

Message ID 20211112192817.199075-17-sjg@chromium.org
State Deferred
Delegated to: Tom Rini
Headers show
Series tools: Add support for signing devicetree blobs | expand

Commit Message

Simon Glass Nov. 12, 2021, 7:28 p.m. UTC 
Add some documentation for these tools, along with a MAINTAINER entry.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 MAINTAINERS          |   7 +++
 doc/fdt_check_sign.1 |  74 +++++++++++++++++++++++++++++
 doc/fdt_sign.1       | 111 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 192 insertions(+)
 create mode 100644 doc/fdt_check_sign.1
 create mode 100644 doc/fdt_sign.1
diff mbox series

Patch

diff --git a/MAINTAINERS b/MAINTAINERS
index 00ff572d4d2..9f476d03eb0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -780,6 +780,13 @@  F:	cmd/fdt.c
 F:	common/fdt_support.c
 F:	scripts/dtc-version.sh
 
+FDT SIGNING
+M:	Simon Glass <sjg@chromium.org>
+S:	Maintained
+F:	doc/fdt_*sign.1
+F:	tools/fdt_check_sign.c
+F:	tools/fdt_sign.c
+
 FREEBSD
 M:	Rafal Jaworowski <raj@semihalf.com>
 S:	Maintained
diff --git a/doc/fdt_check_sign.1 b/doc/fdt_check_sign.1
new file mode 100644
index 00000000000..ca4d338a92b
--- /dev/null
+++ b/doc/fdt_check_sign.1
@@ -0,0 +1,74 @@ 
+.TH FDT_CHECK_SIGN 1 "2021-11-11"
+
+.SH NAME
+fdt_check_sign \- Check the signature in a flat device tree (FDT) file
+.SH SYNOPSIS
+.B fdt_check_sign
+.RB [\fIoptions\fP] " \-f [" "device tree binary file" "] " \-K " [" "key file" "]"
+
+.SH "DESCRIPTION"
+The
+.B fdt_check_sign
+command is used to check the signatures in a device tree binary file (.dtb
+file) to ensure it has not been modified since it was signed.
+
+Permitted modifications are to the
+.B /chosen
+node and
+.B /signature
+node/subnodes only.
+
+.SH "OPTIONS"
+
+.TP
+.BI "\-f [" "device tree binary file" "]"
+Selects the .dtb file to check.
+
+.TP
+.BI "\-k [" "key directory" "]"
+Selects the device tree binary file containing the public key to check against.
+
+.SH EXAMPLES
+
+.P
+Generate a key pair with openssl:
+
+.nf
+   $ openssl genpkey -algorithm RSA -out name.key \\
+                 -pkeyopt rsa_keygen_bits:2048 \\
+                 -pkeyopt rsa_keygen_pubexp:65537
+   $ openssl req -batch -new -x509 -key name.key -out name.crt
+.fi
+
+.P
+Create a .dtb file to accept the public key, called pubkey.dtb in this example.
+
+   # echo "/dts-v1/; /{};" | dtc - -o pubkey.dtb
+
+Sign a device tree binary:
+
+.nf
+   $ fdt_sign -f input.dtb -G name.key -K pubkey.dtb -k . -r
+   Signature written to 'input.dtb', node '/signature/name'
+   Public key written to 'pubkey.dtb', node '/signature/key-name
+.fi
+
+.P
+Check the signatures:
+
+.nf
+   $ fdt_check_sign -f input.dtb -k pubkey.dtb
+   name+
+   Verify OK
+   Signature check OK
+.fi
+
+.SH SEE ALSO
+
+fdt_sign
+
+.SH HOMEPAGE
+http://www.denx.de/wiki/U-Boot/WebHome
+.PP
+.SH AUTHOR
+This manual page was written by Simon Glass <sjg@chromium.org>.
diff --git a/doc/fdt_sign.1 b/doc/fdt_sign.1
new file mode 100644
index 00000000000..39f8bdc2a40
--- /dev/null
+++ b/doc/fdt_sign.1
@@ -0,0 +1,111 @@ 
+.TH FDT_SIGN 1 "2021-11-11"
+
+.SH NAME
+fdt_sign \- Sign a flat device tree (FDT) file
+.SH SYNOPSIS
+.B fdt_sign
+.RB [\fIoptions\fP] " \-f [" "device tree binary file" "] " \-G " [" "key file" "]"
+
+.SH "DESCRIPTION"
+The
+.B fdt_sign
+command is used to sign device tree binary files (.dtb files) so that they be
+protected against unwanted modification.
+
+.B fdt_sign
+adds a /signature node to the FDT, if not already present, then adds a node with
+the signature itself, in a simplified format. It uses a private key to generate
+the signature.
+
+.B fdt_check_sign
+can then be used to verify the signature against a public key.
+
+The /chosen node is ignored when signing. A /signature node is added containing
+the signature.
+
+.SH "OPTIONS"
+
+.TP
+.BI "\-f [" "device tree binary file" "]"
+Selects the .dtb file to sign.
+
+.TP
+.BI "\-G [" "key file" "]"
+Selects the key file to sign with. This should be a .key file containing an
+RSA private key.
+
+.TP
+.BI "\-k [" "key directory" "]"
+Selects the directory containing the key file.
+
+.TP
+.BI "\-K [" "key .dtb file" "]"
+Selects the device tree binary file to write the public key into. This is
+updated with a /signature subnode containing the public key the can be used to
+verify the signed device tree.
+
+.TP
+.BI "\-o [" "output file" "]"
+Selects the output file to write to. If omitted, the device tree binary file is
+updated in-place and only the
+.B -f
+parameter is used.
+
+.TP
+.BI "\-q
+Selects quiet mode which supresses non-error output.
+
+.TP
+.BI "\-r
+Marks the key as 'required', meaning that it must be used to check a signature
+in the device tree, when fdt_check_sign is used.
+
+.TP
+.BI "\-S
+Selects the key name to sign with. This is optional and defaults to the base
+name of the key file.
+
+.SH EXAMPLES
+
+.P
+Generate a key pair with openssl:
+
+.nf
+   $ openssl genpkey -algorithm RSA -out name.key \\
+                 -pkeyopt rsa_keygen_bits:2048 \\
+                 -pkeyopt rsa_keygen_pubexp:65537
+   $ openssl req -batch -new -x509 -key name.key -out name.crt
+.fi
+
+.P
+Create a .dtb file to accept the public key, called pubkey.dtb in this example.
+
+   # echo "/dts-v1/; /{};" | dtc - -o pubkey.dtb
+
+Sign a device tree binary:
+
+.nf
+   $ fdt_sign -f input.dtb -G name.key -K pubkey.dtb -k . -r
+   Signature written to 'input.dtb', node '/signature/name'
+   Public key written to 'pubkey.dtb', node '/signature/key-name
+.fi
+
+.P
+Check the signatures:
+
+.nf
+   $ fdt_check_sign -f input.dtb -k pubkey.dtb
+   name+
+   Verify OK
+   Signature check OK
+.fi
+
+.SH SEE ALSO
+
+fdt_check_sign
+
+.SH HOMEPAGE
+http://www.denx.de/wiki/U-Boot/WebHome
+.PP
+.SH AUTHOR
+This manual page was written by Simon Glass <sjg@chromium.org>.