man: add example how to configure automatic signing

Fixes #978.

diff --git a/man/uki.conf.example b/man/uki.conf.example
new file mode 100644 (file)
index 0000000..84a9f77
--- /dev/null
+++ b/man/uki.conf.example
@@ -0,0 +1,14 @@
+[UKI]
+SecureBootPrivateKey=/etc/kernel/secure-boot.key.pem
+SecureBootCertificate=/etc/kernel/secure-boot.cert.pem
+
+[PCRSignature:initrd]
+Phases=enter-initrd
+PCRPrivateKey=/etc/kernel/pcr-initrd.key.pem
+PCRPublicKey=/etc/kernel/pcr-initrd.pub.pem
+
+[PCRSignature:system]
+Phases=enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit
+       enter-initrd:leave-initrd:sysinit:ready
+PCRPrivateKey=/etc/kernel/pcr-system.key.pem
+PCRPublicKey=/etc/kernel/pcr-system.pub.pem

diff --git a/man/ukify.xml b/man/ukify.xml
index 283d58b3b05ef5cdd095a723ccb2e23f6fa746fe..6895301d016e6ab994a8e3c8907acd6e166a6dc1 100644 (file)
--- a/man/ukify.xml
+++ b/man/ukify.xml
@@ -499,6 +499,36 @@ $ /usr/lib/systemd/ukify -c ukify.conf build \
       <para>This creates a signed PE binary that contains the additional kernel command line parameter
       <literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para>
     </example>
+
+    <example>
+      <title>Decide signing policy and create certificate and keys</title>
+
+      <para>First, let's create an config file that specifies what signatures shall be made:</para>
+
+      <programlisting># cat >/etc/kernel/uki.conf &lt;&lt;EOF
+<xi:include href="uki.conf.example" parse="text" />EOF</programlisting>
+
+      <para>Next, we can generate the certificate and keys:</para>
+      <programlisting># /usr/lib/systemd/ukify genkey --config=/etc/kernel/uki.conf
+Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
+Writing SecureBoot certicate to /etc/kernel/secure-boot.cert.pem
+Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
+Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
+Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
+Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
+</programlisting>
+
+      <para>(Both operations need to be done as root to allow write access
+      to <filename>/etc/kernel/</filename>.)</para>
+
+      <para>Subsequent invocations of using the config file
+      (<command>/usr/lib/systemd/ukify build --config=/etc/kernel/uki.conf</command>)
+      will use this certificate and key files. Note that the
+      <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename>
+      by default, so after this file has been created, installations of kernels that create a UKI on the
+      local machine using <command>kernel-install</command> would perform signing using this config.</para>
+    </example>
   </refsect1>
 
   <refsect1>