summaryrefslogtreecommitdiffstats
path: root/docs/v2.4.0-ReleaseNotes
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
commit1660d4b7a65d9ad2ce0deaa19d35579ca4084ac5 (patch)
tree6cf8220b628ebd2ccfc1375dd6516c6996e9abcc /docs/v2.4.0-ReleaseNotes
parentInitial commit. (diff)
downloadcryptsetup-upstream.tar.xz
cryptsetup-upstream.zip
Adding upstream version 2:2.6.1.upstream/2%2.6.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--docs/v2.4.0-ReleaseNotes302
1 files changed, 302 insertions, 0 deletions
diff --git a/docs/v2.4.0-ReleaseNotes b/docs/v2.4.0-ReleaseNotes
new file mode 100644
index 0000000..2d70e0a
--- /dev/null
+++ b/docs/v2.4.0-ReleaseNotes
@@ -0,0 +1,302 @@
+Cryptsetup 2.4.0 Release Notes
+==============================
+Stable release with new features and bug fixes.
+
+This version introduces support for external libraries
+(plugins) for handling LUKS2 token objects.
+
+Changes since version 2.3.6
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* External LUKS token plugins
+
+ A LUKS2 token is an object that can describe how to get a passphrase
+ to unlock a particular keyslot. The generic metadata format is part
+ of the LUKS2 specification.
+
+ Cryptsetup 2.4 adds the possibility to implement token handlers
+ in external libraries (possibly provided by other projects).
+
+ A token library allows cryptsetup to understand metadata and provide
+ basic operations. Currently external tokens may be used to unlock
+ keyslots for following CLI actions: open (luksOpen),
+ refresh (open --refresh), resize and dump (prints token specific
+ content).
+
+ LUKS2 devices cannot be resumed (luksResume action) via tokens yet.
+ Support for resume and other actions will be added later.
+
+ The library now provides an interface that automatically tries to load
+ an external library for a token object in LUKS2 metadata.
+
+ Token libraries should be installed in the cryptsetup subdirectory
+ (usually /lib*/cryptsetup). This path is configurable through
+ --with-luks2-external-tokens-path configure option.
+
+ The external plugin loading can be compiled entirely out if
+ --disable-external-tokens configure option is used. The external token
+ interface can also be disabled runtime on the command line by
+ --disable-external-tokens cryptsetup switch or by calling
+ crypt_token_external_disable() API function.
+
+ The name of the loaded token library is determined from the JSON LUKS
+ metadata token object type. For example, "ssh" token will load library
+ "libcryptsetup-token-ssh.so".
+
+ External projects can use this interface to handle specific hardware
+ without introducing additional dependencies to libcryptsetup core.
+
+ As of cryptsetup 2.4.0 release systemd project already merged upstream
+ native cryptsetup token handler for its systemd-tpm2 LUKS2 token
+ released originally in systemd-v248. The token can be created using
+ systemd-cryptenroll utility and devices may be manipulated either by
+ systemd-cryptsetup cli or by cryptsetup for actions listed above.
+
+ Other tokens like systemd-fido2 and systemd-pkcs11 are currently
+ in-review.
+
+* Experimental SSH token
+
+ As a demonstration of the external LUKS2 token interface, a new SSH
+ token handler and cryptsetup-ssh utility is now provided and compiled
+ by default.
+
+ Crypsetup SSH token allows using remote keyfile through SSH protocol
+ (it will authenticate through SSH certificates).
+
+ You can disable the build of this token library with
+ --disable-ssh-token configure option.
+
+To configure the token metadata, you need cryptsetup-ssh utility.
+
+Activation of the device is then performed by the cryptsetup utility.
+
+Example (how to activate LUKS2 through remote keyfile):
+
+ - configure existing LUKS2 device with keyslot activated by a keyfile
+ # cryptsetup luksAddKey <device> keyfile --key-slot 2
+
+ - store that keyfile on a remote system accessible through SSH
+
+ - configure SSH to use certificate for authentication
+
+ - add a LUKS2 token with cryptsetup-ssh utility:
+ # cryptsetup-ssh add <device>1 --key-slot 2 \
+ --ssh-server test-vm \
+ --ssh-user test \
+ --ssh-path /home/test/keyfile \
+ --ssh-keypath /home/test/.ssh/test_rsa_key
+
+ - you should see token metadata now with "cryptsetup luksDump ..."
+ ...
+ Tokens:
+ 0: ssh
+ ssh_server: test-vm
+ ssh_user: test
+ ssh_path: /home/test/keyfile
+ ssh_key_path: /home/test/.ssh/test_rsa_key
+ Keyslot: 2
+
+
+ - activation now should be automatic
+ # cryptsetup open <device> test --verbose
+ SSH token initiating ssh session.
+ Key slot 2 unlocked.
+ Command successful.
+
+ - to remove a token, you can use "cryptsetup token remove" command
+ (no plugin library required)
+
+ Please note SSH token is just demonstration of plugin interface API,
+ it is an EXPERIMENTAL feature.
+
+* Add cryptsetup --token-type parameter.
+
+ It restricts token type to the parameter value in case no specific
+ token-id is selected.
+
+* Support for token based activation with PIN.
+
+ If specific token requires PIN to unlock keyslot passphrase and
+ --token-only parameter was used cryptsetup asks for additional
+ token PIN.
+
+* Respect keyslot priority with token-based activation.
+
+* Default LUKS2 PBKDF is now Argon2id
+
+ Cryptsetup LUKS2 was using Argon2 while there were two versions,
+ data-independent (Argon2i) suitable for the KDF use case and
+ Argon2d (data-dependent). Later Argon2id was introduced as a new
+ mandatory algorithm.
+
+ We switched the password-based key derivation algorithms
+ following the latest version of Argon2 RFC draft
+ (https://datatracker.ietf.org/doc/draft-irtf-cfrg-argon2/) to Argon2id
+ (from Argon2i) as it is the mandatory and primary version
+ of the Argon2 algorithm.
+
+ There is no need to modify older containers; the main reason is that
+ RFC makes Argon2id the primary variant, while Argon2i subvariant is
+ only optional.
+ Argon2id provides better protection to side-channel attacks while
+ still providing protection to time-memory tradeoffs.
+
+ We will switch to OpenSSL implementation once it is available.
+ With a crystal ball as a reference, it could happen early in
+ OpenSSL 3.1 release.
+ Watch https://github.com/openssl/openssl/issues/4091.
+
+* Increase minimal memory cost for Argon2 benchmark to 64MiB.
+
+ This patch increases the benchmarking value to 64 MiB (as minimal
+ suggested values in Argon2 RFC). For compatibility reasons, we still
+ allow older limits if set by a parameter.
+
+ NOTE: Argon2 RFC draft defines suggested parameters for disk
+ encryption, but the LUKS2 approach is slightly different. We need to
+ provide platform-independent values. The values in the draft expect
+ 64bit systems (suggesting using 6 GiB of RAM). In comparison, we need
+ to provide compatibility with all 32bit systems, so allocating more
+ than 4GiB memory is not an option for LUKS2.
+
+ The maximal limit in LUKS2 stays for 4 GiB, and by default LUKS2 PBKDF
+ benchmarking sets maximum to 1 GIB, preferring an increase of CPU cost
+ while running benchmark
+
+* Autodetect optimal encryption sector size on LUKS2 format.
+
+ While the support for larger encryption sectors is supported
+ for several releases, it required an additional parameter.
+
+ Code now uses automatic detection of 4096-bytes native sector devices
+ and automatically enables 4096-bytes encryption size for LUKS2.
+
+ If no setor size option is used, sector size is detected
+ automatically by cryptsetup. For libcryptsetup API, autodetection
+ happens once you specify sector_size to 0.
+
+ NOTE: crypt_format() function runs autodetection ONLY if you
+ recompile your application to the new API symbol version.
+ For backward compatibility, older applications ignore this parameter.
+
+* Use VeraCrypt option by default and add --disable-veracrypt option.
+
+ While TrueCrypt is no longer developed and supported since 2014,
+ VeraCrypt devices (a successor of TrueCrypt) are much more used today.
+
+ Default is now to support VeraCrypt format (in addition to TrueCrypt),
+ making the --veracrypt option obsolete (ignored as it is the default).
+
+ If you need to disable VeraCrypt support, use the new option
+ --disable-veracrypt.
+
+ This option increases the time to recognize wrong passwords because
+ some VeraCrypt modes use a high PBKDF2 iteration count, and the code
+ must try all variants. This could be limited by using --hash and
+ --cipher options mentioned below.
+
+* Support --hash and --cipher to limit opening time for TCRYPT type
+
+ If a user knows which particular PBKDF2 hash or cipher is used for
+ TrueCrypt/VeraCrypt container, TCRYPT format now supports --hash and
+ --cipher option.
+
+ Note the value means substring (all cipher chains containing
+ the cipher substring are tried).
+
+ For example, you can use
+ # cryptsetup tcryptDump --hash sha512 <container>
+
+ Note: to speed up the scan, the hash option (used for PBKDF)2 matters.
+ Cipher variants are scanned very quickly.
+
+ Use with care.
+ It can reveal some sensitive attributes of the container!
+
+* Fixed default OpenSSL crypt backend support for OpenSSL3.
+
+ For OpenSSL version 3, we need to load legacy provider for older hash
+ and ciphers. For example, RIPEMD160 and Whirlpool hash algorithms are
+ no longer available by default.
+
+ NOTE: the plain format still uses RIPEMD160 for password hashing by
+ default. Changing the default would cause incompatibilities for many
+ old systems. Nevertheless, such a change will be needed very soon.
+
+* integritysetup: add integrity-recalculate-reset flag.
+
+ The new dm-integrity option in kernel 5.13 can restart recalculation
+ from the beginning of the device.
+ It can be used to change the integrity checksum function.
+
+ New integritysetup --integrity-recalculate-reset option is added to
+ integritysetup, and CRYPT_ACTIVATE_RECALCULATE_RESET flag to API.
+
+* cryptsetup: retains keyslot number in luksChangeKey for LUKS2.
+
+ In LUKS1, any change in keyslot means keyslot number change.
+
+ In LUKS2, we can retain the keyslot number.
+ Now luksKeyChange and crypt_keyslot_change_by_passphrase() API
+ retains keyslot number for LUKS2 by default.
+
+* Fix cryptsetup resize using LUKS2 tokens.
+
+ Fix a bug where cryptsetup needlessly asked for a passphrase even
+ though the volume key was already unlocked via LUKS2 token.
+
+* Add close --deferred and --cancel-deferred options.
+
+ All command-line utilities now understand deferred options for the
+ close command. Deferred close means that the device is removed
+ automagically after the last user closed the device.
+ Cancel deferred means to cancel this operation (so the device remains
+ active even if there a no longer active users).
+
+ CRYPT_DEACTIVATE_DEFERRED and CRYPT_DEACTIVATE_DEFERRED_CANCEL flags
+ are now available for API.
+
+* Rewritten command-line option parsing to avoid libpopt arguments
+ memory leaks.
+
+ Note: some distributions use patched lipopt that still leaks memory
+ inside internal code (see Debian bug 941814).
+
+* Add --test-args option.
+
+ New --test-args option can be used for syntax checking for valid
+ command-line arguments with no actions performed.
+ Note that it cannot detect unknown algorithm names and similar where
+ we need call API functions.
+
+* veritysetup: add --root-hash-file option
+ Allow passing the root hash via a file, rather than verbatim on
+ the command line, for the open, verify, and format actions.
+
+* libcryptsetup C API extensions (see libcryptsetup.h for details)
+
+ - crypt_logf - a printf like log function
+ - crypt_dump_json - dump LUKS2 metadata in JSON format
+ - crypt_header_is_detached - check if context use detached header
+ - crypt_token_max - get maximal tokens number
+ - crypt_token_external_path - get path for plugins (or NULL)
+ - crypt_token_external_disable - disable runtime support for plugins
+ - crypt_activate_by_token_pin - activate by token with additional PIN
+ - crypt_reencrypt_run - fixed API for deprecated crypt_reencrypt
+
+ The token plugin library interface cosists from these versioned
+ exported symbols (for details see header file and SSH token example):
+ cryptsetup_token_open
+ cryptsetup_token_open_pin
+ cryptsetup_token_buffer_free
+ cryptsetup_token_validate
+ cryptsetup_token_dump
+ cryptsetup_token_version
+
+ Since version 2.4 libcryptsetup uses exact symbol versioning
+ Newly introduced functions have CRYPTSETUP_2.4 namespace (the old
+ symbol always used CRYPTSETUP_2.0).
+ There is no change in soname (the library is backward compatible).
+
+ * Many fixes and additions to documentation and man pages.