32e48797a14f80de6ebff7a441e489021bfce58a
[linux-2.6.git] / Documentation / device-mapper / 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 Construction Parameters
9 =======================
10     <version> <dev> <hash_dev> <hash_start>
11     <data_block_size> <hash_block_size>
12     <num_data_blocks> <hash_start_block>
13     <algorithm> <digest> <salt>
14
15 <version>
16     This is the version number of the on-disk format.
17
18     0 is the original format used in the Chromium OS.
19         The salt is appended when hashing, digests are stored continuously and
20         the rest of the block is padded with zeros.
21
22     1 is the current format that should be used for new devices.
23         The salt is prepended when hashing and each digest is
24         padded with zeros to the power of two.
25
26 <dev>
27     This is the device containing the data the integrity of which needs to be
28     checked.  It may be specified as a path, like /dev/sdaX, or a device number,
29     <major>:<minor>.
30
31 <hash_dev>
32     This is the device that that supplies the hash tree data.  It may be
33     specified similarly to the device path and may be the same device.  If the
34     same device is used, the hash_start should be outside of the dm-verity
35     configured device size.
36
37 <data_block_size>
38     The block size on a data device.  Each block corresponds to one digest on
39     the hash device.
40
41 <hash_block_size>
42     The size of a hash block.
43
44 <num_data_blocks>
45     The number of data blocks on the data device.  Additional blocks are
46     inaccessible.  You can place hashes to the same partition as data, in this
47     case hashes are placed after <num_data_blocks>.
48
49 <hash_start_block>
50     This is the offset, in <hash_block_size>-blocks, from the start of hash_dev
51     to the root block of the hash tree.
52
53 <algorithm>
54     The cryptographic hash algorithm used for this device.  This should
55     be the name of the algorithm, like "sha1".
56
57 <digest>
58     The hexadecimal encoding of the cryptographic hash of the root hash block
59     and the salt.  This hash should be trusted as there is no other authenticity
60     beyond this point.
61
62 <salt>
63     The hexadecimal encoding of the salt value.
64
65 Theory of operation
66 ===================
67
68 dm-verity is meant to be setup as part of a verified boot path.  This
69 may be anything ranging from a boot using tboot or trustedgrub to just
70 booting from a known-good device (like a USB drive or CD).
71
72 When a dm-verity device is configured, it is expected that the caller
73 has been authenticated in some way (cryptographic signatures, etc).
74 After instantiation, all hashes will be verified on-demand during
75 disk access.  If they cannot be verified up to the root node of the
76 tree, the root hash, then the I/O will fail.  This should identify
77 tampering with any data on the device and the hash data.
78
79 Cryptographic hashes are used to assert the integrity of the device on a
80 per-block basis.  This allows for a lightweight hash computation on first read
81 into the page cache.  Block hashes are stored linearly-aligned to the nearest
82 block the size of a page.
83
84 Hash Tree
85 ---------
86
87 Each node in the tree is a cryptographic hash.  If it is a leaf node, the hash
88 is of some block data on disk.  If it is an intermediary node, then the hash is
89 of a number of child nodes.
90
91 Each entry in the tree is a collection of neighboring nodes that fit in one
92 block.  The number is determined based on block_size and the size of the
93 selected cryptographic digest algorithm.  The hashes are linearly-ordered in
94 this entry and any unaligned trailing space is ignored but included when
95 calculating the parent node.
96
97 The tree looks something like:
98
99 alg = sha256, num_blocks = 32768, block_size = 4096
100
101                                  [   root    ]
102                                 /    . . .    \
103                      [entry_0]                 [entry_1]
104                     /  . . .  \                 . . .   \
105          [entry_0_0]   . . .  [entry_0_127]    . . . .  [entry_1_127]
106            / ... \             /   . . .  \             /           \
107      blk_0 ... blk_127  blk_16256   blk_16383      blk_32640 . . . blk_32767
108
109
110 On-disk format
111 ==============
112
113 Below is the recommended on-disk format. The verity kernel code does not
114 read the on-disk header. It only reads the hash blocks which directly
115 follow the header. It is expected that a user-space tool will verify the
116 integrity of the verity_header and then call dmsetup with the correct
117 parameters. Alternatively, the header can be omitted and the dmsetup
118 parameters can be passed via the kernel command-line in a rooted chain
119 of trust where the command-line is verified.
120
121 The on-disk format is especially useful in cases where the hash blocks
122 are on a separate partition. The magic number allows easy identification
123 of the partition contents. Alternatively, the hash blocks can be stored
124 in the same partition as the data to be verified. In such a configuration
125 the filesystem on the partition would be sized a little smaller than
126 the full-partition, leaving room for the hash blocks.
127
128 struct superblock {
129         uint8_t signature[8]
130                 "verity\0\0";
131
132         uint8_t version;
133                 1 - current format
134
135         uint8_t data_block_bits;
136                 log2(data block size)
137
138         uint8_t hash_block_bits;
139                 log2(hash block size)
140
141         uint8_t pad1[1];
142                 zero padding
143
144         uint16_t salt_size;
145                 big-endian salt size
146
147         uint8_t pad2[2];
148                 zero padding
149
150         uint32_t data_blocks_hi;
151                 big-endian high 32 bits of the 64-bit number of data blocks
152
153         uint32_t data_blocks_lo;
154                 big-endian low 32 bits of the 64-bit number of data blocks
155
156         uint8_t algorithm[16];
157                 cryptographic algorithm
158
159         uint8_t salt[384];
160                 salt (the salt size is specified above)
161
162         uint8_t pad3[88];
163                 zero padding to 512-byte boundary
164 }
165
166 Directly following the header (and with sector number padded to the next hash
167 block boundary) are the hash blocks which are stored a depth at a time
168 (starting from the root), sorted in order of increasing index.
169
170 Status
171 ======
172 V (for Valid) is returned if every check performed so far was valid.
173 If any check failed, C (for Corruption) is returned.
174
175 Example
176 =======
177
178 Setup a device:
179   dmsetup create vroot --table \
180     "0 2097152 "\
181     "verity 1 /dev/sda1 /dev/sda2 4096 4096 2097152 1 "\
182     "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
183     "1234000000000000000000000000000000000000000000000000000000000000"
184
185 A command line tool veritysetup is available to compute or verify
186 the hash tree or activate the kernel driver.  This is available from
187 the LVM2 upstream repository and may be supplied as a package called
188 device-mapper-verity-tools:
189     git://sources.redhat.com/git/lvm2
190     http://sourceware.org/git/?p=lvm2.git
191     http://sourceware.org/cgi-bin/cvsweb.cgi/LVM2/verity?cvsroot=lvm2
192
193 veritysetup -a vroot /dev/sda1 /dev/sda2 \
194         4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076