Crypto: libblockdev Reference Manual

Crypto

Crypto — plugin for operations with encrypted devices

Functions

gboolean	bd_crypto_check_deps ()
void	bd_crypto_close ()
gboolean	bd_crypto_init ()
GQuark	bd_crypto_error_quark ()
gchar *	bd_crypto_generate_backup_passphrase ()
gboolean	bd_crypto_device_is_luks ()
gboolean	bd_crypto_device_seems_encrypted ()
gchar *	bd_crypto_luks_uuid ()
guint64	bd_crypto_luks_get_metadata_size ()
gchar *	bd_crypto_luks_status ()
gboolean	bd_crypto_luks_format ()
gboolean	bd_crypto_luks_format_blob ()
void	bd_crypto_luks_extra_free ()
BDCryptoLUKSExtra *	bd_crypto_luks_extra_copy ()
BDCryptoLUKSExtra *	bd_crypto_luks_extra_new ()
void	bd_crypto_luks_pbkdf_free ()
BDCryptoLUKSPBKDF *	bd_crypto_luks_pbkdf_copy ()
BDCryptoLUKSPBKDF *	bd_crypto_luks_pbkdf_new ()
gboolean	bd_crypto_luks_format_luks2 ()
gboolean	bd_crypto_luks_format_luks2_blob ()
gboolean	bd_crypto_luks_open ()
gboolean	bd_crypto_luks_open_blob ()
gboolean	bd_crypto_luks_close ()
gboolean	bd_crypto_luks_add_key ()
gboolean	bd_crypto_luks_add_key_blob ()
gboolean	bd_crypto_luks_remove_key ()
gboolean	bd_crypto_luks_remove_key_blob ()
gboolean	bd_crypto_luks_change_key ()
gboolean	bd_crypto_luks_change_key_blob ()
gboolean	bd_crypto_luks_resize ()
gboolean	bd_crypto_luks_resize_luks2 ()
gboolean	bd_crypto_luks_resize_luks2_blob ()
gboolean	bd_crypto_luks_suspend ()
gboolean	bd_crypto_luks_resume_blob ()
gboolean	bd_crypto_luks_resume ()
gboolean	bd_crypto_luks_kill_slot ()
gboolean	bd_crypto_luks_header_backup ()
gboolean	bd_crypto_luks_header_restore ()
void	bd_crypto_luks_info_free ()
BDCryptoLUKSInfo *	bd_crypto_luks_info_copy ()
BDCryptoLUKSInfo *	bd_crypto_luks_info ()
void	bd_crypto_integrity_info_free ()
BDCryptoIntegrityInfo *	bd_crypto_integrity_info_copy ()
BDCryptoIntegrityInfo *	bd_crypto_integrity_info ()
gboolean	bd_crypto_tc_open ()
gboolean	bd_crypto_tc_open_full ()
gboolean	bd_crypto_tc_close ()
gboolean	bd_crypto_escrow_device ()
gboolean	bd_crypto_is_tech_avail ()

Types and Values

#define	BD_CRYPTO_LUKS_METADATA_SIZE
#define	BD_CRYPTO_ERROR
enum	BDCryptoError
#define	BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET
#define	BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH
#define	DEFAULT_LUKS_KEYSIZE_BITS
#define	DEFAULT_LUKS_CIPHER
	BDCryptoLUKSExtra
	BDCryptoLUKSPBKDF
enum	BDCryptoLUKSVersion
	BDCryptoLUKSInfo
	BDCryptoIntegrityInfo
enum	BDCryptoTech
enum	BDCryptoTechMode

Includes

#include <crypto.h>

Description

A plugin for operations with encrypted devices. For now, only LUKS devices are supported.

Functions taking a parameter called "device" require the backing device to be passed. On the other hand functions taking the "luks_device" parameter require the LUKS device (/dev/mapper/SOMETHING").

Sizes are given in bytes unless stated otherwise.

Functions

bd_crypto_check_deps ()

gboolean
bd_crypto_check_deps (void);

Returns

whether the plugin's runtime dependencies are satisfied or not

Function checking plugin's runtime dependencies.

bd_crypto_close ()

void
bd_crypto_close (void);

Cleans up after the plugin. **This function is called automatically by the library's functions that unload it.**

bd_crypto_init ()

gboolean
bd_crypto_init (void);

Initializes the plugin. **This function is called automatically by the library's initialization functions.**

bd_crypto_error_quark ()

GQuark
bd_crypto_error_quark (void);

[skip]

bd_crypto_generate_backup_passphrase ()

gchar *
bd_crypto_generate_backup_passphrase (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

A newly generated BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH-long passphrase.

See BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET for the definition of the charset used for the passphrase.

Tech category: always available

bd_crypto_device_is_luks ()

gboolean
bd_crypto_device_is_luks (const gchar *device,
                          GError **error);

Parameters

device	the queried device
error	place to store error (if any).	[out]

Returns

TRUE if the given device is a LUKS device or FALSE if not or failed to determine (the error ) is populated with the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_device_seems_encrypted ()

gboolean
bd_crypto_device_seems_encrypted (const gchar *device,
                                  GError **error);

Determines whether a block device seems to be encrypted.

TCRYPT volumes are not easily identifiable, because they have no cleartext header, but are completely encrypted. This function is used to determine whether a block device is a candidate for being TCRYPT encrypted.

To achieve this, we calculate the chi square value of the first 512 Bytes and treat devices with a chi square value between 136 and 426 as candidates for being encrypted. For the reasoning, see: https://tails.boum.org/blueprint/veracrypt/

Parameters

device	the queried device
error	place to store error (if any).	[out]

Returns

TRUE if the given device seems to be encrypted or FALSE if not or failed to determine (the error ) is populated with the error in such cases)

Tech category: BD_CRYPTO_TECH_TRUECRYPT-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_luks_uuid ()

gchar *
bd_crypto_luks_uuid (const gchar *device,
                     GError **error);

Parameters

device	the queried device
error	place to store error (if any).	[out]

Returns

UUID of the device or NULL if failed to determine (error is populated with the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_luks_get_metadata_size ()

guint64
bd_crypto_luks_get_metadata_size (const gchar *device,
                                  GError **error);

Parameters

device	the queried device
error	place to store error (if any).	[out]

Returns

luks device metadata size of the device or 0 if failed to determine (error is populated with the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_luks_status ()

gchar *
bd_crypto_luks_status (const gchar *luks_device,
                       GError **error);

Parameters

luks_device	the queried LUKS device
error	place to store error (if any).	[out]

Returns

one of "invalid", "inactive", "active" or "busy" or NULL if failed to determine (error is populated with the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY.

[transfer none]

bd_crypto_luks_format ()

gboolean
bd_crypto_luks_format (const gchar *device,
                       const gchar *cipher,
                       guint64 key_size,
                       const gchar *passphrase,
                       const gchar *key_file,
                       guint64 min_entropy,
                       GError **error);

Formats the given device as LUKS according to the other parameters given. If min_entropy is specified (greater than 0), the function waits for enough entropy to be available in the random data pool (WHICH MAY POTENTIALLY TAKE FOREVER).

Parameters

device	a device to format as LUKS
cipher	cipher specification (type-mode, e.g. "aes-xts-plain64") or `NULL` to use the default.	[allow-none]
key_size	size of the volume key in bits or 0 to use the default
passphrase	a passphrase for the new LUKS device or `NULL` if not requested.	[allow-none]
key_file	a key file for the new LUKS device or `NULL` if not requested.	[allow-none]
min_entropy	minimum random data entropy (in bits) required to format `device` as LUKS
error	place to store error (if any).	[out]

Returns

whether the given device was successfully formatted as LUKS or not (the error ) contains the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_CREATE

bd_crypto_luks_format_blob ()

gboolean
bd_crypto_luks_format_blob (const gchar *device,
                            const gchar *cipher,
                            guint64 key_size,
                            const guint8 *pass_data,
                            gsize data_len,
                            guint64 min_entropy,
                            GError **error);

Parameters

device	a device to format as LUKS
cipher	cipher specification (type-mode, e.g. "aes-xts-plain64") or `NULL` to use the default.	[allow-none]
key_size	size of the volume key in bits or 0 to use the default
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
min_entropy	minimum random data entropy (in bits) required to format `device` as LUKS
error	place to store error (if any).	[out]

Returns

whether the given device was successfully formatted as LUKS or not (the error ) contains the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_CREATE

bd_crypto_luks_extra_free ()

void
bd_crypto_luks_extra_free (BDCryptoLUKSExtra *extra);

Frees extra .

[skip]

bd_crypto_luks_extra_copy ()

BDCryptoLUKSExtra *
bd_crypto_luks_extra_copy (BDCryptoLUKSExtra *extra);

Creates a new copy of extra .

[skip]

bd_crypto_luks_extra_new ()

BDCryptoLUKSExtra *
bd_crypto_luks_extra_new (guint64 data_alignment,
                          const gchar *data_device,
                          const gchar *integrity,
                          guint64 sector_size,
                          const gchar *label,
                          const gchar *subsystem,
                          BDCryptoLUKSPBKDF *pbkdf);

[constructor]

Parameters

data_alignment	data alignment in sectors, 0 for default/auto detection
data_device	detached encrypted data device or NULL.	[allow-none]
integrity	integrity algorithm (e.g. "hmac-sha256") or NULL for no integrity support.	[allow-none]
sector_size	encryption sector size, 0 for default (512)
label	LUKS header label or NULL.	[allow-none]
subsystem	LUKS header subsystem or NULL.	[allow-none]
pbkdf	key derivation function specification or NULL for default.	[allow-none]

Returns

a new LUKS extra argument.

[transfer full]

bd_crypto_luks_pbkdf_free ()

void
bd_crypto_luks_pbkdf_free (BDCryptoLUKSPBKDF *pbkdf);

Frees pbkdf .

[skip]

bd_crypto_luks_pbkdf_copy ()

BDCryptoLUKSPBKDF *
bd_crypto_luks_pbkdf_copy (BDCryptoLUKSPBKDF *pbkdf);

Creates a new copy of pbkdf .

[skip]

bd_crypto_luks_pbkdf_new ()

BDCryptoLUKSPBKDF *
bd_crypto_luks_pbkdf_new (const gchar *type,
                          const gchar *hash,
                          guint32 max_memory_kb,
                          guint32 iterations,
                          guint32 time_ms,
                          guint32 parallel_threads);

[constructor]

Parameters

type	PBKDF algorithm.	[allow-none]
hash	hash for LUKS header or NULL for default.	[allow-none]
max_memory_kb	requested memory cost (in KiB) or 0 for default (benchmark)
iterations	requested iterations or 0 for default (benchmark)
time_ms	requested time cost or 0 for default (benchmark)
parallel_threads	requested parallel cost (threads) or 0 for default (benchmark)

Returns

a new pbkdf argument.

[transfer full]

bd_crypto_luks_format_luks2 ()

gboolean
bd_crypto_luks_format_luks2 (const gchar *device,
                             const gchar *cipher,
                             guint64 key_size,
                             const gchar *passphrase,
                             const gchar *key_file,
                             guint64 min_entropy,
                             BDCryptoLUKSVersion luks_version,
                             BDCryptoLUKSExtra *extra,
                             GError **error);

Either passhphrase or key_file has to be != NULL.

Using this function with luks_version set to BD_CRYPTO_LUKS_VERSION_LUKS1 and extra to NULL is the same as calling bd_crypto_luks_format.

Parameters

device	a device to format as LUKS
cipher	cipher specification (type-mode, e.g. "aes-xts-plain64") or `NULL` to use the default.	[allow-none]
key_size	size of the volume key in bits or 0 to use the default
passphrase	a passphrase for the new LUKS device or `NULL` if not requested.	[allow-none]
key_file	a key file for the new LUKS device or `NULL` if not requested.	[allow-none]
min_entropy	minimum random data entropy (in bits) required to format `device` as LUKS
luks_version	whether to use LUKS v1 or LUKS v2
extra	extra arguments for LUKS format creation.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the given device was successfully formatted as LUKS or not (the error ) contains the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS2-BD_CRYPTO_TECH_MODE_CREATE

bd_crypto_luks_format_luks2_blob ()

gboolean
bd_crypto_luks_format_luks2_blob (const gchar *device,
                                  const gchar *cipher,
                                  guint64 key_size,
                                  const guint8 *pass_data,
                                  gsize data_len,
                                  guint64 min_entropy,
                                  BDCryptoLUKSVersion luks_version,
                                  BDCryptoLUKSExtra *extra,
                                  GError **error);

Using this function with luks_version set to BD_CRYPTO_LUKS_VERSION_LUKS1 and extra to NULL is the same as calling bd_crypto_luks_format_blob.

Parameters

device	a device to format as LUKS
cipher	cipher specification (type-mode, e.g. "aes-xts-plain64") or `NULL` to use the default.	[allow-none]
key_size	size of the volume key in bits or 0 to use the default
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
min_entropy	minimum random data entropy (in bits) required to format `device` as LUKS
luks_version	whether to use LUKS v1 or LUKS v2
extra	extra arguments for LUKS format creation.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the given device was successfully formatted as LUKS or not (the error ) contains the error in such cases)

Tech category: BD_CRYPTO_TECH_LUKS2-BD_CRYPTO_TECH_MODE_CREATE

bd_crypto_luks_open ()

gboolean
bd_crypto_luks_open (const gchar *device,
                     const gchar *name,
                     const gchar *passphrase,
                     const gchar *key_file,
                     gboolean read_only,
                     GError **error);

Parameters

device	the device to open
name	name for the LUKS device
passphrase	passphrase to open the `device` or `NULL`.	[allow-none]
key_file	key file path to use for opening the `device` or `NULL`.	[allow-none]
read_only	whether to open as read-only or not (meaning read-write)
error	place to store error (if any).	[out]

Returns

whether the device was successfully opened or not

One of passphrase , key_file has to be != NULL.

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_luks_open_blob ()

gboolean
bd_crypto_luks_open_blob (const gchar *device,
                          const gchar *name,
                          const guint8 *pass_data,
                          gsize data_len,
                          gboolean read_only,
                          GError **error);

Parameters

device	the device to open
name	name for the LUKS device
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
read_only	whether to open as read-only or not (meaning read-write)
error	place to store error (if any).	[out]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_luks_close ()

gboolean
bd_crypto_luks_close (const gchar *luks_device,
                      GError **error);

Parameters

luks_device	LUKS device to close
error	place to store error (if any).	[out]

Returns

whether the given luks_device was successfully closed or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_luks_add_key ()

gboolean
bd_crypto_luks_add_key (const gchar *device,
                        const gchar *pass,
                        const gchar *key_file,
                        const gchar *npass,
                        const gchar *nkey_file,
                        GError **error);

Parameters

device	device to add new key to
pass	passphrase for the `device` or `NULL`.	[allow-none]
key_file	key file for the `device` or `NULL`.	[allow-none]
npass	passphrase to add to `device` or `NULL`.	[allow-none]
nkey_file	key file to add to `device` or `NULL`.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the npass or nkey_file was successfully added to device or not

One of pass , key_file has to be != NULL and the same applies to npass , nkey_file .

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_ADD_KEY

bd_crypto_luks_add_key_blob ()

gboolean
bd_crypto_luks_add_key_blob (const gchar *device,
                             const guint8 *pass_data,
                             gsize data_len,
                             const guint8 *npass_data,
                             gsize ndata_len,
                             GError **error);

Parameters

device	device to add new key to
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
npass_data	a new passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=ndata_len]
ndata_len	length of the `npass_data` buffer
error	place to store error (if any).	[out]

Returns

whether the npass_data was successfully added to device or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_ADD_KEY

bd_crypto_luks_remove_key ()

gboolean
bd_crypto_luks_remove_key (const gchar *device,
                           const gchar *pass,
                           const gchar *key_file,
                           GError **error);

Parameters

device	device to add new key to
pass	passphrase for the `device` or `NULL`.	[allow-none]
key_file	key file for the `device` or `NULL`.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the key was successfully removed or not

Either pass or key_file has to be != NULL.

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_REMOVE_KEY

bd_crypto_luks_remove_key_blob ()

gboolean
bd_crypto_luks_remove_key_blob (const gchar *device,
                                const guint8 *pass_data,
                                gsize data_len,
                                GError **error);

Parameters

device	device to add new key to
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data) to remove.	[array length=data_len]
data_len	length of the `pass_data` buffer
error	place to store error (if any).	[out]

Returns

whether the key was successfully removed or not

Either pass or key_file has to be != NULL.

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_REMOVE_KEY

bd_crypto_luks_change_key ()

gboolean
bd_crypto_luks_change_key (const gchar *device,
                           const gchar *pass,
                           const gchar *npass,
                           GError **error);

Parameters

device	device to change key of
pass	old passphrase
npass	new passphrase
error	place to store error (if any).	[out]

Returns

whether the key was successfully changed or not

No support for changing key files (yet).

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_ADD_KEY&BD_CRYPTO_TECH_MODE_REMOVE_KEY

bd_crypto_luks_change_key_blob ()

gboolean
bd_crypto_luks_change_key_blob (const gchar *device,
                                const guint8 *pass_data,
                                gsize data_len,
                                const guint8 *npass_data,
                                gsize ndata_len,
                                GError **error);

Parameters

device	device to change key of
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
npass_data	a new passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=ndata_len]
ndata_len	length of the `npass_data` buffer
error	place to store error (if any).	[out]

Returns

whether the key was successfully changed or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_ADD_KEY&BD_CRYPTO_TECH_MODE_REMOVE_KEY

bd_crypto_luks_resize ()

gboolean
bd_crypto_luks_resize (const gchar *device,
                       guint64 size,
                       GError **error);

You need to specify passphrase when resizing LUKS 2 devices that don't have verified key loaded in kernel. If you don't specify a passphrase, resize will fail with BD_CRYPTO_ERROR_RESIZE_PERM. Use bd_crypto_luks_resize_luks2 or bd_crypto_luks_resize_luks2_blob for these devices.

Parameters

luks_device	opened LUKS device to resize
size	requested size in sectors or 0 to adapt to the backing device
error	place to store error (if any).	[out]

Returns

whether the luks_device was successfully resized or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_RESIZE

bd_crypto_luks_resize_luks2 ()

gboolean
bd_crypto_luks_resize_luks2 (const gchar *luks_device,
                             guint64 size,
                             const gchar *passphrase,
                             const gchar *key_file,
                             GError **error);

Parameters

luks_device	opened LUKS device to resize
passphrase	passphrase to resize the `luks_device` or `NULL`.	[allow-none]
key_file	key file path to use for resizinh the `luks_device` or `NULL`.	[allow-none]
size	requested size in sectors or 0 to adapt to the backing device
error	place to store error (if any).	[out]

