TCPLAY(8)

📦
version 3.3 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TCPLAY — the girlies' guide to managing TrueCrypt volumes 💖

okay so bestie, welcome to TCPLAY(8), System Manager's Manual, section 8. yes it's a real manpage and yes i'm about to make it make sense. sit down, grab a strawberry 🍓, and let's talk about encrypted volumes.

✨ NAME ✨

tcplay — the tool that manages TrueCrypt volumes. that's it. that's the whole name section. iconic. 👑

🌸 SYNOPSIS 🌸

here's the shape of it, in all its glory:

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] [-p] [-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] [-p] [-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

no cap, it looks like a lot but it's literally just "pick a command, add your options." you got this. 💅

🦋 DESCRIPTION 🦋

so the whole point of tcplay is full support for creating and opening/mapping TrueCrypt-compatible volumes. it supports the following commands, each with its own little pile of options detailed further down (i promise we get to them):

  • -c, --create — create a brand new encrypted TrueCrypt volume on the device you point at with --device. baby's first volume, but make it encrypted. 🎀
  • -h, --help — prints the help message and dips. polite.
  • -i, --info — prints out info about the encrypted device you specified with --device. the gossip session, basically.
  • -j mapping, --info-mapped=mapping — prints out info about the mapped tcplay volume you named in mapping. heads up though: information like key CRC and the PBKDF2 PRF is not available via this command. sad but true.
  • --modify — modify the volume header. this mode lets you change the passphrase, keyfiles, and PBKDF2 PRF, and also restore from a backup header. glow-up mode fr. ✨
  • -m mapping, --map=mapping — map the encrypted TrueCrypt volume on the device you gave with --device as a dm(4) mapping called mapping. important: the mapping argument should not contain any spaces or special characters. keep it cute, keep it simple.
  • -u mapping, --unmap=mapping — removes (unmaps) the dm(4) mapping you named in mapping, plus any related cascade mappings. and listen: if you mapped a volume using full disk encryption and made mappings for individual partitions using kpartx(8), you must remove those before unmapping the volume. order matters, bestie.
  • -v, --version — prints the version message and exits. short and sweet.

💜 options common to all commands

these ones work everywhere, they're the group chat regulars:

  • -d device, --device=device — tells tcplay which disk device the TrueCrypt volume lives on (or will live on). this one is mandatory for all commands. non-negotiable.
  • -f keyfile_hidden, --keyfile-hidden=keyfile_hidden — a keyfile to use in addition to the passphrase when you're either creating a hidden volume, or protecting a hidden volume while mapping or querying the outer volume. but if you only intend to map a hidden volume, you have to use the --keyfile option instead. this option can appear multiple times — do that and multiple keyfiles get used. also: this option is not valid in the --modify mode.
  • -k keyfile, --keyfile=keyfile — a keyfile to use in addition to the passphrase. same deal: it can appear multiple times, and then multiple keyfiles will be used. stacking them like bracelets. 💫

🌈 additional options for the --create command

  • -a pbkdf_hash, --pbkdf-prf=pbkdf_hash — which hash algorithm to use for the PBKDF2 password derivation. wanna see what's supported? specify --pbkdf-prf=help.
  • -b cipher, --cipher=cipher — which cipher algorithm, or cascade of ciphers, to use to encrypt the new volume. wanna see what's supported? specify --cipher=help.
  • -g, --hidden — the newly created volume will contain a hidden volume. the keyfiles applied to the passphrase for the hidden volume are the ones from --keyfile-hidden. the user gets prompted for the size of the hidden volume interactively. mystery girl energy. 🙈
  • -w, --weak-keys — uses urandom(4) for key material instead of a strong entropy source. and like… this is in general a really bad idea and should only be used for testing. not me warning you twice.
  • -x pbkdf_hash, --pbkdf-prf-hidden=pbkdf_hash — which hash algorithm to use for PBKDF2 password derivation for the hidden volume. only valid together with --hidden. if you don't specify one, it uses the same as the outer volume. to see supported algorithms, specify --pbkdf-prf-hidden=help.
  • -y cipher, --cipher-hidden=cipher — which cipher algorithm or cascade of ciphers to use to encrypt the hidden volume on the new TrueCrypt volume. only valid together with --hidden. if no cipher is specified, it uses the same as the outer volume. to see supported algorithms, specify --cipher-hidden=help.
  • -z, --insecure-erase — skips the secure erase of the disk. > use this option carefully, it is a security risk! 😭 please be careful.

🧚 additional options for --info, --map and --modify

  • -e, --protect-hidden — says that an outer volume will be queried or mapped, but its reported size gets adjusted to match the size of the hidden volume inside it. both the hidden volume and outer volume passphrase and keyfiles will be required. note: this option only applies to the --info and --map commands.
  • -p, --prompt-passphrase — makes tcplay prompt for a passphrase immediately, even if a keyfile was provided. normally, if a keyfile is supplied, tcplay first tries to unlock the volume using only the keyfile, and only prompts for a passphrase if that first attempt fails. but since a failed unlocking attempt can take a non-trivial amount of time, using this option can reduce the total unlocking time if you need both a keyfile and a passphrase. this option only makes sense if -k or -f are used. tl;dr: skip the awkward silence, just ask.
  • -s system_device, --system-encryption=system_device — required if you're trying to access a device that uses system encryption, like an encrypted Windows system partition. it does not apply to disks using full disk encryption. --device points at the actual encrypted partition, while the system_device argument points to the parent device (i.e. the underlying physical disk) of the encrypted partition.
  • --fde — meant for disks using full disk encryption (FDE). when a disk has been encrypted using TrueCrypt's FDE, the complete disk is encrypted except for the first 63 sectors. --device should point to the whole disk device, not to any particular partition. the resulting mapping covers the whole disk and will not appear as separate partitions. to access individual partitions after mapping, you can use kpartx(8). it's giving "one big vibe, no subdivisions." 💀
  • --use-backup — for when the primary headers of a volume have been corrupted. this forces tcplay to use the backup headers, which live at the end of the device, to access the volume. the backup plan came through. 🫶

🎀 additional options only for the --map command

  • -t, --allow-trim — enables TRIM (discard) support on the mapped volume.

⭐ additional options only for the --modify command

  • --new-pbkdf-prf=pbkdf_hash — which hash algorithm to use for PBKDF2 password derivation when reencrypting the volume header. if you don't specify it, the reencrypted header uses the current PRF. to see supported algorithms, specify --pbkdf-prf=help.
  • --new-keyfile=keyfile — a keyfile to use in addition to the new passphrase when reencrypting the volume header. can appear multiple times, and then multiple keyfiles get used.
  • --restore-from-backup-hdr — if you use this, then neither --new-pbkdf-prf nor --new-keyfile should be specified. this option implies --use-backup. use it to restore the volume headers from the backup header. the reset button but for headers. 🔥

and one more thing, on the signal front: sending a SIGINFO or SIGUSR1 signal to a running tcplay process makes it print progress on slower tasks like gathering entropy or wiping the volume. so when it's being slow and mysterious, you can literally just poke it. 💅

🌸 NOTES 🌸

  • TrueCrypt limits passphrases to 64 characters (including the terminating null character). to stay compatible, tcplay does the same.
  • all passphrases (excluding keyfiles) are trimmed to 64 characters.
  • keyfiles are limited to a size of 1 MB, but up to 256 keyfiles can be used. yes, two hundred and fifty-six. stack 'em. 👑

💜 PLAUSIBLE DENIABILITY 💜

okay this is the cool part, pay attention bestie. tcplay offers plausible deniability.

hidden volumes are created within an outer volume. which volume you actually access depends solely on the passphrase and keyfile(s) you use. if the passphrase and keyfiles for the outer volume are specified, no information about the existence of the hidden volume is exposed. and without knowledge of the passphrase and keyfile(s) of the hidden volume, its existence stays unexposed. 🕵️♀️

and you can protect the hidden volume while mapping the outer volume by using the --protect-hidden option and specifying the passphrase and keyfiles for both the outer and hidden volumes. main character with a secret identity, fr.

part 1 done, but we're not done — keep scrolling, there's more coming. 🦋

🔐 VERACRYPT SUPPORT 💖

so tcplay is a bestie who speaks both languages: legacy TrueCrypt and VeraCrypt, no cap. when you're creating a new volume, the PBKDF2 PRF you pick is literally the thing that decides which format you get. the formats are identical other than the rounds of the key derivation functions as well as the volume signature and minver fields in the header. so converting a volume from one format to the other using tcplay is simply a matter of using the --modify option and specifying a PBKDF2 PRF hash matching the intended target format with the --new-pbkdf-prf argument. that's it, that's the whole conversion arc. 🦋

PBKDF2 PRFs suffixed with -VC are VeraCrypt PRFs, whilst all others are legacy TrueCrypt PRFs. by default, new volumes are created with a VeraCrypt PRF to offer better security — she's looking out for you, periodt. 💅

NOTE: failed unlocking attempts even for legacy TrueCrypt volumes now take significantly longer than before, as tcplay will cycle through all PRFs, including the VeraCrypt PRFs with much higher number of PRF iterations. successful attempts should still take the same amount of time as before, as the legacy PRF settings are tried first. one notable exception is if both a keyfile and a passphrase is required. normally, tcplay would first attempt an unlock attempt with just the keyfile, and only prompt for a passphrase after that attempt failed. if it is known in advance that both a keyfile and passphrase are required to unlock a volume, the -p option to --info and --map can more than halve the time required to unlock the volume. 😭 (yeah, it's giving "brutally slow", but at least now you know why)

🌸 EXAMPLES 🌸

okay bestie, this is the part where it all clicks. let's go. ✨

Create a new TrueCrypt volume on /dev/vn0 🎀

using the cipher cascade of AES and Twofish and the Whirlpool hash algorithm for PBKDF2 password derivation, plus two keyfiles, one.key and two.key:

tcplay --create --device=/dev/vn0
--cipher=TWOFISH-256-XTS,AES-256-XTS --pbkdf-prf=whirlpool
--keyfile=one.key --keyfile=two.key

Map the outer volume 🔥

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 🫶

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 💀

unmapping the volume truecrypt2 on both Linux and DragonFly after unmounting:

dmsetup remove truecrypt2

or alternatively:

tcplay --unmap=truecrypt2

The iconic plausible-deniability combo 👑

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=TWOFISH-256-XTS,AES-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 volume. 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. 💖 (this is the whole magic trick, and it ate)

Full disk encryption ✨

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

Header backup shenanigans 🌈

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. 🫠 (she said what she said)

👀 SEE ALSO 👀

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

🕰️ HISTORY 🕰️

the tcplay utility appeared in DragonFly 2.11. a legend was born, fr fr. 👑

💜 AUTHORS 💜

Alex Hornung

and that's the whole page, bestie 🎀 this one's from the Debian build, dated December 8, 2013 — page TCPLAY(8), section 8, mystery-and-encryption division. now go forth and encrypt responsibly, ily 💖✨🦋

📦 where this page comes from