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
37 .Nm tc_api_create_volume ,
38 .Nm tc_api_map_volume ,
39 .Nm tc_api_unmap_volume ,
40 .Nm tc_api_check_cipher ,
41 .Nm tc_api_check_prf_hash ,
42 .Nm tc_api_get_error_msg ,
43 .Nm tc_api_get_summary
44 .Nd TrueCrypt volume management
51 .Fn tc_api_init "int verbose"
53 .Fn tc_api_uninit "void"
55 .Fn tc_api_create_volume "tc_api_opts *api_opts"
57 .Fn tc_api_map_volume "tc_api_opts *api_opts"
59 .Fn tc_api_unmap_volume "tc_api_opts *api_opts"
61 .Fn tc_api_check_cipher "tc_api_opts *api_opts"
63 .Fn tc_api_check_prf_hash "tc_api_opts *api_opts"
65 .Fn tc_api_get_error_msg "void"
67 .Fn tc_api_get_summary "void"
71 library provides an interface to create, query and map
76 .Fn tc_api_create_volume ,
77 .Fn tc_api_map_volume ,
78 .Fn tc_api_unmap_volume ,
79 .Fn tc_api_check_cipher
81 .Fn tc_api_check_prf_hash
84 data structure as only argument, which is defined as follows:
86 typedef struct tc_api_opts {
90 const char **tc_keyfiles;
92 /* Fields for mapping */
94 int tc_password_retries;
95 int tc_interactive_prompt;
96 unsigned long tc_prompt_timeout;
98 /* Fields for creation */
101 char *tc_cipher_hidden;
102 char *tc_prf_hash_hidden;
103 size_t tc_size_hidden_in_bytes;
104 char *tc_passphrase_hidden;
105 const char **tc_keyfiles_hidden;
109 where the keyfile fields,
112 .Fa tc_keyfiles_hidden ,
115 terminated arrays of key file strings.
119 function initializes the library internals and prepares it for use via
121 This function has to be called before using any other API function.
124 argument is non-zero, then the library will output information such as
125 errors via stdout and stderr.
129 function clears up all internal secure memory, such as memory used for
130 decrypted headers, passphrases, keyfiles, etc.
133 .Fn tc_api_create_volume
134 function creates a new volume using the parameters specified in the
137 The new volume will be created on the device specified by
139 using the cipher specified by
141 and the pbkdf2 prf hash algorithm specified by
143 and using the passphrase and keyfiles specified by
149 .Fa tc_size_hidden_in_bytes
150 is not zero, a hidden volume of the given size will be created, using
151 the cipher specified by
153 and the pbkdf2 prf hash algorithm specified by
154 .Fa tc_prf_hash_hidden .
158 .Fa tc_prf_hash_hidden
161 the same algorithm as for the outer volume will be used.
162 The passphrase and keyfiles used are specified by
163 .Fa tc_passphrase_hidden
165 .Fa tc_keyfiles_hidden
169 .Fn tc_api_map_volume
170 function maps a volume using the parameters specified in the
173 The volume, which will be mapped as
178 .Fa tc_interactive_prompt
179 field determines whether the user will be prompted to enter a passphrase
180 interactively or whether the passphrase in
183 If an interactive prompt is used, the prompt will time out after
184 .Fa tc_prompt_timeout
186 A value of 0 indicates that no timeout will occur.
187 The number of passphrase entry retries is defined by
188 .Fa tc_password_retries .
190 .Fn tc_api_map_volume
191 function does not support accessing an outer volume while
192 protecting the hidden volume.
193 Depending on the passphrase/keyfiles used
194 either the outer or the hidden volume will be mapped.
197 .Fn tc_api_unmap_volume
198 unmaps / closes the volume specified in
202 .Fn tc_api_check_cipher
203 function checks whether the cipher specified in the
210 .Fn tc_api_check_prf_hash
211 function checks whether the prf hash algorithm specified in the
218 .Fn tc_api_get_error_msg
219 function should be called whenver another API function returns
221 It returns a string containing a description of the error that
225 .Fn tc_api_get_summary
226 function returns a string containing a summary of the current
227 progress of a certain operation.
228 Currently only the volume erasing
229 part of creating a new volume can provide a summary.
230 When no summary is available, an empty string is returned.
231 The output otherwise is equivalent to that of a
237 .Fn tc_api_get_error_msg
239 .Fn tc_api_get_summary
242 to signal that the operation completed successfully, or
244 to signal that an error occurred.
247 .Fn tc_api_get_error_msg
249 .Fn tc_api_get_summary
250 always return a valid, but possibly empty, string.
254 library offers full compatibility with TrueCrypt volumes including
256 volumes, system encryption (map-only), keyfiles and cipher cascading.