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/LUKS2-locking.txt (2711B)

LUKS2 device locking overview
=============================

Why
~~~

LUKS2 format keeps two identical copies of metadata stored consecutively
at the head of metadata device (file or bdev). The metadata
area (both copies) must be updated in a single atomic operation to avoid
header corruption during concurrent write.

While with LUKS1 users may have clear knowledge of when a LUKS header is
being updated (written to) or when it's being read solely the need for
locking with legacy format was not so obvious as it is with the LUKSv2 format.

With LUKS2 the boundary between read-only and read-write is blurry and what
used to be the exclusively read-only operation (i.e., cryptsetup open command) may
easily become read-update operation silently without user's knowledge.
Major feature of LUKS2 format is resilience against accidental
corruption of metadata (i.e., partial header overwrite by parted or cfdisk
while creating partition on mistaken block device).
Such header corruption is detected early on header read and auto-recovery
procedure takes place (the corrupted header with checksum mismatch is being
replaced by the secondary one if that one is intact).
On current Linux systems header load operation may be triggered without user
direct intervention for example by udev rule or from systemd service.
Such clash of header read and auto-recovery procedure could have severe
consequences with the worst case of having LUKS2 device unaccessible or being
broken beyond repair.

The whole locking of LUKSv2 device headers split into two categories depending
what backend the header is stored on:

I) block device
~~~~~~~~~~~~~~~

We perform flock() on file descriptors of files stored in a private
directory (by default /run/lock/cryptsetup). The file name is derived
from major:minor couple of affected block device. Note we recommend
that access to private locking directory is supposed to be limited
to superuser only. For this method to work the distribution needs
to install the locking directory with appropriate access rights.

II) regular files
~~~~~~~~~~~~~~~~~

First notable difference between headers stored in a file
vs. headers stored in a block device is that headers in a file may be
manipulated by the regular user unlike headers on block devices. Therefore
we perform flock() protection on file with the luks2 header directly.

Limitations
~~~~~~~~~~~

a) In general, the locking model provides serialization of I/Os targeting
the header only. It means the header is always written or read at once
while locking is enabled.
We do not suppress any other negative effect that two or more concurrent
writers of the same header may cause.

b) The locking is not cluster aware in any way.

cmd: