Crypto

Crypto — plugin for operations with encrypted devices

Functions

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 ()
const gchar * bd_crypto_luks_status ()
gboolean bd_crypto_luks_format ()
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 ()
void bd_crypto_keyslot_context_free ()
BDCryptoKeyslotContext * bd_crypto_keyslot_context_copy ()
BDCryptoKeyslotContext * bd_crypto_keyslot_context_new_passphrase ()
BDCryptoKeyslotContext * bd_crypto_keyslot_context_new_keyfile ()
BDCryptoKeyslotContext * bd_crypto_keyslot_context_new_keyring ()
BDCryptoKeyslotContext * bd_crypto_keyslot_context_new_volume_key ()
gboolean bd_crypto_luks_open ()
gboolean bd_crypto_luks_close ()
gboolean bd_crypto_luks_add_key ()
gboolean bd_crypto_luks_remove_key ()
gboolean bd_crypto_luks_change_key ()
gboolean bd_crypto_luks_resize ()
gboolean bd_crypto_luks_suspend ()
gboolean bd_crypto_luks_resume ()
gboolean bd_crypto_luks_kill_slot ()
gboolean bd_crypto_luks_header_backup ()
gboolean bd_crypto_luks_header_restore ()
gboolean bd_crypto_luks_set_label ()
gboolean bd_crypto_luks_set_uuid ()
gboolean bd_crypto_luks_convert ()
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 ()
BDCryptoIntegrityExtra * bd_crypto_integrity_extra_copy ()
void bd_crypto_integrity_extra_free ()
BDCryptoIntegrityExtra * bd_crypto_integrity_extra_new ()
gboolean bd_crypto_integrity_format ()
gboolean bd_crypto_integrity_open ()
gboolean bd_crypto_integrity_close ()
void bd_crypto_luks_token_info_free ()
BDCryptoLUKSTokenInfo * bd_crypto_luks_token_info_copy ()
BDCryptoLUKSTokenInfo ** bd_crypto_luks_token_info ()
gboolean bd_crypto_keyring_add_key ()
gboolean bd_crypto_tc_open ()
gboolean bd_crypto_tc_close ()
gboolean bd_crypto_escrow_device ()
BDCryptoBITLKInfo * bd_crypto_bitlk_info ()
BDCryptoBITLKInfo * bd_crypto_bitlk_info_copy ()
void bd_crypto_bitlk_info_free ()
gboolean bd_crypto_bitlk_open ()
gboolean bd_crypto_bitlk_close ()
gboolean bd_crypto_fvault2_open ()
gboolean bd_crypto_fvault2_close ()
gboolean bd_crypto_opal_is_supported ()
gboolean bd_crypto_opal_wipe_device ()
gboolean bd_crypto_opal_format ()
gboolean bd_crypto_opal_reset_device ()
gboolean bd_crypto_is_tech_avail ()

Types and Values

Includes

#include <crypto.h>

Description

A plugin for operations with encrypted devices. Currently LUKS, Integrity, TrueCrypt/VeraCrypt, BitLocker and FileVault2 devices are supported. See BDCryptoTech for full list of supported technologies.

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_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][optional]

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][optional]

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][optional]

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_status ()

const 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][optional]

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,
                       BDCryptoKeyslotContext *context,
                       guint64 min_entropy,
                       BDCryptoLUKSVersion luks_version,
                       BDCryptoLUKSExtra *extra,
                       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).

Supported context types for this function: passphrase, key file

Parameters

device

a device to format as LUKS

 

cipher

cipher specification (type-mode, e.g. "aes-xts-plain64") or NULL to use the default.

[nullable]

key_size

size of the volume key in bits or 0 to use the default

 

context

key slot context (passphrase/keyfile/token...) for this LUKS device

 

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.

[nullable]

error

place to store error (if any).

[out][optional]

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]

Parameters

extra

BDCryptoLUKSExtra to free.

[nullable]

