lib/libcryptsetup.h

   1 /**
   2  * @file libcryptsetup.h
   3  * @brief Public cryptsetup API
   4  *
   5  * For more verbose examples of LUKS related use cases,
   6  * please read @ref index "examples" @endref.
   7  */
   8
   9 #ifndef _LIBCRYPTSETUP_H
  10 #define _LIBCRYPTSETUP_H
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #include <stdint.h>
  16
  17 struct crypt_device; /* crypt device handle */
  18
  19 /**
  20  * Initialize crypt device handle and check if provided device exists.
  21  *
  22  * @param cd Returns pointer to crypt device handle
  23  * @param device Path to the backing device.
  24  *        If @e device is not a block device but a path to some file,
  25  *        the function will try to create a loopdevice and attach
  26  *        the file to the loopdevice with AUTOCLEAR flag set.
  27  *        If @e device is @e NULL function it will initialize dm backend only.
  28  *
  29  * @return @e 0 on success or negative errno value otherwise.
  30  *
  31  * @note Note that logging is not initialized here, possible messages uses
  32  *       default log function.
  33  */
  34 int crypt_init(struct crypt_device **cd, const char *device);
  35
  36 /**
  37  * Initialize crypt device handle from provided active device name,
  38  * and, optionally, from separate metadata (header) device
  39  * and check if provided device exists.
  40  *
  41  * @return @e 0 on success or negative errno value otherwise.
  42  *
  43  * @param cd returns crypt device handle for active device
  44  * @param name name of active crypt device
  45  * @param header_device optional device containing on-disk header
  46  *        (@e NULL if it the same as underlying device on there is no on-disk header)
  47  *
  48  * @post In case @e device points to active LUKS device but header load fails,
  49  * context device type is set to @e NULL and @e 0 is returned as if it were successful.
  50  * Context with @e NULL device type can only be deactivated by crypt_deactivate
  51  *
  52  * @note @link crypt_init_by_name @endlink is equivalent to calling
  53  *       crypt_init_by_name_and_header(cd, name, NULL);
  54  */
  55 int crypt_init_by_name_and_header(struct crypt_device **cd,
  56                                   const char *name,
  57                                   const char *header_device);
  58
  59 /**
  60  * This is equivalent to call
  61  * @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
  62  *
  63  * @sa crypt_init_by_name_and_header
  64  */
  65 int crypt_init_by_name(struct crypt_device **cd, const char *name);
  66
  67 /**
  68  * @defgroup loglevel "Cryptsetup logging API"
  69  *
  70  * Set of functions and defines used in cryptsetup for
  71  * logging purposes
  72  *
  73  */
  74
  75 /**
  76  * @addtogroup loglevel
  77  * @{
  78  */
  79
  80 /** normal log level */
  81 #define CRYPT_LOG_NORMAL 0
  82 /** error log level */
  83 #define CRYPT_LOG_ERROR  1
  84 /** verbose log level */
  85 #define CRYPT_LOG_VERBOSE  2
  86 /** debug log level - always on stdout */
  87 #define CRYPT_LOG_DEBUG -1
  88
  89 /**
  90  * Set log function.
  91  *
  92  * @param cd crypt device handle (can be @e NULL to set default log function)
  93  * @param log user defined log function reference
  94  * @param usrptr provided identification in callback
  95  * @param level log level below (debug messages can uses other levels)
  96  * @param msg log message
  97  */
  98 void crypt_set_log_callback(struct crypt_device *cd,
  99         void (*log)(int level, const char *msg, void *usrptr),
 100         void *usrptr);
 101
 102 /**
 103  * Defines log function or use the default one otherwise.
 104  *
 105  * @see crypt_set_log_callback
 106  *
 107  * @param cd crypt device handle
 108  * @param level log level
 109  * @param msg log message
 110  */
 111 void crypt_log(struct crypt_device *cd, int level, const char *msg);
 112 /** @} */
 113
 114 /**
 115  * Set confirmation callback (yes/no)
 116  *
 117  * If code need confirmation (like resetting uuid or restoring LUKS header from file)
 118  * this function is called. If not defined, everything is confirmed.
 119  *
 120  * Callback function @e confirm should return @e 0 if operation is declined,
 121  * other values mean accepted.
 122  *
 123  * @param cd crypt device handle
 124  * @param confirm user defined confirm callback reference
 125  * @param usrptr provided identification in callback
 126  * @param msg Message for user to confirm
 127  *
 128  * @note Current version of cryptsetup API requires confirmation only when UUID is being changed
 129  */
 130 void crypt_set_confirm_callback(struct crypt_device *cd,
 131         int (*confirm)(const char *msg, void *usrptr),
 132         void *usrptr);
 133
 134 /**
 135  * Set password query callback.
 136  *
 137  * If code need @e _interactive_ query for password, this callback is called.
 138  * If not defined, compiled-in default is called (uses terminal input).
 139  *
 140  * Callback should return length of password in buffer
 141  * or negative errno value in case of error.
 142  *
 143  * @param cd crypt device handle
 144  * @param usrptr provided identification in callback
 145  * @param msg Message for user
 146  * @param buf buffer for password
 147  * @param length size of buffer
 148  *
 149  * @note Note that if this function is defined, verify option is ignored
 150  *   (caller which provided callback is responsible for password verification)
 151  * @note Only zero terminated passwords can be entered this way, for complex
 152  *   use API functions directly.
 153  * @note Maximal length of password is limited to @e length @e - @e 1 (minimal 511 chars)
 154  *
 155  * @see Callback function is used in these call provided, that certain conditions are met:
 156  * @li crypt_keyslot_add_by_passphrase
 157  * @li crypt_activate_by_passphrase
 158  * @li crypt_resume_by_passphrase
 159  * @li crypt_resume_by_keyfile
 160  * @li crypt_keyslot_add_by_keyfile
 161  * @li crypt_keyslot_add_by_volume_key
 162  *
 163  */
 164 void crypt_set_password_callback(struct crypt_device *cd,
 165         int (*password)(const char *msg, char *buf, size_t length, void *usrptr),
 166         void *usrptr);
 167
 168 /**
 169  * Set timeout for interactive password entry using default
 170  * password callback
 171  *
 172  * @param cd crypt device handle
 173  * @param timeout_sec timeout in seconds
 174  */
 175 void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
 176
 177 /**
 178  * Set number of retries in case password input has been incorrect
 179  *
 180  * @param cd crypt device handle
 181  * @param tries the number
 182  */
 183 void crypt_set_password_retry(struct crypt_device *cd, int tries);
 184
 185 /**
 186  * Set how long should cryptsetup iterate in PBKDF2 pseudorandom function.
 187  * Default value heads towards the iterations which takes around 1 second
 188  *
 189  * @param cd crypt device handle
 190  * @param iteration_time_ms the time in ms
 191  */
 192 void crypt_set_iterarion_time(struct crypt_device *cd, uint64_t iteration_time_ms);
 193
 194 /**
 195  * Set whether passphrase will be verified on input
 196  * (user has to input same passphrase twice)
 197  *
 198  * @param cd crypt device handle
 199  * @param password_verify @e 0 = false, @e !0 true
 200  */
 201 void crypt_set_password_verify(struct crypt_device *cd, int password_verify);
 202
 203 /**
 204  * Set data device (encrypted payload area device) if LUKS header is separated
 205  *
 206  * @param cd crypt device handle
 207  * @param device path to device
 208  *
 209  * @pre context is of LUKS type
 210  * @pre unlike @ref crypt_init @endref, in this function param @e device
 211  *      has to be block device (at least 512B large)
 212  */
 213 int crypt_set_data_device(struct crypt_device *cd, const char *device);
 214
 215 /**
 216  * @defgroup rng "Cryptsetup (pseudo)random API"
 217  *
 218  * @addtogroup rng
 219  * @{
 220  *
 221  */
 222
 223 /** CRYPT_RNG_URANDOM - use /dev/urandom */
 224 #define CRYPT_RNG_URANDOM 0
 225 /** CRYPT_RNG_RANDOM  - use /dev/random (waits if no entropy in system) */
 226 #define CRYPT_RNG_RANDOM  1
 227
 228 /**
 229  * Set which RNG (random number generator) is used for generating long term key
 230  *
 231  * @param cd crypt device handle
 232  * @param rng_type kernel random number generator to use
 233  *
 234  */
 235 void crypt_set_rng_type(struct crypt_device *cd, int rng_type);
 236
 237 /**
 238  * Get which RNG (random number generator) is used for generating long term key
 239  *
 240  * @param cd crypt device handle
 241  * @return RNG type on success or negative errno value otherwise.
 242  *
 243  */
 244 int crypt_get_rng_type(struct crypt_device *cd);
 245
 246 /** @} */
 247
 248 /**
 249  * Helper to lock/unlock memory to avoid swap sensitive data to disk
 250  *
 251  * @param cd crypt device handle, can be @e NULL
 252  * @param lock 0 to unlock otherwise lock memory
 253  *
 254  * @returns Value indicating whether the memory is locked (function can be called multiple times).
 255  *
 256  * @note Only root can do this.
 257  * @note It locks/unlocks all process memory, not only crypt context.
 258  */
 259 int crypt_memory_lock(struct crypt_device *cd, int lock);
 260
 261 /**
 262  * @defgroup crypt_type "Cryptsetup on-disk format types"
 263  *
 264  * Set of functions, \#defines and structs related
 265  * to on-disk format types
 266  */
 267
 268 /**
 269  * @addtogroup crypt_type
 270  * @{
 271  */
 272
 273 /** regular crypt device, no on-disk header */
 274 #define CRYPT_PLAIN "PLAIN"
 275 /** LUKS version 1 header on-disk */
 276 #define CRYPT_LUKS1 "LUKS1"
 277 /** loop-AES compatibility mode */
 278 #define CRYPT_LOOPAES "LOOPAES"
 279
 280 /**
 281  * Get device type
 282  *
 283  * @param cd crypt device handle
 284  * @return string according to device type or @e NULL if not known.
 285  */
 286 const char *crypt_get_type(struct crypt_device *cd);
 287
 288 /**
 289  *
 290  * Structure used as parameter for PLAIN device type
 291  *
 292  * @see crypt_format
 293  */
 294 struct crypt_params_plain {
 295         const char *hash; /**< password hash function */
 296         uint64_t offset; /**< offset in sectors */
 297         uint64_t skip; /**< IV offset / initialization sector */
 298         uint64_t size; /**< size of mapped device or @e 0 for autodetection */
 299 };
 300
 301 /**
 302  * Structure used as parameter for LUKS device type
 303  *
 304  * @see crypt_format, crypt_load
 305  *
 306  * @note during crypt_format @e data_device attribute determines
 307  *       if the LUKS header is separated from encrypted payload device
 308  *
 309  */
 310 struct crypt_params_luks1 {
 311         const char *hash; /**< hash used in LUKS header */
 312         size_t data_alignment; /**< data alignment in sectors, data offset is multiple of this */
 313         const char *data_device; /**< detached encrypted data device or @e NULL */
 314 };
 315
 316 /**
 317  *
 318  * Structure used as parameter for loop-AES device type
 319  *
 320  * @see crypt_format
 321  *
 322  */
 323 struct crypt_params_loopaes {
 324         const char *hash; /**< key hash function */
 325         uint64_t offset;  /**< offset in sectors */
 326         uint64_t skip;    /**< IV offset / initialization sector */
 327 };
 328
 329 /** @} */
 330
 331 /**
 332  * Create (format) new crypt device (and possible header on-disk) but not activates it.
 333  *
 334  * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
 335  *
 336  * @param cd crypt device handle
 337  * @param type type of device (optional params struct must be of this type)
 338  * @param cipher (e.g. "aes")
 339  * @param cipher_mode including IV specification (e.g. "xts-plain")
 340  * @param uuid requested UUID or @e NULL if it should be generated
 341  * @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
 342  * @param volume_key_size size of volume key in bytes.
 343  * @param params crypt type specific parameters (see @link crypt_type @endlink)
 344  *
 345  * @returns @e 0 on success or negative errno value otherwise.
 346  *
 347  * @note Note that crypt_format does not enable any keyslot (in case of work with LUKS device), but it stores volume key internally
 348  *       and subsequent crypt_keyslot_add_* calls can be used.
 349  */
 350 int crypt_format(struct crypt_device *cd,
 351         const char *type,
 352         const char *cipher,
 353         const char *cipher_mode,
 354         const char *uuid,
 355         const char *volume_key,
 356         size_t volume_key_size,
 357         void *params);
 358
 359 /**
 360  * Set new UUID for already existing device
 361  *
 362  * @param cd crypt device handle
 363  * @param uuid requested UUID or @e NULL if it should be generated
 364  *
 365  * @returns 0 on success or negative errno value otherwise.
 366  *
 367  * @note Currently, only LUKS device type are supported
 368  */
 369 int crypt_set_uuid(struct crypt_device *cd,
 370                    const char *uuid);
 371
 372 /**
 373  * Load crypt device parameters from on-disk header
 374  *
 375  * @param cd crypt device handle
 376  * @param requested_type - use @e NULL for all known
 377  * @param params crypt type specific parameters (see @link crypt_type @endlink)
 378  *
 379  * @returns 0 on success or negative errno value otherwise.
 380  *
 381  * @post In case LUKS header is read successfully but payload device is too small
 382  * error is returned and device type in context is set to @e NULL
 383  *
 384  * @note Note that in current version load works only for LUKS device type
 385  *
 386  */
 387 int crypt_load(struct crypt_device *cd,
 388                const char *requested_type,
 389                void *params);
 390
 391 /**
 392  * Resize crypt device
 393  *
 394  * @param cd - crypt device handle
 395  * @param name - name of device to resize
 396  * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
 397  *
 398  * @return @e 0 on success or negative errno value otherwise.
 399  */
 400 int crypt_resize(struct crypt_device *cd,
 401                  const char *name,
 402                  uint64_t new_size);
 403
 404 /**
 405  * Suspends crypt device.
 406  *
 407  * @param cd crypt device handle, can be @e NULL
 408  * @param name name of device to suspend
 409  *
 410  * @return 0 on success or negative errno value otherwise.
 411  *
 412  * @note Only LUKS device type is supported
 413  *
 414  */
 415 int crypt_suspend(struct crypt_device *cd,
 416                   const char *name);
 417
 418 /**
 419  * Resumes crypt device using passphrase.
 420  *
 421  *
 422  * @param cd crypt device handle
 423  * @param name name of device to resume
 424  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 425  * @param passphrase passphrase used to unlock volume key, @e NULL for query
 426  * @param passphrase_size size of @e passphrase (binary data)
 427  *
 428  * @return unlocked key slot number or negative errno otherwise.
 429  *
 430  * @note Only LUKS device type is supported
 431  */
 432 int crypt_resume_by_passphrase(struct crypt_device *cd,
 433                                const char *name,
 434                                int keyslot,
 435                                const char *passphrase,
 436                                size_t passphrase_size);
 437
 438 /**
 439  * Resumes crypt device using key file.
 440  *
 441  * @param cd crypt device handle
 442  * @param name name of device to resume
 443  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 444  * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
 445  * @param keyfile_size number of bytes to read from @keyfile, 0 is unlimited
 446  *
 447  * @return unlocked key slot number or negative errno otherwise.
 448  */
 449 int crypt_resume_by_keyfile(struct crypt_device *cd,
 450                             const char *name,
 451                             int keyslot,
 452                             const char *keyfile,
 453                             size_t keyfile_size);
 454
 455 /**
 456  * Releases crypt device context and used memory.
 457  *
 458  * @param cd crypt device handle
 459  */
 460 void crypt_free(struct crypt_device *cd);
 461
 462 /**
 463  * @defgroup keyslot "Cryptsetup LUKS keyslots API"
 464  * @addtogroup keyslot
 465  * @{
 466  *
 467  */
 468
 469 /** iterate through all keyslots and find first one that fits */
 470 #define CRYPT_ANY_SLOT -1
 471
 472 /**
 473  * Add key slot using provided passphrase
 474  *
 475  * @pre @e cd contains initialized and formatted LUKS device context
 476  *
 477  * @param cd crypt device handle
 478  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 479  * @param passphrase passphrase used to unlock volume key, @e NULL for query
 480  * @param passphrase_size size of @passphrase (binary data)
 481  * @param new_passphrase passphrase for new keyslot, @e NULL for query
 482  * @param new_passphrase_size size of @e new_passphrase (binary data)
 483  *
 484  * @return allocated key slot number or negative errno otherwise.
 485  */
 486 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
 487         int keyslot,
 488         const char *passphrase,
 489         size_t passphrase_size,
 490         const char *new_passphrase,
 491         size_t new_passphrase_size);
 492
 493 /**
 494  * Get number of keyslots supported for device type.
 495  *
 496  * @param type crypt device type
 497  *
 498  * @return slot count or negative errno otherwise if device
 499  * doesn't not support keyslots.
 500  */
 501 int crypt_keyslot_max(const char *type);
 502
 503 /**
 504 * Add key slot using provided key file path
 505  *
 506  * @pre @e cd contains initialized and formatted LUKS device context
 507  *
 508  * @param cd crypt device handle
 509  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 510  * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
 511  * @param keyfile_size number of bytes to read from @keyfile, @e 0 is unlimited
 512  * @param new_keyfile keyfile for new keyslot, @e NULL for passphrase query
 513  * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
 514  *
 515  * @return allocated key slot number or negative errno otherwise.
 516  *
 517  * @note Note that @e keyfile can be "-" for STDIN
 518  *
 519  */
 520 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
 521         int keyslot,
 522         const char *keyfile,
 523         size_t keyfile_size,
 524         const char *new_keyfile,
 525         size_t new_keyfile_size);
 526
 527 /**
 528  * Add key slot using provided volume key
 529  *
 530  * @pre @e cd contains initialized and formatted LUKS device context
 531  *
 532  * @param cd crypt device handle
 533  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 534  * @param volume_key provided volume key or @e NULL if used after crypt_format
 535  * @param volume_key_size size of @volume_key
 536  * @param passphrase passphrase for new keyslot, @e NULL for query
 537  * @param passphrase_size size of @passphrase
 538  *
 539  * @return allocated key slot number or negative errno otherwise.
 540  *
 541  */
 542 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
 543         int keyslot,
 544         const char *volume_key,
 545         size_t volume_key_size,
 546         const char *passphrase,
 547         size_t passphrase_size);
 548
 549 /**
 550  * Destroy (and disable) key slot
 551  *
 552  * @pre @e cd contains initialized and formatted LUKS device context
 553  *
 554  * @param cd crypt device handle
 555  * @param keyslot requested key slot to destroy
 556  *
 557  * @return @e 0 on success or negative errno value otherwise.
 558  *
 559  * @note Note that there is no passphrase verification used.
 560  */
 561 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
 562
 563 /** @} */
 564
 565 /**
 566  * @defgroup aflags "Device runtime attributes"
 567  *
 568  * Activation flags
 569  *
 570  * @addtogroup aflags
 571  * @{
 572  *
 573  */
 574 /** device is read only */
 575 #define CRYPT_ACTIVATE_READONLY (1 << 0)
 576 /** ignored */
 577 #define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
 578 /** ??? */
 579 #define CRYPT_ACTIVATE_SHARED   (1 << 2)
 580 /** enable discards aka TRIM */
 581 #define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
 582
 583 /**
 584  * Active device runtime attributes
 585  */
 586 struct crypt_active_device {
 587         uint64_t offset; /**< offset in sectors */
 588         uint64_t iv_offset; /**< IV initialization sector */
 589         uint64_t size; /**< active device size */
 590         uint32_t flags; /**< activation flags */
 591 };
 592
 593 /**
 594  * Receives runtime attributes of active crypt device
 595  *
 596  * @param cd crypt device handle (can be @e NULL)
 597  * @param name name of active device
 598  * @param cad preallocated active device attributes to fill
 599  *
 600  * @return @e 0 on success or negative errno value otherwise
 601  *
 602  */
 603 int crypt_get_active_device(struct crypt_device *cd,
 604                             const char *name,
 605                             struct crypt_active_device *cad);
 606
 607 /** @} */
 608
 609 /**
 610  * Activate device or check passphrase
 611  *
 612  * @param cd crypt device handle
 613  * @param name name of device to create, if @e NULL only check passphrase
 614  * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
 615  * @param passphrase passphrase used to unlock volume key, @e NULL for query
 616  * @param passphrase_size size of @e passphrase
 617  * @param flags activation flags
 618  *
 619  * @return unlocked key slot number or negative errno otherwise.
 620  */
 621 int crypt_activate_by_passphrase(struct crypt_device *cd,
 622         const char *name,
 623         int keyslot,
 624         const char *passphrase,
 625         size_t passphrase_size,
 626         uint32_t flags);
 627
 628 /**
 629  * Activate device or check using key file
 630  *
 631  * @param cd crypt device handle
 632  * @param name name of device to create, if @e NULL only check keyfile
 633  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 634  * @param keyfile key file used to unlock volume key
 635  * @param keyfile_size number of bytes to read from @keyfile, 0 is unlimited
 636  * @param flags activation flags
 637  *
 638  * @return unlocked key slot number or negative errno otherwise.
 639  */
 640 int crypt_activate_by_keyfile(struct crypt_device *cd,
 641         const char *name,
 642         int keyslot,
 643         const char *keyfile,
 644         size_t keyfile_size,
 645         uint32_t flags);
 646
 647 /**
 648  * Activate device using provided volume key
 649  *
 650  *
 651  * @param cd crypt device handle
 652  * @param name name of device to create, if @e NULL only check volume key
 653  * @param volume_key provided volume key (or @e NULL to use internal)
 654  * @param volume_key_size size of @volume_key
 655  * @param flags activation flags
 656  *
 657  * @return @e 0 on success or negative errno value otherwise.
 658  *
 659  * @note If @e NULL is used for volume_key, device has to be initialized
 660  *       by previous operation (like @ref crypt_format @endref
 661  *       or @ref crypt_init_by_name @endref)
 662  */
 663 int crypt_activate_by_volume_key(struct crypt_device *cd,
 664         const char *name,
 665         const char *volume_key,
 666         size_t volume_key_size,
 667         uint32_t flags);
 668
 669 /**
 670  * Deactivate crypt device. This function tries to remove active device-mapper
 671  * mapping from kernel. Also, sensitive data like the volume key are removed from
 672  * memory
 673  *
 674  * @param cd crypt device handle, can be @e NULL
 675  * @param name name of device to deactivate
 676  *
 677  * @return @e 0 on success or negative errno value otherwise.
 678  *
 679  */
 680 int crypt_deactivate(struct crypt_device *cd, const char *name);
 681
 682 /**
 683  * Get volume key from of crypt device
 684  *
 685  * @param cd crypt device handle
 686  * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
 687  * @param volume_key buffer for volume key
 688  * @param volume_key_size on input, size of buffer @e volume_key,
 689  *        on output size of @e volume_key
 690  * @param passphrase passphrase used to unlock volume key
 691  * @param passphrase_size size of @e passphrase
 692  *
 693  * @return unlocked key slot number or negative errno otherwise.
 694  */
 695 int crypt_volume_key_get(struct crypt_device *cd,
 696         int keyslot,
 697         char *volume_key,
 698         size_t *volume_key_size,
 699         const char *passphrase,
 700         size_t passphrase_size);
 701
 702 /**
 703  * Verify that provided volume key is valid for crypt device
 704  *
 705  * @param cd crypt device handle
 706  * @param volume_key provided volume key
 707  * @param volume_key_size size of @e volume_key
 708  *
 709  * @return @e 0 on success or negative errno value otherwise.
 710  */
 711 int crypt_volume_key_verify(struct crypt_device *cd,
 712         const char *volume_key,
 713         size_t volume_key_size);
 714
 715
 716 /*
 717  * @defgroup devstat "dmcrypt device status"
 718  * @addtogroup devstat
 719  * @{
 720  */
 721
 722 typedef enum {
 723         CRYPT_INVALID, /**< device mapping is invalid in this context */
 724         CRYPT_INACTIVE, /**< no such mapped device */
 725         CRYPT_ACTIVE, /**< device is active */
 726         CRYPT_BUSY /**< device is active and has open count > 0 */
 727 } crypt_status_info;
 728
 729 /**
 730  * Get status info about device name
 731  *
 732  * @param cd crypt device handle, can be @e NULL
 733  * @param name crypt device name
 734  *
 735  * @return value defined by crypt_status_info.
 736  *
 737  */
 738 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
 739
 740 /**
 741  * Dump text-formatted information about crypt device to log output
 742  *
 743  * @param cd crypt device handle
 744  *
 745  * @return @e 0 on success or negative errno value otherwise.
 746  */
 747 int crypt_dump(struct crypt_device *cd);
 748
 749 /**
 750  * Get cipher used in device
 751  *
 752  * @param cd crypt device handle
 753  *
 754  * @return used cipher, e.g. "aes" or @e NULL otherwise
 755  *
 756  */
 757 const char *crypt_get_cipher(struct crypt_device *cd);
 758
 759 /**
 760  * Get cipher mode used in device
 761  *
 762  * @param cd crypt device handle
 763  *
 764  * @return used cipher mode e.g. "xts-plain" or @e otherwise
 765  *
 766  */
 767 const char *crypt_get_cipher_mode(struct crypt_device *cd);
 768
 769 /**
 770  * Get device UUID
 771  *
 772  * @param cd crypt device handle
 773  *
 774  * @return device UUID or @e NULL if not set
 775  *
 776  */
 777 const char *crypt_get_uuid(struct crypt_device *cd);
 778
 779 /**
 780  * Get path to underlaying device
 781  *
 782  * @param cd crypt device handle
 783  *
 784  * @return path to underlaying device name
 785  *
 786  */
 787 const char *crypt_get_device_name(struct crypt_device *cd);
 788
 789 /**
 790  * Get device offset in sectors where real data starts on underlying device)
 791  *
 792  * @param cd crypt device handle
 793  *
 794  * @return device offset in sectors
 795  *
 796  */
 797 uint64_t crypt_get_data_offset(struct crypt_device *cd);
 798
 799 /**
 800  * Get IV offset in sectors (skip)
 801  *
 802  * @param cd crypt device handle
 803  *
 804  * @return IV offset
 805  *
 806  */
 807 uint64_t crypt_get_iv_offset(struct crypt_device *cd);
 808
 809 /**
 810  * Get size (in bytes) of volume key for crypt device
 811  *
 812  * @param cd crypt device handle
 813  *
 814  * @return volume key size
 815  *
 816  */
 817 int crypt_get_volume_key_size(struct crypt_device *cd);
 818
 819 /**
 820  * @addtogroup keyslot
 821  * @{
 822  *
 823  */
 824 typedef enum {
 825         CRYPT_SLOT_INVALID, /**< invalid keyslot */
 826         CRYPT_SLOT_INACTIVE, /**< keyslot is inactive (free) */
 827         CRYPT_SLOT_ACTIVE, /**< keyslot is active (used) */
 828         CRYPT_SLOT_ACTIVE_LAST /**< keylost is active (used)
 829                                 *   and last used at the same time */
 830 } crypt_keyslot_info;
 831
 832 /**
 833  * Get information about particular key slot
 834  *
 835  *
 836  * @param cd crypt device handle
 837  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 838  *
 839  * @return value defined by crypt_keyslot_info
 840  *
 841  */
 842 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
 843 /** @} */
 844
 845 /**
 846  * Backup header and keyslots to file
 847  *
 848  * @param cd crypt device handle
 849  * @param requested_type type of header to backup
 850  * @param backup_file file to backup header to
 851  *
 852  * @return @e 0 on success or negative errno value otherwise.
 853  *
 854  */
 855 int crypt_header_backup(struct crypt_device *cd,
 856         const char *requested_type,
 857         const char *backup_file);
 858
 859 /**
 860  * Restore header and keyslots from backup file
 861  *
 862  *
 863  * @param cd crypt device handle
 864  * @param requested_type type of header to restore
 865  * @param backup_file file to restore header from
 866  *
 867  * @return @e 0 on success or negative errno value otherwise.
 868  *
 869  */
 870 int crypt_header_restore(struct crypt_device *cd,
 871         const char *requested_type,
 872         const char *backup_file);
 873
 874 /**
 875  * Receives last reported error
 876  *
 877  * @param buf buffef for message
 878  * @param size size of buffer
 879  *
 880  * @note Note that this is old API function using global context.
 881  * All error messages are reported also through log callback.
 882  */
 883 void crypt_get_error(char *buf, size_t size);
 884
 885 /**
 886  * Get directory where mapped crypt devices are created
 887  *
 888  * @return the directory path
 889  */
 890 const char *crypt_get_dir(void);
 891
 892 /**
 893  * @defgroup dbg "Library debug level"
 894  *
 895  * Set library debug level
 896  *
 897  * @addtogroup dbg
 898  * @{
 899  */
 900
 901 /** Debug all */
 902 #define CRYPT_DEBUG_ALL  -1
 903 /** Debug none */
 904 #define CRYPT_DEBUG_NONE  0
 905
 906 /**
 907  * Set the debug level for library
 908  *
 909  * @param level debug level
 910  *
 911  */
 912 void crypt_set_debug_level(int level);
 913
 914 /** @} */
 915
 916 #ifdef __cplusplus
 917 }
 918 #endif
 919 #endif /* _LIBCRYPTSETUP_H */