| blob | 376b9aeb56939136dba3d543f5b6f4d7584b6408 |
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