bd_crypto_luks_extra_copy ()

BDCryptoLUKSExtra *
bd_crypto_luks_extra_copy (BDCryptoLUKSExtra *extra);

Creates a new copy of extra .

[skip]

Parameters

extra

BDCryptoLUKSExtra to copy.

[nullable]

bd_crypto_luks_extra_new ()

BDCryptoLUKSExtra *
bd_crypto_luks_extra_new (guint64 data_alignment,
                          const gchar *data_device,
                          const gchar *integrity,
                          guint32 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.

[nullable]

integrity

integrity algorithm (e.g. "hmac-sha256") or NULL for no integrity support.

[nullable]

sector_size

encryption sector size, 0 for default (512)

 

label

LUKS header label or NULL.

[nullable]

subsystem

LUKS header subsystem or NULL.

[nullable]

pbkdf

key derivation function specification or NULL for default.

[nullable]

Returns

a new LUKS extra argument.

[transfer full]


bd_crypto_luks_pbkdf_free ()

void
bd_crypto_luks_pbkdf_free (BDCryptoLUKSPBKDF *pbkdf);

Frees pbkdf .

[skip]

Parameters

pbkdf

BDCryptoLUKSPBKDF to free.

[nullable]

bd_crypto_luks_pbkdf_copy ()

BDCryptoLUKSPBKDF *
bd_crypto_luks_pbkdf_copy (BDCryptoLUKSPBKDF *pbkdf);

Creates a new copy of pbkdf .

[skip]

Parameters

pbkdf

BDCryptoLUKSPBKDF to copy.

[nullable]

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.

[nullable]

hash

hash for LUKS header or NULL for default.

[nullable]

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_keyslot_context_free ()

void
bd_crypto_keyslot_context_free (BDCryptoKeyslotContext *context);

Frees context .

[skip]

Parameters

context

BDCryptoKeyslotContext to free.

[nullable]

bd_crypto_keyslot_context_copy ()

BDCryptoKeyslotContext *
bd_crypto_keyslot_context_copy (BDCryptoKeyslotContext *context);

Creates a new copy of context .

[skip]

Parameters

context

BDCryptoKeyslotContext to copy.

[nullable]

bd_crypto_keyslot_context_new_passphrase ()

BDCryptoKeyslotContext *
bd_crypto_keyslot_context_new_passphrase
                               (const guint8 *pass_data,
                                gsize data_len,
                                GError **error);

Returns (transfer full): new BDCryptoKeyslotContext initialized by passphrase or NULL in case of error

Tech category: always available

Parameters

pass_data

a passphrase for the new context (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][optional]

bd_crypto_keyslot_context_new_keyfile ()

BDCryptoKeyslotContext *
bd_crypto_keyslot_context_new_keyfile (const gchar *keyfile,
                                       guint64 keyfile_offset,
                                       gsize key_size,
                                       GError **error);

Returns (transfer full): new BDCryptoKeyslotContext initialized by key file or NULL in case of error

Tech category: always available

Parameters

keyfile

a key file for the new context

 

keyfile_offset

number of bytes to read from keyfile or 0 for unlimited

 

key_size

number of bytes to skip at start of keyfile

 

error

place to store error (if any).

[out][optional]

bd_crypto_keyslot_context_new_keyring ()

BDCryptoKeyslotContext *
bd_crypto_keyslot_context_new_keyring (const gchar *key_desc,
                                       GError **error);

Returns (transfer full): new BDCryptoKeyslotContext initialized by key_desc or NULL in case of error

Note: Keyslot passphrase must be stored in 'user' key type and the key has to be reachable by process context on behalf of which this function is called.

Tech category: always available

Parameters

key_desc

kernel keyring key description

 

error

place to store error (if any).

[out][optional]

bd_crypto_keyslot_context_new_volume_key ()

BDCryptoKeyslotContext *
bd_crypto_keyslot_context_new_volume_key
                               (const guint8 *volume_key,
                                gsize volume_key_size,
                                GError **error);

Returns (transfer full): new BDCryptoKeyslotContext initialized by volume key or NULL in case of error

Tech category: always available

Parameters

volume_key

a volume key for the new context (may contain arbitrary binary data).

[array length=volume_key_size]

volume_key_size

length of the volume_key_size buffer

 

error

place to store error (if any).

[out][optional]

bd_crypto_luks_open ()

gboolean
bd_crypto_luks_open (const gchar *device,
                     const gchar *name,
                     BDCryptoKeyslotContext *context,
                     gboolean read_only,
                     GError **error);

Supported context types for this function: passphrase, key file, keyring

Parameters

device

the device to open

 

name

name for the LUKS device

 

context

key slot context (passphrase/keyfile/token...) to open this LUKS device

 

read_only

whether to open as read-only or not (meaning read-write)

 

error

place to store error (if any).

[out][optional]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_OPEN_CLOSE

Example of using bd_crypto_luks_open with BDCryptoKeyslotContext:

1
2
3
BDCryptoKeyslotContext *context = NULL;
context = bd_crypto_keyslot_context_new_passphrase ("passphrase", 10, NULL);
bd_crypto_luks_open ("/dev/vda1", "luks-device", context, FALSE, NULL);


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][optional]

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,
                        BDCryptoKeyslotContext *context,
                        BDCryptoKeyslotContext *ncontext,
                        GError **error);

