1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
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.
|
