path: root/Documentation/driver-api/firmware/signing.rst
diff options
Diffstat (limited to 'Documentation/driver-api/firmware/signing.rst')
1 files changed, 81 insertions, 0 deletions
diff --git a/Documentation/driver-api/firmware/signing.rst b/Documentation/driver-api/firmware/signing.rst
new file mode 100644
index 000000000000..2dbee104700e
--- /dev/null
+++ b/Documentation/driver-api/firmware/signing.rst
@@ -0,0 +1,81 @@
+Kernel firmware signing facility
+The kernel firmware signing facility enables to cryptographically sign
+firmware files on a system using the same keys used for module signing.
+Firmware files's signatures consist of PKCS#7 messages of the respective
+firmware file. A firmware file named foo.bin, would have its respective
+signature on the filesystem as foo.bin.p7s. When firmware signature
+checking is enabled (FIRMWARE_SIG) and when one of the above APIs is used
+against foo.bin, the file foo.bin.p7s will also be looked for. If
+FIRMWARE_SIG_FORCE is enabled the foo.bin file will only be allowed to
+be returned to callers of the above APIs if and only if the foo.bin.p7s
+file is confirmed to be a valid signature of the foo.bin file. If
+FIRMWARE_SIG_FORCE is not enabled and only FIRMWARE_SIG is enabled the
+kernel will be permissive and enabled unsigned firmware files, or firmware
+files with incorrect signatures. If FIRMWARE_SIG is not enabled the
+signature file is ignored completely.
+Firmware signing increases security by making it harder to load a malicious
+firmware into the kernel. The firmware signature checking is done by the
+kernel so that it is not necessary to have trusted userspace bits.
+Configuring firmware signing
+The firmware signing facility is enabled by going to the section::
+ -> Device Drivers
+ -> Generic Driver Options
+ -> Userspace firmware loading support (FW_LOADER [=y])
+ -> Firmware signature verification (FIRMWARE_SIG [=y])
+If you want to not allow unsigned firmware to be loaded you should
+ -> Require all firmware to be validly signed (FIRMWARE_SIG_FORCE [=y])
+under the same menu.
+Using signing keys
+The same key types used for module signing can be used for firmware
+signing. For details on that refer to `Kernel module signing`_.
+.. _`Kernel module signing`: /admin-guide/module-signing.rst
+You will need:
+ A) A DER-encoded X.509 certificate containing the public key.
+ B) A DER-encoded PKCS#7 message containing the signatures, these are
+ the .p7s files.
+ C) A binary blob that is the detached data for the PKCS#7 message, this
+ is the firmware files
+A) is must be made available to the kernel. One way to do this is to provide a
+DER-encoded in the source directory as <name>.x509 when you build the kernel.
+Signing firmware files
+To generate a DER-encoded PKCS#7 signature message for each firmware file
+you can use the following commands:
+ scripts/sign-file -f sha256 \
+ or
+ openssl smime -sign -in $FIRMWARE_BLOB_NAME \
+ -outform DER \
+ -signer $X509_CERT_FILE_IN_PEM_FORM \
+ -nocerts -md $DIGEST_ALGORITHM -binary > \