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)
#define	CRYPT_REENCRYPT_CREATE_NEW_DIGEST   (UINT32_C(1) << 5)

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_init_by_keyslot_context (struct crypt_device *cd, const char *name, struct crypt_keyslot_context *kc_old, struct crypt_keyslot_context *kc_new, 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_CREATE_NEW_DIGEST

#define CRYPT_REENCRYPT_CREATE_NEW_DIGEST   (UINT32_C(1) << 5)

Calculate new (future) volume key digest directly during reencryption initialization. The keyslot context for new volume key must be CRYPT_KC_TYPE_KEY or CRYPT_KC_TYPE_VK_KEYRING. (in)

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

int crypt_reencrypt_init_by_keyslot_context	(	struct crypt_device *	cd,
		const char *	name,
		struct crypt_keyslot_context *	kc_old,
		struct crypt_keyslot_context *	kc_new,
		int	keyslot_old,
		int	keyslot_new,
		const char *	cipher,
		const char *	cipher_mode,
		const struct crypt_params_reencrypt *	params
	)

Initialize or reload LUKS2 reencryption operation using keyslot contexts.

The function can initialize reencryption on-disk metadata or reload reencryption context from on-disk LUSK2 metadata to resume interrupted operation.

If the device is not in reencryption state (crypt_reencrypt_status returns CRYPT_REENCRYPT_NONE) the function initializes on-disk metadata to include all necessary reencryption segments and new encryption parameters (cipher, cipher mode, encryption sector size) according to the provided parameters.

If on-disk metadata already describes reencryption operation (crypt_reencrypt_status returns CRYPT_REENCRYPT_CLEAN), it loads these parameters and internally initializes reencryption context. It also verifies if the device is eligible to resume reencryption operation. Some reencryption parameters (crypt_params_reencrypt) may be modified depending on the original values in the initialization call. When resuming the operation, all parameters may be omitted except cd, name (offline/online),kc_old and kc_new.

If on-disk metadata describes reencryption operation requiring recovery (crypt_reencrypt_status returns CRYPT_REENCRYPT_CRASH), it can be recovered by adding CRYPT_REENCRYPT_RECOVERY flag in crypt_params_reencrypt parameter.

Parameters

cd	crypt device handle
name	name of the active device or NULL for offline reencryption
kc_old	keyslot context providing access to volume key in keyslot id keyslot_old.
kc_new	keyslot context providing access to volume key in keyslot id keyslot_new.
keyslot_old	keyslot id containing current volume key for the device or CRYPT_ANY_SLOT
keyslot_new	keyslot id containing (unbound) future volume key in encryption or reencryption operation. It must be set in the initialization call except when initializing the decrypt operation. In reencryption operation it may contain also the current volume key in case the volume key change is not requested.
cipher	new cipher specification (e.g. "aes") or NULL in decryption. Relevant only during metadata initialization.
cipher_mode	cipher mode and IV (e.g. "xts-plain64") or NULL in decryption. Relevant only during metadata initialization.
params	reencryption parameters crypt_params_reencrypt.

Returns

reencryption key slot number or negative errno otherwise.

Note

Only after successful reencryption initialization you may run the operation with crypt_reencrypt_run.

During CRYPT_REENCRYPT_REENCRYPT operation it is highly recommended to use same keyslot context (same passphrase, token, keyfile, etc) in both kc_old and kc_new parameters for at least one keyslot containing future volume key and one keyslot containing current volume key. If the same keyslot context can not be used to unlock any current or any future volume key it would be impossible to perform reencryption crash recovery during device activation for example after system reboot. Any keyslot passphrase may be changed in-before initializing reencryption operation via crypt_keyslot_change_by_passphrase.

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.

Note

A progress callback can interrupt reencryption process by returning non-zero code.

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.