lib/libtcplay/tcplay.3

   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
  69 The
  70 .Nm tcplay
  71 library provides an interface to create, query and map
  72 TrueCrypt-compatible
  73 volumes.
  74 .Pp
  75 The
  76 .Fn tc_api_create_volume ,
  77 .Fn tc_api_map_volume ,
  78 .Fn tc_api_unmap_volume ,
  79 .Fn tc_api_check_cipher
  80 and
  81 .Fn tc_api_check_prf_hash
  82 functions take a
  83 .Vt tc_api_opts
  84 data structure as only argument, which is defined as follows:
  85 .Bd -literal
  86 typedef 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
 109 where the keyfile fields,
 110 .Fa tc_keyfiles
 111 and
 112 .Fa tc_keyfiles_hidden ,
 113 are
 114 .Dv NULL
 115 terminated arrays of key file strings.
 116 .Pp
 117 The
 118 .Fn tc_api_init
 119 function initializes the library internals and prepares it for use via
 120 the API.
 121 This function has to be called before using any other API function.
 122 If the
 123 .Fa verbose
 124 argument is non-zero, then the library will output information such as
 125 errors via stdout and stderr.
 126 .Pp
 127 The
 128 .Fn tc_api_uninit
 129 function clears up all internal secure memory, such as memory used for
 130 decrypted headers, passphrases, keyfiles, etc.
 131 .Pp
 132 The
 133 .Fn tc_api_create_volume
 134 function creates a new volume using the parameters specified in the
 135 .Fa api_opts
 136 argument.
 137 The new volume will be created on the device specified by
 138 .Fa tc_device
 139 using the cipher specified by
 140 .Fa tc_cipher
 141 and the pbkdf2 prf hash algorithm specified by
 142 .Fa tc_prf_hash
 143 and using the passphrase and keyfiles specified by
 144 .Fa tc_passphrase
 145 and
 146 .Fa tc_keyfiles
 147 respectively.
 148 If
 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
 152 .Fa tc_cipher_hidden
 153 and the pbkdf2 prf hash algorithm specified by
 154 .Fa tc_prf_hash_hidden .
 155 If
 156 .Fa tc_cipher_hidden
 157 or
 158 .Fa tc_prf_hash_hidden
 159 are
 160 .Dv NULL ,
 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
 164 and
 165 .Fa tc_keyfiles_hidden
 166 respectively.
 167 .Pp
 168 The
 169 .Fn tc_api_map_volume
 170 function maps a volume using the parameters specified in the
 171 .Fa api_opts
 172 argument.
 173 The volume, which will be mapped as
 174 .Fa tc_map_name ,
 175 is specified in
 176 .Fa tc_device .
 177 The
 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
 181 .Fa tc_passphrase
 182 will be used.
 183 If an interactive prompt is used, the prompt will time out after
 184 .Fa tc_prompt_timeout
 185 seconds.
 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 .
 189 Note that the
 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.
 195 .Pp
 196 The
 197 .Fn tc_api_unmap_volume
 198 unmaps / closes the volume specified in
 199 .Fa tc_map_name .
 200 .Pp
 201 The
 202 .Fn tc_api_check_cipher
 203 function checks whether the cipher specified in the
 204 .Fa api_opts
 205 argument field
 206 .Fa tc_cipher
 207 is valid.
 208 .Pp
 209 The
 210 .Fn tc_api_check_prf_hash
 211 function checks whether the prf hash algorithm specified in the
 212 .Fa api_opts
 213 argument field
 214 .Fa tc_prf_hash
 215 is valid.
 216 .Pp
 217 The
 218 .Fn tc_api_get_error_msg
 219 function should be called whenver another API function returns
 220 .Dv TC_ERR .
 221 It returns a string containing a description of the error that
 222 occurred.
 223 .Pp
 224 The
 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
 232 .Dv SIGINFO
 233 signal when using
 234 .Xr tcplay 8 .
 235 .Sh RETURN VALUES
 236 All functions except
 237 .Fn tc_api_get_error_msg
 238 and
 239 .Fn tc_api_get_summary
 240 return either
 241 .Dv TC_OK
 242 to signal that the operation completed successfully, or
 243 .Dv TC_ERR
 244 to signal that an error occurred.
 245 .Pp
 246 The
 247 .Fn tc_api_get_error_msg
 248 and
 249 .Fn tc_api_get_summary
 250 always return a valid, but possibly empty, string.
 251 .Sh COMPATIBILITY
 252 The
 253 .Nm tcplay
 254 library offers full compatibility with TrueCrypt volumes including
 255 hidden
 256 volumes, system encryption (map-only), keyfiles and cipher cascading.
 257 .Sh SEE ALSO
 258 .Xr tcplay 8
 259 .Sh HISTORY
 260 The
 261 .Nm tcplay
 262 library appeared in
 263 .Dx 2.11 .
 264 .Sh AUTHORS
 265 .An Alex Hornung