TCPLAY(3)

💖 TCPLAY(3) 💖 — TrueCrypt volume management, but make it iconic

okay bestie, welcome to the manual page for TCPLAY(3). this is part 1, so buckle up. 💅

---

✨ NAME ✨

so this page covers all these iconic functions: tc_api_init, tc_api_uninit, tc_api_has, tc_api_cipher_iterate, tc_api_prf_iterate, tc_api_task_init, tc_api_task_uninit, tc_api_task_set, tc_api_task_do, tc_api_task_info_get, tc_api_task_get_error — and they're all about TrueCrypt volume management. periodt. 👑

---

📚 LIBRARY 📚

TrueCrypt volume management (libtcplay, -ltcplay). yes, that's the vibe. 🦋

---

🦋 SYNOPSIS 🦋

here's the code, bestie, copy it exactly:

#include <tcplay_api.h>

typedef int
(*tc_api_cipher_iterator_fn)(void *priv, const char *name,
    int key_length_in_bits, int ciphers_in_chain);

typedef int
(*tc_api_prf_iterator_fn)(void *priv, const char *name);

typedef int
(*tc_api_state_change_fn)(void *priv, const char *state,
    int enter_state);

int
tc_api_init(int verbose);

int
tc_api_uninit(void);

int
tc_api_has(const char *feature);

int
tc_api_cipher_iterate(tc_api_cipher_iterator_fn fn, void *priv);

int
tc_api_prf_iterate(tc_api_prf_iterator_fn fn, void *priv);

tc_api_task
tc_api_task_init(const char *op);

int
tc_api_task_uninit(tc_api_task task);

int
tc_api_task_set(tc_api_task task, const char *key, ...);

int
tc_api_task_do(tc_api_task task);

int
tc_api_task_info_get(tc_api_task task, const char *key, ...);

const char *
tc_api_task_get_error(tc_api_task task);

---

💅 DESCRIPTION 💅

so basically, the tcplay library is your bestie for creating, querying, mapping, and managing TrueCrypt-compatible volumes. 💖

tc_api_init() — this one initializes the library internals and gets everything ready for API time. You have to call it before you touch any other API function, no cap. If verbose is non-zero, the library will spill info like errors to stdout and stderr.

tc_api_uninit() — this one clears up all the internal secure memory, like the stuff used for decrypted headers, passphrases, keyfiles, etc. clean up your mess, bestie. 🧼

tc_api_has() — checks if the loaded tcplay library has the feature you pass in feature. Right now, the current version supports these features:

• trim — Allows enabling discards/TRIM when mapping a volume

tc_api_cipher_iterate() — this one passes every available cipher chain to the callback you give it in fn. The priv argument gets passed along on every call of the callback. The cipher chain's name goes to the callback in name. Also, ciphers_in_chain holds the number of ciphers in the current chain, and key_length_in_bits holds the total key length for the cipher chain, in bits. 🔐

tc_api_prf_iterate() — same vibe: it passes every available cipher chain to the callback in fn. The priv argument is passed on every call of the callback. The name of the PKBDF2 PRF algorithm is passed to the callback in name. (yes, it says cipher chain, we're just quoting the lore.) 🌀

tc_api_task_init() — this one initializes and returns a tc_api_task opaque pointer you can use to run tcplay commands. Each task is a one-time thing: it can only be used for a single tc_api_task_do() call, and you must deallocate it with tc_api_task_uninit(). The op argument can be one of these:

• create — Create a new encrypted TrueCrypt volume.
• map — Map an existing TrueCrypt volume.
• info — Request information about an encrypted TrueCrypt volume.
• info_mapped — Request information about a mapped TrueCrypt volume.
• unmap — Unmap a mapped TrueCrypt volume.
• modify — Modify the TrueCrypt volume by changing the passphrase, keyfiles, PRF algorithm, restoring from a backup header, restoring from a header file or saving to a header file.
• restore — Modify the TrueCrypt volume as modify does, but without changing the passphrase, keyfiles or PRF algorithm.

tc_api_task_set() — this is the one that lets you set a bunch of different options for the current task. Here's the tea on which keys are available for each operation. M means mandatory, * means optional. (There's also a ? in there, just roll with it.) 👑

