FM / cryptsetup

/usr/share/doc/cryptsetup

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

Edit: /usr/share/doc/cryptsetup/README.keyctl (3583B)

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

cmd: