diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/v2.5.0-ReleaseNotes | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/docs/v2.5.0-ReleaseNotes b/docs/v2.5.0-ReleaseNotes new file mode 100644 index 0000000..f5bdeec --- /dev/null +++ b/docs/v2.5.0-ReleaseNotes @@ -0,0 +1,291 @@ +Cryptsetup 2.5.0 Release Notes +============================== +Stable release with new features and bug fixes. + +Changes since version 2.4.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Split manual pages into per-action pages and use AsciiDoc format. + + Manual pages are now generated from AsciiDoc format, allowing easy + conditional modifications for per-action options. + + Generation of man pages requires the asciidoctor tool installed. + + Pre-generated man pages are also included in the distribution tarball. + You can use --disable-asciidoc configure option to skip man page + generation completely. In this case, pre-generated man pages will be + used for installation. + + For cryptsetup, there is main man page (cryptsetup.8) that references + separate man pages for each command (for example, cryptsetup-open.8). + You can open such a man page by simply running "man cryptsetup open". + Also, man pages for action aliases are available (cryptsetup-luksOpen.8 + is an alias for cryptsetup-open.8, etc.) + +LUKS volume reencryption changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Remove cryptsetup-reencrypt tool from the project and move reencryption + to already existing "cryptsetup reencrypt" command. + + Cryptsetup reencrypt now handles both LUKS1 and LUKS2 reencryption, + encryption, and decryption. + + If you need to emulate the old cryptsetup-reencrypt binary, use simple + wrappers script running "exec cryptsetup reencrypt $@". + + All command line options should be compatible. An exception is the + reencryption of LUKS2 volumes with old LUKS1 reencryption code that was + replaced by native and more resilient LUKS2 reencryption. + +* LUKS2: implement --decryption option that allows LUKS removal. The + operation can run online or offline and supports the data shift option. + + During the initialization, the LUKS2 header is exported to a file. + The first data segment is moved to the head of the data device in place + of the original header. + + The feature internally introduces several new resilience modes + (combination of existing modes datashift and "checksum" or "journal"). + Datashift resilience mode is applied for data moved towards the first + segment, and the first segment is then decrypted in place. + + This decryption mode is not backward compatible with prior LUKS2 + reencryption. Interrupted operations in progress cannot be resumed + using older cryptsetup releases. + +* Reencryption metadata options that are not compatible with recent code + (features implemented in more recent releases) are now only read, but + code will not activate or modify such metadata. + Reencryption metadata contains a version that is validated when + reencryption is resumed. + For more info, see the updated LUKS2 on-disk format specification. + + Safe operation of reencryption is to always finish the operation with + only one version of the tools. + +* Fix decryption operation with --active-name option and restrict + it to be used only with LUKS2. + +* Do not refresh reencryption digest when not needed. + This should speed up the reencryption resume process. + +* Store proper resilience data in LUKS2 reencrypt initialization. + Resuming reencryption now does not require specification of resilience + type parameters if these are the same as during initialization. + +* Properly wipe the unused area after reencryption with datashift in + the forward direction. + +* Check datashift value against larger sector size. + For example, it could cause an issue if misaligned 4K sector appears + during decryption. + +* Do not allow sector size increase reencryption in offline mode. + The eventual logical block size increase on the dm-crypt device above + may lead to an unusable filesystem. Do not allow offline reencryption + when sector size increase is requested. + + You can use --force-offline-reencrypt option to override this check + (and potentially destroy the data). + +* Do not allow dangerous sector size change during reencryption. + By changing the encryption sector size during reencryption, a user + may increase the effective logical block size for the dm-crypt active + device. + + Do not allow encryption sector size to be increased over the value + provided by fs superblock in BLOCK_SIZE property. + +* Ask the user for confirmation before resuming reencryption. + The prompt is not shown in batch mode or when the user explicitly asks + for a reencryption resume via --resume-only. + +* Do not resume reencryption with conflicting parameters. + For example, if the operation was initialized as --encrypt, do not + allow resume with opposing parameter --decrypt and vice versa. + Also, the code now checks for conflicting resilience parameters + (datashift cannot be changed after initialization). + +* Add --force-offline-reencrypt option. + It can be used to enforce offline reencryption in batch mode when + the device is a regular file; therefore, cryptsetup cannot detect + properly active devices using it. + Also, it may be useful to override the active device auto-detection + for specific storage configurations (dangerous!). + +* Do not allow nested encryption in LUKS reencrypt. + Avoid accidental nested encryption via cryptsetup reencrypt --encrypt. + +* Fix --test-passphrase when the device is in reencryption. + +* Do not upload keys in keyring during offline reencryption. + Reencryption runs in userspace, so the kernel does not need the key. + +* Support all options allowed with luksFormat with encrypt action. + +* Add prompt if LUKS2 decryption is run with a detached header. + +* Add warning for reencryption of file image and mention + the possible use of --force-offline-reencrypt option. + +Other changes +~~~~~~~~~~~~~ + +* Add resize action to integritysetup. + This allows resizing of standalone integrity devices. + +* Support --device-size option (that allows unit specification) for plain + devices (existing --size option requires 512-byte sectors units). + +* Fix detection of encryption sector size if a detached header is used. + +* Remove obsolete dracut plugin reencryption example. + +* Fix possible keyslot area size overflow during conversion to LUKS2. + If keyslots are not sorted according to binary area offset, the area + size calculation was wrong and could overflow. + +* Hardening and fixes to LUKS2 validation functions: + + * Log a visible error if convert fails due to validation check. + + * Check for interval (keyslot and segment area) overflow. + + * Check cipher availability before LUKS conversion to LUKS2. + Some historic incompatibilities are ignored for LUKS1 but do not + work for LUKS2. + + * Add empty string check to LUKS2 metadata JSON validation. + Most of the LUKS2 fields cannot be empty. + + * Fix JSON objects validation to check JSON object type properly. + +* TCRYPT: Properly apply retry count and continue if some PBKDF variant + is unavailable. + +* BITLK: Add a warning when activating a device with the wrong size + stored in metadata. + +* BITLK: Add BitLocker volume size to dump command. + +* BITLK: Fix possible UTF16 buffer overflow in volume key dump. + +* BITLK: Skip question if the batch mode is set for volume key dump. + +* BITLK: Check dm-zero availability in the kernel. + Bitlocker compatible mode uses dm-zero to mask metadata area. + The device cannot be activated if dm-zero is not available. + +* Fix error message for LUKS2-only cryptsetup commands to explicitly + state LUKS2 version is required. + +* Fix error message for incompatible dm-integrity metadata. + If the integritysetup tool is too old, kernel dm-integrity may use + a more recent version of dm-integrity metadata. + +* Properly deactivate the integrity device even if the LUKS2 header + is no longer available. + If LUKS2 is used with integrity protection, there is always + a dm-integrity device underneath that must be deactivated. + +* Allow use of --header option for cryptsetup close. + This can be used to check that the activated device has the same UUID. + +* Fix activation of LUKS2 device with integrity and detached header. + The kernel-parsed dm-integrity superblock is always located on the + data device, the incorrectly used detached header device here. + +* Add ZEROOUT IOCTL support for crypt_wipe API call. + For block devices, we can use optimized in-kernel BLKZEROOUT ioctl. + +* VERITY: set loopback sector size according to dm-verity block sizes. + Verity block size has the same limits, so we can optimize the loop + device to increase performance. + +* Other Documentation and man page improvements: + + * Update LUKS2 on-disk format description. + + * Add per-keyslot LUKS2 options to the man page. + Some options were missing for LUKS2 luksAddKey and luksChangeKey. + + * Fix cryptsetup manpage to use PBKDF consistently. + + * Add compile info to README. This information was lost when we removed + the default automake INSTALL file. + + * Use volume key consistently in FAQ and man pages. + + * Use markdown version of FAQ directly for installation. + + * Clarify graceful reencryption interruption. + Currently, it can be interrupted by both SIGINT and SIGTERM signals. + + * Add new mailing list info. + + * Mention non-cryptographic xxhash64 hash for integrity protection. + +* veritysetup: dump device sizes. + Calculating device sizes for verity devices is a little bit tricky. + Data, hash, and FEC can share devices or be separate devices. + Now dump command prints used device sizes, but it requires that + the user specifies all values that are not stored in superblock + (like FEC device and FEC roots). + +* Fix check for argp_usage in configure if argp-standalone lib is used. + +* Add constant time memcmp and hexa print implementation and use it for + cryptographic keys handling. + +* Display progress when wiping the end of the resized device. + +* LUKS2 token: prefer token PIN query before passphrase in some cases. + When a user provides --token-type or specific --token-id, a token PIN + query is preferred to a passphrase query. + +* LUKS2 token: allow tokens to be replaced with --token-replace option + for cryptsetup token command. + +* LUKS2 token: do not continue operation when interrupted in PIN prompt. + +* Add --progress-json parameter to utilities. + Progress data can now be printed out in JSON format suitable for + machine processing. + +* Embedded Argon2 PBKDF: optimize and simplify thread exit. + +* Avoid using SHA1 in tests and fix new enforcements introduced in FIPS + provider for OpenSSL3 (like minimal parameters for PBKDF2). + +* Use custom UTF conversion and avoid linking to iconv as a dependency. + +* Reimplement BASE64 with simplified code instead of coreutils version. + +* Fix regression when warning messages were not displayed + if some kernel feature is not supported (2.4.2). + +* Add support for --key-slot option in luksResume action. + +Libcryptsetup API extensions and changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Properly define uint32_t constants in API. + This is not a real change, but it avoids strict compiler warnings. + +* crypt_resume_by_token_pin() - Resume crypt device using LUKS2 token. + +* crypt_get_label() - Get the label of the LUKS2 device. + +* crypt_get_subsystem() - Get the subsystem label of the LUKS2 device. + +* Make CRYPT_WIPE_ENCRYPTED_ZERO crypt_wipe() option obsolete. + It was never implemented (the idea was to speed up wipe), but with + the recent RNG performance changes, it makes no longer sense. + +* Add struct crypt_params_reencrypt changes related to decryption. + +* Improve crypt_reencrypt_status() return values. + Empty or any non-LUKS types now returns CRYPT_REENCRYPT_INVALID status. + For LUKS1 devices, it returns CRYPT_REENCRYPT_NONE. |