1 Cryptsetup 2.3.0 Release Notes
2 ==============================
3 Stable release with new experimental features and bug fixes.
5 Cryptsetup 2.3 version introduces support for BitLocker-compatible
6 devices (BITLK format). This format is used in Windows systems,
7 and in combination with a filesystem driver, cryptsetup now provides
8 native read-write access to BitLocker Full Disk Encryption devices.
10 The BITLK implementation is based on publicly available information
11 and it is an independent and opensource implementation that allows
12 to access this proprietary disk encryption.
14 Changes since version 2.2.2
15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 * BITLK (Windows BitLocker compatible) device access
19 BITLK userspace implementation is based on the master thesis and code
20 provided by Vojtech Trefny. Also, thanks to other opensource projects
21 like libbde (that provide alternative approach to decode this format)
22 we were able to verify cryptsetup implementation.
24 NOTE: Support for the BITLK device is EXPERIMENTAL and will require
25 a lot of testing. If you get some error message (mainly unsupported
26 metadata in the on-disk header), please help us by submitting an issue
27 to cryptsetup project, so we can fix it. Thank you!
29 Cryptsetup supports BITLK activation through passphrase or recovery
30 passphrase for existing devices (BitLocker and Bitlocker to Go).
32 Activation through TPM, SmartCard, or any other key protector
33 is not supported. And in some situations, mainly for TPM bind to some
34 PCR registers, it could be even impossible on Linux in the future.
36 All metadata (key protectors) are handled read-only, cryptsetup cannot
37 create or modify them. Except for old devices (created in old Vista
38 systems), all format variants should be recognized.
40 Data devices can be activated read-write (followed by mounting through
41 the proper filesystem driver). To access filesystem on the decrypted device
42 you need properly installed driver (vfat, NTFS or exFAT).
44 Foe AES-XTS, activation is supported on all recent Linux kernels.
46 For older AES-CBC encryption, Linux Kernel version 5.3 is required
47 (support for special IV variant); for AES-CBC with Elephant diffuser,
48 Linux Kernel 5.6 is required.
50 Please note that CBC variants are legacy, and we provide it only
51 for backward compatibility (to be able to access old drives).
53 Cryptsetup command now supports the new "bitlk" format and implement dump,
54 open, status, and close actions.
56 To activate a BITLK device, use
58 # cryptsetup open --type bitlk <device> <name>
60 # cryptsetup bitlkOpen <device> <name>
62 Then with properly installed fs driver (usually NTFS, vfat or exFAT),
63 you can mount the plaintext device /dev/mapper<name> device as a common
66 To print metadata information about BITLK device, use
67 # crypotsetup bitlkDump <device>
69 To print information about the active device, use
70 # cryptsetup status <name>
72 Example (activation of disk image):
73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75 # Recent blkid recognizes BitLocker device,just to verity
76 # blkid bitlocker_xts_ntfs.img
77 bitlocker_xts_ntfs.img: TYPE="BitLocker"
79 # Print visible metadata information (on-disk, form the image)
80 # cryptsetup bitlkDump bitlocker_xts_ntfs.img
81 Info for BITLK device bitlocker_xts_ntfs.img.
84 Created: Wed Oct 23 17:38:15 2019
85 Description: DESKTOP-xxxxxxx E: 23.10.2019
87 Cipher mode: xts-plain64
93 Protection: VMK protected with passphrase
95 Key data size: 44 [bytes]
98 Protection: VMK protected with recovery passphrase
100 Key data size: 44 [bytes]
102 Key data size: 44 [bytes]
104 # Activation (recovery passphrase works the same as password)
105 # cryptsetup bitlkOpen bitlocker_xts_ntfs.img test -v
106 Enter passphrase for bitlocker_xts_ntfs.img:
109 # Information about the active device
110 # cryptsetup status test
111 /dev/mapper/test is active.
113 cipher: aes-xts-plain64
117 # Plaintext device should now contain decrypted NTFS filesystem
118 # blkid /dev/mapper/test
119 /dev/mapper/test: UUID="..." TYPE="ntfs"
122 # mount /dev/mapper/test /mnt/tst
126 # cryptsetup close test
128 * Veritysetup now supports activation with additional PKCS7 signature
129 of root hash through --root-hash-signature option.
130 The signature uses an in-kernel trusted key to validate the signature
131 of the root hash during activation. This option requires Linux kernel
132 5.4 with DM_VERITY_VERIFY_ROOTHASH_SIG option.
134 Verity devices activated with signature now has a special flag
135 (with signature) active in device status (veritysetup status <name>).
138 # veritysetup open <data_device> name <hash_device> <root_hash> \
139 --root-hash-signature=<roothash_p7_sig_file>
141 * Integritysetup now calculates hash integrity size according to algorithm
142 instead of requiring an explicit tag size.
144 Previously, when integritysetup formats a device with hash or
145 HMAC integrity checksums, it required explicitly tag size entry from
146 a user (or used default value).
147 This led to confusion and unexpected shortened tag sizes.
149 Now, libcryptsetup calculates tag size according to real hash output.
150 Tag size can also be specified, then it warns if these values differ.
152 * Integritysetup now supports fixed padding for dm-integrity devices.
154 There was an in-kernel bug that wasted a lot of space when using metadata
155 areas for integrity-protected devices if a larger sector size than
157 This problem affects both stand-alone dm-integrity and also LUKS2 with
158 authenticated encryption and larger sector size.
160 The new extension to dm-integrity superblock is needed, so devices
161 with the new optimal padding cannot be activated on older systems.
163 Integritysetup/Cryptsetup will use new padding automatically if it
164 detects the proper kernel. To create a compatible device with
165 the old padding, use --integrity-legacy-padding option.
167 * A lot of fixes to online LUKS2 reecryption.
169 * Add crypt_resume_by_volume_key() function to libcryptsetup.
170 If a user has a volume key available, the LUKS device can be resumed
171 directly using the provided volume key.
172 No keyslot derivation is needed, only the key digest is checked.
174 * Implement active device suspend info.
175 Add CRYPT_ACTIVATE_SUSPENDED bit to crypt_get_active_device() flags
176 that informs the caller that device is suspended (luksSuspend).
178 * Allow --test-passphrase for a detached header.
179 Before this fix, we required a data device specified on the command
180 line even though it was not necessary for the passphrase check.
182 * Allow --key-file option in legacy offline encryption.
183 The option was ignored for LUKS1 encryption initialization.
185 * Export memory safe functions.
186 To make developing of some extensions simpler, we now export
187 functions to handle memory with proper wipe on deallocation.
189 * Fail crypt_keyslot_get_pbkdf for inactive LUKS1 keyslot.
191 Libcryptsetup API extensions
192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193 The libcryptsetup API is backward compatible for existing symbols.
196 crypt_set_compatibility
197 crypt_get_compatibility;
198 crypt_resume_by_volume_key;
199 crypt_activate_by_signed_key;
205 New defines introduced :
206 CRYPT_BITLK "BITLK" - BITLK (BitLocker-compatible mode
207 CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING - dm-integrity legacy padding
208 CRYPT_VERITY_ROOT_HASH_SIGNATURE - dm-verity root hash signature
209 CRYPT_ACTIVATE_SUSPENDED - device suspended info flag