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 May 2, 2020 32.Dt TCPLAY 3 33.Os 34.Sh NAME 35.Nm tc_api_init , 36.Nm tc_api_uninit , 37.Nm tc_api_has , 38.Nm tc_api_cipher_iterate , 39.Nm tc_api_prf_iterate , 40.Nm tc_api_task_init , 41.Nm tc_api_task_uninit , 42.Nm tc_api_task_set , 43.Nm tc_api_task_do , 44.Nm tc_api_task_info_get , 45.Nm tc_api_task_get_error 46.Nd TrueCrypt volume management 47.Sh LIBRARY 48.Lb libtcplay 49.Sh SYNOPSIS 50.In tcplay_api.h 51.Ft typedef int 52.Fn (*tc_api_cipher_iterator_fn) "void *priv" "const char *name" "int key_length_in_bits" "int ciphers_in_chain" 53.Ft typedef int 54.Fn (*tc_api_prf_iterator_fn) "void *priv" "const char *name" 55.Ft typedef int 56.Fn (*tc_api_state_change_fn) "void *priv" "const char *state" "int enter_state" 57.Ft int 58.Fn tc_api_init "int verbose" 59.Ft int 60.Fn tc_api_uninit "void" 61.Ft int 62.Fn tc_api_has "const char *feature" 63.Ft int 64.Fn tc_api_cipher_iterate "tc_api_cipher_iterator_fn fn" "void *priv" 65.Ft int 66.Fn tc_api_prf_iterate "tc_api_prf_iterator_fn fn" "void *priv" 67.Ft tc_api_task 68.Fn tc_api_task_init "const char *op" 69.Ft int 70.Fn tc_api_task_uninit "tc_api_task task" 71.Ft int 72.Fn tc_api_task_set "tc_api_task task" "const char *key" "..." 73.Ft int 74.Fn tc_api_task_do "tc_api_task task" 75.Ft int 76.Fn tc_api_task_info_get "tc_api_task task" "const char *key" "..." 77.Ft const char * 78.Fn tc_api_task_get_error "tc_api_task task" 79.Sh DESCRIPTION 80The 81.Nm tcplay 82library provides an interface to create, query, map and manage 83TrueCrypt-compatible volumes. 84.Pp 85The 86.Fn tc_api_init 87function initializes the library internals and prepares it for use via 88the API. 89This function has to be called before using any other API function. 90If the 91.Fa verbose 92argument is non-zero, then the library will output information such as 93errors via stdout and stderr. 94.Pp 95The 96.Fn tc_api_uninit 97function clears up all internal secure memory, such as memory used for 98decrypted headers, passphrases, keyfiles, etc. 99.Pp 100The 101.Fn tc_api_has 102function checks whether the loaded tcplay library has the feature 103specified by the 104.Fa feature 105argument. 106The current version of the 107.Nm tcplay 108library supports the following features: 109.Bl -column "some_long_feature" "Description" 110.It Sy Feature Ta Sy Description 111.It Li trim Ta Allows enabling discards/TRIM when mapping a volume 112.El 113.Pp 114The 115.Fn tc_api_cipher_iterate 116function passes every available cipher chain to the callback provided in the 117.Fa fn 118argument. 119The 120.Fa priv 121argument is passed on every call of the callback function. 122The name of the cipher chain is passed to the callback function in the 123.Fa name 124argument. 125Similarly, 126the 127.Fa ciphers_in_chain 128argument holds the number of ciphers in the current chain, 129and 130.Fa key_length_in_bits 131holds the total key length for the cipher chain, 132in bits. 133.Pp 134The 135.Fn tc_api_prf_iterate 136function passes every available cipher chain to the callback provided in the 137.Fa fn 138argument. 139The 140.Fa priv 141argument is passed on every call of the callback function. 142The name of the PKBDF2 PRF algorithm is passed to the callback function in the 143.Fa name 144argument. 145.Pp 146The 147.Fn tc_api_task_init 148function initializes and returns a 149.Ft tc_api_task 150opaque pointer that can be used to run 151.Nm tcplay 152commands. 153Each task can be used only for a single 154.Fn tc_api_task_do 155call, 156and must be deallocated using 157.Fn tc_api_task_uninit . 158The 159.Fa op 160argument can be one of the following: 161.Bl -tag -width indent 162.It Sy create 163Create a new encrypted TrueCrypt volume. 164.It Sy map 165Map an existing TrueCrypt volume. 166.It Sy info 167Request information about an encrypted TrueCrypt volume. 168.It Sy info_mapped 169Request information about a mapped TrueCrypt volume. 170.It Sy unmap 171Unmap a mapped TrueCrypt volume. 172.It Sy modify 173Modify the TrueCrypt volume by changing the passphrase, keyfiles, PRF algorithm, 174restoring from a backup header, restoring from a header file or saving to a header file. 175.It Sy restore 176Modify the TrueCrypt volume as 177.Sy modify 178does, but without changing the passphrase, keyfiles or PRF algorithm. 179.El 180.Pp 181The 182.Fn tc_api_task_set 183function allows settting a number of different options for the current task. 184The following table shows which keys are available on calls to 185.Fn tc_api_task_set 186for each of the operations. 187The letter 188.Sy M 189indicates the setting is mandatory, 190whilst 191.Sy * 192indicates the setting is optional. 193.Bl -column "hidden_header_from_filexxx" "createxxx" "infoxxx" "mapxxx" "unmapxxx" "info_mappedxxx" "modifyxxx" "restorexxx" 194.It Sy Key Ta Sy create Ta Sy info Ta Sy map Ta Sy unmap Ta Sy info_mapped Ta Sy modify Ta Sy restore 195.It Li dev Ta "M" Ta "M" Ta "M" Ta "*" Ta Ta "M" Ta "M" 196.It Li map_name Ta Ta Ta "M" Ta "M" Ta "M" Ta Ta "" 197.It Li interactive Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 198.It Li retries Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 199.It Li timeout Ta "*" Ta "*" Ta "*" Ta Ta Ta Ta "" 200.It Li state_change_fn Ta "*" Ta Ta Ta Ta Ta "*" Ta "*" 201.It Li weak_keys_and_salt Ta "*" Ta Ta Ta Ta Ta "*" Ta "*" 202.It Li secure_erase Ta "*" Ta Ta Ta Ta Ta Ta "" 203.It Li hidden_size_bytes Ta "*" Ta Ta Ta Ta Ta Ta "" 204.It Li prf_algo Ta "*" Ta Ta Ta Ta Ta Ta "" 205.It Li h_prf_algo Ta "*" Ta Ta Ta Ta Ta Ta "" 206.It Li cipher_chain Ta "*" Ta Ta Ta Ta Ta Ta "" 207.It Li h_cipher_chain Ta "*" Ta Ta Ta Ta Ta Ta "" 208.It Li protect_hidden Ta Ta "*" Ta "*" Ta Ta Ta Ta "" 209.It Li fde Ta Ta "*" Ta "*" Ta Ta Ta Ta "" 210.It Li sys Ta Ta "*" Ta "*" Ta Ta Ta "?" Ta "?" 211.It Li use_backup_header Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 212.It Li header_from_file Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 213.It Li hidden_header_from_file Ta Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 214.It Li allow_trim Ta Ta Ta "*" Ta Ta Ta Ta "" 215.It Li save_header_to_file Ta Ta Ta Ta Ta Ta "*" Ta "" 216.It Li passphrase Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 217.It Li h_passphrase Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 218.It Li keyfiles Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 219.It Li h_keyfiles Ta "*" Ta "*" Ta "*" Ta Ta Ta "*" Ta "*" 220.It Li new_passphrase Ta Ta Ta Ta Ta Ta "*" Ta "" 221.It Li new_keyfiles Ta Ta Ta Ta Ta Ta "*" Ta "" 222.It Li new_prf_algo Ta Ta Ta Ta Ta Ta "*" Ta "" 223.El 224.Pp 225The varargs accepted by the 226.Fn tc_api_task_set 227function depend on the key being set. 228.Bl -tag -width indent 229.It dev 230The vararg is of type 231.Ft const char * . 232It sets the device that contains the TrueCrypt volume to operate on. 233.It map_name 234The vararg is of type 235.Ft const char * . 236It set the name of the mapped volume. 237.It interactive 238The vararg is of type 239.Ft int . 240It determines whether the user will be prompted for a passphrase or whether 241the settings are taken from the arguments set using 242.Fn tc_api_task_set . 243.It retries 244The vararg is of type 245.Ft int . 246It determines the number of passphrase retries if 247.Fa interactive 248is set. 249.It weak_keys_and_salt 250The vararg is of type 251.Ft int . 252It determines whether to use a weak source of entropy for key material and/or 253the salt. 254.It secure_erase 255The vararg is of type 256.Ft int . 257It determines whether a secure erase is performed as part of the volume creation. 258.It hidden_size_bytes 259The vararg is of type 260.Ft int64_t . 261If set to 262.Fa 0 263it implies no hidden volume will be created. 264A positive value implies a hidden volume of the specified size in bytes is created. 265.It prf_algo 266The vararg is of type 267.Ft const char * 268and must be a valid PBKDF2 PRF algorithm. 269It determines which PBKDF2 PRF algorithm is used for the outer volume. 270.It h_prf_algo 271The vararg is of type 272.Ft const char * 273and must be a valid PBKDF2 PRF algorithm. 274It determines which PBKDF2 PRF algorithm is used for the hidden volume. 275.It cipher_chain 276The vararg is of type 277.Ft const char * 278and must be a valid 279.Nm tcplay 280cipher chain. 281It determines which cipher chain is used to encrypt the outer volume. 282.It h_cipher_chain 283The vararg is of type 284.Ft const char * 285and must be a valid 286.Nm tcplay 287cipher chain. 288It determines which cipher chain is used to encrypt the hidden volume. 289.It protect_hidden 290The vararg is of type 291.Ft int . 292It determines whether the size of the outer volume should be adjusted to protect 293any hidden volume. 294Using this mode requires both outer and hidden passphrases and keyfiles. 295.It sys 296The vararg is of type 297.Ft const char * . 298It determines whether the volume is a system encrypted volume, 299and if so, which disk is the system disk and hence contains the header. 300If set to 301.Dv NULL 302the volume will implicitly be treated as a non-system encrypted volume. 303.It fde 304The vararg is of type 305.Ft int . 306It determines whether the disk uses full disk encryption or not. 307If specified, the device pointed to by the 308.Fa dev 309setting should be a whole disk device, not any partition. 310The device will be mapped or queried as a whole. 311For more details on full disk encryption, see 312.Xr tcplay 8 . 313.It use_backup_header 314The vararg is of type 315.Ft int . 316It determines whether the backup header should be used instead of the regular 317header to access the volume. 318.It header_from_file 319The vararg is of type 320.Ft const char * . 321If not 322.Dv NULL 323it forces 324.Nm tcplay 325to use the header in the specified file instead of the regular outer volume header. 326.It hidden_header_from_file 327The vararg is of type 328.Ft const char * . 329If not 330.Dv NULL 331it forces 332.Nm tcplay 333to use the header in the specified file instead of the regular hidden volume header. 334.It allow_trim 335The vararg is of type 336.Ft int . 337It specifies whether the mapped volume should allow discards (TRIM). 338.It save_header_to_file 339The vararg is of type 340.Ft const char * . 341If not 342.Dv NULL 343it forces 344.Nm tcplay 345to write the (modified) header to the specified file instead of replacing the volume 346headers. 347.It passphrase 348The vararg is of type 349.Ft const char * . 350It sets the passphrase that 351.Nm tcplay 352uses to access the volume. 353.It h_passphrase 354The vararg is of type 355.Ft const char * . 356It sets the passphrase that 357.Nm tcplay 358uses to unlock the hidden volume header. 359This option is only used if a hidden volume is being created or the 360.Fa protect_hidden 361setting is set. 362Otherwise 363.Nm tcplay 364will first use the regular passphrase to try to unlock the outer volume and then 365try to unlock the hidden volume header with the same passphrase without ever 366using 367.Fa h_passphrase . 368.It keyfiles 369The vararg is of type 370.Ft const char * . 371If not 372.Dv NULL 373the given keyfile will be added to the keyfile pool. 374Multiple calls to set this option with a non- 375.Dv NULL 376argument result add additional keyfiles. 377If 378.Dv NULL 379all keyfiles are cleared. 380.It h_keyfiles 381The vararg is of type 382.Ft const char * . 383If not 384.Dv NULL 385the given keyfile will be added to the keyfile pool. 386Multiple calls to set this option with a non- 387.Dv NULL 388argument result add additional keyfiles. 389If 390.Dv NULL 391all keyfiles are cleared. 392This option is only used if a hidden volume is being created or the 393.Fa protect_hidden 394setting is set. 395Otherwise 396.Nm tcplay 397will first use the regular keyfiles to try to unlock the outer volume and then 398try to unlock the hidden volume header with the same keyfiles without ever 399using 400.Fa h_keyfiles . 401.It new_passphrase 402The vararg is of type 403.Fa const char * . 404It specifies the new passphrase to use when modifying the volume header. 405.It new_keyfiles 406The vararg is of type 407.Fa const char * . 408If not 409.Dv NULL 410the given keyfile will be added to the new keyfile pool. 411Multiple calls to set this option with a non- 412.Dv NULL 413argument result add additional keyfiles. 414If 415.Dv NULL 416all new keyfiles are cleared. 417When the volume header is modified, 418it will be reencrypted using the new keyfiles. 419.It new_prf_algo 420The vararg is of type 421.Ft const char * 422and must be a valid PBKDF2 PRF algorithm. 423It determines which PBKDF2 PRF algorithm is used when reencrypting the (modified) 424volume header. 425.It state_change_fn 426The first vararg is of type 427.Fa tc_api_state_change_fn 428and the second vararg is of type 429.Fa void * . 430It allows the consumer to provide a callback function which will be called when 431starting and stopping a time-intensive sub-operation such as collecting entropy 432or erasing a volume. 433The second vararg is passed as the 434.Fa priv 435argument to the callback. 436The 437.Fa enter_state 438argument to the callback determines whether 439.Nm tcplay 440is starting or stopping the time-intensive sub-task specified in the 441.Fa state 442argument. 443.El 444.Pp 445The 446.Fn tc_api_task_do 447function runs the task specified in the 448.Fa task 449argument. 450Before running the task, 451.Fn tc_api_task_do 452performs a simple sanity check of the arguments set previously using 453.Fn tc_api_task_set 454before performing the actual operation. 455After a call to 456.Fn tc_api_task_do 457for the 458.Sy info 459or 460.Sy info_mapped 461operations, 462the queried information is available to be accessed using 463.Fn tc_api_task_info_get . 464.Pp 465The 466.Fn tc_api_task_info_get 467function can be used to query the result of a 468.Sy info 469or 470.Sy info_mapped 471operation. 472The 473.Fa task 474argument is the task used in a previous 475.Fn tc_api_task_do 476call. 477The 478.Fa key 479argument can be one of the following: 480.Bl -column "some_long_feature" "very_long_type" "Description" 481.It Sy Key Ta Sy type Ta Sy Description 482.It Li device Ta Ft char * Ta Corresponding device node 483.It Li cipher Ta Ft char * Ta Used cipher chain 484.It Li prf Ta Ft char * Ta Used PBKDF2 PRF algorithm 485.It Li key_bits Ta Ft int * Ta Number of key bits 486.It Li size Ta Ft int64_t * Ta Volume size in bytes 487.It Li iv_offset Ta Ft int64_t * Ta IV Offset of volume in bytes 488.It Li block_offset Ta Ft int64_t * Ta Block Offset of volume in bytes 489.El 490.Pp 491The second vararg argument must be of the type specified in the above table. 492The first vararg argument is always the size of the storage provided 493in the second argument. 494For a 495.Ft char * 496argument, the size corresponds to the size of the buffer at the provided 497location and must be of type 498.Ft size_t . 499For an 500.Ft int * 501or 502.Ft int64_t * 503argument, it should be the size of the underlying type. 504.Pp 505The 506.Fn tc_api_task_get_error 507function can be used to get a detailed error message after a failed 508.Fa tc_api_task_do 509call. 510The 511.Fa task 512argument is the task used in a previous 513.Fn tc_api_task_do 514call. 515.Sh NOTES 516TrueCrypt limits passphrases to 64 characters (including the terminating 517null character). 518To be compatible with it, 519.Nm tcplay 520does the same. 521All passphrases (exlcuding keyfiles) are trimmed to 64 characters. 522Similarly, keyfiles are limited to a size of 1 MB, but up to 256 523keyfiles can be used. 524.Sh RETURN VALUES 525All functions except 526.Fn tc_api_task_init 527and 528.Fn tc_api_task_get_error 529return either 530.Dv TC_OK 531to indicate that the operation completed successfully, or 532.Dv TC_ERR_UNIMPL 533to indicate that the operation is not implemented 534, or 535.Dv TC_ERR 536to indicate that any other error occurred. 537.Pp 538The 539.Fn tc_api_task_get_error 540function always return a valid, but possibly empty (or irrelevant, 541if not called after an error occurred) string. 542.Pp 543The 544.Fn tc_api_task_init 545function returns 546.Dv NULL 547if an error occurred and an opaque 548.Ft tc_api_task 549otherwise. 550.Sh COMPATIBILITY 551The 552.Nm tcplay 553library offers full compatibility with TrueCrypt volumes including 554hidden 555volumes, system encryption (map-only), keyfiles and cipher cascading. 556.Sh SEE ALSO 557.Xr tcplay 8 558.Sh HISTORY 559The 560.Nm tcplay 561library appeared in 562.Dx 2.11 . 563.Sh AUTHORS 564.An Alex Hornung 565