docs/v1.5.0-ReleaseNotes - platform/external/cryptsetup - Git at Google

 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
	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