1 Cryptsetup 2.1.0 Release Notes
2 ==============================
3 Stable release with new features and bug fixes.
5 Cryptsetup 2.1 version uses a new on-disk LUKS2 format as the default
6 LUKS format and increases default LUKS2 header size.
8 The legacy LUKS (referenced as LUKS1) will be fully supported forever
9 as well as a traditional and fully backward compatible format.
11 When upgrading a stable distribution, please use configure option
12 --with-default-luks-format=LUKS1 to maintain backward compatibility.
14 This release also switches to OpenSSL as a default cryptographic
15 backend for LUKS header processing. Use --with-crypto_backend=gcrypt
16 configure option if you need to preserve legacy libgcrypt backend.
18 Please do not use LUKS2 without properly configured backup or
19 in production systems that need to be compatible with older systems.
21 Changes since version 2.0.6
22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
24 * The default for cryptsetup LUKS format action is now LUKS2.
25 You can use LUKS1 with cryptsetup option --type luks1.
27 * The default size of the LUKS2 header is increased to 16 MB.
28 It includes metadata and the area used for binary keyslots;
29 it means that LUKS header backup is now 16MB in size.
31 Note, that used keyslot area is much smaller, but this increase
32 of reserved space allows implementation of later extensions
33 (like online reencryption).
34 It is fully compatible with older cryptsetup 2.0.x versions.
35 If you require to create LUKS2 header with the same size as
36 in the 2.0.x version, use --offset 8192 option for luksFormat
37 (units are in 512-bytes sectors; see notes below).
39 * Cryptsetup now doubles LUKS default key size if XTS mode is used
40 (XTS mode uses two internal keys). This does not apply if key size
41 is explicitly specified on the command line and it does not apply
43 This fixes a confusion with AES and 256bit key in XTS mode where
44 code used AES128 and not AES256 as often expected.
46 Also, the default keyslot encryption algorithm (if cannot be derived
47 from data encryption algorithm) is now available as configure
48 options --with-luks2-keyslot-cipher and --with-luks2-keyslot-keybits.
49 The default is aes-xts-plain64 with 2 * 256-bits key.
51 * Default cryptographic backend used for LUKS header processing is now
52 OpenSSL. For years, OpenSSL provided better performance for PBKDF.
54 NOTE: Cryptsetup/libcryptsetup supports several cryptographic
55 library backends. The fully supported are libgcrypt, OpenSSL and
56 kernel crypto API. FIPS mode extensions are maintained only for
57 libgcrypt and OpenSSL. Nettle and NSS are usable only for some
58 subset of algorithms and cannot provide full backward compatibility.
59 You can always switch to other backends by using a configure switch,
60 for libgcrypt (compatibility for older distributions) use:
61 --with-crypto_backend=gcrypt
63 * The Python bindings are no longer supported and the code was removed
64 from cryptsetup distribution. Please use the libblockdev project
65 that already covers most of the libcryptsetup functionality
68 * Cryptsetup now allows using --offset option also for luksFormat.
69 It means that the specified offset value is used for data offset.
70 LUKS2 header areas are automatically adjusted according to this value.
71 (Note units are in 512-byte sectors due to the previous definition
72 of this option in plain mode.)
73 This option can replace --align-payload with absolute alignment value.
75 * Cryptsetup now supports new refresh action (that is the alias for
77 It allows changes of parameters for an active device (like root
78 device mapping), for example, it can enable or disable TRIM support
80 It is supported for LUKS1, LUKS2, plain and loop-AES devices.
82 * Integritysetup now supports mode with detached data device through
83 new --data-device option.
84 Since kernel 4.18 there is a possibility to specify external data
85 device for dm-integrity that stores all integrity tags.
87 * Integritysetup now supports automatic integrity recalculation
88 through new --integrity-recalculate option.
89 Linux kernel since version 4.18 supports automatic background
90 recalculation of integrity tags for dm-integrity.
92 Other changes and fixes
93 ~~~~~~~~~~~~~~~~~~~~~~~
95 * Fix for crypt_wipe call to allocate space if the header is backed
96 by a file. This means that if you use detached header file, it will
97 now have always the full size after luksFormat, even if only
98 a few keyslots are used.
100 * Fixes to offline cryptsetup-reencrypt to preserve LUKS2 keyslots
101 area sizes after reencryption and fixes for some other issues when
102 creating temporary reencryption headers.
104 * Added some FIPS mode workarounds. We cannot (yet) use Argon2 in
105 FIPS mode, libcryptsetup now fallbacks to use PBKDF2 in FIPS mode.
107 * Rejects conversion to LUKS1 if PBKDF2 hash algorithms
110 * The hash setting on command line now applies also to LUKS2 PBKDF2
111 digest. In previous versions, the LUKS2 key digest used PBKDF2-SHA256
112 (except for converted headers).
114 * Allow LUKS2 keyslots area to increase if data offset allows it.
115 Cryptsetup can fine-tune LUKS2 metadata area sizes through
116 --luks2-metadata-size=BYTES and --luks2-keyslots-size=BYTES.
117 Please DO NOT use these low-level options until you need it for
118 some very specific additional feature.
119 Also, the code now prints these LUKS2 header area sizes in dump
122 * For LUKS2, keyslot can use different encryption that data with
123 new options --keyslot-key-size=BITS and --keyslot-cipher=STRING
124 in all commands that create new LUKS keyslot.
125 Please DO NOT use these low-level options until you need it for
126 some very specific additional feature.
128 * Code now avoids data flush when reading device status through
131 * The Nettle crypto backend and the userspace kernel crypto API
132 backend were enhanced to allow more available hash functions
133 (like SHA3 variants).
135 * Upstream code now does not require libgcrypt-devel
136 for autoconfigure, because OpenSSL is the default.
137 The libgcrypt does not use standard pkgconfig detection and
138 requires specific macro (part of libgcrypt development files)
139 to be always present during autoconfigure.
140 With other crypto backends, like OpenSSL, this makes no sense,
141 so this part of autoconfigure is now optional.
143 * Cryptsetup now understands new --debug-json option that allows
144 an additional dump of some JSON information. These are no longer
145 present in standard debug output because it could contain some
146 specific LUKS header parameters.
148 * The luksDump contains the hash algorithm used in Anti-Forensic
151 * All debug messages are now sent through configured log callback
152 functions, so an application can easily use own debug messages
153 handling. In previous versions debug messages were printed directly
156 Libcryptsetup API additions
157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
159 These new calls are now exported, for details see libcryptsetup.h:
161 * crypt_init_data_device
162 * crypt_get_metadata_device_name
163 functions to init devices with separate metadata and data device
164 before a format function is called.
166 * crypt_set_data_offset
167 sets the data offset for LUKS to the specified value
169 It should replace alignment calculation in LUKS param structures.
171 * crypt_get_metadata_size
172 * crypt_set_metadata_size
173 allows to set/get area sizes in LUKS header
174 (according to specification).
176 * crypt_get_default_type
177 get default compiled-in LUKS type (version).
179 * crypt_get_pbkdf_type_params
180 allows to get compiled-in PBKDF parameters.
182 * crypt_keyslot_set_encryption
183 * crypt_keyslot_get_encryption
184 allows to set/get per-keyslot encryption algorithm for LUKS2.
186 * crypt_keyslot_get_pbkdf
187 allows to get PBKDF parameters per-keyslot.
189 and these new defines:
190 * CRYPT_LOG_DEBUG_JSON (message type for JSON debug)
191 * CRYPT_DEBUG_JSON (log level for JSON debug)
192 * CRYPT_ACTIVATE_RECALCULATE (dm-integrity recalculate flag)
193 * CRYPT_ACTIVATE_REFRESH (new open with refresh flag)
195 All existing API calls should remain backward compatible.
197 Unfinished things & TODO for next releases
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199 * Optional authenticated encryption is still an experimental feature
200 and can have performance problems for high-speed devices and device
201 with larger IO blocks (like RAID).
203 * Authenticated encryption does not use encryption for a dm-integrity
204 journal. While it does not influence data confidentiality or
205 integrity protection, an attacker can get some more information
206 from data journal or cause that system will corrupt sectors after
207 journal replay. (That corruption will be detected though.)
209 * The LUKS2 metadata area increase is mainly needed for the new online
210 reencryption as the major feature for the next release.