Device activation

Macros
#define	CRYPT_DEACTIVATE_DEFERRED   (UINT32_C(1) << 0)
#define	CRYPT_DEACTIVATE_FORCE   (UINT32_C(1) << 1)
#define	CRYPT_DEACTIVATE_DEFERRED_CANCEL   (UINT32_C(1) << 2)

Functions
int	crypt_activate_by_keyslot_context (struct crypt_device *cd, const char *name, int keyslot, struct crypt_keyslot_context *kc, int additional_keyslot, struct crypt_keyslot_context *additional_kc, uint32_t flags)
int	crypt_activate_by_passphrase (struct crypt_device *cd, const char *name, int keyslot, const char *passphrase, size_t passphrase_size, uint32_t flags)
int	crypt_activate_by_keyfile_device_offset (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size, uint64_t keyfile_offset, uint32_t flags)
int	crypt_activate_by_keyfile_offset (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size, size_t keyfile_offset, uint32_t flags)
int	crypt_activate_by_keyfile (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size, uint32_t flags)
int	crypt_activate_by_volume_key (struct crypt_device *cd, const char *name, const char *volume_key, size_t volume_key_size, uint32_t flags)
int	crypt_activate_by_signed_key (struct crypt_device *cd, const char *name, const char *volume_key, size_t volume_key_size, const char *signature, size_t signature_size, uint32_t flags)
int	crypt_activate_by_keyring (struct crypt_device *cd, const char *name, const char *key_description, int keyslot, uint32_t flags)
int	crypt_deactivate_by_name (struct crypt_device *cd, const char *name, uint32_t flags)
int	crypt_deactivate (struct crypt_device *cd, const char *name)

Detailed Description

Macro Definition Documentation

CRYPT_DEACTIVATE_DEFERRED

#define CRYPT_DEACTIVATE_DEFERRED   (UINT32_C(1) << 0)

lazy deactivation - remove once last user releases it

CRYPT_DEACTIVATE_DEFERRED_CANCEL

#define CRYPT_DEACTIVATE_DEFERRED_CANCEL   (UINT32_C(1) << 2)

if set, remove lazy deactivation

CRYPT_DEACTIVATE_FORCE

#define CRYPT_DEACTIVATE_FORCE   (UINT32_C(1) << 1)

force deactivation - if the device is busy, it is replaced by error device

Function Documentation

crypt_activate_by_keyfile()

int crypt_activate_by_keyfile	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		uint32_t	flags
	)

Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).

crypt_activate_by_keyfile_device_offset()

int crypt_activate_by_keyfile_device_offset	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		uint64_t	keyfile_offset,
		uint32_t	flags
	)

Activate device or check using key file.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check keyfile
keyslot	requested keyslot to check or CRYPT_ANY_SLOT
keyfile	key file used to unlock volume key
keyfile_size	number of bytes to read from keyfile, 0 is unlimited
keyfile_offset	number of bytes to skip at start of keyfile
flags	activation flags

Returns

unlocked key slot number or negative errno otherwise.

crypt_activate_by_keyfile_offset()

int crypt_activate_by_keyfile_offset	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		size_t	keyfile_offset,
		uint32_t	flags
	)

Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).

crypt_activate_by_keyring()

int crypt_activate_by_keyring	(	struct crypt_device *	cd,
		const char *	name,
		const char *	key_description,
		int	keyslot,
		uint32_t	flags
	)

Activate device using passphrase stored in kernel keyring.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check passphrase in keyring
key_description	kernel keyring key description library should look for passphrase in
keyslot	requested keyslot to check or CRYPT_ANY_SLOT
flags	activation flags

Returns

unlocked keyslot number on success or negative errno value otherwise.

Note

Keyslot passphrase must be stored in 'user' key type and the key has to be reachable for process context on behalf of which this function is called.

crypt_activate_by_keyslot_context()

int crypt_activate_by_keyslot_context	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		struct crypt_keyslot_context *	kc,
		int	additional_keyslot,
		struct crypt_keyslot_context *	additional_kc,
		uint32_t	flags
	)

