Macros
#define	CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING (1 << 0)

#define	CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC (1 << 1)

#define	CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (1 << 2)

Functions
int	crypt_format (struct crypt_device cd, const char type, const char cipher, const char cipher_mode, const char uuid, const char volume_key, size_t volume_key_size, void *params)

void	crypt_set_compatibility (struct crypt_device *cd, uint32_t flags)

uint32_t	crypt_get_compatibility (struct crypt_device *cd)

int	crypt_convert (struct crypt_device cd, const char type, void *params)

int	crypt_set_uuid (struct crypt_device cd, const char uuid)

int	crypt_set_label (struct crypt_device cd, const char label, const char *subsystem)

int	crypt_volume_key_keyring (struct crypt_device *cd, int enable)

int	crypt_load (struct crypt_device cd, const char requested_type, void *params)

int	crypt_repair (struct crypt_device cd, const char requested_type, void *params)

int	crypt_resize (struct crypt_device cd, const char name, uint64_t new_size)

int	crypt_suspend (struct crypt_device cd, const char name)

int	crypt_resume_by_passphrase (struct crypt_device cd, const char name, int keyslot, const char *passphrase, size_t passphrase_size)

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

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

int	crypt_resume_by_keyfile (struct crypt_device cd, const char name, int keyslot, const char *keyfile, size_t keyfile_size)

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

Detailed Description

Set of functions for formatting and manipulating with specific crypt_type

Macro Definition Documentation

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC

#define CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC (1 << 1)

dm-integrity device does not protect superblock with HMAC (old kernels)

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING

#define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING (1 << 0)

dm-integrity device uses less effective (legacy) padding (old kernels)

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC

#define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (1 << 2)

dm-integrity allow recalculating of volumes with HMAC keys (old kernels)

Function Documentation

◆ crypt_convert()

int crypt_convert	(	struct crypt_device *	cd,
		const char *	type,
		void *	params
	)

Convert to new type for already existing device.

Parameters

cd	crypt device handle
type	type of device (optional params struct must be of this type)
params	crypt type specific parameters (see crypt-type)

Returns: 0 on success or negative errno value otherwise.

Note: Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported. Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf type must be PBKDF2) and device cannot be formatted with any authenticated encryption mode.; Device must be offline for conversion. UUID change is not possible for active devices.

◆ crypt_format()

int crypt_format	(	struct crypt_device *	cd,
		const char *	type,
		const char *	cipher,
		const char *	cipher_mode,
		const char *	uuid,
		const char *	volume_key,
		size_t	volume_key_size,
		void *	params
	)

Create (format) new crypt device (and possible header on-disk) but do not activate it.

Precondition: cd contains initialized and not formatted device context (device type must not be set)

Parameters

cd	crypt device handle
type	type of device (optional params struct must be of this type)
cipher	(e.g. "aes")
cipher_mode	including IV specification (e.g. "xts-plain")
uuid	requested UUID or NULL if it should be generated
volume_key	pre-generated volume key or NULL if it should be generated (only for LUKS)
volume_key_size	size of volume key in bytes.
params	crypt type specific parameters (see crypt-type)

Returns: 0 on success or negative errno value otherwise.

Note: Note that crypt_format does not create LUKS keyslot (any version). To create keyslot call any crypt_keyslot_add_* function.; For VERITY crypt-type, only uuid parameter is used, other parameters are ignored and verity specific attributes are set through mandatory params option.

Examples: crypt_luks_usage.c.

◆ crypt_get_compatibility()

uint32_t crypt_get_compatibility ( struct crypt_device * cd )

Get compatibility flags.

Parameters

cd	crypt device handle

Returns: compatibility flags

◆ crypt_load()

int crypt_load	(	struct crypt_device *	cd,
		const char *	requested_type,
		void *	params
	)

Load crypt device parameters from on-disk header.

Parameters

cd	crypt device handle
requested_type	crypt-type or NULL for all known
params	crypt type specific parameters (see crypt-type)

Returns: 0 on success or negative errno value otherwise.

Postcondition: In case LUKS header is read successfully but payload device is too small error is returned and device type in context is set to NULL

Note: Note that in current version load works only for LUKS and VERITY device type.

Examples: crypt_luks_usage.c.

◆ crypt_repair()

int crypt_repair	(	struct crypt_device *	cd,
		const char *	requested_type,
		void *	params
	)

Try to repair crypt device LUKS on-disk header if invalid.

Parameters

cd	crypt device handle
requested_type	crypt-type or NULL for all known
params	crypt type specific parameters (see crypt-type)

Returns: 0 on success or negative errno value otherwise.

