diff options
Diffstat (limited to 'docs/v1.5.0-ReleaseNotes')
| -rw-r--r-- | docs/v1.5.0-ReleaseNotes | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/docs/v1.5.0-ReleaseNotes b/docs/v1.5.0-ReleaseNotes new file mode 100644 index 0000000..9f1e1d1 --- /dev/null +++ b/docs/v1.5.0-ReleaseNotes @@ -0,0 +1,241 @@ +Cryptsetup 1.5.0 Release Notes +============================== + +This release covers mainly inclusion of: + + * Veritysetup tool (and related libcryptsetup extensions for dm-verity). + + * Experimental cryptsetup-reencrypt tool (LUKS offline reencryption). + +Changes since version 1.5.0-rc2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * Add --device-size option for reencryption tool. + + * Switch to use unit suffix for --reduce-device-size option. + + * Remove open device debugging feature (no longer needed). + + * Fix library name for FIPS check. + + * Add example of using reencryption inside dracut (see misc/dracut). + +Changes since version 1.5.0-rc1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool. + +! cryptsetup-reencrypt tool is EXPERIMENTAL +! ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL + +This tool tries to simplify situation when you need to re-encrypt the whole +LUKS device in situ (without need to move data elsewhere). + +This can happen for example when you want to change volume (master) key, +encryption algorithm, or other encryption parameter. + +Cryptsetup-reencrypt can even optionally shift data on device +(reducing data device size - you need some free space at the end of device). + +In general, cryptsetup-reencrypt can be used to + + - re-generate volume key + - change arbitrary encryption parameters + - add encryption to not yet encrypted drive + +Side effect of reencryption is that final device will contain +only ciphertext (for all sectors) so even if device was not properly +wiped by random data, after reencryption you cannot distinguish +which sectors are used. +(Reencryption is done always for the whole device.) + +There are for sure bugs, please TEST IT IN TEST ENVIRONMENT before +use for your data. + +This tool is not resistant to HW and kernel failures - hw crash +will cause serious data corruption. + +You can enable compilation of this tool with --enable-cryptsetup-reencrypt +configure option (it is switched off by default). +(Tool requires libcryptsetup 1.4.3 and later.) + +You have to provide all keyslot passphrases or use --keyslot-option +(then all other keyslots will be disabled). + +EXAMPLES (from man page) + +Reencrypt /dev/sdb1 (change volume key) + # cryptsetup-reencrypt /dev/sdb1 + +Reencrypt and also change cipher and cipher mode + # cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64 + + Note: if you are changing key size, there must be enough space + for keyslots in header or you have to use --reduce-device size and + reduce fs in advance. + +Add LUKS encryption to not yet encrypted device + First, be sure you have space added to disk. + Or, alternatively, shrink filesystem in advance. + + Here we need 4096 512-bytes sectors (enough for 2x128 bit key). + + # fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors + + # cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096 + +There are some options which can improve performance (depends on system), +namely --use-directio (use direct IO for all operations) can be faster +on some systems. See man page. + +Progress and estimated time is printed during reencryption. + +You can suspend reencryption (using ctrl+c or term signal). +To continue reencryption you have to provide only +the device parameter (offset is stored in temporary log file). + +Please note LUKS device is marked invalid during reencryption and +you have to retain tool temporary files until reencryption finishes. + +Temporary files are LUKS-<uuid>.[log|org|new] + +Other changes +~~~~~~~~~~~~~ + + * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID). + + * Add --test-passphrase option for luksOpen (check passphrase only). + + * Fix parsing of hexadecimal string (salt or root hash) in veritysetup. + +Changes since version 1.4.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Introduce veritysetup tool for dm-verity target management. + +The dm-verity device-mapper target was added to Linux kernel 3.4 and +provides transparent integrity checking of block devices using a cryptographic +digest provided by the kernel crypto API. This target is read-only. + +It is meant to be setup as part of a verified boot path (it was originally +developed by Chrome OS authors as part of verified boot infrastructure). + +For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity +and kernel dm-verity documentation. + +The libcryptsetup library was extended to support manipulation +with dm-verity kernel module and new veritysetup CLI tool is added. + +There are no additional library requirements (it uses the same crypto +backend as cryptsetup). + +If you want compile cryptsetup without veritysetup tool, +use --disable-veritysetup configure option. +For other configuration option see configure --help and veritysetup --help +(e.g. default parameters). + +Supported libcryptsetup functions new CRYPT_VERITY type: + crypt_init + crypt_init_by_name + crypt_set_data device + crypt_get_type + crypt_format + crypt_load + crypt_get_active_device + crypt_activate_by_volume_key (volume key == root hash here) + crypt_dump +and new introduced function + crypt_get_verity_info + +Please see comments in libcryptsetup.h and veritysetup.c as an code example +how to use CRYPT_VERITY API. + +The veritysetup tool supports these operations: + + veritysetup format <data_device> <hash_device> + Formats <hash_device> (calculates all hash areas according to <data_device>). + This is initial command to prepare device <hash_device> for later verification. + + veritysetup create <name> <data_device> <hash_device> <root_hash> + Creates (activates) a dm-verity mapping with <name> backed by device <data_device> + and using <hash_device> for in-kernel verification. + + veritysetup verify <data_device> <hash_device> <root_hash> + Verifies data in userspace (no kernel device is activated). + + veritysetup remove <name> + Removes activated device from kernel (similar to dmsetup remove). + + veritysetup status <name> + Reports status for the active kernel dm-verity device. + + veritysetup dump <hash_device> + Reports parameters of verity device from on-disk stored superblock. + +For more info see veritysetup --help and veritysetup man page. + +Other changes +~~~~~~~~~~~~~ + + * Both data and header device can now be a file and + loop device is automatically allocated. + + * Require only up to last keyslot area for header device, previously + backup (and activation) required device/file of size up to data start + offset (data payload). + + * Fix header backup and restore to work on files with large data offset. + Backup and restore now works even if backup file is smaller than data offset. + +Appendix: Examples of veritysetup use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Format device using default parameters, info and final root hash is printed: + # veritysetup format /dev/sdb /dev/sdc + VERITY header information for /dev/sdc + UUID: fad30431-0c59-4fa6-9b57-732a90501f75 + Hash type: 1 + Data blocks: 52224 + Data block size: 4096 + Hash block size: 4096 + Hash algorithm: sha256 + Salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9 + Root hash: 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1 + + Activation of device in-kernel: + # veritysetup create vr /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1 + Note - if device is corrupted, kernel mapping is created but will report failure: + Verity device detected corruption after activation. + + Userspace verification: + # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1 + Verification failed at position 8192. + Verification of data area failed. + + Active device status report: + # veritysetup status vr + /dev/mapper/vr is active. + type: VERITY + status: verified + hash type: 1 + data block: 4096 + hash block: 4096 + hash name: sha256 + salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9 + data device: /dev/sdb + size: 417792 sectors + mode: readonly + hash device: /dev/sdc + hash offset: 8 sectors + + Dump of on-disk superblock information: + # veritysetup dump /dev/sdc + VERITY header information for /dev/sdc + UUID: fad30431-0c59-4fa6-9b57-732a90501f75 + Hash type: 1 + Data blocks: 52224 + Data block size: 4096 + Hash block size: 4096 + Hash algorithm: sha256 + Salt: 5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9 + + Remove mapping: + # veritysetup remove vr |