| blob | dfe4b3bd554bcb238e509b2892c5c0a03d1f15d7 |
1 .\"
2 .\" Copyright (c) 2011 The DragonFly Project. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\"
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in
12 .\" the documentation and/or other materials provided with the
13 .\" distribution.
14 .\" 3. Neither the name of The DragonFly Project nor the names of its
15 .\" contributors may be used to endorse or promote products derived
16 .\" from this software without specific, prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .Dd January 20, 2014
32 .Dt TCPLAY 3
33 .Os
34 .Sh NAME
35 .Nm tc_api_init ,
36 .Nm tc_api_uninit ,
37 .Nm tc_api_has ,
38 .Nm tc_api_cipher_iterate ,
39 .Nm tc_api_prf_iterate ,
40 .Nm tc_api_task_init ,
41 .Nm tc_api_task_uninit ,
42 .Nm tc_api_task_set ,
43 .Nm tc_api_task_do ,
44 .Nm tc_api_task_info_get ,
45 .Nm tc_api_task_get_error
46 .Nd TrueCrypt volume management
47 .Sh LIBRARY
48 .Lb libtcplay
49 .Sh SYNOPSIS
50 .In tcplay_api.h
51 .Ft typedef int
52 .Fn (*tc_api_cipher_iterator_fn) "void *priv" "const char *name" "int key_length_in_bits" "int ciphers_in_chain"
53 .Ft typedef int
54 .Fn (*tc_api_prf_iterator_fn) "void *priv" "const char *name"
55 .Ft typedef int
56 .Fn (*tc_api_state_change_fn) "void *priv" "const char *state" "int enter_state"
57 .Ft int
58 .Fn tc_api_init "int verbose"
59 .Ft int
60 .Fn tc_api_uninit "void"
61 .Ft int
62 .Fn tc_api_has "const char *feature"
63 .Ft int
64 .Fn tc_api_cipher_iterate "tc_api_cipher_iterator_fn fn" "void *priv"
65 .Ft int
66 .Fn tc_api_prf_iterate "tc_api_prf_iterator_fn fn" "void *priv"
67 .Ft tc_api_task
68 .Fn tc_api_task_init "const char *op"
69 .Ft int
70 .Fn tc_api_task_uninit "tc_api_task task"
71 .Ft int
72 .Fn tc_api_task_set "tc_api_task task" "const char *key" "..."
73 .Ft int
74 .Fn tc_api_task_do "tc_api_task task"
75 .Ft int
76 .Fn tc_api_task_info_get "tc_api_task task" "const char *key" "..."
77 .Ft const char *
78 .Fn tc_api_task_get_error "tc_api_task task"
79 .Sh DESCRIPTION
80 The
81 .Nm tcplay
82 library provides an interface to create, query, map and manage
83 TrueCrypt-compatible volumes.
84 .Pp
85 The
86 .Fn tc_api_init
87 function initializes the library internals and prepares it for use via
88 the API.
89 This function has to be called before using any other API function.
90 If the
91 .Fa verbose
92 argument is non-zero, then the library will output information such as
93 errors via stdout and stderr.
94 .Pp
95 The
96 .Fn tc_api_uninit
97 function clears up all internal secure memory, such as memory used for
98 decrypted headers, passphrases, keyfiles, etc.
99 .Pp
100 The
101 .Fn tc_api_has
102 function checks whether the loaded tcplay library has the feature
103 specified by the
104 .Fa feature
105 argument.
106 The current version of the
107 .Nm tcplay
108 library supports the following features:
109 .Bl -column "some_long_feature" "Description"
110 .It Sy Feature Ta Sy Description
111 .It Li trim Ta Allows enabling discards/TRIM when mapping a volume
112 .El
113 .Pp
114 The
115 .Fn tc_api_cipher_iterate
116 function passes every available cipher chain to the callback provided in the
117 .Fa fn
118 argument.
119 The
120 .Fa priv
121 argument is passed on every call of the callback function.
122 The name of the cipher chain is passed to the callback function in the
123 .Fa name
124 argument.
125 Similarly,
126 the
127 .Fa ciphers_in_chain
128 argument holds the number of ciphers in the current chain,
129 and
130 .Fa key_length_in_bits
131 holds the total key length for the cipher chain,
132 in bits.
133 .Pp
134 The
135 .Fn tc_api_prf_iterate
136 function passes every available cipher chain to the callback provided in the
137 .Fa fn
138 argument.
139 The
140 .Fa priv
141 argument is passed on every call of the callback function.
142 The name of the PKBDF2 PRF algorithm is passed to the callback function in the
143 .Fa name
144 argument.
145 .Pp
146 The
147 .Fn tc_api_task_init
148 function initializes and returns a
149 .Ft tc_api_task
150 opaque pointer that can be used to run
151 .Nm tcplay
152 commands.
153 Each task can be used only for a single
154 .Fn tc_api_task_do
155 call,
156 and must be deallocated using
157 .Fn tc_api_task_uninit .
158 The
159 .Fa op
160 argument can be one of the following:
161 .Bl -tag -width indent
162 .It Sy create
163 Create a new encrypted TrueCrypt volume.
164 .It Sy map
165 Map an existing TrueCrypt volume.
166 .It Sy info
167 Request information about an encrypted TrueCrypt volume.
168 .It Sy info_mapped
169 Request information about a mapped TrueCrypt volume.
170 .It Sy unmap
171 Unmap a mapped TrueCrypt volume.
172 .It Sy modify
173 Modify the TrueCrypt volume by changing the passphrase, keyfiles, PRF algorithm,
174 restoring from a backup header, restoring from a header file or saving to a header file.
175 .It Sy restore
176 Modify the TrueCrypt volume as
177 .Sy modify
178 does, but without changing the passphrase, keyfiles or PRF algorithm.
179 .El
180 .Pp
181 The
182 .Fn tc_api_task_set
183 function allows settting a number of different options for the current task.
184 The following table shows which keys are available on calls to
185 .Fn tc_api_task_set
186 for each of the operations.
187 The letter
188 .Sy M
189 indicates the setting is mandatory,
190 whilst
191 .Sy *
192 indicates the setting is optional.
193 .Bl -column "hidden_header_from_filexxx" "createxxx" "infoxxx" "mapxxx" "unmapxxx" "info_mappedxxx" "modifyxxx" "restorexxx"
194 .It Sy Key Ta Sy create Ta Sy info Ta Sy map Ta Sy unmap Ta Sy info_mapped Ta Sy modify Ta Sy restore
195 .It Li dev Ta "M" Ta "M" Ta "M" Ta "*" Ta Ta "M" Ta "M"
196 .It Li map_name Ta Ta Ta "M" Ta "M" Ta "M" Ta Ta ""
197 .It Li interactive Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
198 .It Li retries Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
199 .It Li timeout Ta "*" Ta "*" Ta "*" Ta Ta Ta Ta ""
200 .It Li state_change_fn Ta "*" Ta Ta Ta Ta Ta "*" Ta "*"
201 .It Li weak_keys_and_salt Ta "*" Ta Ta Ta Ta Ta "*" Ta "*"
202 .It Li secure_erase Ta "*" Ta Ta Ta Ta Ta Ta ""
203 .It Li hidden_size_bytes Ta "*" Ta Ta Ta Ta Ta Ta ""
204 .It Li prf_algo Ta "*" Ta Ta Ta Ta Ta Ta ""
205 .It Li h_prf_algo Ta "*" Ta Ta Ta Ta Ta Ta ""
206 .It Li cipher_chain Ta "*" Ta Ta Ta Ta Ta Ta ""
207 .It Li h_cipher_chain Ta "*" Ta Ta Ta Ta Ta Ta ""
208 .It Li protect_hidden Ta Ta "*" Ta "*" Ta Ta Ta Ta ""
209 .It Li fde Ta Ta "*" Ta "*" Ta Ta Ta Ta ""
210 .It Li sys Ta Ta "*" Ta "*" Ta Ta Ta "?" Ta "?"
211 .It Li use_backup_header Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
212 .It Li header_from_file Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
213 .It Li hidden_header_from_file Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
214 .It Li allow_trim Ta Ta Ta "*" Ta Ta Ta Ta ""
215 .It Li save_header_to_file Ta Ta Ta Ta Ta Ta "*" Ta ""
216 .It Li passphrase Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
217 .It Li h_passphrase Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
218 .It Li keyfiles Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
219 .It Li h_keyfiles Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*"
220 .It Li new_passphrase Ta Ta Ta Ta Ta Ta "*" Ta ""
221 .It Li new_keyfiles Ta Ta Ta Ta Ta Ta "*" Ta ""
222 .It Li new_prf_algo Ta Ta Ta Ta Ta Ta "*" Ta ""
223 .El
224 The varargs accepted by the
225 .Fn tc_api_task_set
226 function depend on the key being set.
227 .Bl -tag -width indent
228 .It dev
229 The vararg is of type
230 .Ft const char * .
231 It sets the device that contains the TrueCrypt volume to operate on.
232 .It map_name
233 The vararg is of type
234 .Ft const char * .
235 It set the name of the mapped volume.
236 .It interactive
237 The vararg is of type
238 .Ft int .
239 It determines whether the user will be prompted for a passphrase or whether
240 the settings are taken from the arguments set using
241 .Fn tc_api_task_set .
242 .It retries
243 The vararg is of type
244 .Ft int .
245 It determines the number of passphrase retries if
246 .Fa interactive
247 is set.
248 .It weak_keys_and_salt
249 The vararg is of type
250 .Ft int .
251 It determines whether to use a weak source of entropy for key material and/or
252 the salt.
253 .It secure_erase
254 The vararg is of type
255 .Ft int .
256 It determines whether a secure erase is performed as part of the volume creation.
257 .It hidden_size_bytes
258 The vararg is of type
259 .Ft int64_t .
260 If set to
261 .Fa 0
262 it implies no hidden volume will be created.
263 A positive value implies a hidden volume of the specified size in bytes is created.
264 .It prf_algo
265 The vararg is of type
266 .Ft const char *
267 and must be a valid PBKDF2 PRF algorithm.
268 It determines which PBKDF2 PRF algorithm is used for the outer volume.
269 .It h_prf_algo
270 The vararg is of type
271 .Ft const char *
272 and must be a valid PBKDF2 PRF algorithm.
273 It determines which PBKDF2 PRF algorithm is used for the hidden volume.
274 .It cipher_chain
275 The vararg is of type
276 .Ft const char *
277 and must be a valid
278 .Nm tcplay
279 cipher chain.
280 It determines which cipher chain is used to encrypt the outer volume.
281 .It h_cipher_chain
282 The vararg is of type
283 .Ft const char *
284 and must be a valid
285 .Nm tcplay
286 cipher chain.
287 It determines which cipher chain is used to encrypt the hidden volume.
288 .It protect_hidden
289 The vararg is of type
290 .Ft int .
291 It determines whether the size of the outer volume should be adjusted to protect
292 any hidden volume.
293 Using this mode requires both outer and hidden passphrases and keyfiles.
294 .It sys
295 The vararg is of type
296 .Ft const char * .
297 It determines whether the volume is a system encrypted volume,
298 and if so, which disk is the system disk and hence contains the header.
299 If set to
300 .Dv NULL
301 the volume will implicitly be treated as a non-system encrypted volume.
302 .It fde
303 The vararg is of type
304 .Ft int .
305 It determines whether the disk uses full disk encryption or not.
306 If specified, the device pointed to by the
307 .Fa dev
308 setting should be a whole disk device, not any partition.
309 The device will be mapped or queried as a whole.
310 To access individual partitions, a utility such as
311 .Xr kpartx 8
312 should be used, which will create additional individual mappings
313 for each partition in the decrypted mapped volume.
314 For more details on full disk encryption, see
315 .Xr tcplay 8 .
316 .It use_backup_header
317 The vararg is of type
318 .Ft int .
319 It determines whether the backup header should be used instead of the regular
320 header to access the volume.
321 .It header_from_file
322 The vararg is of type
323 .Ft const char * .
324 If not
325 .Dv NULL
326 it forces
327 .Nm tcplay
328 to use the header in the specified file instead of the regular outer volume header.
329 .It hidden_header_from_file
330 The vararg is of type
331 .Ft const char * .
332 If not
333 .Dv NULL
334 it forces
335 .Nm tcplay
336 to use the header in the specified file instead of the regular hidden volume header.
337 .It allow_trim
338 The vararg is of type
339 .Ft int .
340 It specifies whether the mapped volume should allow discards (TRIM).
341 .It save_header_to_file
342 The vararg is of type
343 .Ft const char * .
344 If not
345 .Dv NULL
346 it forces
347 .Nm tcplay
348 to write the (modified) header to the specified file instead of replacing the volume
349 headers.
350 .It passphrase
351 The vararg is of type
352 .Ft const char * .
353 It sets the passphrase that
354 .Nm tcplay
355 uses to access the volume.
356 .It h_passphrase
357 The vararg is of type
358 .Ft const char * .
359 It sets the passphrase that
360 .Nm tcplay
361 uses to unlock the hidden volume header.
362 This option is only used if a hidden volume is being created or the
363 .Fa protect_hidden
364 setting is set.
365 Otherwise
366 .Nm tcplay
367 will first use the regular passphrase to try to unlock the outer volume and then
368 try to unlock the hidden volume header with the same passphrase without ever
369 using
370 .Fa h_passphrase .
371 .It keyfiles
372 The vararg is of type
373 .Ft const char * .
374 If not
375 .Dv NULL
376 the given keyfile will be added to the keyfile pool.
377 Multiple calls to set this option with a non-
378 .Dv NULL
379 argument result add additional keyfiles.
380 If
381 .Dv NULL
382 all keyfiles are cleared.
383 .It h_keyfiles
384 The vararg is of type
385 .Ft const char * .
386 If not
387 .Dv NULL
388 the given keyfile will be added to the keyfile pool.
389 Multiple calls to set this option with a non-
390 .Dv NULL
391 argument result add additional keyfiles.
392 If
393 .Dv NULL
394 all keyfiles are cleared.
395 This option is only used if a hidden volume is being created or the
396 .Fa protect_hidden
397 setting is set.
398 Otherwise
399 .Nm tcplay
400 will first use the regular keyfiles to try to unlock the outer volume and then
401 try to unlock the hidden volume header with the same keyfiles without ever
402 using
403 .Fa h_keyfiles .
404 .It new_passphrase
405 The vararg is of type
406 .Fa const char * .
407 It specifies the new passphrase to use when modifying the volume header.
408 .It new_keyfiles
409 The vararg is of type
410 .Fa const char * .
411 If not
412 .Dv NULL
413 the given keyfile will be added to the new keyfile pool.
414 Multiple calls to set this option with a non-
415 .Dv NULL
416 argument result add additional keyfiles.
417 If
418 .Dv NULL
419 all new keyfiles are cleared.
420 When the volume header is modified,
421 it will be reencrypted using the new keyfiles.
422 .It new_prf_algo
423 The vararg is of type
424 .Ft const char *
425 and must be a valid PBKDF2 PRF algorithm.
426 It determines which PBKDF2 PRF algorithm is used when reencrypting the (modified)
427 volume header.
428 .It state_change_fn
429 The first vararg is of type
430 .Fa tc_api_state_change_fn
431 and the second vararg is of type
432 .Fa void * .
433 It allows the consumer to provide a callback function which will be called when
434 starting and stopping a time-intensive sub-operation such as collecting entropy
435 or erasing a volume.
436 The second vararg is passed as the
437 .Fa priv
438 argument to the callback.
439 The
440 .Fa enter_state
441 argument to the callback determines whether
442 .Nm tcplay
443 is starting or stopping the time-intensive sub-task specified in the
444 .Fa state
445 argument.
446 .El
447 .Pp
448 The
449 .Fn tc_api_task_do
450 function runs the task specified in the
451 .Fa task
452 argument.
453 Before running the task,
454 .Fn tc_api_task_do
455 performs a simple sanity check of the arguments set previously using
456 .Fn tc_api_task_set
457 before performing the actual operation.
458 After a call to
459 .Fn tc_api_task_do
460 for the
461 .Sy info
462 or
463 .Sy info_mapped
464 operations,
465 the queried information is available to be accessed using
466 .Fn tc_api_task_info_get .
467 .Pp
468 The
469 .Fn tc_api_task_info_get
470 function can be used to query the result of a
471 .Sy info
472 or
473 .Sy info_mapped
474 operation.
475 The
476 .Fa task
477 argument is the task used in a previous
478 .Fn tc_api_task_do
479 call.
480 The
481 .Fa key
482 argument can be one of the following:
483 .Bl -column "some_long_feature" "very_long_type" "Description"
484 .It Sy Key Ta Sy type Ta Sy Description
485 .It Li device Ta Ft char * Ta Corresponding device node
486 .It Li cipher Ta Ft char * Ta Used cipher chain
487 .It Li prf Ta Ft char * Ta Used PBKDF2 PRF algorithm
488 .It Li key_bits Ta Ft int * Ta Number of key bits
489 .It Li size Ta Ft int64_t * Ta Volume size in bytes
490 .It Li iv_offset Ta Ft int64_t * Ta IV Offset of volume in bytes
491 .It Li block_offset Ta Ft int64_t * Ta Block Offset of volume in bytes
492 .El
493 .Pp
494 The second vararg argument must be of the type specified in the above table.
495 The first vararg argument is always the size of the storage provided
496 in the second argument.
497 For a
498 .Ft char *
499 argument, the size corresponds to the size of the buffer at the provided
500 location and must be of type
501 .Ft size_t .
502 For an
503 .Ft int *
504 or
505 .Ft int64_t *
506 argument, it should be the size of the underlying type.
507 .Pp
508 The
509 .Fn tc_api_task_get_error
510 function can be used to get a detailed error message after a failed
511 .Fa tc_api_task_do
512 call.
513 The
514 .Fa task
515 argument is the task used in a previous
516 .Fn tc_api_task_do
517 call.
518 .Sh NOTES
519 TrueCrypt limits passphrases to 64 characters (including the terminating
520 null character).
521 To be compatible with it,
522 .Nm tcplay
523 does the same.
524 All passphrases (exlcuding keyfiles) are trimmed to 64 characters.
525 Similarly, keyfiles are limited to a size of 1 MB, but up to 256
526 keyfiles can be used.
527 .Sh RETURN VALUES
528 All functions except
529 .Fn tc_api_task_init
530 and
531 .Fn tc_api_task_get_error
532 return either
533 .Dv TC_OK
534 to indicate that the operation completed successfully, or
535 .Dv TC_ERR_UNIMPL
536 to indicate that the operation is not implemented
537 , or
538 .Dv TC_ERR
539 to indicate that any other error occurred.
540 .Pp
541 The
542 .Fn tc_api_task_get_error
543 function always return a valid, but possibly empty (or irrelevant,
544 if not called after an error occurred) string.
545 .Pp
546 The
547 .Fn tc_api_task_init
548 function returns
549 .Dv NULL
550 if an error occurred and an opaque
551 .Ft tc_api_task
552 otherwise.
553 .Sh COMPATIBILITY
554 The
555 .Nm tcplay
556 library offers full compatibility with TrueCrypt volumes including
557 hidden
558 volumes, system encryption (map-only), keyfiles and cipher cascading.
559 .Sh SEE ALSO
560 .Xr tcplay 8 ,
561 .Xr kpartx 8
562 .Sh HISTORY
563 The
564 .Nm tcplay
565 library appeared in
566 .Dx 2.11 .
567 .Sh AUTHORS
568 .An Alex Hornung