integritysetup(8)

1INTEGRITYSETUP(8)            Maintenance Commands            INTEGRITYSETUP(8)
2
3
4

NAME

6       integritysetup - manage dm-integrity (block level integrity) volumes
7

SYNOPSIS

9       integritysetup <options> <action> <action args>
10

DESCRIPTION

12       Integritysetup  is used to configure dm-integrity managed device-mapper
13       mappings.
14
15       Device-mapper integrity target provides read-write  transparent  integ‐
16       rity  checking of block devices. The dm-integrity target emulates addi‐
17       tional data integrity field per-sector. You  can  use  this  additional
18       field  directly with integritysetup utility, or indirectly (for authen‐
19       ticated encryption) through cryptsetup.
20
21       Integritysetup supports these operations:
22
23       format <device>
24
25              Formats <device> (calculates space and  dm-integrity  superblock
26              and wipes the device).
27
28              <options>   can   be  [--data-device,  --batch-mode,  --no-wipe,
29              --journal-size, --interleave-sectors,  --tag-size,  --integrity,
30              --integrity-key-size,    --integrity-key-file,    --sector-size,
31              --progress-frequency]
32
33
34       open <device> <name>
35       create <name> <device> (OBSOLETE syntax)
36
37              Open a mapping with <name> backed by device <device>.
38
39              <options> can be [--data-device, --batch-mode,  --journal-water‐
40              mark,   --journal-commit-time,   --buffer-sectors,  --integrity,
41              --integrity-key-size, --integrity-key-file, --integrity-no-jour‐
42              nal,     --integrity-recalculate,    --integrity-recalculate-re‐
43              set,--integrity-recovery-mode, --allow-discards]
44
45
46       close <name>
47
48              Removes existing mapping <name>.
49
50              For backward compatibility, there is remove  command  alias  for
51              the close command.
52
53              <options> can be [--deferred] or [--cancel-deferred]
54
55
56       status <name>
57
58              Reports status for the active integrity mapping <name>.
59
60       dump <device>
61
62              Reports parameters from on-disk stored superblock.
63
64

OPTIONS

66       --verbose, -v
67              Print more information on command execution.
68
69       --debug
70              Run  in debug mode with full diagnostic logs. Debug output lines
71              are always prefixed by '#'.
72
73       --version
74              Show the program version.
75
76       --batch-mode
77              Do not ask for confirmation.
78
79       --progress-frequency <seconds>
80              Print separate line every <seconds> with wipe progress.
81
82       --no-wipe
83              Do not wipe the device after format. A device that is  not  ini‐
84              tially wiped will contain invalid checksums.
85
86       --journal-size, -j BYTES
87              Size of the journal.
88
89       --interleave-sectors SECTORS
90              The number of interleaved sectors.
91
92       --integrity-recalculate
93              Automatically  recalculate  integrity  tags in kernel on activa‐
94              tion.  The device can be used during automatic integrity  recal‐
95              culation  but  becomes  fully integrity protected only after the
96              background operation is  finished.   This  option  is  available
97              since the Linux kernel version 4.19.
98
99       --integrity-recalculate-reset
100              Restart  recalculation from the beginning of the device.  It can
101              be used to change the integrity checksum function.  Note it does
102              not  change  the tag length.  This option is available since the
103              Linux kernel version 5.13.
104
105       --journal-watermark PERCENT
106              Journal watermark in percents. When the size of the journal  ex‐
107              ceeds this watermark, the journal flush will be started.
108
109       --journal-commit-time MS
110              Commit  time  in milliseconds. When this time passes (and no ex‐
111              plicit flush operation was issued), the journal is written.
112
113       --tag-size, -t BYTES
114              Size of the integrity tag per-sector (here the  integrity  func‐
115              tion will store authentication tag).
116
117              NOTE: The size can be smaller that output size of the hash func‐
118              tion, in that case only part of the hash will be stored.
119
120       --data-device
121              Specify a separate data device that contains existing data.  The
122              <device> then will contain calculated integrity tags and journal
123              for this data device.
124
125       --sector-size, -s BYTES
126              Sector size (power of two: 512, 1024, 2048, 4096).
127
128       --buffer-sectors SECTORS
129              The number of sectors in one buffer.
130
131              The tag area is accessed using buffers, the  large  buffer  size
132              means  that the I/O size will be larger, but there could be less
133              I/Os issued.
134
135       --integrity, -I ALGORITHM
136              Use internal integrity calculation (standalone mode).   The  in‐
137              tegrity  algorithm  can  be  CRC (crc32c/crc32) or hash function
138              (sha1, sha256).
139
140              For HMAC (hmac-sha256) you have also to specify an integrity key
141              and its size.
142
143       --integrity-key-size BYTES
144              The size of the data integrity key. Maximum is 4096 bytes.
145
146       --integrity-key-file FILE
147              The file with the integrity key.
148
149       --integrity-no-journal, -D
150              Disable journal for integrity device.
151
152       --integrity-bitmap-mode. -B
153              Use  alternate  bitmap  mode  (available since Linux kernel 5.2)
154              where dm-integrity uses bitmap instead of a journal. If a bit in
155              the  bitmap  is 1, the corresponding region's data and integrity
156              tags are not synchronized - if the machine crashes,  the  unsyn‐
157              chronized  regions  will  be  recalculated.   The bitmap mode is
158              faster than the journal mode, because we don't have to write the
159              data  twice,  but it is also less reliable, because if data cor‐
160              ruption happens when the machine crashes,  it  may  not  be  de‐
161              tected.
162
163       --bitmap-sectors-per-bit SECTORS
164              Number  of  512-byte  sectors  per bitmap bit, the value must be
165              power of two.
166
167       --bitmap-flush-time MS
168              Bitmap flush time in milliseconds.
169
170
171       WARNING:
172              In case of a crash, it is possible that the data  and  integrity
173              tag doesn't match if the journal is disabled.
174
175       --integrity-recovery-mode. -R
176              Recovery mode (no journal, no tag checking).
177
178
179       NOTE: The following options are intended for testing purposes only.
180              Using  journal encryption does not make sense without encryption
181              the data, these options are  internally  used  in  authenticated
182              disk encryption with cryptsetup(8).
183
184       --journal-integrity ALGORITHM
185              Integrity  algorithm  for  journal area.  See --integrity option
186              for detailed specification.
187
188       --journal-integrity-key-size BYTES
189              The size of the journal integrity key. Maximum is 4096 bytes.
190
191       --journal-integrity-key-file FILE
192              The file with the integrity key.
193
194       --journal-crypt ALGORITHM
195              Encryption algorithm for journal data area.  You can use a block
196              cipher  here  such  as  cbc-aes or a stream cipher, for example,
197              chacha20 or ctr-aes.
198
199       --journal-crypt-key-size BYTES
200              The size of the journal encryption key. Maximum is 4096 bytes.
201
202       --journal-crypt-key-file FILE
203              The file with the journal encryption key.
204
205       --allow-discards
206              Allow the use of discard (TRIM) requests for the  device.   This
207              option is available since the Linux kernel version 5.7.
208
209       --deferred
210              Defers  device  removal  in  close  command  until the last user
211              closes it.
212
213       --cancel-deferred
214              Removes a previously configured deferred device removal in close
215              command.
216
217       The dm-integrity target is available since Linux kernel version 4.12.
218
219       NOTE:  Format  and activation of an integrity device always require su‐
220              peruser privilege because the superblock is calculated and  han‐
221              dled in dm-integrity kernel target.
222
223

