"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/Keyring.txt" (24 Jul 2021, 2724 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 Integration with kernel keyring service
    2 ---------------------------------------
    3 
    4 We have two different use cases for kernel keyring service:
    5 
    6 I) Volume keys
    7 
    8 Since upstream kernel 4.10 dm-crypt device mapper target allows loading volume
    9 key (VK) in kernel keyring service. The key offloaded in kernel keyring service
   10 is only referenced (by key description) in dm-crypt target and the VK is therefore
   11 no longer stored directly in dm-crypt target. Starting with cryptsetup 2.0 we
   12 load VK in kernel keyring by default for LUKSv2 devices (when dm-crypt with the
   13 feature is available).
   14 
   15 Currently cryptsetup loads VK in 'logon' type kernel key so that VK is passed in
   16 the kernel and can't be read from userspace afterward. Also cryptsetup loads VK in
   17 thread keyring (before passing the reference to dm-crypt target) so that the key
   18 lifetime is directly bound to the process that performs the dm-crypt setup. When
   19 cryptsetup process exits (for whatever reason) the key gets unlinked in kernel
   20 automatically. In summary, the key description visible in dm-crypt table line is
   21 a reference to VK that usually no longer exists in kernel keyring service if you
   22 used cryptsetup to for device activation.
   23 
   24 Using this feature dm-crypt no longer maintains a direct key copy (but there's
   25 always at least one copy in kernel crypto layer).
   26 
   27 II) Keyslot passphrase
   28 The second use case for kernel keyring is to allow cryptsetup reading the keyslot
   29 passphrase stored in kernel keyring instead. The user may load passphrase in kernel
   30 keyring and notify cryptsetup to read it from there later. Currently, cryptsetup
   31 cli supports kernel keyring for passphrase only via LUKS2 internal token
   32 (luks2-keyring). Library also provides a general method for device activation by
   33 reading passphrase from keyring: crypt_activate_by_keyring(). The key type
   34 for use case II) must always be 'user' since we need to read the actual key
   35 data from userspace unlike with VK in I). Ability to read keyslot passphrase
   36 from kernel keyring also allows easily auto-activate LUKS2 devices.
   37 
   38 Simple example how to use kernel keyring for keyslot passphrase:
   39 
   40 1) create LUKS2 keyring token for keyslot 0 (in LUKS2 device/image)
   41 cryptsetup token add --key-description my:key -S 0 /dev/device
   42 
   43 2) Load keyslot passphrase in user keyring
   44 read -s -p "Keyslot passphrase: "; echo -n $REPLY | keyctl padd user my:key @u
   45 
   46 3) Activate device using passphrase stored in kernel keyring
   47 cryptsetup open /dev/device my_unlocked_device
   48 
   49 4a) unlink the key when no longer needed by
   50 keyctl unlink %user:my:key @u
   51 
   52 4b) or revoke it immediately by
   53 keyctl revoke %user:my:key
   54 
   55 If cryptsetup asks for passphrase in step 3) something went wrong with keyring
   56 activation. See --debug output then.