Adding debian version 2:2.3.7-1+deb11u1.debian/2%2.3.7-1+deb11u1debian

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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