Supported context types for this function: passphrase, key file

Parameters

device

device to add new key to

 

context

key slot context (passphrase/keyfile/token...) to for this LUKS device

 

ncontext

new key slot context (passphrase/keyfile/token...) to add to this LUKS device

 

error

place to store error (if any).

[out][optional]

Returns

whether the ncontext 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,
                           BDCryptoKeyslotContext *context,
                           GError **error);

Supported context types for this function: passphrase, key file

Parameters

device

device to add new key to

 

context

key slot context (passphrase/keyfile/token...) to remove from this LUKS device

 

error

place to store error (if any).

[out][optional]

Returns

whether the key was successfully removed or not

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,
                           BDCryptoKeyslotContext *context,
                           BDCryptoKeyslotContext *ncontext,
                           GError **error);

Supported context types for this function: passphrase, key file

Parameters

device

device to change key of

 

context

key slot context (passphrase/keyfile/token...) for this LUKS device

 

ncontext

new key slot context (passphrase/keyfile/token...) to add to this LUKS device

 

error

place to store error (if any).

[out][optional]

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 *luks_device,
                       guint64 size,
                       BDCryptoKeyslotContext *context,
                       GError **error);

Supported context types for this function: passphrase, key file

Parameters

luks_device

opened LUKS device to resize

 

size

requested size in sectors or 0 to adapt to the backing device

 

context

key slot context (passphrase/keyfile/token...) for this LUKS device .

[nullable]

error

place to store error (if any).

[out][optional]

Returns

whether the luks_device was successfully resized or not

You need to specify either context for LUKS 2 devices that don't have verified key loaded in kernel. For LUKS 1 devices you can set context NULL.

Tech category: BD_CRYPTO_TECH_LUKS-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][optional]

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 ()

gboolean
bd_crypto_luks_resume (const gchar *luks_device,
                       BDCryptoKeyslotContext *context,
                       GError **error);

Supported context types for this function: passphrase, key file

Parameters

luks_device

LUKS device to resume

 

context

key slot context (passphrase/keyfile/token...) for luks_device .

[nullable]

error

place to store error (if any).

[out][optional]

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][optional]

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][optional]

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][optional]

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_set_label ()

gboolean
bd_crypto_luks_set_label (const gchar *device,
                          const gchar *label,
                          const gchar *subsystem,
                          GError **error);

Parameters

device

device to set label on

 

label

label to set.

[nullable]

subsystem

subsystem to set.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

