cryptsetup API
Public cryptsetup API
Loading...
Searching...
No Matches
Data Structures | Macros | Functions
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_typecrypt_get_pbkdf_type_params (const char *pbkdf_type)
 
const struct crypt_pbkdf_typecrypt_get_pbkdf_default (const char *type)
 
const struct crypt_pbkdf_typecrypt_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
cdcrypt device handle
metadata_sizesize in bytes of JSON area + 4k binary header
keyslots_sizesize 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
typetype 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
cdcrypt 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_typetype 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
cdcrypt 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
cdcrypt device handle, can be NULL
lock0 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
cdcrypt device handle, can be NULL
enable0 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
cdcrypt device handle
iteration_time_msthe 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
cdcrypt device handle, can be NULL
metadata_sizesize in bytes of JSON area + 4k binary header
keyslots_sizesize 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
cdcrypt device handle
pbkdfPBKDF 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
cdcrypt device handle
rng_typekernel random number generator to use