@@ -89,6 +89,32 @@ This has a number of options available:
8989 their signatures checked without causing a dependency loop.
9090
9191
92+ (4) "File name or PKCS#11 URI of module signing key" (CONFIG_MODULE_SIG_KEY)
93+
94+ Setting this option to something other than its default of
95+ "signing_key.pem" will disable the autogeneration of signing keys and
96+ allow the kernel modules to be signed with a key of your choosing.
97+ The string provided should identify a file containing both a private
98+ key and its corresponding X.509 certificate in PEM form, or — on
99+ systems where the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI
100+ as defined by RFC7512. In the latter case, the PKCS#11 URI should
101+ reference both a certificate and a private key.
102+
103+ If the PEM file containing the private key is encrypted, or if the
104+ PKCS#11 token requries a PIN, this can be provided at build time by
105+ means of the KBUILD_SIGN_PIN variable.
106+
107+
108+ (5) "Additional X.509 keys for default system keyring" (CONFIG_SYSTEM_TRUSTED_KEYS)
109+
110+ This option can be set to the filename of a PEM-encoded file containing
111+ additional certificates which will be included in the system keyring by
112+ default.
113+
114+ Note that enabling module signing adds a dependency on the OpenSSL devel
115+ packages to the kernel build processes for the tool that does the signing.
116+
117+
92118=======================
93119GENERATING SIGNING KEYS
94120=======================
@@ -100,11 +126,11 @@ it can be deleted or stored securely. The public key gets built into the
100126kernel so that it can be used to check the signatures as the modules are
101127loaded.
102128
103- Under normal conditions, the kernel build will automatically generate a new
104- keypair using openssl if one does not exist in the files:
129+ Under normal conditions, when CONFIG_MODULE_SIG_KEY is unchanged from its
130+ default, the kernel build will automatically generate a new keypair using
131+ openssl if one does not exist in the file:
105132
106- signing_key.priv
107- signing_key.x509
133+ signing_key.pem
108134
109135during the building of vmlinux (the public part of the key needs to be built
110136into vmlinux) using parameters in the:
@@ -135,8 +161,12 @@ kernel sources tree and the openssl command. The following is an example to
135161generate the public/private key files:
136162
137163 openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \
138- -config x509.genkey -outform DER -out signing_key.x509 \
139- -keyout signing_key.priv
164+ -config x509.genkey -outform PEM -out kernel_key.pem \
165+ -keyout kernel_key.pem
166+
167+ The full pathname for the resulting kernel_key.pem file can then be specified
168+ in the CONFIG_MODULE_SIG_KEY option, and the certificate and key therein will
169+ be used instead of an autogenerated keypair.
140170
141171
142172=========================
@@ -152,10 +182,9 @@ in a keyring called ".system_keyring" that can be seen by:
152182 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 []
153183 ...
154184
155- Beyond the public key generated specifically for module signing, any file
156- placed in the kernel source root directory or the kernel build root directory
157- whose name is suffixed with ".x509" will be assumed to be an X.509 public key
158- and will be added to the keyring.
185+ Beyond the public key generated specifically for module signing, additional
186+ trusted certificates can be provided in a PEM-encoded file referenced by the
187+ CONFIG_SYSTEM_TRUSTED_KEYS configuration option.
159188
160189Further, the architecture code may take public keys from a hardware store and
161190add those in also (e.g. from the UEFI key database).
@@ -181,7 +210,7 @@ To manually sign a module, use the scripts/sign-file tool available in
181210the Linux kernel source tree. The script requires 4 arguments:
182211
183212 1. The hash algorithm (e.g., sha256)
184- 2. The private key filename
213+ 2. The private key filename or PKCS#11 URI
185214 3. The public key filename
186215 4. The kernel module to be signed
187216
@@ -194,6 +223,9 @@ The hash algorithm used does not have to match the one configured, but if it
194223doesn't, you should make sure that hash algorithm is either built into the
195224kernel or can be loaded without requiring itself.
196225
226+ If the private key requires a passphrase or PIN, it can be provided in the
227+ $KBUILD_SIGN_PIN environment variable.
228+
197229
198230============================
199231SIGNED MODULES AND STRIPPING
0 commit comments