Macros
#define	CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING (UINT32_C(1) << 0)

#define	CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC (UINT32_C(1) << 1)

#define	CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (UINT32_C(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)

int	crypt_format_luks2_opal (struct crypt_device cd, const char cipher, const char cipher_mode, const char uuid, const char volume_keys, size_t volume_keys_size, struct crypt_params_luks2 params, struct crypt_params_hw_opal *opal_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)

const char *	crypt_get_label (struct crypt_device *cd)

const char *	crypt_get_subsystem (struct crypt_device *cd)

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)

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

int	crypt_resume_by_keyslot_context (struct crypt_device cd, const char name, int keyslot, struct crypt_keyslot_context *kc)

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 (UINT32_C(1) << 1)

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

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING

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

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

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC

#define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (UINT32_C(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_format_luks2_opal()

int crypt_format_luks2_opal	(	struct crypt_device *	cd,
		const char *	cipher,
		const char *	cipher_mode,
		const char *	uuid,
		const char *	volume_keys,
		size_t	volume_keys_size,
		struct crypt_params_luks2 *	params,
		struct crypt_params_hw_opal *	opal_params
	)

Create (format) new LUKS2 crypt device over HW OPAL device 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
cipher	for SW encryption (e.g. "aes") or NULL for HW encryption only
cipher_mode	including IV specification (e.g. "xts-plain") or NULL for HW encryption only
uuid	requested UUID or NULL if it should be generated
volume_keys	pre-generated volume keys or NULL if it should be generated (only for LUKS2 SW encryption)
volume_keys_size	size of volume keys in bytes (only for SW encryption).
params	LUKS2 crypt type specific parameters (see crypt-type)
opal_params	OPAL specific parameters

Returns: 0 on success or negative errno value otherwise.

Note: Note that crypt_format_luks2_opal does not create LUKS keyslot. To create keyslot call any crypt_keyslot_add_* function.

◆ crypt_get_compatibility()

uint32_t crypt_get_compatibility ( struct crypt_device * cd )

Get compatibility flags.

Parameters

cd	crypt device handle

Returns: compatibility flags

◆ crypt_get_label()

const char * crypt_get_label ( struct crypt_device * cd )

Get the label of an existing device.

Parameters

cd	crypt device handle

Returns: label, or NULL otherwise

◆ crypt_get_subsystem()

const char * crypt_get_subsystem ( struct crypt_device * cd )

Get the subsystem of an existing device.

Parameters

cd	crypt device handle

Returns: subsystem, or NULL otherwise

◆ 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 load works only for device types with on-disk metadata.; Function does not print visible error message if metadata is not present.

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_keyslot_context()

int crypt_resume_by_keyslot_context	(	struct crypt_device *	cd,
		const char *	name,
		int	keyslot,
		struct crypt_keyslot_context *	kc
	)

Resume crypt device using keyslot context.

Parameters

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

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_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_token_pin()

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

Resume crypt device using LUKS2 token.

Parameters

cd	LUKS2 crypt device handle
name	name of device to resume
type	restrict type of token, if NULL all types are allowed
pin	passphrase (or PIN) to unlock token (may be binary data)
pin_size	size of pin
usrptr	provided identification in callback

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 resume LUKS2 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 to unlock keyslot.; with

Parameters

token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop to resume 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_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_format_luks2_opal()

◆ crypt_get_compatibility()

◆ crypt_get_label()

◆ crypt_get_subsystem()

◆ crypt_load()

◆ crypt_repair()

◆ crypt_resize()

◆ crypt_resume_by_keyfile()

◆ crypt_resume_by_keyfile_device_offset()

◆ crypt_resume_by_keyfile_offset()

◆ crypt_resume_by_keyslot_context()

◆ crypt_resume_by_passphrase()

◆ crypt_resume_by_token_pin()

◆ crypt_resume_by_volume_key()

◆ crypt_set_compatibility()

◆ crypt_set_label()

◆ crypt_set_uuid()

◆ crypt_suspend()

◆ crypt_volume_key_keyring()