LEGACY COMPATIBILITY OPTIONS

225       WARNING:
226              Do  not use these options until you need compatibility with spe‐
227              cific old kernel.
228
229       --integrity-legacy-padding
230              Use inefficient legacy padding.
231
232       --integrity-legacy-hmac
233              Use old flawed  HMAC  calclation  (also  does  not  protect  su‐
234              perblock).
235
236       --integrity-legacy-recalculate
237              Allow  insecure  recalculating of volumes with HMAC keys (recal‐
238              cualtion offset in superblock is not protected).
239
240

RETURN CODES

242       Integritysetup returns 0 on success and a non-zero value on error.
243
244       Error codes are:
245           1 wrong parameters
246           2 no permission
247           3 out of memory
248           4 wrong device specified
249           5 device already exists, or device is busy.
250
251

EXAMPLES

253       Format the device with default standalone mode (CRC32C):
254
255       integritysetup format <device>
256
257       Open the device with default parameters:
258
259       integritysetup open <device> test
260
261       Format the device in standalone mode for use with HMAC(SHA256):
262
263       integritysetup format <device> --tag-size  32  --integrity  hmac-sha256
264       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
265
266       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
267
268       integritysetup  open  <device>  test  --integrity  hmac-sha256 --integ‐
269       rity-key-file <keyfile> --integrity-key-size <key_bytes>
270
271       Dump dm-integrity superblock information:
272
273       integritysetup dump <device>
274
275

REPORTING BUGS

277       Report bugs, including ones in the  documentation,  on  the  cryptsetup
278       mailing  list at <dm-crypt@saout.de> or in the 'Issues' section on LUKS
279       website.  Please attach the output of the failed command with the --de‐
280       bug option added.
281

AUTHORS

283       The  integritysetup tool is written by Milan Broz <gmazyland@gmail.com>
284       and is part of the cryptsetup project.
285

COPYRIGHT

287       Copyright © 2016-2021 Red Hat, Inc.
288       Copyright © 2016-2021 Milan Broz
289
290       This is free software; see the source for copying conditions.  There is
291       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
292       PURPOSE.
293