cryptsetup API
Public cryptsetup API
Loading...
Searching...
No Matches
Modules | Macros | Enumerations | Functions
LUKS keyslots

Modules

 Crypt keyslot context
 

Macros

#define CRYPT_ANY_SLOT   -1
 
#define CRYPT_VOLUME_KEY_NO_SEGMENT   (UINT32_C(1) << 0)
 
#define CRYPT_VOLUME_KEY_SET   (UINT32_C(1) << 1)
 
#define CRYPT_VOLUME_KEY_DIGEST_REUSE   (UINT32_C(1) << 2)
 

Enumerations

enum  crypt_keyslot_info {
  CRYPT_SLOT_INVALID , CRYPT_SLOT_INACTIVE , CRYPT_SLOT_ACTIVE , CRYPT_SLOT_ACTIVE_LAST ,
  CRYPT_SLOT_UNBOUND
}
 
enum  crypt_keyslot_priority { CRYPT_SLOT_PRIORITY_INVALID =-1 , CRYPT_SLOT_PRIORITY_IGNORE = 0 , CRYPT_SLOT_PRIORITY_NORMAL = 1 , CRYPT_SLOT_PRIORITY_PREFER = 2 }
 

Functions

int crypt_keyslot_add_by_passphrase (struct crypt_device *cd, int keyslot, const char *passphrase, size_t passphrase_size, const char *new_passphrase, size_t new_passphrase_size)
 
int crypt_keyslot_change_by_passphrase (struct crypt_device *cd, int keyslot_old, int keyslot_new, const char *passphrase, size_t passphrase_size, const char *new_passphrase, size_t new_passphrase_size)
 
int crypt_keyslot_add_by_keyfile_device_offset (struct crypt_device *cd, int keyslot, const char *keyfile, size_t keyfile_size, uint64_t keyfile_offset, const char *new_keyfile, size_t new_keyfile_size, uint64_t new_keyfile_offset)
 
int crypt_keyslot_add_by_keyfile_offset (struct crypt_device *cd, int keyslot, const char *keyfile, size_t keyfile_size, size_t keyfile_offset, const char *new_keyfile, size_t new_keyfile_size, size_t new_keyfile_offset)
 
int crypt_keyslot_add_by_keyfile (struct crypt_device *cd, int keyslot, const char *keyfile, size_t keyfile_size, const char *new_keyfile, size_t new_keyfile_size)
 
int crypt_keyslot_add_by_volume_key (struct crypt_device *cd, int keyslot, const char *volume_key, size_t volume_key_size, const char *passphrase, size_t passphrase_size)
 
int crypt_keyslot_add_by_key (struct crypt_device *cd, int keyslot, const char *volume_key, size_t volume_key_size, const char *passphrase, size_t passphrase_size, uint32_t flags)
 
int crypt_keyslot_add_by_keyslot_context (struct crypt_device *cd, int keyslot_existing, struct crypt_keyslot_context *kc, int keyslot_new, struct crypt_keyslot_context *new_kc, uint32_t flags)
 
int crypt_keyslot_destroy (struct crypt_device *cd, int keyslot)
 
crypt_keyslot_info crypt_keyslot_status (struct crypt_device *cd, int keyslot)
 
crypt_keyslot_priority crypt_keyslot_get_priority (struct crypt_device *cd, int keyslot)
 
int crypt_keyslot_set_priority (struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority)
 
int crypt_keyslot_max (const char *type)
 
int crypt_keyslot_area (struct crypt_device *cd, int keyslot, uint64_t *offset, uint64_t *length)
 
int crypt_keyslot_get_key_size (struct crypt_device *cd, int keyslot)
 
const char * crypt_keyslot_get_encryption (struct crypt_device *cd, int keyslot, size_t *key_size)
 
int crypt_keyslot_get_pbkdf (struct crypt_device *cd, int keyslot, struct crypt_pbkdf_type *pbkdf)
 
int crypt_keyslot_set_encryption (struct crypt_device *cd, const char *cipher, size_t key_size)
 
const char * crypt_get_dir (void)
 

Detailed Description

Macro Definition Documentation

◆ CRYPT_ANY_SLOT

#define CRYPT_ANY_SLOT   -1

iterate through all keyslots and find first one that fits

Examples
crypt_luks_usage.c.

◆ CRYPT_VOLUME_KEY_DIGEST_REUSE

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

