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  [--batch-mode,  --no-wipe,  --journal-size,
29              --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  [--batch-mode,  --journal-watermark,  --jour‐
40              nal-commit-time,          --buffer-sectors,         --integrity,
41              --integrity-key-size, --integrity-key-file, --integrity-no-jour‐
42              nal, --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       --journal-watermark PERCENT
89              Journal watermark in percents. When  the  size  of  the  journal
90              exceeds this watermark, the journal flush will be started.
91
92       --journal-commit-time MS
93              Commit  time  in  milliseconds.  When  this  time passes (and no
94              explicit flush operation was issued), the journal is written.
95
96       --tag-size, -t BYTES
97              Size of the integrity tag per-sector (here the  integrity  func‐
98              tion will store authentication tag).
99
100              NOTE: The size can be smaller that output size of the hash func‐
101              tion, in that case only part of the hash will be stored.
102
103       --sector-size, -s BYTES
104              Sector size (power of two: 512, 1024, 2048, 4096).
105
106       --buffer-sectors SECTORS
107              The number of sectors in one buffer.
108
109              The tag area is accessed using buffers, the  large  buffer  size
110              means  that the I/O size will be larger, but there could be less
111              I/Os issued.
112
113       --integrity, -I ALGORITHM
114              Use  internal  integrity  calculation  (standalone  mode).   The
115              integrity  algorithm  can be CRC (crc32c/crc32) or hash function
116              (sha1, sha256).
117
118              For HMAC (hmac-sha256) you have also to specify an integrity key
119              and its size.
120
121       --integrity-key-size BYTES
122              The size of the data integrity key.
123
124       --integrity-key-file FILE
125              The file with the integrity key.
126
127       --integrity-no-journal, -D
128              Disable journal for integrity device.
129
130              WARNING:  In  case  of a crash, it is possible that the data and
131              integrity tag doesn't match if the journal is disabled.
132
133       --integrity-recovery-mode. -R
134              Recovery mode (no journal, no tag checking).
135
136
137       NOTE: The following options are intended for testing purposes only.
138              Using journal encryption does not make sense without  encryption
139              the  data,  these  options  are internally used in authenticated
140              disk encryption with cryptsetup(8).
141
142       --journal-integrity ALGORITHM
143              Integrity algorithm for journal area.   See  --integrity  option
144              for detailed specification.
145
146       --journal-integrity-key-size BYTES
147              The size of the journal integrity key.
148
149       --journal-integrity-key-file FILE
150              The file with the integrity key.
151
152       --journal-crypt ALGORITHM
153              Encryption algorithm for journal data area.  You can use a block
154              cipher here such as cbc(aes) or a stream  cipher,  for  example,
155              chacha20 or ctr(aes).
156
157       --journal-crypt-key-size BYTES
158              The size of the journal encryption key.
159
160       --journal-crypt-key-file FILE
161              The file with the journal encryption key.
162
163       The dm-integrity target is available since Linux kernel version 4.12.
164
165       NOTE:  Format  and  activation  of  an  integrity device always require
166              superuser privilege because the  superblock  is  calculated  and
167              handled in dm-integrity kernel target.
168
169

RETURN CODES

171       Integritysetup returns 0 on success and a non-zero value on error.
172
173       Error codes are:
174           1 wrong parameters
175           2 no permission
176           3 out of memory
177           4 wrong device specified
178           5 device already exists, or device is busy.
179
180

EXAMPLES

182       Format the device with default standalone mode (CRC32C):
183
184       integritysetup format <device>
185
186       Open the device with default parameters:
187
188       integritysetup open <device> test
189
190       Format the device in standalone mode for use with HMAC(SHA256):
191
192       integritysetup  format  <device>  --tag-size 32 --integrity hmac-sha256
193       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
194
195       Open (activate) the device with HMAC(SHA256) and HMAC key in file:
196
197       integritysetup   open    <device>    test    --integrity    hmac-sha256
198       --integrity-key-file <keyfile> --integrity-key-size <key_bytes>
199
200       Dump dm-integrity superblock information:
201
202       integritysetup dump <device>
203
204

REPORTING BUGS

206       Report  bugs,  including  ones  in the documentation, on the cryptsetup
207       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
208       website.   Please  attach  the  output  of  the failed command with the
209       --debug option added.
210

AUTHORS

212       The integritysetup tool is written by Milan Broz  <gmazyland@gmail.com>
213       and is part of the cryptsetup project.
214

COPYRIGHT

216       Copyright © 2016-2018 Red Hat, Inc.
217       Copyright © 2016-2018 Milan Broz
218
219       This is free software; see the source for copying conditions.  There is
220       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
221       PURPOSE.
222