Crypto: libblockdev Reference Manual

Crypto

Crypto — plugin for operations with encrypted devices

Types and Values

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

#define BD_CRYPTO_LUKS_METADATA_SIZE (2 MiB)

bd_crypto_error_quark ()

GQuark
bd_crypto_error_quark (void);

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.

[transfer full]

bd_crypto_device_is_luks ()

gboolean
bd_crypto_device_is_luks (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 (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).

[transfer full]

bd_crypto_luks_status ()

gchar *
bd_crypto_luks_status (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 (gchar *device,
                       gchar *cipher,
                       guint64 key_size,
                       gchar *passphrase,
                       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).

Either passhphrase or key_file has to be != NULL.

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

gboolean
bd_crypto_luks_open (gchar *device,
                     gchar *name,
                     gchar *passphrase,
                     gchar *key_file,
                     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]
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_close ()

gboolean
bd_crypto_luks_close (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 (gchar *device,
                        gchar *pass,
                        gchar *key_file,
                        gchar *npass,
                        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_remove_key ()

gboolean
bd_crypto_luks_remove_key (gchar *device,
                           gchar *pass,
                           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_change_key ()

gboolean
bd_crypto_luks_change_key (gchar *device,
                           gchar *pass,
                           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_resize ()

gboolean
bd_crypto_luks_resize (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 (gchar *device,
                         gchar *passphrase,
                         gchar *cert_data,
                         gchar *directory,
                         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
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_ERROR

#define BD_CRYPTO_ERROR bd_crypto_error_quark ()

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"

#define	BD_CRYPTO_LUKS_METADATA_SIZE
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_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_escrow_device ()