Assign key to first matching digest before creating new digest

◆ CRYPT_VOLUME_KEY_NO_SEGMENT

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

create keyslot with volume key not associated with current dm-crypt segment

◆ CRYPT_VOLUME_KEY_SET

#define CRYPT_VOLUME_KEY_SET   (UINT32_C(1) << 1)

create keyslot with new volume key and assign it to current dm-crypt segment

Enumeration Type Documentation

◆ crypt_keyslot_info

Crypt keyslot info

Enumerator
CRYPT_SLOT_INVALID 

invalid keyslot

CRYPT_SLOT_INACTIVE 

keyslot is inactive (free)

CRYPT_SLOT_ACTIVE 

keyslot is active (used)

CRYPT_SLOT_ACTIVE_LAST 

keylost is active (used) and last used at the same time

CRYPT_SLOT_UNBOUND 

keyslot is active and not bound to any crypt segment (LUKS2 only)

◆ crypt_keyslot_priority

Crypt keyslot priority

Enumerator
CRYPT_SLOT_PRIORITY_INVALID 

no such slot

CRYPT_SLOT_PRIORITY_IGNORE 

CRYPT_ANY_SLOT will ignore it for open

CRYPT_SLOT_PRIORITY_NORMAL 

default priority, tried after preferred

CRYPT_SLOT_PRIORITY_PREFER 

will try to open first

Function Documentation

◆ crypt_get_dir()

const char * crypt_get_dir ( void  )

Get directory where mapped crypt devices are created

Returns
the directory path
Examples
crypt_luks_usage.c.

◆ crypt_keyslot_add_by_key()

int crypt_keyslot_add_by_key ( struct crypt_device *  cd,
int  keyslot,
const char *  volume_key,
size_t  volume_key_size,
const char *  passphrase,
size_t  passphrase_size,
uint32_t  flags 
)

Add key slot using provided key.

Precondition
cd contains initialized and formatted LUKS2 device context
Parameters
cdcrypt device handle
keyslotrequested keyslot or CRYPT_ANY_SLOT
volume_keyprovided volume key or NULL (see note below)
volume_key_sizesize of volume_key
passphrasepassphrase for new keyslot
passphrase_sizesize of passphrase
flagskey flags to set
Returns
allocated key slot number or negative errno otherwise.
Note
in case volume_key is NULL following first matching rule will apply:
  • if cd is device handle used in crypt_format() by current process, the volume key generated (or passed) in crypt_format() will be stored in keyslot.
  • if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be generated and stored in keyslot. The keyslot will become unbound (unusable to dm-crypt device activation).
  • fails with -EINVAL otherwise
Warning
CRYPT_VOLUME_KEY_SET flag force updates volume key. It is not reencryption! By doing so you will most probably destroy your ciphertext data device. It's supposed to be used only in wrapped keys scheme for key refresh process where real (inner) volume key stays untouched. It may be involved on active keyslot which makes the (previously unbound) keyslot new regular keyslot.

◆ crypt_keyslot_add_by_keyfile()

int crypt_keyslot_add_by_keyfile ( struct crypt_device *  cd,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size,
const char *  new_keyfile,
size_t  new_keyfile_size 
)

Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).

◆ crypt_keyslot_add_by_keyfile_device_offset()

int crypt_keyslot_add_by_keyfile_device_offset ( struct crypt_device *  cd,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size,
uint64_t  keyfile_offset,
const char *  new_keyfile,
size_t  new_keyfile_size,
uint64_t  new_keyfile_offset 
)

Add key slot using provided key file path.

Precondition
cd contains initialized and formatted LUKS device context
Parameters
cdcrypt device handle
keyslotrequested keyslot or CRYPT_ANY_SLOT
keyfilekey file used to unlock volume key
keyfile_sizenumber of bytes to read from keyfile, 0 is unlimited
keyfile_offsetnumber of bytes to skip at start of keyfile
new_keyfilekeyfile for new keyslot
new_keyfile_sizenumber of bytes to read from new_keyfile, 0 is unlimited
new_keyfile_offsetnumber of bytes to skip at start of new_keyfile
Returns
allocated key slot number or negative errno otherwise.

◆ crypt_keyslot_add_by_keyfile_offset()

