summaryrefslogtreecommitdiffstats
path: root/debian/README.gnupg-sc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
commitfd888e850cf413955483bfb993aeeea5ea611289 (patch)
tree6148fed3d1f30272c48403f4cdefa59c2b7e1513 /debian/README.gnupg-sc
parentAdding upstream version 2:2.6.1. (diff)
downloadcryptsetup-fd888e850cf413955483bfb993aeeea5ea611289.tar.xz
cryptsetup-fd888e850cf413955483bfb993aeeea5ea611289.zip
Adding debian version 2:2.6.1-4~deb12u2.debian/2%2.6.1-4_deb12u2debian
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'debian/README.gnupg-sc')
-rw-r--r--debian/README.gnupg-sc55
1 files changed, 55 insertions, 0 deletions
diff --git a/debian/README.gnupg-sc b/debian/README.gnupg-sc
new file mode 100644
index 0000000..edddfbd
--- /dev/null
+++ b/debian/README.gnupg-sc
@@ -0,0 +1,55 @@
+Using an OpenPGP smartcard for LUKS dm-crypt devices in Debian
+==============================================================
+
+The Debian cryptsetup package provides the keyscript `decrypt_gnupg-sc`
+for setups with a keyfile that is encrypted using an OpenPGP smartcard.
+
+The following example assumes that you store the encrypted keyfile in
+`/etc/keys/cryptkey.gpg`. LUKS device is `/dev/<luks_device>`.
+
+First, you'll have to create the keyfile and encrypt it with your key
+0xDEADBEEF:
+
+ dd if=/dev/random bs=1 count=256 | gpg --recipient 0xDEADBEEF \
+ --output /etc/keys/cryptkey.gpg --encrypt
+
+Next the LUKS device needs to be formated with the key. For that, the
+`decrypt_gnupg-sc` keyscript can be used:
+
+ /lib/cryptsetup/scripts/decrypt_gnupg-sc /etc/keys/cryptkey.gpg | \
+ cryptsetup --key-file=- luksFormat /dev/<luks_device>
+
+In order to unlock the encrypted LUKS device automatically during boot process,
+add the following to `/etc/crypttab`:
+
+ cdev1 /dev/<luks_device> /etc/keys/cryptkey.gpg luks,keyscript=decrypt_gnupg-sc
+
+In order to avoid data loss if the smartcard is damaged or lost, you may
+want to decrypt `/etc/keys/cryptkey.gpg` and store the plaintext in a safe
+place. Or alternatively, use another slot with your backup key:
+
+ cryptsetup luksAddKey /dev/<luks_device> /path/to/backup.key
+
+
+Decrypting the keyfile at initramfs stage
+-----------------------------------------
+
+If the device is to be unlocked at initramfs stage (such as for the root
+FS or the resume device), you need to copy the public part of the
+encryption key to `/etc/cryptsetup-initramfs/pubring.gpg`:
+
+ gpg --export 0xDEADBEEF >/etc/cryptsetup-initramfs/pubring.gpg
+
+Then the provided initramfs hooks should do all additionally required
+work for you when the initramfs is created or updated.
+
+Be warned though, that for such devices the OpenPGP encrypted key is copied
+to the initramfs by the initramfs cryptgnupg-sc hook. If you don't want this,
+you should take a look at the initramfs cryptgnupg-sc hook, which is located
+at `/usr/share/initramfs-tools/hooks/cryptgnupg-sc`.
+
+Moreover, note that unlocking at initramfs stage is currently not compatible
+with plymouth or other bootsplash, as a curses-based prompt is used for PIN
+entry.
+
+ -- Guilhem Moulin <guilhem@guilhem.org> Sun, 23 Sep 2018 03:28:31 +0200