Activate device or check using keyslot context. In some cases (device under reencryption), more than one keyslot context is required (e.g. one for the old volume key and one for the new volume key). The order of the keyslot contexts does not matter. When less keyslot contexts are supplied than required to unlock the device an -ESRCH error code is returned and you should call the function again with an additional keyslot context specified.

NOTE: the API at the moment fully works for single keyslot context only, the additional keyslot context currently works only with CRYPT_KC_TYPE_VK_KEYRING or CRYPT_KC_TYPE_KEY contexts.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check passphrase
keyslot	requested keyslot to check or CRYPT_ANY_SLOT, keyslot is ignored for unlock methods not based on passphrase
kc	keyslot context providing volume key or passphrase.
additional_keyslot	requested additional keyslot to check or CRYPT_ANY_SLOT
additional_kc	keyslot context providing additional volume key or passphrase (e.g. old volume key for device under reencryption).
flags	activation flags

Returns

unlocked key slot number for passphrase-based unlock, zero for other unlock methods (e.g. volume key context) or negative errno on error.

crypt_activate_by_passphrase()

int crypt_activate_by_passphrase	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	passphrase,
		size_t	passphrase_size,
		uint32_t	flags
	)

Activate device or check passphrase.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check passphrase
keyslot	requested keyslot to check or CRYPT_ANY_SLOT
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase
flags	activation flags

Returns

unlocked key slot number or negative errno otherwise.

Examples

crypt_luks_usage.c.

crypt_activate_by_signed_key()

int crypt_activate_by_signed_key	(	struct crypt_device *	cd,
		const char *	name,
		const char *	volume_key,
		size_t	volume_key_size,
		const char *	signature,
		size_t	signature_size,
		uint32_t	flags
	)

Activate VERITY device using provided key and optional signature).

Parameters

cd	crypt device handle
name	name of device to create
volume_key	provided volume key
volume_key_size	size of volume_key
signature	buffer with signature for the key
signature_size	bsize of signature buffer
flags	activation flags

Returns

0 on success or negative errno value otherwise.

Note

For VERITY the volume key means root hash required for activation. Because kernel dm-verity is always read only, you have to provide CRYPT_ACTIVATE_READONLY flag always.

crypt_activate_by_volume_key()

int crypt_activate_by_volume_key	(	struct crypt_device *	cd,
		const char *	name,
		const char *	volume_key,
		size_t	volume_key_size,
		uint32_t	flags
	)

Activate device using provided volume key.

Parameters

cd	crypt device handle
name	name of device to create, if NULL only check volume key
volume_key	provided volume key (or NULL to use internal)
volume_key_size	size of volume_key
flags	activation flags

Returns

0 on success or negative errno value otherwise.

Note

If NULL is used for volume_key, device has to be initialized by previous operation (like crypt_format or crypt_init_by_name)

For VERITY the volume key means root hash required for activation. Because kernel dm-verity is always read only, you have to provide CRYPT_ACTIVATE_READONLY flag always.

For TCRYPT the volume key should be always NULL the key from decrypted header is used instead.

For BITLK the name cannot be NULL checking volume key is not supported for BITLK, the device will be activated even if the provided key is not correct.

crypt_deactivate()

int crypt_deactivate	(	struct crypt_device *	cd,
		const char *	name
	)

Deactivate crypt device. See crypt_deactivate_by_name with empty flags.

Examples

crypt_luks_usage.c.

crypt_deactivate_by_name()

int crypt_deactivate_by_name	(	struct crypt_device *	cd,
		const char *	name,
		uint32_t	flags
	)

Deactivate crypt device. This function tries to remove active device-mapper mapping from kernel. Also, sensitive data like the volume key are removed from memory

Parameters

cd	crypt device handle, can be NULL
name	name of device to deactivate
flags	deactivation flags

Returns

0 on success or negative errno value otherwise.