diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/v2.2.0-ReleaseNotes | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/docs/v2.2.0-ReleaseNotes b/docs/v2.2.0-ReleaseNotes new file mode 100644 index 0000000..b1fd363 --- /dev/null +++ b/docs/v2.2.0-ReleaseNotes @@ -0,0 +1,279 @@ +Cryptsetup 2.2.0 Release Notes +============================== +Stable release with new experimental features and bug fixes. + +Cryptsetup 2.2 version introduces a new LUKS2 online reencryption +extension that allows reencryption of mounted LUKS2 devices +(device in use) in the background. + +Online reencryption is a complex feature. Please be sure you +have a full data backup before using this feature. + +Changes since version 2.1.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +LUKS2 online reencryption +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reencryption is intended to provide a reliable way to change +volume key or an algorithm change while the encrypted device is still +in use. + +It is based on userspace-only approach (no kernel changes needed) +that uses the device-mapper subsystem to remap active devices on-the-fly +dynamically. The device is split into several segments (encrypted by old +key, new key and so-called hotzone, where reencryption is actively running). + +The flexible LUKS2 metadata format is used to store intermediate states +(segment mappings) and both version of keyslots (old and new keys). +Also, it provides a binary area (in the unused keyslot area space) +to provide recovery metadata in the case of unexpected failure during +reencryption. LUKS2 header is during the reencryption marked with +"online-reencryption" keyword. After the reencryption is finished, +this keyword is removed, and the device is backward compatible with all +older cryptsetup tools (that support LUKS2). + +The recovery supports three resilience modes: + + - checksum: default mode, where individual checksums of ciphertext hotzone + sectors are stored, so the recovery process can detect which sectors were + already reencrypted. It requires that the device sector write is atomic. + + - journal: the hotzone is journaled in the binary area + (so the data are written twice) + + - none: performance mode; there is no protection + (similar to old offline reencryption) + +These resilience modes are not available if reencryption uses data shift. + +Note: until we have full documentation (both of the process and metadata), +please refer to Ondrej's slides (some slight details are no longer relevant) +https://okozina.fedorapeople.org/online-disk-reencryption-with-luks2-compact.pdf + +The offline reencryption tool (cryptsetup-reencrypt) is still supported +for both LUKS1 and LUKS2 format. + +Cryptsetup examples for reencryption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reencryption feature is integrated directly into cryptsetup utility +as the new "reencrypt" action (command). + +There are three basic modes - to perform reencryption (change of already +existing LUKS2 device), to add encryption to plaintext device and to remove +encryption from a device (decryption). + +In all cases, if existing LUKS2 metadata contains information about +the ongoing reencryption process, following reencrypt command continues +with the ongoing reencryption process until it is finished. + +You can activate a device with ongoing reencryption as the standard LUKS2 +device, but the reencryption process will not continue until the cryptsetup +reencrypt command is issued. + + +1) Reencryption +~~~~~~~~~~~~~~~ +This mode is intended to change any attribute of the data encryption +(change of the volume key, algorithm or sector size). +Note that authenticated encryption is not yet supported. + +You can start the reencryption process by specifying a LUKS2 device or with +a detached LUKS2 header. +The code should automatically recognize if the device is in use (and if it +should use online mode of reencryption). + +If you do not specify parameters, only volume key is changed +(a new random key is generated). + +# cryptsetup reencrypt <device> [--header <hdr>] + +You can also start reencryption using active mapped device name: + # cryptsetup reencrypt --active-name <name> + +You can also specify the resilience mode (none, checksum, journal) with +--resilience=<mode> option, for checksum mode also the hash algorithm with +--resilience-hash=<alg> (only hash algorithms supported by cryptographic +backend are available). + +The maximal size of reencryption hotzone can be limited by +--hotzone-size=<size> option and applies to all reencryption modes. +Note that for checksum and journal mode hotzone size is also limited +by available space in binary keyslot area. + +2) Encryption +~~~~~~~~~~~~~ +This mode provides a way to encrypt a plaintext device to LUKS2 format. +This option requires reduction of device size (for LUKS2 header) or new +detached header. + + # cryptsetup reencrypt <device> --encrypt --reduce-device-size <size> + +Or with detached header: + # cryptsetup reencrypt <device> --encrypt --header <hdr> + +3) Decryption +~~~~~~~~~~~~~ +This mode provides the removal of existing LUKS2 encryption and replacing +a device with plaintext content only. +For now, we support only decryption with a detached header. + + # cryptsetup reencrypt <device> --decrypt --header <hdr> + +For all three modes, you can split the process to metadata initialization +(prepare keyslots and segments but do not run reencryption yet) and the data +reencryption step by using --init-only option. + +Prepares metadata: + # cryptsetup reencrypt --init-only <parameters> + +Starts the data processing: + # cryptsetup reencrypt <device> + +Please note, that due to the Linux kernel limitation, the encryption or +decryption process cannot be run entirely online - there must be at least +short offline window where operation adds/removes device-mapper crypt (LUKS2) layer. +This step should also include modification of /etc/crypttab and fstab UUIDs, +but it is out of the scope of cryptsetup tools. + +Limitations +~~~~~~~~~~~ +Most of these limitations will be (hopefully) fixed in next versions. + +* Only one active keyslot is supported (all old keyslots will be removed + after reencryption). + +* Only block devices are now supported as parameters. As a workaround + for images in a file, please explicitly map a loop device over the image + and use the loop device as the parameter. + +* Devices with authenticated encryption are not supported. (Later it will + be limited by the fixed per-sector metadata, per-sector metadata size + cannot be changed without a new device format operation.) + +* The reencryption uses userspace crypto library, with fallback to + the kernel (if available). There can be some specific configurations + where the fallback does not provide optimal performance. + +* There are no translations of error messages until the final release + (some messages can be rephrased as well). + +* The repair command is not finished; the recovery of interrupted + reencryption is made automatically on the first device activation. + +* Reencryption triggers too many udev scans on metadata updates (on closing + write enabled file descriptors). This has a negative performance impact on the whole + reencryption and generates excessive I/O load on the system. + +New libcryptsetup reencryption API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The libcryptsetup contains new API calls that are used to setup and +run the reencryption. + +Note that there can be some changes in API implementation of these functions +and/or some new function can be introduced in final cryptsetup 2.2 release. + +New API symbols (see documentation in libcryptsetup.h) +* struct crypt_params_reencrypt - reencryption parameters + +* crypt_reencrypt_init_by_passphrase +* crypt_reencrypt_init_by_keyring + - function to configure LUKS2 metadata for reencryption; + if metadata already exists, it configures the context from this metadata + +* crypt_reencrypt + - run the reencryption process (processing the data) + - the optional callback function can be used to interrupt the reencryption + or report the progress. + +* crypt_reencrypt_status + - function to query LUKS2 metadata about the reencryption state + +Other changes and fixes +~~~~~~~~~~~~~~~~~~~~~~~ +* Add optional global serialization lock for memory hard PBKDF. + (The --serialize-memory-hard-pbkdf option in cryptsetup and + CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF in activation flag.) + + This is an "ugly" optional workaround for a situation when multiple devices + are being activated in parallel (like systemd crypttab activation). + The system instead of returning ENOMEM (no memory available) starts + out-of-memory (OOM) killer to kill processes randomly. + + Until we find a reliable way how to work with memory-hard function + in these situations, cryptsetup provide a way how to serialize memory-hard + unlocking among parallel cryptsetup instances to workaround this problem. + This flag is intended to be used only in very specific situations, + never use it directly :-) + +* Abort conversion to LUKS1 with incompatible sector size that is + not supported in LUKS1. + +* Report error (-ENOENT) if no LUKS keyslots are available. User can now + distinguish between a wrong passphrase and no keyslot available. + +* Fix a possible segfault in detached header handling (double free). + +* Add integritysetup support for bitmap mode introduced in Linux kernel 5.2. + Integritysetup now supports --integrity-bitmap-mode option and + --bitmap-sector-per-bit and --bitmap-flush-time commandline options. + + In the bitmap operation mode, if a bit in the bitmap is 1, the corresponding + region's data and integrity tags are not synchronized - if the machine + crashes, the unsynchronized regions will be recalculated. + The bitmap mode is faster than the journal mode because we don't have + to write the data twice, but it is also less reliable, because if data + corruption happens when the machine crashes, it may not be detected. + This can be used only for standalone devices, not with dm-crypt. + +* The libcryptsetup now keeps all file descriptors to underlying device + open during the whole lifetime of crypt device context to avoid excessive + scanning in udev (udev run scan on every descriptor close). + +* The luksDump command now prints more info for reencryption keyslot + (when a device is in-reencryption). + +* New --device-size parameter is supported for LUKS2 reencryption. + It may be used to encrypt/reencrypt only the initial part of the data + device if the user is aware that the rest of the device is empty. + + Note: This change causes API break since the last rc0 release + (crypt_params_reencrypt structure contains additional field). + +* New --resume-only parameter is supported for LUKS2 reencryption. + This flag resumes reencryption process if it exists (not starting + new reencryption). + +* The repair command now tries LUKS2 reencryption recovery if needed. + +* If reencryption device is a file image, an interactive dialog now + asks if reencryption should be run safely in offline mode + (if autodetection of active devices failed). + +* Fix activation through a token where dm-crypt volume key was not + set through keyring (but using old device-mapper table parameter mode). + +* Online reencryption can now retain all keyslots (if all passphrases + are provided). Note that keyslot numbers will change in this case. + +* Allow volume key file to be used if no LUKS2 keyslots are present. + If all keyslots are removed, LUKS2 has no longer information about + the volume key size (there is only key digest present). + Please use --key-size option to open the device or add a new keyslot + in these cases. + +* Print a warning if online reencrypt is called over LUKS1 (not supported). + +* Fix TCRYPT KDF failure in FIPS mode. + Some crypto backends support plain hash in FIPS mode but not for PBKDF2. + +* Remove FIPS mode restriction for crypt_volume_key_get. + It is an application responsibility to use this API in the proper context. + +* Reduce keyslots area size in luksFormat when the header device is too small. + Unless user explicitly asks for keyslots areas size (either via + --luks2-keyslots-size or --offset) reduce keyslots size so that it fits + in metadata device. + +* Make resize action accept --device-size parameter (supports units suffix). |