Data Structures
struct	crypt_token_params_luks2_keyring

struct	crypt_token_handler

Macros
#define	CRYPT_ANY_TOKEN -1

#define	CRYPT_TOKEN_ABI_VERSION1 "CRYPTSETUP_TOKEN_1.0"

#define	CRYPT_TOKEN_ABI_OPEN "cryptsetup_token_open"

#define	CRYPT_TOKEN_ABI_OPEN_PIN "cryptsetup_token_open_pin"

#define	CRYPT_TOKEN_ABI_BUFFER_FREE "cryptsetup_token_buffer_free"

#define	CRYPT_TOKEN_ABI_VALIDATE "cryptsetup_token_validate"

#define	CRYPT_TOKEN_ABI_DUMP "cryptsetup_token_dump"

#define	CRYPT_TOKEN_ABI_VERSION "cryptsetup_token_version"

Typedefs
typedef int(*	crypt_token_open_func) (struct crypt_device cd, int token, char buffer, size_t buffer_len, void *usrptr)

typedef int(*	crypt_token_open_pin_func) (struct crypt_device cd, int token, const char pin, size_t pin_size, char *buffer, size_t buffer_len, void *usrptr)

typedef void(*	crypt_token_buffer_free_func) (void *buffer, size_t buffer_len)

typedef int(*	crypt_token_validate_func) (struct crypt_device cd, const char json)

typedef void(*	crypt_token_dump_func) (struct crypt_device cd, const char json)

typedef const char (	crypt_token_version_func) (void)

Enumerations
enum	crypt_token_info { CRYPT_TOKEN_INVALID , CRYPT_TOKEN_INACTIVE , CRYPT_TOKEN_INTERNAL , CRYPT_TOKEN_INTERNAL_UNKNOWN , CRYPT_TOKEN_EXTERNAL , CRYPT_TOKEN_EXTERNAL_UNKNOWN }

Functions
int	crypt_token_max (const char *type)

int	crypt_token_json_get (struct crypt_device cd, int token, const char *json)

int	crypt_token_json_set (struct crypt_device cd, int token, const char json)

crypt_token_info	crypt_token_status (struct crypt_device cd, int token, const char *type)

int	crypt_token_luks2_keyring_set (struct crypt_device cd, int token, const struct crypt_token_params_luks2_keyring params)

int	crypt_token_luks2_keyring_get (struct crypt_device cd, int token, struct crypt_token_params_luks2_keyring params)

int	crypt_token_assign_keyslot (struct crypt_device *cd, int token, int keyslot)

int	crypt_token_unassign_keyslot (struct crypt_device *cd, int token, int keyslot)

int	crypt_token_is_assigned (struct crypt_device *cd, int token, int keyslot)

int	crypt_token_register (const crypt_token_handler *handler)

const char *	crypt_token_external_path (void)

int	crypt_token_set_external_path (const char *path)

void	crypt_token_external_disable (void)

int	crypt_activate_by_token (struct crypt_device cd, const char name, int token, void *usrptr, uint32_t flags)

int	crypt_activate_by_token_pin (struct crypt_device cd, const char name, const char type, int token, const char pin, size_t pin_size, void *usrptr, uint32_t flags)

Detailed Description

Utilities for handling tokens LUKS2 Token is a device or a method how to read password for particular keyslot automatically. It can be chunk of data stored on hardware token or just a metadata how to generate the password.

Macro Definition Documentation

◆ CRYPT_ANY_TOKEN

#define CRYPT_ANY_TOKEN -1

Iterate through all tokens

◆ CRYPT_TOKEN_ABI_BUFFER_FREE

#define CRYPT_TOKEN_ABI_BUFFER_FREE "cryptsetup_token_buffer_free"

deallocate callback - ABI exported symbol for external token

◆ CRYPT_TOKEN_ABI_DUMP

#define CRYPT_TOKEN_ABI_DUMP "cryptsetup_token_dump"

dump token metadata - ABI exported symbol for external token

◆ CRYPT_TOKEN_ABI_OPEN

#define CRYPT_TOKEN_ABI_OPEN "cryptsetup_token_open"

open by token - ABI exported symbol for external token (mandatory)

◆ CRYPT_TOKEN_ABI_OPEN_PIN

#define CRYPT_TOKEN_ABI_OPEN_PIN "cryptsetup_token_open_pin"

