242 lines
8.4 KiB
Plaintext
242 lines
8.4 KiB
Plaintext
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
|