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
32 is faster than the journal mode, because we don't have to write the data
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
46 buffer size will produce a smaller resulting read/write operation to the
48 a full write to the data covered by a single buffer.
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
84 		journaled mode degrades write throughput twice because the
86 	B - bitmap mode - data and metadata are written without any
90 	R - recovery mode - in this mode, journal is not replayed,
130 	When this argument is used, the dm-integrity target won't accept
135 	will protect the data against accidental corruption.
141 	from an upper layer target, such as dm-crypt. The upper layer
157 	the size of files that were written. To protect against this
161 	Protect sector numbers in the journal from accidental or malicious
162 	modification. To protect against accidental modification, use a
163 	crc algorithm, to protect against malicious modification, use a
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
274 		  numbers in the journal section, to protect against a
282 	    - every sector in the data area contains:
289 	512-byte sector of the journal ends with 8-byte commit id. If the
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