whether the given label and subsystem were successfully set or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_MODIFY


bd_crypto_luks_set_uuid ()

gboolean
bd_crypto_luks_set_uuid (const gchar *device,
                         const gchar *uuid,
                         GError **error);

Parameters

device

device to set UUID on

 

uuid

UUID to set or NULL to generate a new one.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

whether the given uuid was successfully set or not

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_MODIFY


bd_crypto_luks_convert ()

gboolean
bd_crypto_luks_convert (const gchar *device,
                        BDCryptoLUKSVersion target_version,
                        GError **error);

Parameters

device

a LUKS device to convert to a different version of LUKS

 

target_version

the LUKS version to convert to

 

error

place to store error (if any).

[out][optional]

Returns

whether the device was converted to target_version . False, if the device is already in the target_version format.

Warning: LUKS header loss is possible. See bd_crypto_luks_header_backup() and bd_crypto_luks_header_restore()

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_MODIFY


bd_crypto_luks_info_free ()

void
bd_crypto_luks_info_free (BDCryptoLUKSInfo *info);

Frees info .

[skip]

Parameters

info

BDCryptoLUKSInfo to free.

[nullable]

bd_crypto_luks_info_copy ()

BDCryptoLUKSInfo *
bd_crypto_luks_info_copy (BDCryptoLUKSInfo *info);

Creates a new copy of info .

[skip]

Parameters

info

BDCryptoLUKSInfo to copy.

[nullable]

bd_crypto_luks_info ()

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

Parameters

device

a device to get information about

 

error

place to store error (if any).

[out][optional]

Returns

information about the device or NULL in case of error

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY.

[transfer full]


bd_crypto_integrity_info_free ()

void
bd_crypto_integrity_info_free (BDCryptoIntegrityInfo *info);

Frees info .

[skip]

Parameters

info

BDCryptoIntegrityInfo to free.

[nullable]

bd_crypto_integrity_info_copy ()

BDCryptoIntegrityInfo *
bd_crypto_integrity_info_copy (BDCryptoIntegrityInfo *info);

Creates a new copy of info .

[skip]

Parameters

info

BDCryptoIntegrityInfo to copy.

[nullable]

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][optional]

Returns

information about the device or NULL in case of error

Tech category: BD_CRYPTO_TECH_INTEGRITY-BD_CRYPTO_TECH_MODE_QUERY.

[transfer full]


bd_crypto_integrity_extra_copy ()

BDCryptoIntegrityExtra *
bd_crypto_integrity_extra_copy (BDCryptoIntegrityExtra *extra);

Creates a new copy of extra .

[skip]

Parameters

extra

BDCryptoIntegrityExtra to copy.

[nullable]

bd_crypto_integrity_extra_free ()

void
bd_crypto_integrity_extra_free (BDCryptoIntegrityExtra *extra);

Frees extra .

[skip]

Parameters

extra

BDCryptoIntegrityExtra to free.

[nullable]

bd_crypto_integrity_extra_new ()

BDCryptoIntegrityExtra *
bd_crypto_integrity_extra_new (guint32 sector_size,
                               guint64 journal_size,
                               guint journal_watermark,
                               guint journal_commit_time,
                               guint64 interleave_sectors,
                               guint64 tag_size,
                               guint64 buffer_sectors);

[constructor]

Parameters

sector_size

integrity sector size, 0 for default (512)

 

journal_size

size of journal in bytes

 

journal_watermark

journal flush watermark in percents; in bitmap mode sectors-per-bit

 

journal_commit_time

journal commit time (or bitmap flush time) in ms

 

interleave_sectors

number of interleave sectors (power of two)

 

tag_size

tag size per-sector in bytes

 

buffer_sectors

number of sectors in one buffer

 

Returns

a new Integrity extra argument.

[transfer full]


bd_crypto_integrity_format ()

