summaryrefslogtreecommitdiffstats
path: root/docs/v2.2.0-ReleaseNotes
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/v2.2.0-ReleaseNotes279
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).