DragonFly On-Line Manual Pages

Search: Section:  


TCPLAY(8)	       DragonFly System Manager's Manual	     TCPLAY(8)

NAME

tcplay -- tool to manage TrueCrypt volumes

SYNOPSIS

tcplay -c -d device [-g] [-z] [-w] [-a pbkdf_hash] [-b cipher] [-f keyfile_hidden] [-k keyfile] [-x pbkdf_hash] [-y cipher] tcplay -i -d device [-e] [-f keyfile_hidden] [-k keyfile] [-s system_device] [--fde] [--use-backup] [--use-hdr-file hdr_file] [--use-hidden-hdr-file hdr_file] tcplay -j mapping tcplay -m mapping -d device [-e] [-f keyfile_hidden] [-k keyfile] [-s system_device] [-t] [--fde] [--use-backup] [--use-hdr-file hdr_file] [--use-hidden-hdr-file hdr_file] tcplay --modify -d device [-k keyfile] [--new-keyfile new_keyfile] [--new-pbkdf-prf pbkdf_hash] [-s system_device] [--fde] [--use-backup] [--use-hdr-file hdr_file] [--use-hidden-hdr-file hdr_file] [--save-hdr-backup hdr_file] [-w] tcplay --modify -d device [-k keyfile] --restore-from-backup-hdr [-w] tcplay -u mapping tcplay -h | -v

DESCRIPTION