gboolean
bd_crypto_integrity_format (const gchar *device,
                            const gchar *algorithm,
                            gboolean wipe,
                            BDCryptoKeyslotContext *context,
                            BDCryptoIntegrityExtra *extra,
                            GError **error);

Formats the given device as integrity according to the other parameters given.

Supported context types for this function: volume key

Parameters

device

a device to format as integrity

 

algorithm

integrity algorithm specification (e.g. "crc32c" or "sha256")

 

wipe

whether to wipe the device after format; a device that is not initially wiped will contain invalid checksums

 

context

key slot context (passphrase/keyfile/token...) for this device.

[nullable]

extra

extra arguments for integrity format creation.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

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

Tech category: BD_CRYPTO_TECH_INTEGRITY-BD_CRYPTO_TECH_MODE_CREATE


bd_crypto_integrity_open ()

gboolean
bd_crypto_integrity_open (const gchar *device,
                          const gchar *name,
                          const gchar *algorithm,
                          BDCryptoKeyslotContext *context,
                          BDCryptoIntegrityOpenFlags flags,
                          BDCryptoIntegrityExtra *extra,
                          GError **error);

Supported context types for this function: volume key

Parameters

device

integrity device to open

 

name

name for the opened device

 

algorithm

integrity algorithm specification (e.g. "crc32c" or "sha256")

 

context

key slot context (passphrase/keyfile/token...) for this device.

[nullable]

flags

flags for the integrity device activation

 

extra

extra arguments for integrity open.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_INTEGRITY-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_integrity_close ()

gboolean
bd_crypto_integrity_close (const gchar *integrity_device,
                           GError **error);

Parameters

integrity_device

integrity device to close

 

error

place to store error (if any).

[out][optional]

Returns

whether the given integrity_device was successfully closed or not

Tech category: BD_CRYPTO_TECH_INTEGRITY-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_luks_token_info_free ()

void
bd_crypto_luks_token_info_free (BDCryptoLUKSTokenInfo *info);

Frees info .

[skip]

Parameters

info

BDCryptoLUKSTokenInfo to free.

[nullable]

bd_crypto_luks_token_info_copy ()

BDCryptoLUKSTokenInfo *
bd_crypto_luks_token_info_copy (BDCryptoLUKSTokenInfo *info);

Creates a new copy of info .

[skip]

Parameters

info

BDCryptoLUKSTokenInfo to copy.

[nullable]

bd_crypto_luks_token_info ()

BDCryptoLUKSTokenInfo **
bd_crypto_luks_token_info (const gchar *device,
                           GError **error);

Parameters

device

a device to get LUKS2 token information about

 

error

place to store error (if any).

[out][optional]

Returns

information about tokens on device

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_QUERY.

[array zero-terminated=1][transfer full]


bd_crypto_keyring_add_key ()

gboolean
bd_crypto_keyring_add_key (const gchar *key_desc,
                           const guint8 *key_data,
                           gsize data_len,
                           GError **error);

Parameters

key_desc

kernel keyring key description

 

key_data

a key to add to kernel keyring (may contain arbitrary binary data).

[array length=data_len]

data_len

length of the key_data buffer

 

error

place to store error (if any) *.

[out][optional]

Returns

whether the given key was successfully saved to kernel keyring or not

Tech category: BD_CRYPTO_TECH_KEYRING-BD_CRYPTO_TECH_MODE_ADD_KEY


bd_crypto_tc_open ()

gboolean
bd_crypto_tc_open (const gchar *device,
                   const gchar *name,
                   BDCryptoKeyslotContext *context,
                   const gchar **keyfiles,
                   gboolean hidden,
                   gboolean system,
                   gboolean veracrypt,
                   guint32 veracrypt_pim,
                   gboolean read_only,
                   GError **error);

Supported context types for this function: passphrase

Parameters

device

the device to open

 

name

name for the TrueCrypt/VeraCrypt device

 

context

passphrase key slot context for this TrueCrypt/VeraCrypt volume.

