docs/v2.1.0-ReleaseNotes

   1 Cryptsetup 2.1.0 Release Notes
   2 ==============================
   3 Stable release with new features and bug fixes.
   4
   5 Cryptsetup 2.1 version uses a new on-disk LUKS2 format as the default
   6 LUKS format and increases default LUKS2 header size.
   7
   8 The legacy LUKS (referenced as LUKS1) will be fully supported forever
   9 as well as a traditional and fully backward compatible format.
  10
  11 When upgrading a stable distribution, please use configure option
  12 --with-default-luks-format=LUKS1 to maintain backward compatibility.
  13
  14 This release also switches to OpenSSL as a default cryptographic
  15 backend for LUKS header processing. Use --with-crypto_backend=gcrypt
  16 configure option if you need to preserve legacy libgcrypt backend.
  17
  18 Please do not use LUKS2 without properly configured backup or
  19 in production systems that need to be compatible with older systems.
  20
  21 Changes since version 2.0.6
  22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23
  24 * The default for cryptsetup LUKS format action is now LUKS2.
  25   You can use LUKS1 with cryptsetup option --type luks1.
  26
  27 * The default size of the LUKS2 header is increased to 16 MB.
  28   It includes metadata and the area used for binary keyslots;
  29   it means that LUKS header backup is now 16MB in size.
  30
  31   Note, that used keyslot area is much smaller, but this increase
  32   of reserved space allows implementation of later extensions
  33   (like online reencryption).
  34   It is fully compatible with older cryptsetup 2.0.x versions.
  35   If you require to create LUKS2 header with the same size as
  36   in the 2.0.x version, use --offset 8192 option for luksFormat
  37   (units are in 512-bytes sectors; see notes below).
  38
  39 * Cryptsetup now doubles LUKS default key size if XTS mode is used
  40   (XTS mode uses two internal keys). This does not apply if key size
  41   is explicitly specified on the command line and it does not apply
  42   for the plain mode.
  43   This fixes a confusion with AES and 256bit key in XTS mode where
  44   code used AES128 and not AES256 as often expected.
  45
  46   Also, the default keyslot encryption algorithm (if cannot be derived
  47   from data encryption algorithm) is now available as configure
  48   options --with-luks2-keyslot-cipher and --with-luks2-keyslot-keybits.
  49   The default is aes-xts-plain64 with 2 * 256-bits key.
  50
  51 * Default cryptographic backend used for LUKS header processing is now
  52   OpenSSL. For years, OpenSSL provided better performance for PBKDF.
  53
  54   NOTE: Cryptsetup/libcryptsetup supports several cryptographic
  55   library backends. The fully supported are libgcrypt, OpenSSL and
  56   kernel crypto API. FIPS mode extensions are maintained only for
  57   libgcrypt and OpenSSL. Nettle and NSS are usable only for some
  58   subset of algorithms and cannot provide full backward compatibility.
  59   You can always switch to other backends by using a configure switch,
  60   for libgcrypt (compatibility for older distributions) use:
  61   --with-crypto_backend=gcrypt
  62
  63 * The Python bindings are no longer supported and the code was removed
  64   from cryptsetup distribution. Please use the libblockdev project
  65   that already covers most of the libcryptsetup functionality
  66   including LUKS2.
  67
  68 * Cryptsetup now allows using --offset option also for luksFormat.
  69   It means that the specified offset value is used for data offset.
  70   LUKS2 header areas are automatically adjusted according to this value.
  71   (Note units are in 512-byte sectors due to the previous definition
  72   of this option in plain mode.)
  73   This option can replace --align-payload with absolute alignment value.
  74
  75 * Cryptsetup now supports new refresh action (that is the alias for
  76   "open --refresh").
  77   It allows changes of parameters for an active device (like root
  78   device mapping), for example, it can enable or disable TRIM support
  79   on-the-fly.
  80   It is supported for LUKS1, LUKS2, plain and loop-AES devices.
  81
  82 * Integritysetup now supports mode with detached data device through
  83   new --data-device option.
  84   Since kernel 4.18 there is a possibility to specify external data
  85   device for dm-integrity that stores all integrity tags.
  86
  87 * Integritysetup now supports automatic integrity recalculation
  88   through new --integrity-recalculate option.
  89   Linux kernel since version 4.18 supports automatic background
  90   recalculation of integrity tags for dm-integrity.
  91
  92 Other changes and fixes
  93 ~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 * Fix for crypt_wipe call to allocate space if the header is backed
  96   by a file. This means that if you use detached header file, it will
  97   now have always the full size after luksFormat, even if only
  98   a few keyslots are used.
  99
 100 * Fixes to offline cryptsetup-reencrypt to preserve LUKS2 keyslots
 101   area sizes after reencryption and fixes for some other issues when
 102   creating temporary reencryption headers.
 103
 104 * Added some FIPS mode workarounds. We cannot (yet) use Argon2 in
 105   FIPS mode, libcryptsetup now fallbacks to use PBKDF2 in FIPS mode.
 106
 107 * Rejects conversion to LUKS1 if PBKDF2 hash algorithms
 108   in keyslots differ.
 109
 110 * The hash setting on command line now applies also to LUKS2 PBKDF2
 111   digest. In previous versions, the LUKS2 key digest used PBKDF2-SHA256
 112   (except for converted headers).
 113
 114 * Allow LUKS2 keyslots area to increase if data offset allows it.
 115   Cryptsetup can fine-tune LUKS2 metadata area sizes through
 116   --luks2-metadata-size=BYTES and --luks2-keyslots-size=BYTES.
 117   Please DO NOT use these low-level options until you need it for
 118   some very specific additional feature.
 119   Also, the code now prints these LUKS2 header area sizes in dump
 120   command.
 121
 122 * For LUKS2, keyslot can use different encryption that data with
 123   new options --keyslot-key-size=BITS and --keyslot-cipher=STRING
 124   in all commands that create new LUKS keyslot.
 125   Please DO NOT use these low-level options until you need it for
 126   some very specific additional feature.
 127
 128 * Code now avoids data flush when reading device status through
 129   device-mapper.
 130
 131 * The Nettle crypto backend and the userspace kernel crypto API
 132   backend were enhanced to allow more available hash functions
 133   (like SHA3 variants).
 134
 135 * Upstream code now does not require libgcrypt-devel
 136   for autoconfigure, because OpenSSL is the default.
 137   The libgcrypt does not use standard pkgconfig detection and
 138   requires specific macro (part of libgcrypt development files)
 139   to be always present during autoconfigure.
 140   With other crypto backends, like OpenSSL, this makes no sense,
 141   so this part of autoconfigure is now optional.
 142
 143 * Cryptsetup now understands new --debug-json option that allows
 144   an additional dump of some JSON information. These are no longer
 145   present in standard debug output because it could contain some
 146   specific LUKS header parameters.
 147
 148 * The luksDump contains the hash algorithm used in Anti-Forensic
 149   function.
 150
 151 * All debug messages are now sent through configured log callback
 152   functions, so an application can easily use own debug messages
 153   handling. In previous versions debug messages were printed directly
 154   to standard output.)
 155
 156 Libcryptsetup API additions
 157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 158
 159 These new calls are now exported, for details see libcryptsetup.h:
 160
 161  * crypt_init_data_device
 162  * crypt_get_metadata_device_name
 163      functions to init devices with separate metadata and data device
 164      before a format function is called.
 165
 166  * crypt_set_data_offset
 167      sets the data offset for LUKS to the specified value
 168      in 512-byte sectors.
 169      It should replace alignment calculation in LUKS param structures.
 170
 171  * crypt_get_metadata_size
 172  * crypt_set_metadata_size
 173      allows one to set/get area sizes in LUKS header
 174      (according to specification).
 175
 176  * crypt_get_default_type
 177      get default compiled-in LUKS type (version).
 178
 179  * crypt_get_pbkdf_type_params
 180      allows one to get compiled-in PBKDF parameters.
 181
 182  * crypt_keyslot_set_encryption
 183  * crypt_keyslot_get_encryption
 184      allows one to set/get per-keyslot encryption algorithm for LUKS2.
 185
 186  * crypt_keyslot_get_pbkdf
 187      allows one to get PBKDF parameters per-keyslot.
 188
 189  and these new defines:
 190  * CRYPT_LOG_DEBUG_JSON (message type for JSON debug)
 191  * CRYPT_DEBUG_JSON (log level for JSON debug)
 192  * CRYPT_ACTIVATE_RECALCULATE (dm-integrity recalculate flag)
 193  * CRYPT_ACTIVATE_REFRESH (new open with refresh flag)
 194
 195 All existing API calls should remain backward compatible.
 196
 197 Unfinished things & TODO for next releases
 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 199 * Optional authenticated encryption is still an experimental feature
 200   and can have performance problems for high-speed devices and device
 201   with larger IO blocks (like RAID).
 202
 203 * Authenticated encryption does not use encryption for a dm-integrity
 204   journal. While it does not influence data confidentiality or
 205   integrity protection, an attacker can get some more information
 206   from data journal or cause that system will corrupt sectors after
 207   journal replay. (That corruption will be detected though.)
 208
 209 * The LUKS2 metadata area increase is mainly needed for the new online
 210   reencryption as the major feature for the next release.