cryptsetup: added notes + example to setup/use encrypted disks

2 files changed, 88 insertions, 0 deletions

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