[nullable]

read_only

whether to open as read-only or not (meaning read-write)

 

keyfiles

paths to the keyfiles for the TrueCrypt/VeraCrypt volume.

[nullable][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 (only used if veracrypt is TRUE)

 

error

place to store error (if any).

[out][optional]

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][optional]

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.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

whether the escrow data was successfully created for device or not

Tech category: BD_CRYPTO_TECH_ESCROW-BD_CRYPTO_TECH_MODE_CREATE


bd_crypto_bitlk_info ()

BDCryptoBITLKInfo *
bd_crypto_bitlk_info (const gchar *device,
                      GError **error);

Returns (transfer full): information about the device or NULL in case of error

Tech category: BD_CRYPTO_TECH_BITLK-BD_CRYPTO_TECH_MODE_QUERY

Parameters

device

a device to get information about

 

error

place to store error (if any).

[out][optional]

bd_crypto_bitlk_info_copy ()

BDCryptoBITLKInfo *
bd_crypto_bitlk_info_copy (BDCryptoBITLKInfo *info);

Creates a new copy of info .

[skip]

Parameters

info

BDCryptoBITLKInfo to copy.

[nullable]

bd_crypto_bitlk_info_free ()

void
bd_crypto_bitlk_info_free (BDCryptoBITLKInfo *info);

Frees info .

[skip]

Parameters

info

BDCryptoBITLKInfo to free.

[nullable]

bd_crypto_bitlk_open ()

gboolean
bd_crypto_bitlk_open (const gchar *device,
                      const gchar *name,
                      BDCryptoKeyslotContext *context,
                      gboolean read_only,
                      GError **error);

Supported context types for this function: passphrase, key file

Parameters

device

the device to open

 

name

name for the BITLK device

 

context

key slot context (passphrase/keyfile/token...) for this BITLK device

 

read_only

whether to open as read-only or not (meaning read-write)

 

error

place to store error (if any).

[out][optional]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_BITLK-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_bitlk_close ()

gboolean
bd_crypto_bitlk_close (const gchar *bitlk_device,
                       GError **error);

Parameters

bitlk_device

BITLK device to close

 

error

place to store error (if any).

[out][optional]

Returns

whether the given bitlk_device was successfully closed or not

Tech category: BD_CRYPTO_TECH_BITLK-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_fvault2_open ()

gboolean
bd_crypto_fvault2_open (const gchar *device,
                        const gchar *name,
                        BDCryptoKeyslotContext *context,
                        gboolean read_only,
                        GError **error);

Supported context types for this function: passphrase, key file

Parameters

device

the device to open

 

name

name for the FVAULT2 device

 

context

key slot context (passphrase/keyfile/token...) for this FVAULT2 volume

 

read_only

whether to open as read-only or not (meaning read-write)

 

error

place to store error (if any).

[out][optional]

Returns

whether the device was successfully opened or not

Tech category: BD_CRYPTO_TECH_FVAULT2-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_fvault2_close ()

gboolean
bd_crypto_fvault2_close (const gchar *fvault2_device,
                         GError **error);

Parameters

fvault2_device

FVAULT2 device to close

 

error

place to store error (if any).

[out][optional]

Returns

whether the given fvault2_device was successfully closed or not

Tech category: BD_CRYPTO_TECH_FVAULT2-BD_CRYPTO_TECH_MODE_OPEN_CLOSE


bd_crypto_opal_is_supported ()

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

Parameters

device

device to check for OPAL support

 

error

place to store error (if any).

[out][optional]

Returns

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

Tech category: BD_CRYPTO_TECH_SED_OPAL-BD_CRYPTO_TECH_MODE_QUERY


bd_crypto_opal_wipe_device ()

gboolean
bd_crypto_opal_wipe_device (const gchar *device,
                            BDCryptoKeyslotContext *context,
                            GError **error);

Parameters

device

LUKS HW-OPAL device to wipe

 

