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/Keyring.txt (2724B)

Integration with kernel keyring service
---------------------------------------

We have two different use cases for kernel keyring service:

I) Volume keys

Since upstream kernel 4.10 dm-crypt device mapper target allows loading volume
key (VK) in kernel keyring service. The key offloaded in kernel keyring service
is only referenced (by key description) in dm-crypt target and the VK is therefore
no longer stored directly in dm-crypt target. Starting with cryptsetup 2.0 we
load VK in kernel keyring by default for LUKSv2 devices (when dm-crypt with the
feature is available).

Currently cryptsetup loads VK in 'logon' type kernel key so that VK is passed in
the kernel and can't be read from userspace afterward. Also cryptsetup loads VK in
thread keyring (before passing the reference to dm-crypt target) so that the key
lifetime is directly bound to the process that performs the dm-crypt setup. When
cryptsetup process exits (for whatever reason) the key gets unlinked in kernel
automatically. In summary, the key description visible in dm-crypt table line is
a reference to VK that usually no longer exists in kernel keyring service if you
used cryptsetup to for device activation.

Using this feature dm-crypt no longer maintains a direct key copy (but there's
always at least one copy in kernel crypto layer).

II) Keyslot passphrase
The second use case for kernel keyring is to allow cryptsetup reading the keyslot
passphrase stored in kernel keyring instead. The user may load passphrase in kernel
keyring and notify cryptsetup to read it from there later. Currently, cryptsetup
cli supports kernel keyring for passphrase only via LUKS2 internal token
(luks2-keyring). Library also provides a general method for device activation by
reading passphrase from keyring: crypt_activate_by_keyring(). The key type
for use case II) must always be 'user' since we need to read the actual key
data from userspace unlike with VK in I). Ability to read keyslot passphrase
from kernel keyring also allows easily auto-activate LUKS2 devices.

Simple example how to use kernel keyring for keyslot passphrase:

1) create LUKS2 keyring token for keyslot 0 (in LUKS2 device/image)
cryptsetup token add --key-description my:key -S 0 /dev/device

2) Load keyslot passphrase in user keyring
read -s -p "Keyslot passphrase: "; echo -n $REPLY | keyctl padd user my:key @u

3) Activate device using passphrase stored in kernel keyring
cryptsetup open /dev/device my_unlocked_device

4a) unlink the key when no longer needed by
keyctl unlink %user:my:key @u

4b) or revoke it immediately by
keyctl revoke %user:my:key

If cryptsetup asks for passphrase in step 3) something went wrong with keyring
activation. See --debug output then.

cmd: