Modules
	Crypt keyslot context

Macros
#define	CRYPT_ANY_SLOT -1

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

#define	CRYPT_VOLUME_KEY_SET (UINT32_C(1) << 1)

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

Enumerations
enum	crypt_keyslot_info { CRYPT_SLOT_INVALID , CRYPT_SLOT_INACTIVE , CRYPT_SLOT_ACTIVE , CRYPT_SLOT_ACTIVE_LAST , CRYPT_SLOT_UNBOUND }

enum	crypt_keyslot_priority { CRYPT_SLOT_PRIORITY_INVALID =-1 , CRYPT_SLOT_PRIORITY_IGNORE = 0 , CRYPT_SLOT_PRIORITY_NORMAL = 1 , CRYPT_SLOT_PRIORITY_PREFER = 2 }

Functions
int	crypt_keyslot_add_by_passphrase (struct crypt_device cd, int keyslot, const char passphrase, size_t passphrase_size, const char *new_passphrase, size_t new_passphrase_size)

int	crypt_keyslot_change_by_passphrase (struct crypt_device cd, int keyslot_old, int keyslot_new, const char passphrase, size_t passphrase_size, const char *new_passphrase, size_t new_passphrase_size)

int	crypt_keyslot_add_by_keyfile_device_offset (struct crypt_device cd, int keyslot, const char keyfile, size_t keyfile_size, uint64_t keyfile_offset, const char *new_keyfile, size_t new_keyfile_size, uint64_t new_keyfile_offset)

int	crypt_keyslot_add_by_keyfile_offset (struct crypt_device cd, int keyslot, const char keyfile, size_t keyfile_size, size_t keyfile_offset, const char *new_keyfile, size_t new_keyfile_size, size_t new_keyfile_offset)

int	crypt_keyslot_add_by_keyfile (struct crypt_device cd, int keyslot, const char keyfile, size_t keyfile_size, const char *new_keyfile, size_t new_keyfile_size)

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

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

int	crypt_keyslot_add_by_keyslot_context (struct crypt_device cd, int keyslot_existing, struct crypt_keyslot_context kc, int keyslot_new, struct crypt_keyslot_context *new_kc, uint32_t flags)

int	crypt_keyslot_destroy (struct crypt_device *cd, int keyslot)

crypt_keyslot_info	crypt_keyslot_status (struct crypt_device *cd, int keyslot)

crypt_keyslot_priority	crypt_keyslot_get_priority (struct crypt_device *cd, int keyslot)

int	crypt_keyslot_set_priority (struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority)

int	crypt_keyslot_max (const char *type)

int	crypt_keyslot_area (struct crypt_device cd, int keyslot, uint64_t offset, uint64_t *length)

int	crypt_keyslot_get_key_size (struct crypt_device *cd, int keyslot)

const char *	crypt_keyslot_get_encryption (struct crypt_device cd, int keyslot, size_t key_size)

int	crypt_keyslot_get_pbkdf (struct crypt_device cd, int keyslot, struct crypt_pbkdf_type pbkdf)

int	crypt_keyslot_set_encryption (struct crypt_device cd, const char cipher, size_t key_size)

const char *	crypt_get_dir (void)

Detailed Description

Macro Definition Documentation

◆ CRYPT_ANY_SLOT

#define CRYPT_ANY_SLOT -1

iterate through all keyslots and find first one that fits

Examples: crypt_luks_usage.c.

◆ CRYPT_VOLUME_KEY_DIGEST_REUSE

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

Assign key to first matching digest before creating new digest

◆ CRYPT_VOLUME_KEY_NO_SEGMENT

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

create keyslot with volume key not associated with current dm-crypt segment

◆ CRYPT_VOLUME_KEY_SET

#define CRYPT_VOLUME_KEY_SET (UINT32_C(1) << 1)

create keyslot with new volume key and assign it to current dm-crypt segment

Enumeration Type Documentation

◆ crypt_keyslot_info

enum crypt_keyslot_info

Crypt keyslot info

Enumerator
CRYPT_SLOT_INVALID	invalid keyslot
CRYPT_SLOT_INACTIVE	keyslot is inactive (free)
CRYPT_SLOT_ACTIVE	keyslot is active (used)
CRYPT_SLOT_ACTIVE_LAST	keylost is active (used) and last used at the same time
CRYPT_SLOT_UNBOUND	keyslot is active and not bound to any crypt segment (LUKS2 only)

◆ crypt_keyslot_priority

enum crypt_keyslot_priority

Crypt keyslot priority

Enumerator
CRYPT_SLOT_PRIORITY_INVALID	no such slot
CRYPT_SLOT_PRIORITY_IGNORE	CRYPT_ANY_SLOT will ignore it for open
CRYPT_SLOT_PRIORITY_NORMAL	default priority, tried after preferred
CRYPT_SLOT_PRIORITY_PREFER	will try to open first

Function Documentation

◆ crypt_get_dir()

const char * crypt_get_dir ( void )

Get directory where mapped crypt devices are created

Returns: the directory path

Examples: crypt_luks_usage.c.

◆ crypt_keyslot_add_by_key()

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

Add key slot using provided key.

Precondition: cd contains initialized and formatted LUKS2 device context

Parameters

cd	crypt device handle
keyslot	requested keyslot or CRYPT_ANY_SLOT
volume_key	provided volume key or NULL (see note below)
volume_key_size	size of volume_key
passphrase	passphrase for new keyslot
passphrase_size	size of passphrase
flags	key flags to set

Returns: allocated key slot number or negative errno otherwise.

Note

in case volume_key is NULL following first matching rule will apply:

if cd is device handle used in crypt_format() by current process, the volume key generated (or passed) in crypt_format() will be stored in keyslot.
if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be generated and stored in keyslot. The keyslot will become unbound (unusable to dm-crypt device activation).
fails with -EINVAL otherwise

Warning: CRYPT_VOLUME_KEY_SET flag force updates volume key. It is not reencryption! By doing so you will most probably destroy your ciphertext data device. It's supposed to be used only in wrapped keys scheme for key refresh process where real (inner) volume key stays untouched. It may be involved on active keyslot which makes the (previously unbound) keyslot new regular keyslot.

◆ crypt_keyslot_add_by_keyfile()

int crypt_keyslot_add_by_keyfile	(	struct crypt_device *	cd,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		const char *	new_keyfile,
		size_t	new_keyfile_size
	)

Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).

◆ crypt_keyslot_add_by_keyfile_device_offset()

int crypt_keyslot_add_by_keyfile_device_offset	(	struct crypt_device *	cd,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		uint64_t	keyfile_offset,
		const char *	new_keyfile,
		size_t	new_keyfile_size,
		uint64_t	new_keyfile_offset
	)

Add key slot using provided key file path.

Precondition: cd contains initialized and formatted LUKS device context

Parameters

cd	crypt device handle
keyslot	requested keyslot 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
new_keyfile	keyfile for new keyslot
new_keyfile_size	number of bytes to read from new_keyfile, 0 is unlimited
new_keyfile_offset	number of bytes to skip at start of new_keyfile

Returns: allocated key slot number or negative errno otherwise.

◆ crypt_keyslot_add_by_keyfile_offset()

int crypt_keyslot_add_by_keyfile_offset	(	struct crypt_device *	cd,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size,
		size_t	keyfile_offset,
		const char *	new_keyfile,
		size_t	new_keyfile_size,
		size_t	new_keyfile_offset
	)

Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).

◆ crypt_keyslot_add_by_keyslot_context()

int crypt_keyslot_add_by_keyslot_context	(	struct crypt_device *	cd,
		int	keyslot_existing,
		struct crypt_keyslot_context *	kc,
		int	keyslot_new,
		struct crypt_keyslot_context *	new_kc,
		uint32_t	flags
	)

Add key slot by volume key provided by keyslot context (kc). New keyslot will be protected by passphrase provided by new keyslot context (new_kc). See crypt-keyslot-context for context initialization routines.

Precondition: cd contains initialized and formatted LUKS device context.

Parameters

cd	crypt device handle
keyslot_existing	existing keyslot or CRYPT_ANY_SLOT to get volume key from.
kc	keyslot context providing volume key.
keyslot_new	new keyslot or CRYPT_ANY_SLOT (first free number is used).
new_kc	keyslot context providing passphrase for new keyslot.
flags	key flags to set

Returns: allocated key slot number or negative errno otherwise.

Note

new_kc can not be CRYPT_KC_TYPE_KEY type keyslot context.

