path: root/docs/v2.7.0-ReleaseNotes

Cryptsetup 2.7.0 Release Notes
==============================
Stable release with new features and bug fixes.

Changes since version 2.6.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Introduce support for hardware OPAL disk encryption.

  Some SATA and NVMe devices support hardware encryption through OPAL2
  TCG interface (SEDs - self-encrypting drives). Using hardware disk
  encryption is controversial as you must trust proprietary hardware.

  On the other side, using both software and hardware encryption
  layers increases the security margin by adding an additional layer
  of protection. There is usually no performance drop if OPAL encryption
  is used (the drive always operates with full throughput), and it does
  not add any utilization to the main CPU.

  LUKS2 now supports hardware encryption through the Linux kernel
  SED OPAL interface (CONFIG_BLK_SED_OPAL Linux kernel option must be
  enabled). Cryptsetup OPAL is never enabled by default; you have to use
  luksFormat parameters to use it. OPAL support can be disabled during
  the build phase with --disable-hw-opal configure option.

  LUKS2 OPAL encryption is configured the same way as software encryption
  - it stores metadata in the LUKS2 header and activates encryption for
  the data area on the disk (configured OPAL locking range).
  LUKS2 header metadata must always be visible (thus not encrypted).
  The key stored in LUKS2 keyslots contains two parts - volume key
  for software (dm-crypt) encryption and unlocking key for OPAL.
  OPAL unlocking key is independent of the dm-crypt volume key and is
  always 256 bits long. Cryptsetup does not support full drive OPAL
  encryption; only a specific locking range is always used.

  If the OPAL device is in its initial factory state (after factory
  reset), cryptsetup needs to configure the OPAL admin user and password.
  If the OPAL admin user is already set, the OPAL password must be
  provided during luksFormat.
  The provided password is needed only to configure or reset the OPAL
  locking range; LUKS device activation requires LUKS passphrase only.
  LUKS passphrase should be different from OPAL password (OPAL admin user
  is configured inside OPAL hardware while LUKS unlocking passphrase
  unlocks LUKS keyslot).

  OPAL encryption can be used in combination with software (dm-crypt)
  encryption (--hw-opal option) or without the software layer
  (--hw-opal-only option).
  You can see the configured segment parameters in the luksDump command.
  LUKS2 devices with OPAL segments set a new requirement flag in
  the LUKS2 header to prevent older cryptsetup metadata manipulation.
  Do not use hardware-only encryption if you do not fully trust your
  hardware vendor.

  Compatibility notes:
    - Linux kernel SED interface does NOT work through USB external
    adapters due to the missing compatibility layer in Linux USB storage
    drivers (even if USB hardware itself can support OPAL commands).
    - other TCG security subsystems like Ruby or Pyrite are not
    supported. Note that many drives support only Pyrite subsystem that
    does NOT encrypt data (it provides only authentication).
    - compatibility among OPAL-enabled drives is often very problematic,
    specifically for older drives. Many drives have bugs in the firmware
    that make the Linux kernel interface unusable.
    - if you forget the OPAL admin password, the only way to recover is
    the full drive factory reset through the PSID key (usually printed
    on the drive itself) that wipes all data on the drive (not only the
    LUKS area).
    - cryptsetup reencryption is not supported for LUKS2 OPAL-enabled
    devices
    - most OPAL drives use AES-XTS cipher mode (older drives can use
    AES-CBC). This information is not available through kernel SED API.
    - locked OPAL locking ranges return IO errors while reading; this
    can produce a lot of scary messages in the log if some tools (like
    blkid) try to read the locked area.

  Examples:

  * Formatting the drive
  Use --hw-opal with luksFormat (or --hw-opal-only for hardware only
  encryption):

  # cryptsetup luksFormat --hw-opal <device>
  Enter passphrase for <device>: ***
  Enter OPAL Admin password: ***

  * Check configuration with luksDump.
  Note "hw-opal-crypt" segment that uses both dm-crypt and OPAL
  encryption - keyslot stores 768 bits key (512 sw + 256 bits OPAL key).

  # cryptsetup luksDump <device>
    LUKS header information
    Version:        2
    ...
    Data segments:
       0: hw-opal-crypt
         offset: 16777216 [bytes]
         length: ... [bytes]
         cipher: aes-xts-plain64
         sector: 512 [bytes]
         HW OPAL encryption:
                OPAL segment number: 1
                OPAL key: 256 bits
                OPAL segment length: ... [bytes]
     Keyslots:
       0: luks2
         Key:        768 bits
      ...

  For devices with OPAL encryption ONLY (only 256 bits OPAL unlocking
  key is stored):
     LUKS header information
     Version:        2
     ...

     Data segments:
        0: hw-opal
          offset: 16777216 [bytes]
          length: ... [bytes]
          cipher: (no SW encryption)
          HW OPAL encryption:
                OPAL segment number: 1
                OPAL key: 256 bits
                OPAL segment length: ... [bytes]
     Keyslots:
       0: luks2
         Key:        256 bits
         ...

  * Activation and deactivation (open, close, luksSuspend, luksResume)
  with OPAL works the same as for the LUKS2 device.

  * Erase LUKS metadata (keyslots) and remove OPAL locking range:
  # cryptsetup luksErase <device>
    Enter OPAL Admin password: ***

  The LUKS header is destroyed (unlike in normal LUKS luksErase) as
  data are no longer accessible even with previous volume key knowledge.

  * Factory reset OPAL drive (if you do not know the Admin password).
    You need the PSID (physical presence security ID), which is usually
    printed on the device label. Note this will reset the device to
    factory state, erasing all data on it (not only LUKS).

  # cryptsetup luksErase --hw-opal-factory-reset <device>
    Enter OPAL PSID: ***

