From 8de64474ded169db55cdd34be9c020ed13c4e5e7 Mon Sep 17 00:00:00 2001
From: Johannes Stoelp <johannes.stoelp@gmail.com>
Date: Mon, 29 Aug 2022 22:27:28 +0200
Subject: cryptsetup: added notes + example to setup/use encrypted disks

---
 src/SUMMARY.md          |  1 +
 src/linux/README.md     |  1 +
 src/linux/cryptsetup.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 src/linux/cryptsetup.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 8f87671..d48a4b4 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -54,6 +54,7 @@
     - [systemd](./linux/systemd.md)
     - [coredump](./linux/coredump.md)
     - [ptrace_scope](./linux/ptrace_scope.md)
+    - [cryptsetup](./linux/cryptsetup.md)
 
 - [Network](./network/README.md)
     - [tcpdump](./network/tcpdump.md)
diff --git a/src/linux/README.md b/src/linux/README.md
index bd80476..b21cc55 100644
--- a/src/linux/README.md
+++ b/src/linux/README.md
@@ -3,3 +3,4 @@
 - [systemd](./systemd.md)
 - [coredump](./coredump.md)
 - [ptrace_scope](./ptrace_scope.md)
+- [cryptsetup](./cryptsetup.md)
diff --git a/src/linux/cryptsetup.md b/src/linux/cryptsetup.md
new file mode 100644
index 0000000..3388a7d
--- /dev/null
+++ b/src/linux/cryptsetup.md
@@ -0,0 +1,87 @@
+# [cryptsetup(8)][man-cryptsetup8]
+
+```text
+cryptsetup <action> [opts] <action args>
+
+action:
+    open <dev> <name> --type <type>    Open (decrypt) <dev> and map with <name>.
+                                       Mapped as /dev/mapper/<name>.
+                                       Type: {luks,plain,tcrypt,bitlk}
+    close <name>                       Close existing mapping <name>.
+    status <name>                      Print status for mapping <name>.
+
+    luksFormat <dev>                   Create new LUKS partition and set initial passphrase.
+                                       (Keyslot 0)
+    luksAddKey <dev>                   Add a new passphrase.
+    luksRemoveKey <dev>                Remove existing passphrase.
+    luksChangeKey <dev>                Change existing passphrase.
+    lusDump <dev>                      Dump LUKS header for device.
+```
+
+## Example: Create `LUKS` encrypted disk.
+
+For this example we use a file as backing storage and set it up as
+[loop(4)][man-loop4] device. The loop device can be replaced by any block
+device file.
+
+> Optional: Overwrite existing data on disk.\
+> `sudo dd if=/dev/urandom of=/dev/sdX bs=1M`
+
+First create the backing file and setup the loop device.
+
+```sh
+# Create 100MB file.
+dd if=/dev/zero of=blkfile bs=1M count=100
+
+# Attach file to first free (-f) loop device
+sudo losetup -f ./blkfile
+# List loop devices.
+sudo losetup -l
+# NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE              DIO LOG-SEC
+# /dev/loop0         0      0         0  0 /home/johannst/blkfile   0     512
+```
+
+Create a new LUKS partition and format new filesystem.
+
+```sh
+# Initialize LUKS partition and set initial passphrase.
+sudo cryptsetup luksFormat /dev/loop0
+
+file blkfile
+# blkfile: LUKS encrypted file, ver 2 [, , sha256] UUID: 8...
+
+# Open (decrypt) the LUKS device, it will be mapped under /dev/mapper/loop0.
+sudo cryptsetup open --type luks /dev/loop0 loop0
+
+# Format partition with new filesystem.
+sudo mkfs.vfat /dev/mapper/loop0
+
+lsblk -f
+# NAME        FSTYPE    FSVER LABEL  UUID  FSAVAIL FSUSE% MOUNTPOINTS
+# loop0       crypto_LU 2            8...
+# └─loop0     vfat      FAT16        D...    83.8M     0% /home/johannst/mnt
+
+# Close (re-encrypt) LUKS device.
+sudo cryptsetup close loop0
+```
+
+## Example: Using an existing LUKS device.
+
+```sh
+# Open (decrypt) the LUKS device, it will be mapped under /dev/mapper/loop0.
+sudo cryptsetup open --type luks /dev/loop0 loop0
+
+# Mount filesystem.
+sudo mount /dev/mapper/loop0 <mntpoint>
+
+# Use disk ...
+
+# Unmount filesystem.
+sudo umount <mntpoint>
+
+# Close (re-encrypt) LUKS device.
+sudo cryptsetup close loop0
+```
+
+[man-loop4]: https://man7.org/linux/man-pages/man4/loop.4.html
+[man-cryptsetup8]: https://www.man7.org/linux/man-pages/man8/cryptsetup.8.html
-- 
cgit v1.2.3