open by token with PIN - ABI exported symbol for external token

◆ CRYPT_TOKEN_ABI_VALIDATE

#define CRYPT_TOKEN_ABI_VALIDATE "cryptsetup_token_validate"

validate token metadata - ABI exported symbol for external token

◆ CRYPT_TOKEN_ABI_VERSION

#define CRYPT_TOKEN_ABI_VERSION "cryptsetup_token_version"

token version - ABI exported symbol for external token

◆ CRYPT_TOKEN_ABI_VERSION1

#define CRYPT_TOKEN_ABI_VERSION1 "CRYPTSETUP_TOKEN_1.0"

ABI version for external token in libcryptsetup-token-[name].so

Typedef Documentation

◆ crypt_token_buffer_free_func

typedef void(* crypt_token_buffer_free_func) (void *buffer, size_t buffer_len)

Token handler buffer free function prototype. This function is used by library to free the buffer with keyslot passphrase when it's no longer needed. If not defined the library overwrites buffer with zeroes and call free().

Parameters

buffer	the buffer with keyslot passphrase
buffer_len	the buffer length

◆ crypt_token_dump_func

typedef void(* crypt_token_dump_func) (struct crypt_device *cd, const char *json)

Token handler dump function prototype. This function is supposed to print token implementation specific details. It gets called during crypt_dump if token handler was registered before.

Parameters

cd	crypt device handle
json	buffer with token JSON

Note: dump implementations are advised to use crypt_log function to dump token details.

◆ crypt_token_open_func

typedef int(* crypt_token_open_func) (struct crypt_device *cd, int token, char **buffer, size_t *buffer_len, void *usrptr)

Token handler open function prototype. This function retrieves password from a token and return allocated buffer containing this password. This buffer has to be deallocated by calling free() function and content should be wiped before deallocation.

Parameters

cd	crypt device handle
token	token id
buffer	returned allocated buffer with password
buffer_len	length of the buffer
usrptr	user data in crypt_activate_by_token

Returns: 0 on success (token passed LUKS2 keyslot passphrase in buffer) or negative errno otherwise.

Note: Negative ENOANO errno means that token is PIN protected and caller should use crypt_activate_by_token_pin with PIN provided.; Negative EAGAIN errno means token handler requires additional hardware not present in the system.

◆ crypt_token_open_pin_func

typedef int(* crypt_token_open_pin_func) (struct crypt_device *cd, int token, const char *pin, size_t pin_size, char **buffer, size_t *buffer_len, void *usrptr)

Token handler open with passphrase/PIN function prototype. This function retrieves password from a token and return allocated buffer containing this password. This buffer has to be deallocated by calling free() function and content should be wiped before deallocation.

Parameters

cd	crypt device handle
token	token id
pin	passphrase (or PIN) to unlock token (may be binary data)
pin_size	size of pin
buffer	returned allocated buffer with password
buffer_len	length of the buffer
usrptr	user data in crypt_activate_by_token

Returns: 0 on success (token passed LUKS2 keyslot passphrase in buffer) or negative errno otherwise.

Note: Negative ENOANO errno means that token is PIN protected and PIN was missing or wrong.; Negative EAGAIN errno means token handler requires additional hardware not present in the system.

◆ crypt_token_validate_func

typedef int(* crypt_token_validate_func) (struct crypt_device *cd, const char *json)

Token handler validate function prototype. This function validates JSON representation of user defined token for additional data specific for its token type. If defined in the handler, it's called during crypt_activate_by_token. It may also be called during crypt_token_json_set when appropriate token handler was registered before with crypt_token_register.

Parameters

cd	crypt device handle
json	buffer with JSON

◆ crypt_token_version_func

typedef const char *(* crypt_token_version_func) (void)

Token handler version function prototype. This function is supposed to return pointer to version string information.

Note: The returned string is advised to contain only version. For example '1.0.0' or 'v1.2.3.4'.

Enumeration Type Documentation

◆ crypt_token_info

enum crypt_token_info

Token info

Enumerator
CRYPT_TOKEN_INVALID	token is invalid
CRYPT_TOKEN_INACTIVE	token is empty (free)
CRYPT_TOKEN_INTERNAL	active internal token with driver
CRYPT_TOKEN_INTERNAL_UNKNOWN	active internal token (reserved name) with missing token driver
CRYPT_TOKEN_EXTERNAL	active external (user defined) token with driver
CRYPT_TOKEN_EXTERNAL_UNKNOWN	active external (user defined) token with missing token driver

