admin-guide/device-mapper/dm-integrity.rst

2 dm-integrity
5 The dm-integrity target emulates a block device that has additional
6 per-sector tags that can be used for storing integrity information.
9 writing the sector and the integrity tag must be atomic - i.e. in case of
12 To guarantee write atomicity, the dm-integrity target uses journal, it
16 The dm-integrity target can be used with the dm-crypt target - in this
17 situation the dm-crypt target creates the integrity data and passes them
18 to the dm-integrity target via bio_integrity_payload attached to the bio.
19 In this mode, the dm-crypt and dm-integrity targets provide authenticated
20 disk encryption - if the attacker modifies the encrypted device, an I/O
23 The dm-integrity target can also be used as a standalone target, in this
25 mode, the dm-integrity target can be used to detect silent data
28 There's an alternate mode of operation where dm-integrity uses a bitmap
30 region's data and integrity tags are not synchronized - if the machine
38 zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
41 Accesses to the on-disk metadata area containing checksums (aka tags) are
42 buffered using dm-bufio. When an access to any given metadata area
53 2. load the dm-integrity target with one-sector size, the kernel driver
55 3. unload the dm-integrity target
57 5. load the dm-integrity target with the target size
59 6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
67 2. the number of reserved sector at the beginning of the device - the
68    dm-integrity won't read of write these sectors
70 3. the size of the integrity tag (if "-" is used, the size is taken from
71    the internal-hash algorithm)
75 	D - direct writes (without journal)
80 	J - journaled writes
86 	B - bitmap mode - data and metadata are written without any
90 	R - recovery mode - in this mode, journal is not replayed,
106 	The number of interleaved sectors. This values is rounded down to
130 	When this argument is used, the dm-integrity target won't accept
141 	from an upper layer target, such as dm-crypt. The upper layer
166 	This option is not needed when using internal-hash because in this
173 	less overhead there is for per-block integrity metadata.
178 	512-byte sectors that corresponds to one bitmap bit.
190 	space-efficient. If this option is not present, large padding is
191 	used - that is for compatibility with older kernels.
196 	- the section number is mixed to the mac, so that an attacker can't
198 	- the superblock is protected by journal_mac
199 	- a 16-byte salt stored in the superblock is mixed to the mac, so
206 	default for security reasons - an attacker could modify the volume,
214 data depend on them and the reloaded target would be non-functional.
226 2. provided data sectors - that is the number of sectors that the user
228 3. the current recalculating position (or '-' if we didn't recalculate)
239 	* magic string - identifies that the device was formatted
244 	* provided data sectors - the number of sectors that this target
250 		- a flag is set if journal_mac is used
252 		- recalculating is in progress
254 		- journal area contains the bitmap of dirty
263 	  - every journal entry contains:
270 	  - every metadata sector ends with
272 		* mac (8-bytes), all the macs in 8 metadata sectors form a
273 		  64-byte value. It is used to store hmac of sector
282 	    - every sector in the data area contains:
289 	512-byte sector of the journal ends with 8-byte commit id. If the
295 * one or more runs of interleaved tags and data.
298 	* tag area - it contains integrity tags. There is one tag for each
301 	* data area - it contains data sectors. The number of data sectors