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