doc: add documentation for uefi signing

madisongh · Nov 27, 2023 · 1ea5f53 · 1ea5f53
1 parent 37af994
commit 1ea5f53
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 0 deletions.
diff --git a/doc/ueficapsulesign.md b/doc/ueficapsulesign.md
@@ -0,0 +1,41 @@
+# UEFI capsule signing
+
+Supports encapsulating kernel and bup payloads into a signed UEFI capsule.
+
+## Prerequisites
+
+    $ apt-get install liblz4-tool
+    $ pip3 install PyYAML
+
+## Key file storage layout
+
+For UEFI capsule signing, the following files are expected to be present:
+
+    ${DIGSIGSERVER_KEYFILE_URI}/${machine}/ueficapsulesign/trusted_public_cert.pem
+    ${DIGSIGSERVER_KEYFILE_URI}/${machine}/ueficapsulesign/other_public_cert.pem
+    ${DIGSIGSERVER_KEYFILE_URI}/${machine}/ueficapsulesign/signer_private_cert.pem
+
+where `${machine}` is the value of the `machine=` parameter included in the signing request.
+
+See [here](https://github.com/tianocore/tianocore.github.io/wiki/Capsule-Based-System-Firmware-Update-Generate-Keys) for instructions on how to provision these keys.
+
+## REST API endpoint
+
+Request type: `POST`
+
+Endpoint: `/sign/tegra/ueficapsule`
+
+Expected parameters:
+* `machine=<machine-name>` - a name for the device, used to locate the signing keys
+* `soctype=<soctype>` - one of `tegra194`, `tegra234`
+* `bspversion=<l4t-version>` - the L4T BSP version, e.g. `35.4.1`
+* `guid=<guid>` - a unique identifier for the target soc type
+* `artifact=<body>` - the binary to be signed
+
+Response: the signed capsule
+
+Example usage:
+
+    $ curl --silent --fail -X POST -F "machine=jetson-xavier-nx-devkit-emmc" -F "soctype=tegra194" -F "bspversion=35.4.1" -F "guid=be3f5d68-7654-4ed2-838c-2a2faf901a78" -F "artifact=@tegra-minimal-initramfs-jetson-xavier-nx-devkit-emmc.bl_only.bup-payload" --output ./tegra-bl.cap "http://127.0.0.1:9999/sign/tegra/ueficapsule"
+
+    $ curl --silent --fail -X POST -F "machine=jetson-xavier-nx-devkit-emmc" -F "soctype=tegra194" -F "bspversion=35.4.1" -F "guid=be3f5d68-7654-4ed2-838c-2a2faf901a78" -F "artifact=@tegra-minimal-initramfs-jetson-xavier-nx-devkit-emmc.kernel_only.bup-payload" --output ./tegra-kernel.capa "http://127.0.0.1:9999/sign/tegra/ueficapsule"
diff --git a/doc/uefisign.md b/doc/uefisign.md
@@ -0,0 +1,45 @@
+# UEFI signing
+
+Supports signing of the following artifacts that UEFI verifies during boot:
+
+* kernel
+* kernel dtb
+* L4TLauncher (BOOTAA64.efi)
+* extlinux.conf
+* initrd
+
+## Prerequisites
+
+    $ apt-get install sbsigntool
+
+## Key file storage layout
+
+For UEFI signing, the following files are expected to be present:
+
+    ${DIGSIGSERVER_KEYFILE_URI}/${machine}/uefisign/db.key
+    ${DIGSIGSERVER_KEYFILE_URI}/${machine}/uefisign/db.crt
+
+where `${machine}` is the value of the `machine=` parameter included in the signing request.
+
+## REST API endpoint
+
+Request type: `POST`
+
+Endpoint: `/sign/tegra/uefi`
+
+Expected parameters:
+* `machine=<machine-name>` - a name for the device, used to locate the signing keys
+* `signing_type=<sbsign|signature|attach_signature>` - the type of signing to perform
+* `artifact=<body>` - the binary to be signed
+
+Response: the signed binary or signature
+
+Example usage:
+
+    $ curl --silent --fail -X POST -F "machine=jetson-xavier-nx-devkit-emmc" -F "signing_type=sbsign" -F "artifact=@$1" --output $1 "http://127.0.0.1:9999/sign/tegra/uefi"
+
+    $ curl --silent --fail -X POST -F "machine=jetson-xavier-nx-devkit-emmc" -F "signing_type=signature" -F "artifact=@$1" --output $1.sig "http://127.0.0.1:9999/sign/tegra/uefi"
+
+    $ curl --silent --fail -X POST -F "machine=jetson-xavier-nx-devkit-emmc" -F "signing_type=attach_signature" -F "artifact=@$1" --output $1.signed "http://127.0.0.1:9999/sign/tegra/uefi"
+
+where `$1` is one of the UEFI payloads described [here](https://docs.nvidia.com/jetson/archives/r35.4.1/DeveloperGuide/text/SD/Security/SecureBoot.html#generate-signed-uefi-payloads).