sbin/tcplay/tcplay.8

   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
 100 The
 101 .Nm
 102 utility provides full support for creating and opening/mapping
 103 TrueCrypt-compatible volumes.
 104 It supports the following commands, each with a set of options
 105 detailed further below:
 106 .Bl -tag -width indent
 107 .It Fl c , Fl -create
 108 Create a new encrypted TrueCrypt volume on the device
 109 specified by
 110 .Fl -device .
 111 .It Fl h, Fl -help
 112 Print help message and exit.
 113 .It Fl i , Fl -info
 114 Print out information about the encrypted device specified by
 115 .Fl -device .
 116 .It Fl j Ar mapping , Fl -info-mapped Ns = Ns Ar mapping
 117 Print out information about the mapped tcplay volume specified
 118 by
 119 .Ar mapping .
 120 Information such as key CRC and the PBKDF2 PRF is not available
 121 via this command.
 122 .It Fl -modify
 123 Modify the volume header.
 124 This mode allows changing passphrase, keyfiles, PBKDF2 PRF as
 125 well as restoring from a backup header.
 126 .It Fl m Ar mapping , Fl -map Ns = Ns Ar mapping
 127 Map the encrypted TrueCrypt volume on the device specified by
 128 .Fl -device
 129 as a
 130 .Xr dm 4
 131 mapping called
 132 .Ar mapping .
 133 The
 134 .Ar mapping
 135 argument should not contain any spaces or special characters.
 136 .It Fl u Ar mapping , Fl -unmap Ns = Ns Ar mapping
 137 Removes (unmaps) the
 138 .Xr dm 4
 139 mapping specified by
 140 .Ar mapping
 141 as well as any related cascade mappings.
 142 If you mapped a volume using full disk encryption and created
 143 mapping for individual partitions using
 144 .Xr kpartx 8 ,
 145 you must remove these prior to unmapping the volume.
 146 .It Fl v, Fl -version
 147 Print version message and exit.
 148 .El
 149 .Pp
 150 Options common to all commands are:
 151 .Bl -tag -width indent
 152 .It Fl d Ar device , Fl -device Ns = Ns Ar device
 153 Specifies the disk
 154 .Ar device
 155 on which the TrueCrypt volume resides/will reside.
 156 This option is mandatory for all commands.
 157 .It Fl f Ar keyfile_hidden , Fl -keyfile-hidden Ns = Ns Ar keyfile_hidden
 158 Specifies a keyfile
 159 to use in addition to the passphrase when either creating a
 160 hidden volume or when protecting a hidden volume while mapping
 161 or querying the outer volume.
 162 If you only intend to map a hidden volume, the
 163 .Fl -keyfile
 164 option has to be used.
 165 This option can appear multiple times; if so, multiple
 166 keyfiles will be used.
 167 This option is not valid in the
 168 .Fl -modify
 169 mode.
 170 .It Fl k Ar keyfile , Fl -keyfile Ns = Ns Ar keyfile
 171 Specifies a
 172 .Ar keyfile
 173 to use in addition to the passphrase.
 174 This option can appear multiple times; if so, multiple
 175 keyfiles will be used.
 176 .El
 177 .Pp
 178 Additional options for the
 179 .Fl -create
 180 command are:
 181 .Bl -tag -width indent
 182 .It Fl a Ar pbkdf_hash , Fl -pbkdf-prf Ns = Ns Ar pbkdf_hash
 183 Specifies which hash algorithm to use for the PBKDF2 password
 184 derivation.
 185 To 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
 188 Specifies which cipher algorithm or cascade of ciphers to use
 189 to encrypt the new volume.
 190 To see which algorithms are supported, specify
 191 .Fl -cipher Ns = Ns Cm help .
 192 .It Fl g, Fl -hidden
 193 Specifies that the newly created volume will contain a hidden
 194 volume.
 195 The keyfiles applied to the passphrase for the hidden
 196 volume are those specified by
 197 .Fl -keyfile-hidden .
 198 The user will be prompted for the size of the hidden volume
 199 interactively.
 200 .It Fl w, Fl -weak-keys
 201 Use
 202 .Xr urandom 4
 203 for key material instead of a strong entropy source.
 204 This is in general a really bad idea and should only be used
 205 for testing.
 206 .It Fl x Ar pbkdf_hash , Fl -pbkdf-prf-hidden Ns = Ns Ar pbkdf_hash
 207 Specifies which hash algorithm to use for the PBKDF2 password
 208 derivation for the hidden volume.
 209 Only valid in conjunction with
 210 .Fl -hidden .
 211 If no algorithm is specified, the same as for the outer volume
 212 will be used.
 213 To 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
 216 Specifies which cipher algorithm or cascade of ciphers to use
 217 to encrypt the hidden volume on the new TrueCrypt volume.
 218 Only valid in conjunction with
 219 .Fl -hidden .
 220 If no cipher is specified, the same as for the outer volume
 221 will be used.
 222 To see which algorithms are supported, specify
 223 .Fl -cipher-hidden Ns = Ns Cm help .
 224 .It Fl z, Fl -insecure-erase
 225 Skips the secure erase of the disk.
 226 Use this option carefully as it is a security risk!
 227 .El
 228 .Pp
 229 Additional options for the
 230 .Fl -info ,
 231 .Fl -map
 232 and
 233 .Fl -modify
 234 commands are:
 235 .Bl -tag -width indent
 236 .It Fl e, Fl -protect-hidden
 237 Specifies that an outer volume will be queried or mapped, but
 238 its reported size will be adjusted accordingly to the size of
 239 the hidden volume contained in it.
 240 Both the hidden volume and outer volume passphrase and keyfiles
 241 will be required.
 242 This option only applies to the
 243 .Fl -info
 244 and
 245 .Fl -map
 246 commands.
 247 .It Fl s Ar system_device , Fl -system-encryption Ns = Ns Ar system_device
 248 This option is required if you are attempting to access a device
 249 that uses system encryption, for example an encrypted
 250 .Tn Windows
 251 system partition.
 252 It does not apply to disks using full disk encryption.
 253 The
 254 .Fl -device
 255 option will point at the actual encrypted partition, while the
 256 .Ar system_device
 257 argument will point to the parent device (i.e.\& underlying physical disk)
 258 of the encrypted partition.
 259 .It Fl -fde
 260 This option is intended to be used with disks using full disk encryption (FDE).
 261 When a disk has been encrypted using TrueCrypt's FDE, the complete disk
 262 is encrypted except for the first 63 sectors.
 263 The
 264 .Fl -device
 265 option should point to the whole disk device, not to any particular
 266 partition.
 267 The resultant mapping will cover the whole disk, and will not appear as
 268 separate partitions.
 269 To access individual partitions after mapping,
 270 .Xr kpartx 8
 271 can be used.
 272 .It Fl -use-backup
 273 This option is intended to be used when the primary headers of a volume
 274 have been corrupted.
 275 This option will force
 276 .Nm
 277 to use the backup headers, which are located at the end of the device,
 278 to access the volume.
 279 .El
 280 .Pp
 281 Additional options only for the
 282 .Fl -map
 283 command are:
 284 .Bl -tag -width indent
 285 .It Fl t , Fl -allow-trim
 286 This option enables TRIM (discard) support on the mapped volume.
 287 .El
 288 .Pp
 289 Additional options only for the
 290 .Fl -modify
 291 command are:
 292 .Bl -tag -width indent
 293 .It Fl -new-pbkdf-prf Ns = Ns Ar pbkdf_hash
 294 Specifies which hash algorithm to use for the PBKDF2 password
 295 derivation on reencrypting the volume header.
 296 If this option is not specified, the reencrypted header will
 297 use the current PRF.
 298 To see which algorithms are supported, specify
 299 .Fl -pbkdf-prf Ns = Ns Cm help .
 300 .It Fl -new-keyfile Ns = Ns Ar keyfile
 301 Specifies a
 302 .Ar keyfile
 303 to use in addition to the new passphrase on reencrypting the
 304 volume header.
 305 This option can appear multiple times; if so, multiple
 306 keyfiles will be used.
 307 .It Fl -restore-from-backup-hdr
 308 If this option is specified, neither
 309 .Fl -new-pbkdf-prf
 310 nor
 311 .Fl -new-keyfile
 312 should be specified.
 313 This option implies
 314 .Fl -use-backup .
 315 Use this option to restore the volume headers from the backup
 316 header.
 317 .El
 318 .Pp
 319 Sending a
 320 .Dv SIGINFO
 321 or
 322 .Dv SIGUSR1
 323 signal to a running
 324 .Nm
 325 process makes it print progress on slower tasks
 326 such as gathering entropy or wiping the volume.
 327 .Sh NOTES
 328 TrueCrypt limits passphrases to 64 characters (including the terminating
 329 null character).
 330 To be compatible with it,
 331 .Nm
 332 does the same.
 333 All passphrases (excluding keyfiles) are trimmed to 64 characters.
 334 Similarly, keyfiles are limited to a size of 1 MB, but up to
 335 256 keyfiles can be used.
 336 .Sh PLAUSIBLE DENIABILITY
 337 .Nm
 338 offers plausible deniability. Hidden volumes are created within an outer
 339 volume.
 340 Which volume is accessed solely depends on the passphrase and keyfile(s)
 341 used.
 342 If the passphrase and keyfiles for the outer volume are specified,
 343 no information about the existence of the hidden volume is exposed.
 344 Without knowledge of the passphrase and keyfile(s) of the hidden volume
 345 its existence remains unexposed.
 346 The hidden volume can be protected when mapping the outer volume by
 347 using the
 348 .Fl -protect-hidden
 349 option and specifying the passphrase and keyfiles for both the outer
 350 and hidden volumes.
 351 .Sh EXAMPLES
 352 Create a new TrueCrypt volume on
 353 .Pa /dev/vn0
 354 using the cipher cascade
 355 of AES and Twofish and the Whirlpool hash algorithm for
 356 PBKDF2 password derivation and two keyfiles,
 357 .Pa one.key
 358 and
 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
 369 Map the outer volume on the TrueCrypt volume on
 370 .Pa /dev/vn0
 371 as
 372 .Sy truecrypt1 ,
 373 but protect the hidden volume, using the keyfile
 374 .Pa hidden.key ,
 375 from 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
 383 Map the hidden volume on the TrueCrypt volume on
 384 .Pa /dev/vn0
 385 as
 386 .Sy truecrypt2 ,
 387 using 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
 395 Map and mount the volume in the file
 396 .Pa secvol
 397 on 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
 409 Similarly 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
 422 Unmapping the volume
 423 .Sy truecrypt2
 424 on both Linux and
 425 .Dx
 426 after unmounting:
 427 .Bd -ragged -offset indent
 428 .Sy dmsetup Cm remove Cm truecrypt2
 429 .Ed
 430 .Pp
 431 Or alternatively:
 432 .Bd -ragged -offset indent
 433 .Nm Fl -unmap Ns = Ns Cm truecrypt2
 434 .Ed
 435 .Pp
 436 A hidden volume whose existence can be plausibly denied and its outer volume
 437 can 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
 451 will prompt the user for the passphrase for both the outer and hidden volume
 452 as well as the size of the hidden volume inside the outer volume.
 453 The hidden volume will be created inside the area spanned by the outer volume.
 454 The hidden volume can optionally use a different cipher and prf function
 455 as specified by the
 456 .Fl -cipher-hidden
 457 and
 458 .Fl -pbkdf-prf-hidden
 459 options.
 460 Which volume is later accessed depends only on which passphrase and keyfile(s)
 461 are being used,
 462 so that the existence of the hidden volume remains unknown without knowledge
 463 of the passphrase and keyfile it is protected by since it is located within
 464 the outer volume.
 465 To map the outer volume without potentially damaging the hidden volume,
 466 the passphrase and keyfile(s) of the hidden volume must be known and provided
 467 alongside the
 468 .Fl -protect-hidden
 469 option.
 470 .Pp
 471 A 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
 478 To access individual partitions on the now mapped disk,
 479 the following command will generate mappings for each
 480 individual partition on the encrypted disk:
 481 .Bd -ragged -offset indent
 482 .Sy kpartx Fl -av Cm /dev/mapper/tcplay_sdb
 483 .Ed
 484 .Pp
 485 To restore the main volume header from the backup header, the following
 486 command 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
 493 As with most other commands, which header is saved (used as source) depends
 494 on the passphrase and keyfiles used.
 495 .Pp
 496 To 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
 503 As with most other commands, which header is saved (used as source) depends
 504 on the passphrase and keyfiles used.
 505 .Pp
 506 To restore a header from a backup header file, the following command can be
 507 used:
 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
 513 Similarly, 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
 519 Which header is used as the source of the operation will still depend on the
 520 passphrase and keyfiles used.
 521 Even if you use the
 522 .Fl -use-hidden-hdr-file
 523 option, if you specify the passphrase and keyfiles for the main header, the
 524 main 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
 531 The
 532 .Nm
 533 utility appeared in
 534 .Dx 2.11 .
 535 .Sh AUTHORS
 536 .An Alex Hornung