diff options
Diffstat (limited to 'docs/v2.7.0-ReleaseNotes')
| -rw-r--r-- | docs/v2.7.0-ReleaseNotes | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/docs/v2.7.0-ReleaseNotes b/docs/v2.7.0-ReleaseNotes new file mode 100644 index 0000000..6af199b --- /dev/null +++ b/docs/v2.7.0-ReleaseNotes @@ -0,0 +1,437 @@ +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 |