For kc parameter with type CRYPT_KC_TYPE_KEY the keyslot_existing parameter is ignored.

in case there is no active LUKS keyslot to get existing volume key from, one of following must apply:

cd must be device handle used in crypt_format() by current process (it holds reference to generated volume key)
kc must be of CRYPT_KC_TYPE_KEY type with valid volume key.

With CRYPT_VOLUME_KEY_NO_SEGMENT flag raised and kc of type CRYPT_KC_TYPE_KEY with volume_key set to NULL the new volume_key will be generated and stored in new keyslot. The keyslot will become unbound (unusable to dm-crypt device activation).

Warning: CRYPT_VOLUME_KEY_SET flag force updates volume key. It is not reencryption! By doing so you will most probably destroy your ciphertext data device. It's supposed to be used only in wrapped keys scheme for key refresh process where real (inner) volume key stays untouched. It may be involved on active keyslot which makes the (previously unbound) keyslot new regular keyslot.

◆ crypt_keyslot_add_by_passphrase()

int crypt_keyslot_add_by_passphrase	(	struct crypt_device *	cd,
		int	keyslot,
		const char *	passphrase,
		size_t	passphrase_size,
		const char *	new_passphrase,
		size_t	new_passphrase_size
	)

Add key slot using provided passphrase.

Precondition: cd contains initialized and formatted LUKS device context

Parameters

cd	crypt device handle
keyslot	requested keyslot or CRYPT_ANY_SLOT
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase (binary data)
new_passphrase	passphrase for new keyslot
new_passphrase_size	size of new_passphrase (binary data)

Returns: allocated key slot number or negative errno otherwise.

Examples: crypt_luks_usage.c.

◆ crypt_keyslot_add_by_volume_key()

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

Add key slot using provided volume key.

Precondition: cd contains initialized and formatted LUKS device context

Parameters

cd	crypt device handle
keyslot	requested keyslot or CRYPT_ANY_SLOT
volume_key	provided volume key or NULL if used after crypt_format
volume_key_size	size of volume_key
passphrase	passphrase for new keyslot
passphrase_size	size of passphrase

Returns: allocated key slot number or negative errno otherwise.

Examples: crypt_luks_usage.c.

◆ crypt_keyslot_area()

int crypt_keyslot_area	(	struct crypt_device *	cd,
		int	keyslot,
		uint64_t *	offset,
		uint64_t *	length
	)

Get keyslot area pointers (relative to metadata device).

Parameters

cd	crypt device handle
keyslot	keyslot number
offset	offset on metadata device (in bytes)
length	length of keyslot area (in bytes)

Returns: 0 on success or negative errno value otherwise.

◆ crypt_keyslot_change_by_passphrase()

int crypt_keyslot_change_by_passphrase	(	struct crypt_device *	cd,
		int	keyslot_old,
		int	keyslot_new,
		const char *	passphrase,
		size_t	passphrase_size,
		const char *	new_passphrase,
		size_t	new_passphrase_size
	)

Change defined key slot using provided passphrase.

Precondition: cd contains initialized and formatted LUKS device context

Parameters

cd	crypt device handle
keyslot_old	old keyslot or CRYPT_ANY_SLOT
keyslot_new	new keyslot (can be the same as old)
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase (binary data)
new_passphrase	passphrase for new keyslot
new_passphrase_size	size of new_passphrase (binary data)

Returns: allocated key slot number or negative errno otherwise.

◆ crypt_keyslot_destroy()

int crypt_keyslot_destroy	(	struct crypt_device *	cd,
		int	keyslot
	)

Destroy (and disable) key slot.

Precondition: cd contains initialized and formatted LUKS device context

Parameters

cd	crypt device handle
keyslot	requested key slot to destroy

Returns: 0 on success or negative errno value otherwise.

Note: Note that there is no passphrase verification used.

◆ crypt_keyslot_get_encryption()

const char * crypt_keyslot_get_encryption	(	struct crypt_device *	cd,
		int	keyslot,
		size_t *	key_size
	)

Get cipher and key size for keyslot encryption. Use for LUKS2 keyslot to set different encryption type than for data encryption. Parameters will be used for next keyslot operations.

Parameters

cd	crypt device handle
keyslot	keyslot number of CRYPT_ANY_SLOT for default
key_size	encryption key size (in bytes)

Returns: cipher specification on success or NULL.

Note: This is the encryption of keyslot itself, not the data encryption algorithm!

◆ crypt_keyslot_get_key_size()

int crypt_keyslot_get_key_size	(	struct crypt_device *	cd,
		int	keyslot
	)

Get size (in bytes) of stored key in particular keyslot. Use for LUKS2 unbound keyslots, for other keyslots it is the same as crypt_get_volume_key_size

Parameters

cd	crypt device handle
keyslot	keyslot number

Returns: volume key size or negative errno value otherwise.

◆ crypt_keyslot_get_pbkdf()

int crypt_keyslot_get_pbkdf	(	struct crypt_device *	cd,
		int	keyslot,
		struct crypt_pbkdf_type *	pbkdf
	)

Get PBKDF parameters for keyslot.

Parameters

cd	crypt device handle
keyslot	keyslot number
pbkdf	struct with returned PBKDF parameters

Returns: 0 on success or negative errno value otherwise.

◆ crypt_keyslot_get_priority()

crypt_keyslot_priority crypt_keyslot_get_priority	(	struct crypt_device *	cd,
		int	keyslot
	)

Get keyslot priority (LUKS2)

Parameters

cd	crypt device handle
keyslot	keyslot number

Returns: value defined by crypt_keyslot_priority

◆ crypt_keyslot_max()

int crypt_keyslot_max ( const char * type )

Get number of keyslots supported for device type.

Parameters

type	crypt device type

Returns: slot count or negative errno otherwise if device doesn't not support keyslots.

◆ crypt_keyslot_set_encryption()

int crypt_keyslot_set_encryption	(	struct crypt_device *	cd,
		const char *	cipher,
		size_t	key_size
	)

Set encryption for keyslot. Use for LUKS2 keyslot to set different encryption type than for data encryption. Parameters will be used for next keyslot operations that create or change a keyslot.

Parameters

cd	crypt device handle
cipher	(e.g. "aes-xts-plain64")
key_size	encryption key size (in bytes)

Returns: 0 on success or negative errno value otherwise.

Note: To reset to default keyslot encryption (the same as for data) set cipher to NULL and key size to 0.

◆ crypt_keyslot_set_priority()

int crypt_keyslot_set_priority	(	struct crypt_device *	cd,
		int	keyslot,
		crypt_keyslot_priority	priority
	)

Set keyslot priority (LUKS2)

Parameters

cd	crypt device handle
keyslot	keyslot number
priority	priority defined in crypt_keyslot_priority

Returns: 0 on success or negative errno value otherwise.

◆ crypt_keyslot_status()

crypt_keyslot_info crypt_keyslot_status	(	struct crypt_device *	cd,
		int	keyslot
	)

Get information about particular key slot.

Parameters

cd	crypt device handle
keyslot	requested keyslot to check or CRYPT_ANY_SLOT

Returns: value defined by crypt_keyslot_info

Modules

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CRYPT_ANY_SLOT

◆ CRYPT_VOLUME_KEY_DIGEST_REUSE

◆ CRYPT_VOLUME_KEY_NO_SEGMENT

◆ CRYPT_VOLUME_KEY_SET

Enumeration Type Documentation

◆ crypt_keyslot_info

◆ crypt_keyslot_priority

Function Documentation

◆ crypt_get_dir()

◆ crypt_keyslot_add_by_key()

◆ crypt_keyslot_add_by_keyfile()

◆ crypt_keyslot_add_by_keyfile_device_offset()

◆ crypt_keyslot_add_by_keyfile_offset()

◆ crypt_keyslot_add_by_keyslot_context()

◆ crypt_keyslot_add_by_passphrase()

◆ crypt_keyslot_add_by_volume_key()

◆ crypt_keyslot_area()

◆ crypt_keyslot_change_by_passphrase()

◆ crypt_keyslot_destroy()

◆ crypt_keyslot_get_encryption()

◆ crypt_keyslot_get_key_size()

◆ crypt_keyslot_get_pbkdf()

◆ crypt_keyslot_get_priority()

◆ crypt_keyslot_max()

◆ crypt_keyslot_set_encryption()

◆ crypt_keyslot_set_priority()

◆ crypt_keyslot_status()