I am trying to understand the token subsystem in cryptsetup in order to create a plugin.
The cryptsetup project has multiple sources of documentation
man pages
cryptsetup
specifications documents
FAQ
Wiki
Release Notes
source code
docs folder
other
mailing list
Here is all of the token information from each documentation source
....
If cryptsetup detected volume key for active device loaded in kernel keyring service, resize action would first try to retrieve the key using a token and only if it failed it'd ask for a passphrase to unlock a keyslot (LUKS) or to derive a volume key again (plain mode). The kernel keyring is used by default for LUKS2 devices.
With LUKS2 device additional <options> can be [--token-id, --token-only, --token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset, --timeout, --disable-external-tokens, --disable-locks, --dis‐able-keyring].
....
open --type luks <device> <name>
luksOpen <device> <name> (old syntax)
Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase.
First, the passphrase is searched in LUKS tokens. If it's not found in any token and also the passphrase is not supplied via --key-file, the command prompts for it interactively.
<options> can be [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --master-key-file, --token-id, --token-only, --token-type, --disable-ex‐ternal-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf].
....
token <add|remove|import|export> <device>
Action add creates new keyring token to enable auto-activation of the device. For the auto-activation, the passphrase must be stored in keyring with the specified description. Usually, the passphrase should be stored in user or user-session keyring. The token command is supported only for LUKS2.
For adding new keyring token, option --key-description is mandatory. Also, new token is assigned to key slot specified with --key-slot option or to all active key slots in the case --key-slot option is omitted.
To remove existing token, specify the token ID which should be removed with --token-id option.
WARNING: The action token remove removes any token type, not just keyring type from token slot specified by --token-id option.
Action import can store arbitrary valid token json in LUKS2 header. It may be passed via standard input or via file passed in --json-file option. If you specify --key-slot then successfully imported token is also assigned to the key slot.
Action export writes requested token json to a file passed with --json-file or to standard output.
<options> can be [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file].
....
--json-file Read token json from a file or write token to it. See token action for more information. --json-file=- reads json from standard input or writes it to standard output respectively.
....
--disable-external-tokens
Disable loading of plugins for external LUKS2 tokens.
--token-id
Specify what token to use in actions token, open or resize. If omitted, all available tokens will be checked before proceeding further with passphrase prompt.
--token-only
Do not proceed further with action (any of token, open or resize) if token activation failed. Without the option, action asks for passphrase to proceed further.
--token-type
Restrict tokens eligible for operation to specific token type (name). Mostly useful when no --token-id is specified.
3.6 Tokens Object
A token is an object that can describe how to get a passphrase to unlock a particular keyslot. It can also contain additional user-defined JSON metadata.
The mandatory fields for every token are:
• type [string] the token type (tokens with luks2- prefix are reserved for the implementation internal use).
• keyslots [array] the array of keyslot objects names that are assigned to the token.
The rest of the JSON content is the particular token implementation and can contain arbitrary JSON structured data (implementation should provide an interface to the JSON metadata directly). For example, the reference implementation of luks2-keyring token allows automatic activation of the device if the passphrase is preloaded into a keyring with the specified ID.
The luks2-keyring token type contains these fields:
• type [string] is set to the luks2-keyring.
• keyslots [array] is assigned to the specific keyslot(s).
• key description [string] contains the ID of the keyring entry with a pass-
phrase.
....
• The header contains a concept of tokens that are objects, assigned to
keyslots, which contain metadata describing where to get unlocking pass-
phrase. Tokens can be used for support of external key store mechanisms
....
3 LUKS2 JSON Metadata Format
The LUKS2 metadata allows defining objects that, according to the type field, defines a specific functionality. Objects that are not recognized byt the implementation are ignored, but metadata are still maintained inside the JSON metadata. Implementation must validate the JSON structure before updating the on-disk header.
The LUKS2 structure has 5 mandatory top-level objects (see Figure 3) as follows:
• config contains persistent header configuration attributes.
• keyslots are objects describing encrypted keys storage areas.
• digests are used to verify that keys decrypted from keyslots are correct.
• segments describe areas on disk that contain user encrypted data.
• tokens can optionally include additional metadata, bindings to other systems – how to get a passphrase for the keyslot.
....
3.1
LUKS2 JSON Example
The following example contains full JSON metadata from the reference im-
plementation for a LUKS2 device that is encrypted with the AES-XTS cipher,
contains two keyslots and one token. The token type is keyring (can be unlocked
by a passphrase in the keyring) and it is bound to the second keyslot.
...
" tokens " : {
"0" : {
" type " : " luks2 - keyring " ,
" keyslots " : [
"1"
],
" ke y_ d es cr ip t io n " : " MyKe yringKe yID "
}
}
....
10.12 What is a LUKS2 Token?
A LUKS2 token is an object that describes "how to get a passphrase or key" to unlock particular keyslot. A LUKS2 token is stored as json data in the LUKS2 header. The token can be related to all keyslots or a specific one. As the token is stored in JSON formay it is text by default but binary data can be encoded into it according to the JSON conventions.
Documentation on the last changes to LUKS2 tokens can be found in the release notes. As of version 2.4 of cryptsetup, there are significant features. The standard documentation for working with tokens is in the luks2 reference available as PDF on the project page.
see FAQ
* Fix compilation for libc implementations without dlvsym().
Some alternative libc implementations (like musl) do not provide versioned symbols dlvsym function. Code now fallbacks to dlsym operation for dynamic LUKS2 token load. It is up to maintainers to ensure that LUKS2 token plugins are compiled for the supported version.
....
* Print error message when assigning a token to an inactive keyslot.
Most of this content is TOKEN related. Not copying here unless it applies to something I am doing.