int crypt_keyslot_add_by_keyfile_offset ( struct crypt_device *  cd,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size,
size_t  keyfile_offset,
const char *  new_keyfile,
size_t  new_keyfile_size,
size_t  new_keyfile_offset 
)

Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).

◆ crypt_keyslot_add_by_keyslot_context()

int crypt_keyslot_add_by_keyslot_context ( struct crypt_device *  cd,
int  keyslot_existing,
struct crypt_keyslot_context *  kc,
int  keyslot_new,
struct crypt_keyslot_context *  new_kc,
uint32_t  flags 
)

Add key slot by volume key provided by keyslot context (kc). New keyslot will be protected by passphrase provided by new keyslot context (new_kc). See crypt-keyslot-context for context initialization routines.

Precondition
cd contains initialized and formatted LUKS device context.
Parameters
cdcrypt device handle
keyslot_existingexisting keyslot or CRYPT_ANY_SLOT to get volume key from.
kckeyslot context providing volume key.
keyslot_newnew keyslot or CRYPT_ANY_SLOT (first free number is used).
new_kckeyslot context providing passphrase for new keyslot.
flagskey flags to set
Returns
allocated key slot number or negative errno otherwise.
Note
new_kc can not be CRYPT_KC_TYPE_KEY type keyslot context.
For kc parameter with type CRYPT_KC_TYPE_KEY the keyslot_existing parameter is ignored.
in case there is no active LUKS keyslot to get existing volume key from, one of following must apply:
  • cd must be device handle used in crypt_format() by current process (it holds reference to generated volume key)
  • kc must be of CRYPT_KC_TYPE_KEY type with valid volume key.
With CRYPT_VOLUME_KEY_NO_SEGMENT flag raised and kc of type CRYPT_KC_TYPE_KEY with volume_key set to NULL the new volume_key will be generated and stored in new keyslot. The keyslot will become unbound (unusable to dm-crypt device activation).
Warning
CRYPT_VOLUME_KEY_SET flag force updates volume key. It is not reencryption! By doing so you will most probably destroy your ciphertext data device. It's supposed to be used only in wrapped keys scheme for key refresh process where real (inner) volume key stays untouched. It may be involved on active keyslot which makes the (previously unbound) keyslot new regular keyslot.

◆ crypt_keyslot_add_by_passphrase()

int crypt_keyslot_add_by_passphrase ( struct crypt_device *  cd,
int  keyslot,
const char *  passphrase,
size_t  passphrase_size,
const char *  new_passphrase,
size_t  new_passphrase_size 
)

Add key slot using provided passphrase.

Precondition
cd contains initialized and formatted LUKS device context
Parameters
cdcrypt device handle
keyslotrequested keyslot or CRYPT_ANY_SLOT
passphrasepassphrase used to unlock volume key
passphrase_sizesize of passphrase (binary data)
new_passphrasepassphrase for new keyslot
new_passphrase_sizesize of new_passphrase (binary data)
Returns
allocated key slot number or negative errno otherwise.
Examples
crypt_luks_usage.c.

◆ crypt_keyslot_add_by_volume_key()

int crypt_keyslot_add_by_volume_key ( struct crypt_device *  cd,
int  keyslot,
const char *  volume_key,
size_t  volume_key_size,
const char *  passphrase,
size_t  passphrase_size 
)

Add key slot using provided volume key.

Precondition
cd contains initialized and formatted LUKS device context
Parameters
cdcrypt device handle
keyslotrequested keyslot or CRYPT_ANY_SLOT
volume_keyprovided volume key or NULL if used after crypt_format
volume_key_sizesize of volume_key
passphrasepassphrase for new keyslot
passphrase_sizesize of passphrase
Returns
allocated key slot number or negative errno otherwise.
Examples
crypt_luks_usage.c.

◆ crypt_keyslot_area()

int crypt_keyslot_area ( struct crypt_device *  cd,
int  keyslot,
uint64_t *  offset,
uint64_t *  length 
)

Get keyslot area pointers (relative to metadata device).

Parameters
cdcrypt device handle
keyslotkeyslot number
offsetoffset on metadata device (in bytes)
lengthlength of keyslot area (in bytes)
Returns
0 on success or negative errno value otherwise.

◆ crypt_keyslot_change_by_passphrase()

int crypt_keyslot_change_by_passphrase ( struct crypt_device *  cd,
int  keyslot_old,
int  keyslot_new,
const char *  passphrase,
size_t  passphrase_size,
const char *  new_passphrase,
size_t  new_passphrase_size 
)

