1.\" 2.\" Copyright (c) 2011 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd December 8, 2013 33.Dt TCPLAY 8 34.Os 35.Sh NAME 36.Nm tcplay 37.Nd tool to manage TrueCrypt volumes 38.Sh SYNOPSIS 39.Nm 40.Fl c 41.Fl d Ar device 42.Op Fl g 43.Op Fl z 44.Op Fl w 45.Op Fl a Ar pbkdf_hash 46.Op Fl b Ar cipher 47.Op Fl f Ar keyfile_hidden 48.Op Fl k Ar keyfile 49.Op Fl x Ar pbkdf_hash 50.Op Fl y Ar cipher 51.Nm 52.Fl i 53.Fl d Ar device 54.Op Fl e 55.Op Fl f Ar keyfile_hidden 56.Op Fl k Ar keyfile 57.Op Fl s Ar system_device 58.Op Fl -fde 59.Op Fl -use-backup 60.Op Fl -use-hdr-file Ar hdr_file 61.Op Fl -use-hidden-hdr-file Ar hdr_file 62.Nm 63.Fl j Ar mapping 64.Nm 65.Fl m Ar mapping 66.Fl d Ar device 67.Op Fl e 68.Op Fl f Ar keyfile_hidden 69.Op Fl k Ar keyfile 70.Op Fl s Ar system_device 71.Op Fl t 72.Op Fl -fde 73.Op Fl -use-backup 74.Op Fl -use-hdr-file Ar hdr_file 75.Op Fl -use-hidden-hdr-file Ar hdr_file 76.Nm 77.Fl -modify 78.Fl d Ar device 79.Op Fl k Ar keyfile 80.Op Fl -new-keyfile Ar new_keyfile 81.Op Fl -new-pbkdf-prf Ar pbkdf_hash 82.Op Fl s Ar system_device 83.Op Fl -fde 84.Op Fl -use-backup 85.Op Fl -use-hdr-file Ar hdr_file 86.Op Fl -use-hidden-hdr-file Ar hdr_file 87.Op Fl -save-hdr-backup Ar hdr_file 88.Op Fl w 89.Nm 90.Fl -modify 91.Fl d Ar device 92.Op Fl k Ar keyfile 93.Fl -restore-from-backup-hdr 94.Op Fl w 95.Nm 96.Fl u Ar mapping 97.Nm 98.Fl h | v 99.Sh DESCRIPTION 100The 101.Nm 102utility provides full support for creating and opening/mapping 103TrueCrypt-compatible volumes. 104It supports the following commands, each with a set of options 105detailed further below: 106.Bl -tag -width indent 107.It Fl c , Fl -create 108Create a new encrypted TrueCrypt volume on the device 109specified by 110.Fl -device . 111.It Fl h, Fl -help 112Print help message and exit. 113.It Fl i , Fl -info 114Print out information about the encrypted device specified by 115.Fl -device . 116.It Fl j Ar mapping , Fl -info-mapped Ns = Ns Ar mapping 117Print out information about the mapped tcplay volume specified 118by 119.Ar mapping . 120Information such as key CRC and the PBKDF2 PRF is not available 121via this command. 122.It Fl -modify 123Modify the volume header. 124This mode allows changing passphrase, keyfiles, PBKDF2 PRF as 125well as restoring from a backup header. 126.It Fl m Ar mapping , Fl -map Ns = Ns Ar mapping 127Map the encrypted TrueCrypt volume on the device specified by 128.Fl -device 129as a 130.Xr dm 4 131mapping called 132.Ar mapping . 133The 134.Ar mapping 135argument should not contain any spaces or special characters. 136.It Fl u Ar mapping , Fl -unmap Ns = Ns Ar mapping 137Removes (unmaps) the 138.Xr dm 4 139mapping specified by 140.Ar mapping 141as well as any related cascade mappings. 142If you mapped a volume using full disk encryption and created 143mapping for individual partitions using 144.Xr kpartx 8 , 145you must remove these prior to unmapping the volume. 146.It Fl v, Fl -version 147Print version message and exit. 148.El 149.Pp 150Options common to all commands are: 151.Bl -tag -width indent 152.It Fl d Ar device , Fl -device Ns = Ns Ar device 153Specifies the disk 154.Ar device 155on which the TrueCrypt volume resides/will reside. 156This option is mandatory for all commands. 157.It Fl f Ar keyfile_hidden , Fl -keyfile-hidden Ns = Ns Ar keyfile_hidden 158Specifies a keyfile 159to use in addition to the passphrase when either creating a 160hidden volume or when protecting a hidden volume while mapping 161or querying the outer volume. 162If you only intend to map a hidden volume, the 163.Fl -keyfile 164option has to be used. 165This option can appear multiple times; if so, multiple 166keyfiles will be used. 167This option is not valid in the 168.Fl -modify 169mode. 170.It Fl k Ar keyfile , Fl -keyfile Ns = Ns Ar keyfile 171Specifies a 172.Ar keyfile 173to use in addition to the passphrase. 174This option can appear multiple times; if so, multiple 175keyfiles will be used. 176.El 177.Pp 178Additional options for the 179.Fl -create 180command are: 181.Bl -tag -width indent 182.It Fl a Ar pbkdf_hash , Fl -pbkdf-prf Ns = Ns Ar pbkdf_hash 183Specifies which hash algorithm to use for the PBKDF2 password 184derivation. 185To see which algorithms are supported, specify 186.Fl -pbkdf-prf Ns = Ns Cm help . 187.It Fl b Ar cipher , Fl -cipher Ns = Ns Ar cipher 188Specifies which cipher algorithm or cascade of ciphers to use 189to encrypt the new volume. 190To see which algorithms are supported, specify 191.Fl -cipher Ns = Ns Cm help . 192.It Fl g, Fl -hidden 193Specifies that the newly created volume will contain a hidden 194volume. 195The keyfiles applied to the passphrase for the hidden 196volume are those specified by 197.Fl -keyfile-hidden . 198The user will be prompted for the size of the hidden volume 199interactively. 200.It Fl w, Fl -weak-keys 201Use 202.Xr urandom 4 203for key material instead of a strong entropy source. 204This is in general a really bad idea and should only be used 205for testing. 206.It Fl x Ar pbkdf_hash , Fl -pbkdf-prf-hidden Ns = Ns Ar pbkdf_hash 207Specifies which hash algorithm to use for the PBKDF2 password 208derivation for the hidden volume. 209Only valid in conjunction with 210.Fl -hidden . 211If no algorithm is specified, the same as for the outer volume 212will be used. 213To see which algorithms are supported, specify 214.Fl -pbkdf-prf-hidden Ns = Ns Cm help . 215.It Fl y Ar cipher , Fl -cipher-hidden Ns = Ns Ar cipher 216Specifies which cipher algorithm or cascade of ciphers to use 217to encrypt the hidden volume on the new TrueCrypt volume. 218Only valid in conjunction with 219.Fl -hidden . 220If no cipher is specified, the same as for the outer volume 221will be used. 222To see which algorithms are supported, specify 223.Fl -cipher-hidden Ns = Ns Cm help . 224.It Fl z, Fl -insecure-erase 225Skips the secure erase of the disk. 226Use this option carefully as it is a security risk! 227.El 228.Pp 229Additional options for the 230.Fl -info , 231.Fl -map 232and 233.Fl -modify 234commands are: 235.Bl -tag -width indent 236.It Fl e, Fl -protect-hidden 237Specifies that an outer volume will be queried or mapped, but 238its reported size will be adjusted accordingly to the size of 239the hidden volume contained in it. 240Both the hidden volume and outer volume passphrase and keyfiles 241will be required. 242This option only applies to the 243.Fl -info 244and 245.Fl -map 246commands. 247.It Fl s Ar system_device , Fl -system-encryption Ns = Ns Ar system_device 248This option is required if you are attempting to access a device 249that uses system encryption, for example an encrypted 250.Tn Windows 251system partition. 252It does not apply to disks using full disk encryption. 253The 254.Fl -device 255option will point at the actual encrypted partition, while the 256.Ar system_device 257argument will point to the parent device (i.e.\& underlying physical disk) 258of the encrypted partition. 259.It Fl -fde 260This option is intended to be used with disks using full disk encryption (FDE). 261When a disk has been encrypted using TrueCrypt's FDE, the complete disk 262is encrypted except for the first 63 sectors. 263The 264.Fl -device 265option should point to the whole disk device, not to any particular 266partition. 267The resultant mapping will cover the whole disk, and will not appear as 268separate partitions. 269To access individual partitions after mapping, 270.Xr kpartx 8 271can be used. 272.It Fl -use-backup 273This option is intended to be used when the primary headers of a volume 274have been corrupted. 275This option will force 276.Nm 277to use the backup headers, which are located at the end of the device, 278to access the volume. 279.El 280.Pp 281Additional options only for the 282.Fl -map 283command are: 284.Bl -tag -width indent 285.It Fl t , Fl -allow-trim 286This option enables TRIM (discard) support on the mapped volume. 287.El 288.Pp 289Additional options only for the 290.Fl -modify 291command are: 292.Bl -tag -width indent 293.It Fl -new-pbkdf-prf Ns = Ns Ar pbkdf_hash 294Specifies which hash algorithm to use for the PBKDF2 password 295derivation on reencrypting the volume header. 296If this option is not specified, the reencrypted header will 297use the current PRF. 298To see which algorithms are supported, specify 299.Fl -pbkdf-prf Ns = Ns Cm help . 300.It Fl -new-keyfile Ns = Ns Ar keyfile 301Specifies a 302.Ar keyfile 303to use in addition to the new passphrase on reencrypting the 304volume header. 305This option can appear multiple times; if so, multiple 306keyfiles will be used. 307.It Fl -restore-from-backup-hdr 308If this option is specified, neither 309.Fl -new-pbkdf-prf 310nor 311.Fl -new-keyfile 312should be specified. 313This option implies 314.Fl -use-backup . 315Use this option to restore the volume headers from the backup 316header. 317.El 318.Pp 319Sending a 320.Dv SIGINFO 321or 322.Dv SIGUSR1 323signal to a running 324.Nm 325process makes it print progress on slower tasks 326such as gathering entropy or wiping the volume. 327.Sh NOTES 328TrueCrypt limits passphrases to 64 characters (including the terminating 329null character). 330To be compatible with it, 331.Nm 332does the same. 333All passphrases (excluding keyfiles) are trimmed to 64 characters. 334Similarly, keyfiles are limited to a size of 1 MB, but up to 335256 keyfiles can be used. 336.Sh PLAUSIBLE DENIABILITY 337.Nm 338offers plausible deniability. Hidden volumes are created within an outer 339volume. 340Which volume is accessed solely depends on the passphrase and keyfile(s) 341used. 342If the passphrase and keyfiles for the outer volume are specified, 343no information about the existence of the hidden volume is exposed. 344Without knowledge of the passphrase and keyfile(s) of the hidden volume 345its existence remains unexposed. 346The hidden volume can be protected when mapping the outer volume by 347using the 348.Fl -protect-hidden 349option and specifying the passphrase and keyfiles for both the outer 350and hidden volumes. 351.Sh EXAMPLES 352Create a new TrueCrypt volume on 353.Pa /dev/vn0 354using the cipher cascade 355of AES and Twofish and the Whirlpool hash algorithm for 356PBKDF2 password derivation and two keyfiles, 357.Pa one.key 358and 359.Pa two.key : 360.Bd -ragged -offset indent 361.Nm Fl -create 362.Fl -device Ns = Ns Cm /dev/vn0 363.Fl -cipher Ns = Ns Cm AES-256-XTS,TWOFISH-256-XTS 364.Fl -pbkdf-prf Ns = Ns Cm whirlpool 365.Fl -keyfile Ns = Ns Cm one.key 366.Fl -keyfile Ns = Ns Cm two.key 367.Ed 368.Pp 369Map the outer volume on the TrueCrypt volume on 370.Pa /dev/vn0 371as 372.Sy truecrypt1 , 373but protect the hidden volume, using the keyfile 374.Pa hidden.key , 375from being overwritten: 376.Bd -ragged -offset indent 377.Nm Fl -map Ns = Ns Cm truecrypt1 378.Fl -device Ns = Ns Cm /dev/vn0 379.Fl -protect-hidden 380.Fl -keyfile-hidden Ns = Ns Cm hidden.key 381.Ed 382.Pp 383Map the hidden volume on the TrueCrypt volume on 384.Pa /dev/vn0 385as 386.Sy truecrypt2 , 387using the keyfile 388.Pa hidden.key : 389.Bd -ragged -offset indent 390.Nm Fl -map Ns = Ns Cm truecrypt2 391.Fl -device Ns = Ns Cm /dev/vn0 392.Fl -keyfile Ns = Ns Cm hidden.key 393.Ed 394.Pp 395Map and mount the volume in the file 396.Pa secvol 397on Linux: 398.Bd -ragged -offset indent 399.Sy losetup Cm /dev/loop1 Cm secvol 400.Ed 401.Bd -ragged -offset indent 402.Nm Fl -map Ns = Ns Cm secv 403.Fl -device Ns = Ns Cm /dev/loop1 404.Ed 405.Bd -ragged -offset indent 406.Sy mount Cm /dev/mapper/secv Cm /mnt 407.Ed 408.Pp 409Similarly on 410.Dx : 411.Bd -ragged -offset indent 412.Sy vnconfig Cm vn1 Cm secvol 413.Ed 414.Bd -ragged -offset indent 415.Nm Fl -map Ns = Ns Cm secv 416.Fl -device Ns = Ns Cm /dev/vn1 417.Ed 418.Bd -ragged -offset indent 419.Sy mount Cm /dev/mapper/secv Cm /mnt 420.Ed 421.Pp 422Unmapping the volume 423.Sy truecrypt2 424on both Linux and 425.Dx 426after unmounting: 427.Bd -ragged -offset indent 428.Sy dmsetup Cm remove Cm truecrypt2 429.Ed 430.Pp 431Or alternatively: 432.Bd -ragged -offset indent 433.Nm Fl -unmap Ns = Ns Cm truecrypt2 434.Ed 435.Pp 436A hidden volume whose existence can be plausibly denied and its outer volume 437can for example be created with 438.Bd -ragged -offset indent 439.Nm Fl -create 440.Fl -hidden 441.Fl -device Ns = Ns Cm /dev/loop0 442.Fl -cipher Ns = Ns Cm AES-256-XTS,TWOFISH-256-XTS 443.Fl -pbkdf-prf Ns = Ns Cm whirlpool 444.Fl -keyfile Ns = Ns Cm one.key 445.Fl -cipher-hidden Ns = Ns Cm AES-256-XTS 446.Fl -pbkdf-prf-hidden Ns = Ns Cm whirlpool 447.Fl -keyfile-hidden Ns = Ns Cm hidden.key 448.Ed 449.Pp 450.Nm 451will prompt the user for the passphrase for both the outer and hidden volume 452as well as the size of the hidden volume inside the outer volume. 453The hidden volume will be created inside the area spanned by the outer volume. 454The hidden volume can optionally use a different cipher and prf function 455as specified by the 456.Fl -cipher-hidden 457and 458.Fl -pbkdf-prf-hidden 459options. 460Which volume is later accessed depends only on which passphrase and keyfile(s) 461are being used, 462so that the existence of the hidden volume remains unknown without knowledge 463of the passphrase and keyfile it is protected by since it is located within 464the outer volume. 465To map the outer volume without potentially damaging the hidden volume, 466the passphrase and keyfile(s) of the hidden volume must be known and provided 467alongside the 468.Fl -protect-hidden 469option. 470.Pp 471A disk encrypted using full disk encryption can be mapped using 472.Bd -ragged -offset indent 473.Nm Fl -map Ns = Ns Cm tcplay_sdb 474.Fl -device Ns = Ns Cm /dev/sdb 475.Fl -fde 476.Ed 477.Pp 478To access individual partitions on the now mapped disk, 479the following command will generate mappings for each 480individual partition on the encrypted disk: 481.Bd -ragged -offset indent 482.Sy kpartx Fl -av Cm /dev/mapper/tcplay_sdb 483.Ed 484.Pp 485To restore the main volume header from the backup header, the following 486command can be used: 487.Bd -ragged -offset indent 488.Nm Fl -modify 489.Fl -device Ns = Ns Cm /dev/sdb 490.Fl -restore-from-backup-hdr 491.Ed 492.Pp 493As with most other commands, which header is saved (used as source) depends 494on the passphrase and keyfiles used. 495.Pp 496To save a backup copy of a header, the following command can be used: 497.Bd -ragged -offset indent 498.Nm Fl -modify 499.Fl -device Ns = Ns Cm /dev/sdb 500.Fl -save-hdr-backup Ns = Ns Cm /tmp/sdb_backup_header.hdr 501.Ed 502.Pp 503As with most other commands, which header is saved (used as source) depends 504on the passphrase and keyfiles used. 505.Pp 506To restore a header from a backup header file, the following command can be 507used: 508.Bd -ragged -offset indent 509.Nm Fl -modify 510.Nm -use-hdr-file Ns = Ns Cm /tmp/sdb_backup_header.hdr 511.Ed 512.Pp 513Similarly, to restore a hidden header from a backup header file: 514.Bd -ragged -offset indent 515.Nm Fl -modify 516.Nm -use-hidden-hdr-file Ns = Ns Cm /tmp/sdb_backup_hidden_header.hdr 517.Ed 518.Pp 519Which header is used as the source of the operation will still depend on the 520passphrase and keyfiles used. 521Even if you use the 522.Fl -use-hidden-hdr-file 523option, if you specify the passphrase and keyfiles for the main header, the 524main header will be used instead. 525.Sh SEE ALSO 526.Xr crypttab 5 , 527.Xr cryptsetup 8 , 528.Xr dmsetup 8 , 529.Xr kpartx 8 530.Sh HISTORY 531The 532.Nm 533utility appeared in 534.Dx 2.11 . 535.Sh AUTHORS 536.An Alex Hornung 537