Top | ![]() |
![]() |
![]() |
![]() |
#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 | |
enum | BDCryptoLUKSVersion |
BDCryptoLUKSInfo | |
BDCryptoIntegrityInfo | |
enum | BDCryptoTech |
enum | BDCryptoTechMode |
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.
void
bd_crypto_close ();
Cleans up after the plugin. **This function is called automatically by the library's functions that unload it.**
gboolean bd_crypto_init ();
Initializes the plugin. **This function is called automatically by the library's initialization functions.**
gchar *
bd_crypto_generate_backup_passphrase (GError **error
);
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
gboolean bd_crypto_device_is_luks (const gchar *device
,GError **error
);
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
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/
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
gchar * bd_crypto_luks_uuid (const gchar *device
,GError **error
);
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
guint64 bd_crypto_luks_get_metadata_size (const gchar *device
,GError **error
);
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
gchar * bd_crypto_luks_status (const gchar *luks_device
,GError **error
);
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]
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 |
[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 |
[allow-none] |
key_file |
a key file for the new LUKS device or |
[allow-none] |
min_entropy |
minimum random data entropy (in bits) required to format |
|
error |
place to store error (if any). |
[out] |
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
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).
device |
a device to format as LUKS |
|
cipher |
cipher specification (type-mode, e.g. "aes-xts-plain64") or |
[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 |
|
min_entropy |
minimum random data entropy (in bits) required to format |
|
error |
place to store error (if any). |
[out] |
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
void
bd_crypto_luks_extra_free (BDCryptoLUKSExtra *extra
);
Frees extra
.
[skip]
BDCryptoLUKSExtra *
bd_crypto_luks_extra_copy (BDCryptoLUKSExtra *extra
);
Creates a new copy of extra
.
[skip]
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_1
and
extra
to NULL
is the same as calling bd_crypto_luks_format
.
device |
a device to format as LUKS |
|
cipher |
cipher specification (type-mode, e.g. "aes-xts-plain64") or |
[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 |
[allow-none] |
key_file |
a key file for the new LUKS device or |
[allow-none] |
min_entropy |
minimum random data entropy (in bits) required to format |
|
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] |
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
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_1
and
extra
to NULL
is the same as calling bd_crypto_luks_format_blob
.
device |
a device to format as LUKS |
|
cipher |
cipher specification (type-mode, e.g. "aes-xts-plain64") or |
[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 |
|
min_entropy |
minimum random data entropy (in bits) required to format |
|
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] |
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
gboolean bd_crypto_luks_open (const gchar *device
,const gchar *name
,const gchar *passphrase
,const gchar *key_file
,gboolean read_only
,GError **error
);
device |
the device to open |
|
name |
name for the LUKS device |
|
passphrase |
passphrase to open the |
[allow-none] |
key_file |
key file path to use for opening the |
[allow-none] |
read_only |
whether to open as read-only or not (meaning read-write) |
|
error |
place to store error (if any). |
[out] |
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
gboolean bd_crypto_luks_open_blob (const gchar *device
,const gchar *name
,const guint8 *pass_data
,gsize data_len
,gboolean read_only
,GError **error
);
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 |
|
read_only |
whether to open as read-only or not (meaning read-write) |
|
error |
place to store error (if any). |
[out] |
whether the device
was successfully opened or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_OPEN_CLOSE
gboolean bd_crypto_luks_close (const gchar *luks_device
,GError **error
);
whether the given luks_device
was successfully closed or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_OPEN_CLOSE
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
);
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
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
);
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 |
|
npass_data |
a new passphrase for the new LUKS device (may contain arbitrary binary data). |
[array length=ndata_len] |
ndata_len |
length of the |
|
error |
place to store error (if any). |
[out] |
whether the npass_data
was successfully added to device
or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_ADD_KEY
gboolean bd_crypto_luks_remove_key (const gchar *device
,const gchar *pass
,const gchar *key_file
,GError **error
);
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
gboolean bd_crypto_luks_remove_key_blob (const gchar *device
,const guint8 *pass_data
,gsize data_len
,GError **error
);
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 |
|
error |
place to store error (if any). |
[out] |
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
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] |
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
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
);
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 |
|
npass_data |
a new passphrase for the new LUKS device (may contain arbitrary binary data). |
[array length=ndata_len] |
ndata_len |
length of the |
|
error |
place to store error (if any). |
[out] |
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
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.
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] |
whether the luks_device
was successfully resized or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_RESIZE
gboolean bd_crypto_luks_resize_luks2 (const gchar *luks_device
,guint64 size
,const gchar *passphrase
,const gchar *key_file
,GError **error
);
luks_device |
opened LUKS device to resize |
|
passphrase |
passphrase to resize the |
[allow-none] |
key_file |
key file path to use for resizinh the |
[allow-none] |
size |
requested size in sectors or 0 to adapt to the backing device |
|
error |
place to store error (if any). |
[out] |
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
gboolean bd_crypto_luks_resize_luks2_blob (const gchar *luks_device
,guint64 size
,const guint8 *pass_data
,gsize data_len
,GError **error
);
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 |
|
size |
requested size in sectors or 0 to adapt to the backing device |
|
error |
place to store error (if any). |
[out] |
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
gboolean bd_crypto_luks_suspend (const gchar *luks_device
,GError **error
);
whether the given luks_device
was successfully suspended or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME
gboolean bd_crypto_luks_resume_blob (const gchar *luks_device
,const guint8 *pass_data
,gsize data_len
,GError **error
);
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 |
|
error |
place to store error (if any). |
[out] |
whether the given luks_device
was successfully resumed or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME
gboolean bd_crypto_luks_resume (const gchar *luks_device
,const gchar *passphrase
,const gchar *key_file
,GError **error
);
whether the given luks_device
was successfully resumed or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_SUSPEND_RESUME
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.
device |
device to kill slot on |
|
slot |
keyslot to destroy |
|
error |
place to store error (if any). |
[out] |
whether the given slot
was successfully destroyed or not
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_REMOVE_KEY
gboolean bd_crypto_luks_header_backup (const gchar *device
,const gchar *backup_file
,GError **error
);
device |
device to backup the LUKS header |
|
backup_file |
file to save the header backup to |
|
error |
place to store error (if any). |
[out] |
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
gboolean bd_crypto_luks_header_restore (const gchar *device
,const gchar *backup_file
,GError **error
);
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] |
whether the given device
LUKS header was successfully restored
from backup_file
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_BACKUP_RESTORE
void
bd_crypto_luks_info_free (BDCryptoLUKSInfo *info
);
Frees info
.
[skip]
BDCryptoLUKSInfo *
bd_crypto_luks_info_copy (BDCryptoLUKSInfo *info
);
Creates a new copy of info
.
[skip]
BDCryptoLUKSInfo * bd_crypto_luks_info (const gchar *luks_device
,GError **error
);
information about the luks_device
or NULL
in case of error
Tech category: BD_CRYPTO_TECH_LUKS
-BD_CRYPTO_TECH_MODE_QUERY
void
bd_crypto_integrity_info_free (BDCryptoIntegrityInfo *info
);
Frees info
.
[skip]
BDCryptoIntegrityInfo *
bd_crypto_integrity_info_copy (BDCryptoIntegrityInfo *info
);
BDCryptoIntegrityInfo * bd_crypto_integrity_info (const gchar *device
,GError **error
);
information about the device
or NULL
in case of error
Tech category: BD_CRYPTO_TECH_INTEGRITY
-BD_CRYPTO_TECH_MODE_QUERY
gboolean bd_crypto_tc_open (const gchar *device
,const gchar *name
,const guint8 *pass_data
,gsize data_len
,gboolean read_only
,GError **error
);
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 |
|
read_only |
whether to open as read-only or not (meaning read-write) |
|
error |
place to store error (if any). |
[out] |
whether the device
was successfully opened or not
Tech category: BD_CRYPTO_TECH_TRUECRYPT
-BD_CRYPTO_TECH_MODE_OPEN_CLOSE
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
);
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 |
|
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] |
whether the device
was successfully opened or not
Tech category: BD_CRYPTO_TECH_TRUECRYPT
-BD_CRYPTO_TECH_MODE_OPEN_CLOSE
gboolean bd_crypto_tc_close (const gchar *tc_device
,GError **error
);
whether the given tc_device
was successfully closed or not
Tech category: BD_CRYPTO_TECH_TRUECRYPT
-BD_CRYPTO_TECH_MODE_OPEN_CLOSE
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 |
[allow-none] |
error |
place to store error (if any). |
[out] |
whether the ecrow data was successfully created for device
or not
Tech category: BD_CRYPTO_TECH_ESCROW
-BD_CRYPTO_TECH_MODE_CREATE
gboolean bd_crypto_is_tech_avail (BDCryptoTech tech
,guint64 mode
,GError **error
);
tech |
the queried tech |
|
mode |
a bit mask of queried modes of operation (BDCryptoTechMode) for |
|
error |
place to store error (details about why the |
[out] |
#define BD_CRYPTO_BACKUP_PASSPHRASE_CHARSET "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz./"
typedef struct { guint64 data_alignment; gchar *data_device; gchar *integrity; guint64 sector_size; gchar *label; gchar *subsystem; } BDCryptoLUKSExtra;
guint64 |
data alignment in sectors, 0 for default/auto detection |
|
gchar * |
detached encrypted data device or NULL |
|
gchar * |
integrity algorithm (e.g. "hmac-sha256") or NULL for no integrity support Note: this field is valid only for LUKS 2 |
|
guint64 |
encryption sector size, 0 for default (512) Note: this field is valid only for LUKS 2 |
|
gchar * |
LUKS header label or NULL Note: this field is valid only for LUKS 2 |
|
gchar * |
typedef struct { BDCryptoLUKSVersion version; gchar *cipher; gchar *mode; gchar *uuid; gchar *backing_device; gint64 sector_size; } BDCryptoLUKSInfo;
BDCryptoLUKSVersion |
LUKS version |
|
gchar * |
used cipher (e.g. "aes") |
|
gchar * |
used cipher mode (e.g. "xts-plain") |
|
gchar * |
UUID of the LUKS device |
|
gchar * |
name of the underlying block device |
|
gint64 |
size (in bytes) of encryption sector Note: sector size is valid only for LUKS 2 |
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;
gchar * |
integrity algorithm |
|
guint32 |
integrity key size in bytes |
|
guint32 |
sector size in bytes |
|
guint32 |
tag size per-sector in bytes |
|
guint32 |
number of interleave sectors |
|
guint64 |
size of journal in bytes |
|
gchar * |
journal encryption algorithm |
|
gchar * |
journal integrity algorithm |