* plain mode: Set default cipher to aes-xts-plain64 and password hashing
  to sha256.

  NOTE: this is a backward incompatible change for plain mode (if you
  rely on defaults). It is not relevant for LUKS devices.

  The default plain encryption mode was CBC for a long time, with many
  performance problems. Using XTS mode aligns it with LUKS defaults.

  The hash algorithm for plain mode was ripemd160, which is considered
  deprecated, so the new default is sha256.

  The default key size remains 256 bits (it means using AES-128 as XTS
  requires two keys).

  Always specify cipher, hash, and key size for plain mode (or even
  better, use LUKS as it stores all options in its metadata on disk).
  As we need to upgrade algorithms from time to time because of security
  reasons, cryptsetup now warns users to specify these options explicitly
  in the open cryptsetup command if plain mode is used.
  Cryptsetup does not block using any legacy encryption type; just it
  must be specified explicitly on the cryptsetup command line.

  You can configure these defaults during build time if you need to
  enforce backward compatibility.
  To get the backward-compatible setting, use:
    --with-plain-hash=ripemd160 --with-plain-cipher=aes
    --with-plain-mode=cbc-essiv:sha256

  Compiled-in defaults are visible in cryptsetup --help output.

* Allow activation (open), luksResume, and luksAddKey to use the volume
  key stored in a keyring.
* Allow to store volume key to a user-specified keyring in open and
  luksResume commands.

  These options are intended to be used for integration with other
  systems for automation.

  Users can now use the volume key (not passphrase) stored in arbitrary
  kernel keyring and directly use it in particular cryptsetup commands
  with --volume-key-keyring option. The keyring can use various policies
  (set outside of the cryptsetup scope, for example, by keyctl).

  The --volume-key-keyring option takes a key description in
  keyctl-compatible syntax and can either be a numeric key ID or
  a string name in the format [%<key type>:]<key name>.
  The default key type is "user".

  To store the volume key in a keyring, you can use cryptsetup with
  --link-vk-to-keyring option that is available for open and luksResume
  cryptsetup command. The option argument has a more complex format:
  <keyring_description>::<key_description>.
  The <keyring_description> contains the existing kernel keyring
  description (numeric id or keyctl format). The <keyring_description>
  may be optionally prefixed with "%:" or "%keyring:". The string "::" is
  a delimiter that separates keyring and key descriptions.
  The <key_description> has the same syntax as used in the
  --volume-key-keyring option.

  Example:

  Open the device and store the volume key to the keyring:
  # cryptsetup open <device> --link-vk-to-keyring "@s::%user:testkey" tst

  Add keyslot using the stored key in a keyring:
  # cryptsetup luksAddKey <device> --volume-key-keyring "%user:testkey"

