aboutsummaryrefslogtreecommitdiff
path: root/Documentation/driver-api/firmware/signing.rst
blob: 2dbee104700e152c4c1db0e852362d3dc86c84ac (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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