cryptsetup API
Public cryptsetup API
Macros | Functions
Cryptsetup device context actions

Macros

#define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING   (1 << 0)
 
#define CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC   (1 << 1)
 
#define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC   (1 << 2)
 

Functions

int crypt_format (struct crypt_device *cd, const char *type, const char *cipher, const char *cipher_mode, const char *uuid, const char *volume_key, size_t volume_key_size, void *params)
 
void crypt_set_compatibility (struct crypt_device *cd, uint32_t flags)
 
uint32_t crypt_get_compatibility (struct crypt_device *cd)
 
int crypt_convert (struct crypt_device *cd, const char *type, void *params)
 
int crypt_set_uuid (struct crypt_device *cd, const char *uuid)
 
int crypt_set_label (struct crypt_device *cd, const char *label, const char *subsystem)
 
int crypt_volume_key_keyring (struct crypt_device *cd, int enable)
 
int crypt_load (struct crypt_device *cd, const char *requested_type, void *params)
 
int crypt_repair (struct crypt_device *cd, const char *requested_type, void *params)
 
int crypt_resize (struct crypt_device *cd, const char *name, uint64_t new_size)
 
int crypt_suspend (struct crypt_device *cd, const char *name)
 
int crypt_resume_by_passphrase (struct crypt_device *cd, const char *name, int keyslot, const char *passphrase, size_t passphrase_size)
 
int crypt_resume_by_keyfile_device_offset (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size, uint64_t keyfile_offset)
 
int crypt_resume_by_keyfile_offset (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size, size_t keyfile_offset)
 
int crypt_resume_by_keyfile (struct crypt_device *cd, const char *name, int keyslot, const char *keyfile, size_t keyfile_size)
 
int crypt_resume_by_volume_key (struct crypt_device *cd, const char *name, const char *volume_key, size_t volume_key_size)
 

Detailed Description

Set of functions for formatting and manipulating with specific crypt_type

Macro Definition Documentation

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC

#define CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC   (1 << 1)

dm-integrity device does not protect superblock with HMAC (old kernels)

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING

#define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING   (1 << 0)

dm-integrity device uses less effective (legacy) padding (old kernels)

◆ CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC

#define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC   (1 << 2)

dm-integrity allow recalculating of volumes with HMAC keys (old kernels)

Function Documentation

◆ crypt_convert()

int crypt_convert ( struct crypt_device *  cd,
const char *  type,
void *  params 
)

Convert to new type for already existing device.

Parameters
cdcrypt device handle
typetype of device (optional params struct must be of this type)
paramscrypt type specific parameters (see crypt-type)
Returns
0 on success or negative errno value otherwise.
Note
Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported. Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf type must be PBKDF2) and device cannot be formatted with any authenticated encryption mode.
Device must be offline for conversion. UUID change is not possible for active devices.

◆ crypt_format()

int crypt_format ( struct crypt_device *  cd,
const char *  type,
const char *  cipher,
const char *  cipher_mode,
const char *  uuid,
const char *  volume_key,
size_t  volume_key_size,
void *  params 
)

Create (format) new crypt device (and possible header on-disk) but do not activate it.

Precondition
cd contains initialized and not formatted device context (device type must not be set)
Parameters
cdcrypt device handle
typetype of device (optional params struct must be of this type)
cipher(e.g. "aes")
cipher_modeincluding IV specification (e.g. "xts-plain")
uuidrequested UUID or NULL if it should be generated
volume_keypre-generated volume key or NULL if it should be generated (only for LUKS)
volume_key_sizesize of volume key in bytes.
paramscrypt type specific parameters (see crypt-type)
Returns
0 on success or negative errno value otherwise.
Note
Note that crypt_format does not create LUKS keyslot (any version). To create keyslot call any crypt_keyslot_add_* function.
For VERITY crypt-type, only uuid parameter is used, other parameters are ignored and verity specific attributes are set through mandatory params option.
Examples
crypt_luks_usage.c.

◆ crypt_get_compatibility()

uint32_t crypt_get_compatibility ( struct crypt_device *  cd)

Get compatibility flags.

Parameters
cdcrypt device handle
Returns
compatibility flags

◆ crypt_load()

int crypt_load ( struct crypt_device *  cd,
const char *  requested_type,
void *  params 
)

Load crypt device parameters from on-disk header.

Parameters
cdcrypt device handle
requested_typecrypt-type or NULL for all known
paramscrypt type specific parameters (see crypt-type)
Returns
0 on success or negative errno value otherwise.
Postcondition
In case LUKS header is read successfully but payload device is too small error is returned and device type in context is set to NULL
Note
Note that in current version load works only for LUKS and VERITY device type.
Examples
crypt_luks_usage.c.

◆ crypt_repair()

int crypt_repair ( struct crypt_device *  cd,
const char *  requested_type,
void *  params 
)

Try to repair crypt device LUKS on-disk header if invalid.

