1 Cryptsetup 2.0.0 Release Notes
2 ==============================
3 Stable release with experimental features.
5 This version introduces a new on-disk LUKS2 format.
7 The legacy LUKS (referenced as LUKS1) will be fully supported
8 forever as well as a traditional and fully backward compatible format.
10 NOTE: This version changes soname of libcryptsetup library and increases
11 major version for all public symbols.
12 Most of the old functions are fully backward compatible, so only
13 recompilation of programs should be needed.
15 Please note that authenticated disk encryption, non-cryptographic
16 data integrity protection (dm-integrity), use of Argon2 Password-Based
17 Key Derivation Function and the LUKS2 on-disk format itself are new
18 features and can contain some bugs.
20 To provide all security features of authenticated encryption we need
21 better nonce-reuse resistant algorithm in kernel (see note below).
22 For now, please use authenticated encryption as experimental feature.
24 Please do not use LUKS2 without properly configured backup or in
25 production systems that need to be compatible with older systems.
27 Changes since version 2.0.0-RC1
28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29 * Limit KDF requested (for format) memory by available physical memory.
30 On some systems too high requested amount of memory causes OOM killer
31 to kill the process (instead of returning ENOMEM).
32 We never try to use more than half of available physical memory.
34 * Ignore device alignment if it is not multiple of minimal-io.
35 Some USB enclosures seems to report bogus topology info that
36 prevents to use LUKS detached header.
38 Changes since version 2.0.0-RC0
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41 * Enable to use system libargon2 instead of bundled version.
42 Renames --disable-argon2 to --disable-internal-argon2 option
43 and adds --enable-libargon2 flag to allow system libargon2.
45 * Changes in build system (Automake)
46 - The build system now uses non-recursive automake (except for tests).
47 (Tools binaries are now located in buildroot directory.)
48 - New --disable-cryptsetup option to disable build of cryptsetup tool.
49 - Enable build of cryptsetup-reencrypt by default.
51 * Install tmpfiles.d configuration for LUKS2 locking directory.
52 You can overwrite this using --with-tmpfilesdir configure option.
53 If your distro does not support tmpfiles.d directory, you have
54 to create locking directory (/run/lock/cryptsetup) in cryptsetup
55 package (or init scripts).
57 * Adds limited support for offline reencryption of LUKS2 format.
59 * Decrease size of testing images (and the whole release archive).
61 * Fixes for several memory leaks found by Valgrind and Coverity tools.
63 * Fixes for several typos in man pages and error messages.
65 * LUKS header file in luksFormat is now automatically created
68 * Do not allow resize if device size is not aligned to sector size.
70 Cryptsetup 2.0.0 RC0 Release Notes
71 ==================================
76 * New command integritysetup: support for the new dm-integrity kernel target.
78 The dm-integrity is a new kernel device-mapper target that introduces
79 software emulation of per-sector integrity fields on the disk sector level.
80 It is available since Linux kernel version 4.12.
82 The provided per-sector metadata fields can be used for storing a data
83 integrity checksum (for example CRC32).
84 The dm-integrity implements data journal that enforces atomic update
85 of a sector and its integrity metadata.
87 Integritysetup is a CLI utility that can setup standalone dm-integrity
88 devices (that internally check integrity of data).
90 Integritysetup is intended to be used for settings that require
91 non-cryptographic data integrity protection with no data encryption.
92 Fo setting integrity protected encrypted devices, see disk authenticated
95 Note that after formatting the checksums need to be initialized;
96 otherwise device reads will fail because of integrity errors.
97 Integritysetup by default tries to wipe the device with zero blocks
98 to avoid this problem. Device wipe can be time-consuming, you can skip
99 this step by specifying --no-wipe option.
100 (But note that not wiping device can cause some operations to fail
101 if a write is not multiple of page size and kernel page cache tries
102 to read sectors with not yet initialized checksums.)
104 The default setting is tag size 4 bytes per-sector and CRC32C protection.
105 To format device with these defaults:
106 $ integritysetup format <device>
107 $ integritysetup open <device> <name>
109 Note that used algorithm (unlike tag size) is NOT stored in device
110 kernel superblock and if you use different algorithm, you MUST specify
111 it in every open command, for example:
112 $ integritysetup format <device> --tag-size 32 --integrity sha256
113 $ integritysetup open <device> <name> --integrity sha256
115 For more info, see integrity man page.
117 * Veritysetup command can now format and activate dm-verity devices
118 that contain Forward Error Correction (FEC) (Reed-Solomon code is used).
119 This feature is used on most of Android devices already (available since
122 There are new options --fec-device, --fec-offset to specify data area
123 with correction code and --fec-roots that set Redd-Solomon generator roots.
124 This setting can be used for format command (veritysetup will calculate
125 and store RS codes) or open command (veritysetup configures kernel
126 dm-verity to use RS codes).
128 For more info see veritysetup man page.
130 * Support for larger sector sizes for crypt devices.
132 LUKS2 and plain crypt devices can be now configured with larger encryption
133 sector (typically 4096 bytes, sector size must be the power of two,
134 maximal sector size is 4096 bytes for portability).
135 Large sector size can decrease encryption overhead and can also help
136 with some specific crypto hardware accelerators that perform very
137 badly with 512 bytes sectors.
139 Note that if you configure such a larger sector of the device that does use
140 smaller physical sector, there is a possibility of a data corruption during
141 power fail (partial sector writes).
143 WARNING: If you use different sector size for a plain device after data were
144 stored, the decryption will produce garbage.
146 For LUKS2, the sector size is stored in metadata and cannot be changed later.
148 LUKS2 format and features
149 ~~~~~~~~~~~~~~~~~~~~~~~~~
150 The LUKS2 is an on-disk storage format designed to provide simple key
151 management, primarily intended for Full Disk Encryption based on dm-crypt.
153 The LUKS2 is inspired by LUKS1 format and in some specific situations (most
154 of the default configurations) can be converted in-place from LUKS1.
156 The LUKS2 format is designed to allow future updates of various
157 parts without the need to modify binary structures and internally
158 uses JSON text format for metadata. Compilation now requires the json-c library
159 that is used for JSON data processing.
161 On-disk format provides redundancy of metadata, detection
162 of metadata corruption and automatic repair from metadata copy.
164 NOTE: For security reasons, there is no redundancy in keyslots binary data
165 (encrypted keys) but the format allows adding such a feature in future.
167 NOTE: to operate correctly, LUKS2 requires locking of metadata.
168 Locking is performed by using flock() system call for images in file
169 and for block device by using a specific lock file in /run/lock/cryptsetup.
171 This directory must be created by distribution (do not rely on internal
172 fallback). For systemd-based distribution, you can simply install
173 scripts/cryptsetup.conf into tmpfiles.d directory.
175 For more details see LUKS2-format.txt and LUKS2-locking.txt in the docs
176 directory. (Please note this is just overview, there will be more formal
177 documentation later.)
182 LUKS2 allows using all possible configurations as LUKS1.
184 To format device as LUKS2, you have to add "--type luks2" during format:
186 $ cryptsetup luksFormat --type luks2 <device>
188 All commands issued later will recognize the new format automatically.
190 The newly added features in LUKS2 include:
192 * Authenticated disk (sector) encryption (EXPERIMENTAL)
194 Legacy Full disk encryption (FDE), for example, LUKS1, is a length-preserving
195 encryption (plaintext is the same size as a ciphertext).
196 Such FDE can provide data confidentiality, but cannot provide sound data
197 integrity protection.
199 Full disk authenticated encryption is a way how to provide both
200 confidentiality and data integrity protection. Integrity protection here means
201 not only detection of random data corruption (silent data corruption) but also
202 prevention of an unauthorized intentional change of disk sector content.
204 NOTE: Integrity protection of this type cannot prevent a replay attack.
205 An attacker can replace the device or its part of the old content, and it
207 If you need such protection, better use integrity protection on a higher layer.
209 For data integrity protection on the sector level, we need additional
210 per-sector metadata space. In LUKS2 this space is provided by a new
211 device-mapper dm-integrity target (available since kernel 4.12).
212 Here the integrity target provides only reliable per-sector metadata store,
213 and the whole authenticated encryption is performed inside dm-crypt stacked
214 over the dm-integrity device.
216 For encryption, Authenticated Encryption with Additional Data (AEAD) is used.
217 Every sector is processed as a encryption request of this format:
219 |----- AAD -------|------ DATA -------|-- AUTH TAG --|
220 | (authenticated) | (auth+encryption) | |
221 | sector_LE | IV | sector in/out | tag in/out |
223 AEAD encrypts the whole sector and also authenticates sector number
224 (to detect sector relocation) and also authenticates Initialization Vector.
226 AEAD encryption produces encrypted data and authentication tag.
227 The authenticated tag is then stored in per-sector metadata space provided
230 Most of the current AEAD algorithms requires IV as a nonce, value that is
231 never reused. Because sector number, as an IV, cannot be used in this
232 environment, we use a new random IV (IV is a random value generated by system
233 RNG on every write). This random IV is then stored in the per-sector metadata
236 Because the authentication tag (and IV) requires additional space, the device
237 provided for a user has less capacity. Also, the data journalling means that
238 writes are performed twice, decreasing throughput.
240 This integrity protection works better with SSDs. If you want to ignore
241 dm-integrity data journal (because journalling is performed on some higher
242 layer or you just want to trade-off performance to safe recovery), you can
243 switch journal off with --integrity-no-journal option.
244 (This flag can be stored persistently as well.)
246 Note that (similar to integritysetup) the device read will fail if
247 authentication tag is not initialized (no previous write).
248 By default cryptsetup run wipe of a device (writing zeroes) to initialize
249 authentication tags. This operation can be very time-consuming.
250 You can skip device wipe using --integrity-no-wipe option.
252 To format LUKS2 device with integrity protection, use new --integrity option.
254 For now, there are very few AEAD algorithms that can be used, and some
255 of them are known to be problematic. In this release we support only
256 a few of AEAD algorithms (options are for now hard coded), later this
257 extension will be completely algorithm-agnostic.
259 For testing of authenticated encryption, these algorithms work for now:
261 1) aes-xts-plain64 with hmac-sha256 or hmac-sha512 as the authentication tag.
262 (Common FDE mode + independent authentication tag. Authentication key
263 for HMAC is independently generated. This mode is very slow.)
264 $ cryptsetup luksFormat --type luks2 <device> --cipher aes-xts-plain64 --integrity hmac-sha256
266 2) aes-gcm-random (native AEAD mode)
267 DO NOT USE in production! The GCM mode uses only 96-bit nonce,
268 and possible collision means fatal security problem.
269 GCM mode has very good hardware support through AES-NI, so it is useful
270 for performance testing.
271 $ cryptsetup luksFormat --type luks2 <device> --cipher aes-gcm-random --integrity aead
273 3) ChaCha20 with Poly1305 authenticator (according to RFC7539)
274 $ cryptsetup luksFormat --type luks2 <device> --cipher chacha20-random --integrity poly1305
276 To specify AES128/AES256 just specify proper key size (without possible
277 authentication key). Other symmetric ciphers, like Serpent or Twofish,
278 should work as well. The mode 1) and 2) should be compatible with IEEE 1619.1
279 standard recommendation.
281 There will be better suitable authenticated modes available soon
282 For now we are just preparing framework to enable it (and hopefully improve security of FDE).
284 FDE authenticated encryption is not a replacement for filesystem layer
285 authenticated encryption. The goal is to provide at least something because
286 data integrity protection is often completely ignored in today systems.
288 * New memory-hard PBKDF
290 LUKS1 introduced Password-Based Key Derivation Function v2 as a tool to
291 increase attacker cost for a dictionary and brute force attacks.
292 The PBKDF2 uses iteration count to increase time of key derivation.
293 Unfortunately, with modern GPUs, the PBKDF2 calculations can be run
294 in parallel and PBKDF2 can no longer provide the best available protection.
295 Increasing iteration count just cannot prevent massive parallel dictionary
296 password attacks in long-term.
298 To solve this problem, a new PBKDF, based on so-called memory-hard functions
299 can be used. Key derivation with memory-hard function requires a certain
300 amount of memory to compute its output. The memory requirement is very
301 costly for GPUs and prevents these systems to operate effectively,
302 increasing cost for attackers.
304 LUKS2 introduces support for Argon2i and Argon2id as a PBKDF.
305 Argon2 is the winner of Password Hashing Competition and is currently
306 in final RFC draft specification.
308 For now, libcryptsetup contains the embedded copy of reference implementation
309 of Argon2 (that is easily portable to all architectures).
310 Later, once this function is available in common crypto libraries, it will
311 switch to external implementation. (This happened for LUKS1 and PBKDF2
313 With using reference implementation (that is not optimized for speed), there
314 is some performance penalty. However, using memory-hard PBKDF should still
315 significantly complicate GPU-optimized dictionary and brute force attacks.
317 The Argon2 uses three costs: memory, time (number of iterations) and parallel
319 Note that time and memory cost highly influences each other (accessing a lot
320 of memory takes more time).
322 There is a new benchmark that tries to calculate costs to take similar way as
323 in LUKS1 (where iteration is measured to take 1-2 seconds on user system).
324 Because now there are more cost variables, it prefers time cost (iterations)
325 and tries to find required memory that fits. (IOW required memory cost can be
326 lower if the benchmarks are not able to find required parameters.)
327 The benchmark cannot run too long, so it tries to approximate next step
330 For now, default LUKS2 PBKDF algorithm is Argon2i (data independent variant)
331 with memory cost set to 128MB, time to 800ms and parallel thread according
332 to available CPU cores but no more than 4.
334 All default parameters can be set during compile time and also set on
335 the command line by using --pbkdf, --pbkdf-memory, --pbkdf-parallel and
337 (Or without benchmark directly by using --pbkdf-force-iterations, see below.)
339 You can still use PBKDF2 even for LUKS2 by specifying --pbkdf pbkdf2 option.
340 (Then only iteration count is applied.)
342 * Use of kernel keyring
344 Kernel keyring is a storage for sensitive material (like cryptographic keys)
347 LUKS2 uses keyring for two major functions:
349 - To store volume key for dm-crypt where it avoids sending volume key in
350 every device-mapper ioctl structure. Volume key is also no longer directly
351 visible in a dm-crypt mapping table. The key is not available for the user
352 after dm-crypt configuration (obviously except direct memory scan).
353 Use of kernel keyring can be disabled in runtime by --disable-keyring option.
355 - As a tool to automatically unlock LUKS device if a passphrase is put into
356 kernel keyring and proper keyring token is configured.
358 This allows storing a secret (passphrase) to kernel per-user keyring by
359 some external tool (for example some TPM handler) and LUKS2, if configured,
360 will automatically search in the keyring and unlock the system.
361 For more info see Tokens section below.
364 The activation flags (like allow-discards) can be stored in metadata and used
365 automatically by all later activations (even without using crypttab).
367 To store activation flags permanently, use activation command with required
368 flags and add --persistent option.
370 For example, to mark device to always activate with TRIM enabled,
371 use (for LUKS2 type):
373 $ cryptsetup open <device> <name> --allow-discards --persistent
375 You can check persistent flags in dump command output:
377 $ cryptsetup luksDump <device>
379 * Tokens and auto-activation
381 A LUKS2 token is an object that can be described "how to get passphrase or key"
382 to unlock particular keyslot.
383 (Also it can be used to store any additional metadata, and with
384 the libcryptsetup interface it can be used to define user token types.)
386 Cryptsetup internally implements keyring token. Cryptsetup tries to use
387 available tokens before asking for the passphrase. For keyring token,
388 it means that if the passphrase is available under specified identifier
389 inside kernel keyring, the device is automatically activated using this
392 Example of using LUKS2 keyring token:
394 # Adding token to metadata with "my_token" identifier (by default it applies to all keyslots).
395 $ cryptsetup token add --key-description "my_token" <device>
397 # Storing passphrase to user keyring (this can be done by an external application)
398 $ echo -n <passphrase> | keyctl padd user my_token @u
400 # Now cryptsetup activates automatically if it finds correct passphrase
401 $ cryptsetup open <device> <name>
403 The main reason to use tokens this way is to separate possible hardware
404 handlers from cryptsetup code.
408 LUKS2 keyslot can have a new priority attribute.
409 The default is "normal". The "prefer" priority tell the keyslot to be tried
410 before other keyslots. Priority "ignore" means that keyslot will never be
411 used if not specified explicitly (it can be used for backup administrator
412 passwords that are used only situations when a user forgets own passphrase).
414 The priority of keyslot can be set with new config command, for example
415 $ cryptsetup config <device> --key-slot 1 --priority prefer
417 Setting priority to normal will reset slot to normal state.
419 * LUKS2 label and subsystem
421 The header now contains additional fields for label and subsystem (additional
422 label). These fields can be used similar to filesystem label and will be
423 visible in udev rules to possible filtering. (Note that blkid do not yet
424 contain the LUKS scanning code).
426 By default both labels are empty. Label and subsystem are always set together
427 (no option means clear the label) with the config command:
429 $ cryptsetup config <device> --label my_device --subsystem ""
431 * In-place conversion form LUKS1
433 To allow easy testing and transition to the new LUKS2 format, there is a new
434 convert command that allows in-place conversion from the LUKS1 format and,
435 if there are no incompatible options, also conversion back from LUKS2
438 Note this command can be used only on some LUKS1 devices (some device header
439 sizes are not supported).
440 This command is dangerous, never run it without header backup!
441 If something fails in the middle of conversion (IO error), the header
442 is destroyed. (Note that conversion requires move of keyslot data area to
445 To convert header in-place to LUKS2 format, use
446 $ cryptsetup convert <device> --type luks2
448 To convert it back to LUKS1 format, use
449 $ cryptsetup convert <device> --type luks1
451 You can verify LUKS version with luksDump command.
452 $ cryptsetup luksDump <device>
454 Note that some LUKS2 features will make header incompatible with LUKS1 and
455 conversion will be rejected (for example using new Argon2 PBKDF or integrity
456 extensions). Some minor attributes can be lost in conversion.
461 * Explicit KDF iterations count setting
463 With new PBKDF interface, there is also the possibility to setup PBKDF costs
464 directly, avoiding benchmarks. This can be useful if device is formatted to be
465 primarily used on a different system.
467 The option --pbkdf-force-iterations is available for both LUKS1 and LUKS2
468 format. Using this option can cause device to have either very low or very
470 In the first case it means bad protection to dictionary attacks, in the second
471 case, it can mean extremely high unlocking time or memory requirements.
472 Use only if you are sure what you are doing!
474 Not that this setting also affects iteration count for the key digest.
475 For LUKS1 iteration count for digest will be approximately 1/8 of requested
476 value, for LUKS2 and "pbkdf2" digest minimal PBKDF2 iteration count (1000)
477 will be used. You cannot set lower iteration count than the internal minimum
480 To format LUKS1 device with forced iteration count (and no benchmarking), use
481 $ cryptsetup luksFormat <device> --pbkdf-force-iterations 22222
483 For LUKS2 it is always better to specify full settings (do not rely on default
485 For example, we can set to use Argon2id with iteration cost 5, memory 128000
487 $ cryptsetup luksFormat --type luks2 <device> \
488 --pbkdf argon2id --pbkdf-force-iterations 5 --pbkdf-memory 128000 --pbkdf-parallel 1
492 Cryptsetup can now also open VeraCrypt device that uses Personal Iteration
493 Multiplier (PIM). PIM is an integer value that user must remember additionally
494 to passphrase and influences PBKDF2 iteration count (without it VeraCrypt uses
495 a fixed number of iterations).
497 To open VeraCrypt device with PIM settings, use --veracrypt-pim (to specify
498 PIM on the command line) or --veracrypt-query-pim to query PIM interactively.
500 * Support for plain64be IV
502 The plain64be is big-endian variant of plain64 Initialization Vector. It is
503 used in some images of hardware-based disk encryption systems. Supporting this
504 variant allows using dm-crypt to map such images through cryptsetup.
508 Cryptsetup now can mark device for deferred removal by using a new option
509 --deferred. This means that close command will not fail if the device is still
510 in use, but will instruct the kernel to remove the device automatically after
511 use count drops to zero (for example, once the filesystem is unmounted).
513 * A lot of updates to man pages and many minor changes that would make this
514 release notes too long ;-)
516 Libcryptsetup API changes
517 ~~~~~~~~~~~~~~~~~~~~~~~~~
519 These API functions were removed, libcryptsetup no longer handles password
520 retries from terminal (application should handle terminal operations itself):
521 crypt_set_password_callback;
523 crypt_set_password_retry;
524 crypt_set_password_verify;
526 This call is removed (no need to keep typo backward compatibility,
527 the proper function is crypt_set_iteration_time :-)
528 crypt_set_iterarion_time;
530 These calls were removed because are not safe, use per-context
531 error callbacks instead:
535 The PBKDF benchmark was replaced by a new function that uses new KDF structure
536 crypt_benchmark_kdf; (removed)
537 crypt_benchmark_pbkdf; (new API call)
539 These new calls are now exported, for details see libcryptsetup.h:
540 crypt_keyslot_add_by_key;
541 crypt_keyslot_set_priority;
542 crypt_keyslot_get_priority;
544 crypt_token_json_get;
545 crypt_token_json_set;
547 crypt_token_luks2_keyring_get;
548 crypt_token_luks2_keyring_set;
549 crypt_token_assign_keyslot;
550 crypt_token_unassign_keyslot;
551 crypt_token_register;
553 crypt_activate_by_token;
554 crypt_activate_by_keyring;
555 crypt_deactivate_by_name;
557 crypt_metadata_locking;
558 crypt_volume_key_keyring;
559 crypt_get_integrity_info;
560 crypt_get_sector_size;
561 crypt_persistent_flags_set;
562 crypt_persistent_flags_get;
563 crypt_set_pbkdf_type;
564 crypt_get_pbkdf_type;
570 Unfinished things & TODO for next releases
571 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
572 * There will be better documentation and examples.
574 * There will be some more formal definition of the threat model for integrity
575 protection. (And a link to some papers discussing integrity protection,
576 once it is, hopefully, accepted and published.)
578 * Offline re-encrypt tool LUKS2 support is currently limited.
579 There will be online LUKS2 re-encryption tool in future.
581 * Authenticated encryption will use new algorithms from CAESAR competition
582 (https://competitions.cr.yp.to/caesar.html) once these algorithms are available
583 in kernel (more on this later).
584 NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305)
585 in kernel have too small 96-bit nonces that are problematic with
586 randomly generated IVs (the collison probability is not negligible).
587 For the GCM, nonce collision is a fatal problem.
589 * Authenticated encryption do not set encryption for dm-integrity journal.
591 While it does not influence data confidentiality or integrity protection,
592 an attacker can get some more information from data journal or cause that
593 system will corrupt sectors after journal replay. (That corruption will be
596 * Some utilities (blkid, systemd-cryptsetup) have already support for LUKS
597 but not yet in released version (support in crypttab etc).
599 * There are some examples of user-defined tokens inside misc/luks2_keyslot_example
600 directory (like a simple external program that uses libssh to unlock LUKS2
601 using remote keyfile).
603 * The python binding (pycryptsetup) contains only basic functionality for LUKS1
604 (it is not updated for new features) and will be deprecated soon in favor
605 of python bindings to libblockdev library (that can already handle LUKS1 devices).