"Fossies" - the Fresh Open Source Software Archive 
Member "cryptsetup-2.4.3/docs/v2.3.0-ReleaseNotes" (13 Jan 2022, 7978 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Cryptsetup 2.3.0 Release Notes
2 ==============================
3 Stable release with new experimental features and bug fixes.
4
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.
9
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.
13
14 Changes since version 2.2.2
15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17 * BITLK (Windows BitLocker compatible) device access
18
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.
23
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!
28
29 Cryptsetup supports BITLK activation through passphrase or recovery
30 passphrase for existing devices (BitLocker and Bitlocker to Go).
31
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.
35
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.
39
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).
43
44 Foe AES-XTS, activation is supported on all recent Linux kernels.
45
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.
49
50 Please note that CBC variants are legacy, and we provide it only
51 for backward compatibility (to be able to access old drives).
52
53 Cryptsetup command now supports the new "bitlk" format and implement dump,
54 open, status, and close actions.
55
56 To activate a BITLK device, use
57
58 # cryptsetup open --type bitlk <device> <name>
59 or with alias
60 # cryptsetup bitlkOpen <device> <name>
61
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
64 filesystem.
65
66 To print metadata information about BITLK device, use
67 # crypotsetup bitlkDump <device>
68
69 To print information about the active device, use
70 # cryptsetup status <name>
71
72 Example (activation of disk image):
73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74
75 # Recent blkid recognizes BitLocker device,just to verity
76 # blkid bitlocker_xts_ntfs.img
77 bitlocker_xts_ntfs.img: TYPE="BitLocker"
78
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.
82 Version: 2
83 GUID: ...
84 Created: Wed Oct 23 17:38:15 2019
85 Description: DESKTOP-xxxxxxx E: 23.10.2019
86 Cipher name: aes
87 Cipher mode: xts-plain64
88 Cipher key: 128 bits
89
90 Keyslots:
91 0: VMK
92 GUID: ...
93 Protection: VMK protected with passphrase
94 Salt: ...
95 Key data size: 44 [bytes]
96 1: VMK
97 GUID: ...
98 Protection: VMK protected with recovery passphrase
99 Salt: ...
100 Key data size: 44 [bytes]
101 2: FVEK
102 Key data size: 44 [bytes]
103
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:
107 Command successful.
108
109 # Information about the active device
110 # cryptsetup status test
111 /dev/mapper/test is active.
112 type: BITLK
113 cipher: aes-xts-plain64
114 keysize: 128 bits
115 ...
116
117 # Plaintext device should now contain decrypted NTFS filesystem
118 # blkid /dev/mapper/test
119 /dev/mapper/test: UUID="..." TYPE="ntfs"
120
121 # And can be mounted
122 # mount /dev/mapper/test /mnt/tst
123
124 # Deactivation
125 # umount /mnt/tst
126 # cryptsetup close test
127
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.
133
134 Verity devices activated with signature now has a special flag
135 (with signature) active in device status (veritysetup status <name>).
136
137 Usage:
138 # veritysetup open <data_device> name <hash_device> <root_hash> \
139 --root-hash-signature=<roothash_p7_sig_file>
140
141 * Integritysetup now calculates hash integrity size according to algorithm
142 instead of requiring an explicit tag size.
143
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.
148
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.
151
152 * Integritysetup now supports fixed padding for dm-integrity devices.
153
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
156 512 bytes was used.
157 This problem affects both stand-alone dm-integrity and also LUKS2 with
158 authenticated encryption and larger sector size.
159
160 The new extension to dm-integrity superblock is needed, so devices
161 with the new optimal padding cannot be activated on older systems.
162
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.
166
167 * A lot of fixes to online LUKS2 reecryption.
168
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.
173
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).
177
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.
181
182 * Allow --key-file option in legacy offline encryption.
183 The option was ignored for LUKS1 encryption initialization.
184
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.
188
189 * Fail crypt_keyslot_get_pbkdf for inactive LUKS1 keyslot.
190
191 Libcryptsetup API extensions
192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193 The libcryptsetup API is backward compatible for existing symbols.
194
195 New symbols
196 crypt_set_compatibility
197 crypt_get_compatibility;
198 crypt_resume_by_volume_key;
199 crypt_activate_by_signed_key;
200 crypt_safe_alloc;
201 crypt_safe_realloc;
202 crypt_safe_free;
203 crypt_safe_memzero;
204
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