summaryrefslogtreecommitdiffstats
path: root/debian/README.keyctl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--debian/README.keyctl106
1 files changed, 106 insertions, 0 deletions
diff --git a/debian/README.keyctl b/debian/README.keyctl
new file mode 100644
index 0000000..6585c8b
--- /dev/null
+++ b/debian/README.keyctl
@@ -0,0 +1,106 @@
+decrypt_keyctl
+==============
+
+A passphrase caching script to be used in `/etc/crypttab` on Debian and Ubuntu.
+When there are multiple cryptsetup (either plain or LUKS) volumes with the same
+passphrase, it is an unnecessary task to input the passphrase more than once.
+
+Just add this script as keyscript to your `/etc/crypttab` and it will cache the
+passphrase of all crypttab entries with the same identifier.
+
+Either copy decrypt_keyctl into the default search path for keyscripts from
+cryptsetup /lib/cryptdisks/scripts/. So you can just write
+`keyscript=decrypt_keyctl` in `/etc/crypttab`, or use a random path of your
+choice and give the full path e.g `keyscript=/sbin/decrypt_keyctl`.
+
+
+Requirements
+------------
+
+* Debian cryptsetup package with `/etc/crypttab` handling and keyscript option
+ * Tested with Debian Lenny, Squeeze and Sid
+* Installed and working keyutils package (`keyctl`)
+ * Needs `CONFIG_KEYS=y` in your kernel configuration
+
+What For?
+---------
+
+In old (pre 2.6.38) kernels, dm-crypt used to be single threaded. Thus every
+dm-crypt mapping only used a single core for crypto operations. To use the full
+power of your many-core processor it is was necessary to split the dm-crypt
+device. For Linux software raid arrays the easiest segmentation was to just put
+the dm-crypt layer below the software raid layer.
+
+But with a 5 disk raid5 it is a rather daunting task to input the passphrase
+five times. This is what this keyscripts solve for you.
+
+Usage
+-----
+
+Best shown by example:
+
+* 5 disks
+* Linux software raid5
+
+Layer:
+
+ sda sdb sdc ... sde
+ +-----------+ +-----------+
+ | LUKS | | LUKS |
+ | +-------+ | | +-------+ |
+ | | RAID5 | | | | RAID5 | |
+ | | ... | | | | ... | |
+
+Crypttab Entries:
+
+ <target> <source> <keyfile> <options>
+ sda_crypt /dev/sda2 main_data_raid luks,discard,keyscript=decrypt_keyctl
+ sdb_crypt /dev/sdb2 main_data_raid luks,discard,keyscript=decrypt_keyctl
+ ...
+ sde_crypt /dev/sde2 main_data_raid luks,discard,keyscript=decrypt_keyctl
+
+
+How does it work
+----------------
+
+Crypttab Interface:
+
+A keyscript is added to options including a keyfile definition as third
+parameter in the crypttab file. The keyscript is called with the keyfile as the
+first and only parameter. Additionally there are a few environment variables
+set but currently are not used by this keyscript (man 5 crypttab for exact
+description).
+
+Keyscript:
+
+`decrypt_keyctl` uses the Linux kernel keyring facility to securely cache
+passphrases between multiple invocations.
+The keyfile parameter from crypttab is used to find the same passphrase
+between multiple invocations. The term used to described the key in the user
+keyring is `cryptsetup:$CRYPTTAB_KEY`, unless `$CRYPTTAB_KEY` is empty
+or has the special value `none`, in which case the description is merely
+`cryptsetup` (thus allowing compatibility with other tools like gdm and
+systemd-ask-password(1).)
+
+Currently the cache timeout is 60 seconds and not configurable (please report a
+bug if it is too low for you).
+
+
+Problems
+--------
+
+Passphrase is piped between processes and could end up in unsecured memory,
+thus later swapped to disk! => Use of cryptoswap recommend!
+
+
+Hints
+-----
+
+To remove all traces of this keyscript you may want to cleanup the keyring
+completely with the following command afterwards:
+
+ sudo keyctl clear @u
+
+ -- Jonas Meurer <jonas@freesources.org> Mon, 27 Sep 2010 14:01:35 +0000
+
+ -- Guilhem Moulin <guilhem@debian.org> Tue, 25 Dec 2018 01:12:24 +0100