Note: For LUKS2 device crypt_repair bypass blkid checks and perform auto-recovery even though there're third party device signatures found by blkid probes. Currently the crypt_repair on LUKS2 works only if exactly one header checksum does not match or exactly one header is missing.

◆ crypt_resize()

int crypt_resize	(	struct crypt_device *	cd,
		const char *	name,
		uint64_t	new_size
	)

Resize crypt device.

Parameters

cd	- crypt device handle
name	- name of device to resize
new_size	- new device size in sectors or 0 to use all of the underlying device size

Returns: 0 on success or negative errno value otherwise.

Note: Most notably it returns -EPERM when device was activated with volume key in kernel keyring and current device handle (context) doesn't have verified key loaded in kernel. To load volume key for already active device use any of crypt_activate_by_passphrase, crypt_activate_by_keyfile, crypt_activate_by_keyfile_offset, crypt_activate_by_volume_key, crypt_activate_by_keyring or crypt_activate_by_token with flag CRYPT_ACTIVATE_KEYRING_KEY raised and name parameter set to NULL.

◆ crypt_resume_by_keyfile()

int crypt_resume_by_keyfile	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	keyfile,
		size_t	keyfile_size
	)

Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).

◆ crypt_resume_by_keyfile_device_offset()

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

Resume crypt device using key file.

Parameters

cd	crypt device handle
name	name of device to resume
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

Returns: unlocked key slot number or negative errno otherwise.

◆ crypt_resume_by_keyfile_offset()

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

Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).

◆ crypt_resume_by_passphrase()

int crypt_resume_by_passphrase	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		const char *	passphrase,
		size_t	passphrase_size
	)

Resume crypt device using passphrase.

Parameters

cd	crypt device handle
name	name of device to resume
keyslot	requested keyslot or CRYPT_ANY_SLOT
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase (binary data)

Returns: unlocked key slot number or negative errno otherwise.

Note: Only LUKS device type is supported

◆ crypt_resume_by_volume_key()

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

Resume crypt device using provided volume key.

Parameters

cd	crypt device handle
name	name of device to resume
volume_key	provided volume key
volume_key_size	size of volume_key

Returns: 0 on success or negative errno value otherwise.

◆ crypt_set_compatibility()

void crypt_set_compatibility	(	struct crypt_device *	cd,
		uint32_t	flags
	)

Set format compatibility flags.

Parameters

cd	crypt device handle
flags	CRYPT_COMPATIBILITY_* flags

◆ crypt_set_label()

int crypt_set_label	(	struct crypt_device *	cd,
		const char *	label,
		const char *	subsystem
	)

Set new labels (label and subsystem) for already existing device.

Parameters

cd	crypt device handle
label	requested label or NULL
subsystem	requested subsystem label or NULL

Returns: 0 on success or negative errno value otherwise.

Note: Currently, only LUKS2 device type is supported

◆ crypt_set_uuid()

int crypt_set_uuid	(	struct crypt_device *	cd,
		const char *	uuid
	)

Set new UUID for already existing device.

Parameters

cd	crypt device handle
uuid	requested UUID or NULL if it should be generated

Returns: 0 on success or negative errno value otherwise.

Note: Currently, only LUKS device type are supported

◆ crypt_suspend()

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

Suspend crypt device.

Parameters

cd	crypt device handle, can be NULL
name	name of device to suspend

Returns: 0 on success or negative errno value otherwise.

Note: Only LUKS device type is supported

◆ crypt_volume_key_keyring()

int crypt_volume_key_keyring	(	struct crypt_device *	cd,
		int	enable
	)

Enable or disable loading of volume keys via kernel keyring. When set to 'enabled' library loads key in kernel keyring first and pass the key description to dm-crypt instead of binary key copy. If set to 'disabled' library fallbacks to old method of loading volume key directly in dm-crypt target.

Parameters

cd	crypt device handle, can be NULL
enable	0 to disable loading of volume keys via kernel keyring (classical method) otherwise enable it (default)

Returns: 0 on success or negative errno value otherwise.

Note: Currently loading of volume keys via kernel keyring is supported (and enabled by default) only for LUKS2 devices.; The switch is global on the library level.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC

Function Documentation

◆ crypt_convert()

◆ crypt_format()

◆ crypt_get_compatibility()

◆ crypt_load()

◆ crypt_repair()

◆ crypt_resize()

◆ crypt_resume_by_keyfile()

◆ crypt_resume_by_keyfile_device_offset()

◆ crypt_resume_by_keyfile_offset()

◆ crypt_resume_by_passphrase()

◆ crypt_resume_by_volume_key()

◆ crypt_set_compatibility()

◆ crypt_set_label()

◆ crypt_set_uuid()

◆ crypt_suspend()

◆ crypt_volume_key_keyring()