docs/v2.3.0-ReleaseNotes

   1 Cryptsetup 2.3.0 Release Notes
   2 ==============================
   3 Stable release with new experimental features and bug fixes.
   4
   5 Cryptsetup 2.3 version introduces support for BitLocker-compatible
   6 devices (BITLK format). This format is used in Windows systems,
   7 and in combination with a filesystem driver, cryptsetup now provides
   8 native read-write access to BitLocker Full Disk Encryption devices.
   9
  10 The BITLK implementation is based on publicly available information
  11 and it is an independent and opensource implementation that allows
  12 to access this proprietary disk encryption.
  13
  14 Changes since version 2.2.2
  15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  16
  17 * BITLK (Windows BitLocker compatible) device access
  18
  19   BITLK userspace implementation is based on the master thesis and code
  20   provided by Vojtech Trefny. Also, thanks to other opensource projects
  21   like libbde (that provide alternative approach to decode this format)
  22   we were able to verify cryptsetup implementation.
  23
  24   NOTE: Support for the BITLK device is EXPERIMENTAL and will require
  25   a lot of testing. If you get some error message (mainly unsupported
  26   metadata in the on-disk header), please help us by submitting an issue
  27   to cryptsetup project, so we can fix it. Thank you!
  28
  29   Cryptsetup supports BITLK activation through passphrase or recovery
  30   passphrase for existing devices (BitLocker and Bitlocker to Go).
  31
  32   Activation through TPM, SmartCard, or any other key protector
  33   is not supported. And in some situations, mainly for TPM bind to some
  34   PCR registers, it could be even impossible on Linux in the future.
  35
  36   All metadata (key protectors) are handled read-only, cryptsetup cannot
  37   create or modify them. Except for old devices (created in old Vista
  38   systems), all format variants should be recognized.
  39
  40   Data devices can be activated read-write (followed by mounting through
  41   the proper filesystem driver). To access filesystem on the decrypted device
  42   you need properly installed driver (vfat, NTFS or exFAT).
  43
  44   Foe AES-XTS, activation is supported on all recent Linux kernels.
  45
  46   For older AES-CBC encryption, Linux Kernel version 5.3 is required
  47   (support for special IV variant); for AES-CBC with Elephant diffuser,
  48   Linux Kernel 5.6 is required.
  49
  50   Please note that CBC variants are legacy, and we provide it only
  51   for backward compatibility (to be able to access old drives).
  52
  53   Cryptsetup command now supports the new "bitlk" format and implement dump,
  54   open, status, and close actions.
  55
  56   To activate a BITLK device, use
  57
  58     # cryptsetup open --type bitlk <device> <name>
  59       or with alias
  60     # cryptsetup bitlkOpen <device> <name>
  61
  62   Then with properly installed fs driver (usually NTFS, vfat or exFAT),
  63   you can mount the plaintext device /dev/mapper<name> device as a common
  64   filesystem.
  65
  66  To print metadata information about BITLK device, use
  67    # crypotsetup bitlkDump <device>
  68
  69  To print information about the active device, use
  70    # cryptsetup status <name>
  71
  72  Example (activation of disk image):
  73  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74
  75   # Recent blkid recognizes BitLocker device,just to verity
  76   # blkid bitlocker_xts_ntfs.img
  77     bitlocker_xts_ntfs.img: TYPE="BitLocker"
  78
  79   # Print visible metadata information (on-disk, form the image)
  80   # cryptsetup bitlkDump bitlocker_xts_ntfs.img
  81     Info for BITLK device bitlocker_xts_ntfs.img.
  82     Version:        2
  83     GUID:           ...
  84     Created:        Wed Oct 23 17:38:15 2019
  85     Description:    DESKTOP-xxxxxxx E: 23.10.2019
  86     Cipher name:    aes
  87     Cipher mode:    xts-plain64
  88     Cipher key:     128 bits
  89
  90     Keyslots:
  91      0: VMK
  92             GUID:           ...
  93             Protection:     VMK protected with passphrase
  94             Salt:           ...
  95             Key data size:  44 [bytes]
  96      1: VMK
  97             GUID:           ...
  98             Protection:     VMK protected with recovery passphrase
  99             Salt:           ...
 100             Key data size:  44 [bytes]
 101      2: FVEK
 102            Key data size:  44 [bytes]
 103
 104   # Activation (recovery passphrase works the same as password)
 105   # cryptsetup bitlkOpen bitlocker_xts_ntfs.img test -v
 106     Enter passphrase for bitlocker_xts_ntfs.img:
 107     Command successful.
 108
 109   # Information about the active device
 110   # cryptsetup status test
 111     /dev/mapper/test is active.
 112     type:    BITLK
 113     cipher:  aes-xts-plain64
 114     keysize: 128 bits
 115     ...
 116
 117   # Plaintext device should now contain decrypted NTFS filesystem
 118   # blkid /dev/mapper/test
 119     /dev/mapper/test: UUID="..." TYPE="ntfs"
 120
 121   # And can be mounted
 122   # mount /dev/mapper/test /mnt/tst
 123
 124   # Deactivation
 125   # umount /mnt/tst
 126   # cryptsetup close test
 127
 128 * Veritysetup now supports activation with additional PKCS7 signature
 129   of root hash through --root-hash-signature option.
 130   The signature uses an in-kernel trusted key to validate the signature
 131   of the root hash during activation. This option requires Linux kernel
 132   5.4 with DM_VERITY_VERIFY_ROOTHASH_SIG option.
 133
 134   Verity devices activated with signature now has a special flag
 135   (with signature) active in device status (veritysetup status <name>).
 136
 137   Usage:
 138   # veritysetup open <data_device> name <hash_device> <root_hash> \
 139     --root-hash-signature=<roothash_p7_sig_file>
 140
 141 * Integritysetup now calculates hash integrity size according to algorithm
 142   instead of requiring an explicit tag size.
 143
 144   Previously, when integritysetup formats a device with hash or
 145   HMAC integrity checksums, it required explicitly tag size entry from
 146   a user (or used default value).
 147   This led to confusion and unexpected shortened tag sizes.
 148
 149   Now, libcryptsetup calculates tag size according to real hash output.
 150   Tag size can also be specified, then it warns if these values differ.
 151
 152 * Integritysetup now supports fixed padding for dm-integrity devices.
 153
 154   There was an in-kernel bug that wasted a lot of space when using metadata
 155   areas for integrity-protected devices if a larger sector size than
 156   512 bytes was used.
 157   This problem affects both stand-alone dm-integrity and also LUKS2 with
 158   authenticated encryption and larger sector size.
 159
 160   The new extension to dm-integrity superblock is needed, so devices
 161   with the new optimal padding cannot be activated on older systems.
 162
 163   Integritysetup/Cryptsetup will use new padding automatically if it
 164   detects the proper kernel. To create a compatible device with
 165   the old padding, use --integrity-legacy-padding option.
 166
 167 * A lot of fixes to online LUKS2 reecryption.
 168
 169 * Add crypt_resume_by_volume_key() function to libcryptsetup.
 170   If a user has a volume key available, the LUKS device can be resumed
 171   directly using the provided volume key.
 172   No keyslot derivation is needed, only the key digest is checked.
 173
 174 * Implement active device suspend info.
 175   Add CRYPT_ACTIVATE_SUSPENDED bit to crypt_get_active_device() flags
 176   that informs the caller that device is suspended (luksSuspend).
 177
 178 * Allow --test-passphrase for a detached header.
 179   Before this fix, we required a data device specified on the command
 180   line even though it was not necessary for the passphrase check.
 181
 182 * Allow --key-file option in legacy offline encryption.
 183   The option was ignored for LUKS1 encryption initialization.
 184
 185 * Export memory safe functions.
 186   To make developing of some extensions simpler, we now export
 187   functions to handle memory with proper wipe on deallocation.
 188
 189 * Fail crypt_keyslot_get_pbkdf for inactive LUKS1 keyslot.
 190
 191 Libcryptsetup API extensions
 192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 193 The libcryptsetup API is backward compatible for existing symbols.
 194
 195 New symbols
 196  crypt_set_compatibility
 197  crypt_get_compatibility;
 198  crypt_resume_by_volume_key;
 199  crypt_activate_by_signed_key;
 200  crypt_safe_alloc;
 201  crypt_safe_realloc;
 202  crypt_safe_free;
 203  crypt_safe_memzero;
 204
 205 New defines introduced :
 206   CRYPT_BITLK "BITLK" - BITLK (BitLocker-compatible mode
 207   CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING - dm-integrity legacy padding
 208   CRYPT_VERITY_ROOT_HASH_SIGNATURE - dm-verity root hash signature
 209   CRYPT_ACTIVATE_SUSPENDED - device suspended info flag