docs/v2.5.0-ReleaseNotes

   1 Cryptsetup 2.5.0 Release Notes
   2 ==============================
   3 Stable release with new features and bug fixes.
   4
   5 Changes since version 2.4.3
   6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7
   8 * Split manual pages into per-action pages and use AsciiDoc format.
   9
  10   Manual pages are now generated from AsciiDoc format, allowing easy
  11   conditional modifications for per-action options.
  12
  13   Generation of man pages requires the asciidoctor tool installed.
  14
  15   Pre-generated man pages are also included in the distribution tarball.
  16   You can use --disable-asciidoc configure option to skip man page
  17   generation completely. In this case, pre-generated man pages will be
  18   used for installation.
  19
  20   For cryptsetup, there is main man page (cryptsetup.8) that references
  21   separate man pages for each command (for example, cryptsetup-open.8).
  22   You can open such a man page by simply running "man cryptsetup open".
  23   Also, man pages for action aliases are available (cryptsetup-luksOpen.8
  24   is an alias for cryptsetup-open.8, etc.)
  25
  26 LUKS volume reencryption changes
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28
  29 * Remove cryptsetup-reencrypt tool from the project and move reencryption
  30   to already existing "cryptsetup reencrypt" command.
  31
  32   Cryptsetup reencrypt now handles both LUKS1 and LUKS2 reencryption,
  33   encryption, and decryption.
  34
  35   If you need to emulate the old cryptsetup-reencrypt binary, use simple
  36   wrappers script running "exec cryptsetup reencrypt $@".
  37
  38   All command line options should be compatible. An exception is the
  39   reencryption of LUKS2 volumes with old LUKS1 reencryption code that was
  40   replaced by native and more resilient LUKS2 reencryption.
  41
  42 * LUKS2: implement --decryption option that allows LUKS removal. The
  43   operation can run online or offline and supports the data shift option.
  44
  45   During the initialization, the LUKS2 header is exported to a file.
  46   The first data segment is moved to the head of the data device in place
  47   of the original header.
  48
  49   The feature internally introduces several new resilience modes
  50   (combination of existing modes datashift and "checksum" or "journal").
  51   Datashift resilience mode is applied for data moved towards the first
  52   segment, and the first segment is then decrypted in place.
  53
  54   This decryption mode is not backward compatible with prior LUKS2
  55   reencryption. Interrupted operations in progress cannot be resumed
  56   using older cryptsetup releases.
  57
  58 * Reencryption metadata options that are not compatible with recent code
  59   (features implemented in more recent releases) are now only read, but
  60   code will not activate or modify such metadata.
  61   Reencryption metadata contains a version that is validated when
  62   reencryption is resumed.
  63   For more info, see the updated LUKS2 on-disk format specification.
  64
  65   Safe operation of reencryption is to always finish the operation with
  66   only one version of the tools.
  67
  68 * Fix decryption operation with --active-name option and restrict
  69   it to be used only with LUKS2.
  70
  71 * Do not refresh reencryption digest when not needed.
  72   This should speed up the reencryption resume process.
  73
  74 * Store proper resilience data in LUKS2 reencrypt initialization.
  75   Resuming reencryption now does not require specification of resilience
  76   type parameters if these are the same as during initialization.
  77
  78 * Properly wipe the unused area after reencryption with datashift in
  79   the forward direction.
  80
  81 * Check datashift value against larger sector size.
  82   For example, it could cause an issue if misaligned 4K sector appears
  83   during decryption.
  84
  85 * Do not allow sector size increase reencryption in offline mode.
  86   The eventual logical block size increase on the dm-crypt device above
  87   may lead to an unusable filesystem. Do not allow offline reencryption
  88   when sector size increase is requested.
  89
  90   You can use --force-offline-reencrypt option to override this check
  91   (and potentially destroy the data).
  92
  93 * Do not allow dangerous sector size change during reencryption.
  94   By changing the encryption sector size during reencryption, a user
  95   may increase the effective logical block size for the dm-crypt active
  96   device.
  97
  98   Do not allow encryption sector size to be increased over the value
  99   provided by fs superblock in BLOCK_SIZE property.
 100
 101 * Ask the user for confirmation before resuming reencryption.
 102   The prompt is not shown in batch mode or when the user explicitly asks
 103   for a reencryption resume via --resume-only.
 104
 105 * Do not resume reencryption with conflicting parameters.
 106   For example, if the operation was initialized as --encrypt, do not
 107   allow resume with opposing parameter --decrypt and vice versa.
 108   Also, the code now checks for conflicting resilience parameters
 109   (datashift cannot be changed after initialization).
 110
 111 * Add --force-offline-reencrypt option.
 112   It can be used to enforce offline reencryption in batch mode when
 113   the device is a regular file; therefore, cryptsetup cannot detect
 114   properly active devices using it.
 115   Also, it may be useful to override the active device auto-detection
 116   for specific storage configurations (dangerous!).
 117
 118 * Do not allow nested encryption in LUKS reencrypt.
 119   Avoid accidental nested encryption via cryptsetup reencrypt --encrypt.
 120
 121 * Fix --test-passphrase when the device is in reencryption.
 122
 123 * Do not upload keys in keyring during offline reencryption.
 124   Reencryption runs in userspace, so the kernel does not need the key.
 125
 126 * Support all options allowed with luksFormat with encrypt action.
 127
 128 * Add prompt if LUKS2 decryption is run with a detached header.
 129
 130 * Add warning for reencryption of file image and mention
 131   the possible use of --force-offline-reencrypt option.
 132
 133 Other changes
 134 ~~~~~~~~~~~~~
 135
 136 * Add resize action to integritysetup.
 137   This allows resizing of standalone integrity devices.
 138
 139 * Support --device-size option (that allows unit specification) for plain
 140   devices (existing --size option requires 512-byte sectors units).
 141
 142 * Fix detection of encryption sector size if a detached header is used.
 143
 144 * Remove obsolete dracut plugin reencryption example.
 145
 146 * Fix possible keyslot area size overflow during conversion to LUKS2.
 147   If keyslots are not sorted according to binary area offset, the area
 148   size calculation was wrong and could overflow.
 149
 150 * Hardening and fixes to LUKS2 validation functions:
 151
 152   * Log a visible error if convert fails due to validation check.
 153
 154   * Check for interval (keyslot and segment area) overflow.
 155
 156   * Check cipher availability before LUKS conversion to LUKS2.
 157     Some historic incompatibilities are ignored for LUKS1 but do not
 158     work for LUKS2.
 159
 160   * Add empty string check to LUKS2 metadata JSON validation.
 161     Most of the LUKS2 fields cannot be empty.
 162
 163   * Fix JSON objects validation to check JSON object type properly.
 164
 165 * TCRYPT: Properly apply retry count and continue if some PBKDF variant
 166   is unavailable.
 167
 168 * BITLK: Add a warning when activating a device with the wrong size
 169   stored in metadata.
 170
 171 * BITLK: Add BitLocker volume size to dump command.
 172
 173 * BITLK: Fix possible UTF16 buffer overflow in volume key dump.
 174
 175 * BITLK: Skip question if the batch mode is set for volume key dump.
 176
 177 * BITLK: Check dm-zero availability in the kernel.
 178   Bitlocker compatible mode uses dm-zero to mask metadata area.
 179   The device cannot be activated if dm-zero is not available.
 180
 181 * Fix error message for LUKS2-only cryptsetup commands to explicitly
 182   state LUKS2 version is required.
 183
 184 * Fix error message for incompatible dm-integrity metadata.
 185   If the integritysetup tool is too old, kernel dm-integrity may use
 186   a more recent version of dm-integrity metadata.
 187
 188 * Properly deactivate the integrity device even if the LUKS2 header
 189   is no longer available.
 190   If LUKS2 is used with integrity protection, there is always
 191   a dm-integrity device underneath that must be deactivated.
 192
 193 * Allow use of --header option for cryptsetup close.
 194   This can be used to check that the activated device has the same UUID.
 195
 196 * Fix activation of LUKS2 device with integrity and detached header.
 197   The kernel-parsed dm-integrity superblock is always located on the
 198   data device, the incorrectly used detached header device here.
 199
 200 * Add ZEROOUT IOCTL support for crypt_wipe API call.
 201   For block devices, we can use optimized in-kernel BLKZEROOUT ioctl.
 202
 203 * VERITY: set loopback sector size according to dm-verity block sizes.
 204   Verity block size has the same limits, so we can optimize the loop
 205   device to increase performance.
 206
 207 * Other Documentation and man page improvements:
 208
 209   * Update LUKS2 on-disk format description.
 210
 211   * Add per-keyslot LUKS2 options to the man page.
 212     Some options were missing for LUKS2 luksAddKey and luksChangeKey.
 213
 214   * Fix cryptsetup manpage to use PBKDF consistently.
 215
 216   * Add compile info to README. This information was lost when we removed
 217     the default automake INSTALL file.
 218
 219   * Use volume key consistently in FAQ and man pages.
 220
 221   * Use markdown version of FAQ directly for installation.
 222
 223   * Clarify graceful reencryption interruption.
 224     Currently, it can be interrupted by both SIGINT and SIGTERM signals.
 225
 226   * Add new mailing list info.
 227
 228   * Mention non-cryptographic xxhash64 hash for integrity protection.
 229
 230 * veritysetup: dump device sizes.
 231   Calculating device sizes for verity devices is a little bit tricky.
 232   Data, hash, and FEC can share devices or be separate devices.
 233   Now dump command prints used device sizes, but it requires that
 234   the user specifies all values that are not stored in superblock
 235   (like FEC device and FEC roots).
 236
 237 * Fix check for argp_usage in configure if argp-standalone lib is used.
 238
 239 * Add constant time memcmp and hexa print implementation and use it for
 240   cryptographic keys handling.
 241
 242 * Display progress when wiping the end of the resized device.
 243
 244 * LUKS2 token: prefer token PIN query before passphrase in some cases.
 245   When a user provides --token-type or specific --token-id, a token PIN
 246   query is preferred to a passphrase query.
 247
 248 * LUKS2 token: allow tokens to be replaced with --token-replace option
 249   for cryptsetup token command.
 250
 251 * LUKS2 token: do not continue operation when interrupted in PIN prompt.
 252
 253 * Add --progress-json parameter to utilities.
 254   Progress data can now be printed out in JSON format suitable for
 255   machine processing.
 256
 257 * Embedded Argon2 PBKDF: optimize and simplify thread exit.
 258
 259 * Avoid using SHA1 in tests and fix new enforcements introduced in FIPS
 260   provider for OpenSSL3 (like minimal parameters for PBKDF2).
 261
 262 * Use custom UTF conversion and avoid linking to iconv as a dependency.
 263
 264 * Reimplement BASE64 with simplified code instead of coreutils version.
 265
 266 * Fix regression when warning messages were not displayed
 267   if some kernel feature is not supported (2.4.2).
 268
 269 * Add support for --key-slot option in luksResume action.
 270
 271 Libcryptsetup API extensions and changes
 272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 273
 274 * Properly define uint32_t constants in API.
 275   This is not a real change, but it avoids strict compiler warnings.
 276
 277 * crypt_resume_by_token_pin() - Resume crypt device using LUKS2 token.
 278
 279 * crypt_get_label() - Get the label of the LUKS2 device.
 280
 281 * crypt_get_subsystem() - Get the subsystem label of the LUKS2 device.
 282
 283 * Make CRYPT_WIPE_ENCRYPTED_ZERO crypt_wipe() option obsolete.
 284   It was never implemented (the idea was to speed up wipe), but with
 285   the recent RNG performance changes, it makes no longer sense.
 286
 287 * Add struct crypt_params_reencrypt changes related to decryption.
 288
 289 * Improve crypt_reencrypt_status() return values.
 290   Empty or any non-LUKS types now returns CRYPT_REENCRYPT_INVALID status.
 291   For LUKS1 devices, it returns CRYPT_REENCRYPT_NONE.