1 ============
2 dm-integrity
3 ============
4
5 The dm-integrity target emulates a block devic
6 per-sector tags that can be used for storing i
7
8 A general problem with storing integrity tags
9 writing the sector and the integrity tag must
10 crash, either both sector and integrity tag or
11
12 To guarantee write atomicity, the dm-integrity
13 writes sector data and integrity tags into a j
14 and then copies the data and integrity tags to
15
16 The dm-integrity target can be used with the d
17 situation the dm-crypt target creates the inte
18 to the dm-integrity target via bio_integrity_p
19 In this mode, the dm-crypt and dm-integrity ta
20 disk encryption - if the attacker modifies the
21 error is returned instead of random data.
22
23 The dm-integrity target can also be used as a
24 mode it calculates and verifies the integrity
25 mode, the dm-integrity target can be used to d
26 corruption on the disk or in the I/O path.
27
28 There's an alternate mode of operation where d
29 instead of a journal. If a bit in the bitmap i
30 region's data and integrity tags are not synch
31 crashes, the unsynchronized regions will be re
32 is faster than the journal mode, because we do
33 twice, but it is also less reliable, because i
34 when the machine crashes, it may not be detect
35
36 When loading the target for the first time, th
37 the device. But it will only format the device
38 zeroes. If the superblock is neither valid nor
39 target can't be loaded.
40
41 Accesses to the on-disk metadata area containi
42 buffered using dm-bufio. When an access to any
43 occurs, each unique metadata area gets its own
44 is capped at the size of the metadata area, bu
45 requiring multiple buffers to represent the fu
46 buffer size will produce a smaller resulting r
47 metadata area for small reads/writes. The meta
48 a full write to the data covered by a single b
49
50 To use the target for the first time:
51
52 1. overwrite the superblock with zeroes
53 2. load the dm-integrity target with one-secto
54 will format the device
55 3. unload the dm-integrity target
56 4. read the "provided_data_sectors" value from
57 5. load the dm-integrity target with the targe
58 "provided_data_sectors"
59 6. if you want to use dm-integrity with dm-cry
60 with the size "provided_data_sectors"
61
62
63 Target arguments:
64
65 1. the underlying block device
66
67 2. the number of reserved sector at the beginn
68 dm-integrity won't read of write these sect
69
70 3. the size of the integrity tag (if "-" is us
71 the internal-hash algorithm)
72
73 4. mode:
74
75 D - direct writes (without journal)
76 in this mode, journaling is
77 not used and data sectors and
78 separately. In case of crash,
79 and integrity tag doesn't matc
80 J - journaled writes
81 data and integrity tags are wr
82 journal and atomicity is guara
83 either both data and tag or no
84 journaled mode degrades write
85 data have to be written twice.
86 B - bitmap mode - data and metadata ar
87 synchronization, the driver ma
88 regions where data and metadat
89 only be used with internal has
90 R - recovery mode - in this mode, jour
91 checksums are not checked and
92 allowed. This mode is useful f
93 device cannot be activated in
94 modes.
95
96 5. the number of additional arguments
97
98 Additional arguments:
99
100 journal_sectors:number
101 The size of journal, this argument is
102 device. If the device is already forma
103 superblock is used.
104
105 interleave_sectors:number (default 32768)
106 The number of interleaved sectors. Thi
107 a power of two. If the device is alrea
108 the superblock is used.
109
110 meta_device:device
111 Don't interleave the data and metadata
112 separate device for metadata.
113
114 buffer_sectors:number (default 128)
115 The number of sectors in one metadata
116 down to a power of two.
117
118 journal_watermark:number (default 50)
119 The journal watermark in percents. Whe
120 exceeds this watermark, the thread tha
121 be started.
122
123 commit_time:number (default 10000)
124 Commit time in milliseconds. When this
125 written. The journal is also written i
126 request is received.
127
128 internal_hash:algorithm(:key) (the key is op
129 Use internal hash or crc.
130 When this argument is used, the dm-int
131 integrity tags from the upper target,
132 generate and verify the integrity tags
133
134 You can use a crc algorithm (such as c
135 will protect the data against accident
136 You can also use a hmac algorithm (for
137 "hmac(sha256):0123456789abcdef"), in t
138 cryptographic authentication of the da
139
140 When this argument is not used, the in
141 from an upper layer target, such as dm
142 target should check the validity of th
143
144 recalculate
145 Recalculate the integrity tags automat
146 when using internal hash.
147
148 journal_crypt:algorithm(:key) (the key is op
149 Encrypt the journal using given algori
150 attacker can't read the journal. You c
151 (such as "cbc(aes)") or a stream ciphe
152 or "ctr(aes)").
153
154 The journal contains history of last w
155 an attacker reading the journal could
156 that were written. From the sector num
157 the size of files that were written. T
158 situation, you can encrypt the journal
159
160 journal_mac:algorithm(:key) (the key is op
161 Protect sector numbers in the journal
162 modification. To protect against accid
163 crc algorithm, to protect against mali
164 hmac algorithm with a key.
165
166 This option is not needed when using i
167 mode, the integrity of journal entries
168 the journal. Thus, modified sector num
169 this stage.
170
171 block_size:number (default 512)
172 The size of a data block in bytes. The
173 less overhead there is for per-block i
174 Supported values are 512, 1024, 2048 a
175
176 sectors_per_bit:number
177 In the bitmap mode, this parameter spe
178 512-byte sectors that corresponds to o
179
180 bitmap_flush_interval:number
181 The bitmap flush interval in milliseco
182 are synchronized when this interval ex
183
184 allow_discards
185 Allow block discard requests (a.k.a. T
186 Discards are only allowed to devices u
187
188 fix_padding
189 Use a smaller padding of the tag area
190 space-efficient. If this option is not
191 used - that is for compatibility with
192
193 fix_hmac
194 Improve security of internal_hash and
195
196 - the section number is mixed to the m
197 copy sectors from one journal sectio
198 - the superblock is protected by journ
199 - a 16-byte salt stored in the superbl
200 that the attacker can't detect that
201 key and also to disallow the attacke
202 disk to another
203
204 legacy_recalculate
205 Allow recalculating of volumes with HM
206 default for security reasons - an atta
207 set recalc_sector to zero, and the ker
208 modification.
209
210 The journal mode (D/J), buffer_sectors, journa
211 allow_discards can be changed when reloading t
212 table and swap the tables with suspend and res
213 should not be changed when reloading the targe
214 data depend on them and the reloaded target wo
215
216 For example, on a device using the default int
217 block_size of 512, and an internal_hash of crc
218 bytes, it will take 128 KiB of tags to track a
219 256 sectors of metadata per data area. With th
220 128, that means there will be 2 buffers per me
221 per 16 MiB of data.
222
223 Status line:
224
225 1. the number of integrity mismatches
226 2. provided data sectors - that is the number
227 could use
228 3. the current recalculating position (or '-'
229
230
231 The layout of the formatted block device:
232
233 * reserved sectors
234 (they are not used by this target, they ca
235 storing LUKS metadata or for other purpose
236 area is specified in the target arguments
237
238 * superblock (4kiB)
239 * magic string - identifies that the d
240 * version
241 * log2(interleave sectors)
242 * integrity tag size
243 * the number of journal sections
244 * provided data sectors - the number o
245 provides (i.e. the size of the devic
246 metadata and padding). The user of t
247 bios that access data beyond the "pr
248 * flags
249 SB_FLAG_HAVE_JOURNAL_MAC
250 - a flag is set if journal_mac
251 SB_FLAG_RECALCULATING
252 - recalculating is in progress
253 SB_FLAG_DIRTY_BITMAP
254 - journal area contains the bi
255 blocks
256 * log2(sectors per block)
257 * a position where recalculating finis
258 * journal
259 The journal is divided into sections,
260
261 * metadata area (4kiB), it contains jo
262
263 - every journal entry contains:
264
265 * logical sector (specifies wh
266 be written)
267 * last 8 bytes of data
268 * integrity tag (the size is s
269
270 - every metadata sector ends with
271
272 * mac (8-bytes), all the macs
273 64-byte value. It is used to
274 numbers in the journal secti
275 possibility that the attacke
276 numbers in the journal.
277 * commit id
278
279 * data area (the size is variable; it
280 entries fit into the metadata area)
281
282 - every sector in the data area co
283
284 * data (504 bytes of data, the
285 the journal entry)
286 * commit id
287
288 To test if the whole journal section w
289 512-byte sector of the journal ends wi
290 commit id matches on all sectors in a
291 assumed that the section was written c
292 doesn't match, the section was written
293 be replayed.
294
295 * one or more runs of interleaved tags and dat
296 Each run contains:
297
298 * tag area - it contains integrity tag
299 sector in the data area. The size of
300 greater.
301 * data area - it contains data sectors
302 in one run must be a power of two. l
303 in the superblock.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.