[PATCH 4/4] firmware: document signature verification for driver data

[AKASHI Takahiro]

add descriptions and usage about firmware signing in driver data APIs.

Signed-off-by: AKASHI Takahiro <takahiro.akashi@xxxxxxxxxx>
Cc: Luis R. Rodriguez <mcgrof@xxxxxxxx>
---
 Documentation/driver-api/firmware/driver_data.rst  |  6 ++
 .../driver-api/firmware/fallback-mechanisms.rst    |  5 +-
 Documentation/driver-api/firmware/signing.rst      | 81 ++++++++++++++++++++++
 3 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/driver-api/firmware/signing.rst

diff --git a/Documentation/driver-api/firmware/driver_data.rst b/Documentation/driver-api/firmware/driver_data.rst
index be7c7ff99151..cdc47144a8b2 100644
--- a/Documentation/driver-api/firmware/driver_data.rst
+++ b/Documentation/driver-api/firmware/driver_data.rst
@@ -94,6 +94,12 @@ in these callbacks it frees it for you by default after callback handlers
 are issued. If you wish to keep the driver data around after your callbacks
 you must specify this through the driver data request parameter data structure.
 
+Signature verification
+======================
+
+  * `data signing`_
+.. _`data signing`: ./signing.rst
+
 Driver data private internal functionality
 ==========================================
 
diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst
index d19354794e67..e557d6630330 100644
--- a/Documentation/driver-api/firmware/fallback-mechanisms.rst
+++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst
@@ -81,11 +81,12 @@ and a file upload firmware into:
 
   * /sys/$DEVPATH/loading
   * /sys/$DEVPATH/data
+  * /sys/$DEVPATH/sig_data
 
 To upload firmware you will echo 1 onto the loading file to indicate
 you are loading firmware. You then cat the firmware into the data file,
-and you notify the kernel the firmware is ready by echo'ing 0 onto
-the loading file.
+optionally its signature file, and you notify the kernel the firmware is
+ready by echo'ing 0 onto the loading file.
 
 The firmware device used to help load firmware using sysfs is only created if
 direct firmware loading fails and if the fallback mechanism is enabled for your
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
+================================
+
+Overview
+========
+
+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
+enable::
+
+        -> 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 \
+		$PRIVATE_KEY_FILE_IN_PEM_FORM \
+		$X509_CERT_FILE_IN_PEM_FORM \
+		$FIRMWARE_BLOB_NAME
+
+  or
+
+	openssl smime -sign -in $FIRMWARE_BLOB_NAME \
+		-outform DER \
+		-inkey $PRIVATE_KEY_FILE_IN_PEM_FORM \
+		-signer $X509_CERT_FILE_IN_PEM_FORM \
+		-nocerts -md $DIGEST_ALGORITHM -binary > \
+		$(FIRMWARE_BLOB_NAME).p7s
-- 
2.11.1