linux-kernel - [PATCH] Documentation: module-signing: Mention default

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20230511043852.25803-1-bagasdotme@gmail.com>
Date:   Thu, 11 May 2023 11:38:52 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Linux Keyrings <keyrings@...r.kernel.org>,
        Linux Kernel Build System <linux-kbuild@...r.kernel.org>,
        Linux Documentation <linux-doc@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Cc:     David Howells <dhowells@...hat.com>,
        David Woodhouse <dwmw2@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Masahiro Yamada <masahiroy@...nel.org>,
        Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH] Documentation: module-signing: Mention default_x509.genkey template

Commit f3a2ba44e93e2c ("certs: check-in the default x509 config file")
adds default x509 keypair config file template, but forgets to mention
it in kernel module signing documentation. Update the doc accordingly.

Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 Documentation/admin-guide/module-signing.rst | 41 ++++++++------------
 1 file changed, 17 insertions(+), 24 deletions(-)

diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst
index 7d7c7c8a545ca6..365d60a6245f17 100644
--- a/Documentation/admin-guide/module-signing.rst
+++ b/Documentation/admin-guide/module-signing.rst
@@ -133,46 +133,39 @@ kernel so that it can be used to check the signatures as the modules are
 loaded.
 
 Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its
-default, the kernel build will automatically generate a new keypair using
-openssl if one does not exist in the file::
-
-	certs/signing_key.pem
-
+default, the kernel build will automatically generate a new keypair in
+``certs/signing_key.pem`` using openssl if it doesn't exist,
 during the building of vmlinux (the public part of the key needs to be built
-into vmlinux) using parameters in the::
-
-	certs/x509.genkey
-
+into vmlinux) using parameters in the ``certs/x509.genkey`` configuration
 file (which is also generated if it does not already exist).
 
-It is strongly recommended that you provide your own x509.genkey file.
-
-Most notably, in the x509.genkey file, the req_distinguished_name section
-should be altered from the default::
+If you'd like to provide alternative configuration, copy
+``certs/default_x509.genkey`` to ``certs/x509.genkey`` and edit the copy
+instead. Most likely, you will want to edit the ``req_distinguished_name``
+section, which identifies the resulting keypair. For example::
 
 	[ req_distinguished_name ]
-	#O = Unspecified company
-	CN = Build time autogenerated kernel key
-	#emailAddress = unspecified.user@...pecified.company
+	O = Example company
+	CN = Example kernel build
+	emailAddress = user@...mple.com
 
 The generated RSA key size can also be set with::
 
 	[ req ]
 	default_bits = 4096
 
-
-It is also possible to manually generate the key private/public files using the
-x509.genkey key generation configuration file in the root node of the Linux
-kernel sources tree and the openssl command.  The following is an example to
-generate the public/private key files::
+Optionally, you can also manually generate the keypair so that the same
+keypair can be used in multiple builds. To generate it::
 
 	openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \
 	   -config x509.genkey -outform PEM -out kernel_key.pem \
 	   -keyout kernel_key.pem
 
-The full pathname for the resulting kernel_key.pem file can then be specified
-in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will
-be used instead of an autogenerated keypair.
+See :manpage:`openssl-req(1)` for the explanation.
+
+The full pathname for the resulting ``kernel_key.pem`` file can then be
+specified in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key
+therein will be used instead of an autogenerated keypair.
 
 
 =========================

base-commit: ac9a78681b921877518763ba0e89202254349d1b
-- 
An old man doll... just what I always wanted! - Clara