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