"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/LUKS2-locking.txt" (24 Jul 2021, 2711 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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.