• dev — create: M, info: M, map: M, unmap: *, modify: M, restore: M.
• map_name — map: M, unmap: M, info_mapped: M.
• interactive — create: *, info: *, map: *, modify: *, restore: *.
• retries — create: *, info: *, map: *, modify: *, restore: *.
• timeout — create: *, info: *, map: *.
• state_change_fn — create: *, modify: *, restore: *.
• weak_keys_and_salt — create: *, modify: *, restore: *.
• secure_erase — create: *.
• hidden_size_bytes — create: *.
• prf_algo — create: *.
• h_prf_algo — create: *.
• cipher_chain — create: *.
• h_cipher_chain — create: *.
• protect_hidden — info: *, map: *.
• fde — info: *, map: *.
• sys — info: *, map: *, modify: ?, restore: ?.
• use_backup_header — info: *, map: *, modify: *, restore: *.
• header_from_file — info: *, map: *, modify: *, restore: *.
• hidden_header_from_file — info: *, map: *, modify: *, restore: *.
• allow_trim — map: *.
• save_header_to_file — modify: *.
• passphrase — create: *, info: *, map: *, modify: *, restore: *.
• h_passphrase — create: *, info: *, map: *, modify: *, restore: *.
• keyfiles — create: *, info: *, map: *, modify: *, restore: *.
• h_keyfiles — create: *, info: *, map: *, modify: *, restore: *.
• new_passphrase — modify: *.
• new_keyfiles — modify: *.
• new_prf_algo — modify: *.

The varargs accepted by the tc_api_task_set() function depend on the key being set. here's the breakdown:

• dev — the vararg is of type const char *. it sets the device that contains the TrueCrypt volume to operate on.
• map_name — the vararg is of type const char *. it sets the name of the mapped volume.
• interactive — the vararg is of type int. it determines whether the user will be prompted for a passphrase or whether the settings are taken from the arguments set using tc_api_task_set().
• retries — the vararg is of type int. it determines the number of passphrase retries if interactive is set.
• weak_keys_and_salt — the vararg is of type int. it determines whether to use a weak source of entropy for key material and/or the salt.
• secure_erase — the vararg is of type int. it determines whether a secure erase is performed as part of the volume creation.
• hidden_size_bytes — the vararg is of type int64_t. if set to 0 it implies no hidden volume will be created. A positive value implies a hidden volume of the specified size in bytes is created.
• prf_algo — the vararg is of type const char * and must be a valid PBKDF2 PRF algorithm. it determines which PBKDF2 PRF algorithm is used for the outer volume.
• h_prf_algo — the vararg is of type const char * and must be a valid PBKDF2 PRF algorithm. it determines which PBKDF2 PRF algorithm is used for the hidden volume.
• cipher_chain — the vararg is of type const char * and must be a valid tcplay cipher chain. it determines which cipher chain is used to encrypt the outer volume.
• h_cipher_chain — the vararg is of type const char * and must be a valid tcplay cipher chain. it determines which cipher chain is used to encrypt the hidden volume.
• protect_hidden — the vararg is of type int. it determines whether the size of the outer volume should be adjusted to protect any hidden volume. Using this mode requires both outer and hidden passphrases and keyfiles.
• sys — the vararg is of type const char *. it determines whether the volume is a system encrypted volume, and if so, which disk is the system disk and hence contains the header. If set to NULL the volume will implicitly be treated as a non-system encrypted volume.
• fde — the vararg is of type int. it determines whether the disk uses full disk encryption or not. If specified, the device pointed to by the dev setting should be a whole disk device, not any partition. The device will be mapped or queried as a whole. To access individual partitions, a utility such as kpartx(8) should be used, which will create additional individual mappings for each partition in the decrypted mapped volume. For more details on full disk encryption, see tcplay(8).
• use_backup_header — the vararg is of type int. it determines whether the backup header should be used instead of the regular header to access the volume.
• header_from_file — the vararg is of type const char *. if not NULL it forces tcplay to use the header in the specified file instead of the regular outer volume header.
• hidden_header_from_file — the vararg is of type const char *. if not NULL it forces tcplay to use the header in the specified file instead of the regular hidden volume header.
• allow_trim — the vararg is of type int. it specifies whether the mapped volume should allow discards (TRIM).
• save_header_to_file — the vararg is of type const char *. if not NULL it forces tcplay to write the (modified) header to the specified file instead of replacing the volume headers.
• passphrase — the vararg is of type const char *. it sets the passphrase that tcplay uses to access the volume.
• h_passphrase — the vararg is of type const char *. it sets the passphrase that tcplay uses to unlock the hidden volume header. This option is only used if a hidden volume is being created or the protect_hidden setting is set. Otherwise tcplay will first use the regular passphrase to try to unlock the outer volume and then try to unlock the hidden volume header with the same passphrase without ever using h_passphrase.

---

and that's the tea for part 1, bestie — part 2 is coming in hot. 🔥

