1 Cryptsetup 2.4.0 Release Notes
2 ==============================
3 Stable release with new features and bug fixes.
5 This version introduces support for external libraries
6 (plugins) for handling LUKS2 token objects.
8 Changes since version 2.3.6
9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
11 * External LUKS token plugins
13 A LUKS2 token is an object that can describe how to get a passphrase
14 to unlock a particular keyslot. The generic metadata format is part
15 of the LUKS2 specification.
17 Cryptsetup 2.4 adds the possibility to implement token handlers
18 in external libraries (possibly provided by other projects).
20 A token library allows cryptsetup to understand metadata and provide
21 basic operations. Currently external tokens may be used to unlock
22 keyslots for following CLI actions: open (luksOpen),
23 refresh (open --refresh), resize and dump (prints token specific
26 LUKS2 devices cannot be resumed (luksResume action) via tokens yet.
27 Support for resume and other actions will be added later.
29 The library now provides an interface that automatically tries to load
30 an external library for a token object in LUKS2 metadata.
32 Token libraries should be installed in the cryptsetup subdirectory
33 (usually /lib*/cryptsetup). This path is configurable through
34 --with-luks2-external-tokens-path configure option.
36 The external plugin loading can be compiled entirely out if
37 --disable-external-tokens configure option is used. The external token
38 interface can also be disabled runtime on the command line by
39 --disable-external-tokens cryptsetup switch or by calling
40 crypt_token_external_disable() API function.
42 The name of the loaded token library is determined from the JSON LUKS
43 metadata token object type. For example, "ssh" token will load library
44 "libcryptsetup-token-ssh.so".
46 External projects can use this interface to handle specific hardware
47 without introducing additional dependencies to libcryptsetup core.
49 As of cryptsetup 2.4.0 release systemd project already merged upstream
50 native cryptsetup token handler for its systemd-tpm2 LUKS2 token
51 released originally in systemd-v248. The token can be created using
52 systemd-cryptenroll utility and devices may be manipulated either by
53 systemd-cryptsetup cli or by cryptsetup for actions listed above.
55 Other tokens like systemd-fido2 and systemd-pkcs11 are currently
58 * Experimental SSH token
60 As a demonstration of the external LUKS2 token interface, a new SSH
61 token handler and cryptsetup-ssh utility is now provided and compiled
64 Crypsetup SSH token allows using remote keyfile through SSH protocol
65 (it will authenticate through SSH certificates).
67 You can disable the build of this token library with
68 --disable-ssh-token configure option.
70 To configure the token metadata, you need cryptsetup-ssh utility.
72 Activation of the device is then performed by the cryptsetup utility.
74 Example (how to activate LUKS2 through remote keyfile):
76 - configure existing LUKS2 device with keyslot activated by a keyfile
77 # cryptsetup luksAddKey <device> keyfile --key-slot 2
79 - store that keyfile on a remote system accessible through SSH
81 - configure SSH to use certificate for authentication
83 - add a LUKS2 token with cryptsetup-ssh utility:
84 # cryptsetup-ssh add <device>1 --key-slot 2 \
85 --ssh-server test-vm \
87 --ssh-path /home/test/keyfile \
88 --ssh-keypath /home/test/.ssh/test_rsa_key
90 - you should see token metadata now with "cryptsetup luksDump ..."
96 ssh_path: /home/test/keyfile
97 ssh_key_path: /home/test/.ssh/test_rsa_key
101 - activation now should be automatic
102 # cryptsetup open <device> test --verbose
103 SSH token initiating ssh session.
107 - to remove a token, you can use "cryptsetup token remove" command
108 (no plugin library required)
110 Please note SSH token is just demonstration of plugin interface API,
111 it is an EXPERIMENTAL feature.
113 * Add cryptsetup --token-type parameter.
115 It restricts token type to the parameter value in case no specific
116 token-id is selected.
118 * Support for token based activation with PIN.
120 If specific token requires PIN to unlock keyslot passphrase and
121 --token-only parameter was used cryptsetup asks for additional
124 * Respect keyslot priority with token-based activation.
126 * Default LUKS2 PBKDF is now Argon2id
128 Cryptsetup LUKS2 was using Argon2 while there were two versions,
129 data-independent (Argon2i) suitable for the KDF use case and
130 Argon2d (data-dependent). Later Argon2id was introduced as a new
133 We switched the password-based key derivation algorithms
134 following the latest version of Argon2 RFC draft
135 (https://datatracker.ietf.org/doc/draft-irtf-cfrg-argon2/) to Argon2id
136 (from Argon2i) as it is the mandatory and primary version
137 of the Argon2 algorithm.
139 There is no need to modify older containers; the main reason is that
140 RFC makes Argon2id the primary variant, while Argon2i subvariant is
142 Argon2id provides better protection to side-channel attacks while
143 still providing protection to time-memory tradeoffs.
145 We will switch to OpenSSL implementation once it is available.
146 With a crystal ball as a reference, it could happen early in
148 Watch https://github.com/openssl/openssl/issues/4091.
150 * Increase minimal memory cost for Argon2 benchmark to 64MiB.
152 This patch increases the benchmarking value to 64 MiB (as minimal
153 suggested values in Argon2 RFC). For compatibility reasons, we still
154 allow older limits if set by a parameter.
156 NOTE: Argon2 RFC draft defines suggested parameters for disk
157 encryption, but the LUKS2 approach is slightly different. We need to
158 provide platform-independent values. The values in the draft expect
159 64bit systems (suggesting using 6 GiB of RAM). In comparison, we need
160 to provide compatibility with all 32bit systems, so allocating more
161 than 4GiB memory is not an option for LUKS2.
163 The maximal limit in LUKS2 stays for 4 GiB, and by default LUKS2 PBKDF
164 benchmarking sets maximum to 1 GIB, preferring an increase of CPU cost
165 while running benchmark
167 * Autodetect optimal encryption sector size on LUKS2 format.
169 While the support for larger encryption sectors is supported
170 for several releases, it required an additional parameter.
172 Code now uses automatic detection of 4096-bytes native sector devices
173 and automatically enables 4096-bytes encryption size for LUKS2.
175 If no setor size option is used, sector size is detected
176 automatically by cryptsetup. For libcryptsetup API, autodetection
177 happens once you specify sector_size to 0.
179 NOTE: crypt_format() function runs autodetection ONLY if you
180 recompile your application to the new API symbol version.
181 For backward compatibility, older applications ignore this parameter.
183 * Use VeraCrypt option by default and add --disable-veracrypt option.
185 While TrueCrypt is no longer developed and supported since 2014,
186 VeraCrypt devices (a successor of TrueCrypt) are much more used today.
188 Default is now to support VeraCrypt format (in addition to TrueCrypt),
189 making the --veracrypt option obsolete (ignored as it is the default).
191 If you need to disable VeraCrypt support, use the new option
194 This option increases the time to recognize wrong passwords because
195 some VeraCrypt modes use a high PBKDF2 iteration count, and the code
196 must try all variants. This could be limited by using --hash and
197 --cipher options mentioned below.
199 * Support --hash and --cipher to limit opening time for TCRYPT type
201 If a user knows which particular PBKDF2 hash or cipher is used for
202 TrueCrypt/VeraCrypt container, TCRYPT format now supports --hash and
205 Note the value means substring (all cipher chains containing
206 the cipher substring are tried).
208 For example, you can use
209 # cryptsetup tcryptDump --hash sha512 <container>
211 Note: to speed up the scan, the hash option (used for PBKDF)2 matters.
212 Cipher variants are scanned very quickly.
215 It can reveal some sensitive attributes of the container!
217 * Fixed default OpenSSL crypt backend support for OpenSSL3.
219 For OpenSSL version 3, we need to load legacy provider for older hash
220 and ciphers. For example, RIPEMD160 and Whirlpool hash algorithms are
221 no longer available by default.
223 NOTE: the plain format still uses RIPEMD160 for password hashing by
224 default. Changing the default would cause incompatibilities for many
225 old systems. Nevertheless, such a change will be needed very soon.
227 * integritysetup: add integrity-recalculate-reset flag.
229 The new dm-integrity option in kernel 5.13 can restart recalculation
230 from the beginning of the device.
231 It can be used to change the integrity checksum function.
233 New integritysetup --integrity-recalculate-reset option is added to
234 integritysetup, and CRYPT_ACTIVATE_RECALCULATE_RESET flag to API.
236 * cryptsetup: retains keyslot number in luksChangeKey for LUKS2.
238 In LUKS1, any change in keyslot means keyslot number change.
240 In LUKS2, we can retain the keyslot number.
241 Now luksKeyChange and crypt_keyslot_change_by_passphrase() API
242 retains keyslot number for LUKS2 by default.
244 * Fix cryptsetup resize using LUKS2 tokens.
246 Fix a bug where cryptsetup needlessly asked for a passphrase even
247 though the volume key was already unlocked via LUKS2 token.
249 * Add close --deferred and --cancel-deferred options.
251 All command-line utilities now understand deferred options for the
252 close command. Deferred close means that the device is removed
253 automagically after the last user closed the device.
254 Cancel deferred means to cancel this operation (so the device remains
255 active even if there a no longer active users).
257 CRYPT_DEACTIVATE_DEFERRED and CRYPT_DEACTIVATE_DEFERRED_CANCEL flags
258 are now available for API.
260 * Rewritten command-line option parsing to avoid libpopt arguments
263 Note: some distributions use patched lipopt that still leaks memory
264 inside internal code (see Debian bug 941814).
266 * Add --test-args option.
268 New --test-args option can be used for syntax checking for valid
269 command-line arguments with no actions performed.
270 Note that it cannot detect unknown algorithm names and similar where
271 we need call API functions.
273 * veritysetup: add --root-hash-file option
274 Allow passing the root hash via a file, rather than verbatim on
275 the command line, for the open, verify, and format actions.
277 * libcryptsetup C API extensions (see libcryptsetup.h for details)
279 - crypt_logf - a printf like log function
280 - crypt_dump_json - dump LUKS2 metadata in JSON format
281 - crypt_header_is_detached - check if context use detached header
282 - crypt_token_max - get maximal tokens number
283 - crypt_token_external_path - get path for plugins (or NULL)
284 - crypt_token_external_disable - disable runtime support for plugins
285 - crypt_activate_by_token_pin - activate by token with additional PIN
286 - crypt_reencrypt_run - fixed API for deprecated crypt_reencrypt
288 The token plugin library interface cosists from these versioned
289 exported symbols (for details see header file and SSH token example):
290 cryptsetup_token_open
291 cryptsetup_token_open_pin
292 cryptsetup_token_buffer_free
293 cryptsetup_token_validate
294 cryptsetup_token_dump
295 cryptsetup_token_version
297 Since version 2.4 libcryptsetup uses exact symbol versioning
298 Newly introduced functions have CRYPTSETUP_2.4 namespace (the old
299 symbol always used CRYPTSETUP_2.0).
300 There is no change in soname (the library is backward compatible).
302 * Many fixes and additions to documentation and man pages.