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