• keyfiles — the vararg is of type const char *. if it's not NULL, the given keyfile gets added to the keyfile pool. multiple calls to set this option with a non-NULL argument result in adding additional keyfiles. if NULL, all keyfiles are cleared. 💅
• h_keyfiles — the vararg is of type const char *. if not NULL, the given keyfile gets added to the keyfile pool. multiple calls to set this option with a non-NULL argument result in adding additional keyfiles. if NULL, all keyfiles are cleared. this option is only used if a hidden volume is being created or the protect_hidden setting is set. otherwise tcplay will first use the regular keyfiles to try to unlock the outer volume and then try to unlock the hidden volume header with the same keyfiles without ever using h_keyfiles. so like, it's the special hidden volume keyfile thing. ✨
• new_passphrase — the vararg is of type const char *. it specifies the new passphrase to use when modifying the volume header. 🔑
• new_keyfiles — the vararg is of type const char *. if not NULL, the given keyfile gets added to the new keyfile pool. multiple calls to set this option with a non-NULL argument result in adding additional keyfiles. if NULL, all new keyfiles are cleared. when the volume header is modified, it will be reencrypted using the new keyfiles. 💖
• new_prf_algo — the vararg is of type const char * and must be a valid PBKDF2 PRF algorithm. it determines which PBKDF2 PRF algorithm is used when reencrypting the (modified) volume header. 🎀
• state_change_fn — the first vararg is of type tc_api_state_change_fn and the second vararg is of type void *. it allows the consumer to provide a callback function which will be called when starting and stopping a time-intensive sub-operation such as collecting entropy or erasing a volume. the second vararg is passed as the priv argument to the callback. the enter_state argument to the callback determines whether tcplay is starting or stopping the time-intensive sub-task specified in the state argument. so like, you get updates on the big stuff! 🦋

so the tc_api_task_do() function runs the task specified in the task argument. before running the task, tc_api_task_do() performs a simple sanity check of the arguments set previously using tc_api_task_set() before performing the actual operation. after a call to tc_api_task_do() for the info or info_mapped operations, the queried information is available to be accessed using tc_api_task_info_get(). 💅

the tc_api_task_info_get() function can be used to query the result of a info or info_mapped operation. the task argument is the task used in a previous tc_api_task_do() call. the key argument can be one of the following:

• device — type char * — Corresponding device node
• cipher — type char * — Used cipher chain
• prf — type char * — Used PBKDF2 PRF algorithm
• key_bits — type int * — Number of key bits
• size — type int64_t * — Volume size in bytes
• iv_offset — type int64_t * — IV Offset of volume in bytes
• block_offset — type int64_t * — Block Offset of volume in bytes

the second vararg argument must be of the type specified in the above table. the first vararg argument is always the size of the storage provided in the second argument. for a char * argument, the size corresponds to the size of the buffer at the provided location and must be of type size_t. for an int * or int64_t * argument, it should be the size of the underlying type. 📏

the tc_api_task_get_error() function can be used to get a detailed error message after a failed tc_api_task_do call. the task argument is the task used in a previous tc_api_task_do() call. 😭

---

✨ NOTES ✨

TrueCrypt limits passphrases to 64 characters (including the terminating null character). to be compatible with it, tcplay does the same. all passphrases (excluding keyfiles) are trimmed to 64 characters. similarly, keyfiles are limited to a size of 1 MB, but up to 256 keyfiles can be used. so like, keep it short and sweet, bestie. 💅

---

🎀 RETURN VALUES 🎀

all functions except tc_api_task_init() and tc_api_task_get_error() return either TC_OK to indicate that the operation completed successfully, or TC_ERR_UNIMPL to indicate that the operation is not implemented, or TC_ERR to indicate that any other error occurred. 🔥

the tc_api_task_get_error() function always returns a valid, but possibly empty (or irrelevant, if not called after an error occurred) string. 🤷‍♀️

the tc_api_task_init() function returns NULL if an error occurred and an opaque tc_api_task otherwise. ✨

---

💖 COMPATIBILITY 💖

the tcplay library offers full compatibility with TrueCrypt volumes including hidden volumes, system encryption (map-only), keyfiles and cipher cascading. slay! 👑

---

🌈 SEE ALSO 🌈

• tcplay(8)
• kpartx(8)

---

📜 HISTORY 📜

the tcplay library appeared in DragonFly 2.11. 🦋

---

👑 AUTHORS 👑

Alex Hornung 💅

---

and that's the tea, bestie! this page is from Debian, dated January 20, 2014, for TCPLAY(3). periodt! 💖