[system-administrators-guide] Changing entities
by stephenw
commit 1a4a51331cac15726a7b97b72161253e21d04096
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:52:39 2014 +0100
Changing entities
en-US/Working_with_the_GRUB_2_Boot_Loader.xml | 6 +++---
1 files changed, 3 insertions(+), 3 deletions(-)
---
diff --git a/en-US/Working_with_the_GRUB_2_Boot_Loader.xml b/en-US/Working_with_the_GRUB_2_Boot_Loader.xml
index 1e81667..45fe966 100644
--- a/en-US/Working_with_the_GRUB_2_Boot_Loader.xml
+++ b/en-US/Working_with_the_GRUB_2_Boot_Loader.xml
@@ -845,10 +845,10 @@ For more information on adding kernel options, see <xref linkend="sec-Editing_an
<section id="sec-UEFI_Secure_Boot_Support_in_Fedora">
<title>UEFI Secure Boot Support in Fedora</title>
<para>
- &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; can be installed and run on systems where UEFI Secure Boot is enabled. On UEFI-based systems with the Secure Boot technology enabled, all drivers that are loaded must be signed with a valid certificate, otherwise the system will not accept them. All drivers provided by Red Hat are signed by the UEFI CA certificate.
+ &MAJOROS; includes support for the UEFI Secure Boot feature, which means that &MAJOROS; can be installed and run on systems where UEFI Secure Boot is enabled. On UEFI-based systems with the Secure Boot technology enabled, all drivers that are loaded must be signed with a valid certificate, otherwise the system will not accept them. All drivers provided by Red Hat are signed by the UEFI CA certificate.
</para>
- <para>
- If you want to load externally built drivers — drivers that are not provided on the &PRODUCT; Linux DVD — you must make sure these drivers are signed as well.
+ <para>
+ If you want to load externally built drivers — drivers that are not provided on the &MAJOROS; Linux DVD — you must make sure these drivers are signed as well.
</para>
<para>
<!--Information on signing custom drivers is available in <xref linkend="sect-signing-kernel-modules-for-secure-boot" />.-->
9 years, 5 months
[system-administrators-guide] kernel-abi-whitelists | missing tag
by stephenw
commit 7d65e864933b603239393ad1aefd3350768f2e50
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:45:44 2014 +0100
kernel-abi-whitelists | missing tag
en-US/Manually_Upgrading_the_Kernel.xml | 1 +
1 files changed, 1 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Manually_Upgrading_the_Kernel.xml b/en-US/Manually_Upgrading_the_Kernel.xml
index aacf3a5..766df2c 100644
--- a/en-US/Manually_Upgrading_the_Kernel.xml
+++ b/en-US/Manually_Upgrading_the_Kernel.xml
@@ -161,6 +161,7 @@
<package>perf</package> — This package contains supporting scripts and documentation for the <application>perf</application> tool shipped in each kernel image subpackage.
</para>
</listitem>
+ <listitem>
<para>
<package>kernel-abi-whitelists</package> — Contains information pertaining to the &MAJOROS; kernel ABI, including a lists of kernel symbols that are needed by external Linux kernel modules and a <package>yum</package> plug-in to aid enforcement.
</para>
9 years, 5 months
[system-administrators-guide] Update entities to 21
by stephenw
commit 8af96908d2267e512198a1d2195819fce72e0c18
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Wed Dec 10 16:24:33 2014 +0100
Update entities to 21
en-US/System_Administrators_Guide.ent | 6 +++---
1 files changed, 3 insertions(+), 3 deletions(-)
---
diff --git a/en-US/System_Administrators_Guide.ent b/en-US/System_Administrators_Guide.ent
index 9fa54e9..656da29 100644
--- a/en-US/System_Administrators_Guide.ent
+++ b/en-US/System_Administrators_Guide.ent
@@ -7,8 +7,8 @@
<!-- Additional Entities: -->
<!ENTITY MAJOROS "Fedora">
-<!ENTITY MAJOROSVER "Fedora 20">
+<!ENTITY MAJOROSVER "Fedora 21">
<!ENTITY OSORG "The Fedora Project">
-<!ENTITY PKGOS "fc20">
-<!ENTITY PRODVER "20">
+<!ENTITY PKGOS "fc21">
+<!ENTITY PRODVER "21">
<!ENTITY BZURL "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component...;'>http://bugzilla.redhat.com/</ulink>">
9 years, 5 months
[system-administrators-guide] directories should have a trailing slash
by stephenw
commit e230abf4466990613d70ff85754642ac2581f743
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:32:53 2014 +0100
directories should have a trailing slash
en-US/Manually_Upgrading_the_Kernel.xml | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
---
diff --git a/en-US/Manually_Upgrading_the_Kernel.xml b/en-US/Manually_Upgrading_the_Kernel.xml
index 295ba78..aacf3a5 100644
--- a/en-US/Manually_Upgrading_the_Kernel.xml
+++ b/en-US/Manually_Upgrading_the_Kernel.xml
@@ -491,7 +491,7 @@ Version: dracut-037-11.git20140402.fc20
<para>
On IBM eServer System i machines, the initial RAM disk and kernel files are combined into a single file, which is created with the <command>addRamDisk</command> command. This step is performed automatically if the kernel and its associated packages are installed or upgraded from the RPM packages distributed by &OSORG;; thus, it does not need to be executed manually. To verify that it was created, run the following command as <systemitem class="username">root</systemitem> to make sure the <filename>/boot/vmlinitrd-<replaceable>kernel_version</replaceable></filename> file already exists:
</para>
- <screen><command>ls -l /boot</command></screen>
+ <screen><command>ls -l /boot/</command></screen>
<para>
The <replaceable>kernel_version</replaceable> should match the version of the kernel just installed.
</para>
9 years, 5 months
[system-administrators-guide] kernel-tools
by stephenw
commit f3a037da65059748e63dd775b8bf7bc554357a20
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:32:38 2014 +0100
kernel-tools
en-US/Manually_Upgrading_the_Kernel.xml | 5 +++++
1 files changed, 5 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Manually_Upgrading_the_Kernel.xml b/en-US/Manually_Upgrading_the_Kernel.xml
index b9df95e..295ba78 100644
--- a/en-US/Manually_Upgrading_the_Kernel.xml
+++ b/en-US/Manually_Upgrading_the_Kernel.xml
@@ -165,6 +165,11 @@
<package>kernel-abi-whitelists</package> — Contains information pertaining to the &MAJOROS; kernel ABI, including a lists of kernel symbols that are needed by external Linux kernel modules and a <package>yum</package> plug-in to aid enforcement.
</para>
</listitem>
+ <listitem>
+ <para>
+ <package>kernel-tools</package> — Contains tools for manipulating the Linux kernel and supporting documentation.
+ </para>
+ </listitem>
</itemizedlist>
</section>
<section id="s1-kernel-preparing">
9 years, 5 months
[system-administrators-guide] kernel-abi-whitelists
by stephenw
commit a2606a810bfa382782890fd213cfac03d79856ef
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:32:01 2014 +0100
kernel-abi-whitelists
en-US/Manually_Upgrading_the_Kernel.xml | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Manually_Upgrading_the_Kernel.xml b/en-US/Manually_Upgrading_the_Kernel.xml
index cd27290..b9df95e 100644
--- a/en-US/Manually_Upgrading_the_Kernel.xml
+++ b/en-US/Manually_Upgrading_the_Kernel.xml
@@ -161,6 +161,10 @@
<package>perf</package> — This package contains supporting scripts and documentation for the <application>perf</application> tool shipped in each kernel image subpackage.
</para>
</listitem>
+ <para>
+ <package>kernel-abi-whitelists</package> — Contains information pertaining to the &MAJOROS; kernel ABI, including a lists of kernel symbols that are needed by external Linux kernel modules and a <package>yum</package> plug-in to aid enforcement.
+ </para>
+ </listitem>
</itemizedlist>
</section>
<section id="s1-kernel-preparing">
9 years, 5 months
[system-administrators-guide] Change wrong entity to "Fedora"
by stephenw
commit d4e39f62f62da96face2f6641b6ba23bc11769ba
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:18:26 2014 +0100
Change wrong entity to "Fedora"
en-US/Working_with_Kernel_Modules.xml | 20 ++++++++++----------
1 files changed, 10 insertions(+), 10 deletions(-)
---
diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml
index 1af0060..214f01c 100644
--- a/en-US/Working_with_Kernel_Modules.xml
+++ b/en-US/Working_with_Kernel_Modules.xml
@@ -478,10 +478,10 @@ virtio-net</screen>
<section id="sect-signing-kernel-modules-for-secure-boot">
<title>Signing Kernel Modules for Secure Boot</title>
<para>
- &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; can be installed and run on systems where UEFI Secure Boot is enabled. <footnote><para>&PRODUCT; does not require the use of Secure Boot on UEFI systems.</para></footnote> When Secure Boot is enabled, the EFI operating system boot loaders, the &PRODUCT; kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The &PRODUCT; distribution includes signed boot loaders, signed kernels, and signed kernel modules. In addition, the signed first-stage boot loader and the signed kernel include embedded &PRODUCT; public keys. These signed executable binaries and embedded keys enable &PRODUCT; to install, boot, and run with the Microsoft UEFI Secure Boot CA keys that are provided by the UEFI firmware on systems that support UEFI Secure Boot.<footnote><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote>
+ Fedora includes support for the UEFI Secure Boot feature, which means that Fedora can be installed and run on systems where UEFI Secure Boot is enabled. <footnote><para>Fedora does not require the use of Secure Boot on UEFI systems.</para></footnote> When Secure Boot is enabled, the EFI operating system boot loaders, the Fedora kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The Fedora distribution includes signed boot loaders, signed kernels, and signed kernel modules. In addition, the signed first-stage boot loader and the signed kernel include embedded Fedora public keys. These signed executable binaries and embedded keys enable Fedora to install, boot, and run with the Microsoft UEFI Secure Boot CA keys that are provided by the UEFI firmware on systems that support UEFI Secure Boot.<footnote><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote>
</para>
<para>
- The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with &PRODUCT; on UEFI-based systems where Secure Boot is enabled. These sections also provide an overview of available options for getting your public key onto the target system where you want to deploy your kernel module.
+ The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with Fedora on UEFI-based systems where Secure Boot is enabled. These sections also provide an overview of available options for getting your public key onto the target system where you want to deploy your kernel module.
</para>
<section id="sect-prerequisites">
@@ -544,7 +544,7 @@ virtio-net</screen>
<section id="sect-kernel-module-authentication">
<title>Kernel Module Authentication</title>
<para>
- In &PRODUCT;, when a kernel module is loaded, the module's signature is checked using the public X.509 keys on the kernel's system key ring, excluding those keys that are on the kernel's system black list key ring.
+ In Fedora, when a kernel module is loaded, the module's signature is checked using the public X.509 keys on the kernel's system key ring, excluding those keys that are on the kernel's system black list key ring.
</para>
<section id="sect-sources-for-public-keys-used-to-authenticate-kernel-modules">
@@ -618,13 +618,13 @@ virtio-net</screen>
Note that if the system is not UEFI-based or if UEFI Secure Boot is not enabled, then only the keys that are embedded in the kernel are loaded onto the system key ring and you have no ability to augment that set of keys without rebuilding the kernel. The system black list key ring is a list of X.509 keys which have been revoked. If your module is signed by a key on the black list then it will fail authentication even if your public key is in the system key ring.
</para>
<para>
- You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is not enabled.
+ You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a Fedora system where UEFI Secure Boot is not enabled.
</para>
<screen>~]# <command>keyctl list %:.system_keyring</command>
1 key in keyring:
61139991: ---lswrv 0 0 asymmetric: Fedora kernel signing key: 1fc9e68f7419556348fdee2fdeb7ff9da6337b</screen>
<para>
- The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is enabled.
+ The following is abbreviated example output from a Fedora system where UEFI Secure Boot is enabled.
</para>
<screen>~]# <command>keyctl list %:.system_keyring</command>
6 keys in keyring:
@@ -743,7 +743,7 @@ virtio-net</screen>
<procedure>
<step>
<para>
- The <command>openssl</command> tool can be used to generate a key pair that satisfies the requirements for kernel module signing in &PRODUCT;. Some of the parameters for this key generation request are best specified with a configuration file; follow the example below to create your own configuration file.</para>
+ The <command>openssl</command> tool can be used to generate a key pair that satisfies the requirements for kernel module signing in Fedora. Some of the parameters for this key generation request are best specified with a configuration file; follow the example below to create your own configuration file.</para>
<screen>~]# <command>cat << EOF > <replaceable>configuration_file</replaceable>.config</command>
[ req ]
default_bits = 4096
@@ -789,7 +789,7 @@ EOF</screen>
<section id="sect-enrolling-public-key-on-target-system"><title>Enrolling Public Key on Target System</title>
<para>
- When &PRODUCT; boots on a UEFI-based system with Secure Boot enabled, all keys that are in the Secure Boot db key database, but not in the dbx database of revoked keys, are loaded onto the system keyring by the kernel. The system keyring is used to authenticate kernel modules.
+ When Fedora boots on a UEFI-based system with Secure Boot enabled, all keys that are in the Secure Boot db key database, but not in the dbx database of revoked keys, are loaded onto the system keyring by the kernel. The system keyring is used to authenticate kernel modules.
</para>
<section id="sect-factory-firmware-image-including-public-key"><title>Factory Firmware Image Including Public Key</title>
<para>
@@ -801,7 +801,7 @@ EOF</screen>
It is possible to add a key to an existing populated and active Secure Boot key database. This can be done by writing and providing an EFI executable <emphasis>enrollment</emphasis> image. Such an enrollment image contains a properly formed request to append a key to the Secure Boot key database. This request must include data that is properly signed by the private key that corresponds to a public key that is already in the system's Secure Boot Key Exchange Key (KEK) database. Additionally, this EFI image must be signed by a private key that corresponds to a public key that is already in the key database.
</para>
<para>
- It is also possible to write an enrollment image that runs under &PRODUCT;. However, the &PRODUCT; image must be properly signed by a private key that corresponds to a public key that is already in the KEK database.
+ It is also possible to write an enrollment image that runs under Fedora. However, the Fedora image must be properly signed by a private key that corresponds to a public key that is already in the KEK database.
</para>
<para>
The construction of either type of key enrollment images requires assistance from the platform vendor.
@@ -809,7 +809,7 @@ EOF</screen>
</section>
<section id="sect-system-administrator-manually-adding-public-key-to-the-mok-list"><title>System Administrator Manually Adding Public Key to the MOK List</title>
<para>
- The Machine Owner Key (MOK) facility is a feature that is supported by &PRODUCT; and can be used to augment the UEFI Secure Boot key database. When &PRODUCT; boots on a UEFI-enabled system with Secure Boot enabled, the keys on the MOK list are also added to the system keyring in addition to the keys from the key database. The MOK list keys are also stored persistently and securely in the same fashion as the Secure Boot key database keys, but these are two separate facilities. The MOK facility is supported by shim.efi, MokManager.efi, grubx64.efi, and the &PRODUCT; <command>mokutil</command> utility.
+ The Machine Owner Key (MOK) facility is a feature that is supported by Fedora and can be used to augment the UEFI Secure Boot key database. When Fedora boots on a UEFI-enabled system with Secure Boot enabled, the keys on the MOK list are also added to the system keyring in addition to the keys from the key database. The MOK list keys are also stored persistently and securely in the same fashion as the Secure Boot key database keys, but these are two separate facilities. The MOK facility is supported by shim.efi, MokManager.efi, grubx64.efi, and the Fedora <command>mokutil</command> utility.
</para>
<para>
The major capability provided by the MOK facility is the ability to add public keys to the MOK list without needing to have the key chain back to another key that is already in the KEK database. However, enrolling a MOK key requires manual interaction by a <emphasis>physically present</emphasis> user at the UEFI system console on each target system. Nevertheless, the MOK facility provides an excellent method for testing newly generated key pairs and testing kernel modules signed with them.
@@ -820,7 +820,7 @@ EOF</screen>
<procedure>
<step>
<para>
- Request addition of your public key to the MOK list using a &PRODUCT; userspace utility:
+ Request addition of your public key to the MOK list using a Fedora userspace utility:
</para>
<screen>~]# <command>mokutil <option>--import</option> <filename>my_signing_key_pub.der</filename></command></screen>
<para>
9 years, 5 months
[system-administrators-guide] Update command output examples to suit Fed21
by stephenw
commit d501776fbc64ed282e228f89f83c9cb5870a420b
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:09:13 2014 +0100
Update command output examples to suit Fed21
en-US/Working_with_Kernel_Modules.xml | 17 ++++++++---------
1 files changed, 8 insertions(+), 9 deletions(-)
---
diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml
index 182ee4c..1af0060 100644
--- a/en-US/Working_with_Kernel_Modules.xml
+++ b/en-US/Working_with_Kernel_Modules.xml
@@ -149,21 +149,21 @@ nf_nat 21798 4 nf_nat_ipv4,nf_nat_ipv6,ip6table_nat,iptable_nat
<title>Listing information about a kernel module with lsmod</title>
<para>To display information about the <systemitem class="resource">e1000e</systemitem> module, which is the Intel PRO/1000 network driver, run:</para>
<screen>~]# <command>modinfo e1000e</command>
-filename: /lib/modules/3.15.6-200.fc20.x86_64/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
+filename: /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
version: 2.3.2-k
license: GPL
description: Intel(R) PRO/1000 Network Driver
author: Intel Corporation, <linux.nics(a)intel.com>
-srcversion: AB1D5F954DC03B1296E61BD
+srcversion: 2FBED3F5E2EF40112284D95
alias: pci:v00008086d00001503sv*sd*bc*sc*i*
alias: pci:v00008086d00001502sv*sd*bc*sc*i*
<lineannotation>[some <literal>alias</literal> lines omitted]</lineannotation>
alias: pci:v00008086d0000105Esv*sd*bc*sc*i*
depends: ptp
intree: Y
-vermagic: 3.15.6-200.fc20.x86_64 SMP mod_unload
+vermagic: 3.17.4-302.fc21.x86_64 SMP mod_unload
signer: Fedora kernel signing key
-sig_key: 5B:F5:46:43:B9:B1:61:72:B2:43:6D:40:A5:6F:75:0A:D1:58:1D:80
+sig_key: 1F:C9:E6:8F:74:19:55:63:48:FD:EE:2F:DE:B7:FF:9D:A6:33:7B:BF
sig_hashalgo: sha256
parm: debug:Debug level (0=none,...,16=all) (int)
parm: copybreak:Maximum size of packet that is copied to a new buffer on receive (uint)
@@ -282,11 +282,10 @@ parm: WriteProtectNVM:Write-protect NVM [WARNING: disabling this can l
<title>modprobe -v shows module dependencies as they are loaded</title>
<para>You can load the <systemitem class="protocol">Fibre Channel over Ethernet</systemitem> module verbosely by typing the following at a shell prompt:</para>
<screen>~]# <command>modprobe -v fcoe</command>
-insmod /lib/modules/3.16.6-200.fc20.x86_64/kernel/drivers/scsi/scsi_tgt.ko
-insmod /lib/modules/3.16.6-200.fc20.x86_64/kernel/drivers/scsi/scsi_transport_fc.ko
-insmod /lib/modules/3.16.6-200.fc20.x86_64/kernel/drivers/scsi/libfc/libfc.ko
-insmod /lib/modules/3.16.6-200.fc20.x86_64/kernel/drivers/scsi/fcoe/libfcoe.ko
-insmod /lib/modules/3.16.6-200.fc20.x86_64/kernel/drivers/scsi/fcoe/fcoe.ko</screen>
+insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/scsi_transport_fc.ko.xz
+insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/libfc/libfc.ko.xz
+insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/libfcoe.ko.xz
+insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/fcoe.ko.xz</screen>
<para>In this example, you can see that <command>modprobe</command> loaded the <systemitem class="resource">scsi_tgt</systemitem>, <systemitem class="resource">scsi_transport_fc</systemitem>, <systemitem class="resource">libfc</systemitem> and <systemitem class="resource">libfcoe</systemitem> modules as dependencies before finally loading <systemitem class="resource">fcoe</systemitem>. Also note that <command>modprobe</command> used the more primitive <command>insmod</command> command to insert the modules into the running kernel.</para>
</example>
<indexterm>
9 years, 5 months
[system-administrators-guide] Signing Kernel Modules for Secure Boot
by stephenw
commit b5d1e67efcbe76a2258604f5087fef4c40ea4917
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Dec 13 09:08:27 2014 +0100
Signing Kernel Modules for Secure Boot
en-US/Working_with_Kernel_Modules.xml | 445 +++++++++++++++++++++++++++++++++
1 files changed, 445 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml
index 790d15f..182ee4c 100644
--- a/en-US/Working_with_Kernel_Modules.xml
+++ b/en-US/Working_with_Kernel_Modules.xml
@@ -476,6 +476,451 @@ virtio-net</screen>
</section>
+ <section id="sect-signing-kernel-modules-for-secure-boot">
+ <title>Signing Kernel Modules for Secure Boot</title>
+ <para>
+ &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; can be installed and run on systems where UEFI Secure Boot is enabled. <footnote><para>&PRODUCT; does not require the use of Secure Boot on UEFI systems.</para></footnote> When Secure Boot is enabled, the EFI operating system boot loaders, the &PRODUCT; kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The &PRODUCT; distribution includes signed boot loaders, signed kernels, and signed kernel modules. In addition, the signed first-stage boot loader and the signed kernel include embedded &PRODUCT; public keys. These signed executable binaries and embedded keys enable &PRODUCT; to install, boot, and run with the Microsoft UEFI Secure Boot CA keys that are provided by the UEFI firmware on systems that support UEFI Secure Boot.<footnote><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote>
+ </para>
+ <para>
+ The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with &PRODUCT; on UEFI-based systems where Secure Boot is enabled. These sections also provide an overview of available options for getting your public key onto the target system where you want to deploy your kernel module.
+ </para>
+
+ <section id="sect-prerequisites">
+ <title>Prerequisites</title>
+ <para>
+ In order to enable signing of externally built modules, the tools listed in the following table are required to be installed on the system.
+ </para>
+
+ <table frame='all' id="table-required-tools"><title>Required Tools</title>
+ <tgroup cols='4' align='left'>
+ <thead>
+ <row>
+ <entry>Tool</entry>
+ <entry>Provided by Package</entry>
+ <entry>Used on</entry>
+ <entry>Purpose</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><command>openssl</command></entry>
+ <entry><package>openssl</package></entry>
+ <entry>Build system</entry>
+ <entry>Generates public and private X.509 key pair</entry>
+ </row>
+ <row>
+ <entry><command>sign-file</command></entry>
+ <entry><package>kernel-devel</package></entry>
+ <entry>Build system</entry>
+ <entry>Perl script used to sign kernel modules</entry>
+ </row>
+ <row>
+ <entry><command>perl</command></entry>
+ <entry><package>perl</package></entry>
+ <entry>Build system</entry>
+ <entry>Perl interpreter used to run the signing script</entry>
+ </row>
+ <row>
+ <entry><command>mokutil</command></entry>
+ <entry><package>mokutil</package></entry>
+ <entry>Target system</entry>
+ <entry>Optional tool used to manually enroll the public key</entry>
+ </row>
+ <row>
+ <entry><command>keyctl</command></entry>
+ <entry><package>keyutils</package></entry>
+ <entry>Target system</entry>
+ <entry>Optional tool used to display public keys in the system key ring</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>
+ Note that the build system, where you build and sign your kernel module, does not need to have UEFI Secure Boot enabled and does not even need to be a UEFI-based system.
+ </para>
+ </note>
+ </section>
+
+ <section id="sect-kernel-module-authentication">
+ <title>Kernel Module Authentication</title>
+ <para>
+ In &PRODUCT;, when a kernel module is loaded, the module's signature is checked using the public X.509 keys on the kernel's system key ring, excluding those keys that are on the kernel's system black list key ring.
+ </para>
+
+ <section id="sect-sources-for-public-keys-used-to-authenticate-kernel-modules">
+ <title>Sources For Public Keys Used To Authenticate Kernel Modules</title>
+ <para>
+ During boot, the kernel loads X.509 keys into the system key ring or the system black list key ring from a set of persistent key stores as shown in <xref linkend="table-sources-for-system-key-rings" />
+ </para>
+
+ <table frame='all' id="table-sources-for-system-key-rings"><title>Sources For System Key Rings</title>
+ <tgroup cols='4' align='left'>
+ <thead>
+ <row>
+ <entry>Source of X.509 Keys</entry>
+ <entry>User Ability to Add Keys</entry>
+ <entry>UEFI Secure Boot State</entry>
+ <entry>Keys Loaded During Boot</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Embedded in kernel</entry>
+ <entry>No</entry>
+ <entry>-</entry>
+ <entry><systemitem>.system_keyring</systemitem></entry>
+ </row>
+ <row>
+ <entry morerows="1">UEFI Secure Boot "db"</entry>
+ <entry morerows="1">Limited</entry>
+ <entry>Not enabled</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry><systemitem>.system_keyring</systemitem></entry>
+ </row>
+ <row>
+ <entry morerows="1">UEFI Secure Boot "dbx"</entry>
+ <entry morerows="1">Limited</entry>
+ <entry>Not enabled</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry><systemitem>.system_keyring</systemitem></entry>
+ </row>
+ <row>
+ <entry morerows="1">Embedded in <systemitem>shim.efi</systemitem> boot loader</entry>
+ <entry morerows="1">No</entry>
+ <entry>Not enabled</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry><systemitem>.system_keyring</systemitem></entry>
+ </row>
+ <row>
+ <entry morerows="1">Machine Owner Key (MOK) list</entry>
+ <entry morerows="1">Yes</entry>
+ <entry>Not enabled</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry><systemitem>.system_keyring</systemitem></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Note that if the system is not UEFI-based or if UEFI Secure Boot is not enabled, then only the keys that are embedded in the kernel are loaded onto the system key ring and you have no ability to augment that set of keys without rebuilding the kernel. The system black list key ring is a list of X.509 keys which have been revoked. If your module is signed by a key on the black list then it will fail authentication even if your public key is in the system key ring.
+ </para>
+ <para>
+ You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is not enabled.
+ </para>
+<screen>~]# <command>keyctl list %:.system_keyring</command>
+1 key in keyring:
+ 61139991: ---lswrv 0 0 asymmetric: Fedora kernel signing key: 1fc9e68f7419556348fdee2fdeb7ff9da6337b</screen>
+ <para>
+ The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is enabled.
+ </para>
+<screen>~]# <command>keyctl list %:.system_keyring</command>
+6 keys in keyring:
+...asymmetric: Red Hat Enterprise Linux Driver Update Program (key 3): bf57f3e87...
+...asymmetric: Red Hat Secure Boot (CA key 1): 4016841644ce3a810408050766e8f8a29...
+...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4309bd82709c8cd54f316ed...
+...asymmetric: Microsoft Windows Production PCA 2011: a92902398e16c49778cd90f99e...
+...asymmetric: Red Hat Enterprise Linux kernel signing key: 4249689eefc77e95880b...
+...asymmetric: Red Hat Enterprise Linux kpatch signing key: 4d38fd864ebe18c5f0b7...</screen>
+ <para>
+ The above output shows the addition of two keys from the UEFI Secure Boot "db" keys plus the <computeroutput>Red Hat Secure Boot (CA key 1)</computeroutput> which is embedded in the <systemitem>shim.efi</systemitem> boot loader. You can also look for the kernel console messages that identify the keys with an UEFI Secure Boot related source, that is UEFI Secure Boot db, embedded shim, and MOK list.
+ </para>
+<screen>~]# <command>dmesg | grep 'EFI: Loaded cert'</command>
+[5.160660] EFI: Loaded cert 'Microsoft Windows Production PCA 2011: a9290239...
+[5.160674] EFI: Loaded cert 'Microsoft Corporation UEFI CA 2011: 13adbf4309b...
+[5.165794] EFI: Loaded cert 'Red Hat Secure Boot (CA key 1): 4016841644ce3a8...</screen>
+ </section>
+ <section id="sect-kernel-module-authentication-requirements">
+ <title>
+ Kernel Module Authentication Requirements
+ </title>
+ <para>
+ If UEFI Secure Boot is enabled or if the <option>module.sig_enforce</option> kernel parameter has been specified, then only signed kernel modules that are authenticated using a key on the system key ring can be successfully loaded.<footnote><para>Provided that the public key is not on the system black list key ring.</para></footnote> If UEFI Secure Boot is disabled and if the <option>module.sig_enforce</option> kernel parameter has not been specified, then unsigned kernel modules and signed kernel modules without a public key can be successfully loaded. This is summarized in <xref linkend="table-kernel-module-authentication-requirements-for-loading"/>.
+ </para>
+
+ <table frame='all' id="table-kernel-module-authentication-requirements-for-loading"><title>Kernel Module Authentication Requirements for Loading</title>
+ <tgroup cols='6' align='left'>
+ <thead>
+ <row>
+ <entry>Module Signed</entry>
+ <entry>Public Key Found and Signature Valid</entry>
+ <entry>UEFI Secure Boot State</entry>
+ <entry>module.sig_enforce</entry>
+ <entry>Module Load</entry>
+ <entry>Kernel Tainted</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="2">Unsigned</entry>
+ <entry morerows="2">-</entry>
+ <entry>Not enabled</entry>
+ <entry>Not enabled</entry>
+ <entry>Succeeds</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Not enabled</entry>
+ <entry>Enabled</entry>
+ <entry>Fails</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry>-</entry>
+ <entry>Fails</entry>
+ <entry>-</entry>
+ </row>
+
+ <row>
+ <entry morerows="2">Signed</entry>
+ <entry morerows="2">No</entry>
+ <entry>Not enabled</entry>
+ <entry>Not enabled</entry>
+ <entry>Succeeds</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Not enabled</entry>
+ <entry>Enabled</entry>
+ <entry>Fails</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry>-</entry>
+ <entry>Fails</entry>
+ <entry>-</entry>
+ </row>
+
+ <row>
+ <entry morerows="2">Signed</entry>
+ <entry morerows="2">Yes</entry>
+ <entry>Not enabled</entry>
+ <entry>Not enabled</entry>
+ <entry>Succeeds</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Not enabled</entry>
+ <entry>Enabled</entry>
+ <entry>Succeeds</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Enabled</entry>
+ <entry>-</entry>
+ <entry>Succeeds</entry>
+ <entry>No</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Subsequent sections will describe how to generate a public and private X.509 key pair, how to use the private key to sign a kernel module, and how to enroll the public key into a source for the system key ring.
+ </para>
+ </section>
+ </section>
+
+ <section id="sect-generating-a-public-private-x509-key-pair">
+ <title>Generating a Public and Private X.509 Key Pair</title>
+ <para>
+ You need to generate a public and private X.509 key pair that will be used to sign a kernel module after it has been built. The corresponding public key will be used to authenticate the kernel module when it is loaded.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ The <command>openssl</command> tool can be used to generate a key pair that satisfies the requirements for kernel module signing in &PRODUCT;. Some of the parameters for this key generation request are best specified with a configuration file; follow the example below to create your own configuration file.</para>
+<screen>~]# <command>cat << EOF > <replaceable>configuration_file</replaceable>.config</command>
+[ req ]
+default_bits = 4096
+distinguished_name = req_distinguished_name
+prompt = no
+string_mask = utf8only
+x509_extensions = myexts
+
+[ req_distinguished_name ]
+O = <replaceable>Organization</replaceable>
+CN = <replaceable>Organization signing key</replaceable>
+emailAddress = <replaceable>E-mail address</replaceable>
+
+[ myexts ]
+basicConstraints=critical,CA:FALSE
+keyUsage=digitalSignature
+subjectKeyIdentifier=hash
+authorityKeyIdentifier=keyid
+EOF</screen>
+ </step>
+ <step>
+ <para>
+ After you have created the configuration file, you can create an X.509 public and private key pair. The public key will be written to the <filename><replaceable>public_key</replaceable>.der</filename> file and the private key will be written to the <filename><replaceable>private_key</replaceable>.priv</filename> file.
+ </para>
+
+<screen>~]# <command>openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 \
+> -batch -config <replaceable>configuration_file</replaceable>.config -outform DER \
+> -out <replaceable>public_key</replaceable>.der \
+> -keyout <replaceable>private_key</replaceable>.priv</command></screen>
+ </step>
+ <step>
+ <para>
+ Enroll your public key on all systems where you want to authenticate and load your kernel module.
+ </para>
+ </step>
+ </procedure>
+<warning>
+ <para>
+ Take proper care to guard the contents of your private key. In the wrong hands, the key could be used to compromise any system which has your public key.
+ </para>
+</warning>
+ </section>
+
+ <section id="sect-enrolling-public-key-on-target-system"><title>Enrolling Public Key on Target System</title>
+ <para>
+ When &PRODUCT; boots on a UEFI-based system with Secure Boot enabled, all keys that are in the Secure Boot db key database, but not in the dbx database of revoked keys, are loaded onto the system keyring by the kernel. The system keyring is used to authenticate kernel modules.
+ </para>
+ <section id="sect-factory-firmware-image-including-public-key"><title>Factory Firmware Image Including Public Key</title>
+ <para>
+ To facilitate authentication of your kernel module on your systems, consider requesting your system vendor to incorporate your public key into the UEFI Secure Boot key database in their factory firmware image.
+ </para>
+ </section>
+ <section id="sect-executable-key-enrollment-image-adding-public-key"><title>Executable Key Enrollment Image Adding Public Key</title>
+ <para>
+ It is possible to add a key to an existing populated and active Secure Boot key database. This can be done by writing and providing an EFI executable <emphasis>enrollment</emphasis> image. Such an enrollment image contains a properly formed request to append a key to the Secure Boot key database. This request must include data that is properly signed by the private key that corresponds to a public key that is already in the system's Secure Boot Key Exchange Key (KEK) database. Additionally, this EFI image must be signed by a private key that corresponds to a public key that is already in the key database.
+ </para>
+ <para>
+ It is also possible to write an enrollment image that runs under &PRODUCT;. However, the &PRODUCT; image must be properly signed by a private key that corresponds to a public key that is already in the KEK database.
+ </para>
+ <para>
+ The construction of either type of key enrollment images requires assistance from the platform vendor.
+ </para>
+ </section>
+ <section id="sect-system-administrator-manually-adding-public-key-to-the-mok-list"><title>System Administrator Manually Adding Public Key to the MOK List</title>
+ <para>
+ The Machine Owner Key (MOK) facility is a feature that is supported by &PRODUCT; and can be used to augment the UEFI Secure Boot key database. When &PRODUCT; boots on a UEFI-enabled system with Secure Boot enabled, the keys on the MOK list are also added to the system keyring in addition to the keys from the key database. The MOK list keys are also stored persistently and securely in the same fashion as the Secure Boot key database keys, but these are two separate facilities. The MOK facility is supported by shim.efi, MokManager.efi, grubx64.efi, and the &PRODUCT; <command>mokutil</command> utility.
+ </para>
+ <para>
+ The major capability provided by the MOK facility is the ability to add public keys to the MOK list without needing to have the key chain back to another key that is already in the KEK database. However, enrolling a MOK key requires manual interaction by a <emphasis>physically present</emphasis> user at the UEFI system console on each target system. Nevertheless, the MOK facility provides an excellent method for testing newly generated key pairs and testing kernel modules signed with them.
+ </para>
+ <para>
+ Follow these steps to add your public key to the MOK list:
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Request addition of your public key to the MOK list using a &PRODUCT; userspace utility:
+ </para>
+<screen>~]# <command>mokutil <option>--import</option> <filename>my_signing_key_pub.der</filename></command></screen>
+ <para>
+ You will be asked to enter and confirm a password for this MOK enrollment request.
+ </para>
+ </step>
+ <step>
+ <para>
+ Reboot the machine.
+ </para>
+ </step>
+ <step>
+ <para>
+ The pending MOK key enrollment request will be noticed by <systemitem>shim.efi</systemitem> and it will launch <systemitem>MokManager.efi</systemitem> to allow you to complete the enrollment from the UEFI console. You will need to enter the password you previously associated with this request and confirm the enrollment. Your public key is added to the MOK list, which is persistent.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ Once a key is on the MOK list, it will be automatically propagated to the system key ring on this and subsequent boots when UEFI Secure Boot is enabled.
+ </para>
+ </section>
+ </section>
+ <section id="sect-signing-kernel-module-with-the-private-key">
+ <title>Signing Kernel Module with the Private Key</title>
+ <para>
+ There are no extra steps required to prepare your kernel module for signing. You build your kernel module normally. Assuming an appropriate Makefile and corresponding sources, follow these steps to build your module and sign it:
+ </para>
+
+ <procedure>
+ <step>
+ <para>
+ Build your <filename>my_module.ko</filename> module the standard way:
+ </para>
+<screen>~]# <command>make -C /usr/src/kernels/$(uname -r) M=$PWD modules</command></screen>
+ </step>
+ <step>
+ <para>
+ Sign your kernel module with your private key. This is done with a Perl script. Note that the script requires that you provide both the files that contain your private and the public key as well as the kernel module file that you want to sign.
+ </para>
+<screen>~]# <command>perl /usr/src/kernels/$(uname -r)/scripts/sign-file \
+> sha256 \
+> my_signing_key.priv \
+> my_signing_key_pub.der \
+> my_module.ko</command></screen>
+ </step>
+ </procedure>
+ <para>
+ Your kernel module is in ELF image format and this script computes and appends the signature directly to the ELF image in your <filename>my_module.ko</filename> file. The <command>modinfo</command> utility can be used to display information about the kernel module's signature, if it is present. For information on using the utility, see <xref linkend="sec-Displaying_Information_About_a_Module" />.
+ </para>
+ <para>
+ Note that this appended signature is not contained in an ELF image section and is not a formal part of the ELF image. Therefore, tools such as <command>readelf</command> will not be able to display the signature on your kernel module.
+ </para>
+ <para>
+ Your kernel module is now ready for loading. Note that your signed kernel module is also loadable on systems where UEFI Secure Boot is disabled or on a non-UEFI system. That means you do not need to provide both a signed and unsigned version of your kernel module.
+ </para>
+ </section>
+ <section id="sect-loading-signed-kernel-module">
+ <title>Loading Signed Kernel Module</title>
+ <para>
+ Once your public key is enrolled and is in the system keyring, the normal kernel module loading mechanisms will work transparently. In the following example, you will use <command>mokutil</command> to add your public key to the MOK list and you will manually load your kernel module with <command>modprobe</command>.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Optionally, you can verify that your kernel module will not load before you have enrolled your public key. First, verify what keys have been added to the system key ring on the current boot by running the <command>keyctl list %:.system_keyring</command> as root. Since your public key has not been enrolled yet, it should not be displayed in the output of the command.
+ </para>
+ </step>
+ <step>
+ <para>
+ Request enrollment of your public key.
+ </para>
+<screen>~]# <command>mokutil --import <replaceable>my_signing_key_pub</replaceable>.der</command></screen>
+ </step>
+ <step>
+ <para>
+ Reboot, and complete the enrollment at the UEFI console.
+ </para>
+<screen>~]# <command>reboot</command></screen>
+ </step>
+
+ <step>
+ <para>
+ After the system reboots, verify the keys on the system key ring again.
+ </para>
+<screen>~]# <command>keyctl list %:.system_keyring</command></screen>
+ </step>
+ <step>
+ <para>
+ You should now be able to load your kernel module successfully.
+ </para>
+<screen>~]# <command>modprobe -v <replaceable>my_module</replaceable></command>
+insmod /lib/modules/3.17.4-302.fc21.x86_64/extra/<replaceable>my_module</replaceable>.ko
+~]# <command>lsmod | grep <replaceable>my_module</replaceable></command>
+<replaceable>my_module</replaceable> 12425 0</screen>
+ </step>
+ </procedure>
+ </section>
+ </section>
+
<section
id="s1-kernel-modules-additional-resources">
<title>Additional Resources</title>
9 years, 5 months
[system-administrators-guide] Added quotes to `timedatectl` invocation with both time and date.
by Pete Travis
commit 08be912bc2cc730b9eaf2ef0a939b48326423041
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Wed Dec 10 22:04:44 2014 -0700
Added quotes to `timedatectl` invocation with both time and date.
Thanks to @Cygniapolis for reporting via
https://ask.fedoraproject.org/en/question/59289
en-US/Configuring_the_Date_and_Time.xml | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
---
diff --git a/en-US/Configuring_the_Date_and_Time.xml b/en-US/Configuring_the_Date_and_Time.xml
index 580877b..bd13810 100644
--- a/en-US/Configuring_the_Date_and_Time.xml
+++ b/en-US/Configuring_the_Date_and_Time.xml
@@ -105,7 +105,7 @@ NTP synchronized: no
<para>
To change the current date to 2 June 2013 and keep the current time (11:26 p.m.), run the following command as <systemitem class="username">root</systemitem>:
</para>
-<screen>~]# <command>timedatectl set-time 2013-06-02 23:26:00</command></screen>
+<screen>~]# <command>timedatectl set-time "2013-06-02 23:26:00"</command></screen>
</example>
</section>
<section id="sect-Configuring_the_Date_and_Time-timedatectl-Time_Zone">
9 years, 5 months