From 7bb68b84a237ddfbd9278532b789c8129d6cdf0f Mon Sep 17 00:00:00 2001
From: John Soros <j@roxor.me>
Date: Wed, 21 Nov 2018 15:48:24 +0000
Subject: [PATCH] custom kernel: Add documentation for building a kernel signed
 with the user's Machine Owner Key

The Machine Owner Key allows a user to build a custom kernel that is bootable using secure boot.
---
 .../pages/kernel/build-custom-kernel.adoc     | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/modules/ROOT/pages/kernel/build-custom-kernel.adoc b/modules/ROOT/pages/kernel/build-custom-kernel.adoc
index 0f183f1..dbd5bd3 100644
--- a/modules/ROOT/pages/kernel/build-custom-kernel.adoc
+++ b/modules/ROOT/pages/kernel/build-custom-kernel.adoc
@@ -44,6 +44,8 @@ If you want to use `make xconfig`, you'll need some additional packages:
 sudo dnf install qt3-devel libXi-devel gcc-c++
 ----
 
+=== Secure boot
+
 Make sure you add the user doing the build to `/etc/pesign/users` and run the
 authorize user script:
 
@@ -52,6 +54,48 @@ authorize user script:
 sudo /usr/libexec/pesign/pesign-authorize
 ----
 
+Create a new Machine Owner Key (MOK) to import to UEFI:
+
+[source,bash]
+----
+openssl req -new -x509 -newkey rsa:2048 -keyout "key.pem" \
+        -outform DER -out "cert.der" -nodes -days 36500 \
+        -subj "/CN=<your name>/"
+----
+
+Import the new certificate into your UEFI database:
+
+NOTE: You will be asked to authorize the import at next boot.
+
+[source,bash]
+----
+mokutil --import "cert.der"
+----
+
+Create a PKCS #12 key file:
+
+[source,bash]
+----
+openssl pkcs12 -export -out key.p12 -inkey key.pem -in cert.der
+----
+
+You can then import the certificate and key into the nss database:
+
+[source,bash]
+----
+certutil -A -i cert.der -n "<MOK certificate nickname>" -d /etc/pki/pesign/ -t "Pu,Pu,Pu"
+pk12util -i key.p12 -d /etc/pki/pesign
+----
+
+Once the certificate and key are imported into your nss database, you can build the kernel
+with the selected key by adding `%define pe_signing_cert <MOK certificate nickname>` to the
+kernel.spec file or calling rpmbuild directly with the
+`--define "pe_signing_cert <MOK certificate nickname>"` flag.
+
+NOTE: While https://bugzilla.redhat.com/show_bug.cgi?id=1651020[bugzilla bug #1651020] is open
+you might need to edit the line that starts with `+%pesign+` in the kernel spec file and substitute
+it with `+pesign -c %{pe_signing_cert} --certdir /etc/pki/pesign/ -s -i $KernelImage -o vmlinuz.signed+`.
+
 It's also recommended that you install `ccache`, which can help speed up
 rebuilds: