cryptsetup/docs/v2.2.0-ReleaseNotes

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).