1CRYPTSETUP-LUKSADDKEY(8) Maintenance Commands CRYPTSETUP-LUKSADDKEY(8)
2
6 cryptsetup-luksAddKey - add a new passphrase
7
9 cryptsetup luksAddKey [<options>] <device> [<key file with new key>]
10
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 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 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 <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
37 --type <device-type>
38 Specifies required device type, for more info read BASIC ACTIONS
39 section in cryptsetup(8).
40 --hash, -h <hash-spec>
42 The specified hash is used for PBKDF2 and AF splitter.
43 --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 --key-file, -d name
50 Read the passphrase from file.
51 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 The passphrase supplied via --key-file is always the passphrase for
56 existing keyslot requested by the command.
57 If you want to set a new passphrase via key file, you have to use a
59 positional argument or parameter --new-keyfile.
60 See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
62 more information.
63 --keyfile-offset value
65 Skip value bytes at the beginning of the key file.
66 --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 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 --new-keyfile name
78 Read the passphrase for a new keyslot from file.
79 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 This is alternative method to positional argument when adding new
84 passphrase via kefile.
85 --new-keyfile-offset value
87 Skip value bytes at the start when adding a new passphrase from key
88 file.
89 --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 --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 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 --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 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 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 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 --new-key-slot <0-N>
127 This option allows you to specify which key slot is selected for
128 the new key.
129 NOTE: When used this option affects --key-slot option.
131 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 --key-size, -s bits
138 Provide volume key size in bits. The argument has to be a multiple
139 of 8.
140 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 --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 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 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 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 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 You can see all PBKDF parameters for particular LUKS2 keyslot with
172 cryptsetup-luksDump(8) command.
173 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 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 --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 --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 --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 --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 --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 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 --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 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 --force-password
232 Do not use password quality checking for new LUKS passwords.
233 This option is ignored if cryptsetup is built without password
235 quality checking support.
236 For more info about password quality check, see the manual page for
238 pwquality.conf(5) and passwdqc.conf(5).
239 --disable-locks
241 Disable lock protection for metadata on disk. This option is valid
242 only for LUKS2 and ignored for other formats.
243 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 --token-id
249 Specify what token to use when unlocking existing keyslot to get
250 volume key.
251 --new-token-id
253 Specify what token to use to get the passphrase for a new keyslot.
254 --token-only
256 Use only LUKS2 tokens to unlock existing volume key.
257 NOTE: To create a new keyslot using passphrase provided by a token
259 use --new-token-id parameter.
260 --token-type type
262 Specify what token type (all type tokens) to use when unlocking
263 existing keyslot to get volume key.
264 --keyslot-cipher <cipher-spec>
266 This option can be used to set specific cipher encryption for the
267 LUKS2 keyslot area.
268 --keyslot-key-size <bits>
270 This option can be used to set specific key size for the LUKS2
271 keyslot area.
272 --unbound
274 Creates new LUKS2 unbound keyslot.
275 --batch-mode, -q
277 Suppresses all confirmation questions. Use with care!
278 If the --verify-passphrase option is not specified, this option
280 also switches off the passphrase verification.
281 --debug or --debug-json
283 Run in debug mode with full diagnostic logs. Debug output lines are
284 always prefixed by #.
285 If --debug-json is used, additional LUKS2 JSON data structures are
287 printed.
288 --version, -V
290 Show the program version.
291 --usage
293 Show short option help.
294 --help, -?
296 Show help text and default parameters.
297
299 NOTE: When not specified otherwise interactive passphrase prompt is
300 always default method.
301 Add new keyslot using interactive passphrase prompt for both existing
303 and new passphrase:
304 cryptsetup luksAddKey /dev/device
306 Add new keyslot using LUKS2 tokens to unlock existing keyslot with
308 interactive passphrase prompt for new passphrase:
309 cryptsetup luksAddKey --token-only /dev/device
311 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 cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device
317 Add new keyslot using interactive passphrase prompt for existing
319 keyslot, reading new passphrase from key_file:
320 cryptsetup luksAddKey --new-keyfile key_file /dev/device or cryptsetup
322 luksAddKey /dev/device key_file
323 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 cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id
329 5 /dev/device
330
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 Please attach output of the failed command with --debug option added.
337
339 Cryptsetup FAQ
340 <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
341 cryptsetup(8), integritysetup(8) and veritysetup(8)
343
345 Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
346cryptsetup 2.6.1 2023-07-19 CRYPTSETUP-LUKSADDKEY(8)