diff options
Diffstat (limited to 'debian/README.keyctl')
| -rw-r--r-- | debian/README.keyctl | 106 |
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 |