[bug#49654] [PATCH] doc: Add full disc encryption guide to the cookbook

[Joshua Branson]

From: Joshua Branson <jbranso AT gnucode.me>

The original guide was written by Raghav Gururajan <rg@raghavgururajan.name>
and edited by Joshua Branson <jbranso@dismail.de>.

* doc/guix-cookbook.texi (System Configuration): New section of full disc
encryption via libreboot.
---
 doc/guix-cookbook.texi | 724 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 724 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 2e627ecc51..ef8f3425d6 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -18,6 +18,7 @@ Copyright @copyright{} 2020 Brice Waegeneire@*
 Copyright @copyright{} 2020 André Batista@*
 Copyright @copyright{} 2020 Christopher Lemmer Webber
 Copyright @copyright{} 2021 Joshua Branson@*
+Copyright @copyright{} 2021 Raghav Gururajan@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -1358,6 +1359,7 @@ reference.
 * Customizing the Kernel::       Creating and using a custom Linux kernel on 
Guix System.
 * Guix System Image API::        Customizing images to target specific 
platforms.
 * Connecting to Wireguard VPN::  Connecting to a Wireguard VPN.
+* Guix System with Full Disk Encryption::    Guix System with Full Disk 
Encryption
 * Customizing a Window Manager:: Handle customization of a Window manager on 
Guix System.
 * Running Guix on a Linode Server:: Running Guix on a Linode Server
 * Setting up a bind mount:: Setting up a bind mount in the file-systems 
definition.
@@ -1938,6 +1940,728 @@ For more specific information about NetworkManager and 
wireguard
 
@uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see
 this post by thaller}.
 
