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