system/efitools: Update README.

Signed-off-by: Willy Sudiarto Raharjo <willysr@slackbuilds.org>

5 files changed, 141 insertions, 8 deletions

diff --git a/system/efitools/README b/system/efitools/README
index 939fd6c9457c..d10aac792249 100644
--- a/system/efitools/README
+++ b/system/efitools/README
@@ -1,10 +1,11 @@
+## README efitools
 efitools is a set of tools for manipulating EFI secure boot platforms.
 
 If you ever plan to use LockDown.efi (it's an EFI program that
-installs a predefined set of Secure Boot keys if you run it while your
-machine is in setup mode) you will want to use your own Secure Boot
-keys and maybe specify an owner GUID (in hex). The keys should be placed
-in the SlackBuild directory and named:
+installs a predefined set of Secure Boot keys if you run it while
+your machine is in setup mode) you will want to use your own Secure
+Boot keys and maybe specify an owner GUID (in hex). The keys should
+be placed in the SlackBuild directory and named:
 Platform Key public/private keys - PK.crt, PK.key
 Key Exchange public/private keys - KEK.crt, KEK.key
 Signature Database public/private keys - DB.crt, DB.key
@@ -14,5 +15,19 @@ and the SlackBuild should be executed using:
 GUID=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx USE_KEYS=yes \
   ./efitools.SlackBuild
 
+efitool-mkusb to make a bootable usbstick, the process will delete
+all files on the usbstick.
+
 It's unlikely that you'll use LockDown.efi and there are alternate
 methods to do what it does, so it's fine just to ignore it.
