cryptsetup  2.3.3
About: cryptsetup is a utility used to conveniently setup disk encryption based on the dm-crypt kernel module. These include plain dm-crypt volumes, LUKS volumes, loop-AES and TrueCrypt compatible format.
  Fossies Dox: cryptsetup-2.3.3.tar.xz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

Cryptsetup device context actions

Set of functions for formatting and manipulating with specific crypt_type. More...

Macros

#define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING   (1 << 0)
 

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_PADDING

#define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING   (1 << 0)

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

Definition at line 655 of file libcryptsetup.h.

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.

Definition at line 5448 of file setup.c.

References _, _luks2_reload(), crypt_free_type(), crypt_load(), isLUKS1(), isLUKS2(), log_dbg, log_err, crypt_device::luks1, crypt_device::luks2, LUKS2_luks1_to_luks2(), LUKS2_luks2_to_luks1(), mdata_device_path(), onlyLUKS(), crypt_device::type, and crypt_device::u.

Referenced by action_luksConvert().

◆ 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.

Definition at line 2243 of file setup.c.

References _, _crypt_format_integrity(), _crypt_format_loopaes(), _crypt_format_luks1(), _crypt_format_luks2(), _crypt_format_plain(), _crypt_format_verity(), crypt_free_volume_key(), crypt_reset_null_type(), crypt_set_null_type(), init_crypto(), isINTEGRITY(), isLOOPAES(), isLUKS1(), isLUKS2(), isPLAIN(), isVERITY(), log_dbg, log_err, mdata_device_path(), crypt_device::type, and crypt_device::volume_key.

Referenced by _activate(), _luksFormat(), action_format(), action_open_loopaes(), action_open_plain(), backup_fake_header(), and create_new_header().

◆ crypt_get_compatibility()

uint32_t crypt_get_compatibility ( struct crypt_device cd)

Get compatibility flags.

Parameters
cdcrypt device handle
Returns
compatibility flags

Definition at line 4735 of file setup.c.

References crypt_device::compatibility.

Referenced by dm_integrity_target_set().

◆ 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.

Definition at line 1004 of file setup.c.

References _crypt_load_bitlk(), _crypt_load_integrity(), _crypt_load_luks(), _crypt_load_tcrypt(), _crypt_load_verity(), crypt_metadata_device(), crypt_reset_null_type(), crypt_device::data_offset, isBITLK(), isINTEGRITY(), isLUKS1(), isLUKS2(), isTCRYPT(), isVERITY(), crypt_device::keyslots_size, log_dbg, mdata_device_path(), crypt_device::metadata_size, and crypt_device::type.

Referenced by _activate(), _open_and_activate_reencrypt_device(), action_bitlkDump(), action_dump(), action_encrypt_luks2(), action_isLuks(), action_luksAddKey(), action_luksChangeKey(), action_luksConfig(), action_luksConvert(), action_luksConvertKey(), action_luksDump(), action_luksErase(), action_luksKillSlot(), action_luksRemoveKey(), action_luksRepair(), action_luksResume(), action_luksUUID(), action_open(), action_open_bitlk(), action_open_luks(), action_reencrypt(), action_token(), activate_luks_headers(), backup_luks_headers(), check(), crypt_convert(), initialize_passphrase(), initialize_uuid(), luks2_change_pbkdf_params(), luks2_metadata_copy(), luksAddUnboundKey(), main(), open_by_remote_password(), open_by_token(), reencrypt_init(), reencrypt_lock_and_verify(), reencrypt_recovery_by_passphrase(), set_reencrypt_requirement(), tcrypt_load(), and token_add().

◆ 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.

Definition at line 2299 of file setup.c.

References _crypt_load_luks(), crypt_check_data_device_size(), crypt_metadata_device(), crypt_set_null_type(), isLUKS(), log_dbg, and mdata_device_path().

Referenced by action_luksRepair().

◆ 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.

Definition at line 2758 of file setup.c.

References _, _reload_device(), dm_target::crypt, CRYPT_ACTIVATE_KEYRING_KEY, CRYPT_ACTIVATE_REFRESH, crypt_data_device(), CRYPT_DEFAULT_SEGMENT, crypt_get_cipher_spec(), crypt_get_data_offset(), crypt_get_device_name(), crypt_get_integrity(), crypt_get_integrity_tag_size(), crypt_get_iv_offset(), crypt_get_sector_size(), crypt_get_uuid(), crypt_key_in_keyring(), crypt_loop_device(), crypt_loop_resize(), DEV_OK, device_block_adjust(), device_block_size(), DM_ACTIVE_CRYPT_KEY, DM_ACTIVE_CRYPT_KEYSIZE, DM_CRYPT, dm_crypt_target_set(), dm_query_device(), dm_targets_free(), crypt_dm_active_device::flags, isLUKS2(), isTCRYPT(), log_dbg, log_err, crypt_device::luks2, LUKS2_key_description_by_segment(), LUKS2_unmet_requirements(), MISALIGNED, name, SECTOR_SHIFT, crypt_dm_active_device::segment, single_segment(), crypt_dm_active_device::size, crypt_device::type, dm_target::type, crypt_device::u, dm_target::u, and crypt_dm_active_device::uuid.

