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