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 ()
gchar *	bd_crypto_luks_uuid ()
gchar *	bd_crypto_luks_status ()
gboolean	bd_crypto_luks_format ()
gboolean	bd_crypto_luks_format_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_tc_open ()
gboolean	bd_crypto_tc_close ()
gboolean	bd_crypto_escrow_device ()

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

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

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

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

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"