1CRYPTSETUP-LUKSADDKEY(8)     Maintenance Commands     CRYPTSETUP-LUKSADDKEY(8)
2
3
4

NAME

6       cryptsetup-luksAddKey - add a new passphrase
7

SYNOPSIS

9       cryptsetup luksAddKey [<options>] <device> [<key file with new key>]
10

DESCRIPTION

12       Adds a keyslot protected by a new passphrase. An existing passphrase
13       must be supplied interactively, via --key-file or LUKS2 token (plugin).
14       Alternatively to existing passphrase user may pass directly volume key
15       (via --volume-key-file). The new passphrase to be added can be
16       specified interactively, read from the file given as the positional
17       argument (also via --new-keyfile parameter) or via LUKS2 token.
18
19       NOTE: with --unbound option the action creates new unbound LUKS2
20       keyslot. The keyslot cannot be used for device activation. If you don’t
21       pass new key via --volume-key-file option, new random key is generated.
22       Existing passphrase for any active keyslot is not required.
23
24       NOTE: some parameters are effective only if used with LUKS2 format that
25       supports per-keyslot parameters. For LUKS1, PBKDF type and hash
26       algorithm is always the same for all keyslots.
27
28       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
29       --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot,
30       --new-key-slot, --volume-key-file, --force-password, --hash, --header,
31       --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations,
32       --pbkdf-memory, --pbkdf-parallel, --unbound, --type, --keyslot-cipher,
33       --keyslot-key-size, --key-size, --timeout, --token-id, --token-type,
34       --token-only, --new-token-id, --verify-passphrase].
35

OPTIONS

