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

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/device-mapper/dm-integrity.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/device-mapper/dm-integrity.rst
Extension
.rst
Size
12577 bytes
Lines
309
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

============
dm-integrity
============

The dm-integrity target emulates a block device that has additional
per-sector tags that can be used for storing integrity information.

A general problem with storing integrity tags with every sector is that
writing the sector and the integrity tag must be atomic - i.e. in case of
crash, either both sector and integrity tag or none of them is written.

To guarantee write atomicity, the dm-integrity target uses journal, it
writes sector data and integrity tags into a journal, commits the journal
and then copies the data and integrity tags to their respective location.

The dm-integrity target can be used with the dm-crypt target - in this
situation the dm-crypt target creates the integrity data and passes them
to the dm-integrity target via bio_integrity_payload attached to the bio.
In this mode, the dm-crypt and dm-integrity targets provide authenticated
disk encryption - if the attacker modifies the encrypted device, an I/O
error is returned instead of random data.

The dm-integrity target can also be used as a standalone target, in this
mode it calculates and verifies the integrity tag internally. In this
mode, the dm-integrity target can be used to detect silent data
corruption on the disk or in the I/O path.

There's an alternate mode of operation where dm-integrity uses a bitmap
instead of a journal. If a bit in the bitmap is 1, the corresponding
region's data and integrity tags are not synchronized - if the machine
crashes, the unsynchronized regions will be recalculated. The bitmap mode
is faster than the journal mode, because we don't have to write the data
twice, but it is also less reliable, because if data corruption happens
when the machine crashes, it may not be detected.

When loading the target for the first time, the kernel driver will format
the device. But it will only format the device if the superblock contains
zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
target can't be loaded.

Accesses to the on-disk metadata area containing checksums (aka tags) are
buffered using dm-bufio. When an access to any given metadata area
occurs, each unique metadata area gets its own buffer(s). The buffer size
is capped at the size of the metadata area, but may be smaller, thereby
requiring multiple buffers to represent the full metadata area. A smaller
buffer size will produce a smaller resulting read/write operation to the
metadata area for small reads/writes. The metadata is still read even in
a full write to the data covered by a single buffer.

To use the target for the first time:

1. overwrite the superblock with zeroes
2. load the dm-integrity target with one-sector size, the kernel driver
   will format the device
3. unload the dm-integrity target
4. read the "provided_data_sectors" value from the superblock
5. load the dm-integrity target with the target size
   "provided_data_sectors"
6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
   with the size "provided_data_sectors"


Target arguments:

1. the underlying block device

2. the number of reserved sector at the beginning of the device - the
   dm-integrity won't read of write these sectors

3. the size of the integrity tag (if "-" is used, the size is taken from

Annotation

Implementation Notes