Documentation/device-mapper/dm-verity.txt

   1 dm-verity
   2 ==========
   3
   4 Device-Mapper's "verity" target provides transparent integrity checking of
   5 block devices using a cryptographic digest provided by the kernel crypto API.
   6 This target is read-only.
   7
   8 Parameters: <device path> <hash device path> <tree depth> <alg> <parent-hash>
   9
  10 <device path>
  11     This is the device that is going to be integrity checked.  It may be
  12     a subset of the full device as specified to dmsetup (start sector and count)
  13     It may be specified as a path, like /dev/sdaX, or a device number,
  14     <major>:<minor>.
  15
  16 <hash device path>
  17     This is the device that that supplies the dm-bht hash data.  It may be
  18     specified similarly to the device path and may be the same device.  If the
  19     same device is used, the hash offset should be outside of the dm-verity
  20     configured device size.
  21
  22 <tree depth>
  23     The tree depth determines how many levels of hashes are used when building
  24     the tree of hashes.  The root of the tree not included and the leaves of
  25     the tree are the hashes of the blocks on disk.
  26
  27 <alg>
  28     The cryptographic hash algorithm used for this device.  This should
  29     be the name of the algorithm, like "sha1".
  30
  31 <root hash>
  32     The hexadecimal encoding of the cryptographic hash of all of the
  33     neighboring nodes at the first level of the tree.  This hash should be
  34     trusted as there is no other authenticity beyond this point.
  35
  36
  37 Theory of operation
  38 ===================
  39
  40 dm-verity is meant to be setup as part of a verified boot path.  This
  41 may be anything ranging from a boot using tboot or trustedgrub to just
  42 booting from a known-good device (like a USB drive or CD).
  43
  44 When a dm-verity device is configured, it is expected that the caller
  45 has been authenticated in some way (cryptographic signatures, etc).
  46 After instantiation, all hashes will be verified on-demand during
  47 disk access.  If they cannot be verified up to the root node of the
  48 tree, the root hash, then the I/O will fail.  This should identify
  49 tampering with any data on the device and the hash data.
  50
  51 Cryptographic hashes are used to assert the integrity of the device on a
  52 per-block basis.  This allows for a lightweight hash computation on first read
  53 into the page cache.  Block hashes are stored linearly aligned to the nearest
  54 block the size of a page.
  55
  56 For more information on the hashing process, see dm-bht.txt.
  57
  58
  59 Example
  60 =======
  61
  62 Setup a device;
  63 [[
  64   dmsetup create vroot --table \
  65     "0 204800 verity /dev/sda1 /dev/sda2 0 3 sha1 "\
  66     "9f74809a2ee7607b16fcc70d9399a4de9725a727"
  67 ]]
  68
  69 A command line tool is available to compute the hash tree and return the
  70 root hash value.
  71   http://git.chromium.org/cgi-bin/gitweb.cgi?p=dm-verity.git;a=tree