37       --type <device-type>
38           Specifies required device type, for more info read BASIC ACTIONS
39           section in cryptsetup(8).
40
41       --hash, -h <hash-spec>
42           The specified hash is used for PBKDF2 and AF splitter.
43
44       --verify-passphrase, -y
45           When interactively asking for a passphrase, ask for it twice and
46           complain if both inputs do not match. Ignored on input from file or
47           stdin.
48
49       --key-file, -d name
50           Read the passphrase from file.
51
52           If the name given is "-", then the passphrase will be read from
53           stdin. In this case, reading will not stop at newline characters.
54
55           The passphrase supplied via --key-file is always the passphrase for
56           existing keyslot requested by the command.
57
58           If you want to set a new passphrase via key file, you have to use a
59           positional argument or parameter --new-keyfile.
60
61           See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
62           more information.
63
64       --keyfile-offset value
65           Skip value bytes at the beginning of the key file.
66
67       --keyfile-size, -l value
68           Read a maximum of value bytes from the key file. The default is to
69           read the whole file up to the compiled-in maximum that can be
70           queried with --help. Supplying more data than the compiled-in
71           maximum aborts the operation.
72
73           This option is useful to cut trailing newlines, for example. If
74           --keyfile-offset is also given, the size count starts after the
75           offset.
76
77       --new-keyfile name
78           Read the passphrase for a new keyslot from file.
79
80           If the name given is "-", then the passphrase will be read from
81           stdin. In this case, reading will not stop at newline characters.
82
83           This is alternative method to positional argument when adding new
84           passphrase via kefile.
85
86       --new-keyfile-offset value
87           Skip value bytes at the start when adding a new passphrase from key
88           file.
89
90       --new-keyfile-size value
91           Read a maximum of value bytes when adding a new passphrase from key
92           file. The default is to read the whole file up to the compiled-in
93           maximum length that can be queried with --help. Supplying more than
94           the compiled in maximum aborts the operation. When
95           --new-keyfile-offset is also given, reading starts after the
96           offset.
97
98       --volume-key-file, --master-key-file (OBSOLETE alias)
99           Use a volume key stored in a file. This allows adding a new keyslot
100           without having to know passphrase to existing one. It may be also
101           used when no keyslot is active.
102
103           WARNING: If you create your own volume key, you need to make sure
104           to do it right. Otherwise, you can end up with a low-entropy or
105           otherwise partially predictable volume key which will compromise
106           security.
107
108       --key-slot, -S <0-N>
109           When used together with parameter --new-key-slot this option allows
110           you to specify which key slot is selected for unlocking volume key.
111
112           NOTE: This option is ignored if existing volume key gets unlocked
113           via LUKS2 token (--token-id, --token-type or --token-only
114           parameters) or when volume key is provided directly via
115           --volume-key-file parameter.
116
117           NOTE: To maintain backward compatibility, without --new-key-slot
118           parameter, this option allows you to specify which key slot is
119           selected for the new key.
120
121           The maximum number of key slots depends on the LUKS version. LUKS1
122           can have up to 8 key slots. LUKS2 can have up to 32 key slots based
123           on key slot area size and key size, but a valid key slot ID can
124           always be between 0 and 31 for LUKS2.
125
126       --new-key-slot <0-N>
127           This option allows you to specify which key slot is selected for
128           the new key.
129
130           NOTE: When used this option affects --key-slot option.
131
132           The maximum number of key slots depends on the LUKS version. LUKS1
133           can have up to 8 key slots. LUKS2 can have up to 32 key slots based
134           on key slot area size and key size, but a valid key slot ID can
135           always be between 0 and 31 for LUKS2.
136
137       --key-size, -s bits
138           Provide volume key size in bits. The argument has to be a multiple
139           of 8.
140
141           This option is required when parameter --volume-key-file is used to
142           provide current volume key. Also, it is used when new unbound
143           keyslot is created by specifying --unbound parameter.
144
145       --pbkdf <PBKDF spec>
146           Set Password-Based Key Derivation Function (PBKDF) algorithm for
147           LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to
148           RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2
149           <https://www.cryptolux.org/index.php/Argon2> for more info).
150
151           For LUKS1, only PBKDF2 is accepted (no need to use this option).
152           The default PBKDF for LUKS2 is set during compilation time and is
153           available in cryptsetup --help output.
154
155           A PBKDF is used for increasing dictionary and brute-force attack
156           cost for keyslot passwords. The parameters can be time, memory and
157           parallel cost.
158
159           For PBKDF2, only time cost (number of iterations) applies. For
160           Argon2i/id, there is also memory cost (memory required during the
161           process of key derivation) and parallel cost (number of threads
162           that run in parallel during the key derivation.
163
164           Note that increasing memory cost also increases time, so the final
165           parameter values are measured by a benchmark. The benchmark tries
166           to find iteration time (--iter-time) with required memory cost
167           --pbkdf-memory. If it is not possible, the memory cost is decreased
168           as well. The parallel cost --pbkdf-parallel is constant and is
169           checked against available CPU cores.
170
171           You can see all PBKDF parameters for particular LUKS2 keyslot with
172           cryptsetup-luksDump(8) command.
173
174           NOTE: If you do not want to use benchmark and want to specify all
175           parameters directly, use --pbkdf-force-iterations with
176           --pbkdf-memory and --pbkdf-parallel. This will override the values
177           without benchmarking. Note it can cause extremely long unlocking
178           time. Use only in specific cases, for example, if you know that the
179           formatted device will be used on some small embedded system.
180
181           MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration
182           count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned
183           integer). Memory and parallel costs are unused for PBKDF2. For
184           Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and
185           maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum
186           memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable
187           memory on some CPU platforms.) If the memory cost parameter is
188           benchmarked (not specified by a parameter) it is always in range
189           from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4
190           (if enough CPUs cores are available, otherwise it is decreased).
191
192       --iter-time, -i <number of milliseconds>
193           The number of milliseconds to spend with PBKDF passphrase
194           processing. Specifying 0 as parameter selects the compiled-in
195           default.
196
197       --pbkdf-memory <number>
198           Set the memory cost for PBKDF (for Argon2i/id the number represents
199           kilobytes). Note that it is maximal value, PBKDF benchmark or
200           available physical memory can decrease it. This option is not
201           available for PBKDF2.
202
203       --pbkdf-parallel <number>
204           Set the parallel cost for PBKDF (number of threads, up to 4). Note
205           that it is maximal value, it is decreased automatically if CPU
206           online count is lower. This option is not available for PBKDF2.
207
208       --pbkdf-force-iterations <num>
209           Avoid PBKDF benchmark and set time cost (iterations) directly. It
210           can be used for LUKS/LUKS2 device only. See --pbkdf option for more
211           info.
212
213       --timeout, -t <number of seconds>
214           The number of seconds to wait before timeout on passphrase input
215           via terminal. It is relevant every time a passphrase is asked. It
216           has no effect if used in conjunction with --key-file.
217
218           This option is useful when the system should not stall if the user
219           does not input a passphrase, e.g. during boot. The default is a
220           value of 0 seconds, which means to wait forever.
221
222       --header <device or file storing the LUKS header>
223           Use a detached (separated) metadata device or file where the LUKS
224           header is stored. This option allows one to store ciphertext and
225           LUKS header on different devices.
226
227           For commands that change the LUKS header (e.g. luksAddKey), specify
228           the device or file with the LUKS header directly as the LUKS
229           device.
230
231       --force-password
232           Do not use password quality checking for new LUKS passwords.
233
234           This option is ignored if cryptsetup is built without password
235           quality checking support.
236
237           For more info about password quality check, see the manual page for
238           pwquality.conf(5) and passwdqc.conf(5).
239
240       --disable-locks
241           Disable lock protection for metadata on disk. This option is valid
242           only for LUKS2 and ignored for other formats.
243
244           WARNING: Do not use this option unless you run cryptsetup in a
245           restricted environment where locking is impossible to perform
246           (where /run directory cannot be used).
247
248       --token-id
249           Specify what token to use when unlocking existing keyslot to get
250           volume key.
251
252       --new-token-id
253           Specify what token to use to get the passphrase for a new keyslot.
254
255       --token-only
256           Use only LUKS2 tokens to unlock existing volume key.
257
258           NOTE: To create a new keyslot using passphrase provided by a token
259           use --new-token-id parameter.
260
261       --token-type type
262           Specify what token type (all type tokens) to use when unlocking
263           existing keyslot to get volume key.
264
265       --keyslot-cipher <cipher-spec>
266           This option can be used to set specific cipher encryption for the
267           LUKS2 keyslot area.
268
269       --keyslot-key-size <bits>
270           This option can be used to set specific key size for the LUKS2
271           keyslot area.
272
273       --unbound
274           Creates new LUKS2 unbound keyslot.
275
276       --batch-mode, -q
277           Suppresses all confirmation questions. Use with care!
278
279           If the --verify-passphrase option is not specified, this option
280           also switches off the passphrase verification.
281
282       --debug or --debug-json
283           Run in debug mode with full diagnostic logs. Debug output lines are
284           always prefixed by #.
285
286           If --debug-json is used, additional LUKS2 JSON data structures are
287           printed.
288
289       --version, -V
290           Show the program version.
291
292       --usage
293           Show short option help.
294
295       --help, -?
296           Show help text and default parameters.
297

