Cryptsetup device context initialization

Functions
int	crypt_init (struct crypt_device **cd, const char *device)
int	crypt_init_data_device (struct crypt_device **cd, const char *device, const char *data_device)
int	crypt_init_by_name_and_header (struct crypt_device **cd, const char *name, const char *header_device)
int	crypt_init_by_name (struct crypt_device **cd, const char *name)
void	crypt_free (struct crypt_device *cd)
void	crypt_set_confirm_callback (struct crypt_device *cd, int(*confirm)(const char *msg, void *usrptr), void *usrptr)
int	crypt_set_data_device (struct crypt_device *cd, const char *device)
int	crypt_set_data_offset (struct crypt_device *cd, uint64_t data_offset)

Detailed Description

Set of functions for creating and destroying crypt_device context

Function Documentation

crypt_free()

void crypt_free

(

struct crypt_device *

cd

)

Release crypt device context and used memory.

Parameters

cd	crypt device handle

Examples

crypt_log_usage.c, and crypt_luks_usage.c.

crypt_init()

int crypt_init	(	struct crypt_device **	cd,
		const char *	device
	)

Initialize crypt device handle and check if the provided device exists.

Parameters

cd	Returns pointer to crypt device handle
device	Path to the backing device. If device is not a block device but a path to some file, the function will try to create a loopdevice and attach the file to the loopdevice with AUTOCLEAR flag set. If device is NULL function it will initialize dm backend only.

Returns

0 on success or negative errno value otherwise.

Note

Note that logging is not initialized here, possible messages use default log function.

Examples

crypt_log_usage.c, and crypt_luks_usage.c.

crypt_init_by_name()

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

This is equivalent to call crypt_init_by_name_and_header(cd, name, NULL)

See also

crypt_init_by_name_and_header

Examples

crypt_luks_usage.c.

crypt_init_by_name_and_header()

int crypt_init_by_name_and_header	(	struct crypt_device **	cd,
		const char *	name,
		const char *	header_device
	)

Initialize crypt device handle from provided active device name, and, optionally, from separate metadata (header) device and check if provided device exists.

Returns

0 on success or negative errno value otherwise.

Parameters

cd	returns crypt device handle for active device
name	name of active crypt device
header_device	optional device containing on-disk header (NULL if it the same as underlying device on there is no on-disk header)

Postcondition

In case device points to active LUKS device but header load fails, context device type is set to NULL and 0 is returned as if it were successful. Context with NULL device type can only be deactivated by crypt_deactivate

Note

crypt_init_by_name is equivalent to calling crypt_init_by_name_and_header(cd, name, NULL);

crypt_init_data_device()

int crypt_init_data_device	(	struct crypt_device **	cd,
		const char *	device,
		const char *	data_device
	)

Initialize crypt device handle with optional data device and check if devices exist.

Parameters

cd	Returns pointer to crypt device handle
device	Path to the backing device or detached header.
data_device	Path to the data device or NULL.

Returns

0 on success or negative errno value otherwise.

Note

Note that logging is not initialized here, possible messages use default log function.

crypt_set_confirm_callback()

void crypt_set_confirm_callback	(	struct crypt_device *	cd,
		int(*)(const char *msg, void *usrptr)	confirm,
		void *	usrptr
	)

Set confirmation callback (yes/no).

If code need confirmation (like resetting uuid or restoring LUKS header from file) this function is called. If not defined, everything is confirmed.

Callback function confirm should return 0 if operation is declined, other values mean accepted.

Parameters

cd	crypt device handle
confirm	user defined confirm callback reference; use msg for message for user to confirm and usrptr for identification in callback
usrptr	provided identification in callback

Note

Current version of cryptsetup API requires confirmation for UUID change and LUKS header restore only.

crypt_set_data_device()

int crypt_set_data_device	(	struct crypt_device *	cd,
		const char *	device
	)

Set data device For LUKS it is encrypted data device when LUKS header is separated. For VERITY it is data device when hash device is separated.

Parameters

cd	crypt device handle
device	path to device

Returns

0 on success or negative errno value otherwise.

crypt_set_data_offset()

int crypt_set_data_offset	(	struct crypt_device *	cd,
		uint64_t	data_offset
	)

Set data device offset in 512-byte sectors. Used for LUKS. This function is replacement for data alignment fields in LUKS param struct. If set to 0 (default), old behaviour is preserved. This value is reset on crypt_load.

Parameters

cd	crypt device handle
data_offset	data offset in bytes

Returns

0 on success or negative errno value otherwise.

Note

Data offset must be aligned to multiple of 8 (alignment to 4096-byte sectors) and must be big enough to accommodate the whole LUKS header with all keyslots.

Data offset is enforced by this function, device topology information is no longer used after calling this function.