docs/v1.5.0-ReleaseNotes

   1 Cryptsetup 1.5.0 RC1 Release Notes
   2 ==================================
   3
   4 This testing release candidate version covers mainly
   5 inclusion of new veritysetup tool (and related libcryptsetup extensions).
   6
   7 Please note that API extension and on-disk superblock can change in next
   8 1.5.0 release candidate (despite it is not expected).
   9
  10 Changes since version 1.4.3
  11 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  12 Introduce veritysetup tool for dm-verity target management.
  13
  14 The dm-verity device-mapper target was added to Linux kernel 3.4 and
  15 provides transparent integrity checking of block devices using a cryptographic
  16 digest provided by the kernel crypto API. This target is read-only.
  17
  18 It is meant to be setup as part of a verified boot path (it was originally
  19 developed by Chrome OS authors as part of verified boot infrastructure).
  20
  21 For deeper description please see http://code.google.com/p/cryptsetup/wiki/DMVerity
  22 and kernel dm-verity documentation.
  23
  24 The libcryptsetup library was extended to support manipulation
  25 with dm-verity kernel module and new veritysetup CLI tool is added.
  26
  27 There are no additional library requirements (it uses the same crypto
  28 backend as cryptsetup).
  29
  30 If you want compile cryptsetup without veritysetup toop,
  31 use --disable-veritysetup configure option.
  32 For other configuration option see configure --help and veritysetup --help
  33 (e.g. default parameters).
  34
  35 Supported libcryptsetup functions new CRYPT_VERITY type:
  36   crypt_init
  37   crypt_init_by_name
  38   crypt_set_data device
  39   crypt_get_type
  40   crypt_format
  41   crypt_load
  42   crypt_get_active_device
  43   crypt_activate_by_volume_key (volume key == root hash here)
  44   crypt_dump
  45 and new introduced function
  46   crypt_get_verity_info
  47
  48 Please see comments in libcryptsetup.h and veritysetup.c as an code example
  49 how to use CRYPT_VERITY API.
  50
  51 The veritysetup tool supports these operations:
  52
  53   veritysetup format <data_device> <hash_device>
  54     Formats <hash_device> (calculates all hash areas according to <data_device>).
  55     This is initial command to prepare device <hash_device> for later verification.
  56
  57   veritysetup create <name> <data_device> <hash_device> <root_hash>
  58     Creates (activates) a dm-verity mapping with <name> backed by device <data_device>
  59     and using <hash_device> for in-kernel verification.
  60
  61   veritysetup verify <data_device> <hash_device> <root_hash>
  62     Verifies data in userspace (no kernel device is activated).
  63
  64   veritysetup remove <name>
  65     Removes activated device from kernel (similar to dmsetup remove).
  66
  67   veritysetup status <name>
  68     Reports status for the active kernel dm-verity device.
  69
  70   veritysetup dump <hash_device>
  71     Reports parameters of verity device from on-disk stored superblock.
  72
  73 For more info see veritysetup --help and veritysetup man page.
  74
  75 Other changes
  76 ~~~~~~~~~~~~~
  77
  78   * Both data and header device can now be a file and
  79     loop device is automatically allocated.
  80
  81   * Require only up to last keyslot area for header device, previously
  82     backup (and activation) required device/file of size up to data start
  83     offset (data payload).
  84
  85   * Fix header backup and restore to work on files with large data offset.
  86     Backup and restore now works even if backup file is smaller than data offset.
  87
  88 Appendix: Examples of veritysetup use
  89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90
  91  Format device using default parameters, info and final root hash is printed:
  92  # veritysetup format /dev/sdb /dev/sdc
  93  VERITY header information for /dev/sdc
  94  UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
  95  Hash type:              1
  96  Data blocks:            52224
  97  Data block size:        4096
  98  Hash block size:        4096
  99  Hash algorithm:         sha256
 100  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 101  Root hash:              7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 102
 103  Activation of device in-kernel:
 104  # veritysetup create vr /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 105  Note - if device is corrupted, kernel mapping is created but will report failure:
 106  Verity device detected corruption after activation.
 107
 108  Userspace verification:
 109  # veritysetup verify /dev/sdb /dev/sdc 7aefa4506f7af497ac491a27f862cf8005ea782a5d97f6426945a6896ab557a1
 110   Verification failed at position 8192.
 111   Verification of data area failed.
 112
 113  Active device status report:
 114  # veritysetup status vr
 115  /dev/mapper/vr is active.
 116    type:        VERITY
 117    status:      verified
 118    hash type:   1
 119    data block:  4096
 120    hash block:  4096
 121    hash name:   sha256
 122    salt:        5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 123    data device: /dev/sdb
 124    size:        417792 sectors
 125    mode:        readonly
 126    hash device: /dev/sdc
 127    hash offset: 8 sectors
 128
 129  Dump of on-disk superblock information:
 130  # veritysetup dump /dev/sdc
 131  VERITY header information for /dev/sdc
 132  UUID:                   fad30431-0c59-4fa6-9b57-732a90501f75
 133  Hash type:              1
 134  Data blocks:            52224
 135  Data block size:        4096
 136  Hash block size:        4096
 137  Hash algorithm:         sha256
 138  Salt:                   5cc52759af76a092e0c21829cd0ef6938f69831bf86926525106f92a7e9e3aa9
 139
 140  Remove mapping:
 141  # veritysetup remove vr