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 April 30, 2020 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.Op Fl -fde 52.Nm 53.Fl i 54.Fl d Ar device 55.Op Fl e 56.Op Fl p 57.Op Fl f Ar keyfile_hidden 58.Op Fl k Ar keyfile 59.Op Fl s Ar system_device 60.Op Fl -use-backup 61.Op Fl -use-hdr-file Ar hdr_file 62.Op Fl -use-hidden-hdr-file Ar hdr_file 63.Nm 64.Fl j Ar mapping 65.Nm 66.Fl m Ar mapping 67.Fl d Ar device 68.Op Fl e 69.Op Fl p 70.Op Fl f Ar keyfile_hidden 71.Op Fl k Ar keyfile 72.Op Fl s Ar system_device 73.Op Fl t 74.Op Fl -fde 75.Op Fl -use-backup 76.Op Fl -use-hdr-file Ar hdr_file 77.Op Fl -use-hidden-hdr-file Ar hdr_file 78.Nm 79.Fl -modify 80.Fl d Ar device 81.Op Fl k Ar keyfile 82.Op Fl -new-keyfile Ar new_keyfile 83.Op Fl -new-pbkdf-prf Ar pbkdf_hash 84.Op Fl s Ar system_device 85.Op Fl -fde 86.Op Fl -use-backup 87.Op Fl -use-hdr-file Ar hdr_file 88.Op Fl -use-hidden-hdr-file Ar hdr_file 89.Op Fl -save-hdr-backup Ar hdr_file 90.Op Fl w 91.Nm 92.Fl -modify 93.Fl d Ar device 94.Op Fl k Ar keyfile 95.Fl -restore-from-backup-hdr 96.Op Fl w 97.Nm 98.Fl u Ar mapping 99.Nm 100.Fl h | v 101.Sh DESCRIPTION 102The 103.Nm 104utility provides full support for creating and opening/mapping 105TrueCrypt-compatible volumes. 106It supports the following commands, each with a set of options 107detailed further below: 108.Bl -tag -width indent 109.It Fl c , Fl -create 110Create a new encrypted TrueCrypt volume on the device 111specified by 112.Fl -device . 113.It Fl h , Fl -help 114Print help message and exit. 115.It Fl i , Fl -info 116Print out information about the encrypted device specified by 117.Fl -device . 118.It Fl j Ar mapping , Fl -info-mapped Ns = Ns Ar mapping 119Print out information about the mapped tcplay volume specified 120by 121.Ar mapping . 122Information such as key CRC and the PBKDF2 PRF is not available 123via this command. 124.It Fl -modify 125Modify the volume header. 126This mode allows changing passphrase, keyfiles, PBKDF2 PRF as 127well as restoring from a backup header. 128.It Fl m Ar mapping , Fl -map Ns = Ns Ar mapping 129Map the encrypted TrueCrypt volume on the device specified by 130.Fl -device 131as a 132.Xr dm 4 133mapping called 134.Ar mapping . 135The 136.Ar mapping 137argument should not contain any spaces or special characters. 138.It Fl u Ar mapping , Fl -unmap Ns = Ns Ar mapping 139Removes (unmaps) the 140.Xr dm 4 141mapping specified by 142.Ar mapping 143as well as any related cascade mappings. 144.It Fl v , Fl -version 145Print version message and exit. 146.El 147.Pp 148Options common to all commands are: 149.Bl -tag -width indent 150.It Fl d Ar device , Fl -device Ns = Ns Ar device 151Specifies the disk 152.Ar device 153on which the TrueCrypt volume resides/will reside. 154This option is mandatory for all commands. 155.It Fl f Ar keyfile_hidden , Fl -keyfile-hidden Ns = Ns Ar keyfile_hidden 156Specifies a keyfile 157to use in addition to the passphrase when either creating a 158hidden volume or when protecting a hidden volume while mapping 159or querying the outer volume. 160If you only intend to map a hidden volume, the 161.Fl -keyfile 162option has to be used. 163This option can appear multiple times; if so, multiple 164keyfiles will be used. 165This option is not valid in the 166.Fl -modify 167mode. 168.It Fl k Ar keyfile , Fl -keyfile Ns = Ns Ar keyfile 169Specifies a 170.Ar keyfile 171to use in addition to the passphrase. 172This option can appear multiple times; if so, multiple 173keyfiles will be used. 174.El 175.Pp 176Additional options for the 177.Fl -create 178command are: 179.Bl -tag -width indent 180.It Fl a Ar pbkdf_hash , Fl -pbkdf-prf Ns = Ns Ar pbkdf_hash 181Specifies which hash algorithm to use for the PBKDF2 password 182derivation. 183To see which algorithms are supported, specify 184.Fl -pbkdf-prf Ns = Ns Cm help . 185.It Fl b Ar cipher , Fl -cipher Ns = Ns Ar cipher 186Specifies which cipher algorithm or cascade of ciphers to use 187to encrypt the new volume. 188To see which algorithms are supported, specify 189.Fl -cipher Ns = Ns Cm help . 190.It Fl g , Fl -hidden 191Specifies that the newly created volume will contain a hidden 192volume. 193The keyfiles applied to the passphrase for the hidden 194volume are those specified by 195.Fl -keyfile-hidden . 196The user will be prompted for the size of the hidden volume 197interactively. 198.It Fl w , Fl -weak-keys 199Use 200.Xr urandom 4 201for key material instead of a strong entropy source. 202This is in general a really bad idea and should only be used 203for testing. 204.It Fl x Ar pbkdf_hash , Fl -pbkdf-prf-hidden Ns = Ns Ar pbkdf_hash 205Specifies which hash algorithm to use for the PBKDF2 password 206derivation for the hidden volume. 207Only valid in conjunction with 208.Fl -hidden . 209If no algorithm is specified, the same as for the outer volume 210will be used. 211To see which algorithms are supported, specify 212.Fl -pbkdf-prf-hidden Ns = Ns Cm help . 213.It Fl y Ar cipher , Fl -cipher-hidden Ns = Ns Ar cipher 214Specifies which cipher algorithm or cascade of ciphers to use 215to encrypt the hidden volume on the new TrueCrypt volume. 216Only valid in conjunction with 217.Fl -hidden . 218If no cipher is specified, the same as for the outer volume 219will be used. 220To see which algorithms are supported, specify 221.Fl -cipher-hidden Ns = Ns Cm help . 222.It Fl z , Fl -insecure-erase 223Skips the secure erase of the disk. 224Use this option carefully as it is a security risk! 225.El 226.Pp 227Additional options for the 228.Fl -info , 229.Fl -map 230and 231.Fl -modify 232commands are: 233.Bl -tag -width indent 234.It Fl e , Fl -protect-hidden 235Specifies that an outer volume will be queried or mapped, but 236its reported size will be adjusted accordingly to the size of 237the hidden volume contained in it. 238Both the hidden volume and outer volume passphrase and keyfiles 239will be required. 240This option only applies to the 241.Fl -info 242and 243.Fl -map 244commands. 245.It Fl p, Fl -prompt-passphrase 246This option causes 247.Nm 248to prompt for a passphrase immediately, even if a keyfile is 249provided. 250Normally, if a keyfile is supplied, 251.Nm 252will first attempt to unlock the volume using only the keyfile, 253and only prompt for a passphrase if that first unlocking attempt 254fails. 255However, since a failed unlocking attempt can take a non-trivial 256amount of time, specifying this option can reduce the total unlocking 257time if both a keyfile and passphrase are required. 258This option only makes sense if 259.Fl k 260or 261.Fl f 262are used. 263.It Fl s Ar system_device , Fl -system-encryption Ns = Ns Ar system_device 264This option is required if you are attempting to access a device 265that uses system encryption, for example an encrypted 266.Tn Windows 267system partition. 268It does not apply to disks using full disk encryption. 269The 270.Fl -device 271option will point at the actual encrypted partition, while the 272.Ar system_device 273argument will point to the parent device (i.e.\& underlying physical disk) 274of the encrypted partition. 275.It Fl -fde 276This option is intended to be used with disks using full disk encryption (FDE). 277When a disk has been encrypted using TrueCrypt's FDE, the complete disk 278is encrypted except for the first 63 sectors. 279The 280.Fl -device 281option should point to the whole disk device, not to any particular 282partition. 283The resultant mapping will cover the whole disk, and will not appear as 284separate partitions. 285.It Fl -use-backup 286This option is intended to be used when the primary headers of a volume 287have been corrupted. 288This option will force 289.Nm 290to use the backup headers, which are located at the end of the device, 291to access the volume. 292.El 293.Pp 294Additional options only for the 295.Fl -map 296command are: 297.Bl -tag -width indent 298.It Fl t , Fl -allow-trim 299This option enables TRIM (discard) support on the mapped volume. 300.El 301.Pp 302Additional options only for the 303.Fl -modify 304command are: 305.Bl -tag -width indent 306.It Fl -new-pbkdf-prf Ns = Ns Ar pbkdf_hash 307Specifies which hash algorithm to use for the PBKDF2 password 308derivation on reencrypting the volume header. 309If this option is not specified, the reencrypted header will 310use the current PRF. 311To see which algorithms are supported, specify 312.Fl -pbkdf-prf Ns = Ns Cm help . 313.It Fl -new-keyfile Ns = Ns Ar keyfile 314Specifies a 315.Ar keyfile 316to use in addition to the new passphrase on reencrypting the 317volume header. 318This option can appear multiple times; if so, multiple 319keyfiles will be used. 320.It Fl -restore-from-backup-hdr 321If this option is specified, neither 322.Fl -new-pbkdf-prf 323nor 324.Fl -new-keyfile 325should be specified. 326This option implies 327.Fl -use-backup . 328Use this option to restore the volume headers from the backup 329header. 330.El 331.Pp 332Sending a 333.Dv SIGINFO 334or 335.Dv SIGUSR1 336signal to a running 337.Nm 338process makes it print progress on slower tasks 339such as gathering entropy or wiping the volume. 340.Sh NOTES 341TrueCrypt limits passphrases to 64 characters (including the terminating 342null character). 343To be compatible with it, 344.Nm 345does the same. 346All passphrases (excluding keyfiles) are trimmed to 64 characters. 347Similarly, keyfiles are limited to a size of 1 MB, but up to 348256 keyfiles can be used. 349.Sh PLAUSIBLE DENIABILITY 350.Nm 351offers plausible deniability. Hidden volumes are created within an outer 352volume. 353Which volume is accessed solely depends on the passphrase and keyfile(s) 354used. 355If the passphrase and keyfiles for the outer volume are specified, 356no information about the existence of the hidden volume is exposed. 357Without knowledge of the passphrase and keyfile(s) of the hidden volume 358its existence remains unexposed. 359The hidden volume can be protected when mapping the outer volume by 360using the 361.Fl -protect-hidden 362option and specifying the passphrase and keyfiles for both the outer 363and hidden volumes. 364.Sh VERACRYPT SUPPORT 365.Nm 366offers both legacy TrueCrypt as well as VeraCrypt support. 367When creating a new volume, the selected PBKDF2 PRF determines whether 368the volume will use the TrueCrypt or VeraCrypt format. 369The formats are identical other than the rounds of the key derivation 370functions as well as the volume signature and minver fields in the 371header. 372Converting volumes from one format or another using 373.Nm 374is simply a matter of using the 375.Fl -modify 376option specifying a PBKDF2 PRF hash matching the intended target format 377with the 378.Fl -new-pbkdf-prf 379argument. 380.Pp 381PBKDF2 PRFs suffixed with 382.Dv -VC 383are VeraCrypt PRFs, whilst all others are legacy TrueCrypt PRFs. 384By default, new volumes are created with a VeraCrypt PRF to offer better 385security. 386.Pp 387NOTE: Failed unlocking attempts even for legacy TrueCrypt volumes now take 388significantly longer than before, as 389.Nm 390will cycle through all PRFs, including the VeraCrypt PRFs with much higher 391number of PRF iterations. 392Successful attempts should still take the same amount of time as before, as 393the legacy PRF settings are tried first. 394One notable exception is if both a keyfile and a passphrase is required. 395Normally, 396.Nm 397would first attempt an unlock attempt with just the keyfile, and only prompt 398for a passphrase after that attempt failed. 399If it is known in advance that both a keyfile and passphrase are required to 400unlock a volume, the 401.Fl p 402option to 403.Fl -info 404and 405.Fl -map 406can more than halve the time required to unlock the volume. 407.Sh EXAMPLES 408Create a new TrueCrypt volume on 409.Pa /dev/vn0 410using the cipher cascade 411of AES and Twofish and the Whirlpool hash algorithm for 412PBKDF2 password derivation and two keyfiles, 413.Pa one.key 414and 415.Pa two.key : 416.Bd -ragged -offset indent 417.Nm Fl -create 418.Fl -device Ns = Ns Cm /dev/vn0 419.Fl -cipher Ns = Ns Cm TWOFISH-256-XTS,AES-256-XTS 420.Fl -pbkdf-prf Ns = Ns Cm whirlpool 421.Fl -keyfile Ns = Ns Cm one.key 422.Fl -keyfile Ns = Ns Cm two.key 423.Ed 424.Pp 425Map the outer volume on the TrueCrypt volume on 426.Pa /dev/vn0 427as 428.Sy truecrypt1 , 429but protect the hidden volume, using the keyfile 430.Pa hidden.key , 431from being overwritten: 432.Bd -ragged -offset indent 433.Nm Fl -map Ns = Ns Cm truecrypt1 434.Fl -device Ns = Ns Cm /dev/vn0 435.Fl -protect-hidden 436.Fl -keyfile-hidden Ns = Ns Cm hidden.key 437.Ed 438.Pp 439Map the hidden volume on the TrueCrypt volume on 440.Pa /dev/vn0 441as 442.Sy truecrypt2 , 443using the keyfile 444.Pa hidden.key : 445.Bd -ragged -offset indent 446.Nm Fl -map Ns = Ns Cm truecrypt2 447.Fl -device Ns = Ns Cm /dev/vn0 448.Fl -keyfile Ns = Ns Cm hidden.key 449.Ed 450.Pp 451Map and mount the volume in the file 452.Pa secvol : 453.Bd -ragged -offset indent 454.Sy vnconfig Cm vn1 Cm secvol 455.Ed 456.Bd -ragged -offset indent 457.Nm Fl -map Ns = Ns Cm secv 458.Fl -device Ns = Ns Cm /dev/vn1 459.Ed 460.Bd -ragged -offset indent 461.Sy mount Cm /dev/mapper/secv Cm /mnt 462.Ed 463.Pp 464Unmapping the volume 465.Sy truecrypt2 466after unmounting: 467.Bd -ragged -offset indent 468.Sy dmsetup Cm remove Cm truecrypt2 469.Ed 470.Pp 471Or alternatively: 472.Bd -ragged -offset indent 473.Nm Fl -unmap Ns = Ns Cm truecrypt2 474.Ed 475.Pp 476A hidden volume whose existence can be plausibly denied and its outer volume 477can for example be created with 478.Bd -ragged -offset indent 479.Nm Fl -create 480.Fl -hidden 481.Fl -device Ns = Ns Cm /dev/vn0 482.Fl -cipher Ns = Ns Cm TWOFISH-256-XTS,AES-256-XTS 483.Fl -pbkdf-prf Ns = Ns Cm whirlpool 484.Fl -keyfile Ns = Ns Cm one.key 485.Fl -cipher-hidden Ns = Ns Cm AES-256-XTS 486.Fl -pbkdf-prf-hidden Ns = Ns Cm whirlpool 487.Fl -keyfile-hidden Ns = Ns Cm hidden.key 488.Ed 489.Pp 490.Nm 491will prompt the user for the passphrase for both the outer and hidden volume 492as well as the size of the hidden volume inside the outer volume. 493The hidden volume will be created inside the area spanned by the outer volume. 494The hidden volume can optionally use a different cipher and prf function 495as specified by the 496.Fl -cipher-hidden 497and 498.Fl -pbkdf-prf-hidden 499options. 500Which volume is later accessed depends only on which passphrase and keyfile(s) 501are being used, 502so that the existence of the hidden volume remains unknown without knowledge 503of the passphrase and keyfile it is protected by since it is located within 504the outer volume. 505To map the outer volume without potentially damaging the hidden volume, 506the passphrase and keyfile(s) of the hidden volume must be known and provided 507alongside the 508.Fl -protect-hidden 509option. 510.Pp 511A disk encrypted using full disk encryption can be mapped using 512.Bd -ragged -offset indent 513.Nm Fl -map Ns = Ns Cm tcplay_da2 514.Fl -device Ns = Ns Cm /dev/da2 515.Fl -fde 516.Ed 517.Pp 518To restore the main volume header from the backup header, the following 519command can be used: 520.Bd -ragged -offset indent 521.Nm Fl -modify 522.Fl -device Ns = Ns Cm /dev/da2 523.Fl -restore-from-backup-hdr 524.Ed 525.Pp 526As with most other commands, which header is saved (used as source) depends 527on the passphrase and keyfiles used. 528.Pp 529To save a backup copy of a header, the following command can be used: 530.Bd -ragged -offset indent 531.Nm Fl -modify 532.Fl -device Ns = Ns Cm /dev/da2 533.Fl -save-hdr-backup Ns = Ns Cm /tmp/da2_backup_header.hdr 534.Ed 535.Pp 536As with most other commands, which header is saved (used as source) depends 537on the passphrase and keyfiles used. 538.Pp 539To restore a header from a backup header file, the following command can be 540used: 541.Bd -ragged -offset indent 542.Nm Fl -modify 543.Fl -device Ns = Ns Cm /dev/da2 544.Fl -use-hdr-file Ns = Ns Cm /tmp/da2_backup_header.hdr 545.Ed 546.Pp 547Similarly, to restore a hidden header from a backup header file: 548.Bd -ragged -offset indent 549.Nm Fl -modify 550.Fl -device Ns = Ns Cm /dev/da2 551.Fl -use-hidden-hdr-file Ns = Ns Cm /tmp/da2_backup_hidden_header.hdr 552.Ed 553.Pp 554Which header is used as the source of the operation will still depend on the 555passphrase and keyfiles used. 556Even if you use the 557.Fl -use-hidden-hdr-file 558option, if you specify the passphrase and keyfiles for the main header, the 559main header will be used instead. 560.Sh SEE ALSO 561.Xr crypttab 5 , 562.Xr cryptsetup 8 , 563.Xr dmsetup 8 564.Sh HISTORY 565The 566.Nm 567utility appeared in 568.Dx 2.11 . 569.Sh AUTHORS 570.An Alex Hornung 571