Function Documentation

◆ crypt_activate_by_token()

int crypt_activate_by_token	(	struct crypt_device *	cd,
		const char *	name,
		int	token,
		void *	usrptr,
		uint32_t	flags
	)

Activate device or check key using a token.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check token
token	requested token to check or CRYPT_ANY_TOKEN to check all
usrptr	provided identification in callback
flags	activation flags

Returns: unlocked key slot number or negative errno otherwise.

Note: EPERM errno means token provided passphrase successfully, but passphrase did not unlock any keyslot associated with the token.; ENOENT errno means no token (or subsequently assigned keyslot) was eligible to unlock device.; ENOANO errno means that token is PIN protected and you should call crypt_activate_by_token_pin with PIN; Negative EAGAIN errno means token handler requires additional hardware not present in the system.; with token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop to unlock device using any available token. It may happen that various token handlers return different error codes. At the end loop returns error codes in the following order (from the most significant to the least) any negative errno except those listed below, non negative token id (success), -ENOANO, -EAGAIN, -EPERM, -ENOENT.

◆ crypt_activate_by_token_pin()

int crypt_activate_by_token_pin	(	struct crypt_device *	cd,
		const char *	name,
		const char *	type,
		int	token,
		const char *	pin,
		size_t	pin_size,
		void *	usrptr,
		uint32_t	flags
	)

Activate device or check key using a token with PIN.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check token
type	restrict type of token, if NULL all types are allowed
token	requested token to check or CRYPT_ANY_TOKEN to check all
pin	passphrase (or PIN) to unlock token (may be binary data)
pin_size	size of pin
usrptr	provided identification in callback
flags	activation flags

Returns: unlocked key slot number or negative errno otherwise.

Note: EPERM errno means token provided passphrase successfully, but passphrase did not unlock any keyslot associated with the token.; ENOENT errno means no token (or subsequently assigned keyslot) was eligible to unlock device.; ENOANO errno means that token is PIN protected and was either missing (NULL) or wrong.; Negative EAGAIN errno means token handler requires additional hardware not present in the system.; with token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop to unlock device using any available token. It may happen that various token handlers return different error codes. At the end loop returns error codes in the following order (from the most significant to the least) any negative errno except those listed below, non negative token id (success), -ENOANO, -EAGAIN, -EPERM, -ENOENT.

◆ crypt_token_assign_keyslot()

int crypt_token_assign_keyslot	(	struct crypt_device *	cd,
		int	token,
		int	keyslot
	)

Assign a token to particular keyslot. (There can be more keyslots assigned to one token id.)

Parameters

cd	crypt device handle
token	token id
keyslot	keyslot to be assigned to token (CRYPT_ANY SLOT assigns all active keyslots to token)

Returns: allocated token id or negative errno otherwise.

◆ crypt_token_external_disable()

void crypt_token_external_disable ( void )

Disable external token handlers (plugins) support If disabled, it cannot be enabled again.

◆ crypt_token_external_path()

const char * crypt_token_external_path ( void )

Report configured path where library searches for external token handlers

Returns: absolute path when external tokens are enabled or NULL otherwise.

◆ crypt_token_is_assigned()

int crypt_token_is_assigned	(	struct crypt_device *	cd,
		int	token,
		int	keyslot
	)

Get info about token assignment to particular keyslot.

Parameters

cd	crypt device handle
token	token id
keyslot	keyslot

Returns: 0 on success (token exists and is assigned to the keyslot), -ENOENT if token is not assigned to a keyslot (token, keyslot or both may be inactive) or other negative errno otherwise.

◆ crypt_token_json_get()

int crypt_token_json_get	(	struct crypt_device *	cd,
		int	token,
		const char **	json
	)

Get content of a token definition in JSON format.

Parameters

cd	crypt device handle
token	token id
json	buffer with JSON

Returns: allocated token id or negative errno otherwise.

◆ crypt_token_json_set()

int crypt_token_json_set	(	struct crypt_device *	cd,
		int	token,
		const char *	json
	)

Store content of a token definition in JSON format.

Parameters

cd	crypt device handle
token	token id or CRYPT_ANY_TOKEN to allocate new one
json	buffer with JSON or NULL to remove token