* Do not flush IO operations if resize grows the device.
  This can help performance in specific cases where the encrypted device
  is extended automatically while running many IO operations.

* Use only half of detected free memory for Argon2 PBKDF on systems
  without swap (for LUKS2 new keyslot or format operations).

  This should avoid out-of-memory crashes on low-memory systems without
  swap. The benchmark for memory-hard KDF during format is tricky, and
  it seems that relying on the maximum half of physical memory is not
  enough; relying on free memory should bring the needed security margin
  while still using Argon2.
  There is no change for systems with active swap.
  Note, for very-low memory-constrained systems, a user should avoid
  memory-hard PBKDF completely (manually select legacy PBKDF2 instead
  of Argon2); cryptsetup does not change PBKDF automatically.

* Add the possibility to specify a directory for external LUKS2 token
  handlers (plugins).

  Use --external-tokens-path parameter in cryptsetup or
  crypt_token_set_external_path API call. The parameter is required to be
  an absolute path, and it is set per process context. This parameter is
  intended mainly for testing and developing new tokens.

* Do not allow reencryption/decryption on LUKS2 devices with
  authenticated encryption or hardware (OPAL) encryption.

  The operation fails later anyway; cryptsetup now detects incompatible
  parameters early.

* Do not fail LUKS format if the operation was interrupted on subsequent
  device wipe.

  Device wipe (used with authenticated encryption) is an optional
  operation and can be interrupted; not yet wiped part of the device will
  only report integrity errors (until overwritten with new data).

* Fix the LUKS2 keyslot option to be used while activating the device
  by a token.

  It can also be used to check if a specific token (--token-id) can
  unlock a specific keyslot (--key-slot option) when --test-passphrase
  option is specified.

* Properly report if the dm-verity device cannot be activated due to
  the inability to verify the signed root hash (ENOKEY).

* Fix to check passphrase for selected keyslot only when adding
  new keyslot.

  If the user specifies the exact keyslot to unlock, cryptsetup no longer
  checks other keyslots.

* Fix to not wipe the keyslot area before in-place overwrite.

  If the LUKS2 keyslot area has to be overwritten (due to lack of free
  space for keyslot swap), cryptsetup does not wipe the affected area as
  the first step (it will be overwritten later anyway).
  Previously, there was an unnecessary risk of losing the keyslot data
  if the code crashed before adding the new keyslot.

  If there is enough space in the keyslot area, cryptsetup never
  overwrites the older keyslot before the new one is written correctly
  (even if the keyslot number remains the same).

* bitlk: Fix segfaults when attempting to verify the volume key.

  Also, clarify that verifying the volume key is impossible without
  providing a passphrase or recovery key.

* Add --disable-blkid command line option to avoid blkid device check.

* Add support for the meson build system.

  All basic operations are supported (compile, test, and dist) with some
  minor exceptions; please see the meson manual for more info.

  The Meson build system will completely replace autotools in some future
  major release. Both autotools and meson build systems are supported,
  and the release archive is built with autotools.

* Fix wipe operation that overwrites the whole device if used for LUKS2
  header with no keyslot area.

  Formatting a LUKS2 device with no defined keyslots area is a very
  specific operation, and the code now properly recognizes such
  configuration.

* Fix luksErase to work with detached LUKS header.

* Disallow the use of internal kernel crypto driver names in "capi"
  specification.

  The common way to specify cipher mode in cryptsetup is to use
  cipher-mode-iv notation (like aes-xts-plain64).
  With the introduction of authenticated ciphers, we also allow
  "capi:<spec>" notation that is directly used by dm-crypt
  (e.g., capi:xts(aes)-plain64).

  CAPI specification was never intended to be used directly in the LUKS
  header; unfortunately, the code allowed it until now.
  Devices with CAPI specification in metadata can no longer be activated;
  header repair is required.

  CAPI specification could allow attackers to change the cipher
  specification to enforce loading some specific kernel crypto driver
  (for example, load driver with known side-channel issues).
  This can be problematic, specifically in a cloud environment
  (modifying LUKS2 metadata in container image).

  Thanks to Jan Wichelmann, Luca Wilke, and Thomas Eisenbarth from
  University of Luebeck for noticing the problems with this code.

