Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758223AbcJQQ7F (ORCPT ); Mon, 17 Oct 2016 12:59:05 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:44082 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757804AbcJQQ4S (ORCPT ); Mon, 17 Oct 2016 12:56:18 -0400 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , LKML , David Howells , David Woodhouse , Jonathan Corbet , Mauro Carvalho Chehab , keyrings@vger.kernel.org Subject: [PATCH 21/32] Documentation/module-signing.txt: convert to ReST markup Date: Mon, 17 Oct 2016 14:55:58 -0200 Message-Id: <85975af0bab9f61d1fb734b5bae80cc21e37cb3e.1476717925.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: References: MIME-Version: 1.0 In-Reply-To: References: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 13218 Lines: 331 - Fix identatio for the document title; - remove its index; - create a table for hash algorithm to be used; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - Fix case on section titles; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/module-signing.txt | 117 ++++++++++++++++------------------ Documentation/user/index.rst | 1 + Documentation/user/module-signing.rst | 1 + 3 files changed, 57 insertions(+), 62 deletions(-) create mode 120000 Documentation/user/module-signing.rst diff --git a/Documentation/module-signing.txt b/Documentation/module-signing.txt index f0e3361db20c..81e76d8c7b00 100644 --- a/Documentation/module-signing.txt +++ b/Documentation/module-signing.txt @@ -1,22 +1,8 @@ - ============================== - KERNEL MODULE SIGNING FACILITY - ============================== - -CONTENTS - - - Overview. - - Configuring module signing. - - Generating signing keys. - - Public keys in the kernel. - - Manually signing modules. - - Signed modules and stripping. - - Loading signed modules. - - Non-valid signatures and unsigned modules. - - Administering/protecting the private key. - +Kernel module signing facility +------------------------------ ======== -OVERVIEW +Overview ======== The kernel module signing facility cryptographically signs modules during @@ -36,17 +22,19 @@ SHA-512 (the algorithm is selected by data in the signature). ========================== -CONFIGURING MODULE SIGNING +Configuring module signing ========================== -The module signing facility is enabled by going to the "Enable Loadable Module -Support" section of the kernel configuration and turning on +The module signing facility is enabled by going to the +:menuselection:`Enable Loadable Module Support` section of +the kernel configuration and turning on:: CONFIG_MODULE_SIG "Module signature verification" This has a number of options available: - (1) "Require modules to be validly signed" (CONFIG_MODULE_SIG_FORCE) + (1) :menuselection:`Require modules to be validly signed` + (``CONFIG_MODULE_SIG_FORCE``) This specifies how the kernel should deal with a module that has a signature for which the key is not known or a module that is unsigned. @@ -64,35 +52,39 @@ This has a number of options available: cannot be parsed, it will be rejected out of hand. - (2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL) + (2) :menuselection:`Automatically sign all modules` + (``CONFIG_MODULE_SIG_ALL``) If this is on then modules will be automatically signed during the modules_install phase of a build. If this is off, then the modules must - be signed manually using: + be signed manually using:: scripts/sign-file - (3) "Which hash algorithm should modules be signed with?" + (3) :menuselection:`Which hash algorithm should modules be signed with?` This presents a choice of which hash algorithm the installation phase will sign the modules with: - CONFIG_MODULE_SIG_SHA1 "Sign modules with SHA-1" - CONFIG_MODULE_SIG_SHA224 "Sign modules with SHA-224" - CONFIG_MODULE_SIG_SHA256 "Sign modules with SHA-256" - CONFIG_MODULE_SIG_SHA384 "Sign modules with SHA-384" - CONFIG_MODULE_SIG_SHA512 "Sign modules with SHA-512" + =============================== ========================================== + ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` + ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` + ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` + ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` + ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` + =============================== ========================================== The algorithm selected here will also be built into the kernel (rather than being a module) so that modules signed with that algorithm can have their signatures checked without causing a dependency loop. - (4) "File name or PKCS#11 URI of module signing key" (CONFIG_MODULE_SIG_KEY) + (4) :menuselection:`File name or PKCS#11 URI of module signing key` + (``CONFIG_MODULE_SIG_KEY``) Setting this option to something other than its default of - "certs/signing_key.pem" will disable the autogeneration of signing keys + ``certs/signing_key.pem`` will disable the autogeneration of signing keys and allow the kernel modules to be signed with a key of your choosing. The string provided should identify a file containing both a private key and its corresponding X.509 certificate in PEM form, or — on systems where @@ -102,10 +94,11 @@ This has a number of options available: If the PEM file containing the private key is encrypted, or if the PKCS#11 token requries a PIN, this can be provided at build time by - means of the KBUILD_SIGN_PIN variable. + means of the ``KBUILD_SIGN_PIN`` variable. - (5) "Additional X.509 keys for default system keyring" (CONFIG_SYSTEM_TRUSTED_KEYS) + (5) :menuselection:`Additional X.509 keys for default system keyring` + (``CONFIG_SYSTEM_TRUSTED_KEYS``) This option can be set to the filename of a PEM-encoded file containing additional certificates which will be included in the system keyring by @@ -116,7 +109,7 @@ packages to the kernel build processes for the tool that does the signing. ======================= -GENERATING SIGNING KEYS +Generating signing keys ======================= Cryptographic keypairs are required to generate and check signatures. A @@ -126,14 +119,14 @@ it can be deleted or stored securely. The public key gets built into the 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 +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: +openssl if one does not exist in the file:: certs/signing_key.pem during the building of vmlinux (the public part of the key needs to be built -into vmlinux) using parameters in the: +into vmlinux) using parameters in the:: certs/x509.genkey @@ -142,14 +135,14 @@ 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: +should be altered from the default:: [ req_distinguished_name ] #O = Unspecified company CN = Build time autogenerated kernel key #emailAddress = unspecified.user@unspecified.company -The generated RSA key size can also be set with: +The generated RSA key size can also be set with:: [ req ] default_bits = 4096 @@ -158,23 +151,23 @@ The generated RSA key size can also be set with: 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: +generate the public/private key files:: 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 +in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will be used instead of an autogenerated keypair. ========================= -PUBLIC KEYS IN THE KERNEL +Public keys in the kernel ========================= The kernel contains a ring of public keys that can be viewed by root. They're -in a keyring called ".system_keyring" that can be seen by: +in a keyring called ".system_keyring" that can be seen by:: [root@deneb ~]# cat /proc/keys ... @@ -184,27 +177,27 @@ in a keyring called ".system_keyring" that can be seen by: Beyond the public key generated specifically for module signing, additional trusted certificates can be provided in a PEM-encoded file referenced by the -CONFIG_SYSTEM_TRUSTED_KEYS configuration option. +``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. Further, the architecture code may take public keys from a hardware store and add those in also (e.g. from the UEFI key database). -Finally, it is possible to add additional public keys by doing: +Finally, it is possible to add additional public keys by doing:: keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] -e.g.: +e.g.:: keyctl padd asymmetric "" 0x223c7853