summaryrefslogtreecommitdiffstats
path: root/docs/v1.5.0-ReleaseNotes
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/v1.5.0-ReleaseNotes241
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..16a34cb
--- /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.
+(Reecryption 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