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
44
45       close <name>
46
47              Removes existing mapping <name>.
48
49              For  backward  compatibility,  there is remove command alias for
50              the close command.
51
52       status <name>
53
54              Reports status for the active integrity mapping <name>.
55
56       dump <device>
57
58              Reports parameters from on-disk stored superblock.
59
60

OPTIONS

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

RETURN CODES

183       Integritysetup returns 0 on success and a non-zero value on error.
184
185       Error codes are:
186           1 wrong parameters
187           2 no permission
188           3 out of memory
189           4 wrong device specified
190           5 device already exists, or device is busy.
191
192

EXAMPLES

194       Format the device with default standalone mode (CRC32C):
195
196       integritysetup format <device>
197
198       Open the device with default parameters:
199
200       integritysetup open <device> test
201
202       Format the device in standalone mode for use with HMAC(SHA256):
203
204       integritysetup  format  <device>  --tag-size 32 --integrity hmac-sha256
205       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
206
207       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
208
209       integritysetup   open    <device>    test    --integrity    hmac-sha256
210       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
211
212       Dump dm-integrity superblock information:
213
214       integritysetup dump <device>
215
216

REPORTING BUGS

218       Report  bugs,  including  ones  in the documentation, on the cryptsetup
219       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
220       website.   Please  attach  the  output  of  the failed command with the
221       --debug option added.
222

AUTHORS

224       The integritysetup tool is written by Milan Broz  <gmazyland@gmail.com>
225       and is part of the cryptsetup project.
226

COPYRIGHT

228       Copyright © 2016-2019 Red Hat, Inc.
229       Copyright © 2016-2019 Milan Broz
230
231       This is free software; see the source for copying conditions.  There is
232       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
233       PURPOSE.
234