+@node Guix System with Full Disk Encryption
+@section Guix System with Full Disk Encryption
+@cindex libreboot, full disk encryption
+
+Guix System is an exotic distribution of GNU/Linux operating system,
+with Guix as package/system manager, Linux-Libre as kernel and
+Shepherd as init system.
+
+Libreboot is a de-blobbed distribution of Coreboot firmware. By
+default, Libreboot comes with GRUB bootloader as a payload.
+
+The objective of this manual is to provide step-by-step guide for
+setting up Guix System (stand-alone Guix), with Full Disk
+Encryption (FDE), on devices powered by Libreboot.
+
+Any users, for their generalized use cases, need not stumble away from
+this guide to accomplish the setup. Advanced users, for deviant use
+cases, will have to explore outside this guide for customization;
+although this guide provides information that is of paramount use.
+
+Let us begin!
+
+@menu
+* Create Boot-able USB::
+* Installing and Setup::
+* Tweaking Libreboot's Grub Payload::
+* Closing Thoughts::
+* Special Thanks::
+@end menu
+
+@node Create Boot-able USB
+@subsection Create Boot-able USB
+
+In the current GNU+Linux system, open terminal as root user.
+
+Insert USB drive and get the device letter @code{/dev/sdX}, where “X” is the
+device letter.
+
+@example
+lsblk --list
+@end example
+
+@example
+NAME  MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
+sda     8:0    0 223.6G  0 disk
+sda1    8:1    0     2M  0 part
+sda2    8:2    0   3.7G  0 part
+sda3    8:3    0 219.9G  0 part /
+zram0 251:0    0   512M  0 disk [SWAP]
+@end example
+
+
+Just in case the device is auto-mounted, unmount the device.
+
+@example
+umount /dev/sdX --verbose
+@end example
+
+Download the Guix System ISO installer package and it’s GPG signature;
+where @code{A.B.C} is the version number and @code{SSS} is the system
+architecture.
+
+@example
+wget --verbose 
https://ftp.gnu.org/gnu/guix/guix-system-install-A.B.C.SSS-linux.iso.xz
+wget --verbose 
https://ftp.gnu.org/gnu/guix/guix-system-install-A.B.C.SSS-linux.iso.xz.sig
+@end example
+
+Import the Guix's public key.
+
+@example
+gpg --verbose --keyserver pool.sks-keyservers.net –-receive-keys 
3CE464558A84FDC69DB40CFB090B11993D9AEBB5
+@end example
+
+Verify the GPG signature of the downloaded package.
+
+@example
+gpg --verbose --verify guix-system-install-A.B.C.SSS-linux.iso.xz.sig
+@end example
+
+Extract ISO image from the downloaded package.
+
+@example
+xz --verbose --decompress guix-system-install-A.B.C.SSS-linux.iso.xz
+@end example
+
+Write the extracted ISO image to the drive.
+
+@example
+dd if=guix-system-install-A.B.C.SSS-linux.iso of=/dev/sdX status=progress; sync
+@end example
+
+Reboot the device.
+
+@example
+reboot
+@end example
+
+@node Installing and Setup
+@subsection Installing and Setup
+
+On reboot, as soon as the Libreboot's graphic art appears, press "S"
+or choose @code{Search for GRUB2 configuration on external media [s]}. Wait
+for the Guix System from USB drive to load.
+
+Once Guix System installer starts, choose @code{Install using the shell
+based process}.
+
+Set your keyboard layout, where @code{lo} is the two-letter keyboard
+layout code (lower-case).
+
+@example
+loadkeys --verbose lo
+@end example
+
+Unblock network interfaces.
+
+@example
+rfkill unblock all
+@end example
+
+Get the names of network interfaces.
+
+@example
+ifconfig -v -a
+@end example
+
+@example
+enp0s25   Link encap:Ethernet  HWaddr 00:1C:25:9A:37:BA
+          UP BROADCAST MULTICAST  MTU:1500  Metric:1
+          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:1000
+          RX bytes:0  TX bytes:0
+          Interrupt:16 Memory:98800000-98820000
+
+lo        Link encap:Local Loopback
+          inet addr:127.0.0.1  Bcast:0.0.0.0  Mask:255.0.0.0
+          UP LOOPBACK RUNNING  MTU:65536  Metric:1
+          RX packets:265 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:265 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:1000
+          RX bytes:164568  TX bytes:164568
+
+wlp2s0    Link encap:Ethernet  HWaddr E4:CE:8F:59:D6:BF
+          inet addr:192.168.1.133  Bcast:192.168.1.255  Mask:255.255.255.0
+          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
+          RX packets:60084 errors:0 dropped:71 overruns:0 frame:0
+          TX packets:33232 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:1000
+          RX bytes:45965805  TX bytes:4905457
+
+@end example
+
+Bring the desired network interface (wired or wireless) up, where
+@code{nwif} is the network interface name.
+
+@example
+ifconfig -v nwif up
+@end example
+
+For wireless connection, follow the wireless setup.
+
+@menu
+* Wireless Setup::
+@end menu
+
+@node Wireless Setup
+@subsubsection Wireless Setup
+
+Create a configuration file using text editor, where @code{fname} is any
+desired name for file.
+
+@example
+nano fname.conf
+@end example
+
+Choose, type and save ONE of the following snippets, where ‘net’ is
+the network name, ‘pass’ is the password or passphrase and ‘uid’ is
+the user identity.
+
+For most private networks:
+
+@example
+network=@{
+  ssid="net"
+  key_mgmt=WPA-PSK
+  psk="pass"
+@}
+@end example
+
+(or)
+
+For most public networks:
+
+@example
+network=@{
+  ssid="net"
+  key_mgmt=NONE
+@}
+@end example
+
+(or)
+
+For most organizational networks:
+
+@example
+network=@{
+  ssid="net"
+  scan_ssid=1
+  key_mgmt=WPA-EAP
+  identity="uid"
+  password="pass"
+  eap=PEAP
+  phase1="peaplabel=0"
+  phase2="auth=MSCHAPV2"
+@}
+@end example
+
+Connect to the configured network.
+
+@example
+wpa_supplicant -B -c fname.conf -i nwif
+@end example
+
+Assign an IP address to the network interface.
+
+@example
+dhclient -v nwif
+@end example
+
+Obtain the device letter @code{/dev/sdX} in which you would like to deploy
+and install Guix System, where “X” is the device letter.
+
+@example
+lsblk --list
+@end example
+
+@example
+NAME  MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
+sda     8:0    0 223.6G  0 disk
+sda1    8:1    0     2M  0 part
+sda2    8:2    0   3.7G  0 part
+sda3    8:3    0 219.9G  0 part /
+zram0 251:0    0   512M  0 disk [SWAP]
+@end example
+
+Wipe the device (Ignore if the device is new).
+
+@example
+shred --verbose --random-source=/dev/urandom /dev/sdX
+@end example
+
+Load the device-mapper module in the current kernel.
+
+@example
+modprobe --verbose dm_mod
+@end example
+
+Partition the device. Follow the prompts. Just do, GPT --> New -->
+Write --> Quit; defaults will be set.
+
+@example
+cfdisk /dev/sdX
+@end example
+
+Obtain the partition number from the device, where “Y” is the
+partition number.
+
+@example
+lsblk --list
+@end example
+
+Encrypt the partition. Follow the prompts.
+
+@example
+cryptsetup --verbose --hash whirlpool --cipher serpent-xts-plain64 \
+--verify-passphrase --use-random --key-size 512 --iter-time 500 \
+luksFormat /dev/sdXY
+@end example
+
+Obtain and note down the UUID of the LUKS partition.
+
+@example
+cryptsetup --verbose luksUUID /dev/sdXY
+@end example
+
+Open the encrypted partition, where @code{luks-uuid} is the LUKS UUID,
+and @code{partname} is any desired name for the partition.
+
+@example
+cryptsetup --verbose
+luksOpen UUID=luks-uuid partname
+@end example
+
+Create a physical volume in the partition.
+
+@example
+pvcreate /dev/mapper/partname --verbose
+@end example
+
+Create a volume group in the physical volume, where @code{vgname} is any
+desired name for volume group.
+
+@example
+vgcreate vgname /dev/mapper/partname --verbose
+@end example
+
+Create logical volumes in the volume group; where "num" is the number
+for space in GB, and @code{lvnameroot} and @code{lvnamehome} are any
+desired names for root and home volumes respectively.
+
+@example
+lvcreate --extents 25%VG vgname --name lvnameroot --verbose
+lvcreate --extents 100%FREE vgname --name lvnamehome --verbose
+@end example
+
+Create filesystems on the logical-volumes, where @code{fsnameroot} and
+@code{fsnamehome} are any desired names for root and home filesystems
+respectively.
+
+@example
+mkfs.btrfs --metadata dup --label fsnameroot /dev/vgname/lvnameroot
+mkfs.btrfs --metadata dup --label fsnamehome /dev/vgname/lvnamehome
+@end example
+
+Mount the filesystems under the current system.
+
+@example
+mount --label fsnameroot --target /mnt --types btrfs --verbose
+mkdir --verbose /mnt/home && mount --label fsnamehome --target \
+/mnt/home --types btrfs --verbose
+@end example
+
+Create a swap file.
+
+@example
+dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress
+mkswap --verbose /mnt/swapfile
+@end example
+
+Make the swap file readable and writable only by root account.
+
+@example
+chmod --verbose 600 /mnt/swapfile
+@end example
+
+Activate the swap file.
+
+@example
+swapon --verbose /mnt/swapfile
+@end example
+
+Install packages on the mounted root filesystem.
+
+@example
+herd start cow-store /mnt
+@end example
+
+Create the system-wide configuration files directory.
+
+@example
+mkdir --verbose /mnt/etc
+@end example
+
+Create, edit and save the system configuration file by typing the
+following code snippet. WATCH-OUT for variables in the code snippet
+and replace them with the relevant values.
+
+@example
+nano /mnt/etc/config.scm
+@end example
+
+The content of config.scm is:
+
+@lisp
+(use-modules
+ (gnu)
+ (gnu system nss))
+
+(use-package-modules
+ certs
+ gnome
+ linux)
+
+(use-service-modules
+ desktop
+ xorg)
+
+(operating-system
+  (kernel linux-libre-lts)
+  (kernel-arguments
+   (append
+    (list
+    ;; this is needed to flash the libreboot ROM. After, you
+    ;; have flashed your rom, it is a good idea to remove
+    ;; iomem=relaxed from your kernel arguments
+     "iomem=relaxed")
+    %default-kernel-arguments))
+
+  (timezone "Zone/SubZone")
+  (locale "ab_XY.1234")
+  (name-service-switch %mdns-host-lookup-nss)
+
+  (bootloader
+   (bootloader-configuration
+    (bootloader
+     (bootloader
+      (inherit grub-bootloader)
+      (installer #~(const #t))))
+    (keyboard-layout keyboard-layout)))
+
+  (keyboard-layout
+   (keyboard-layout
+    "xy"
+    "altgr-intl"))
+
+  (host-name "hostname")
+
+  (mapped-devices
+   (list
+    (mapped-device
+     (source
+      (uuid "LUKS-UUID"))
+     (target "partname")
+     (type luks-device-mapping))
+    (mapped-device
+     (source "vgname")
+     (targets
+      (list
+       "vgname-lvnameroot"
+       "vgname-lvnamehome"))
+     (type lvm-device-mapping))))
+
+  (file-systems
+   (append
+    (list
+     (file-system
+       (type "btrfs")
+       (mount-point "/")
+       (device "/dev/mapper/VGNAME-LVNAMEROOT")
+       (flags '(no-atime))
+       (options "space_cache=v2")
+       (needed-for-boot? #t)
+       (dependencies mapped-devices))
+     (file-system
+       (type "btrfs")
+       (mount-point "/home")
+       (device "/dev/mapper/VGNAME-LVNAMEHOME")
+       (flags '(no-atime))
+       (options "space_cache=v2")
+       (dependencies mapped-devices)))
+    %base-file-systems))
+
+  (swap-devices
+   (list
+    "/swapfile"))
+
+  (users
+   (append
+    (list
+     (user-account
+      (name "USERNAME")
+      (comment "Full Name")
+      (group "users")
+      (supplementary-groups '("audio" "cdrom"
+                              "kvm" "lp" "netdev"
+                              "tape" "video"
+                              "wheel"))))
+    %base-user-accounts))
+
+  (packages
+   (append
+    (list
+     nss-certs)
+    %base-packages))
+
+  (services
+   (append
+    (list
+     (service gnome-desktop-service-type))
+    %desktop-services)))
+@end lisp
+
+Initialize new Guix System.
+
+@example
+guix system init /mnt/etc/config.scm /mnt
+@end example
+
+Reboot the device.
+
+@example
+reboot
+@end example
+
+@node Tweaking Libreboot's Grub Payload
+@subsection Tweaking Libreboot's Grub Payload
+@cindex grub payload
+
+On reboot, as soon as the Libreboot graphic art appears, press “C” to
+enter the command-line.
+
+Enter the following commands and respond to first command with the LUKS
+Key.
+
+@example
+cryptomount -u luks-uuid
+set root=(lvm/vgname-lvnameroot)
+@end example
+
+Upon Guix's GRUB menu, go with the default option.
+
+Enter the LUKS Key again, for kernel, as prompted.
+
+Upon login screen, login as "root" with password field empty.
+
+Open terminal.
+
+Set passkey for the "root" user. Follow the prompts.
+
+@example
+passwd root
+@end example
+
+Set passkey for the "username" user. Follow the prompts.
+
+@example
+passwd username
+@end example
+
+Install flashrom and wget.
+
+@example
+guix package –-install flashrom wget
+@end example
+
+Obtain the ROM chip's model and size. Look for the output line “Found
+[@dots{}] flash chip [@dots{}]”.
+
+@example
+flashrom --verbose --programmer internal
+@end example
+
+Download Libreboot ROM and utilities, where "YYYYMMDD" is the release
+date, @code{devmod} is the device model and "N" is the ROM chip size.
+
+@example
+wget --verbose 
https://rsync.libreboot.org/stable/YYYYMMDD/rom/grub/libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz
+wget --verbose 
https://rsync.libreboot.org/stable/YYYYMMDD/libreboot_rYYYYMMDD_util.tar.xz
+@end example
+
+Extract the downloaded files.
+@example
+tar --extract --file=libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz --verbose
+tar --extract --file=libreboot_rYYYYMMDD_util.tar.xz --verbose
+@end example
+
+Rename the directories of extracted files.
+
+@example
+mv --verbose "libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz" "libreboot_rom"
+mv --verbose "libreboot_rYYYYMMDD_util" "libreboot_util"
+@end example
+
+Copy the ROM image to the directory of cbfstool, where "kbdlo" is the
+keyboard layout and "arch" is the system architecture.
+
+@example
+cp libreboot_rom/devmod_Nmb_kbdlo_vesafb.rom 
libreboot_util/cbfstool/arch/libreboot.rom
+@end example
+
+Change directory to the directory of cbfstool.
+@example
+cd libreboot_util/cbfstool/arch/
+@end example
+
+Extract the GRUB configuration file from the image.
+
+@example
+./cbfstool libreboot.rom extract -n grub.cfg -f grub.cfg
+@end example
+
+Edit the GRUB configuration file and insert the following code snippet
+above the line @code{“menuentry 'Load Operating System [o]' --hotkey='o'
+--unrestricted @{ [...] @}”}.
+
+@example
+nano grub.cfg
+@end example
+
+Snippet:
+@example
+menuentry ‘Guix System (An advanced distribution of the GNU operating system) 
[g]’ --hotkey=’g’ --unrestricted
+@{
+cryptomount -u luks-uuid
+set root=(lvm/vgname-lvnameroot)
+configfile /boot/grub/grub.cfg
+@}
+@end example
+
+Remove the old GRUB configuration file from the ROM image.
+
+@example
+./cbfstool libreboot.rom remove -n grub.cfg
+@end example
+
+Insert the new GRUB configuration file into the ROM image.
+
+@example
+./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw
+@end example
+
+Move the ROM image to the directory of ich9gen.
+
+@example
+mv libreboot.rom ~/libreboot_util/ich9deblob/arch/libreboot.rom
+@end example
+
+Change directory to the directory of ich9gen.
+
+@example
+cd ~/libreboot_util/ich9deblob/arch/
+@end example
+
+Generate descriptor+GbE images with the MAC address, where "mac-addr"
+is the MAC address of the machine.
+
+@example
+ich9gen --macaddress mac-addr
+@end example
+
+Insert the descriptor+GbE image into the ROM image, where "N" is the
+ROM chip size.
+@example
+dd bs=12k conv=notrunc count=1 if=ich9fdgbe_Nm.bin of=libreboot.rom 
status=progress
+@end example
+
+Move the ROM image to the directory of flash.
+
+@example
+mv libreboot.rom ~/libreboot_util/libreboot.rom
+@end example
+
+Change directory to the directory of flash.
+
+@example
+cd ~/libreboot_util
+@end example
+
+Modify the shebang of flash script, from `#!/bin/bash` to `#!/bin/sh`.
+@example
+nano flash
+@end example
+
+Flash the ROM with the new image.
+@example
+./flash update libreboot.rom
+@end example
+
+(or)
+
+@example
+./flash forceupdate libreboot.rom
+@end example
+
+Reboot the device.
+@example
+reboot
+@end example
+
+@node Closing Thoughts
+@subsection Closing Thoughts
+
+Everything should be stream-lined from now. Upon Libreboot's GRUB
+menu, you can either press "G" or choose "Guix System (An advanced
+distribution of the GNU operating system) [g]".
+
+During the boot process, as prompted, you have to type LUKS key twice;
+once for Libreboot's GRUB and once more for Linux-Libre kernel.
+Retyping a passphrase is a minor annoyance, but it is a secure method of
+opening up your device.  There are methods that exist to only type the
+passphrase once, but none are currently integrated into Guix System.
+
+Generally, you will be using Libreboot's initial/default grub.cfg,
+whose Guix menu-entry invokes Guix's grub.cfg located at
+@code{/boot/grub/}. For trouble-shooting, you can also use Libreboot's
+@code{grubtest.cfg}, which hasn't been modified.
+
+Now that you have a working Guix System with full disk encryption, you
+may want to remove the @code{iomem=relaxed} from your
+@code{kernel-arguments}.  @code{iomem=relaxed} is needed to reflash your
+rom.  Since, most users will probably not flash their rom often, those
+users may wish to disable that feature:
+
+@lisp
+  ;; optionally remove this bit of code from your config.scm
+  (kernel-arguments
+   (append
+    (list
+    ;; this is needed to flash the libreboot ROM. After, you
+    ;; have flashed your rom, it is a good idea to remove
+    ;; iomem=relaxed from your kernel arguments
+     "iomem=relaxed")
+    %default-kernel-arguments))
+@end lisp
+
+That is it! You have now setup Guix System with Full Disk Encryption on
+your device powered by Libreboot. Enjoy!
+
+More information about Libreboot can be found at their official
+documentation: @uref{https://libreboot.org/docs/}.
+
+@node Special Thanks
+@subsection Special Thanks
+
+Thanks to Guix developer, Clement Lassieur (clement@@lassieur.org),
+for helping me with the Scheme code for the bootloader configuration.
+
+Thanks to Libreboot founder and developer, Leah Rowe
+(leah@@libreboot.org), for helping me with the understanding of
+Libreboot’s functionalities.
+
 @node Customizing a Window Manager
 @section Customizing a Window Manager
 @cindex wm
-- 
2.32.0