Na}{

File Content: `README.keyctl`

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

Name	Size	Permission
examples	---	0755
AUTHORS	137 bytes	0644
FAQ.gz	48990 bytes	0644
Keyring.txt	2724 bytes	0644
LUKS2-locking.txt	2711 bytes	0644
NEWS.Debian.gz	1057 bytes	0644
README.Debian.gz	5680 bytes	0644
README.debug	2731 bytes	0644
README.gnupg	1848 bytes	0644
README.gnupg-sc	2354 bytes	0644
README.keyctl	3583 bytes	0644
README.md.gz	2223 bytes	0644
README.opensc.gz	2219 bytes	0644
changelog.Debian.gz	2251 bytes	0644
copyright	9292 bytes	0644
v1.0.7-ReleaseNotes	2921 bytes	0644
v1.1.0-ReleaseNotes.gz	2275 bytes	0644
v1.1.1-ReleaseNotes	1796 bytes	0644
v1.1.2-ReleaseNotes	1594 bytes	0644
v1.1.3-ReleaseNotes	482 bytes	0644
v1.2.0-ReleaseNotes.gz	2124 bytes	0644
v1.3.0-ReleaseNotes.gz	2134 bytes	0644
v1.3.1-ReleaseNotes	421 bytes	0644
v1.4.0-ReleaseNotes.gz	2253 bytes	0644
v1.4.1-ReleaseNotes	889 bytes	0644
v1.4.2-ReleaseNotes	1630 bytes	0644
v1.4.3-ReleaseNotes	2359 bytes	0644
v1.5.0-ReleaseNotes.gz	3320 bytes	0644
v1.5.1-ReleaseNotes	1295 bytes	0644
v1.6.0-ReleaseNotes.gz	3818 bytes	0644
v1.6.1-ReleaseNotes	1041 bytes	0644
v1.6.2-ReleaseNotes	985 bytes	0644
v1.6.3-ReleaseNotes	1859 bytes	0644
v1.6.4-ReleaseNotes	2036 bytes	0644
v1.6.5-ReleaseNotes	2479 bytes	0644
v1.6.6-ReleaseNotes	1093 bytes	0644
v1.6.7-ReleaseNotes	3333 bytes	0644
v1.6.8-ReleaseNotes	2061 bytes	0644
v1.7.0-ReleaseNotes	3101 bytes	0644
v1.7.1-ReleaseNotes	1371 bytes	0644
v1.7.2-ReleaseNotes	1487 bytes	0644
v1.7.3-ReleaseNotes	811 bytes	0644
v1.7.4-ReleaseNotes	657 bytes	0644
v1.7.5-ReleaseNotes	833 bytes	0644
v2.0.0-ReleaseNotes.gz	9728 bytes	0644
v2.0.1-ReleaseNotes.gz	2226 bytes	0644
v2.0.2-ReleaseNotes.gz	1992 bytes	0644
v2.0.3-ReleaseNotes.gz	2448 bytes	0644
v2.0.4-ReleaseNotes.gz	2325 bytes	0644
v2.0.5-ReleaseNotes.gz	2068 bytes	0644
v2.0.6-ReleaseNotes.gz	1960 bytes	0644
v2.1.0-ReleaseNotes.gz	3484 bytes	0644
v2.2.0-ReleaseNotes.gz	4582 bytes	0644
v2.2.1-ReleaseNotes	1413 bytes	0644
v2.2.2-ReleaseNotes	2151 bytes	0644
v2.3.0-ReleaseNotes.gz	3250 bytes	0644
v2.3.1-ReleaseNotes	1770 bytes	0644
v2.3.2-ReleaseNotes	1499 bytes	0644
v2.3.3-ReleaseNotes	1396 bytes	0644
v2.3.4-ReleaseNotes.gz	2001 bytes	0644
v2.3.5-ReleaseNotes.gz	3129 bytes	0644
v2.3.6-ReleaseNotes	2316 bytes	0644
v2.4.0-ReleaseNotes.gz	4766 bytes	0644
v2.4.1-ReleaseNotes	1942 bytes	0644
v2.4.2-ReleaseNotes	1375 bytes	0644
v2.4.3-ReleaseNotes.gz	1996 bytes	0644

File Content: README.keyctl

File Content: `README.keyctl`