2 .\" Copyright (c) 2011 The DragonFly Project. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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
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.
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
38 .Nm tc_api_cipher_iterate ,
39 .Nm tc_api_prf_iterate ,
40 .Nm tc_api_task_init ,
41 .Nm tc_api_task_uninit ,
44 .Nm tc_api_task_info_get ,
45 .Nm tc_api_task_get_error
46 .Nd TrueCrypt volume management
52 .Fn (*tc_api_cipher_iterator_fn) "void *priv" "const char *name" "int key_length_in_bits" "int ciphers_in_chain"
54 .Fn (*tc_api_prf_iterator_fn) "void *priv" "const char *name"
56 .Fn (*tc_api_state_change_fn) "void *priv" "const char *state" "int enter_state"
58 .Fn tc_api_init "int verbose"
60 .Fn tc_api_uninit "void"
62 .Fn tc_api_has "const char *feature"
64 .Fn tc_api_cipher_iterate "tc_api_cipher_iterator_fn fn" "void *priv"
66 .Fn tc_api_prf_iterate "tc_api_prf_iterator_fn fn" "void *priv"
68 .Fn tc_api_task_init "const char *op"
70 .Fn tc_api_task_uninit "tc_api_task task"
72 .Fn tc_api_task_set "tc_api_task task" "const char *key" "..."
74 .Fn tc_api_task_do "tc_api_task task"
76 .Fn tc_api_task_info_get "tc_api_task task" "const char *key" "..."
78 .Fn tc_api_task_get_error "tc_api_task task"
82 library provides an interface to create, query, map and manage
83 TrueCrypt-compatible volumes.
87 function initializes the library internals and prepares it for use via
89 This function has to be called before using any other API function.
92 argument is non-zero, then the library will output information such as
93 errors via stdout and stderr.
97 function clears up all internal secure memory, such as memory used for
98 decrypted headers, passphrases, keyfiles, etc.
102 function checks whether the loaded tcplay library has the feature
106 The current version of the
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
115 .Fn tc_api_cipher_iterate
116 function passes every available cipher chain to the callback provided in the
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
128 argument holds the number of ciphers in the current chain,
130 .Fa key_length_in_bits
131 holds the total key length for the cipher chain,
135 .Fn tc_api_prf_iterate
136 function passes every available cipher chain to the callback provided in the
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
148 function initializes and returns a
150 opaque pointer that can be used to run
153 Each task can be used only for a single
156 and must be deallocated using
157 .Fn tc_api_task_uninit .
160 argument can be one of the following:
161 .Bl -tag -width indent
163 Create a new encrypted TrueCrypt volume.
165 Map an existing TrueCrypt volume.
167 Request information about an encrypted TrueCrypt volume.
169 Request information about a mapped TrueCrypt volume.
171 Unmap a mapped TrueCrypt volume.
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.
176 Modify the TrueCrypt volume as
178 does, but without changing the passphrase, keyfiles or PRF algorithm.
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
186 for each of the operations.
189 indicates the setting is mandatory,
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 ""
225 The varargs accepted by the
227 function depend on the key being set.
228 .Bl -tag -width indent
230 The vararg is of type
232 It sets the device that contains the TrueCrypt volume to operate on.
234 The vararg is of type
236 It set the name of the mapped volume.
238 The vararg is of type
240 It determines whether the user will be prompted for a passphrase or whether
241 the settings are taken from the arguments set using
242 .Fn tc_api_task_set .
244 The vararg is of type
246 It determines the number of passphrase retries if
249 .It weak_keys_and_salt
250 The vararg is of type
252 It determines whether to use a weak source of entropy for key material and/or
255 The vararg is of type
257 It determines whether a secure erase is performed as part of the volume creation.
258 .It hidden_size_bytes
259 The vararg is of type
263 it implies no hidden volume will be created.
264 A positive value implies a hidden volume of the specified size in bytes is created.
266 The vararg is of type
268 and must be a valid PBKDF2 PRF algorithm.
269 It determines which PBKDF2 PRF algorithm is used for the outer volume.
271 The vararg is of type
273 and must be a valid PBKDF2 PRF algorithm.
274 It determines which PBKDF2 PRF algorithm is used for the hidden volume.
276 The vararg is of type
281 It determines which cipher chain is used to encrypt the outer volume.
283 The vararg is of type
288 It determines which cipher chain is used to encrypt the hidden volume.
290 The vararg is of type
292 It determines whether the size of the outer volume should be adjusted to protect
294 Using this mode requires both outer and hidden passphrases and keyfiles.
296 The vararg is of type
298 It determines whether the volume is a system encrypted volume,
299 and if so, which disk is the system disk and hence contains the header.
302 the volume will implicitly be treated as a non-system encrypted volume.
304 The vararg is of type
306 It determines whether the disk uses full disk encryption or not.
307 If specified, the device pointed to by the
309 setting should be a whole disk device, not any partition.
310 The device will be mapped or queried as a whole.
311 For more details on full disk encryption, see
313 .It use_backup_header
314 The vararg is of type
316 It determines whether the backup header should be used instead of the regular
317 header to access the volume.
319 The vararg is of type
325 to use the header in the specified file instead of the regular outer volume header.
326 .It hidden_header_from_file
327 The vararg is of type
333 to use the header in the specified file instead of the regular hidden volume header.
335 The vararg is of type
337 It specifies whether the mapped volume should allow discards (TRIM).
338 .It save_header_to_file
339 The vararg is of type
345 to write the (modified) header to the specified file instead of replacing the volume
348 The vararg is of type
350 It sets the passphrase that
352 uses to access the volume.
354 The vararg is of type
356 It sets the passphrase that
358 uses to unlock the hidden volume header.
359 This option is only used if a hidden volume is being created or the
364 will first use the regular passphrase to try to unlock the outer volume and then
365 try to unlock the hidden volume header with the same passphrase without ever
369 The vararg is of type
373 the given keyfile will be added to the keyfile pool.
374 Multiple calls to set this option with a non-
376 argument result add additional keyfiles.
379 all keyfiles are cleared.
381 The vararg is of type
385 the given keyfile will be added to the keyfile pool.
386 Multiple calls to set this option with a non-
388 argument result add additional keyfiles.
391 all keyfiles are cleared.
392 This option is only used if a hidden volume is being created or the
397 will first use the regular keyfiles to try to unlock the outer volume and then
398 try to unlock the hidden volume header with the same keyfiles without ever
402 The vararg is of type
404 It specifies the new passphrase to use when modifying the volume header.
406 The vararg is of type
410 the given keyfile will be added to the new keyfile pool.
411 Multiple calls to set this option with a non-
413 argument result add additional keyfiles.
416 all new keyfiles are cleared.
417 When the volume header is modified,
418 it will be reencrypted using the new keyfiles.
420 The vararg is of type
422 and must be a valid PBKDF2 PRF algorithm.
423 It determines which PBKDF2 PRF algorithm is used when reencrypting the (modified)
426 The first vararg is of type
427 .Fa tc_api_state_change_fn
428 and the second vararg is of type
430 It allows the consumer to provide a callback function which will be called when
431 starting and stopping a time-intensive sub-operation such as collecting entropy
433 The second vararg is passed as the
435 argument to the callback.
438 argument to the callback determines whether
440 is starting or stopping the time-intensive sub-task specified in the
447 function runs the task specified in the
450 Before running the task,
452 performs a simple sanity check of the arguments set previously using
454 before performing the actual operation.
462 the queried information is available to be accessed using
463 .Fn tc_api_task_info_get .
466 .Fn tc_api_task_info_get
467 function can be used to query the result of a
474 argument is the task used in a previous
479 argument can be one of the following:
480 .Bl -column "some_long_feature" "very_long_type" "Description"
481 .It Sy Key Ta Sy type Ta Sy Description
482 .It Li device Ta Ft char * Ta Corresponding device node
483 .It Li cipher Ta Ft char * Ta Used cipher chain
484 .It Li prf Ta Ft char * Ta Used PBKDF2 PRF algorithm
485 .It Li key_bits Ta Ft int * Ta Number of key bits
486 .It Li size Ta Ft int64_t * Ta Volume size in bytes
487 .It Li iv_offset Ta Ft int64_t * Ta IV Offset of volume in bytes
488 .It Li block_offset Ta Ft int64_t * Ta Block Offset of volume in bytes
491 The second vararg argument must be of the type specified in the above table.
492 The first vararg argument is always the size of the storage provided
493 in the second argument.
496 argument, the size corresponds to the size of the buffer at the provided
497 location and must be of type
503 argument, it should be the size of the underlying type.
506 .Fn tc_api_task_get_error
507 function can be used to get a detailed error message after a failed
512 argument is the task used in a previous
516 TrueCrypt limits passphrases to 64 characters (including the terminating
518 To be compatible with it,
521 All passphrases (exlcuding keyfiles) are trimmed to 64 characters.
522 Similarly, keyfiles are limited to a size of 1 MB, but up to 256
523 keyfiles can be used.
528 .Fn tc_api_task_get_error
531 to indicate that the operation completed successfully, or
533 to indicate that the operation is not implemented
536 to indicate that any other error occurred.
539 .Fn tc_api_task_get_error
540 function always return a valid, but possibly empty (or irrelevant,
541 if not called after an error occurred) string.
547 if an error occurred and an opaque
553 library offers full compatibility with TrueCrypt volumes including
555 volumes, system encryption (map-only), keyfiles and cipher cascading.