docs/LUKS2-locking.txt

   1 LUKS2 device locking overview
   2 =============================
   3
   4 Why
   5 ~~~
   6
   7 LUKS2 format keeps two identical copies of metadata stored consecutively
   8 at the head of metadata device (file or bdev). The metadata
   9 area (both copies) must be updated in a single atomic operation to avoid
  10 header corruption during concurrent write.
  11
  12 While with LUKS1 users may have clear knowledge of when a LUKS header is
  13 being updated (written to) or when it's being read solely the need for
  14 locking with legacy format was not so obvious as it is with the LUKSv2 format.
  15
  16 With LUKS2 the boundary between read-only and read-write is blurry and what
  17 used to be the exclusively read-only operation (i.e., cryptsetup open command) may
  18 easily become read-update operation silently without user's knowledge.
  19 Major feature of LUKS2 format is resilience against accidental
  20 corruption of metadata (i.e., partial header overwrite by parted or cfdisk
  21 while creating partition on mistaken block device).
  22 Such header corruption is detected early on header read and auto-recovery
  23 procedure takes place (the corrupted header with checksum mismatch is being
  24 replaced by the secondary one if that one is intact).
  25 On current Linux systems header load operation may be triggered without user
  26 direct intervention for example by udev rule or from systemd service.
  27 Such clash of header read and auto-recovery procedure could have severe
  28 consequences with the worst case of having LUKS2 device unaccessible or being
  29 broken beyond repair.
  30
  31 The whole locking of LUKSv2 device headers split into two categories depending
  32 what backend the header is stored on:
  33
  34 I) block device
  35 ~~~~~~~~~~~~~~~
  36
  37 We perform flock() on file descriptors of files stored in a private
  38 directory (by default /run/lock/cryptsetup). The file name is derived
  39 from major:minor couple of affected block device. Note we recommend
  40 that access to private locking directory is supposed to be limited
  41 to superuser only. For this method to work the distribution needs
  42 to install the locking directory with appropriate access rights.
  43
  44 II) regular files
  45 ~~~~~~~~~~~~~~~~~
  46
  47 First notable difference between headers stored in a file
  48 vs. headers stored in a block device is that headers in a file may be
  49 manipulated by the regular user unlike headers on block devices. Therefore
  50 we perform flock() protection on file with the luks2 header directly.
  51
  52 Limitations
  53 ~~~~~~~~~~~
  54
  55 a) In general, the locking model provides serialization of I/Os targeting
  56 the header only. It means the header is always written or read at once
  57 while locking is enabled.
  58 We do not suppress any other negative effect that two or more concurrent
  59 writers of the same header may cause.
  60
  61 b) The locking is not cluster aware in any way.