Volume Key manipulation

Functions
int	crypt_volume_key_get (struct crypt_device *cd, int keyslot, char *volume_key, size_t *volume_key_size, const char *passphrase, size_t passphrase_size)
int	crypt_volume_key_get_by_keyslot_context (struct crypt_device *cd, int keyslot, char *volume_key, size_t *volume_key_size, struct crypt_keyslot_context *kc)
int	crypt_volume_key_verify (struct crypt_device *cd, const char *volume_key, size_t volume_key_size)

Detailed Description

Function Documentation

crypt_volume_key_get()

int crypt_volume_key_get	(	struct crypt_device *	cd,
		int	keyslot,
		char *	volume_key,
		size_t *	volume_key_size,
		const char *	passphrase,
		size_t	passphrase_size
	)

Get volume key from crypt device.

Parameters

cd	crypt device handle
keyslot	use this keyslot or CRYPT_ANY_SLOT
volume_key	buffer for volume key
volume_key_size	on input, size of buffer volume_key, on output size of volume_key
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase

Returns

unlocked key slot number or negative errno otherwise.

Note

For TCRYPT cipher chain is the volume key concatenated for all ciphers in chain.

For VERITY the volume key means root hash used for activation.

For LUKS devices, if passphrase is NULL and volume key is cached in device context it returns the volume key generated in preceding crypt_format call.

crypt_volume_key_get_by_keyslot_context()

int crypt_volume_key_get_by_keyslot_context	(	struct crypt_device *	cd,
		int	keyslot,
		char *	volume_key,
		size_t *	volume_key_size,
		struct crypt_keyslot_context *	kc
	)

Get volume key from crypt device by keyslot context.

Parameters

cd	crypt device handle
keyslot	use this keyslot or CRYPT_ANY_SLOT
volume_key	buffer for volume key
volume_key_size	on input, size of buffer volume_key, on output size of volume_key
kc	keyslot context used to unlock volume key

Returns

unlocked key slot number or negative errno otherwise.

Note

See crypt-keyslot-context-types for info on keyslot context initialization.

For TCRYPT cipher chain is the volume key concatenated for all ciphers in chain (kc may be NULL).

For VERITY the volume key means root hash used for activation (kc may be NULL).

For LUKS devices, if kc is NULL and volume key is cached in device context it returns the volume key generated in preceding crypt_format call.

CRYPT_KC_TYPE_TOKEN keyslot context is usable only with LUKS2 devices.

CRYPT_KC_TYPE_KEY keyslot context can not be used.

To get LUKS2 unbound key, keyslot parameter must not be CRYPT_ANY_SLOT.

EPERM errno means provided keyslot context could not unlock any (or selected) keyslot.

ENOENT errno means no LUKS keyslot is available to retrieve volume key from and there's no cached volume key in device handle.

crypt_volume_key_verify()

int crypt_volume_key_verify	(	struct crypt_device *	cd,
		const char *	volume_key,
		size_t	volume_key_size
	)

Verify that provided volume key is valid for crypt device.

Parameters

cd	crypt device handle
volume_key	provided volume key
volume_key_size	size of volume_key

Returns

0 on success or negative errno value otherwise.

Note

Negative EPERM return value means that passed volume_key did not pass digest verification routine (not a valid volume key).