context

OPAL admin passphrase context

 

error

place to store error (if any).

[out][optional]

Returns

whether device was successfully wiped or not.

Supported context types for this function: passphrase

Tech category: BD_CRYPTO_TECH_SED_OPAL-BD_CRYPTO_TECH_MODE_MODIFY


bd_crypto_opal_format ()

gboolean
bd_crypto_opal_format (const gchar *device,
                       const gchar *cipher,
                       guint64 key_size,
                       BDCryptoKeyslotContext *context,
                       guint64 min_entropy,
                       BDCryptoLUKSHWEncryptionType hw_encryption,
                       BDCryptoKeyslotContext *opal_context,
                       BDCryptoLUKSExtra *extra,
                       GError **error);

Formats the given device as LUKS HW-OPAL 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).

Supported context types for this function: passphrase, key file Supported opal_context types for this function: passphrase

Parameters

device

a device to format as LUKS HW-OPAL

 

cipher

cipher specification (type-mode, e.g. "aes-xts-plain64") or NULL to use the default.

[nullable]

key_size

size of the volume key in bits or 0 to use the default

 

context

key slot context (passphrase/keyfile/token...) for this LUKS device

 

min_entropy

minimum random data entropy (in bits) required to format device as LUKS

 

hw_encryption

type of hardware encryption (SW+HW or HW only)

 

opal_context

OPAL admin passphrase

 

extra

extra arguments for LUKS format creation.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

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

Tech category: BD_CRYPTO_TECH_LUKS-BD_CRYPTO_TECH_MODE_CREATE


bd_crypto_opal_reset_device ()

gboolean
bd_crypto_opal_reset_device (const gchar *device,
                             BDCryptoKeyslotContext *context,
                             GError **error);

Parameters

device

LUKS HW-OPAL device to run PSID reset on

 

context

PSID context

 

error

place to store error (if any).

[out][optional]

Returns

whether PSI reset on device was successful or not.

Warning: PSID reset will remove all data from device !

Supported context types for this function: passphrase, key file

Tech category: BD_CRYPTO_TECH_SED_OPAL-BD_CRYPTO_TECH_MODE_MODIFY


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][optional]

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_ERROR

#define             BD_CRYPTO_ERROR

enum BDCryptoError

Members

BD_CRYPTO_ERROR_TECH_UNAVAIL

   

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_KEYRING

   

BD_CRYPTO_ERROR_KEYFILE_FAILED

   

BD_CRYPTO_ERROR_INVALID_CONTEXT

   

BD_CRYPTO_ERROR_CONVERT_FAILED

   

BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET

#define BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz./"

BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH

#define BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH 20

BDCryptoLUKSExtra

