Cryptsetup settings (RNG, PBKDF, locking)

Data Structures
struct	crypt_pbkdf_type

Macros
#define	CRYPT_RNG_URANDOM   0
#define	CRYPT_RNG_RANDOM   1
#define	CRYPT_PBKDF_ITER_TIME_SET   (UINT32_C(1) << 0)
#define	CRYPT_PBKDF_NO_BENCHMARK   (UINT32_C(1) << 1)
#define	CRYPT_KDF_PBKDF2   "pbkdf2"
#define	CRYPT_KDF_ARGON2I   "argon2i"
#define	CRYPT_KDF_ARGON2ID   "argon2id"

Functions
void	crypt_set_rng_type (struct crypt_device *cd, int rng_type)
int	crypt_get_rng_type (struct crypt_device *cd)
int	crypt_set_pbkdf_type (struct crypt_device *cd, const struct crypt_pbkdf_type *pbkdf)
const struct crypt_pbkdf_type *	crypt_get_pbkdf_type_params (const char *pbkdf_type)
const struct crypt_pbkdf_type *	crypt_get_pbkdf_default (const char *type)
const struct crypt_pbkdf_type *	crypt_get_pbkdf_type (struct crypt_device *cd)
void	crypt_set_iteration_time (struct crypt_device *cd, uint64_t iteration_time_ms)
int	crypt_memory_lock (struct crypt_device *cd, int lock) __attribute__((deprecated))
int	crypt_metadata_locking (struct crypt_device *cd, int enable)
int	crypt_set_metadata_size (struct crypt_device *cd, uint64_t metadata_size, uint64_t keyslots_size)
int	crypt_get_metadata_size (struct crypt_device *cd, uint64_t *metadata_size, uint64_t *keyslots_size)

Detailed Description

Macro Definition Documentation

CRYPT_KDF_ARGON2I

#define CRYPT_KDF_ARGON2I   "argon2i"

Argon2i according to RFC

CRYPT_KDF_ARGON2ID

#define CRYPT_KDF_ARGON2ID   "argon2id"

Argon2id according to RFC

CRYPT_KDF_PBKDF2

#define CRYPT_KDF_PBKDF2   "pbkdf2"

PBKDF2 according to RFC2898, LUKS1 legacy

CRYPT_PBKDF_ITER_TIME_SET

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

Iteration time set by crypt_set_iteration_time(), for compatibility only.

CRYPT_PBKDF_NO_BENCHMARK

#define CRYPT_PBKDF_NO_BENCHMARK   (UINT32_C(1) << 1)

Never run benchmarks or limit by system resources, use pre-set values or defaults.

CRYPT_RNG_RANDOM

#define CRYPT_RNG_RANDOM   1

CRYPT_RNG_RANDOM - use /dev/random (waits if no entropy in system)

CRYPT_RNG_URANDOM

#define CRYPT_RNG_URANDOM   0

CRYPT_RNG_URANDOM - use /dev/urandom

Function Documentation

crypt_get_metadata_size()

int crypt_get_metadata_size	(	struct crypt_device *	cd,
		uint64_t *	metadata_size,
		uint64_t *	keyslots_size
	)

Get metadata header area sizes. This applies only to LUKS2. These values limit amount of metadata anf number of supportable keyslots.

Parameters

cd	crypt device handle
metadata_size	size in bytes of JSON area + 4k binary header
keyslots_size	size in bytes of binary keyslots area

Returns

0 on success or negative errno value otherwise.

crypt_get_pbkdf_default()

const struct crypt_pbkdf_type * crypt_get_pbkdf_default

(

const char *

type

)

Get default PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots. Works only with LUKS device handles (both versions).

Parameters

type	type of device (see crypt-type)

Returns

struct on success or NULL value otherwise.

crypt_get_pbkdf_type()

const struct crypt_pbkdf_type * crypt_get_pbkdf_type

(

struct crypt_device *

cd

)

Get current PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots. Works only with LUKS device handles (both versions).

Parameters

cd	crypt device handle

Returns

struct on success or NULL value otherwise.

crypt_get_pbkdf_type_params()

const struct crypt_pbkdf_type * crypt_get_pbkdf_type_params

(

const char *

pbkdf_type

)

Get PBKDF (Password-Based Key Derivation Algorithm) parameters.

Parameters

pbkdf_type

type of PBKDF

Returns

struct on success or NULL value otherwise.

crypt_get_rng_type()

int crypt_get_rng_type

(

struct crypt_device *

cd

)

Get which RNG (random number generator) is used for generating long term key.

Parameters

cd	crypt device handle

Returns

RNG type on success or negative errno value otherwise.

crypt_memory_lock()

int crypt_memory_lock	(	struct crypt_device *	cd,
		int	lock
	)

Helper to lock/unlock memory to avoid swap sensitive data to disk. Deprecated, only for backward compatibility. Memory with keys are locked automatically.

Parameters

cd	crypt device handle, can be NULL
lock	0 to unlock otherwise lock memory

Returns

Value indicating whether the memory is locked (function can be called multiple times).

Note

Only root can do this.

It locks/unlocks all process memory, not only crypt context.

crypt_metadata_locking()

int crypt_metadata_locking	(	struct crypt_device *	cd,
		int	enable
	)

Set global lock protection for on-disk metadata (file-based locking).

Parameters

cd	crypt device handle, can be NULL
enable	0 to disable locking otherwise enable it (default)

Returns

0 on success or negative errno value otherwise.

Note

Locking applied only for some metadata formats (LUKS2).

The switch is global on the library level. In current version locking can be only switched off and cannot be switched on later.

crypt_set_iteration_time()

void crypt_set_iteration_time	(	struct crypt_device *	cd,
		uint64_t	iteration_time_ms
	)

Set how long should cryptsetup iterate in PBKDF2 function. Default value heads towards the iterations which takes around 1 second. Deprecated, only for backward compatibility. Use crypt_set_pbkdf_type.

Parameters

cd	crypt device handle
iteration_time_ms	the time in ms

Note

If the time value is not acceptable for active PBKDF, value is quietly ignored.

crypt_set_metadata_size()

int crypt_set_metadata_size	(	struct crypt_device *	cd,
		uint64_t	metadata_size,
		uint64_t	keyslots_size
	)

Set metadata header area sizes. This applies only to LUKS2. These values limit amount of metadata anf number of supportable keyslots.

Parameters

cd	crypt device handle, can be NULL
metadata_size	size in bytes of JSON area + 4k binary header
keyslots_size	size in bytes of binary keyslots area

Returns

0 on success or negative errno value otherwise.

Note

The metadata area is stored twice and both copies contain 4k binary header. Only 16,32,64,128,256,512,1024,2048 and 4096 kB value is allowed (see LUKS2 specification).

Keyslots area size must be multiple of 4k with maximum 128MB.

crypt_set_pbkdf_type()

int crypt_set_pbkdf_type	(	struct crypt_device *	cd,
		const struct crypt_pbkdf_type *	pbkdf
	)

Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot about to get created with any crypt_keyslot_add_*() call.

Parameters

cd	crypt device handle
pbkdf	PBKDF parameters

Returns

0 on success or negative errno value otherwise.

Note

For LUKS1, only PBKDF2 is supported, other settings will be rejected.

For non-LUKS context types the call succeeds, but PBKDF is not used.

crypt_set_rng_type()

void crypt_set_rng_type	(	struct crypt_device *	cd,
		int	rng_type
	)

Set which RNG (random number generator) is used for generating long term key

Parameters

cd	crypt device handle
rng_type	kernel random number generator to use