+
+WARNING!!!! PLEASE MAKE SURE YOU KNOW EXACTLY WHAT YOU ARE DOING
+BEFORE PROCEEDING.
+
+SlackBuilds.org 2023 accepts no liability for any issues caused by
+using this software. The software is provided as is and requires a
+working knowledge, of setting up
+secure booting and keys.
+
+For information how to use this software for secure/boot on Linux
+please see the included. README.Secure_Boot
diff --git a/system/efitools/README.Secure_Boot b/system/efitools/README.Secure_Boot
new file mode 100644
index 000000000000..41a45914c8cd
--- /dev/null
+++ b/system/efitools/README.Secure_Boot
@@ -0,0 +1,116 @@
+## README_Secure_Boot
+
+WARNING!!!! PLEASE MAKE SURE YOU KNOW EXACTLY WHAT YOU ARE DOING BEFORE PROCEEDING.
+
+SlackBuilds.org 2023 accepts no liability for any issues caused by
+using this software. The software is provided as is and requires
+a working knowledge, of setting up secure booting and keys.
+
+
+How to use these files
+
+simply typing make will build you everything including sample certificates for
+PK, KEK and db.
+
+The prerequisites are the standard development environment,
+gnu-efi version 3.0q or later, help2man and sbsigntools.
+
+There will be one file called LockDown.efi.  If run on your
+efi platform in Setup Mode, this binary will *replace* all the
+values in thePK, KEK and db
+variables with the ones you just generated and place the platform
+back into User Mode (booting securely).  If you don't
+want to replace allthe variables, take a dump of your current
+variables,
+see sig-list-to-cert(1), and add them
+to the EFI signature list files before creating LockDown.efi
+
+Say you want to concatenate an existing platform-db.esl file,
+do this:
+
+make DB.esl
+cat platform.esl DB.esl > newDB.esl
+mv newDB.esl DB.esl
+
+and then make LockDown.efi in the usual way.
+
+All of the EFI programs are also generated in signed form
+(signed by both db and KEK).
+
+
+Loader.efi
+==========
+
+This EFI binary is created to boot an unsigned EFI file on the
+platform. Since this explicitly breaks the security of the
+platform, it will first check to see if the boot binary is
+naturally executable and execute it if it is
+(either it's properly signed or the platform isn't in Secure
+Boot mode).
+
+If the binary gives an EFI_ACCESS_DENIED error meaning it
+isn't properly signed,
+Loader.efi will request present user authorisation before
+proceeding to boot.
+
+The idea is that Loader.efi may serve as a chain for elilo.efi
+or another boot loader on distributed linux live and install
+CDs and even as
+the boot loader for the distribution on the hard disk
+assuming the user does not wish to take control of the platform
+and replace the keys.
+
+To build a secure bootable CD, simply use Loader.efi as the usual
+/efi/boot/bootX64.efi and place the usual loader in the same
+directory as the file boot.efi.
+
+In order to add further convenience, if the user places
+the platform in setup mode and re-runs the loader,
+it will ask permission to add the signature the unsigned
+boot loader, boot.efi, to the authorised signatures
+database, meaningLoader.efi will now no longer
+ask for present user authorisation every time the system is
+started.
+
+
+Creating, using and installing your own keys
+============================================
+
+To create PEM files with the certificate and the key for PK for
+example, do
+
+openssl req -new -x509 -newkey rsa:2048 -subj "/CN=PK/" -keyout \
+PK.key -out PK.crt -days 3650 -nodes -sha256
+
+Which will create a self signed X509 certificate for PK in PK.crt
+(using unprotected key PK.key with the subject common name PK
+(that's what the CN=PK is doing).
+
+You need to create at least three sets of certificates: one for PK,
+one for KEK and one for db.
+
+Now you need to take all the efi binaries in
+/usr/share/efitools/efi and sign them with your own db key
+using,
+sbsign --key db.key --cert db.crt --output \
+HelloWorld-signed.efi HelloWorld.efi
+
+To install your new keys on the platform, first create your
+authorised update bundles:
+
+cert-to-sig-list PK.crt PK.esl
+sign-efi-sig-list -k PK.key -c PK.crt PK PK.esl PK.auth
+
+And repeat for KEK and db.  In setup mode, it only matters that
+the PK update PK.auth is signed by the new platform key.
+None of the other variables will have their signatures checked.
+
+Now on your platform update the variables, remembering to do PK
+last because an update to PK usually puts the platform
+into secure mode
+
+UpdateVars db db.auth
+UpdateVars KEK KEK.auth
+UpdateVars PK PK.auth
+
+And you should now be running in secure mode with your own keys.
diff --git a/system/efitools/efitools.SlackBuild b/system/efitools/efitools.SlackBuild
index 5482dae9e63e..6670f971bdf5 100644
--- a/system/efitools/efitools.SlackBuild
+++ b/system/efitools/efitools.SlackBuild
@@ -5,6 +5,8 @@
 # Copyright 2015 Jonathan Li
 # All rights reserved.
 #
+# With changes made by Sam Wright December 2023
+#
 # Redistribution and use of this script, with or without modification, is
 # permitted provided that the following conditions are met:
 #
@@ -127,7 +129,7 @@ for i in $( find $PKG/usr/man -type l ) ; do ln -s $( readlink $i ).gz $i.gz ; r
 
 mkdir -p $PKG/usr/doc/$PRGNAM-$VERSION
 cd $PKG/usr/share/efitools
-mv README COPYING $PKG/usr/doc/$PRGNAM-$VERSION
+mv README README_Secure_Boot COPYING $PKG/usr/doc/$PRGNAM-$VERSION
 cat $CWD/$PRGNAM.SlackBuild > $PKG/usr/doc/$PRGNAM-$VERSION/$PRGNAM.SlackBuild
 
 mkdir -p $PKG/install
diff --git a/system/efitools/efitools.info b/system/efitools/efitools.info
index ff0b1df6bcf9..c2dbacddce09 100644
--- a/system/efitools/efitools.info
+++ b/system/efitools/efitools.info
@@ -6,5 +6,5 @@ MD5SUM="a3a3f04ed6aa5486c97dd206edeebe0a"
 DOWNLOAD_x86_64=""
 MD5SUM_x86_64=""
 REQUIRES="perl-File-Slurp sbsigntools"
-MAINTAINER="Jonathan Li"
-EMAIL="jonathan dot li at hotmail dot co dot uk"
+MAINTAINER="Sam Wright"
+EMAIL="proaudiomanuk@gmail.com"
diff --git a/system/efitools/slack-desc b/system/efitools/slack-desc
index f29b47e2c84c..a93ab08e6af8 100644
--- a/system/efitools/slack-desc
+++ b/system/efitools/slack-desc
@@ -9,7 +9,7 @@
 efitools: efitools (Tools for manipulating UEFI secure boot platforms)
 efitools:
 efitools: efitools is a set of tools for manipulating EFI secure boot platforms.
-efitools:
+efitools: and make a efi boot usb-stick.
 efitools:
 efitools:
 efitools: