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

NAME

6       cryptsetup-token - manage LUKS2 tokens
7

SYNOPSIS

9       cryptsetup token <add|remove|import|export> [<options>] <device>
10

DESCRIPTION

12       Action add creates a new keyring token to enable auto-activation of the
13       device. For the auto-activation, the passphrase must be stored in
14       keyring with the specified description. Usually, the passphrase should
15       be stored in user or user-session keyring. The token command is
16       supported only for LUKS2.
17
18       For adding new keyring token, option --key-description is mandatory.
19       Also, new token is assigned to key slot specified with --key-slot
20       option or to all active key slots in the case --key-slot option is
21       omitted.
22
23       To remove existing token, specify the token ID which should be removed
24       with --token-id option.
25
26       WARNING: The action token remove removes any token type, not just
27       keyring type from token slot specified by --token-id option.
28
29       Action import can store arbitrary valid token json in LUKS2 header. It
30       may be passed via standard input or via file passed in --json-file
31       option. If you specify --key-slot then successfully imported token is
32       also assigned to the key slot.
33
34       Action export writes requested token JSON to a file passed with
35       --json-file or to standard output.
36
37       If --token-id is used with action add or action import and a token with
38       that ID already exists, option --token-replace can be used to replace
39       the existing token.
40
41       <options> can be [--header, --token-id, --key-slot, --key-description,
42       --disable-external-tokens, --disable-locks, --disable-keyring,
43       --json-file, --token-replace].
44

OPTIONS

46       --json-file
47           Read token JSON from a file or write token to it. --json-file=-
48           reads JSON from standard input or writes it to standard output
49           respectively.
50
51       --token-replace
52           Replace an existing token when adding or importing a token with the
53           --token-id option.
54
55       --key-slot, -S <0-N>
56           For LUKS operations that add key material, this option allows you
57           to specify which key slot is selected for the new key.
58
59           The maximum number of key slots depends on the LUKS version. LUKS1
60           can have up to 8 key slots. LUKS2 can have up to 32 key slots based
61           on key slot area size and key size, but a valid key slot ID can
62           always be between 0 and 31 for LUKS2.
63
64       --header <device or file storing the LUKS header>
65           Use a detached (separated) metadata device or file where the LUKS
66           header is stored. This option allows one to store ciphertext and
67           LUKS header on different devices.
68
69           For commands that change the LUKS header (e.g. luksAddKey), specify
70           the device or file with the LUKS header directly as the LUKS
71           device.
72
73       --disable-external-tokens
74           Disable loading of plugins for external LUKS2 tokens.
75
76       --disable-locks
77           Disable lock protection for metadata on disk. This option is valid
78           only for LUKS2 and ignored for other formats.
79
80           WARNING: Do not use this option unless you run cryptsetup in a
81           restricted environment where locking is impossible to perform
82           (where /run directory cannot be used).
83
84       --disable-keyring
85           Do not load volume key in kernel keyring and store it directly in
86           the dm-crypt target instead. This option is supported only for the
87           LUKS2 type.
88
89       --key-description <text>
90           Set key description in keyring for use with token command.
91
92       --token-id
93           Specify what token to use. If omitted, all available tokens will be
94           checked before proceeding further with passphrase prompt.
95
96       --batch-mode, -q
97           Suppresses all confirmation questions. Use with care!
98
99           If the --verify-passphrase option is not specified, this option
100           also switches off the passphrase verification.
101
102       --debug or --debug-json
103           Run in debug mode with full diagnostic logs. Debug output lines are
104           always prefixed by #.
105
106           If --debug-json is used, additional LUKS2 JSON data structures are
107           printed.
108
109       --version, -V
110           Show the program version.
111
112       --usage
113           Show short option help.
114
115       --help, -?
116           Show help text and default parameters.
117

REPORTING BUGS

119       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
120       in Issues project section
121       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
122
123       Please attach output of the failed command with --debug option added.
124

SEE ALSO

126       Cryptsetup FAQ
127       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
128
129       cryptsetup(8), integritysetup(8) and veritysetup(8)
130

CRYPTSETUP

132       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
133
134
135
136cryptsetup 2.5.0                  2022-07-28               CRYPTSETUP-TOKEN(8)