From 27140fc7d18bf249c01d51771d8e4857100e3431 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Tue, 6 Jun 2023 21:31:17 +0200
Subject: [PATCH] man: add example how to configure automatic signing

Fixes #978.
---
 man/uki.conf.example | 14 ++++++++++++++
 man/ukify.xml        | 30 ++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 man/uki.conf.example

diff --git a/man/uki.conf.example b/man/uki.conf.example
new file mode 100644
index 0000000000..84a9f77b8d
--- /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 283d58b3b0..6895301d01 100644
--- 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>
-- 
2.25.1