docs/v2.6.0-ReleaseNotes

   1 Cryptsetup 2.6.0 Release Notes
   2 ==============================
   3 Stable release with new features and bug fixes.
   4
   5 Changes since version 2.5.0
   6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7
   8 * Introduce support for handling macOS FileVault2 devices (FVAULT2).
   9
  10   Cryptsetup now supports the mapping of FileVault2 full-disk encryption
  11   by Apple for the macOS operating system using a native Linux kernel.
  12   You can open an existing USB FileVault portable device and (with
  13   the hfsplus filesystem driver) access the native data read/write.
  14
  15   Cryptsetup supports only (legacy) FileVault2 based on Core Storage
  16   and HFS+ filesystem (introduced in MacOS X 10.7 Lion).
  17   It does NOT support the new version of FileVault based on the APFS
  18   filesystem used in recent macOS versions.
  19
  20   Header formatting and changes are not supported; cryptsetup never
  21   changes the metadata on the device.
  22
  23   FVAULT2 extension requires kernel userspace crypto API and kernel
  24   driver for HFS+ (hfsplus) filesystem (available on most systems today).
  25
  26   Example of using FileVault2 formatted USB device:
  27
  28   A typical encrypted device contains three partitions; the FileVault
  29   encrypted partition is here sda2:
  30
  31   $ lsblk -o NAME,FSTYPE,LABEL /dev/sda
  32     NAME   FSTYPE  LABEL
  33     sda
  34     |-sda1 vfat    EFI
  35     |-sda2
  36     `-sda3 hfsplus Boot OS X
  37
  38   Note: blkid does not recognize FileVault2 format yet.
  39
  40   To dump metadata information about the device, you can use
  41   the fvault2Dump command:
  42
  43   $ cryptsetup fvault2Dump /dev/sda2
  44     Header information for FVAULT2 device /dev/sda2.
  45     Physical volume UUID:   6f353c05-daae-4e76-a0ee-6a9569a22d81
  46     Family UUID:            f82cceb0-a788-4815-945a-53d57fcd55a8
  47     Logical volume offset:  67108864 [bytes]
  48     Logical volume size:    3288334336 [bytes]
  49     Cipher:                 aes
  50     Cipher mode:            xts-plain64
  51     PBKDF2 iterations:      97962
  52     PBKDF2 salt:            173a4ec7447662ec79ca7a47df6c2a01
  53
  54  To activate the device, use open --type fvault2 option:
  55
  56  $ cryptsetup open --type fvault2 /dev/sda2 test
  57    Enter passphrase for /dev/sda2: ...
  58
  59  And check the status of the active device:
  60
  61  $ cryptsetup status test
  62    /dev/mapper/test is active.
  63    type:    FVAULT2
  64    cipher:  aes-xts-plain64
  65    keysize: 256 bits
  66    key location: dm-crypt
  67    device:  /dev/sda2
  68    sector size:  512
  69    offset:  131072 sectors
  70    size:    6422528 sectors
  71    mode:    read/write
  72
  73  Now, if the kernel contains hfsplus filesystem driver, you can mount
  74  decrypted content:
  75
  76  $ mount /dev/mapper/test /mnt/test
  77
  78  For more info about implementation, please refer to the master thesis
  79  by Pavel Tobias, which was the source for this extension.
  80  https://is.muni.cz/th/p0aok/?lang=en
  81
  82 * libcryptsetup: no longer use global memory locking through mlockall()
  83
  84   For many years, libcryptsetup locked all memory (including dependent
  85   library address space) to prevent swapping sensitive content outside
  86   of RAM.
  87
  88   This strategy no longer works as the locking of basic libraries exceeds
  89   the memory locking limit if running as a non-root user.
  90
  91   Libcryptsetup now locks only memory ranges containing sensitive
  92   material (keys) through crypt_safe_alloc() calls.
  93
  94   This change solves many reported mysterious problems of unexpected
  95   failures. If the initial lock was still under the limit and succeeded,
  96   some following memory allocation could fail later as it exceeded
  97   the locking limit. If the initial locking fails,  memory locking
  98   was quietly ignored completely.
  99
 100   The whole crypt_memory_lock() API call is deprecated; it no longer
 101   calls memlockall().
 102
 103 * libcryptsetup: process priority is increased only for key derivation
 104   (PBKDF) calls.
 105
 106   Increasing priority was tight to memory locking and works only if
 107   running under superuser.
 108   Only PBKDF calls and benchmarking now increase the process priority.
 109
 110 * Add new LUKS keyslot context handling functions and API.
 111
 112   In practice, the luksAddKey action does two operations.
 113   It unlocks the existing device volume key and stores the unlocked
 114   volume key in a new keyslot.
 115   Previously the options were limited to key files and passphrases.
 116
 117   Newly available methods (keyslot contexts) are passphrase, keyfile,
 118   key (binary representation), and LUKS2 token.
 119
 120   To unlock a keyslot user may:
 121     - provide existing passphrase via interactive prompt (default method)
 122     - use --key-file option to provide a file with a valid passphrase
 123     - provide volume key directly via --volume-key-file
 124     - unlock keyslot via all available LUKS2 tokens by --token-only
 125     - unlock keyslot via specific token with --token-id
 126     - unlock keyslot via specific token type by --token-type
 127
 128   To provide the passphrase for a new keyslot, a user may:
 129     - provide existing passphrase via interactive prompt (default method)
 130     - use --new-keyfile to read the passphrase from the file
 131     - use --new-token-id to select LUKS2 token to get passphrase
 132       for new keyslot. The new keyslot is assigned to the selected token
 133       id if the operation is successful.
 134
 135 * The volume key may now be extracted using a passphrase, keyfile, or
 136   token. For LUKS devices, it also returns the volume key after
 137   a successful crypt_format call.
 138
 139 * Fix --disable-luks2-reencryption configuration option.
 140
 141 * cryptsetup: Print a better error message and warning if the format
 142   produces an image without space available for data.
 143
 144   Activation now fails early with a more descriptive message.
 145
 146 * Print error if anti-forensic LUKS2 hash setting is not available.
 147   If the specified hash was not available, activation quietly failed.
 148
 149 * Fix internal crypt segment compare routine if the user
 150   specified cipher in kernel format (capi: prefix).
 151
 152 * cryptsetup: Add token unassign action.
 153
 154   This action allows removing token binding on specific keyslot.
 155
 156 * veritysetup: add support for --use-tasklets option.
 157
 158   This option sets try_verify_in_tasklet kernel dm-verity option
 159   (available since Linux kernel 6.0) to allow some performance
 160   improvement on specific systems.
 161
 162 * Provide pkgconfig Require.private settings.
 163
 164   While we do not completely provide static build on udev systems,
 165   it helps produce statically linked binaries in certain situations.
 166
 167 * Always update automake library files if autogen.sh is run.
 168
 169   For several releases, we distributed older automake scripts by mistake.
 170
 171 * reencryption: Fix user defined moved segment size in LUKS2 decryption.
 172
 173   The --hotzone-size argument was ignored in cases where the actual data
 174   size was less than the original LUKS2 data offset.
 175
 176 * Delegate FIPS mode detection to configured crypto backend.
 177   System FIPS mode check no longer depends on /etc/system-fips file.
 178
 179 * tests: externally provided systemd plugin is now optionally compiled
 180   from systemd git and tested with cryptsetup
 181
 182 * tests: initial integration to OSS-fuzz project with basic crypt_load()
 183   test for LUKS2 and JSON mutated fuzzing.
 184
 185   For more info, see README in tests/fuzz directory.
 186
 187 * Update documentation, including FAQ and man pages.
 188
 189 Libcryptsetup API extensions
 190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 191 The libcryptsetup API is backward compatible with existing symbols.
 192
 193 New symbols:
 194   crypt_keyslot_context_init_by_passphrase
 195   crypt_keyslot_context_init_by_keyfile
 196   crypt_keyslot_context_init_by_token
 197   crypt_keyslot_context_init_by_volume_key
 198   crypt_keyslot_context_get_error
 199   crypt_keyslot_context_set_pin
 200   crypt_keyslot_context_get_type
 201   crypt_keyslot_context_free
 202   crypt_keyslot_add_by_keyslot_context
 203   crypt_volume_key_get_by_keyslot_context
 204
 205 New defines:
 206   CRYPT_FVAULT2 "FVAULT2" (FileVault2 compatible mode)
 207
 208 Keyslot context types:
 209   CRYPT_KC_TYPE_PASSPHRASE
 210   CRYPT_KC_TYPE_KEYFILE
 211   CRYPT_KC_TYPE_TOKEN
 212   CRYPT_KC_TYPE_KEY
 213
 214   CRYPT_ACTIVATE_TASKLETS (dm-verity: use tasklets activation flag)
 215
 216 WARNING!
 217 ~~~~~~~~
 218 The next version of cryptsetup will change the encryption mode and key
 219 derivation option for the PLAIN format.
 220
 221 This change will cause backward incompatibility.
 222 For this reason, the user will have to specify the exact parameters
 223 for cipher, key size, and key derivation parameters for plain format.
 224
 225 The default encryption mode will be AES-XTS with 512bit key (AES-256).
 226 The CBC mode is no longer considered the best default, as it allows easy
 227 bit-flipped ciphertext modification attacks and performance problems.
 228
 229 For the passphrase hashing in plain mode, the encryption key is directly
 230 derived through iterative hashing from a user-provided passphrase
 231 (except a keyfile that is not hashed).
 232
 233 The default hash is RIPEMD160, which is no longer the best default
 234 option. The exact change will be yet discussed but should include
 235 the possibility of using a password-based key derivation function
 236 instead of iterative hashing.