The tcplay utility provides full support for creating and opening/mapping TrueCrypt-compatible volumes. It supports the following commands, each with a set of options detailed further below: -c, --create Create a new encrypted TrueCrypt volume on the device specified by --device. -h, --help Print help message and exit. -i, --info Print out information about the encrypted device specified by --device. -j mapping, --info-mapped=mapping Print out information about the mapped tcplay volume specified by mapping. Information such as key CRC and the PBKDF2 PRF is not available via this command. --modify Modify the volume header. This mode allows changing passphrase, keyfiles, PBKDF2 PRF as well as restoring from a backup header. -m mapping, --map=mapping Map the encrypted TrueCrypt volume on the device specified by --device as a dm(4) mapping called mapping. The mapping argument should not contain any spaces or special characters. -u mapping, --unmap=mapping Removes (unmaps) the dm(4) mapping specified by mapping as well as any related cascade mappings. If you mapped a volume using full disk encryption and created mapping for individual parti- tions using kpartx(8), you must remove these prior to unmapping the volume. -v, --version Print version message and exit. Options common to all commands are: -d device, --device=device Specifies the disk device on which the TrueCrypt volume resides/will reside. This option is mandatory for all commands. -f keyfile_hidden, --keyfile-hidden=keyfile_hidden Specifies a keyfile to use in addition to the passphrase when either creating a hidden volume or when protecting a hidden vol- ume while mapping or querying the outer volume. If you only intend to map a hidden volume, the --keyfile option has to be used. This option can appear multiple times; if so, multiple keyfiles will be used. This option is not valid in the --modify mode. -k keyfile, --keyfile=keyfile Specifies a keyfile to use in addition to the passphrase. This option can appear multiple times; if so, multiple keyfiles will be used. Additional options for the --create command are: -a pbkdf_hash, --pbkdf-prf=pbkdf_hash Specifies which hash algorithm to use for the PBKDF2 password derivation. To see which algorithms are supported, specify --pbkdf-prf=help. -b cipher, --cipher=cipher Specifies which cipher algorithm or cascade of ciphers to use to encrypt the new volume. To see which algorithms are supported, specify --cipher=help. -g, --hidden Specifies that the newly created volume will contain a hidden volume. The keyfiles applied to the passphrase for the hidden volume are those specified by --keyfile-hidden. The user will be prompted for the size of the hidden volume interactively. -w, --weak-keys Use urandom(4) for key material instead of a strong entropy source. This is in general a really bad idea and should only be used for testing. -x pbkdf_hash, --pbkdf-prf-hidden=pbkdf_hash Specifies which hash algorithm to use for the PBKDF2 password derivation for the hidden volume. Only valid in conjunction with --hidden. If no algorithm is specified, the same as for the outer volume will be used. To see which algorithms are sup- ported, specify --pbkdf-prf-hidden=help. -y cipher, --cipher-hidden=cipher Specifies which cipher algorithm or cascade of ciphers to use to encrypt the hidden volume on the new TrueCrypt volume. Only valid in conjunction with --hidden. If no cipher is specified, the same as for the outer volume will be used. To see which algorithms are supported, specify --cipher-hidden=help. -z, --insecure-erase Skips the secure erase of the disk. Use this option carefully as it is a security risk! Additional options for the --info, --map and --modify commands are: -e, --protect-hidden Specifies that an outer volume will be queried or mapped, but its reported size will be adjusted accordingly to the size of the hidden volume contained in it. Both the hidden volume and outer volume passphrase and keyfiles will be required. This option only applies to the --info and --map commands. -s system_device, --system-encryption=system_device This option is required if you are attempting to access a device that uses system encryption, for example an encrypted Windows system partition. It does not apply to disks using full disk encryption. The --device option will point at the actual encrypted partition, while the system_device argument will point to the parent device (i.e. underlying physical disk) of the encrypted partition. --fde This option is intended to be used with disks using full disk encryption (FDE). When a disk has been encrypted using True- Crypt's FDE, the complete disk is encrypted except for the first 63 sectors. The --device option should point to the whole disk device, not to any particular partition. The resultant mapping will cover the whole disk, and will not appear as separate parti- tions. To access individual partitions after mapping, kpartx(8) can be used. --use-backup This option is intended to be used when the primary headers of a volume have been corrupted. This option will force tcplay to use the backup headers, which are located at the end of the device, to access the volume. Additional options only for the --map command are: -t, --allow-trim This option enables TRIM (discard) support on the mapped volume. Additional options only for the --modify command are: --new-pbkdf-prf=pbkdf_hash Specifies which hash algorithm to use for the PBKDF2 password derivation on reencrypting the volume header. If this option is not specified, the reencrypted header will use the current PRF. To see which algorithms are supported, specify --pbkdf-prf=help. --new-keyfile=keyfile Specifies a keyfile to use in addition to the new passphrase on reencrypting the volume header. This option can appear multiple times; if so, multiple keyfiles will be used. --restore-from-backup-hdr If this option is specified, neither --new-pbkdf-prf nor --new-keyfile should be specified. This option implies --use-backup. Use this option to restore the volume headers from the backup header. Sending a SIGINFO or SIGUSR1 signal to a running tcplay process makes it print progress on slower tasks such as gathering entropy or wiping the volume.

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. Simi- larly, keyfiles are limited to a size of 1 MB, but up to 256 keyfiles can be used.

PLAUSIBLE DENIABILITY

tcplay offers plausible deniability. Hidden volumes are created within an outer volume. Which volume is accessed solely depends on the passphrase and keyfile(s) used. If the passphrase and keyfiles for the outer volume are specified, no information about the existence of the hidden volume is exposed. Without knowledge of the passphrase and keyfile(s) of the hid- den volume its existence remains unexposed. The hidden volume can be protected when mapping the outer volume by using the --protect-hidden option and specifying the passphrase and keyfiles for both the outer and hidden volumes.

EXAMPLES

