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_bitlk_open ()
gboolean | bd_crypto_bitlk_close ()
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);

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

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

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

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

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

    gboolean
    bd_crypto_bitlk_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 BITLK device |
pass_data | a passphrase for the BITLK 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_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]

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

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