Crypto: libblockdev Reference Manual for libblockdev 3.1.0.

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

## Types and Values

#define | BD_CRYPTO_ERROR
enum | BDCryptoError
#define | BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET
#define | BD_CRYPTO_BACKUP_PASSPHRASE_LENGTH
| BDCryptoLUKSExtra
| BDCryptoLUKSPBKDF
enum | BDCryptoLUKSVersion
| BDCryptoKeyslotContext
| BDCryptoLUKSInfo
| BDCryptoIntegrityInfo
| BDCryptoIntegrityExtra
enum | BDCryptoIntegrityOpenFlags
| BDCryptoLUKSTokenInfo
| BDCryptoBITLKInfo
enum | BDCryptoTech
enum | BDCryptoTechMode

## 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_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_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_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;
    } 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) |

### 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 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 |  |

### 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 |  |