EXAMPLES

299       NOTE: When not specified otherwise interactive passphrase prompt is
300       always default method.
301
302       Add new keyslot using interactive passphrase prompt for both existing
303       and new passphrase:
304
305       cryptsetup luksAddKey /dev/device
306
307       Add new keyslot using LUKS2 tokens to unlock existing keyslot with
308       interactive passphrase prompt for new passphrase:
309
310       cryptsetup luksAddKey --token-only /dev/device
311
312       Add new keyslot using LUKS2 systemd-tpm2 tokens to unlock existing
313       keyslot with interactive passphrase prompt for new passphrase
314       (systemd-tpm2 token plugin must be available):
315
316       cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device
317
318       Add new keyslot using interactive passphrase prompt for existing
319       keyslot, reading new passphrase from key_file:
320
321       cryptsetup luksAddKey --new-keyfile key_file /dev/device or cryptsetup
322       luksAddKey /dev/device key_file
323
324       Add new keyslot using volume stored in volume_key_file and LUKS2 token
325       in slot 5 to get new keyslot passphrase (token in slot 5 must exist and
326       respective token plugin must be available):
327
328       cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id
329       5 /dev/device
330

REPORTING BUGS

332       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
333       in Issues project section
334       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
335
336       Please attach output of the failed command with --debug option added.
337

SEE ALSO

339       Cryptsetup FAQ
340       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
341
342       cryptsetup(8), integritysetup(8) and veritysetup(8)
343

CRYPTSETUP

345       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
346
347
348
349cryptsetup 2.6.1                  2023-02-10          CRYPTSETUP-LUKSADDKEY(8)
Impressum