Cryptsetup 2.8.7-rc1 Release Notes
==================================
Stable bug-fix release candidate that solves several compatibility issues.

All users of cryptsetup must upgrade to this version.

Changes since version 2.8.6
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Changes related to Linux kernel AF_ALG crypto userspace interface deprecation
  Linux kernel maintainers decided to deprecate the AF_ALG interface, which was heavily used
  by cryptsetup, with the plan to remove it (or severely limit it) for security reasons.
  Libcryptsetup uses userspace (primarily via AF_ALG) for processing LUKS keyslots and for on-disk
  metadata handling for other formats. Using AF_ALG ensured that the same set of algorithms
  is present in userspace and later in-kernel for device activation.

  While libcryptsetup has a concept of fallback to userspace library, it was not used in
  all situations.

  In this version, libcryptsetup can use a userspace crypto library, AF_ALG (if present), and
  in some situations (LUKS keyslots), fallback to a temporary dm-crypt mapping. The last option
  requires root privileges. This ensures that most operations will continue to work even when
  AF_ALG is disabled or limited.

  Unfortunately, removing the AF_ALG could cause severe compatibility issues if the required
  algorithm (or encryption mode) is not implemented in the userspace library. A typical example is
  the Adiantum cipher, which is implemented only in the kernel. Also, ciphers like Serpent or
  Twofish (in XTS mode) are missing from several userspace libraries. The cryptsetup benchmark
  for ciphers is no longer available if the AF_ALG interface is unavailable.

* Keyring handling changes.
  Libcryptsetup can use the kernel keyring to transfer the volume key into the kernel, avoiding
  sending it as a parameter to system calls.

  In previous versions, the volume key could be stored in the thread keyring, which should be
  removed when the process exits. Unfortunately, the thread keyring can remain active in some
  situations (such as when allocating a loop device). This could be a problem after calling
  luksSuspend when the volume key could remain in memory.

  Instead of loading volume keys directly into the thread keyring, cryptsetup now creates
  an intermediary keyring linked into the thread keyring and loads volume keys there.
  The intermediary keyring is now removed in the libcryptsetup context destructor
  (usually on application exit).

  Note that in previous versions, volume keys persisted until the process exited (even after
  the context destructor was called).

* Changes related to possible LUKS volume key digest collisions.
  LUKS on-disk metadata uses a volume key digest generated by the PBKDF2 key-derivation algorithm
  to verify that the decrypted volume key is valid. The use of PBKDF2 (instead of a more suitable
  cryptographic digest algorithm) is part of the original LUKS design. It was retained for LUKS2
  for compatibility (it allows easy in-place conversion).

  However, PBKDF2 has several design flaws. As it is based on HMAC (Hash-based Message
  Authentication Code), it also inherits the weak-key HMAC issue. In HMAC, the key can be
  arbitrarily long. If the key is shorter than the hash internal block size, it is padded with
  zeroes to a full block size. This flawed padding causes any HMAC key (shorter than the specified
  block size) to collide with keys that have added trailing zeroes. A collision means that HMAC
  (and PBKDF2) has the same output for colliding keys.

  In LUKS, a PBKDF2 collision is not a security issue; it cannot compromise data confidentiality.
  Moreover, the colliding key has a different length and should be rejected by the underlying block
  cipher. Unfortunately, in some reencryption scenarios (e.g., a header without keyslots),
  a collision key could be accepted, leading to possible data corruption.

  Code now always validates the expected key length.
  This validation is now strictly implemented in LUKS metadata processing.

  In the long term, LUKS will need to upgrade to a better volume key digest algorithm, but that
  will make the format backward-incompatible.

* Support Aria and Camellia ciphers in the libgcrypt cryptographic backend.

* Fix pkg-config library entry for the Mbed TLS cryptographic backend.

* Better document CRYPT_VOLUME_KEY_NO_SEGMENT and CRYPT_VOLUME_KEY_DIGEST_REUSE API flags.
  The keyslot created with the CRYPT_VOLUME_KEY_NO_SEGMENT flag must always be unbound
  (not assigned to the default data segment). The use of the CRYPT_VOLUME_KEY_DIGEST_REUSE flag
  does not make sense without the CRYPT_VOLUME_KEY_NO_SEGMENT or CRYPT_VOLUME_KEY_SET flags.

* Fix several possible corner cases in OpenSSL cryptographic backend (based on AI analysis).
  These include checking before casting from size_t to int, checking return values for the old
  OpenSSL HMAC API, avoiding sending a partial buffer to the caller if the operation fails,
  and explicitly checking for buffer length overflow. Most of these cannot happen in
  the libcryptsetup context, but the cryptographic backend can be used for other projects.

* Code hardening based on various AI analysis reports.
  Including a fix for snprintf truncation in libdevmapper code, avoiding possible leak of JSON
  keyslot object on error path, and a fix for reencryption temporary device name.

* Fix jq (JSON commandline processor) use in testing scripts.
  After the security update for jq, it no longer processes JSON with trailing zeroes.
  Regression test scripts were updated to avoid using this scenario.