docs/v1.5.0-ReleaseNotes

   1 Cryptsetup 1.5.0 RC2 Release Notes
   2 ==================================
   3
   4 This testing release candidate version covers mainly
   5 inclusion of
   6 - new veritysetup tool (and related libcryptsetup extensions).
   7 - new experimental cryptsetup-reencrypt (offline reencryption) tool.
   8
   9 Please note that dm-verity API extension can change in next
  10 1.5.0 release candidate (despite it is not expected).
  11
  12 Changes since version 1.5.0-rc1
  13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  14 Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool.
  15
  16 ! cryptsetup-reencrypt tool is EXPERIMENTAL
  17 ! ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL
  18
  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).
  21
  22 This can happen for example when you want to change volume (master) key,
  23 encryption algorithm, or other encryption parameter.
  24
  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).
  27
  28 In general, cryptsetup-reencrypt can be used to
  29
  30  - re-generate volume key
  31  - change arbitrary encryption parameters
  32  - add encryption to not yet encrypted drive
  33
  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.)
  39
  40 There are for sure bugs, please TEST IT IN TEST ENVIRONMENT before
  41 use for your data.
  42
  43 This tool is not resistant to HW and kernel failures - hw crash
  44 will cause serious data corruption.
  45
  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.)
  49
  50 You have to provide all keyslot passphrases or use --kesylot-option
  51 (then all other keyslots will be disabled).
  52
  53 EXAMPLES (from man page)
  54
  55 Reencrypt /dev/sdb1 (change volume key)
  56    # cryptsetup-reencrypt /dev/sdb1
  57
  58 Reencrypt and also change cipher and cipher mode
  59   # cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
  60
  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
  63   reduce fs in advance.
  64
  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.
  68
  69   Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
  70
  71   # fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors
  72
  73   # cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096
  74
  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.
  78
  79 Progress and estimated time is printed during reencryption.
  80
  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).
  84
  85 Please note LUKS device is marked invalid during reencryption and
  86 you have to retain tool temporary files until reencryption finishes.
  87
  88 Temporary files are LUKS-<uuid>.[log|org|new]
  89
  90 Other changes
  91 ~~~~~~~~~~~~~
  92
  93   * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID).
  94
  95   * Add --test-passphrase option for luksOpen (check passphrase only).
  96
  97   * Fix parsing of hexadecimal string (salt or root hash) in veritysetup.
  98
  99 Changes since version 1.4.3
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101 Introduce veritysetup tool for dm-verity target management.
 102
 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.
 106
 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).
 109
 110 For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity
 111 and kernel dm-verity documentation.
 112
 113 The libcryptsetup library was extended to support manipulation
 114 with dm-verity kernel module and new veritysetup CLI tool is added.
 115
 116 There are no additional library requirements (it uses the same crypto
 117 backend as cryptsetup).
 118
 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).
 123
 124 Supported libcryptsetup functions new CRYPT_VERITY type:
 125   crypt_init
 126   crypt_init_by_name
 127   crypt_set_data device
 128   crypt_get_type
 129   crypt_format
 130   crypt_load
 131   crypt_get_active_device
 132   crypt_activate_by_volume_key (volume key == root hash here)
 133   crypt_dump
 134 and new introduced function
 135   crypt_get_verity_info
 136
 137 Please see comments in libcryptsetup.h and veritysetup.c as an code example
 138 how to use CRYPT_VERITY API.
 139
 140 The veritysetup tool supports these operations:
 141
 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.
 145
 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.
 149
 150   veritysetup verify <data_device> <hash_device> <root_hash>
 151     Verifies data in userspace (no kernel device is activated).
 152
 153   veritysetup remove <name>
 154     Removes activated device from kernel (similar to dmsetup remove).
 155
 156   veritysetup status <name>
 157     Reports status for the active kernel dm-verity device.
 158
 159   veritysetup dump <hash_device>
 160     Reports parameters of verity device from on-disk stored superblock.
 161
 162 For more info see veritysetup --help and veritysetup man page.
 163
 164 Other changes
 165 ~~~~~~~~~~~~~
 166
 167   * Both data and header device can now be a file and
 168     loop device is automatically allocated.
 169
 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).
 173
 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.
 176
 177 Appendix: Examples of veritysetup use
 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 179
 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
 184  Hash type:              1
 185  Data blocks:            52224
 186  Data block size:        4096
 187  Hash block size:        4096
 188  Hash algorithm:         sha256
 189  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 190  Root hash:              7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 191
 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.
 196
 197  Userspace verification:
 198  # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 199   Verification failed at position 8192.
 200   Verification of data area failed.
 201
 202  Active device status report:
 203  # veritysetup status vr
 204  /dev/mapper/vr is active.
 205    type:        VERITY
 206    status:      verified
 207    hash type:   1
 208    data block:  4096
 209    hash block:  4096
 210    hash name:   sha256
 211    salt:        5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 212    data device: /dev/sdb
 213    size:        417792 sectors
 214    mode:        readonly
 215    hash device: /dev/sdc
 216    hash offset: 8 sectors
 217
 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
 222  Hash type:              1
 223  Data blocks:            52224
 224  Data block size:        4096
 225  Hash block size:        4096
 226  Hash algorithm:         sha256
 227  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 228
 229  Remove mapping:
 230  # veritysetup remove vr