Returns: allocated token id or negative errno otherwise.

Note: The buffer must be in proper JSON format and must contain at least string "type" with slot type and an array of string names "keyslots". Keyslots array contains assignments to particular slots and can be empty.

◆ crypt_token_luks2_keyring_get()

int crypt_token_luks2_keyring_get	(	struct crypt_device *	cd,
		int	token,
		struct crypt_token_params_luks2_keyring *	params
	)

Get LUKS2 keyring token params

Parameters

cd	crypt device handle
token	existing luks2 keyring token id
params	returned luks2 keyring token params

Returns: allocated token id or negative errno otherwise.

Note: do not call free() on params members. Members are valid only until next libcryptsetup function is called.

◆ crypt_token_luks2_keyring_set()

int crypt_token_luks2_keyring_set	(	struct crypt_device *	cd,
		int	token,
		const struct crypt_token_params_luks2_keyring *	params
	)

Create a new luks2 keyring token.

Parameters

cd	crypt device handle
token	token id or CRYPT_ANY_TOKEN to allocate new one
params	luks2 keyring token params

Returns: allocated token id or negative errno otherwise.

◆ crypt_token_max()

int crypt_token_max ( const char * type )

Get number of tokens supported for device type.

Parameters

type	crypt device type

Returns: token count or negative errno otherwise if device doesn't not support tokens.

Note: Real number of supported tokens for a particular device depends on usable metadata area size.

◆ crypt_token_register()

int crypt_token_register ( const crypt_token_handler * handler )

Register token handler

Parameters

handler token handler to register

Returns: 0 on success or negative errno value otherwise.

◆ crypt_token_set_external_path()

int crypt_token_set_external_path ( const char * path )

Override configured external token handlers path for the library.

Parameters

path	Absolute path (starts with '/') to new external token handlers directory or NULL.

Note: if path is NULL the external token path is reset to default path.

Returns: 0 on success or negative errno value otherwise.

◆ crypt_token_status()

crypt_token_info crypt_token_status	(	struct crypt_device *	cd,
		int	token,
		const char **	type
	)

Get info for specific token.

Parameters

cd	crypt device handle
token	existing token id
type	pointer for returned type string

Returns: token status info. For any returned status (besides CRYPT_TOKEN_INVALID and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will contain address of type string.

Note: if required, create a copy of string referenced in *type before calling next libcryptsetup API function. The reference may become invalid.

◆ crypt_token_unassign_keyslot()

int crypt_token_unassign_keyslot	(	struct crypt_device *	cd,
		int	token,
		int	keyslot
	)

Unassign a token from particular keyslot. (There can be more keyslots assigned to one token id.)

Parameters

cd	crypt device handle
token	token id
keyslot	keyslot to be unassigned from token (CRYPT_ANY SLOT unassigns all active keyslots from token)

Returns: allocated token id or negative errno otherwise.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CRYPT_ANY_TOKEN

◆ CRYPT_TOKEN_ABI_BUFFER_FREE

◆ CRYPT_TOKEN_ABI_DUMP

◆ CRYPT_TOKEN_ABI_OPEN

◆ CRYPT_TOKEN_ABI_OPEN_PIN

◆ CRYPT_TOKEN_ABI_VALIDATE

◆ CRYPT_TOKEN_ABI_VERSION

◆ CRYPT_TOKEN_ABI_VERSION1

Typedef Documentation

◆ crypt_token_buffer_free_func

◆ crypt_token_dump_func

◆ crypt_token_open_func

◆ crypt_token_open_pin_func

◆ crypt_token_validate_func

◆ crypt_token_version_func

Enumeration Type Documentation

◆ crypt_token_info

Function Documentation

◆ crypt_activate_by_token()

◆ crypt_activate_by_token_pin()

◆ crypt_token_assign_keyslot()

◆ crypt_token_external_disable()

◆ crypt_token_external_path()

◆ crypt_token_is_assigned()

◆ crypt_token_json_get()

◆ crypt_token_json_set()

◆ crypt_token_luks2_keyring_get()

◆ crypt_token_luks2_keyring_set()

◆ crypt_token_max()

◆ crypt_token_register()

◆ crypt_token_set_external_path()

◆ crypt_token_status()

◆ crypt_token_unassign_keyslot()