1 Cryptsetup 1.5.0 RC2 Release Notes
2 ==================================
4 This testing release candidate version covers mainly
6 - new veritysetup tool (and related libcryptsetup extensions).
7 - new experimental cryptsetup-reencrypt (offline reencryption) tool.
9 Please note that dm-verity API extension can change in next
10 1.5.0 release candidate (despite it is not expected).
12 Changes since version 1.5.0-rc1
13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14 Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool.
16 ! cryptsetup-reencrypt tool is EXPERIMENTAL
17 ! ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL
19 This tool tries to simplify situation when you need to re-encrypt the whole
20 LUKS device in situ (without need to move data elsewhere).
22 This can happen for example when you want to change volume (master) key,
23 encryption algorithm, or other encryption parameter.
25 Cryptsetup-reencrypt can even optionally shift data on device
26 (reducing data device size - you need some free space at the end of device).
28 In general, cryptsetup-reencrypt can be used to
30 - re-generate volume key
31 - change arbitrary encryption parameters
32 - add encryption to not yet encrypted drive
34 Side effect of reencryption is that final device will contain
35 only ciphertext (for all sectors) so even if device was not properly
36 wiped by random data, after reencryption you cannot distinguish
37 which sectors are used.
38 (Reecryption is done always for the whole device.)
40 There are for sure bugs, please TEST IT IN TEST ENVIRONMENT before
43 This tool is not resistant to HW and kernel failures - hw crash
44 will cause serious data corruption.
46 You can enable compilation of this tool with --enable-cryptsetup-reencrypt
47 configure option (it is switched off by default).
48 (Tool requires libcryptsetup 1.4.3 and later.)
50 You have to provide all keyslot passphrases or use --kesylot-option
51 (then all other keyslots will be disabled).
53 EXAMPLES (from man page)
55 Reencrypt /dev/sdb1 (change volume key)
56 # cryptsetup-reencrypt /dev/sdb1
58 Reencrypt and also change cipher and cipher mode
59 # cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
61 Note: if you are changing key size, there must be enough space
62 for keyslots in header or you have to use --reduce-device size and
65 Add LUKS encryption to not yet encrypted device
66 First, be sure you have space added to disk.
67 Or, alternatively, shrink filesystem in advance.
69 Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
71 # fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors
73 # cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096
75 There are some options which can improve performance (depends on system),
76 namely --use-directio (use direct IO for all operations) can be faster
77 on some systems. See man page.
79 Progress and estimated time is printed during reencryption.
81 You can suspend reencryption (using ctrl+c or term signal).
82 To continue reencryption you have to provide only
83 the device parameter (offset is stored in temporary log file).
85 Please note LUKS device is marked invalid during reencryption and
86 you have to retain tool temporary files until reencryption finishes.
88 Temporary files are LUKS-<uuid>.[log|org|new]
93 * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID).
95 * Add --test-passphrase option for luksOpen (check passphrase only).
97 * Fix parsing of hexadecimal string (salt or root hash) in veritysetup.
99 Changes since version 1.4.3
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
101 Introduce veritysetup tool for dm-verity target management.
103 The dm-verity device-mapper target was added to Linux kernel 3.4 and
104 provides transparent integrity checking of block devices using a cryptographic
105 digest provided by the kernel crypto API. This target is read-only.
107 It is meant to be setup as part of a verified boot path (it was originally
108 developed by Chrome OS authors as part of verified boot infrastructure).
110 For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity
111 and kernel dm-verity documentation.
113 The libcryptsetup library was extended to support manipulation
114 with dm-verity kernel module and new veritysetup CLI tool is added.
116 There are no additional library requirements (it uses the same crypto
117 backend as cryptsetup).
119 If you want compile cryptsetup without veritysetup tool,
120 use --disable-veritysetup configure option.
121 For other configuration option see configure --help and veritysetup --help
122 (e.g. default parameters).
124 Supported libcryptsetup functions new CRYPT_VERITY type:
127 crypt_set_data device
131 crypt_get_active_device
132 crypt_activate_by_volume_key (volume key == root hash here)
134 and new introduced function
135 crypt_get_verity_info
137 Please see comments in libcryptsetup.h and veritysetup.c as an code example
138 how to use CRYPT_VERITY API.
140 The veritysetup tool supports these operations:
142 veritysetup format <data_device> <hash_device>
143 Formats <hash_device> (calculates all hash areas according to <data_device>).
144 This is initial command to prepare device <hash_device> for later verification.
146 veritysetup create <name> <data_device> <hash_device> <root_hash>
147 Creates (activates) a dm-verity mapping with <name> backed by device <data_device>
148 and using <hash_device> for in-kernel verification.
150 veritysetup verify <data_device> <hash_device> <root_hash>
151 Verifies data in userspace (no kernel device is activated).
153 veritysetup remove <name>
154 Removes activated device from kernel (similar to dmsetup remove).
156 veritysetup status <name>
157 Reports status for the active kernel dm-verity device.
159 veritysetup dump <hash_device>
160 Reports parameters of verity device from on-disk stored superblock.
162 For more info see veritysetup --help and veritysetup man page.
167 * Both data and header device can now be a file and
168 loop device is automatically allocated.
170 * Require only up to last keyslot area for header device, previously
171 backup (and activation) required device/file of size up to data start
172 offset (data payload).
174 * Fix header backup and restore to work on files with large data offset.
175 Backup and restore now works even if backup file is smaller than data offset.
177 Appendix: Examples of veritysetup use
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180 Format device using default parameters, info and final root hash is printed:
181 # veritysetup format /dev/sdb /dev/sdc
182 VERITY header information for /dev/sdc
183 UUID: fad30431-0c59-4fa6-9b57-732a90501f75
186 Data block size: 4096
187 Hash block size: 4096
188 Hash algorithm: sha256
189 Salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
190 Root hash: 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
192 Activation of device in-kernel:
193 # veritysetup create vr /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
194 Note - if device is corrupted, kernel mapping is created but will report failure:
195 Verity device detected corruption after activation.
197 Userspace verification:
198 # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
199 Verification failed at position 8192.
200 Verification of data area failed.
202 Active device status report:
203 # veritysetup status vr
204 /dev/mapper/vr is active.
211 salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
212 data device: /dev/sdb
215 hash device: /dev/sdc
216 hash offset: 8 sectors
218 Dump of on-disk superblock information:
219 # veritysetup dump /dev/sdc
220 VERITY header information for /dev/sdc
221 UUID: fad30431-0c59-4fa6-9b57-732a90501f75
224 Data block size: 4096
225 Hash block size: 4096
226 Hash algorithm: sha256
227 Salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
230 # veritysetup remove vr