Parameters
cdcrypt device handle
requested_typecrypt-type or NULL for all known
paramscrypt type specific parameters (see crypt-type)
Returns
0 on success or negative errno value otherwise.
Note
For LUKS2 device crypt_repair bypass blkid checks and perform auto-recovery even though there're third party device signatures found by blkid probes. Currently the crypt_repair on LUKS2 works only if exactly one header checksum does not match or exactly one header is missing.

◆ crypt_resize()

int crypt_resize ( struct crypt_device *  cd,
const char *  name,
uint64_t  new_size 
)

Resize crypt device.

Parameters
cd- crypt device handle
name- name of device to resize
new_size- new device size in sectors or 0 to use all of the underlying device size
Returns
0 on success or negative errno value otherwise.
Note
Most notably it returns -EPERM when device was activated with volume key in kernel keyring and current device handle (context) doesn't have verified key loaded in kernel. To load volume key for already active device use any of crypt_activate_by_passphrase, crypt_activate_by_keyfile, crypt_activate_by_keyfile_offset, crypt_activate_by_volume_key, crypt_activate_by_keyring or crypt_activate_by_token with flag CRYPT_ACTIVATE_KEYRING_KEY raised and name parameter set to NULL.

◆ crypt_resume_by_keyfile()

int crypt_resume_by_keyfile ( struct crypt_device *  cd,
const char *  name,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size 
)

Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).

◆ crypt_resume_by_keyfile_device_offset()

int crypt_resume_by_keyfile_device_offset ( struct crypt_device *  cd,
const char *  name,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size,
uint64_t  keyfile_offset 
)

Resume crypt device using key file.

Parameters
cdcrypt device handle
namename of device to resume
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
Returns
unlocked key slot number or negative errno otherwise.

◆ crypt_resume_by_keyfile_offset()

int crypt_resume_by_keyfile_offset ( struct crypt_device *  cd,
const char *  name,
int  keyslot,
const char *  keyfile,
size_t  keyfile_size,
size_t  keyfile_offset 
)

Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).

◆ crypt_resume_by_passphrase()

int crypt_resume_by_passphrase ( struct crypt_device *  cd,
const char *  name,
int  keyslot,
const char *  passphrase,
size_t  passphrase_size 
)

Resume crypt device using passphrase.

Parameters
cdcrypt device handle
namename of device to resume
keyslotrequested keyslot or CRYPT_ANY_SLOT
passphrasepassphrase used to unlock volume key
passphrase_sizesize of passphrase (binary data)
Returns
unlocked key slot number or negative errno otherwise.
Note
Only LUKS device type is supported

◆ crypt_resume_by_volume_key()

int crypt_resume_by_volume_key ( struct crypt_device *  cd,
const char *  name,
const char *  volume_key,
size_t  volume_key_size 
)

Resume crypt device using provided volume key.

Parameters
cdcrypt device handle
namename of device to resume
volume_keyprovided volume key
volume_key_sizesize of volume_key
Returns
0 on success or negative errno value otherwise.

◆ crypt_set_compatibility()

void crypt_set_compatibility ( struct crypt_device *  cd,
uint32_t  flags 
)

Set format compatibility flags.

Parameters
cdcrypt device handle
flagsCRYPT_COMPATIBILITY_* flags

◆ crypt_set_label()

int crypt_set_label ( struct crypt_device *  cd,
const char *  label,
const char *  subsystem 
)

Set new labels (label and subsystem) for already existing device.

Parameters
cdcrypt device handle
labelrequested label or NULL
subsystemrequested subsystem label or NULL
Returns
0 on success or negative errno value otherwise.
Note
Currently, only LUKS2 device type is supported

◆ crypt_set_uuid()

int crypt_set_uuid ( struct crypt_device *  cd,
const char *  uuid 
)

Set new UUID for already existing device.

Parameters
cdcrypt device handle
uuidrequested UUID or NULL if it should be generated
Returns
0 on success or negative errno value otherwise.
Note
Currently, only LUKS device type are supported

◆ crypt_suspend()

int crypt_suspend ( struct crypt_device *  cd,
const char *  name 
)

Suspend crypt device.

Parameters
cdcrypt device handle, can be NULL
namename of device to suspend
Returns
0 on success or negative errno value otherwise.
Note
Only LUKS device type is supported

◆ crypt_volume_key_keyring()

int crypt_volume_key_keyring ( struct crypt_device *  cd,
int  enable 
)

Enable or disable loading of volume keys via kernel keyring. When set to 'enabled' library loads key in kernel keyring first and pass the key description to dm-crypt instead of binary key copy. If set to 'disabled' library fallbacks to old method of loading volume key directly in dm-crypt target.

Parameters
cdcrypt device handle, can be NULL
enable0 to disable loading of volume keys via kernel keyring (classical method) otherwise enable it (default)
Returns
0 on success or negative errno value otherwise.
Note
Currently loading of volume keys via kernel keyring is supported (and enabled by default) only for LUKS2 devices.
The switch is global on the library level.