Crypto

Crypto — plugin for operations with encrypted devices

Synopsis

#include <crypto.h>

#define             BD_CRYPTO_LUKS_METADATA_SIZE
GQuark              bd_crypto_error_quark               (void);
#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
gchar *             bd_crypto_generate_backup_passphrase
                                                        (GError **error);
gboolean            bd_crypto_device_is_luks            (const gchar *device,
                                                         GError **error);
gchar *             bd_crypto_luks_uuid                 (const gchar *device,
                                                         GError **error);
gchar *             bd_crypto_luks_status               (const gchar *luks_device,
                                                         GError **error);
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);
gboolean            bd_crypto_luks_open                 (const gchar *device,
                                                         const gchar *name,
                                                         const gchar *passphrase,
                                                         const gchar *key_file,
                                                         GError **error);
gboolean            bd_crypto_luks_close                (const gchar *luks_device,
                                                         GError **error);
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);
gboolean            bd_crypto_luks_remove_key           (const gchar *device,
                                                         const gchar *pass,
                                                         const gchar *key_file,
                                                         GError **error);
gboolean            bd_crypto_luks_change_key           (const gchar *device,
                                                         const gchar *pass,
                                                         const gchar *npass,
                                                         GError **error);
gboolean            bd_crypto_luks_resize               (const gchar *device,
                                                         guint64 size,
                                                         GError **error);
gboolean            bd_crypto_escrow_device             (const gchar *device,
                                                         const gchar *passphrase,
                                                         const gchar *cert_data,
                                                         const gchar *directory,
                                                         const gchar *backup_passphrase,
                                                         GError **error);

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.

Details

BD_CRYPTO_LUKS_METADATA_SIZE

#define             BD_CRYPTO_LUKS_METADATA_SIZE

bd_crypto_error_quark ()

GQuark              bd_crypto_error_quark               (void);

BD_CRYPTO_ERROR

#define             BD_CRYPTO_ERROR

enum BDCryptoError

typedef enum {
    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,
} BDCryptoError;

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"

bd_crypto_generate_backup_passphrase ()

gchar *             bd_crypto_generate_backup_passphrase
                                                        (GError **error);

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

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

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

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

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                 (const gchar *device,
                                                         const gchar *name,
                                                         const gchar *passphrase,
                                                         const gchar *key_file,
                                                         GError **error);

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                (const gchar *luks_device,
                                                         GError **error);

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

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           (const gchar *device,
                                                         const gchar *pass,
                                                         const gchar *key_file,
                                                         GError **error);

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           (const gchar *device,
                                                         const gchar *pass,
                                                         const gchar *npass,
                                                         GError **error);

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               (const gchar *device,
                                                         guint64 size,
                                                         GError **error);

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

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