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 January 20, 2014 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 224The varargs accepted by the 225.Fn tc_api_task_set 226function depend on the key being set. 227.Bl -tag -width indent 228.It dev 229The vararg is of type 230.Ft const char * . 231It sets the device that contains the TrueCrypt volume to operate on. 232.It map_name 233The vararg is of type 234.Ft const char * . 235It set the name of the mapped volume. 236.It interactive 237The vararg is of type 238.Ft int . 239It determines whether the user will be prompted for a passphrase or whether 240the settings are taken from the arguments set using 241.Fn tc_api_task_set . 242.It retries 243The vararg is of type 244.Ft int . 245It determines the number of passphrase retries if 246.Fa interactive 247is set. 248.It weak_keys_and_salt 249The vararg is of type 250.Ft int . 251It determines whether to use a weak source of entropy for key material and/or 252the salt. 253.It secure_erase 254The vararg is of type 255.Ft int . 256It determines whether a secure erase is performed as part of the volume creation. 257.It hidden_size_bytes 258The vararg is of type 259.Ft int64_t . 260If set to 261.Fa 0 262it implies no hidden volume will be created. 263A positive value implies a hidden volume of the specified size in bytes is created. 264.It prf_algo 265The vararg is of type 266.Ft const char * 267and must be a valid PBKDF2 PRF algorithm. 268It determines which PBKDF2 PRF algorithm is used for the outer volume. 269.It h_prf_algo 270The vararg is of type 271.Ft const char * 272and must be a valid PBKDF2 PRF algorithm. 273It determines which PBKDF2 PRF algorithm is used for the hidden volume. 274.It cipher_chain 275The vararg is of type 276.Ft const char * 277and must be a valid 278.Nm tcplay 279cipher chain. 280It determines which cipher chain is used to encrypt the outer volume. 281.It h_cipher_chain 282The vararg is of type 283.Ft const char * 284and must be a valid 285.Nm tcplay 286cipher chain. 287It determines which cipher chain is used to encrypt the hidden volume. 288.It protect_hidden 289The vararg is of type 290.Ft int . 291It determines whether the size of the outer volume should be adjusted to protect 292any hidden volume. 293Using this mode requires both outer and hidden passphrases and keyfiles. 294.It sys 295The vararg is of type 296.Ft const char * . 297It determines whether the volume is a system encrypted volume, 298and if so, which disk is the system disk and hence contains the header. 299If set to 300.Dv NULL 301the volume will implicitly be treated as a non-system encrypted volume. 302.It fde 303The vararg is of type 304.Ft int . 305It determines whether the disk uses full disk encryption or not. 306If specified, the device pointed to by the 307.Fa dev 308setting should be a whole disk device, not any partition. 309The device will be mapped or queried as a whole. 310To access individual partitions, a utility such as 311.Xr kpartx 8 312should be used, which will create additional individual mappings 313for each partition in the decrypted mapped volume. 314For more details on full disk encryption, see 315.Xr tcplay 8 . 316.It use_backup_header 317The vararg is of type 318.Ft int . 319It determines whether the backup header should be used instead of the regular 320header to access the volume. 321.It header_from_file 322The vararg is of type 323.Ft const char * . 324If not 325.Dv NULL 326it forces 327.Nm tcplay 328to use the header in the specified file instead of the regular outer volume header. 329.It hidden_header_from_file 330The vararg is of type 331.Ft const char * . 332If not 333.Dv NULL 334it forces 335.Nm tcplay 336to use the header in the specified file instead of the regular hidden volume header. 337.It allow_trim 338The vararg is of type 339.Ft int . 340It specifies whether the mapped volume should allow discards (TRIM). 341.It save_header_to_file 342The vararg is of type 343.Ft const char * . 344If not 345.Dv NULL 346it forces 347.Nm tcplay 348to write the (modified) header to the specified file instead of replacing the volume 349headers. 350.It passphrase 351The vararg is of type 352.Ft const char * . 353It sets the passphrase that 354.Nm tcplay 355uses to access the volume. 356.It h_passphrase 357The vararg is of type 358.Ft const char * . 359It sets the passphrase that 360.Nm tcplay 361uses to unlock the hidden volume header. 362This option is only used if a hidden volume is being created or the 363.Fa protect_hidden 364setting is set. 365Otherwise 366.Nm tcplay 367will first use the regular passphrase to try to unlock the outer volume and then 368try to unlock the hidden volume header with the same passphrase without ever 369using 370.Fa h_passphrase . 371.It keyfiles 372The vararg is of type 373.Ft const char * . 374If not 375.Dv NULL 376the given keyfile will be added to the keyfile pool. 377Multiple calls to set this option with a non- 378.Dv NULL 379argument result add additional keyfiles. 380If 381.Dv NULL 382all keyfiles are cleared. 383.It h_keyfiles 384The vararg is of type 385.Ft const char * . 386If not 387.Dv NULL 388the given keyfile will be added to the keyfile pool. 389Multiple calls to set this option with a non- 390.Dv NULL 391argument result add additional keyfiles. 392If 393.Dv NULL 394all keyfiles are cleared. 395This option is only used if a hidden volume is being created or the 396.Fa protect_hidden 397setting is set. 398Otherwise 399.Nm tcplay 400will first use the regular keyfiles to try to unlock the outer volume and then 401try to unlock the hidden volume header with the same keyfiles without ever 402using 403.Fa h_keyfiles . 404.It new_passphrase 405The vararg is of type 406.Fa const char * . 407It specifies the new passphrase to use when modifying the volume header. 408.It new_keyfiles 409The vararg is of type 410.Fa const char * . 411If not 412.Dv NULL 413the given keyfile will be added to the new keyfile pool. 414Multiple calls to set this option with a non- 415.Dv NULL 416argument result add additional keyfiles. 417If 418.Dv NULL 419all new keyfiles are cleared. 420When the volume header is modified, 421it will be reencrypted using the new keyfiles. 422.It new_prf_algo 423The vararg is of type 424.Ft const char * 425and must be a valid PBKDF2 PRF algorithm. 426It determines which PBKDF2 PRF algorithm is used when reencrypting the (modified) 427volume header. 428.It state_change_fn 429The first vararg is of type 430.Fa tc_api_state_change_fn 431and the second vararg is of type 432.Fa void * . 433It allows the consumer to provide a callback function which will be called when 434starting and stopping a time-intensive sub-operation such as collecting entropy 435or erasing a volume. 436The second vararg is passed as the 437.Fa priv 438argument to the callback. 439The 440.Fa enter_state 441argument to the callback determines whether 442.Nm tcplay 443is starting or stopping the time-intensive sub-task specified in the 444.Fa state 445argument. 446.El 447.Pp 448The 449.Fn tc_api_task_do 450function runs the task specified in the 451.Fa task 452argument. 453Before running the task, 454.Fn tc_api_task_do 455performs a simple sanity check of the arguments set previously using 456.Fn tc_api_task_set 457before performing the actual operation. 458After a call to 459.Fn tc_api_task_do 460for the 461.Sy info 462or 463.Sy info_mapped 464operations, 465the queried information is available to be accessed using 466.Fn tc_api_task_info_get . 467.Pp 468The 469.Fn tc_api_task_info_get 470function can be used to query the result of a 471.Sy info 472or 473.Sy info_mapped 474operation. 475The 476.Fa task 477argument is the task used in a previous 478.Fn tc_api_task_do 479call. 480The 481.Fa key 482argument can be one of the following: 483.Bl -column "some_long_feature" "very_long_type" "Description" 484.It Sy Key Ta Sy type Ta Sy Description 485.It Li device Ta Ft char * Ta Corresponding device node 486.It Li cipher Ta Ft char * Ta Used cipher chain 487.It Li prf Ta Ft char * Ta Used PBKDF2 PRF algorithm 488.It Li key_bits Ta Ft int * Ta Number of key bits 489.It Li size Ta Ft int64_t * Ta Volume size in bytes 490.It Li iv_offset Ta Ft int64_t * Ta IV Offset of volume in bytes 491.It Li block_offset Ta Ft int64_t * Ta Block Offset of volume in bytes 492.El 493.Pp 494The second vararg argument must be of the type specified in the above table. 495The first vararg argument is always the size of the storage provided 496in the second argument. 497For a 498.Ft char * 499argument, the size corresponds to the size of the buffer at the provided 500location and must be of type 501.Ft size_t . 502For an 503.Ft int * 504or 505.Ft int64_t * 506argument, it should be the size of the underlying type. 507.Pp 508The 509.Fn tc_api_task_get_error 510function can be used to get a detailed error message after a failed 511.Fa tc_api_task_do 512call. 513The 514.Fa task 515argument is the task used in a previous 516.Fn tc_api_task_do 517call. 518.Sh NOTES 519TrueCrypt limits passphrases to 64 characters (including the terminating 520null character). 521To be compatible with it, 522.Nm tcplay 523does the same. 524All passphrases (exlcuding keyfiles) are trimmed to 64 characters. 525Similarly, keyfiles are limited to a size of 1 MB, but up to 256 526keyfiles can be used. 527.Sh RETURN VALUES 528All functions except 529.Fn tc_api_task_init 530and 531.Fn tc_api_task_get_error 532return either 533.Dv TC_OK 534to indicate that the operation completed successfully, or 535.Dv TC_ERR_UNIMPL 536to indicate that the operation is not implemented 537, or 538.Dv TC_ERR 539to indicate that any other error occurred. 540.Pp 541The 542.Fn tc_api_task_get_error 543function always return a valid, but possibly empty (or irrelevant, 544if not called after an error occurred) string. 545.Pp 546The 547.Fn tc_api_task_init 548function returns 549.Dv NULL 550if an error occurred and an opaque 551.Ft tc_api_task 552otherwise. 553.Sh COMPATIBILITY 554The 555.Nm tcplay 556library offers full compatibility with TrueCrypt volumes including 557hidden 558volumes, system encryption (map-only), keyfiles and cipher cascading. 559.Sh SEE ALSO 560.Xr tcplay 8 , 561.Xr kpartx 8 562.Sh HISTORY 563The 564.Nm tcplay 565library appeared in 566.Dx 2.11 . 567.Sh AUTHORS 568.An Alex Hornung 569