* Fix reencryption to fail early for unknown cipher.

* tcrypt: Support new Blake2 hash for VeraCrypt.

  VeraCrypt introduces support for Blake2 PRF for PBKDF2; also support it
  in cryptsetup compatible tcrypt format.

* tcrypt: use hash values as substring for limiting KDF check.

  This allows the user to specify --hash sha or --hash blake2 to limit
  the KDF scan without the need to specify the full algorithm name
  (similar to cipher where we already use substring match).

* Add Aria cipher support and block size info.

  Aria cipher is similar to AES and is supported in Linux kernel crypto
  API in recent releases.
  It can be now used also for LUKS keyslot encryption.

* Do not decrease PBKDF parameters if the user forces them.

  If a user explicitly specifies PBKDF parameters (like iterations,
  used memory, or threads), do not limit them, even if it can cause
  resource exhaustion.
  The force options were mostly used for decreasing parameters, but it
  should work even opposite - despite the fact it can mean an
  out-of-memory crash.

  The only limits are hard limits per the PBKDF algorithm.

* Support OpenSSL 3.2 Argon2 implementation.

  Argon2 is now available directly in OpenSSL, so the code no longer
  needs to use libargon implementation.
  Configure script should detect this automatically.

* Add support for Argon2 from libgcrypt
  (requires yet unreleased gcrypt 1.11).

  Argon2 has been available since version 1.10, but we need version 1.11,
  which will allow empty passwords.

* Used Argon2 PBKDF implementation is now reported in debug mode
  in the cryptographic backend version. For native support in
  OpenSSL 3.2 or libgcrypt 1.11, "argon2" is displayed.
  If libargon2 is used, "cryptsetup libargon2" (for embedded
  library) or "external libargon2" is displayed.

* Link only libcrypto from OpenSSL.

  This reduces dependencies as other OpenSSL libraries are not needed.

* Disable reencryption for Direct-Access (DAX) devices.

  Linux kernel device-mapper cannot stack DAX/non-DAX devices in
  the mapping table, so online reencryption cannot work. Detect DAX
  devices and warn users during LUKS format. Also, DAX or persistent
  memory devices do not provide atomic sector updates; any single
  modification can corrupt the whole encryption block.

* Print a warning message if the device is not aligned to sector size.

  If a partition is resized after format, activation could fail when
  the device is not multiple of a sector size. Print at least a warning
  here, as the activation error message is visible only in kernel syslog.

* Fix sector size and integrity fields display for non-LUKS2 crypt
  devices for the status command.

* Fix suspend for LUKS2 with authenticated encryption (also suspend
  dm-integrity device underneath).

  This should stop the dm-integrity device from issuing journal updates
  and possibly corrupt data if the user also tries to modify the
  underlying device.

* Update keyring and locking documentation and LUKS2 specification
  for OPAL2 support.

Libcryptsetup API extensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The libcryptsetup API is backward compatible for all existing symbols.

New symbols:
  crypt_activate_by_keyslot_context
  crypt_format_luks2_opal
  crypt_get_hw_encryption_type
  crypt_get_hw_encryption_key_size
  crypt_keyslot_context_init_by_keyring
  crypt_keyslot_context_init_by_vk_in_keyring
  crypt_keyslot_context_init_by_signed_key
  crypt_resume_by_keyslot_context
  crypt_token_set_external_path
  crypt_set_keyring_to_link
  crypt_wipe_hw_opal

New defines (hw encryption status):
  CRYPT_SW_ONLY
  CRYPT_OPAL_HW_ONLY
  CRYPT_SW_AND_OPAL_HW

New keyslot context types:
  CRYPT_KC_TYPE_KEYRING
  CRYPT_KC_TYPE_VK_KEYRING
  CRYPT_KC_TYPE_SIGNED_KEY

New requirement flag:
  CRYPT_REQUIREMENT_OPAL