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
16       integrity  checking  of block devices. The dm-integrity target emulates
17       additional 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-recovery-mode,
43              --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       status <name>
54
55              Reports status for the active integrity mapping <name>.
56
57       dump <device>
58
59              Reports parameters from on-disk stored superblock.
60
61

OPTIONS

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

LEGACY COMPATIBILITY OPTIONS

208       WARNING:
209              Do not use these options until you need compatibility with  spe‐
210              cific old kernel.
211
212       --integrity-legacy-padding
213              Use inefficient legacy padding.
214
215       --integrity-legacy-hmac
216              Use   old   flawed   HMAC  calclation  (also  does  not  protect
217              superblock).
218
219       --integrity-legacy-recalculate
220              Allow insecure recalculating of volumes with HMAC  keys  (recal‐
221              cualtion offset in superblock is not protected).
222
223

RETURN CODES

225       Integritysetup returns 0 on success and a non-zero value on error.
226
227       Error codes are:
228           1 wrong parameters
229           2 no permission
230           3 out of memory
231           4 wrong device specified
232           5 device already exists, or device is busy.
233
234

EXAMPLES

236       Format the device with default standalone mode (CRC32C):
237
238       integritysetup format <device>
239
240       Open the device with default parameters:
241
242       integritysetup open <device> test
243
244       Format the device in standalone mode for use with HMAC(SHA256):
245
246       integritysetup  format  <device>  --tag-size 32 --integrity hmac-sha256
247       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
248
249       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
250
251       integritysetup   open    <device>    test    --integrity    hmac-sha256
252       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
253
254       Dump dm-integrity superblock information:
255
256       integritysetup dump <device>
257
258

REPORTING BUGS

260       Report  bugs,  including  ones  in the documentation, on the cryptsetup
261       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
262       website.   Please  attach  the  output  of  the failed command with the
263       --debug option added.
264

AUTHORS

266       The integritysetup tool is written by Milan Broz  <gmazyland@gmail.com>
267       and is part of the cryptsetup project.
268

COPYRIGHT

270       Copyright © 2016-2021 Red Hat, Inc.
271       Copyright © 2016-2021 Milan Broz
272
273       This is free software; see the source for copying conditions.  There is
274       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
275       PURPOSE.
276