Returns

whether the luks_device was successfully resized or not

You need to specify either passphrase or keyfile for LUKS 2 devices that don't have verified key loaded in kernel. For LUKS 1 devices you can set both passphrase and keyfile to NULL to achieve the same as calling bd_crypto_luks_resize.

Tech category: BD_CRYPTO_TECH_LUKS2-BD_CRYPTO_TECH_MODE_RESIZE

bd_crypto_luks_resize_luks2_blob ()

gboolean
bd_crypto_luks_resize_luks2_blob (const gchar *luks_device,
                                  guint64 size,
                                  const guint8 *pass_data,
                                  gsize data_len,
                                  GError **error);

Parameters

luks_device	opened LUKS device to resize
pass_data	a passphrase for the new LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
size	requested size in sectors or 0 to adapt to the backing device
error	place to store error (if any).	[out]

Returns

whether the luks_device was successfully resized or not

You need to specify pass_data for LUKS 2 devices that don't have verified key loaded in kernel.

Tech category: BD_CRYPTO_TECH_LUKS2-BD_CRYPTO_TECH_MODE_RESIZE

bd_crypto_luks_suspend ()

gboolean
bd_crypto_luks_suspend (const gchar *luks_device,
                        GError **error);

Parameters

luks_device	LUKS device to suspend
error	place to store error (if any).	[out]

Returns

whether the given luks_device was successfully suspended or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME

bd_crypto_luks_resume_blob ()

gboolean
bd_crypto_luks_resume_blob (const gchar *luks_device,
                            const guint8 *pass_data,
                            gsize data_len,
                            GError **error);

Parameters

luks_device	LUKS device to resume
pass_data	a passphrase for the LUKS device (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
error	place to store error (if any).	[out]

Returns

whether the given luks_device was successfully resumed or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME

bd_crypto_luks_resume ()

gboolean
bd_crypto_luks_resume (const gchar *luks_device,
                       const gchar *passphrase,
                       const gchar *key_file,
                       GError **error);

Parameters

luks_device	LUKS device to resume
passphrase	passphrase to resume the `device` or `NULL`.	[allow-none]
key_file	key file path to use for resuming the `device` or `NULL`.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the given luks_device was successfully resumed or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME

bd_crypto_luks_kill_slot ()

gboolean
bd_crypto_luks_kill_slot (const gchar *device,
                          gint slot,
                          GError **error);

Note: This can destroy last remaining keyslot without confirmation making the LUKS device permanently inaccessible.

Parameters

device	device to kill slot on
slot	keyslot to destroy
error	place to store error (if any).	[out]

Returns

whether the given slot was successfully destroyed or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_REMOVE_KEY

bd_crypto_luks_header_backup ()

gboolean
bd_crypto_luks_header_backup (const gchar *device,
                              const gchar *backup_file,
                              GError **error);

Parameters

device	device to backup the LUKS header
backup_file	file to save the header backup to
error	place to store error (if any).	[out]

Returns

whether the given backup of device was successfully written to backup_file or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_BACKUP_RESTORE

bd_crypto_luks_header_restore ()

gboolean
bd_crypto_luks_header_restore (const gchar *device,
                               const gchar *backup_file,
                               GError **error);

Parameters

device	device to restore the LUKS header to
backup_file	existing file with a LUKS header backup
error	place to store error (if any).	[out]

Returns

whether the given device LUKS header was successfully restored from backup_file

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_BACKUP_RESTORE

bd_crypto_luks_info_free ()

void
bd_crypto_luks_info_free (BDCryptoLUKSInfo *info);

Frees info .

[skip]

bd_crypto_luks_info_copy ()

BDCryptoLUKSInfo *
bd_crypto_luks_info_copy (BDCryptoLUKSInfo *info);

Creates a new copy of info .

[skip]

bd_crypto_luks_info ()

BDCryptoLUKSInfo *
bd_crypto_luks_info (const gchar *luks_device,
                     GError **error);

Parameters

luks_device	a device to get information about
error	place to store error (if any).	[out]

Returns

information about the luks_device or NULL in case of error

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_integrity_info_free ()

void
bd_crypto_integrity_info_free (BDCryptoIntegrityInfo *info);

Frees info .

[skip]

bd_crypto_integrity_info_copy ()

BDCryptoIntegrityInfo *
bd_crypto_integrity_info_copy (BDCryptoIntegrityInfo *info);

bd_crypto_integrity_info ()

BDCryptoIntegrityInfo *
bd_crypto_integrity_info (const gchar *device,
                          GError **error);

Parameters

device	a device to get information about
error	place to store error (if any).	[out]

Returns

information about the device or NULL in case of error

Tech category: BD_CRYPTO_TECH_INTEGRITY-BD_CRYPTO_TECH_MODE_QUERY

bd_crypto_tc_open ()

gboolean
bd_crypto_tc_open (const gchar *device,
                   const gchar *name,
                   const guint8 *pass_data,
                   gsize data_len,
                   gboolean read_only,
                   GError **error);

Parameters

device	the device to open
name	name for the TrueCrypt/VeraCrypt device
pass_data	a passphrase for the TrueCrypt/VeraCrypt volume (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
read_only	whether to open as read-only or not (meaning read-write)
error	place to store error (if any).	[out]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_TRUECRYPT-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_tc_open_full ()

gboolean
bd_crypto_tc_open_full (const gchar *device,
                        const gchar *name,
                        const guint8 *pass_data,
                        gsize data_len,
                        const gchar **keyfiles,
                        gboolean hidden,
                        gboolean system,
                        gboolean veracrypt,
                        guint32 veracrypt_pim,
                        gboolean read_only,
                        GError **error);

Parameters

device	the device to open
name	name for the TrueCrypt/VeraCrypt device
pass_data	a passphrase for the TrueCrypt/VeraCrypt volume (may contain arbitrary binary data).	[array length=data_len]
data_len	length of the `pass_data` buffer
read_only	whether to open as read-only or not (meaning read-write)
keyfiles	paths to the keyfiles for the TrueCrypt/VeraCrypt volume.	[allow-none][array zero-terminated=1]
hidden	whether a hidden volume inside the volume should be opened
system	whether to try opening as an encrypted system (with boot loader)
veracrypt	whether to try VeraCrypt modes (TrueCrypt modes are tried anyway)
veracrypt_pim	VeraCrypt PIM value
error	place to store error (if any).	[out]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_TRUECRYPT-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_tc_close ()

gboolean
bd_crypto_tc_close (const gchar *tc_device,
                    GError **error);

Parameters

tc_device	TrueCrypt/VeraCrypt device to close
error	place to store error (if any).	[out]

Returns

whether the given tc_device was successfully closed or not

Tech category: BD_CRYPTO_TECH_TRUECRYPT-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

bd_crypto_escrow_device ()

gboolean
bd_crypto_escrow_device (const gchar *device,
                         const gchar *passphrase,
                         const gchar *cert_data,
                         const gchar *directory,
                         const gchar *backup_passphrase,
                         GError **error);

Parameters

device	path of the device to create escrow data for
passphrase	passphrase used for the device
cert_data	certificate data to use for escrow.	[array zero-terminated=1][element-type gchar]
directory	directory to put escrow data into
backup_passphrase	backup passphrase for the device or `NULL`.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the ecrow data was successfully created for device or not

Tech category: BD_CRYPTO_TECH_ESCROW-BD_CRYPTO_TECH_MODE_CREATE

bd_crypto_is_tech_avail ()

gboolean
bd_crypto_is_tech_avail (BDCryptoTech tech,
                         guint64 mode,
                         GError **error);

Parameters

tech	the queried tech
mode	a bit mask of queried modes of operation (BDCryptoTechMode) for `tech`
error	place to store error (details about why the `tech` -`mode` combination is not available).	[out]

Returns

whether the tech -mode combination is available -- supported by the plugin implementation and having all the runtime dependencies available

Types and Values

BD_CRYPTO_LUKS_METADATA_SIZE

#define             BD_CRYPTO_LUKS_METADATA_SIZE

BD_CRYPTO_ERROR

#define             BD_CRYPTO_ERROR

enum BDCryptoError

Members

BD_CRYPTO_ERROR_DEVICE
BD_CRYPTO_ERROR_STATE
BD_CRYPTO_ERROR_INVALID_SPEC
BD_CRYPTO_ERROR_FORMAT_FAILED
BD_CRYPTO_ERROR_RESIZE_FAILED
BD_CRYPTO_ERROR_RESIZE_PERM
BD_CRYPTO_ERROR_ADD_KEY
BD_CRYPTO_ERROR_REMOVE_KEY
BD_CRYPTO_ERROR_NO_KEY
BD_CRYPTO_ERROR_KEY_SLOT
BD_CRYPTO_ERROR_NSS_INIT_FAILED
BD_CRYPTO_ERROR_CERT_DECODE
BD_CRYPTO_ERROR_ESCROW_FAILED
BD_CRYPTO_ERROR_INVALID_PARAMS
BD_CRYPTO_ERROR_TECH_UNAVAIL

BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET

#define BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz./"

BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH

#define BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH 20

DEFAULT_LUKS_KEYSIZE_BITS

#define DEFAULT_LUKS_KEYSIZE_BITS 256

DEFAULT_LUKS_CIPHER

#define DEFAULT_LUKS_CIPHER "aes-xts-plain64"

BDCryptoLUKSExtra

typedef struct {
    guint64 data_alignment;
    gchar *data_device;
    gchar *integrity;
    guint64 sector_size;
    gchar *label;
    gchar *subsystem;
    BDCryptoLUKSPBKDF *pbkdf;
} BDCryptoLUKSExtra;

Members

guint64 `data_alignment`;	data alignment in sectors, 0 for default/auto detection
gchar *`data_device`;	detached encrypted data device or NULL
gchar *`integrity`;	integrity algorithm (e.g. "hmac-sha256") or NULL for no integrity support Note: this field is valid only for LUKS 2
guint64 `sector_size`;	encryption sector size, 0 for default (512) Note: this field is valid only for LUKS 2
gchar *`label`;	LUKS header label or NULL Note: this field is valid only for LUKS 2
gchar *`subsystem`;
BDCryptoLUKSPBKDF *`pbkdf`;	key derivation function specification or NULL for default Note: this field is valid only for LUKS 2

BDCryptoLUKSPBKDF

typedef struct {
    gchar *type;
    gchar *hash;
    guint32 max_memory_kb;
    guint32 iterations;
    guint32 time_ms;
    guint32 parallel_threads;
} BDCryptoLUKSPBKDF;

Members

gchar *`type`;	PBKDF algorithm
gchar *`hash`;	hash for LUKS header or NULL
guint32 `max_memory_kb`;	requested memory cost (in KiB) or 0 for default (benchmark)
guint32 `iterations`;	requested iterations or 0 for default (benchmark)
guint32 `time_ms`;	requested time cost or 0 for default (benchmark)
guint32 `parallel_threads`;	requested parallel cost (threads) or 0 for default (benchmark)

enum BDCryptoLUKSVersion

Members

BD_CRYPTO_LUKS_VERSION_LUKS1
BD_CRYPTO_LUKS_VERSION_LUKS2

BDCryptoLUKSInfo

typedef struct {
    BDCryptoLUKSVersion version;
    gchar *cipher;
    gchar *mode;
    gchar *uuid;
    gchar *backing_device;
    gint64 sector_size;
} BDCryptoLUKSInfo;

Members

BDCryptoLUKSVersion `version`;	LUKS version
gchar *`cipher`;	used cipher (e.g. "aes")
gchar *`mode`;	used cipher mode (e.g. "xts-plain")
gchar *`uuid`;	UUID of the LUKS device
gchar *`backing_device`;	name of the underlying block device
gint64 `sector_size`;	size (in bytes) of encryption sector Note: sector size is valid only for LUKS 2

BDCryptoIntegrityInfo

typedef struct {
    gchar *algorithm;
    guint32 key_size;
    guint32 sector_size;
    guint32 tag_size;
    guint32 interleave_sectors;
    guint64 journal_size;
    gchar *journal_crypt;
    gchar *journal_integrity;
} BDCryptoIntegrityInfo;

Members

gchar *`algorithm`;	integrity algorithm
guint32 `key_size`;	integrity key size in bytes
guint32 `sector_size`;	sector size in bytes
guint32 `tag_size`;	tag size per-sector in bytes
guint32 `interleave_sectors`;	number of interleave sectors
guint64 `journal_size`;	size of journal in bytes
gchar *`journal_crypt`;	journal encryption algorithm
gchar *`journal_integrity`;	journal integrity algorithm

enum BDCryptoTech

Members

BD_CRYPTO_TECH_LUKS
BD_CRYPTO_TECH_LUKS2
BD_CRYPTO_TECH_TRUECRYPT
BD_CRYPTO_TECH_ESCROW
BD_CRYPTO_TECH_INTEGRITY

enum BDCryptoTechMode

Members

BD_CRYPTO_TECH_MODE_CREATE
BD_CRYPTO_TECH_MODE_OPEN_CLOSE
BD_CRYPTO_TECH_MODE_QUERY
BD_CRYPTO_TECH_MODE_ADD_KEY
BD_CRYPTO_TECH_MODE_REMOVE_KEY
BD_CRYPTO_TECH_MODE_RESIZE
BD_CRYPTO_TECH_MODE_SUSPEND_RESUME
BD_CRYPTO_TECH_MODE_BACKUP_RESTORE