lib/libcryptsetup.h

   1 #ifndef _LIBCRYPTSETUP_H
   2 #define _LIBCRYPTSETUP_H
   3 #ifdef __cplusplus
   4 extern "C" {
   5 #endif
   6
   7 #include <stdint.h>
   8
   9 struct crypt_device; /* crypt device handle */
  10
  11 /**
  12  * Initialise crypt device handle and check if provided device exists.
  13  *
  14  * Returns 0 on success or negative errno value otherwise.
  15  *
  16  * @cd - returns pointer to crypt device handle
  17  * @device - path to device
  18  *
  19  * Note that logging is not initialized here, possible messages uses
  20  * default log function.
  21  */
  22 int crypt_init(struct crypt_device **cd, const char *device);
  23
  24 /**
  25  * Initialise crypt device handle from provided active device name
  26  * and check if provided device exists.
  27  *
  28  * Returns 0 on success or negative errno value otherwise.
  29  *
  30  * @cd - crypt device handle
  31  * @name - name of active crypt device
  32  */
  33 int crypt_init_by_name(struct crypt_device **cd, const char *name);
  34
  35 /**
  36  * Set log function.
  37  *
  38  * @cd - crypt device handle
  39  * @usrptr - provided identification in callback
  40  * @class  - log type below (debug messages can uses other levels)
  41  * @msg    - log message
  42  */
  43 #define CRYPT_LOG_NORMAL 0
  44 #define CRYPT_LOG_ERROR  1
  45 #define CRYPT_LOG_DEBUG -1 /* always on stdout */
  46 void crypt_set_log_callback(struct crypt_device *cd,
  47         void (*log)(int class, const char *msg, void *usrptr),
  48         void *usrptr);
  49
  50 /**
  51  * Set confirmation callback (yes/no)
  52  *
  53  * If code need confirmation (like deleting last key slot) this function
  54  * is called. If not defined, everything is confirmed.
  55  *
  56  * Calback should return 0 if operation is declined, other values mean accepted.
  57  *
  58  * @cd - crypt device handle
  59  * @usrptr - provided identification in callback
  60  * @msg - Message for user to confirm
  61  */
  62 void crypt_set_confirm_callback(struct crypt_device *cd,
  63         int (*confirm)(const char *msg, void *usrptr),
  64         void *usrptr);
  65
  66 /**
  67  * Set password query callback.
  68  *
  69  * If code need _interactive_ query for password, this callback is called.
  70  * If not defined, compiled-in default is called (uses terminal input).
  71  *
  72  * @cd - crypt device handle
  73  * @usrptr - provided identification in callback
  74  * @msg - Message for user
  75  * @buf - buffer for password
  76  * @length - size of buffer
  77  *
  78  * - Note that if this function is defined, verify option is ignored
  79  *   (caller whch provided callback is responsible fo password verification)
  80  * - Only zero terminated passwords can be enteted this way, for complex
  81  *   API functions directly.
  82  * - Maximal length of password is limited to @length-1 (minimal 511 chars)
  83  */
  84 void crypt_set_password_callback(struct crypt_device *cd,
  85         int (*password)(const char *msg, char *buf, size_t length, void *usrptr),
  86         void *usrptr);
  87
  88 /**
  89  * Various crypt device parameters
  90  *
  91  * @cd - crypt device handle
  92  * @timeout - timeout in secons for password entry if compiled-in function used
  93  * @password_retry - number of tries for password if not verified
  94  * @iteration_time - iteration time for LUKS header in miliseconds
  95  * @password_verify - for compiled-in password query always verify passwords twice
  96  */
  97 void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
  98 void crypt_set_password_retry(struct crypt_device *cd, int tries);
  99 void crypt_set_iterarion_time(struct crypt_device *cd, uint64_t iteration_time_ms);
 100 void crypt_set_password_verify(struct crypt_device *cd, int password_verify);
 101
 102 /**
 103  * Helper to lock/unlock memory to avoid swap sensitive data to disk
 104  *
 105  * @cd - crypt device handle, can be NULL
 106  * @lock - 0 to unloct otherwise lock memory
 107  *
 108  * Return value indicates that memory is locked (function can be called multiple times).
 109  * Only root can do this. Note it locks/unlocks all process memory, not only crypt context.
 110  */
 111 int crypt_memory_lock(struct crypt_device *cd, int lock);
 112
 113 #define CRYPT_PLAIN "PLAIN" /* regular crypt device, no on-disk header */
 114 #define CRYPT_LUKS1 "LUKS1" /* LUKS version 1 header on-disk */
 115
 116 struct crypt_params_plain {
 117         const char *hash; /* password hash function */
 118         uint64_t offset;  /* offset in sectors */
 119         uint64_t skip;    /* IV initilisation sector */
 120 };
 121
 122 struct crypt_params_luks1 {
 123         const char *hash;      /* hash used in LUKS header */
 124         size_t data_alignment; /* in sectors, data offset is multiple of this */
 125 };
 126
 127 /**
 128  * Create (format) new crypt device (and possible header on-disk) but not activates it.
 129  *
 130  * Returns 0 on success or negative errno value otherwise.
 131  *
 132  * @cd - crypt device handle
 133  * @type - type of device (optional params struct must be of this type)
 134  * @cipher - (e.g. "aes")
 135  * @cipher_mode - including IV specification (e.g. "xts-plain")
 136  * @uuid - requested UUID or NULL if it should be generated
 137  * @volume_key - pre-generated volume key or NULL if it should be generated (only for LUKS)
 138  * @volume_key_size - size og volume key in bytes.
 139  * @params - crypt type specific parameters
 140  *
 141  * Note that crypt_format do not enable any keyslot, but it stores volume key internally
 142  * and subsequent crypt_keyslot_add_* calls can be used.
 143  * (It is the only situation when crypt_keyslot_add_* do not require active key slots.)
 144  */
 145 int crypt_format(struct crypt_device *cd,
 146         const char *type,
 147         const char *cipher,
 148         const char *cipher_mode,
 149         const char *uuid,
 150         const char *volume_key,
 151         size_t volume_key_size,
 152         void *params);
 153
 154 /**
 155  * Load crypt device parameters from on-disk header
 156  *
 157  * Returns 0 on success or negative errno value otherwise.
 158  *
 159  * @cd - crypt device handle
 160  * @requested_type - use NULL for all known
 161  * @params - crypt type specific parameters
 162  */
 163 int crypt_load(struct crypt_device *cd,
 164                const char *requested_type,
 165                void *params);
 166
 167 /**
 168  * Suspends crypt device.
 169  *
 170  * Returns 0 on success or negative errno value otherwise.
 171  *
 172  * @cd - crypt device handle, can be NULL
 173  * @name - name of device to suspend
 174  */
 175 int crypt_suspend(struct crypt_device *cd,
 176                   const char *name);
 177
 178 /**
 179  * Resumes crypt device using passphrase.
 180  *
 181  * Returns unlocked key slot number or negative errno otherwise.
 182  *
 183  * @cd - crypt device handle
 184  * @name - name of device to resume
 185  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
 186  * @passphrase - passphrase used to unlock volume key, NULL for query
 187  * @passphrase_size - size of @passphrase (binary data)
 188  */
 189 int crypt_resume_by_passphrase(struct crypt_device *cd,
 190                                const char *name,
 191                                int keyslot,
 192                                const char *passphrase,
 193                                size_t passphrase_size);
 194
 195 /**
 196  * Resumes crypt device using key file.
 197  *
 198  * Returns unlocked key slot number or negative errno otherwise.
 199  *
 200  * @cd - crypt device handle
 201  * @name - name of device to resume
 202  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
 203  * @keyfile - key file used to unlock volume key, NULL for passphrase query
 204  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
 205  */
 206 int crypt_resume_by_keyfile(struct crypt_device *cd,
 207                             const char *name,
 208                             int keyslot,
 209                             const char *keyfile,
 210                             size_t keyfile_size);
 211
 212 /**
 213  * Releases crypt device context and used memory.
 214  *
 215  * @cd - crypt device handle
 216  */
 217 void crypt_free(struct crypt_device *cd);
 218
 219 /**
 220  * Add key slot using provided passphrase
 221  *
 222  * Returns allocated key slot number or negative errno otherwise.
 223  *
 224  * @cd - crypt device handle
 225  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
 226  * @passphrase - passphrase used to unlock volume key, NULL for query
 227  * @passphrase_size - size of @passphrase (binary data)
 228  * @new_passphrase - passphrase for new keyslot, NULL for query
 229  * @new_passphrase_size - size of @new_passphrase (binary data)
 230  */
 231 #define CRYPT_ANY_SLOT -1
 232 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
 233         int keyslot,
 234         const char *passphrase,
 235         size_t passphrase_size,
 236         const char *new_passphrase,
 237         size_t new_passphrase_size);
 238
 239 /**
 240 * Add key slot using provided key file path
 241  *
 242  * Returns allocated key slot number or negative errno otherwise.
 243  *
 244  * @cd - crypt device handle
 245  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
 246  * @keyfile - key file used to unlock volume key, NULL for passphrase query
 247  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
 248  * @new_keyfile - keyfile for new keyslot, NULL for passphrase query
 249  * @new_keyfile_size - number of bytes to read from @new_keyfile, 0 is unlimited
 250  *
 251  * Note that @keyfile can be "-" for STDIN
 252  */
 253 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
 254         int keyslot,
 255         const char *keyfile,
 256         size_t keyfile_size,
 257         const char *new_keyfile,
 258         size_t new_keyfile_size);
 259
 260 /**
 261  * Add key slot using provided volume key
 262  *
 263  * Returns allocated key slot number or negative errno otherwise.
 264  *
 265  * @cd - crypt device handle
 266  * @keyslot - requested keyslot or CRYPT_ANY_SLOT
 267  * @volume_key - provided volume key or NULL if used after crypt_format
 268  * @volume_key_size - size of @volume_key
 269  * @passphrase - passphrase for new keyslot, NULL for query
 270  * @passphrase_size - size of @passphrase
 271  */
 272 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
 273         int keyslot,
 274         const char *volume_key,
 275         size_t volume_key_size,
 276         const char *passphrase,
 277         size_t passphrase_size);
 278
 279 /**
 280  * Destroy (and disable) key slot
 281  *
 282  * Returns 0 on success or negative errno value otherwise.
 283  *
 284  * @cd - crypt device handle
 285  * @keyslot - requested key slot to destroy
 286  *
 287  * Note that there is no passphrase verification used.
 288  */
 289 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
 290
 291 /**
 292  * Activation flags
 293  */
 294 #define CRYPT_ACTIVATE_READONLY (1 << 0)
 295 #define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
 296
 297 /**
 298  * Activate device or check passphrase
 299  *
 300  * Returns unlocked key slot number or negative errno otherwise.
 301  *
 302  * @cd - crypt device handle
 303  * @name - name of device to create, if NULL only check passphrase
 304  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
 305  * @passphrase - passphrase used to unlock volume key, NULL for query
 306  * @passphrase_size - size of @passphrase
 307  * @flags - activation flags
 308  */
 309 int crypt_activate_by_passphrase(struct crypt_device *cd,
 310         const char *name,
 311         int keyslot,
 312         const char *passphrase,
 313         size_t passphrase_size,
 314         uint32_t flags);
 315
 316 /**
 317  * Activate device or check using key file
 318  *
 319  * Returns unlocked key slot number or negative errno otherwise.
 320  *
 321  * @cd - crypt device handle
 322  * @name - name of device to create, if NULL only check keyfile
 323  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
 324  * @keyfile - key file used to unlock volume key
 325  * @keyfile_size - number of bytes to read from @keyfile, 0 is unlimited
 326  * @flags - activation flags
 327  */
 328 int crypt_activate_by_keyfile(struct crypt_device *cd,
 329         const char *name,
 330         int keyslot,
 331         const char *keyfile,
 332         size_t keyfile_size,
 333         uint32_t flags);
 334
 335 /**
 336  * Activate device using provided volume key
 337  *
 338  * Returns 0 on success or negative errno value otherwise.
 339  *
 340  * @cd - crypt device handle
 341  * @name - name of device to create, if NULL only check volume key
 342  * @volume_key - provided volume key
 343  * @volume_key_size - size of @volume_key
 344  * @flags - activation flags
 345  */
 346 int crypt_activate_by_volume_key(struct crypt_device *cd,
 347         const char *name,
 348         const char *volume_key,
 349         size_t volume_key_size,
 350         uint32_t flags);
 351
 352 /**
 353  * Deactivate crypt device
 354  *
 355  * @cd - crypt device handle, can be NULL
 356  * @name - name of device to deactivate
 357   */
 358 int crypt_deactivate(struct crypt_device *cd, const char *name);
 359
 360 /**
 361  * Get volume key from of crypt device
 362  *
 363  * Returns unlocked key slot number or negative errno otherwise.
 364  *
 365  * @cd - crypt device handle
 366  * @keyslot - use this keyslot or CRYPT_ANY_SLOT
 367  * @volume_key - buffer for volume key
 368  * @volume_key_size - on input, size of buffer @volume_key,
 369  *                    on output size of @volume_key
 370  * @passphrase - passphrase used to unlock volume key, NULL for query
 371  * @passphrase_size - size of @passphrase
 372  */
 373 int crypt_volume_key_get(struct crypt_device *cd,
 374         int keyslot,
 375         char *volume_key,
 376         size_t *volume_key_size,
 377         const char *passphrase,
 378         size_t passphrase_size);
 379
 380 /**
 381  * Verify that provided volume key is valid for crypt device
 382  *
 383  * Returns 0 on success or negative errno value otherwise.
 384  *
 385  * @cd - crypt device handle
 386  * @volume_key - provided volume key
 387  * @volume_key_size - size of @volume_key
 388  */
 389 int crypt_volume_key_verify(struct crypt_device *cd,
 390         const char *volume_key,
 391         size_t volume_key_size);
 392
 393 /**
 394  * Get status info about device name
 395  *
 396  * Returns value defined by crypt_status_info.
 397  *
 398  * @cd - crypt device handle, can be NULL
 399  * @name -crypt device name
 400  *
 401  * INACTIVE - no such mapped device
 402  * ACTIVE - device is active
 403  * BUSY - device is active and has open count > 0
 404  */
 405 typedef enum { INVALID, INACTIVE, ACTIVE, BUSY } crypt_status_info;
 406 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
 407
 408 /**
 409  * Dump text-formatted information about crypt device to log output
 410  *
 411  * Returns 0 on success or negative errno value otherwise.
 412  *
 413  * @cd - crypt device handle, can be NULL
 414  */
 415 int crypt_dump(struct crypt_device *cd);
 416
 417 /**
 418  * Various crypt device info functions
 419  *
 420  * @cd - crypt device handle
 421  *
 422  * cipher - used cipher, e.g. "aes" or NULL otherwise
 423  * cipher_mode - used cipher mode including IV, e.g. "xts-plain" or NULL otherwise
 424  * uuid - device UUID or NULL if not set
 425  * data_offset - device offset in sectors where real data starts on underlying device)
 426  * volume_key_size - size (in bytes) of volume key for crypt device
 427  */
 428 const char *crypt_get_cipher(struct crypt_device *cd);
 429 const char *crypt_get_cipher_mode(struct crypt_device *cd);
 430 const char *crypt_get_uuid(struct crypt_device *cd);
 431 uint64_t crypt_get_data_offset(struct crypt_device *cd);
 432 int crypt_get_volume_key_size(struct crypt_device *cd);
 433
 434 /**
 435  * Get information about particular key slot
 436  *
 437  * Returns value defined by crypt_keyslot_info.
 438  *
 439  * @cd - crypt device handle
 440  * @keyslot - requested keyslot to check or CRYPT_ANY_SLOT
 441  */
 442 typedef enum { SLOT_INVALID, SLOT_INACTIVE, SLOT_ACTIVE, SLOT_ACTIVE_LAST } crypt_keyslot_info;
 443 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
 444
 445 /**
 446  * Backup header and keyslots to file
 447  *
 448  * Returns 0 on success or negative errno value otherwise.
 449  *
 450  * @cd - crypt device handle
 451  * @requested_type - type of header to backup
 452  * @backup_file - file to backup header to
 453  */
 454 int crypt_header_backup(struct crypt_device *cd,
 455         const char *requested_type,
 456         const char *backup_file);
 457
 458 /**
 459  * Restore header and keyslots from backup file
 460  *
 461  * Returns 0 on success or negative errno value otherwise.
 462  *
 463  * @cd - crypt device handle
 464  * @requested_type - type of header to restore
 465  * @backup_file - file to restore header from
 466  */
 467 int crypt_header_restore(struct crypt_device *cd,
 468         const char *requested_type,
 469         const char *backup_file);
 470
 471 /**
 472  * Receives last reported error
 473  *
 474  * @buf - buffef for message
 475  * @size - size of buffer
 476  *
 477  * Note that this is old API function using global context.
 478  * All error messages are reported also through log callback.
 479  */
 480 void crypt_get_error(char *buf, size_t size);
 481
 482 /**
 483  * Get directory where mapped crypt devices are created
 484  */
 485 const char *crypt_get_dir(void);
 486
 487 /**
 488  * Set library debug level
 489  */
 490 #define CRYPT_DEBUG_ALL  -1
 491 #define CRYPT_DEBUG_NONE  0
 492 void crypt_set_debug_level(int level);
 493
 494 /**
 495  * OLD DEPRECATED API **********************************
 496  *
 497  * Provided only for backward compatibility.
 498  */
 499
 500 struct interface_callbacks {
 501     int (*yesDialog)(char *msg);
 502     void (*log)(int class, char *msg);
 503 };
 504
 505 #define CRYPT_FLAG_VERIFY               (1 << 0)
 506 #define CRYPT_FLAG_READONLY             (1 << 1)
 507 #define CRYPT_FLAG_VERIFY_IF_POSSIBLE   (1 << 2)
 508 #define CRYPT_FLAG_VERIFY_ON_DELKEY     (1 << 3)
 509 #define CRYPT_FLAG_NON_EXCLUSIVE_ACCESS (1 << 4)
 510
 511 struct crypt_options {
 512         const char      *name;
 513         const char      *device;
 514
 515         const char      *cipher;
 516         const char      *hash;
 517
 518         const char      *passphrase;
 519         int             passphrase_fd;
 520         const char      *key_file;
 521         const char      *new_key_file;
 522         int             key_size;
 523
 524         unsigned int    flags;
 525         int             key_slot;
 526
 527         uint64_t        size;
 528         uint64_t        offset;
 529         uint64_t        skip;
 530         uint64_t        iteration_time;
 531         uint64_t        timeout;
 532
 533         uint64_t        align_payload;
 534         int             tries;
 535
 536         struct interface_callbacks *icb;
 537 };
 538
 539 int crypt_create_device(struct crypt_options *options);
 540 int crypt_update_device(struct crypt_options *options);
 541 int crypt_resize_device(struct crypt_options *options);
 542 int crypt_query_device(struct crypt_options *options);
 543 int crypt_remove_device(struct crypt_options *options);
 544 int crypt_luksFormat(struct crypt_options *options);
 545 int crypt_luksOpen(struct crypt_options *options);
 546 int crypt_luksKillSlot(struct crypt_options *options);
 547 int crypt_luksRemoveKey(struct crypt_options *options);
 548 int crypt_luksAddKey(struct crypt_options *options);
 549 int crypt_luksUUID(struct crypt_options *options);
 550 int crypt_isLuks(struct crypt_options *options);
 551 int crypt_luksDump(struct crypt_options *options);
 552
 553 void crypt_put_options(struct crypt_options *options);
 554
 555 #ifdef __cplusplus
 556 }
 557 #endif
 558 #endif /* _LIBCRYPTSETUP_H */