LUKS2 volume reencryption support

Data Structures
struct	crypt_params_reencrypt

Macros
#define	CRYPT_REENCRYPT_INITIALIZE_ONLY   (UINT32_C(1) << 0)
#define	CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT   (UINT32_C(1) << 1)
#define	CRYPT_REENCRYPT_RESUME_ONLY   (UINT32_C(1) << 2)
#define	CRYPT_REENCRYPT_RECOVERY   (UINT32_C(1) << 3)
#define	CRYPT_REENCRYPT_REPAIR_NEEDED   (UINT32_C(1) << 4)

Enumerations
enum	crypt_reencrypt_direction_info { CRYPT_REENCRYPT_FORWARD = 0 , CRYPT_REENCRYPT_BACKWARD }
enum	crypt_reencrypt_mode_info { CRYPT_REENCRYPT_REENCRYPT = 0 , CRYPT_REENCRYPT_ENCRYPT , CRYPT_REENCRYPT_DECRYPT }
enum	crypt_reencrypt_info { CRYPT_REENCRYPT_NONE = 0 , CRYPT_REENCRYPT_CLEAN , CRYPT_REENCRYPT_CRASH , CRYPT_REENCRYPT_INVALID }

Functions
int	crypt_reencrypt_init_by_passphrase (struct crypt_device *cd, const char *name, const char *passphrase, size_t passphrase_size, int keyslot_old, int keyslot_new, const char *cipher, const char *cipher_mode, const struct crypt_params_reencrypt *params)
int	crypt_reencrypt_init_by_keyring (struct crypt_device *cd, const char *name, const char *key_description, int keyslot_old, int keyslot_new, const char *cipher, const char *cipher_mode, const struct crypt_params_reencrypt *params)
int	crypt_reencrypt (struct crypt_device *cd, int(*progress)(uint64_t size, uint64_t offset, void *usrptr)) __attribute__((deprecated))
int	crypt_reencrypt_run (struct crypt_device *cd, int(*progress)(uint64_t size, uint64_t offset, void *usrptr), void *usrptr)
crypt_reencrypt_info	crypt_reencrypt_status (struct crypt_device *cd, struct crypt_params_reencrypt *params)

Detailed Description

Set of functions to handling LUKS2 volume reencryption

Macro Definition Documentation

CRYPT_REENCRYPT_INITIALIZE_ONLY

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

Initialize reencryption metadata but do not run reencryption yet. (in)

CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT

#define CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT   (UINT32_C(1) << 1)

Move the first segment, used only with datashift resilience mode and subvariants. (in/out)

CRYPT_REENCRYPT_RECOVERY

#define CRYPT_REENCRYPT_RECOVERY   (UINT32_C(1) << 3)

Run reencryption recovery only. (in)

CRYPT_REENCRYPT_REPAIR_NEEDED

#define CRYPT_REENCRYPT_REPAIR_NEEDED   (UINT32_C(1) << 4)

Reencryption requires metadata protection. (in/out)

CRYPT_REENCRYPT_RESUME_ONLY

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

Resume already initialized reencryption only. (in)

Enumeration Type Documentation

crypt_reencrypt_direction_info

enum crypt_reencrypt_direction_info

Reencryption direction

Enumerator
CRYPT_REENCRYPT_FORWARD	forward direction
CRYPT_REENCRYPT_BACKWARD	backward direction

crypt_reencrypt_info

enum crypt_reencrypt_info

Reencryption status info

Enumerator
CRYPT_REENCRYPT_NONE	No reencryption in progress
CRYPT_REENCRYPT_CLEAN	Ongoing reencryption in a clean state.
CRYPT_REENCRYPT_CRASH	Aborted reencryption that need internal recovery.
CRYPT_REENCRYPT_INVALID	Invalid state.

crypt_reencrypt_mode_info

enum crypt_reencrypt_mode_info

Reencryption mode

Enumerator
CRYPT_REENCRYPT_REENCRYPT	Reencryption mode
CRYPT_REENCRYPT_ENCRYPT	Encryption mode
CRYPT_REENCRYPT_DECRYPT	Decryption mode

Function Documentation

crypt_reencrypt()

int crypt_reencrypt	(	struct crypt_device *	cd,
		int(*)(uint64_t size, uint64_t offset, void *usrptr)	progress
	)

Legacy data reencryption function.

Parameters

cd	crypt device handle
progress	is a callback function reporting device size, current offset of reencryption and provided usrptr identification

Returns

0 on success or negative errno value otherwise.

Deprecated:

Use crypt_reencrypt_run instead.

crypt_reencrypt_init_by_keyring()

int crypt_reencrypt_init_by_keyring	(	struct crypt_device *	cd,
		const char *	name,
		const char *	key_description,
		int	keyslot_old,
		int	keyslot_new,
		const char *	cipher,
		const char *	cipher_mode,
		const struct crypt_params_reencrypt *	params
	)

Initialize reencryption metadata using passphrase in keyring.

This function initializes on-disk metadata to include all reencryption segments, according to the provided options. If metadata already contains ongoing reencryption metadata, it loads these parameters (in this situation all parameters except name and key_description can be omitted).

Parameters

cd	crypt device handle
name	name of active device or NULL for offline reencryption
key_description	passphrase (key) identification in keyring
keyslot_old	keyslot to unlock existing device or CRYPT_ANY_SLOT
keyslot_new	existing (unbound) reencryption keyslot; must be set except for decryption
cipher	cipher specification (e.g. "aes")
cipher_mode	cipher mode and IV (e.g. "xts-plain64")
params	reencryption parameters crypt_params_reencrypt.

Returns

reencryption key slot number or negative errno otherwise.

crypt_reencrypt_init_by_passphrase()

int crypt_reencrypt_init_by_passphrase	(	struct crypt_device *	cd,
		const char *	name,
		const char *	passphrase,
		size_t	passphrase_size,
		int	keyslot_old,
		int	keyslot_new,
		const char *	cipher,
		const char *	cipher_mode,
		const struct crypt_params_reencrypt *	params
	)

Initialize reencryption metadata using passphrase.

This function initializes on-disk metadata to include all reencryption segments, according to the provided options. If metadata already contains ongoing reencryption metadata, it loads these parameters (in this situation all parameters except name and passphrase can be omitted).

Parameters

cd	crypt device handle
name	name of active device or NULL for offline reencryption
passphrase	passphrase used to unlock volume key
passphrase_size	size of passphrase (binary data)
keyslot_old	keyslot to unlock existing device or CRYPT_ANY_SLOT
keyslot_new	existing (unbound) reencryption keyslot; must be set except for decryption
cipher	cipher specification (e.g. "aes")
cipher_mode	cipher mode and IV (e.g. "xts-plain64")
params	reencryption parameters crypt_params_reencrypt.

Returns

reencryption key slot number or negative errno otherwise.

crypt_reencrypt_run()

int crypt_reencrypt_run	(	struct crypt_device *	cd,
		int(*)(uint64_t size, uint64_t offset, void *usrptr)	progress,
		void *	usrptr
	)

Run data reencryption.

Parameters

cd	crypt device handle
progress	is a callback function reporting device size, current offset of reencryption and provided usrptr identification
usrptr	progress specific data

Returns

0 on success or negative errno value otherwise.

crypt_reencrypt_status()

crypt_reencrypt_info crypt_reencrypt_status	(	struct crypt_device *	cd,
		struct crypt_params_reencrypt *	params
	)

LUKS2 reencryption status.

Parameters

cd	crypt device handle
params	reencryption parameters

Returns

reencryption status info and parameters.