Create a new TrueCrypt volume on /dev/vn0 using the cipher cascade of AES and Twofish and the Whirlpool hash algorithm for PBKDF2 password deriva- tion and two keyfiles, one.key and two.key: tcplay --create --device=/dev/vn0 --cipher=AES-256-XTS,TWOFISH-256-XTS --pbkdf-prf=whirlpool --keyfile=one.key --keyfile=two.key Map the outer volume on the TrueCrypt volume on /dev/vn0 as truecrypt1, but protect the hidden volume, using the keyfile hidden.key, from being overwritten: tcplay --map=truecrypt1 --device=/dev/vn0 --protect-hidden --keyfile-hidden=hidden.key Map the hidden volume on the TrueCrypt volume on /dev/vn0 as truecrypt2, using the keyfile hidden.key: tcplay --map=truecrypt2 --device=/dev/vn0 --keyfile=hidden.key Map and mount the volume in the file secvol on Linux: losetup /dev/loop1 secvol tcplay --map=secv --device=/dev/loop1 mount /dev/mapper/secv /mnt Similarly on DragonFly: vnconfig vn1 secvol tcplay --map=secv --device=/dev/vn1 mount /dev/mapper/secv /mnt Unmapping the volume truecrypt2 on both Linux and DragonFly after unmounting: dmsetup remove truecrypt2 Or alternatively: tcplay --unmap=truecrypt2 A hidden volume whose existence can be plausibly denied and its outer volume can for example be created with tcplay --create --hidden --device=/dev/loop0 --cipher=AES-256-XTS,TWOFISH-256-XTS --pbkdf-prf=whirlpool --keyfile=one.key --cipher-hidden=AES-256-XTS --pbkdf-prf-hidden=whirlpool --keyfile-hidden=hidden.key tcplay will prompt the user for the passphrase for both the outer and hidden volume as well as the size of the hidden volume inside the outer volume. The hidden volume will be created inside the area spanned by the outer volume. The hidden volume can optionally use a different cipher and prf function as specified by the --cipher-hidden and --pbkdf-prf-hidden options. Which volume is later accessed depends only on which passphrase and keyfile(s) are being used, so that the existence of the hidden volume remains unknown without knowledge of the passphrase and keyfile it is protected by since it is located within the outer vol- ume. To map the outer volume without potentially damaging the hidden volume, the passphrase and keyfile(s) of the hidden volume must be known and provided alongside the --protect-hidden option. A disk encrypted using full disk encryption can be mapped using tcplay --map=tcplay_sdb --device=/dev/sdb --fde To access individual partitions on the now mapped disk, the following command will generate mappings for each individual partition on the encrypted disk: kpartx --av /dev/mapper/tcplay_sdb To restore the main volume header from the backup header, the following command can be used: tcplay --modify --device=/dev/sdb --restore-from-backup-hdr As with most other commands, which header is saved (used as source) depends on the passphrase and keyfiles used. To save a backup copy of a header, the following command can be used: tcplay --modify --device=/dev/sdb --save-hdr-backup=/tmp/sdb_backup_header.hdr As with most other commands, which header is saved (used as source) depends on the passphrase and keyfiles used. To restore a header from a backup header file, the following command can be used: tcplay --modify -use-hdr-file=/tmp/sdb_backup_header.hdr Similarly, to restore a hidden header from a backup header file: tcplay --modify -use-hidden-hdr-file=/tmp/sdb_backup_hidden_header.hdr Which header is used as the source of the operation will still depend on the passphrase and keyfiles used. Even if you use the --use-hidden-hdr-file option, if you specify the passphrase and keyfiles for the main header, the main header will be used instead.

SEE ALSO

crypttab(5), cryptsetup(8), dmsetup(8), kpartx(8)

HISTORY

The tcplay utility appeared in DragonFly 2.11.

AUTHORS

Alex Hornung DragonFly 5.3 December 8, 2013 DragonFly 5.3 TCPLAY(3) DragonFly Library Functions Manual TCPLAY(3)

NAME

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 -- TrueCrypt volume management

LIBRARY

TrueCrypt-compatible API library (libtcplay, -ltcplay)

SYNOPSIS

#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

