Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 266 lines (262 sloc) 7.083 kb
7bd9bf2 @bwalex add man pages
authored
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 July 5, 2011
32 .Dt TCPLAY 3
33 .Os
34 .Sh NAME
35 .Nm tc_api_init ,
36 .Nm tc_api_uninit ,
37 .Nm tc_api_create_volume ,
38 .Nm tc_api_map_volume ,
1c225df @bwalex proper support for unmapping
authored
39 .Nm tc_api_unmap_volume ,
7bd9bf2 @bwalex add man pages
authored
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
45 .Sh LIBRARY
46 .Lb libtcplay
47 .Sh SYNOPSIS
48 .In tcplay_api.h
49 .Ft int
50 .Fn tc_api_init "int verbose"
51 .Ft int
52 .Fn tc_api_uninit "void"
53 .Ft int
54 .Fn tc_api_create_volume "tc_api_opts *api_opts"
55 .Ft int
56 .Fn tc_api_map_volume "tc_api_opts *api_opts"
57 .Ft int
1c225df @bwalex proper support for unmapping
authored
58 .Fn tc_api_unmap_volume "tc_api_opts *api_opts"
59 .Ft int
7bd9bf2 @bwalex add man pages
authored
60 .Fn tc_api_check_cipher "tc_api_opts *api_opts"
61 .Ft int
62 .Fn tc_api_check_prf_hash "tc_api_opts *api_opts"
63 .Ft const char *
64 .Fn tc_api_get_error_msg "void"
65 .Ft const char *
66 .Fn tc_api_get_summary "void"
67 .Sh DESCRIPTION
68 The
69 .Nm tcplay
70 library provides an interface to create, query and map
71 TrueCrypt-compatible
72 volumes.
73 .Pp
74 The
75 .Fn tc_api_create_volume ,
76 .Fn tc_api_map_volume ,
1c225df @bwalex proper support for unmapping
authored
77 .Fn tc_api_unmap_volume ,
7bd9bf2 @bwalex add man pages
authored
78 .Fn tc_api_check_cipher
79 and
80 .Fn tc_api_check_prf_hash
81 functions take a
82 .Vt tc_api_opts
83 data structure as only argument, which is defined as follows:
84 .Bd -literal
85 typedef struct tc_api_opts {
86 /* Common fields */
87 char *tc_device;
88 char *tc_passphrase;
89 const char **tc_keyfiles;
90
91 /* Fields for mapping */
92 char *tc_map_name;
93 int tc_password_retries;
94 int tc_interactive_prompt;
46f7fdb @bwalex add prompt timeout support
authored
95 unsigned long tc_prompt_timeout;
7bd9bf2 @bwalex add man pages
authored
96
97 /* Fields for creation */
98 char *tc_cipher;
99 char *tc_prf_hash;
c4608da @bwalex bugfix, support for different cipher for hidden vol
authored
100 char *tc_cipher_hidden;
101 char *tc_prf_hash_hidden;
92f96b8 @bwalex make blksz agnostic, fix volume size
authored
102 size_t tc_size_hidden_in_bytes;
7bd9bf2 @bwalex add man pages
authored
103 char *tc_passphrase_hidden;
104 const char **tc_keyfiles_hidden;
105 } tc_api_opts;
106 .Ed
107 .Pp
108 where the keyfile fields,
109 .Fa tc_keyfiles
110 and
111 .Fa tc_keyfiles_hidden ,
112 are
113 .Dv NULL
114 terminated arrays of key file strings.
115 .Pp
116 The
117 .Fn tc_api_init
118 function initializes the library internals and prepares it for use via
119 the API.
120 This function has to be called before using any other API function.
121 If the
122 .Fa verbose
123 argument is non-zero, then the library will output information such as
124 errors via stdout and stderr.
125 .Pp
126 The
127 .Fn tc_api_uninit
128 function clears up all internal secure memory, such as memory used for
129 decrypted headers, passphrases, keyfiles, etc.
130 .Pp
131 The
132 .Fn tc_api_create_volume
133 function creates a new volume using the parameters specified in the
134 .Fa api_opts
135 argument.
136 The new volume will be created on the device specified by
137 .Fa tc_device
138 using the cipher specified by
139 .Fa tc_cipher
140 and the pbkdf2 prf hash algorithm specified by
141 .Fa tc_prf_hash
142 and using the passphrase and keyfiles specified by
143 .Fa tc_passphrase
144 and
145 .Fa tc_keyfiles
146 respectively.
147 If
92f96b8 @bwalex make blksz agnostic, fix volume size
authored
148 .Fa tc_size_hidden_in_bytes
7bd9bf2 @bwalex add man pages
authored
149 is not zero, a hidden volume of the given size will be created, using
c4608da @bwalex bugfix, support for different cipher for hidden vol
authored
150 the cipher specified by
151 .Fa tc_cipher_hidden
152 and the pbkdf2 prf hash algorithm specified by
153 .Fa tc_prf_hash_hidden .
154 If
155 .Fa tc_cipher_hidden
156 or
157 .Fa tc_prf_hash_hidden
158 are
159 .Dv NULL ,
160 the same algorithm as for the outer volume will be used.
161 The passphrase and keyfiles used are specified by
7bd9bf2 @bwalex add man pages
authored
162 .Fa tc_passphrase_hidden
163 and
164 .Fa tc_keyfiles_hidden
165 respectively.
166 .Pp
167 The
168 .Fn tc_api_map_volume
169 function maps a volume using the parameters specified in the
170 .Fa api_opts
171 argument.
172 The volume, which will be mapped as
173 .Fa tc_map_name ,
174 is specified in
175 .Fa tc_device .
176 The
177 .Fa tc_interactive_prompt
178 field determines whether the user will be prompted to enter a passphrase
179 interactively or whether the passphrase in
180 .Fa tc_passphrase
181 will be used.
46f7fdb @bwalex add prompt timeout support
authored
182 If an interactive prompt is used, the prompt will time out after
183 .Fa tc_prompt_timeout
184 seconds.
185 A value of 0 indicates that no timeout will occur.
7bd9bf2 @bwalex add man pages
authored
186 The number of passphrase entry retries is defined by
187 .Fa tc_password_retries .
188 Note that the
189 .Fn tc_api_map_volume
190 function does not support accessing an outer volume while
191 protecting the hidden volume.
192 Depending on the passphrase/keyfiles used
193 either the outer or the hidden volume will be mapped.
194 .Pp
195 The
1c225df @bwalex proper support for unmapping
authored
196 .Fn tc_api_unmap_volume
197 unmaps / closes the volume specified in
198 .Fa tc_map_name .
199 .Pp
200 The
7bd9bf2 @bwalex add man pages
authored
201 .Fn tc_api_check_cipher
202 function checks whether the cipher specified in the
203 .Fa api_opts
204 argument field
205 .Fa tc_cipher
206 is valid.
207 .Pp
208 The
209 .Fn tc_api_check_prf_hash
210 function checks whether the prf hash algorithm specified in the
211 .Fa api_opts
212 argument field
213 .Fa tc_prf_hash
214 is valid.
215 .Pp
216 The
217 .Fn tc_api_get_error_msg
218 function should be called whenver another API function returns
219 .Dv TC_ERR .
220 It returns a string containing a description of the error that
221 occured.
222 .Pp
223 The
224 .Fn tc_api_get_summary
225 function returns a string containing a summary of the current
226 progress of a certain operation.
227 Currently only the volume erasing
228 part of creating a new volume can provide a summary.
229 When no summary is available, an empty string is returned.
230 The output otherwise is equivalent to that of a
231 .Dv SIGINFO
232 signal when using
233 .Xr tcplay 8 .
234 .Sh RETURN VALUES
235 All functions except
236 .Fn tc_api_get_error_msg
237 and
238 .Fn tc_api_get_summary
239 return either
240 .Dv TC_OK
241 to signal that the operation completed successfully, or
242 .Dv TC_ERR
243 to signal that an error occured.
244 .Pp
245 The
246 .Fn tc_api_get_error_msg
247 and
248 .Fn tc_api_get_summary
249 always return a valid, but possibly empty, string.
250 .Sh COMPATIBILITY
251 The
252 .Nm tcplay
253 library offers full compatibility with TrueCrypt volumes including
254 hidden
255 volumes, system encryption (map-only), keyfiles and cipher cascading.
256 .Sh SEE ALSO
257 .Xr tcplay 8
258 .Sh HISTORY
259 The
260 .Nm tcplay
261 library appeared in
262 .Dx 2.11 .
263 .Sh AUTHORS
264 .An Alex Hornung
265
Something went wrong with that request. Please try again.