"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/v2.2.0-ReleaseNotes" (24 Jul 2021, 11884 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Cryptsetup 2.2.0 Release Notes
    2 ==============================
    3 Stable release with new experimental features and bug fixes.
    4 
    5 Cryptsetup 2.2 version introduces a new LUKS2 online reencryption
    6 extension that allows reencryption of mounted LUKS2 devices
    7 (device in use) in the background.
    8 
    9 Online reencryption is a complex feature. Please be sure you
   10 have a full data backup before using this feature.
   11 
   12 Changes since version 2.1.0
   13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   14 
   15 LUKS2 online reencryption
   16 ~~~~~~~~~~~~~~~~~~~~~~~~~
   17 
   18 The reencryption is intended to provide a reliable way to change
   19 volume key or an algorithm change while the encrypted device is still
   20 in use.
   21 
   22 It is based on userspace-only approach (no kernel changes needed)
   23 that uses the device-mapper subsystem to remap active devices on-the-fly
   24 dynamically. The device is split into several segments (encrypted by old
   25 key, new key and so-called hotzone, where reencryption is actively running).
   26 
   27 The flexible LUKS2 metadata format is used to store intermediate states
   28 (segment mappings) and both version of keyslots (old and new keys).
   29 Also, it provides a binary area (in the unused keyslot area space)
   30 to provide recovery metadata in the case of unexpected failure during
   31 reencryption. LUKS2 header is during the reencryption marked with
   32 "online-reencryption" keyword. After the reencryption is finished,
   33 this keyword is removed, and the device is backward compatible with all
   34 older cryptsetup tools (that support LUKS2).
   35 
   36 The recovery supports three resilience modes:
   37 
   38   - checksum: default mode, where individual checksums of ciphertext hotzone
   39     sectors are stored, so the recovery process can detect which sectors were
   40     already reencrypted. It requires that the device sector write is atomic.
   41 
   42   - journal: the hotzone is journaled in the binary area
   43     (so the data are written twice)
   44 
   45   - none: performance mode; there is no protection
   46     (similar to old offline reencryption)
   47 
   48 These resilience modes are not available if reencryption uses data shift.
   49 
   50 Note: until we have full documentation (both of the process and metadata),
   51 please refer to Ondrej's slides (some slight details are no longer relevant)
   52 https://okozina.fedorapeople.org/online-disk-reencryption-with-luks2-compact.pdf
   53 
   54 The offline reencryption tool (cryptsetup-reencrypt) is still supported
   55 for both LUKS1 and LUKS2 format.
   56 
   57 Cryptsetup examples for reencryption
   58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   59 
   60 The reencryption feature is integrated directly into cryptsetup utility
   61 as the new "reencrypt" action (command).
   62 
   63 There are three basic modes - to perform reencryption (change of already
   64 existing LUKS2 device), to add encryption to plaintext device and to remove
   65 encryption from a device (decryption).
   66 
   67 In all cases, if existing LUKS2 metadata contains information about
   68 the ongoing reencryption process, following reencrypt command continues
   69 with the ongoing reencryption process until it is finished.
   70 
   71 You can activate a device with ongoing reencryption as the standard LUKS2
   72 device, but the reencryption process will not continue until the cryptsetup
   73 reencrypt command is issued.
   74 
   75 
   76 1) Reencryption
   77 ~~~~~~~~~~~~~~~
   78 This mode is intended to change any attribute of the data encryption
   79 (change of the volume key, algorithm or sector size).
   80 Note that authenticated encryption is not yet supported.
   81 
   82 You can start the reencryption process by specifying a LUKS2 device or with
   83 a detached LUKS2 header.
   84 The code should automatically recognize if the device is in use (and if it
   85 should use online mode of reencryption).
   86 
   87 If you do not specify parameters, only volume key is changed
   88 (a new random key is generated).
   89 
   90 # cryptsetup reencrypt <device> [--header <hdr>]
   91 
   92 You can also start reencryption using active mapped device name:
   93   # cryptsetup reencrypt --active-name <name>
   94 
   95 You can also specify the resilience mode (none, checksum, journal) with
   96 --resilience=<mode> option, for checksum mode also the hash algorithm with
   97 --resilience-hash=<alg> (only hash algorithms supported by cryptographic
   98 backend are available).
   99 
  100 The maximal size of reencryption hotzone can be limited by
  101 --hotzone-size=<size> option and applies to all reencryption modes.
  102 Note that for checksum and journal mode hotzone size is also limited
  103 by available space in binary keyslot area.
  104 
  105 2) Encryption
  106 ~~~~~~~~~~~~~
  107 This mode provides a way to encrypt a plaintext device to LUKS2 format.
  108 This option requires reduction of device size (for LUKS2 header) or new
  109 detached header.
  110 
  111   # cryptsetup reencrypt <device> --encrypt --reduce-device-size <size>
  112 
  113 Or with detached header:
  114   # cryptsetup reencrypt <device> --encrypt --header <hdr>
  115 
  116 3) Decryption
  117 ~~~~~~~~~~~~~
  118 This mode provides the removal of existing LUKS2 encryption and replacing
  119 a device with plaintext content only.
  120 For now, we support only decryption with a detached header.
  121 
  122   # cryptsetup reencrypt <device> --decrypt --header <hdr>
  123 
  124 For all three modes, you can split the process to metadata initialization
  125 (prepare keyslots and segments but do not run reencryption yet) and the data
  126 reencryption step by using --init-only option.
  127 
  128 Prepares metadata:
  129   # cryptsetup reencrypt --init-only <parameters>
  130 
  131 Starts the data processing:
  132   # cryptsetup reencrypt <device>
  133 
  134 Please note, that due to the Linux kernel limitation, the encryption or
  135 decryption process cannot be run entirely online - there must be at least
  136 short offline window where operation adds/removes device-mapper crypt (LUKS2) layer.
  137 This step should also include modification of /etc/crypttab and fstab UUIDs,
  138 but it is out of the scope of cryptsetup tools.
  139 
  140 Limitations
  141 ~~~~~~~~~~~
  142 Most of these limitations will be (hopefully) fixed in next versions.
  143 
  144 * Only one active keyslot is supported (all old keyslots will be removed
  145   after reencryption).
  146 
  147 * Only block devices are now supported as parameters. As a workaround
  148   for images in a file, please explicitly map a loop device over the image
  149   and use the loop device as the parameter.
  150 
  151 * Devices with authenticated encryption are not supported. (Later it will
  152   be limited by the fixed per-sector metadata, per-sector metadata size
  153   cannot be changed without a new device format operation.)
  154 
  155 * The reencryption uses userspace crypto library, with fallback to
  156   the kernel (if available). There can be some specific configurations
  157   where the fallback does not provide optimal performance.
  158 
  159 * There are no translations of error messages until the final release
  160   (some messages can be rephrased as well).
  161 
  162 * The repair command is not finished; the recovery of interrupted
  163   reencryption is made automatically on the first device activation.
  164 
  165 * Reencryption triggers too many udev scans on metadata updates (on closing
  166   write enabled file descriptors). This has a negative performance impact on the whole
  167   reencryption and generates excessive I/O load on the system.
  168 
  169 New libcryptsetup reencryption API
  170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  171 The libcryptsetup contains new API calls that are used to setup and
  172 run the reencryption.
  173 
  174 Note that there can be some changes in API implementation of these functions
  175 and/or some new function can be introduced in final cryptsetup 2.2 release.
  176 
  177 New API symbols (see documentation in libcryptsetup.h)
  178 * struct crypt_params_reencrypt - reencryption parameters
  179 
  180 * crypt_reencrypt_init_by_passphrase
  181 * crypt_reencrypt_init_by_keyring
  182   - function to configure LUKS2 metadata for reencryption;
  183     if metadata already exists, it configures the context from this metadata
  184 
  185 * crypt_reencrypt
  186   - run the reencryption process (processing the data)
  187   - the optional callback function can be used to interrupt the reencryption
  188     or report the progress.
  189 
  190 * crypt_reencrypt_status
  191   - function to query LUKS2 metadata about the reencryption state
  192 
  193 Other changes and fixes
  194 ~~~~~~~~~~~~~~~~~~~~~~~
  195 * Add optional global serialization lock for memory hard PBKDF.
  196   (The --serialize-memory-hard-pbkdf option in cryptsetup and
  197   CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF in activation flag.)
  198 
  199   This is an "ugly" optional workaround for a situation when multiple devices
  200   are being activated in parallel (like systemd crypttab activation).
  201   The system instead of returning ENOMEM (no memory available) starts
  202   out-of-memory (OOM) killer to kill processes randomly.
  203 
  204   Until we find a reliable way how to work with memory-hard function
  205   in these situations, cryptsetup provide a way how to serialize memory-hard
  206   unlocking among parallel cryptsetup instances to workaround this problem.
  207   This flag is intended to be used only in very specific situations,
  208   never use it directly :-)
  209 
  210 * Abort conversion to LUKS1 with incompatible sector size that is
  211   not supported in LUKS1.
  212 
  213 * Report error (-ENOENT) if no LUKS keyslots are available. User can now
  214   distinguish between a wrong passphrase and no keyslot available.
  215 
  216 * Fix a possible segfault in detached header handling (double free).
  217 
  218 * Add integritysetup support for bitmap mode introduced in Linux kernel 5.2.
  219   Integritysetup now supports --integrity-bitmap-mode option and
  220   --bitmap-sector-per-bit and --bitmap-flush-time commandline options.
  221 
  222   In the bitmap operation mode, if a bit in the bitmap is 1, the corresponding
  223   region's data and integrity tags are not synchronized - if the machine
  224   crashes, the unsynchronized regions will be recalculated.
  225   The bitmap mode is faster than the journal mode because we don't have
  226   to write the data twice, but it is also less reliable, because if data
  227   corruption happens when the machine crashes, it may not be detected.
  228   This can be used only for standalone devices, not with dm-crypt.
  229 
  230 * The libcryptsetup now keeps all file descriptors to underlying device
  231   open during the whole lifetime of crypt device context to avoid excessive
  232   scanning in udev (udev run scan on every descriptor close).
  233 
  234 * The luksDump command now prints more info for reencryption keyslot
  235   (when a device is in-reencryption).
  236 
  237 * New --device-size parameter is supported for LUKS2 reencryption.
  238   It may be used to encrypt/reencrypt only the initial part of the data
  239   device if the user is aware that the rest of the device is empty.
  240 
  241   Note: This change causes API break since the last rc0 release
  242   (crypt_params_reencrypt structure contains additional field).
  243 
  244 * New --resume-only parameter is supported for LUKS2 reencryption.
  245   This flag resumes reencryption process if it exists (not starting
  246   new reencryption).
  247 
  248 * The repair command now tries LUKS2 reencryption recovery if needed.
  249 
  250 * If reencryption device is a file image, an interactive dialog now
  251   asks if reencryption should be run safely in offline mode
  252   (if autodetection of active devices failed).
  253 
  254 * Fix activation through a token where dm-crypt volume key was not
  255   set through keyring (but using old device-mapper table parameter mode).
  256 
  257 * Online reencryption can now retain all keyslots (if all passphrases
  258   are provided). Note that keyslot numbers will change in this case.
  259 
  260 * Allow volume key file to be used if no LUKS2 keyslots are present.
  261   If all keyslots are removed, LUKS2 has no longer information about
  262   the volume key size (there is only key digest present).
  263   Please use --key-size option to open the device or add a new keyslot
  264   in these cases.
  265 
  266 * Print a warning if online reencrypt is called over LUKS1 (not supported).
  267 
  268 * Fix TCRYPT KDF failure in FIPS mode.
  269   Some crypto backends support plain hash in FIPS mode but not for PBKDF2.
  270 
  271 * Remove FIPS mode restriction for crypt_volume_key_get.
  272   It is an application responsibility to use this API in the proper context.
  273 
  274 * Reduce keyslots area size in luksFormat when the header device is too small.
  275   Unless user explicitly asks for keyslots areas size  (either via
  276   --luks2-keyslots-size or --offset) reduce keyslots size so that it fits
  277   in metadata device.
  278 
  279 * Make resize action accept --device-size parameter (supports units suffix).