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