typedef struct {
    guint64 data_alignment;
    gchar *data_device;
    gchar *integrity;
    guint32 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

 

guint32 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;

LUKS header subsystem or NULL Note: this field is valid only for LUKS 2

 

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

   

BDCryptoKeyslotContext

typedef struct {
    BDCryptoKeyslotContextType type;

    union {
        struct {
            guint8 *pass_data;
            gsize data_len;
        } passphrase;

        struct {
            gchar *keyfile;
            guint64 keyfile_offset;
            gsize key_size;
        } keyfile;

        struct {
            gchar *key_desc;
        } keyring;

        struct {
            guint8 *volume_key;
            gsize volume_key_size;
        } volume_key;
    } u;
} BDCryptoKeyslotContext;

BDCryptoLUKSInfo

typedef struct {
    BDCryptoLUKSVersion version;
    gchar *cipher;
    gchar *mode;
    gchar *uuid;
    gchar *backing_device;
    guint32 sector_size;
    guint64 metadata_size;
    gchar *label;
    gchar *subsystem;
    BDCryptoLUKSHWEncryptionType hw_encryption;
} 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

 

guint32 sector_size;

size (in bytes) of encryption sector Note: sector size is valid only for LUKS 2

 

guint64 metadata_size;

LUKS metadata size

 

gchar *label;

label of the LUKS device (valid only for LUKS 2)

 

gchar *subsystem;

subsystem of the LUKS device (valid only for LUKS 2)

 

BDCryptoLUKSHWEncryptionType hw_encryption;

hardware encryption type

 

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

 

BDCryptoIntegrityExtra

typedef struct {
    guint32 sector_size;
    guint64 journal_size;
    guint journal_watermark;
    guint journal_commit_time;
    guint32 interleave_sectors;
    guint32 tag_size;
    guint32 buffer_sectors;
} BDCryptoIntegrityExtra;

Members

guint32 sector_size;

integrity sector size

 

guint64 journal_size;

size of journal in bytes

 

guint journal_watermark;

journal flush watermark in percents; in bitmap mode sectors-per-bit

 

guint journal_commit_time;

journal commit time (or bitmap flush time) in ms

 

guint32 interleave_sectors;

number of interleave sectors (power of two)

 

guint32 tag_size;

tag size per-sector in bytes

 

guint32 buffer_sectors;

number of sectors in one buffer

 

enum BDCryptoIntegrityOpenFlags

Members

BD_CRYPTO_INTEGRITY_OPEN_NO_JOURNAL

   

BD_CRYPTO_INTEGRITY_OPEN_RECOVERY

   

BD_CRYPTO_INTEGRITY_OPEN_NO_JOURNAL_BITMAP

   

BD_CRYPTO_INTEGRITY_OPEN_RECALCULATE

   

BD_CRYPTO_INTEGRITY_OPEN_RECALCULATE_RESET

   

BD_CRYPTO_INTEGRITY_OPEN_ALLOW_DISCARDS

   

BDCryptoLUKSTokenInfo

typedef struct {
    guint id;
    gchar *type;
    gint keyslot;
} BDCryptoLUKSTokenInfo;

Members

guint id;

ID of the token

 

gchar *type;

type of the token

 

gint keyslot;

keyslot this token is assigned to or -1 for inactive/unassigned tokens

 

BDCryptoBITLKInfo

typedef struct {
    gchar *cipher;
    gchar *mode;
    gchar *uuid;
    gchar *backing_device;
    guint32 sector_size;
} BDCryptoBITLKInfo;

Members

gchar *cipher;

used cipher (e.g. "aes")

 

gchar *mode;

used cipher mode (e.g. "xts-plain")

 

gchar *uuid;

UUID of the BITLK device

 

gchar *backing_device;

name of the underlying block device

 

guint32 sector_size;

size (in bytes) of encryption sector

 

enum BDCryptoLUKSHWEncryptionType

Members

BD_CRYPTO_LUKS_HW_ENCRYPTION_UNKNOWN

used for unknown/unsupported hardware encryption or when error was detected when getting the information

 

BD_CRYPTO_LUKS_HW_ENCRYPTION_SW_ONLY

hardware encryption is not configured on this device

 

BD_CRYPTO_LUKS_HW_ENCRYPTION_OPAL_HW_ONLY

only OPAL hardware encryption is configured on this device

 

BD_CRYPTO_LUKS_HW_ENCRYPTION_OPAL_HW_AND_SW

both OPAL hardware encryption and software encryption (using LUKS/dm-crypt) is configured on this device

 

enum BDCryptoTech

Members

BD_CRYPTO_TECH_LUKS

   

BD_CRYPTO_TECH_TRUECRYPT

   

BD_CRYPTO_TECH_ESCROW

   

BD_CRYPTO_TECH_INTEGRITY

   

BD_CRYPTO_TECH_BITLK

   

BD_CRYPTO_TECH_KEYRING

   

BD_CRYPTO_TECH_FVAULT2

   

BD_CRYPTO_TECH_SED_OPAL

   

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

   

BD_CRYPTO_TECH_MODE_MODIFY