The tcplay library provides an interface to create, query, map and manage TrueCrypt-compatible volumes. The tc_api_init() function initializes the library internals and prepares it for use via the API. This function has to be called before using any other API function. If the verbose argument is non-zero, then the library will output information such as errors via stdout and stderr. The tc_api_uninit() function clears up all internal secure memory, such as memory used for decrypted headers, passphrases, keyfiles, etc. The tc_api_has() function checks whether the loaded tcplay library has the feature specified by the feature argument. The current version of the tcplay library supports the following features: Feature Description trim Allows enabling discards/TRIM when mapping a volume The tc_api_cipher_iterate() function passes every available cipher chain to the callback provided in the fn argument. The priv argument is passed on every call of the callback function. The name of the cipher chain is passed to the callback function in the name argument. Similarly, the ciphers_in_chain argument 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. The tc_api_prf_iterate() function passes every available cipher chain to the callback provided in the fn argument. The priv argument is passed on every call of the callback function. The name of the PKBDF2 PRF algo- rithm is passed to the callback function in the name argument. The tc_api_task_init() function initializes and returns a tc_api_task opaque pointer that can be used to run tcplay commands. Each task can be used only for a single tc_api_task_do() call, and must be deallocated using tc_api_task_uninit(). The op argument can be one of the following: 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. The tc_api_task_set() function allows settting a number of different options for the current task. The following table shows which keys are available on calls to tc_api_task_set() for each of the operations. The letter M indicates the setting is mandatory, whilst * indicates the set- ting is optional. Key create info map unmap info_mapped modify restore dev M M M * M M map_name M M M interactive * * * * * retries * * * * * timeout * * * state_change_fn * * * weak_keys_and_salt * * * secure_erase * hidden_size_bytes * prf_algo * h_prf_algo * cipher_chain * h_cipher_chain * protect_hidden * * fde * * sys * * ? ? use_backup_header * * * * header_from_file * * * * hidden_header_from_file * * * * allow_trim * save_header_to_file * passphrase * * * * * h_passphrase * * * * * keyfiles * * * * * h_keyfiles * * * * * new_passphrase * new_keyfiles * new_prf_algo * The varargs accepted by the tc_api_task_set() function depend on the key being set. dev The vararg is of type const char *. It sets the device that con- tains the TrueCrypt volume to operate on. map_name The vararg is of type const char *. It set 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 vol- ume. 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 parti- tion. 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 vol- ume 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. keyfiles The vararg is of type const char *. If not NULL the given key- file will be added to the keyfile pool. Multiple calls to set this option with a non- NULL argument result add additional key- files. If NULL all keyfiles are cleared. h_keyfiles The vararg is of type const char *. If not NULL the given key- file will be added to the keyfile pool. Multiple calls to set this option with a non- NULL argument result add additional key- files. 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 key- files 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. 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 key- file will be added to the new keyfile pool. Multiple calls to set this option with a non- NULL argument result add additional keyfiles. If NULL all new keyfiles are cleared. When the volume header is modified, it will be reencrypted using the new key- files. 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 argu- ment to the callback. The enter_state argument to the callback determines whether tcplay is starting or stopping the time-inten- sive sub-task specified in the state argument. The tc_api_task_do() function runs the task specified in the task argu- ment. Before running the task, tc_api_task_do() performs a simple sanity check of the arguments set previously using tc_api_task_set() before per- forming 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 fol- lowing: Key type Description device char * Corresponding device node cipher char * Used cipher chain prf char * Used PBKDF2 PRF algorithm key_bits int * Number of key bits size int64_t * Volume size in bytes iv_offset int64_t * IV Offset of volume in bytes block_offset int64_t * Block Offset of volume in bytes The second vararg argument must be of the type specified in the above ta- ble. The first vararg argument is always the size of the storage pro- vided in the second argument. For a char * argument, the size corre- sponds 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 (exlcuding keyfiles) are trimmed to 64 characters. Simi- larly, keyfiles are limited to a size of 1 MB, but up to 256 keyfiles can be used.

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 success- fully, 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 return 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.

SEE ALSO

tcplay(8), kpartx(8)

HISTORY

The tcplay library appeared in DragonFly 2.11.

AUTHORS

Alex Hornung DragonFly 5.3 January 20, 2014 DragonFly 5.3

Search: Section: