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
24 mode it calculates and verifies the integrity tag internally. 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
31 crashes, the unsynchronized regions will be recalculated. The bitmap mode
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
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)
73 4. mode:
75 	D - direct writes (without journal)
76 		in this mode, journaling is
80 	J - journaled writes
84 		journaled mode degrades write throughput twice because the
86 	B - bitmap mode - data and metadata are written without any
88 		regions where data and metadata don't match. This mode can
90 	R - recovery mode - in this mode, journal is not replayed,
92 		allowed. This mode is useful for data recovery if the
111 	Don't interleave the data and metadata on the device. Use a
130 	When this argument is used, the dm-integrity target won't accept
137 	"hmac(sha256):0123456789abcdef"), in this mode it will provide
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
167 	mode, the integrity of journal entries is checked when replaying
173 	less overhead there is for per-block integrity metadata.
177 	In the bitmap mode, this parameter specifies the number of
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,
210 The journal mode (D/J), buffer_sectors, journal_watermark, commit_time and
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
241 	* log2(interleave sectors)
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
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