Skip to contentSkip to conversation

device-mapper: verity, an integrity checking target

RFC PATCH New [email protected] 1 participant 1 message May 23, 2010

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 device-mapper: verity, an integrity checking target

From: Will Drewry <[email protected]>

This target transparently passes I/O read requests through to the configured underlying block device. Before data is returned, the cryptographic digest of each block is checked against an original value stored on a separately configured block device (may be the same device). Verification of the stored cryptographic digest is handled through the use of a hash tree. The root node of that tree is set at mapped drive configuration time.

The hash tree implementation, dm-bht.c, provides a means to verify only portions of the block device as needed. In addition, it is possible to reuse dm-bht.c and dm-bht.h in userspace (see tools below) for testing and hash tree verification and creation. At present, this device-mapper target only uses the tree verification code (no kernel-time updates).

The behavior on integrity failure is parameter configurable:
- return -EIO for the given bio
- reboot
- ignore (when possible)

It is planned to make the error handler dynamically configured to support behaviors specific to a given platform.

The userspace verity tools will be available at:
http://git.chromium.org/cgi-bin/gitweb.cgi?p=dm-verity.git;a=summary
(Currently in review, http://codereview.chromium.org/1687008/show )

The original specification can be found at:
http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot

This work varies from the existing linux-ima work in a number of areas:
- checks at the block device layer including all data and metadata
- doesn't consume the LSM module slot
- doesn't use or update TPM PCR values
It does, however, have overlapping goals and functionality.

Paired with the boot-without-initrd patches for dm, it allow for a fast, verified boot process:
- https://www.redhat.com/archives/dm-devel/2010-May/msg00104.html
- https://www.redhat.com/archives/dm-devel/2010-May/msg00105.html
- https://www.redhat.com/archives/dm-devel/2010-May/msg00106.html

This code and docs are not polished and is likely buggy (rfc!). Any and all feedback is appreciated!

[This patch may be broken up into documentation, dm-bht, and dm-verity, but for purposes of logical cohesiveness and comment, I've kept it together.]

---
 Documentation/device-mapper/dm-bht.txt    |   71 ++
 Documentation/device-mapper/dm-verity.txt |   71 ++
 drivers/md/Kconfig                        |   20 +
 drivers/md/Makefile                       |    1 +
 drivers/md/dm-bht.c                       | 1233 ++++++++++++++++++++++++
 drivers/md/dm-verity.c                    | 1495 +++++++++++++++++++++++++++++
 include/linux/dm-bht.h                    |  137 +++
 7 files changed, 3028 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/device-mapper/dm-bht.txt
 create mode 100644 Documentation/device-mapper/dm-verity.txt
 create mode 100644 drivers/md/dm-bht.c
 create mode 100644 drivers/md/dm-verity.c
 create mode 100644 include/linux/dm-bht.h
Documentation/device-mapper/dm-bht.txt new file +71 -0
new file mode 100644
index 0000000..3ce814f
@@ -0,0 +1,71 @@
+dm-bht
+======
+
+dm-bht provides a block hash tree implementation.  The use of dm-bht allows
+for integrity checking of a given block device without reading the entire
+set of blocks into memory befor euse.
+
+In particular, dm-bht supplies an interface for creating and verifying a tree
+of cryptographic digests with any algorithm supported by the kernel crypto API.
+
+The code is meant to be usable from user-space for creation and verification as
+well as directly from a Device-Mapper target.  The `verity' target is the
+motivating example.
+
+
+Theory of operation
+===================
+
+dm-bht is logically comprised of multiple nodes organized in a tree-like
+structure.  Each node in the tree is a cryptographic hash.  If it is a leaf
+node, the hash is of some block data on disk.  If it is an intermediary node,
+then the hash is of a number of child nodes.
+
+dm-bht has a given depth starting at 1 (ignoring the root node).  Each level in
+the tree is concretely made up of dm_bht_entry structs.  Each entry in the tree
+is a collection of neighboring nodes that fit in one page-sized block.  The
+number is determined based on PAGE_SIZE and the size of the selected
+cryptographic digest algorithm.  The hashes are linearly ordered in this entry
+and any unaligned trailing space is ignored but included when calculating the
+parent node.
+
+The tree looks something like:
+
+depth = 2, alg= sha256, num_blocks = 32767
+                                 [   root    ]
+                                /    . . .    \
+                     [entry_0]                 [entry_1]
+                    /  . . .  \                 . . .   \
+         [entry_0_0]   . . .  [entry_0_127]    . . . .  [entry_1_127]
+           / ... \             /   . . .  \             /           \
+     blk_0 ... blk_127  blk_16256   blk_16383      blk_32640 . . . blk_32767
+
+root is treated independently from the depth and the blocks are expected to
+be hashed and supplied to the dm-bht.  hash blocks that make up the entry
+contents are expected to be read from disk.
+
+dm-bht does not handle I/O directly but instead expects the consumer to
+supply callbacks.  The read callback will always receive a page-align value
+to pass to the block device layer to read in a hash value.
+
+Usage
+=====
+
+Reading and updating the same tree is not safe.  If a new tree is created, it
+should be dm_bht_destroy()d and a new tree should be instantiated, with
+dm_bht_create(), using the same hash data.
+
+When reading, all required data for the hash tree should be populated for a
+block before attempting a verify.  This can be done by calling
+dm_bht_populate().  When all data is ready, a call to dm_bht_verify_block()
+with the expected hash value will perform both the direct block hash check and
+the hashes of the parent and neighboring nodes where needed to ensure validity
+up to the root hash.  Note, dm_bht_set_root_hexdigest() should be called before
+any verification attempts occur.
+
+When updating the tree, all block hashes should be stored with
+dm_bht_store_block().  Once all hashes are stored, a call to dm_bht_compute()
+will initiate a full tree update by walking all of the blocks of hashes
+starting at the leaf nodes and computing upward to the root node.  On
+completion, dm_bht_sync() may be called to write the tree to disk (or wherever
+the callback writes to).
Documentation/device-mapper/dm-verity.txt new file +71 -0

71 lines not on this page · raw message

drivers/md/Kconfig +20 -0
index 4a6feac..49d629e 100644
@@ -243,6 +243,26 @@ config DM_CRYPT
 
 	  If unsure, say N.
 
+config DM_VERITY
+	tristate "Verity target support"
+	depends on BLK_DEV_DM
+	select CRYPTO
+	select CRYPTO_HASH
+	---help---
+	  This device-mapper target allows you to create a device that
+	  transparently integrity checks the data on it. You'll need to
+	  activate the digests you're going to use in the cryptoapi
+	  configuration.
+
+	  Information on how to use dm-verity can be found on
+
+	  <http://dev.chromium.org/chromium-os/chromiumos-design-docs/verified-boot>
+
+	  To compile this code as a module, choose M here: the module will
+	  be called dm-verity.
+
+	  If unsure, say N.
+
 config DM_SNAPSHOT
        tristate "Snapshot target"
        depends on BLK_DEV_DM
drivers/md/Makefile +1 -0
index e355e7f..0408134 100644
@@ -36,6 +36,7 @@ obj-$(CONFIG_MD_FAULTY)		+= faulty.o
 obj-$(CONFIG_BLK_DEV_MD)	+= md-mod.o
 obj-$(CONFIG_BLK_DEV_DM)	+= dm-mod.o
 obj-$(CONFIG_DM_CRYPT)		+= dm-crypt.o
+obj-$(CONFIG_DM_VERITY)		+= dm-verity.o dm-bht.o
 obj-$(CONFIG_DM_DELAY)		+= dm-delay.o
 obj-$(CONFIG_DM_MULTIPATH)	+= dm-multipath.o dm-round-robin.o
 obj-$(CONFIG_DM_MULTIPATH_QL)	+= dm-queue-length.o
drivers/md/dm-bht.c new file +1233 -0

1,233 lines not on this page · raw message

drivers/md/dm-verity.c new file +1495 -0

1,495 lines not on this page · raw message

include/linux/dm-bht.h new file +137 -0

97 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Signature · 1 line
1.7.0.4

Part of the diff is not shown here. View the raw message.