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