Referenced by action_resize().

◆ 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).

Definition at line 3225 of file setup.c.

References crypt_resume_by_keyfile_device_offset(), and name.

◆ 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.

Definition at line 3157 of file setup.c.

References _, CRYPT_DEFAULT_SEGMENT, crypt_drop_keyring_key(), crypt_free_volume_key(), crypt_keyfile_device_read(), crypt_safe_free(), crypt_use_keyring_for_vk(), dm_resume_and_reinstate_key(), dm_status_suspended(), isLUKS1(), isLUKS2(), log_dbg, log_err, crypt_device::luks1, crypt_device::luks2, LUKS2_keyslot_open(), LUKS2_volume_key_load_in_keyring_by_keyslot(), LUKS_open_key_with_hdr(), name, onlyLUKS(), crypt_device::type, and crypt_device::u.

Referenced by crypt_resume_by_keyfile(), and crypt_resume_by_keyfile_offset().

◆ 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).

Definition at line 3235 of file setup.c.

References crypt_resume_by_keyfile_device_offset(), and name.

◆ 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

Definition at line 3093 of file setup.c.

References _, CRYPT_DEFAULT_SEGMENT, crypt_drop_keyring_key(), crypt_free_volume_key(), crypt_use_keyring_for_vk(), dm_resume_and_reinstate_key(), dm_status_suspended(), isLUKS1(), isLUKS2(), log_dbg, log_err, crypt_device::luks1, crypt_device::luks2, LUKS2_keyslot_open(), LUKS2_volume_key_load_in_keyring_by_keyslot(), LUKS_open_key_with_hdr(), name, onlyLUKS(), crypt_device::type, and crypt_device::u.

Referenced by action_luksResume().

◆ 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.

Definition at line 3246 of file setup.c.

References _, crypt_alloc_volume_key(), CRYPT_DEFAULT_SEGMENT, crypt_drop_keyring_key(), crypt_free_volume_key(), crypt_use_keyring_for_vk(), crypt_volume_key_load_in_keyring(), dm_resume_and_reinstate_key(), dm_status_suspended(), isLUKS1(), isLUKS2(), log_dbg, log_err, crypt_device::luks1, crypt_device::luks2, LUKS2_digest_verify_by_segment(), LUKS2_key_description_by_segment(), LUKS_verify_volume_key(), name, onlyLUKS(), crypt_device::type, and crypt_device::u.

◆ 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

Definition at line 4729 of file setup.c.

References crypt_device::compatibility.

Referenced by _luksFormat(), and action_format().

◆ 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

Definition at line 2891 of file setup.c.

References log_dbg, crypt_device::luks2, LUKS2_hdr_labels(), onlyLUKS2(), and crypt_device::u.

Referenced by _config_labels().

◆ 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

Definition at line 2859 of file setup.c.

References _, crypt_confirm(), crypt_get_uuid(), isLUKS1(), log_dbg, crypt_device::luks1, crypt_device::luks2, LUKS2_hdr_uuid(), LUKS_hdr_uuid_set(), mdata_device_path(), onlyLUKS(), crypt_device::type, crypt_device::u, and UUID_STRING_L.

Referenced by action_luksUUID().

◆ 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

Definition at line 3028 of file setup.c.

References _, CRYPT_ACTIVE, crypt_cipher_wrapped_key(), crypt_drop_keyring_key_by_description(), crypt_get_cipher(), crypt_get_cipher_mode(), crypt_get_device_key_description(), CRYPT_LUKS1, CRYPT_LUKS2, crypt_status(), crypt_uuid_type_cmp(), dm_backend_exit(), dm_backend_init(), dm_status_suspended(), dm_suspend_device(), DM_SUSPEND_WIPE_KEY, log_dbg, log_err, LOGON_KEY, name, onlyLUKS(), and crypt_device::type.

Referenced by action_luksSuspend().

◆ 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.

Definition at line 5890 of file setup.c.

References _vk_via_keyring.

Referenced by main().