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