Change defined key slot using provided passphrase.

Precondition
cd contains initialized and formatted LUKS device context
Parameters
cdcrypt device handle
keyslot_oldold keyslot or CRYPT_ANY_SLOT
keyslot_newnew keyslot (can be the same as old)
passphrasepassphrase used to unlock volume key
passphrase_sizesize of passphrase (binary data)
new_passphrasepassphrase for new keyslot
new_passphrase_sizesize of new_passphrase (binary data)
Returns
allocated key slot number or negative errno otherwise.

◆ crypt_keyslot_destroy()

int crypt_keyslot_destroy ( struct crypt_device *  cd,
int  keyslot 
)

Destroy (and disable) key slot.

Precondition
cd contains initialized and formatted LUKS device context
Parameters
cdcrypt device handle
keyslotrequested key slot to destroy
Returns
0 on success or negative errno value otherwise.
Note
Note that there is no passphrase verification used.

◆ crypt_keyslot_get_encryption()

const char * crypt_keyslot_get_encryption ( struct crypt_device *  cd,
int  keyslot,
size_t *  key_size 
)

Get cipher and key size for keyslot encryption. Use for LUKS2 keyslot to set different encryption type than for data encryption. Parameters will be used for next keyslot operations.

Parameters
cdcrypt device handle
keyslotkeyslot number of CRYPT_ANY_SLOT for default
key_sizeencryption key size (in bytes)
Returns
cipher specification on success or NULL.
Note
This is the encryption of keyslot itself, not the data encryption algorithm!

◆ crypt_keyslot_get_key_size()

int crypt_keyslot_get_key_size ( struct crypt_device *  cd,
int  keyslot 
)

Get size (in bytes) of stored key in particular keyslot. Use for LUKS2 unbound keyslots, for other keyslots it is the same as crypt_get_volume_key_size

Parameters
cdcrypt device handle
keyslotkeyslot number
Returns
volume key size or negative errno value otherwise.

◆ crypt_keyslot_get_pbkdf()

int crypt_keyslot_get_pbkdf ( struct crypt_device *  cd,
int  keyslot,
struct crypt_pbkdf_type pbkdf 
)

Get PBKDF parameters for keyslot.

Parameters
cdcrypt device handle
keyslotkeyslot number
pbkdfstruct with returned PBKDF parameters
Returns
0 on success or negative errno value otherwise.

◆ crypt_keyslot_get_priority()

crypt_keyslot_priority crypt_keyslot_get_priority ( struct crypt_device *  cd,
int  keyslot 
)

Get keyslot priority (LUKS2)

Parameters
cdcrypt device handle
keyslotkeyslot number
Returns
value defined by crypt_keyslot_priority

◆ crypt_keyslot_max()

int crypt_keyslot_max ( const char *  type)

Get number of keyslots supported for device type.

Parameters
typecrypt device type
Returns
slot count or negative errno otherwise if device doesn't not support keyslots.

◆ crypt_keyslot_set_encryption()

int crypt_keyslot_set_encryption ( struct crypt_device *  cd,
const char *  cipher,
size_t  key_size 
)

Set encryption for keyslot. Use for LUKS2 keyslot to set different encryption type than for data encryption. Parameters will be used for next keyslot operations that create or change a keyslot.

Parameters
cdcrypt device handle
cipher(e.g. "aes-xts-plain64")
key_sizeencryption key size (in bytes)
Returns
0 on success or negative errno value otherwise.
Note
To reset to default keyslot encryption (the same as for data) set cipher to NULL and key size to 0.

◆ crypt_keyslot_set_priority()

int crypt_keyslot_set_priority ( struct crypt_device *  cd,
int  keyslot,
crypt_keyslot_priority  priority 
)

Set keyslot priority (LUKS2)

Parameters
cdcrypt device handle
keyslotkeyslot number
prioritypriority defined in crypt_keyslot_priority
Returns
0 on success or negative errno value otherwise.

◆ crypt_keyslot_status()

crypt_keyslot_info crypt_keyslot_status ( struct crypt_device *  cd,
int  keyslot 
)

Get information about particular key slot.

Parameters
cdcrypt device handle
keyslotrequested keyslot to check or CRYPT_ANY_SLOT
Returns
value defined by crypt_keyslot_info