Crypto

Crypto — plugin for operations with encrypted devices

Functions

Types and Values

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

Returns

whether the plugin's runtime dependencies are satisfied or not

Function checking plugin's runtime dependencies.


bd_crypto_close ()

void
bd_crypto_close ();

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

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.


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)


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)


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

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


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)


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.


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


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


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 .


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


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.


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.


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


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


bd_crypto_luks_resize ()

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

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


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

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_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_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"