lib/libcryptsetup.h

   1 /*
   2  * libcryptsetup - cryptsetup library
   3  *
   4  * Copyright (C) 2004 Jana Saout <jana@saout.de>
   5  * Copyright (C) 2004-2007 Clemens Fruhwirth <clemens@endorphin.org>
   6  * Copyright (C) 2009-2020 Red Hat, Inc. All rights reserved.
   7  * Copyright (C) 2009-2020 Milan Broz
   8  *
   9  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License
  11  * as published by the Free Software Foundation; either version 2
  12  * of the License, or (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  22  */
  23
  24 /**
  25  * @file libcryptsetup.h
  26  * @brief Public cryptsetup API
  27  *
  28  * For more verbose examples of LUKS related use cases,
  29  * please read @ref index "examples".
  30  */
  31
  32 #ifndef _LIBCRYPTSETUP_H
  33 #define _LIBCRYPTSETUP_H
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include <stddef.h>
  39 #include <stdint.h>
  40
  41 /**
  42  * @defgroup crypt-init Cryptsetup device context initialization
  43  * Set of functions for creating and destroying @e crypt_device context
  44  * @addtogroup crypt-init
  45  * @{
  46  */
  47
  48 struct crypt_device; /* crypt device handle */
  49
  50 /**
  51  * Initialize crypt device handle and check if the provided device exists.
  52  *
  53  * @param cd Returns pointer to crypt device handle
  54  * @param device Path to the backing device.
  55  *        If @e device is not a block device but a path to some file,
  56  *        the function will try to create a loopdevice and attach
  57  *        the file to the loopdevice with AUTOCLEAR flag set.
  58  *        If @e device is @e NULL function it will initialize dm backend only.
  59  *
  60  * @return @e 0 on success or negative errno value otherwise.
  61  *
  62  * @note Note that logging is not initialized here, possible messages use
  63  *       default log function.
  64  */
  65 int crypt_init(struct crypt_device **cd, const char *device);
  66
  67 /**
  68  * Initialize crypt device handle with optional data device and check
  69  * if devices exist.
  70  *
  71  * @param cd Returns pointer to crypt device handle
  72  * @param device Path to the backing device or detached header.
  73  * @param data_device Path to the data device or @e NULL.
  74  *
  75  * @return @e 0 on success or negative errno value otherwise.
  76  *
  77  * @note Note that logging is not initialized here, possible messages use
  78  *       default log function.
  79  */
  80 int crypt_init_data_device(struct crypt_device **cd,
  81         const char *device,
  82         const char *data_device);
  83
  84 /**
  85  * Initialize crypt device handle from provided active device name,
  86  * and, optionally, from separate metadata (header) device
  87  * and check if provided device exists.
  88  *
  89  * @return @e 0 on success or negative errno value otherwise.
  90  *
  91  * @param cd returns crypt device handle for active device
  92  * @param name name of active crypt device
  93  * @param header_device optional device containing on-disk header
  94  *        (@e NULL if it the same as underlying device on there is no on-disk header)
  95  *
  96  * @post In case @e device points to active LUKS device but header load fails,
  97  * context device type is set to @e NULL and @e 0 is returned as if it were successful.
  98  * Context with @e NULL device type can only be deactivated by crypt_deactivate
  99  *
 100  * @note @link crypt_init_by_name @endlink is equivalent to calling
 101  *       crypt_init_by_name_and_header(cd, name, NULL);
 102  */
 103 int crypt_init_by_name_and_header(struct crypt_device **cd,
 104         const char *name,
 105         const char *header_device);
 106
 107 /**
 108  * This is equivalent to call
 109  * @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
 110  *
 111  * @sa crypt_init_by_name_and_header
 112  */
 113 int crypt_init_by_name(struct crypt_device **cd, const char *name);
 114
 115 /**
 116  * Release crypt device context and used memory.
 117  *
 118  * @param cd crypt device handle
 119  */
 120 void crypt_free(struct crypt_device *cd);
 121
 122 /**
 123  * Set confirmation callback (yes/no).
 124  *
 125  * If code need confirmation (like resetting uuid or restoring LUKS header from file)
 126  * this function is called. If not defined, everything is confirmed.
 127  *
 128  * Callback function @e confirm should return @e 0 if operation is declined,
 129  * other values mean accepted.
 130  *
 131  * @param cd crypt device handle
 132  * @param confirm user defined confirm callback reference
 133  * @param usrptr provided identification in callback
 134  * @param msg Message for user to confirm
 135  *
 136  * @note Current version of cryptsetup API requires confirmation for UUID change and
 137  *       LUKS header restore only.
 138  */
 139 void crypt_set_confirm_callback(struct crypt_device *cd,
 140         int (*confirm)(const char *msg, void *usrptr),
 141         void *usrptr);
 142
 143 /**
 144  * Set data device
 145  * For LUKS it is encrypted data device when LUKS header is separated.
 146  * For VERITY it is data device when hash device is separated.
 147  *
 148  * @param cd crypt device handle
 149  * @param device path to device
 150  *
 151  * @returns 0 on success or negative errno value otherwise.
 152  */
 153 int crypt_set_data_device(struct crypt_device *cd, const char *device);
 154
 155 /**
 156  * Set data device offset in 512-byte sectors.
 157  * Used for LUKS.
 158  * This function is replacement for data alignment fields in LUKS param struct.
 159  * If set to 0 (default), old behaviour is preserved.
 160  * This value is reset on @link crypt_load @endlink.
 161  *
 162  * @param cd crypt device handle
 163  * @param data_offset data offset in bytes
 164  *
 165  * @returns 0 on success or negative errno value otherwise.
 166  *
 167  * @note Data offset must be aligned to multiple of 8 (alignment to 4096-byte sectors)
 168  * and must be big enough to accommodate the whole LUKS header with all keyslots.
 169  * @note Data offset is enforced by this function, device topology
 170  * information is no longer used after calling this function.
 171  */
 172 int crypt_set_data_offset(struct crypt_device *cd, uint64_t data_offset);
 173
 174 /** @} */
 175
 176 /**
 177  * @defgroup crypt-log Cryptsetup logging
 178  * Set of functions and defines used in cryptsetup for
 179  * logging purposes
 180  * @addtogroup crypt-log
 181  * @{
 182  */
 183
 184 /** normal log level */
 185 #define CRYPT_LOG_NORMAL 0
 186 /** error log level */
 187 #define CRYPT_LOG_ERROR  1
 188 /** verbose log level */
 189 #define CRYPT_LOG_VERBOSE  2
 190 /** debug log level - always on stdout */
 191 #define CRYPT_LOG_DEBUG -1
 192 /** debug log level - additional JSON output (for LUKS2) */
 193 #define CRYPT_LOG_DEBUG_JSON -2
 194
 195 /**
 196  * Set log function.
 197  *
 198  * @param cd crypt device handle (can be @e NULL to set default log function)
 199  * @param log user defined log function reference
 200  * @param usrptr provided identification in callback
 201  * @param level log level below (debug messages can uses other levels)
 202  * @param msg log message
 203  */
 204 void crypt_set_log_callback(struct crypt_device *cd,
 205         void (*log)(int level, const char *msg, void *usrptr),
 206         void *usrptr);
 207
 208 /**
 209  * Defines log function or use the default one otherwise.
 210  *
 211  * @see crypt_set_log_callback
 212  *
 213  * @param cd crypt device handle
 214  * @param level log level
 215  * @param msg log message
 216  */
 217 void crypt_log(struct crypt_device *cd, int level, const char *msg);
 218 /** @} */
 219
 220 /**
 221  * @defgroup crypt-set Cryptsetup settings (RNG, PBKDF, locking)
 222  * @addtogroup crypt-set
 223  * @{
 224  */
 225
 226 /** CRYPT_RNG_URANDOM - use /dev/urandom */
 227 #define CRYPT_RNG_URANDOM 0
 228 /** CRYPT_RNG_RANDOM  - use /dev/random (waits if no entropy in system) */
 229 #define CRYPT_RNG_RANDOM  1
 230
 231 /**
 232  * Set which RNG (random number generator) is used for generating long term key
 233  *
 234  * @param cd crypt device handle
 235  * @param rng_type kernel random number generator to use
 236  *
 237  */
 238 void crypt_set_rng_type(struct crypt_device *cd, int rng_type);
 239
 240 /**
 241  * Get which RNG (random number generator) is used for generating long term key.
 242  *
 243  * @param cd crypt device handle
 244  * @return RNG type on success or negative errno value otherwise.
 245  *
 246  */
 247 int crypt_get_rng_type(struct crypt_device *cd);
 248
 249 /**
 250  * PBKDF parameters.
 251  */
 252 struct crypt_pbkdf_type {
 253         const char *type;         /**< PBKDF algorithm  */
 254         const char *hash;         /**< Hash algorithm */
 255         uint32_t time_ms;         /**< Requested time cost [milliseconds] */
 256         uint32_t iterations;      /**< Iterations, 0 or benchmarked value. */
 257         uint32_t max_memory_kb;   /**< Requested or benchmarked  memory cost [kilobytes] */
 258         uint32_t parallel_threads;/**< Requested parallel cost [threads] */
 259         uint32_t flags;           /**< CRYPT_PBKDF* flags */
 260 };
 261
 262 /** Iteration time set by crypt_set_iteration_time(), for compatibility only. */
 263 #define CRYPT_PBKDF_ITER_TIME_SET   (1 << 0)
 264 /** Never run benchmarks, use pre-set value or defaults. */
 265 #define CRYPT_PBKDF_NO_BENCHMARK    (1 << 1)
 266
 267 /** PBKDF2 according to RFC2898, LUKS1 legacy */
 268 #define CRYPT_KDF_PBKDF2   "pbkdf2"
 269 /** Argon2i according to RFC */
 270 #define CRYPT_KDF_ARGON2I  "argon2i"
 271 /** Argon2id according to RFC */
 272 #define CRYPT_KDF_ARGON2ID "argon2id"
 273
 274 /**
 275  * Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot
 276  * about to get created with any crypt_keyslot_add_*() call.
 277  *
 278  * @param cd crypt device handle
 279  * @param pbkdf PBKDF parameters
 280  *
 281  * @return 0 on success or negative errno value otherwise.
 282  *
 283  * @note For LUKS1, only PBKDF2 is supported, other settings will be rejected.
 284  * @note For non-LUKS context types the call succeeds, but PBKDF is not used.
 285  */
 286 int crypt_set_pbkdf_type(struct crypt_device *cd,
 287          const struct crypt_pbkdf_type *pbkdf);
 288
 289 /**
 290  * Get PBKDF (Password-Based Key Derivation Algorithm) parameters.
 291  *
 292  * @param pbkdf_type type of PBKDF
 293  *
 294  * @return struct on success or NULL value otherwise.
 295  *
 296  */
 297 const struct crypt_pbkdf_type *crypt_get_pbkdf_type_params(const char *pbkdf_type);
 298
 299 /**
 300  * Get default PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
 301  * Works only with LUKS device handles (both versions).
 302  *
 303  * @param type type of device (see @link crypt-type @endlink)
 304  *
 305  * @return struct on success or NULL value otherwise.
 306  *
 307  */
 308 const struct crypt_pbkdf_type *crypt_get_pbkdf_default(const char *type);
 309
 310 /**
 311  * Get current PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
 312  * Works only with LUKS device handles (both versions).
 313  *
 314  * @param cd crypt device handle
 315  *
 316  * @return struct on success or NULL value otherwise.
 317  *
 318  */
 319 const struct crypt_pbkdf_type *crypt_get_pbkdf_type(struct crypt_device *cd);
 320
 321 /**
 322  * Set how long should cryptsetup iterate in PBKDF2 function.
 323  * Default value heads towards the iterations which takes around 1 second.
 324  * \b Deprecated, only for backward compatibility.
 325  * Use @link crypt_set_pbkdf_type @endlink.
 326  *
 327  * @param cd crypt device handle
 328  * @param iteration_time_ms the time in ms
 329  *
 330  * @note If the time value is not acceptable for active PBKDF, value is quietly ignored.
 331  */
 332 void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);
 333
 334 /**
 335  * Helper to lock/unlock memory to avoid swap sensitive data to disk.
 336  *
 337  * @param cd crypt device handle, can be @e NULL
 338  * @param lock 0 to unlock otherwise lock memory
 339  *
 340  * @returns Value indicating whether the memory is locked (function can be called multiple times).
 341  *
 342  * @note Only root can do this.
 343  * @note It locks/unlocks all process memory, not only crypt context.
 344  */
 345 int crypt_memory_lock(struct crypt_device *cd, int lock);
 346
 347 /**
 348  * Set global lock protection for on-disk metadata (file-based locking).
 349  *
 350  * @param cd crypt device handle, can be @e NULL
 351  * @param enable 0 to disable locking otherwise enable it (default)
 352  *
 353  * @returns @e 0 on success or negative errno value otherwise.
 354  *
 355  * @note Locking applied only for some metadata formats (LUKS2).
 356  * @note The switch is global on the library level.
 357  *       In current version locking can be only switched off and cannot be switched on later.
 358  */
 359 int crypt_metadata_locking(struct crypt_device *cd, int enable);
 360
 361 /**
 362  * Set metadata header area sizes. This applies only to LUKS2.
 363  * These values limit amount of metadata anf number of supportable keyslots.
 364  *
 365  * @param cd crypt device handle, can be @e NULL
 366  * @param metadata_size size in bytes of JSON area + 4k binary header
 367  * @param keyslots_size size in bytes of binary keyslots area
 368  *
 369  * @returns @e 0 on success or negative errno value otherwise.
 370  *
 371  * @note The metadata area is stored twice and both copies contain 4k binary header.
 372  * Only 16,32,64,128,256,512,1024,2048 and 4096 kB value is allowed (see LUKS2 specification).
 373  * @note Keyslots area size must be multiple of 4k with maximum 128MB.
 374  */
 375 int crypt_set_metadata_size(struct crypt_device *cd,
 376         uint64_t metadata_size,
 377         uint64_t keyslots_size);
 378
 379 /**
 380  * Get metadata header area sizes. This applies only to LUKS2.
 381  * These values limit amount of metadata anf number of supportable keyslots.
 382  *
 383  * @param cd crypt device handle
 384  * @param metadata_size size in bytes of JSON area + 4k binary header
 385  * @param keyslots_size size in bytes of binary keyslots area
 386  *
 387  * @returns @e 0 on success or negative errno value otherwise.
 388  */
 389 int crypt_get_metadata_size(struct crypt_device *cd,
 390         uint64_t *metadata_size,
 391         uint64_t *keyslots_size);
 392
 393 /** @} */
 394
 395 /**
 396  * @defgroup crypt-type Cryptsetup on-disk format types
 397  * Set of functions, \#defines and structs related
 398  * to on-disk format types
 399  * @addtogroup crypt-type
 400  * @{
 401  */
 402
 403 /** plain crypt device, no on-disk header */
 404 #define CRYPT_PLAIN "PLAIN"
 405 /** LUKS version 1 header on-disk */
 406 #define CRYPT_LUKS1 "LUKS1"
 407 /** LUKS version 2 header on-disk */
 408 #define CRYPT_LUKS2 "LUKS2"
 409 /** loop-AES compatibility mode */
 410 #define CRYPT_LOOPAES "LOOPAES"
 411 /** dm-verity mode */
 412 #define CRYPT_VERITY "VERITY"
 413 /** TCRYPT (TrueCrypt-compatible and VeraCrypt-compatible) mode */
 414 #define CRYPT_TCRYPT "TCRYPT"
 415 /** INTEGRITY dm-integrity device */
 416 #define CRYPT_INTEGRITY "INTEGRITY"
 417 /** BITLK (BitLocker-compatible mode) */
 418 #define CRYPT_BITLK "BITLK"
 419
 420 /** LUKS any version */
 421 #define CRYPT_LUKS NULL
 422
 423 /**
 424  * Get device type
 425  *
 426  * @param cd crypt device handle
 427  * @return string according to device type or @e NULL if not known.
 428  */
 429 const char *crypt_get_type(struct crypt_device *cd);
 430
 431 /**
 432  * Get device default LUKS type
 433  *
 434  * @return string according to device type (CRYPT_LUKS1 or CRYPT_LUKS2).
 435  */
 436 const char *crypt_get_default_type(void);
 437
 438 /**
 439  *
 440  * Structure used as parameter for PLAIN device type.
 441  *
 442  * @see crypt_format
 443  */
 444 struct crypt_params_plain {
 445         const char *hash;     /**< password hash function */
 446         uint64_t offset;      /**< offset in sectors */
 447         uint64_t skip;        /**< IV offset / initialization sector */
 448         uint64_t size;        /**< size of mapped device or @e 0 for autodetection */
 449         uint32_t sector_size; /**< sector size in bytes (@e 0 means 512 for compatibility) */
 450 };
 451
 452 /**
 453  * Structure used as parameter for LUKS device type.
 454  *
 455  * @see crypt_format, crypt_load
 456  *
 457  * @note during crypt_format @e data_device attribute determines
 458  *       if the LUKS header is separated from encrypted payload device
 459  *
 460  */
 461 struct crypt_params_luks1 {
 462         const char *hash;        /**< hash used in LUKS header */
 463         size_t data_alignment;   /**< data area alignment in 512B sectors, data offset is multiple of this */
 464         const char *data_device; /**< detached encrypted data device or @e NULL */
 465 };
 466
 467 /**
 468  *
 469  * Structure used as parameter for loop-AES device type.
 470  *
 471  * @see crypt_format
 472  *
 473  */
 474 struct crypt_params_loopaes {
 475         const char *hash; /**< key hash function */
 476         uint64_t offset;  /**< offset in sectors */
 477         uint64_t skip;    /**< IV offset / initialization sector */
 478 };
 479
 480 /**
 481  *
 482  * Structure used as parameter for dm-verity device type.
 483  *
 484  * @see crypt_format, crypt_load
 485  *
 486  */
 487 struct crypt_params_verity {
 488         const char *hash_name;     /**< hash function */
 489         const char *data_device;   /**< data_device (CRYPT_VERITY_CREATE_HASH) */
 490         const char *hash_device;   /**< hash_device (output only) */
 491         const char *fec_device;    /**< fec_device (output only) */
 492         const char *salt;          /**< salt */
 493         uint32_t salt_size;        /**< salt size (in bytes) */
 494         uint32_t hash_type;        /**< in-kernel hashing type */
 495         uint32_t data_block_size;  /**< data block size (in bytes) */
 496         uint32_t hash_block_size;  /**< hash block size (in bytes) */
 497         uint64_t data_size;        /**< data area size (in data blocks) */
 498         uint64_t hash_area_offset; /**< hash/header offset (in bytes) */
 499         uint64_t fec_area_offset;  /**< FEC/header offset (in bytes) */
 500         uint32_t fec_roots;        /**< Reed-Solomon FEC roots */
 501         uint32_t flags;            /**< CRYPT_VERITY* flags */
 502 };
 503
 504 /** No on-disk header (only hashes) */
 505 #define CRYPT_VERITY_NO_HEADER   (1 << 0)
 506 /** Verity hash in userspace before activation */
 507 #define CRYPT_VERITY_CHECK_HASH  (1 << 1)
 508 /** Create hash - format hash device */
 509 #define CRYPT_VERITY_CREATE_HASH (1 << 2)
 510 /** Root hash signature required for activation */
 511 #define CRYPT_VERITY_ROOT_HASH_SIGNATURE (1 << 3)
 512
 513 /**
 514  *
 515  * Structure used as parameter for TCRYPT device type.
 516  *
 517  * @see crypt_load
 518  *
 519  */
 520 struct crypt_params_tcrypt {
 521         const char *passphrase;    /**< passphrase to unlock header (input only) */
 522         size_t passphrase_size;    /**< passphrase size (input only, max length is 64) */
 523         const char **keyfiles;     /**< keyfile paths to unlock header (input only) */
 524         unsigned int keyfiles_count;/**< keyfiles count (input only) */
 525         const char *hash_name;     /**< hash function for PBKDF */
 526         const char *cipher;        /**< cipher chain c1[-c2[-c3]] */
 527         const char *mode;          /**< cipher block mode */
 528         size_t key_size;           /**< key size in bytes (the whole chain) */
 529         uint32_t flags;            /**< CRYPT_TCRYPT* flags */
 530         uint32_t veracrypt_pim;    /**< VeraCrypt Personal Iteration Multiplier */
 531 };
 532
 533 /** Include legacy modes when scanning for header */
 534 #define CRYPT_TCRYPT_LEGACY_MODES    (1 << 0)
 535 /** Try to load hidden header (describing hidden device) */
 536 #define CRYPT_TCRYPT_HIDDEN_HEADER   (1 << 1)
 537 /** Try to load backup header */
 538 #define CRYPT_TCRYPT_BACKUP_HEADER   (1 << 2)
 539 /** Device contains encrypted system (with boot loader) */
 540 #define CRYPT_TCRYPT_SYSTEM_HEADER   (1 << 3)
 541 /** Include VeraCrypt modes when scanning for header,
 542  *  all other TCRYPT flags applies as well.
 543  *  VeraCrypt device is reported as TCRYPT type.
 544  */
 545 #define CRYPT_TCRYPT_VERA_MODES      (1 << 4)
 546
 547 /**
 548  *
 549  * Structure used as parameter for dm-integrity device type.
 550  *
 551  * @see crypt_format, crypt_load
 552  *
 553  * @note In bitmap tracking mode, the journal is implicitly disabled.
 554  *       As an ugly workaround for compatibility, journal_watermark is overloaded
 555  *       to mean 512-bytes sectors-per-bit and journal_commit_time means bitmap flush time.
 556  *       All other journal parameters are not applied in the bitmap mode.
 557  */
 558 struct crypt_params_integrity {
 559         uint64_t journal_size;               /**< size of journal in bytes */
 560         unsigned int journal_watermark;      /**< journal flush watermark in percents; in bitmap mode sectors-per-bit  */
 561         unsigned int journal_commit_time;    /**< journal commit time (or bitmap flush time) in ms */
 562         uint32_t interleave_sectors;         /**< number of interleave sectors (power of two) */
 563         uint32_t tag_size;                   /**< tag size per-sector in bytes */
 564         uint32_t sector_size;                /**< sector size in bytes */
 565         uint32_t buffer_sectors;             /**< number of sectors in one buffer */
 566         const char *integrity;               /**< integrity algorithm, NULL for LUKS2 */
 567         uint32_t integrity_key_size;         /**< integrity key size in bytes, info only, 0 for LUKS2 */
 568
 569         const char *journal_integrity;       /**< journal integrity algorithm */
 570         const char *journal_integrity_key;   /**< journal integrity key, only for crypt_load */
 571         uint32_t journal_integrity_key_size; /**< journal integrity key size in bytes, only for crypt_load */
 572
 573         const char *journal_crypt;           /**< journal encryption algorithm */
 574         const char *journal_crypt_key;       /**< journal crypt key, only for crypt_load */
 575         uint32_t journal_crypt_key_size;     /**< journal crypt key size in bytes, only for crypt_load */
 576 };
 577
 578 /**
 579  * Structure used as parameter for LUKS2 device type.
 580  *
 581  * @see crypt_format, crypt_load
 582  *
 583  * @note during crypt_format @e data_device attribute determines
 584  *       if the LUKS2 header is separated from encrypted payload device
 585  *
 586  */
 587 struct crypt_params_luks2 {
 588         const struct crypt_pbkdf_type *pbkdf; /**< PBKDF (and hash) parameters or @e NULL*/
 589         const char *integrity;                /**< integrity algorithm or @e NULL */
 590         const struct crypt_params_integrity *integrity_params; /**< Data integrity parameters or @e NULL*/
 591         size_t data_alignment;   /**< data area alignment in 512B sectors, data offset is multiple of this */
 592         const char *data_device; /**< detached encrypted data device or @e NULL */
 593         uint32_t sector_size;    /**< encryption sector size */
 594         const char *label;       /**< header label or @e NULL*/
 595         const char *subsystem;   /**< header subsystem label or @e NULL*/
 596 };
 597 /** @} */
 598
 599 /**
 600  * @defgroup crypt-actions Cryptsetup device context actions
 601  * Set of functions for formatting and manipulating with specific crypt_type
 602  * @addtogroup crypt-actions
 603  * @{
 604  */
 605
 606 /**
 607  * Create (format) new crypt device (and possible header on-disk) but do not activate it.
 608  *
 609  * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
 610  *
 611  * @param cd crypt device handle
 612  * @param type type of device (optional params struct must be of this type)
 613  * @param cipher (e.g. "aes")
 614  * @param cipher_mode including IV specification (e.g. "xts-plain")
 615  * @param uuid requested UUID or @e NULL if it should be generated
 616  * @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
 617  * @param volume_key_size size of volume key in bytes.
 618  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 619  *
 620  * @returns @e 0 on success or negative errno value otherwise.
 621  *
 622  * @note Note that crypt_format does not create LUKS keyslot (any version). To create keyslot
 623  *       call any crypt_keyslot_add_* function.
 624  * @note For VERITY @link crypt-type @endlink, only uuid parameter is used, other parameters
 625  *      are ignored and verity specific attributes are set through mandatory params option.
 626  */
 627 int crypt_format(struct crypt_device *cd,
 628         const char *type,
 629         const char *cipher,
 630         const char *cipher_mode,
 631         const char *uuid,
 632         const char *volume_key,
 633         size_t volume_key_size,
 634         void *params);
 635
 636 /**
 637  * Set format compatibility flags.
 638  *
 639  * @param cd crypt device handle
 640  * @param flags CRYPT_COMPATIBILITY_* flags
 641  */
 642 void crypt_set_compatibility(struct crypt_device *cd, uint32_t flags);
 643
 644 /**
 645  * Get compatibility flags.
 646  *
 647  * @param cd crypt device handle
 648  *
 649  * @returns compatibility flags
 650  */
 651 uint32_t crypt_get_compatibility(struct crypt_device *cd);
 652
 653 /** dm-integrity device uses less effective (legacy) padding (old kernels) */
 654 #define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING (1 << 0)
 655
 656 /**
 657  * Convert to new type for already existing device.
 658  *
 659  * @param cd crypt device handle
 660  * @param type type of device (optional params struct must be of this type)
 661  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 662  *
 663  * @returns 0 on success or negative errno value otherwise.
 664  *
 665  * @note Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported.
 666  *       Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion
 667  *       possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf
 668  *       type must be PBKDF2) and device cannot be formatted with any authenticated
 669  *       encryption mode.
 670  *
 671  * @note Device must be offline for conversion. UUID change is not possible for active
 672  *       devices.
 673  */
 674 int crypt_convert(struct crypt_device *cd,
 675         const char *type,
 676         void *params);
 677
 678 /**
 679  * Set new UUID for already existing device.
 680  *
 681  * @param cd crypt device handle
 682  * @param uuid requested UUID or @e NULL if it should be generated
 683  *
 684  * @returns 0 on success or negative errno value otherwise.
 685  *
 686  * @note Currently, only LUKS device type are supported
 687  */
 688 int crypt_set_uuid(struct crypt_device *cd,
 689         const char *uuid);
 690
 691 /**
 692  * Set new labels (label and subsystem) for already existing device.
 693  *
 694  * @param cd crypt device handle
 695  * @param label requested label or @e NULL
 696  * @param subsystem requested subsystem label or @e NULL
 697  *
 698  * @returns 0 on success or negative errno value otherwise.
 699  *
 700  * @note Currently, only LUKS2 device type is supported
 701  */
 702 int crypt_set_label(struct crypt_device *cd,
 703         const char *label,
 704         const char *subsystem);
 705
 706 /**
 707  * Enable or disable loading of volume keys via kernel keyring. When set to
 708  * 'enabled' library loads key in kernel keyring first and pass the key
 709  * description to dm-crypt instead of binary key copy. If set to 'disabled'
 710  * library fallbacks to old method of loading volume key directly in
 711  * dm-crypt target.
 712  *
 713  * @param cd crypt device handle, can be @e NULL
 714  * @param enable 0 to disable loading of volume keys via kernel keyring
 715  *        (classical method) otherwise enable it (default)
 716  *
 717  * @returns @e 0 on success or negative errno value otherwise.
 718  *
 719  * @note Currently loading of volume keys via kernel keyring is supported
 720  *       (and enabled by default) only for LUKS2 devices.
 721  * @note The switch is global on the library level.
 722  */
 723 int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
 724
 725 /**
 726  * Load crypt device parameters from on-disk header.
 727  *
 728  * @param cd crypt device handle
 729  * @param requested_type @link crypt-type @endlink or @e NULL for all known
 730  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 731  *
 732  * @returns 0 on success or negative errno value otherwise.
 733  *
 734  * @post In case LUKS header is read successfully but payload device is too small
 735  * error is returned and device type in context is set to @e NULL
 736  *
 737  * @note Note that in current version load works only for LUKS and VERITY device type.
 738  *
 739  */
 740 int crypt_load(struct crypt_device *cd,
 741         const char *requested_type,
 742         void *params);
 743
 744 /**
 745  * Try to repair crypt device LUKS on-disk header if invalid.
 746  *
 747  * @param cd crypt device handle
 748  * @param requested_type @link crypt-type @endlink or @e NULL for all known
 749  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 750  *
 751  * @returns 0 on success or negative errno value otherwise.
 752  *
 753  * @note For LUKS2 device crypt_repair bypass blkid checks and
 754  *       perform auto-recovery even though there're third party device
 755  *       signatures found by blkid probes. Currently the crypt_repair on LUKS2
 756  *       works only if exactly one header checksum does not match or exactly
 757  *       one header is missing.
 758  */
 759 int crypt_repair(struct crypt_device *cd,
 760         const char *requested_type,
 761         void *params);
 762
 763 /**
 764  * Resize crypt device.
 765  *
 766  * @param cd - crypt device handle
 767  * @param name - name of device to resize
 768  * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
 769  *
 770  * @return @e 0 on success or negative errno value otherwise.
 771  *
 772  * @note Most notably it returns -EPERM when device was activated with volume key
 773  *       in kernel keyring and current device handle (context) doesn't have verified key
 774  *       loaded in kernel. To load volume key for already active device use any of
 775  *       @link crypt_activate_by_passphrase @endlink, @link crypt_activate_by_keyfile @endlink,
 776  *       @link crypt_activate_by_keyfile_offset @endlink, @link crypt_activate_by_volume_key @endlink,
 777  *       @link crypt_activate_by_keyring @endlink or @link crypt_activate_by_token @endlink with flag
 778  *       @e CRYPT_ACTIVATE_KEYRING_KEY raised and @e name parameter set to @e NULL.
 779  */
 780 int crypt_resize(struct crypt_device *cd,
 781         const char *name,
 782         uint64_t new_size);
 783
 784 /**
 785  * Suspend crypt device.
 786  *
 787  * @param cd crypt device handle, can be @e NULL
 788  * @param name name of device to suspend
 789  *
 790  * @return 0 on success or negative errno value otherwise.
 791  *
 792  * @note Only LUKS device type is supported
 793  *
 794  */
 795 int crypt_suspend(struct crypt_device *cd,
 796         const char *name);
 797
 798 /**
 799  * Resume crypt device using passphrase.
 800  *
 801  *
 802  * @param cd crypt device handle
 803  * @param name name of device to resume
 804  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 805  * @param passphrase passphrase used to unlock volume key
 806  * @param passphrase_size size of @e passphrase (binary data)
 807  *
 808  * @return unlocked key slot number or negative errno otherwise.
 809  *
 810  * @note Only LUKS device type is supported
 811  */
 812 int crypt_resume_by_passphrase(struct crypt_device *cd,
 813         const char *name,
 814         int keyslot,
 815         const char *passphrase,
 816         size_t passphrase_size);
 817
 818 /**
 819  * Resume crypt device using key file.
 820  *
 821  * @param cd crypt device handle
 822  * @param name name of device to resume
 823  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 824  * @param keyfile key file used to unlock volume key
 825  * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
 826  * @param keyfile_offset number of bytes to skip at start of keyfile
 827  *
 828  * @return unlocked key slot number or negative errno otherwise.
 829  */
 830 int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
 831         const char *name,
 832         int keyslot,
 833         const char *keyfile,
 834         size_t keyfile_size,
 835         uint64_t keyfile_offset);
 836
 837 /**
 838  * Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
 839  */
 840 int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
 841         const char *name,
 842         int keyslot,
 843         const char *keyfile,
 844         size_t keyfile_size,
 845         size_t keyfile_offset);
 846
 847 /**
 848  * Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
 849  */
 850 int crypt_resume_by_keyfile(struct crypt_device *cd,
 851         const char *name,
 852         int keyslot,
 853         const char *keyfile,
 854         size_t keyfile_size);
 855 /**
 856  * Resume crypt device using provided volume key.
 857  *
 858  * @param cd crypt device handle
 859  * @param name name of device to resume
 860  * @param volume_key provided volume key
 861  * @param volume_key_size size of volume_key
 862  *
 863  * @return @e 0 on success or negative errno value otherwise.
 864  */
 865 int crypt_resume_by_volume_key(struct crypt_device *cd,
 866         const char *name,
 867         const char *volume_key,
 868         size_t volume_key_size);
 869 /** @} */
 870
 871 /**
 872  * @defgroup crypt-keyslot LUKS keyslots
 873  * @addtogroup crypt-keyslot
 874  * @{
 875  */
 876
 877 /** iterate through all keyslots and find first one that fits */
 878 #define CRYPT_ANY_SLOT -1
 879
 880 /**
 881  * Add key slot using provided passphrase.
 882  *
 883  * @pre @e cd contains initialized and formatted LUKS device context
 884  *
 885  * @param cd crypt device handle
 886  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 887  * @param passphrase passphrase used to unlock volume key
 888  * @param passphrase_size size of passphrase (binary data)
 889  * @param new_passphrase passphrase for new keyslot
 890  * @param new_passphrase_size size of @e new_passphrase (binary data)
 891  *
 892  * @return allocated key slot number or negative errno otherwise.
 893  */
 894 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
 895         int keyslot,
 896         const char *passphrase,
 897         size_t passphrase_size,
 898         const char *new_passphrase,
 899         size_t new_passphrase_size);
 900
 901 /**
 902  * Change defined key slot using provided passphrase.
 903  *
 904  * @pre @e cd contains initialized and formatted LUKS device context
 905  *
 906  * @param cd crypt device handle
 907  * @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
 908  * @param keyslot_new new keyslot (can be the same as old)
 909  * @param passphrase passphrase used to unlock volume key
 910  * @param passphrase_size size of passphrase (binary data)
 911  * @param new_passphrase passphrase for new keyslot
 912  * @param new_passphrase_size size of @e new_passphrase (binary data)
 913  *
 914  * @return allocated key slot number or negative errno otherwise.
 915  */
 916 int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
 917         int keyslot_old,
 918         int keyslot_new,
 919         const char *passphrase,
 920         size_t passphrase_size,
 921         const char *new_passphrase,
 922         size_t new_passphrase_size);
 923
 924 /**
 925 * Add key slot using provided key file path.
 926  *
 927  * @pre @e cd contains initialized and formatted LUKS device context
 928  *
 929  * @param cd crypt device handle
 930  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 931  * @param keyfile key file used to unlock volume key
 932  * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
 933  * @param keyfile_offset number of bytes to skip at start of keyfile
 934  * @param new_keyfile keyfile for new keyslot
 935  * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
 936  * @param new_keyfile_offset number of bytes to skip at start of new_keyfile
 937  *
 938  * @return allocated key slot number or negative errno otherwise.
 939  */
 940 int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
 941         int keyslot,
 942         const char *keyfile,
 943         size_t keyfile_size,
 944         uint64_t keyfile_offset,
 945         const char *new_keyfile,
 946         size_t new_keyfile_size,
 947         uint64_t new_keyfile_offset);
 948
 949 /**
 950  * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
 951  */
 952 int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
 953         int keyslot,
 954         const char *keyfile,
 955         size_t keyfile_size,
 956         size_t keyfile_offset,
 957         const char *new_keyfile,
 958         size_t new_keyfile_size,
 959         size_t new_keyfile_offset);
 960
 961 /**
 962  * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
 963  */
 964 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
 965         int keyslot,
 966         const char *keyfile,
 967         size_t keyfile_size,
 968         const char *new_keyfile,
 969         size_t new_keyfile_size);
 970
 971 /**
 972  * Add key slot using provided volume key.
 973  *
 974  * @pre @e cd contains initialized and formatted LUKS device context
 975  *
 976  * @param cd crypt device handle
 977  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 978  * @param volume_key provided volume key or @e NULL if used after crypt_format
 979  * @param volume_key_size size of volume_key
 980  * @param passphrase passphrase for new keyslot
 981  * @param passphrase_size size of passphrase
 982  *
 983  * @return allocated key slot number or negative errno otherwise.
 984  */
 985 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
 986         int keyslot,
 987         const char *volume_key,
 988         size_t volume_key_size,
 989         const char *passphrase,
 990         size_t passphrase_size);
 991
 992 /** create keyslot with volume key not associated with current dm-crypt segment */
 993 #define CRYPT_VOLUME_KEY_NO_SEGMENT (1 << 0)
 994
 995 /** create keyslot with new volume key and assign it to current dm-crypt segment */
 996 #define CRYPT_VOLUME_KEY_SET (1 << 1)
 997
 998 /** Assign key to first matching digest before creating new digest */
 999 #define CRYPT_VOLUME_KEY_DIGEST_REUSE (1 << 2)
1000
1001 /**
1002  * Add key slot using provided key.
1003  *
1004  * @pre @e cd contains initialized and formatted LUKS2 device context
1005  *
1006  * @param cd crypt device handle
1007  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
1008  * @param volume_key provided volume key or @e NULL (see note below)
1009  * @param volume_key_size size of volume_key
1010  * @param passphrase passphrase for new keyslot
1011  * @param passphrase_size size of passphrase
1012  * @param flags key flags to set
1013  *
1014  * @return allocated key slot number or negative errno otherwise.
1015  *
1016  * @note in case volume_key is @e NULL following first matching rule will apply:
1017  * @li if cd is device handle used in crypt_format() by current process, the volume
1018  *     key generated (or passed) in crypt_format() will be stored in keyslot.
1019  * @li if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be
1020  *     generated and stored in keyslot. The keyslot will become unbound (unusable to
1021  *     dm-crypt device activation).
1022  * @li fails with -EINVAL otherwise
1023  *
1024  * @warning CRYPT_VOLUME_KEY_SET flag force updates volume key. It is @b not @b reencryption!
1025  *          By doing so you will most probably destroy your ciphertext data device. It's supposed
1026  *          to be used only in wrapped keys scheme for key refresh process where real (inner) volume
1027  *          key stays untouched. It may be involed on active @e keyslot which makes the (previously
1028  *          unbound) keyslot new regular keyslot.
1029  */
1030 int crypt_keyslot_add_by_key(struct crypt_device *cd,
1031         int keyslot,
1032         const char *volume_key,
1033         size_t volume_key_size,
1034         const char *passphrase,
1035         size_t passphrase_size,
1036         uint32_t flags);
1037
1038 /**
1039  * Destroy (and disable) key slot.
1040  *
1041  * @pre @e cd contains initialized and formatted LUKS device context
1042  *
1043  * @param cd crypt device handle
1044  * @param keyslot requested key slot to destroy
1045  *
1046  * @return @e 0 on success or negative errno value otherwise.
1047  *
1048  * @note Note that there is no passphrase verification used.
1049  */
1050 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
1051 /** @} */
1052
1053 /**
1054  * @defgroup crypt-aflags Device runtime attributes
1055  * Activation flags
1056  * @addtogroup crypt-aflags
1057  * @{
1058  */
1059
1060 /** device is read only */
1061 #define CRYPT_ACTIVATE_READONLY (1 << 0)
1062 /** only reported for device without uuid */
1063 #define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
1064 /** activate even if cannot grant exclusive access (DANGEROUS) */
1065 #define CRYPT_ACTIVATE_SHARED   (1 << 2)
1066 /** enable discards aka TRIM */
1067 #define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
1068 /** skip global udev rules in activation ("private device"), input only */
1069 #define CRYPT_ACTIVATE_PRIVATE (1 << 4)
1070 /** corruption detected (verity), output only */
1071 #define CRYPT_ACTIVATE_CORRUPTED (1 << 5)
1072 /** use same_cpu_crypt option for dm-crypt */
1073 #define CRYPT_ACTIVATE_SAME_CPU_CRYPT (1 << 6)
1074 /** use submit_from_crypt_cpus for dm-crypt */
1075 #define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (1 << 7)
1076 /** dm-verity: ignore_corruption flag - ignore corruption, log it only */
1077 #define CRYPT_ACTIVATE_IGNORE_CORRUPTION (1 << 8)
1078 /** dm-verity: restart_on_corruption flag - restart kernel on corruption */
1079 #define CRYPT_ACTIVATE_RESTART_ON_CORRUPTION (1 << 9)
1080 /** dm-verity: ignore_zero_blocks - do not verify zero blocks */
1081 #define CRYPT_ACTIVATE_IGNORE_ZERO_BLOCKS (1 << 10)
1082 /** key loaded in kernel keyring instead directly in dm-crypt */
1083 #define CRYPT_ACTIVATE_KEYRING_KEY (1 << 11)
1084 /** dm-integrity: direct writes, do not use journal */
1085 #define CRYPT_ACTIVATE_NO_JOURNAL (1 << 12)
1086 /** dm-integrity: recovery mode - no journal, no integrity checks */
1087 #define CRYPT_ACTIVATE_RECOVERY (1 << 13)
1088 /** ignore persistently stored flags */
1089 #define CRYPT_ACTIVATE_IGNORE_PERSISTENT (1 << 14)
1090 /** dm-verity: check_at_most_once - check data blocks only the first time */
1091 #define CRYPT_ACTIVATE_CHECK_AT_MOST_ONCE (1 << 15)
1092 /** allow activation check including unbound keyslots (keyslots without segments) */
1093 #define CRYPT_ACTIVATE_ALLOW_UNBOUND_KEY (1 << 16)
1094 /** dm-integrity: activate automatic recalculation */
1095 #define CRYPT_ACTIVATE_RECALCULATE (1 << 17)
1096 /** reactivate existing and update flags, input only */
1097 #define CRYPT_ACTIVATE_REFRESH  (1 << 18)
1098 /** Use global lock to serialize memory hard KDF on activation (OOM workaround) */
1099 #define CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF (1 << 19)
1100 /** dm-integrity: direct writes, use bitmap to track dirty sectors */
1101 #define CRYPT_ACTIVATE_NO_JOURNAL_BITMAP (1 << 20)
1102 /** device is suspended (key should be wiped from memory), output only */
1103 #define CRYPT_ACTIVATE_SUSPENDED (1 << 21)
1104 /** use IV sector counted in sector_size instead of default 512 bytes sectors */
1105 #define CRYPT_ACTIVATE_IV_LARGE_SECTORS (1 << 22)
1106
1107 /**
1108  * Active device runtime attributes
1109  */
1110 struct crypt_active_device {
1111         uint64_t offset;    /**< offset in sectors */
1112         uint64_t iv_offset; /**< IV initialization sector */
1113         uint64_t size;      /**< active device size */
1114         uint32_t flags;     /**< activation flags */
1115 };
1116
1117 /**
1118  * Receive runtime attributes of active crypt device.
1119  *
1120  * @param cd crypt device handle (can be @e NULL)
1121  * @param name name of active device
1122  * @param cad preallocated active device attributes to fill
1123  *
1124  * @return @e 0 on success or negative errno value otherwise
1125  *
1126  */
1127 int crypt_get_active_device(struct crypt_device *cd,
1128         const char *name,
1129         struct crypt_active_device *cad);
1130
1131 /**
1132  * Get detected number of integrity failures.
1133  *
1134  * @param cd crypt device handle (can be @e NULL)
1135  * @param name name of active device
1136  *
1137  * @return number of integrity failures or @e 0 otherwise
1138  *
1139  */
1140 uint64_t crypt_get_active_integrity_failures(struct crypt_device *cd,
1141         const char *name);
1142 /** @} */
1143
1144 /**
1145  * @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
1146  * @addtogroup crypt-pflags
1147  * @{
1148  */
1149
1150 /**
1151  * LUKS2 header requirements
1152  */
1153 /** Unfinished offline reencryption */
1154 #define CRYPT_REQUIREMENT_OFFLINE_REENCRYPT     (1 << 0)
1155 /** Online reencryption in-progress */
1156 #define CRYPT_REQUIREMENT_ONLINE_REENCRYPT      (1 << 1)
1157 /** unknown requirement in header (output only) */
1158 #define CRYPT_REQUIREMENT_UNKNOWN               (1 << 31)
1159
1160 /**
1161  * Persistent flags type
1162  */
1163 typedef enum {
1164         CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
1165         CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
1166 } crypt_flags_type;
1167
1168 /**
1169  * Set persistent flags.
1170  *
1171  * @param cd crypt device handle (can be @e NULL)
1172  * @param type type to set (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1173  * @param flags flags to set
1174  *
1175  * @return @e 0 on success or negative errno value otherwise
1176  *
1177  * @note Valid only for LUKS2.
1178  *
1179  * @note Not all activation flags can be stored. Only ALLOW_DISCARD,
1180  *       SAME_CPU_CRYPT, SUBMIT_FROM_CRYPT_CPU and NO_JOURNAL can be
1181  *       stored persistently.
1182  *
1183  * @note Only requirements flags recognised by current library may be set.
1184  *       CRYPT_REQUIREMENT_UNKNOWN is illegal (output only) in set operation.
1185  */
1186 int crypt_persistent_flags_set(struct crypt_device *cd,
1187         crypt_flags_type type,
1188         uint32_t flags);
1189
1190 /**
1191  * Get persistent flags stored in header.
1192  *
1193  * @param cd crypt device handle (can be @e NULL)
1194  * @param type flags type to retrieve (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1195  * @param flags reference to output variable
1196  *
1197  * @return @e 0 on success or negative errno value otherwise
1198  */
1199 int crypt_persistent_flags_get(struct crypt_device *cd,
1200         crypt_flags_type type,
1201         uint32_t *flags);
1202 /** @} */
1203
1204 /**
1205  * @defgroup crypt-activation Device activation
1206  * @addtogroup crypt-activation
1207  * @{
1208  */
1209
1210 /**
1211  * Activate device or check passphrase.
1212  *
1213  * @param cd crypt device handle
1214  * @param name name of device to create, if @e NULL only check passphrase
1215  * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
1216  * @param passphrase passphrase used to unlock volume key
1217  * @param passphrase_size size of @e passphrase
1218  * @param flags activation flags
1219  *
1220  * @return unlocked key slot number or negative errno otherwise.
1221  */
1222 int crypt_activate_by_passphrase(struct crypt_device *cd,
1223         const char *name,
1224         int keyslot,
1225         const char *passphrase,
1226         size_t passphrase_size,
1227         uint32_t flags);
1228
1229 /**
1230  * Activate device or check using key file.
1231  *
1232  * @param cd crypt device handle
1233  * @param name name of device to create, if @e NULL only check keyfile
1234  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1235  * @param keyfile key file used to unlock volume key
1236  * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
1237  * @param keyfile_offset number of bytes to skip at start of keyfile
1238  * @param flags activation flags
1239  *
1240  * @return unlocked key slot number or negative errno otherwise.
1241  */
1242 int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
1243         const char *name,
1244         int keyslot,
1245         const char *keyfile,
1246         size_t keyfile_size,
1247         uint64_t keyfile_offset,
1248         uint32_t flags);
1249
1250 /**
1251  * Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
1252  */
1253 int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
1254         const char *name,
1255         int keyslot,
1256         const char *keyfile,
1257         size_t keyfile_size,
1258         size_t keyfile_offset,
1259         uint32_t flags);
1260
1261 /**
1262  * Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
1263  */
1264 int crypt_activate_by_keyfile(struct crypt_device *cd,
1265         const char *name,
1266         int keyslot,
1267         const char *keyfile,
1268         size_t keyfile_size,
1269         uint32_t flags);
1270
1271 /**
1272  * Activate device using provided volume key.
1273  *
1274  * @param cd crypt device handle
1275  * @param name name of device to create, if @e NULL only check volume key
1276  * @param volume_key provided volume key (or @e NULL to use internal)
1277  * @param volume_key_size size of volume_key
1278  * @param flags activation flags
1279  *
1280  * @return @e 0 on success or negative errno value otherwise.
1281  *
1282  * @note If @e NULL is used for volume_key, device has to be initialized
1283  *       by previous operation (like @ref crypt_format
1284  *       or @ref crypt_init_by_name)
1285  * @note For VERITY the volume key means root hash required for activation.
1286  *       Because kernel dm-verity is always read only, you have to provide
1287  *       CRYPT_ACTIVATE_READONLY flag always.
1288  * @note For TCRYPT the volume key should be always NULL and because master
1289  *       key from decrypted header is used instead.
1290  */
1291 int crypt_activate_by_volume_key(struct crypt_device *cd,
1292         const char *name,
1293         const char *volume_key,
1294         size_t volume_key_size,
1295         uint32_t flags);
1296
1297 /**
1298  * Activate VERITY device using provided key and optional signature).
1299  *
1300  * @param cd crypt device handle
1301  * @param name name of device to create
1302  * @param volume_key provided volume key
1303  * @param volume_key_size size of volume_key
1304  * @param signature buffer with signature for the key
1305  * @param signature_size bsize of signature buffer
1306  * @param flags activation flags
1307  *
1308  * @return @e 0 on success or negative errno value otherwise.
1309  *
1310  * @note For VERITY the volume key means root hash required for activation.
1311  *      Because kernel dm-verity is always read only, you have to provide
1312  *      CRYPT_ACTIVATE_READONLY flag always.
1313  */
1314 int crypt_activate_by_signed_key(struct crypt_device *cd,
1315         const char *name,
1316         const char *volume_key,
1317         size_t volume_key_size,
1318         const char *signature,
1319         size_t signature_size,
1320         uint32_t flags);
1321
1322 /**
1323  * Activate device using passphrase stored in kernel keyring.
1324  *
1325  * @param cd crypt device handle
1326  * @param name name of device to create, if @e NULL only check passphrase in keyring
1327  * @param key_description kernel keyring key description library should look
1328  *        for passphrase in
1329  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1330  * @param flags activation flags
1331  *
1332  * @return @e unlocked keyslot number on success or negative errno value otherwise.
1333  *
1334  * @note Keyslot passphrase must be stored in 'user' key type
1335  *       and the key has to be reachable for process context
1336  *       on behalf of which this function is called.
1337  */
1338 int crypt_activate_by_keyring(struct crypt_device *cd,
1339         const char *name,
1340         const char *key_description,
1341         int keyslot,
1342         uint32_t flags);
1343
1344 /** lazy deactivation - remove once last user releases it */
1345 #define CRYPT_DEACTIVATE_DEFERRED (1 << 0)
1346 /** force deactivation - if the device is busy, it is replaced by error device */
1347 #define CRYPT_DEACTIVATE_FORCE    (1 << 1)
1348
1349 /**
1350  * Deactivate crypt device. This function tries to remove active device-mapper
1351  * mapping from kernel. Also, sensitive data like the volume key are removed from
1352  * memory
1353  *
1354  * @param cd crypt device handle, can be @e NULL
1355  * @param name name of device to deactivate
1356  * @param flags deactivation flags
1357  *
1358  * @return @e 0 on success or negative errno value otherwise.
1359  *
1360  */
1361 int crypt_deactivate_by_name(struct crypt_device *cd,
1362         const char *name,
1363         uint32_t flags);
1364
1365 /**
1366  * Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
1367  */
1368 int crypt_deactivate(struct crypt_device *cd, const char *name);
1369 /** @} */
1370
1371 /**
1372  * @defgroup crypt-key Volume Key manipulation
1373  * @addtogroup crypt-key
1374  * @{
1375  */
1376
1377 /**
1378  * Get volume key from crypt device.
1379  *
1380  * @param cd crypt device handle
1381  * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
1382  * @param volume_key buffer for volume key
1383  * @param volume_key_size on input, size of buffer @e volume_key,
1384  *        on output size of @e volume_key
1385  * @param passphrase passphrase used to unlock volume key
1386  * @param passphrase_size size of @e passphrase
1387  *
1388  * @return unlocked key slot number or negative errno otherwise.
1389  *
1390  * @note For TCRYPT cipher chain is the volume key concatenated
1391  *       for all ciphers in chain.
1392  * @note For VERITY the volume key means root hash used for activation.
1393  */
1394 int crypt_volume_key_get(struct crypt_device *cd,
1395         int keyslot,
1396         char *volume_key,
1397         size_t *volume_key_size,
1398         const char *passphrase,
1399         size_t passphrase_size);
1400
1401 /**
1402  * Verify that provided volume key is valid for crypt device.
1403  *
1404  * @param cd crypt device handle
1405  * @param volume_key provided volume key
1406  * @param volume_key_size size of @e volume_key
1407  *
1408  * @return @e 0 on success or negative errno value otherwise.
1409  */
1410 int crypt_volume_key_verify(struct crypt_device *cd,
1411         const char *volume_key,
1412         size_t volume_key_size);
1413 /** @} */
1414
1415 /**
1416  * @defgroup crypt-devstat Crypt and Verity device status
1417  * @addtogroup crypt-devstat
1418  * @{
1419  */
1420
1421 /**
1422  * Device status
1423  */
1424 typedef enum {
1425         CRYPT_INVALID,  /**< device mapping is invalid in this context */
1426         CRYPT_INACTIVE, /**< no such mapped device */
1427         CRYPT_ACTIVE,   /**< device is active */
1428         CRYPT_BUSY      /**< device is active and has open count > 0 */
1429 } crypt_status_info;
1430
1431 /**
1432  * Get status info about device name.
1433  *
1434  * @param cd crypt device handle, can be @e NULL
1435  * @param name crypt device name
1436  *
1437  * @return value defined by crypt_status_info.
1438  *
1439  */
1440 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
1441
1442 /**
1443  * Dump text-formatted information about crypt or verity device to log output.
1444  *
1445  * @param cd crypt device handle
1446  *
1447  * @return @e 0 on success or negative errno value otherwise.
1448  */
1449 int crypt_dump(struct crypt_device *cd);
1450
1451 /**
1452  * Get cipher used in device.
1453  *
1454  * @param cd crypt device handle
1455  *
1456  * @return used cipher, e.g. "aes" or @e NULL otherwise
1457  *
1458  */
1459 const char *crypt_get_cipher(struct crypt_device *cd);
1460
1461 /**
1462  * Get cipher mode used in device.
1463  *
1464  * @param cd crypt device handle
1465  *
1466  * @return used cipher mode e.g. "xts-plain" or @e otherwise
1467  *
1468  */
1469 const char *crypt_get_cipher_mode(struct crypt_device *cd);
1470
1471 /**
1472  * Get device UUID.
1473  *
1474  * @param cd crypt device handle
1475  *
1476  * @return device UUID or @e NULL if not set
1477  *
1478  */
1479 const char *crypt_get_uuid(struct crypt_device *cd);
1480
1481 /**
1482  * Get path to underlaying device.
1483  *
1484  * @param cd crypt device handle
1485  *
1486  * @return path to underlaying device name
1487  *
1488  */
1489 const char *crypt_get_device_name(struct crypt_device *cd);
1490
1491 /**
1492  * Get path to detached metadata device or @e NULL if it is not detached.
1493  *
1494  * @param cd crypt device handle
1495  *
1496  * @return path to underlaying device name
1497  *
1498  */
1499 const char *crypt_get_metadata_device_name(struct crypt_device *cd);
1500
1501 /**
1502  * Get device offset in 512-bytes sectors where real data starts (on underlying device).
1503  *
1504  * @param cd crypt device handle
1505  *
1506  * @return device offset in sectors
1507  *
1508  */
1509 uint64_t crypt_get_data_offset(struct crypt_device *cd);
1510
1511 /**
1512  * Get IV offset in 512-bytes sectors (skip).
1513  *
1514  * @param cd crypt device handle
1515  *
1516  * @return IV offset
1517  *
1518  */
1519 uint64_t crypt_get_iv_offset(struct crypt_device *cd);
1520
1521 /**
1522  * Get size (in bytes) of volume key for crypt device.
1523  *
1524  * @param cd crypt device handle
1525  *
1526  * @return volume key size
1527  *
1528  * @note For LUKS2, this function can be used only if there is at least
1529  *       one keyslot assigned to data segment.
1530  */
1531 int crypt_get_volume_key_size(struct crypt_device *cd);
1532
1533 /**
1534  * Get size (in bytes) of encryption sector for crypt device.
1535  *
1536  * @param cd crypt device handle
1537  *
1538  * @return sector size
1539  *
1540  */
1541 int crypt_get_sector_size(struct crypt_device *cd);
1542
1543 /**
1544  * Get device parameters for VERITY device.
1545  *
1546  * @param cd crypt device handle
1547  * @param vp verity device info
1548  *
1549  * @e 0 on success or negative errno value otherwise.
1550  *
1551  */
1552 int crypt_get_verity_info(struct crypt_device *cd,
1553         struct crypt_params_verity *vp);
1554
1555 /**
1556  * Get device parameters for INTEGRITY device.
1557  *
1558  * @param cd crypt device handle
1559  * @param ip verity device info
1560  *
1561  * @e 0 on success or negative errno value otherwise.
1562  *
1563  */
1564 int crypt_get_integrity_info(struct crypt_device *cd,
1565         struct crypt_params_integrity *ip);
1566 /** @} */
1567
1568 /**
1569  * @defgroup crypt-benchmark Benchmarking
1570  * Benchmarking of algorithms
1571  * @addtogroup crypt-benchmark
1572  * @{
1573  */
1574
1575 /**
1576  * Informational benchmark for ciphers.
1577  *
1578  * @param cd crypt device handle
1579  * @param cipher (e.g. "aes")
1580  * @param cipher_mode (e.g. "xts"), IV generator is ignored
1581  * @param volume_key_size size of volume key in bytes
1582  * @param iv_size size of IV in bytes
1583  * @param buffer_size size of encryption buffer in bytes used in test
1584  * @param encryption_mbs measured encryption speed in MiB/s
1585  * @param decryption_mbs measured decryption speed in MiB/s
1586  *
1587  * @return @e 0 on success or negative errno value otherwise.
1588  *
1589  * @note If encryption_buffer_size is too small and encryption time
1590  *       cannot be properly measured, -ERANGE is returned.
1591  */
1592 int crypt_benchmark(struct crypt_device *cd,
1593         const char *cipher,
1594         const char *cipher_mode,
1595         size_t volume_key_size,
1596         size_t iv_size,
1597         size_t buffer_size,
1598         double *encryption_mbs,
1599         double *decryption_mbs);
1600
1601 /**
1602  * Informational benchmark for PBKDF.
1603  *
1604  * @param cd crypt device handle
1605  * @param pbkdf PBKDF parameters
1606  * @param password password for benchmark
1607  * @param password_size size of password
1608  * @param salt salt for benchmark
1609  * @param salt_size size of salt
1610  * @param volume_key_size output volume key size
1611  * @param progress callback function
1612  * @param usrptr provided identification in callback
1613  *
1614  * @return @e 0 on success or negative errno value otherwise.
1615  */
1616 int crypt_benchmark_pbkdf(struct crypt_device *cd,
1617         struct crypt_pbkdf_type *pbkdf,
1618         const char *password,
1619         size_t password_size,
1620         const char *salt,
1621         size_t salt_size,
1622         size_t volume_key_size,
1623         int (*progress)(uint32_t time_ms, void *usrptr),
1624         void *usrptr);
1625 /** @} */
1626
1627 /**
1628  * @addtogroup crypt-keyslot
1629  * @{
1630  */
1631
1632 /**
1633  * Crypt keyslot info
1634  */
1635 typedef enum {
1636         CRYPT_SLOT_INVALID,    /**< invalid keyslot */
1637         CRYPT_SLOT_INACTIVE,   /**< keyslot is inactive (free) */
1638         CRYPT_SLOT_ACTIVE,     /**< keyslot is active (used) */
1639         CRYPT_SLOT_ACTIVE_LAST,/**< keylost is active (used)
1640                                  *  and last used at the same time */
1641         CRYPT_SLOT_UNBOUND     /**< keyslot is active and not bound
1642                                  *  to any crypt segment (LUKS2 only) */
1643 } crypt_keyslot_info;
1644
1645 /**
1646  * Get information about particular key slot.
1647  *
1648  * @param cd crypt device handle
1649  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1650  *
1651  * @return value defined by crypt_keyslot_info
1652  *
1653  */
1654 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
1655
1656 /**
1657  * Crypt keyslot priority
1658  */
1659 typedef enum {
1660         CRYPT_SLOT_PRIORITY_INVALID =-1, /**< no such slot */
1661         CRYPT_SLOT_PRIORITY_IGNORE  = 0, /**< CRYPT_ANY_SLOT will ignore it for open */
1662         CRYPT_SLOT_PRIORITY_NORMAL  = 1, /**< default priority, tried after preferred */
1663         CRYPT_SLOT_PRIORITY_PREFER  = 2, /**< will try to open first */
1664 } crypt_keyslot_priority;
1665
1666 /**
1667  * Get keyslot priority (LUKS2)
1668  *
1669  * @param cd crypt device handle
1670  * @param keyslot keyslot number
1671  *
1672  * @return value defined by crypt_keyslot_priority
1673  */
1674 crypt_keyslot_priority crypt_keyslot_get_priority(struct crypt_device *cd, int keyslot);
1675
1676 /**
1677  * Set keyslot priority (LUKS2)
1678  *
1679  * @param cd crypt device handle
1680  * @param keyslot keyslot number
1681  * @param priority priority defined in crypt_keyslot_priority
1682  *
1683  * @return @e 0 on success or negative errno value otherwise.
1684  */
1685 int crypt_keyslot_set_priority(struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority);
1686
1687 /**
1688  * Get number of keyslots supported for device type.
1689  *
1690  * @param type crypt device type
1691  *
1692  * @return slot count or negative errno otherwise if device
1693  * doesn't not support keyslots.
1694  */
1695 int crypt_keyslot_max(const char *type);
1696
1697 /**
1698  * Get keyslot area pointers (relative to metadata device).
1699  *
1700  * @param cd crypt device handle
1701  * @param keyslot keyslot number
1702  * @param offset offset on metadata device (in bytes)
1703  * @param length length of keyslot area (in bytes)
1704  *
1705  * @return @e 0 on success or negative errno value otherwise.
1706  *
1707  */
1708 int crypt_keyslot_area(struct crypt_device *cd,
1709         int keyslot,
1710         uint64_t *offset,
1711         uint64_t *length);
1712
1713 /**
1714  * Get size (in bytes) of stored key in particular keyslot.
1715  * Use for LUKS2 unbound keyslots, for other keyslots it is the same as @ref crypt_get_volume_key_size
1716  *
1717  * @param cd crypt device handle
1718  * @param keyslot keyslot number
1719  *
1720  * @return volume key size or negative errno value otherwise.
1721  *
1722  */
1723 int crypt_keyslot_get_key_size(struct crypt_device *cd, int keyslot);
1724
1725 /**
1726  * Get cipher and key size for keyslot encryption.
1727  * Use for LUKS2 keyslot to set different encryption type than for data encryption.
1728  * Parameters will be used for next keyslot operations.
1729  *
1730  * @param cd crypt device handle
1731  * @param keyslot keyslot number of CRYPT_ANY_SLOT for default
1732  * @param key_size encryption key size (in bytes)
1733  *
1734  * @return cipher specification on success or @e NULL.
1735  *
1736  * @note This is the encryption of keyslot itself, not the data encryption algorithm!
1737  */
1738 const char *crypt_keyslot_get_encryption(struct crypt_device *cd, int keyslot, size_t *key_size);
1739
1740 /**
1741  * Get PBKDF parameters for keyslot.
1742  *
1743  * @param cd crypt device handle
1744  * @param keyslot keyslot number
1745  * @param pbkdf struct with returned PBKDF parameters
1746  *
1747  * @return @e 0 on success or negative errno value otherwise.
1748  */
1749 int crypt_keyslot_get_pbkdf(struct crypt_device *cd, int keyslot, struct crypt_pbkdf_type *pbkdf);
1750
1751 /**
1752  * Set encryption for keyslot.
1753  * Use for LUKS2 keyslot to set different encryption type than for data encryption.
1754  * Parameters will be used for next keyslot operations that create or change a keyslot.
1755  *
1756  * @param cd crypt device handle
1757  * @param cipher (e.g. "aes-xts-plain64")
1758  * @param key_size encryption key size (in bytes)
1759  *
1760  * @return @e 0 on success or negative errno value otherwise.
1761  *
1762  * @note To reset to default keyslot encryption (the same as for data)
1763  *       set cipher to NULL and key size to 0.
1764  */
1765 int crypt_keyslot_set_encryption(struct crypt_device *cd,
1766         const char *cipher,
1767         size_t key_size);
1768
1769 /**
1770  * Get directory where mapped crypt devices are created
1771  *
1772  * @return the directory path
1773  */
1774 const char *crypt_get_dir(void);
1775
1776 /** @} */
1777
1778 /**
1779  * @defgroup crypt-backup Device metadata backup
1780  * @addtogroup crypt-backup
1781  * @{
1782  */
1783 /**
1784  * Backup header and keyslots to file.
1785  *
1786  * @param cd crypt device handle
1787  * @param requested_type @link crypt-type @endlink or @e NULL for all known
1788  * @param backup_file file to backup header to
1789  *
1790  * @return @e 0 on success or negative errno value otherwise.
1791  *
1792  */
1793 int crypt_header_backup(struct crypt_device *cd,
1794         const char *requested_type,
1795         const char *backup_file);
1796
1797 /**
1798  * Restore header and keyslots from backup file.
1799  *
1800  * @param cd crypt device handle
1801  * @param requested_type @link crypt-type @endlink or @e NULL for all known
1802  * @param backup_file file to restore header from
1803  *
1804  * @return @e 0 on success or negative errno value otherwise.
1805  *
1806  */
1807 int crypt_header_restore(struct crypt_device *cd,
1808         const char *requested_type,
1809         const char *backup_file);
1810 /** @} */
1811
1812 /**
1813  * @defgroup crypt-dbg Library debug level
1814  * Set library debug level
1815  * @addtogroup crypt-dbg
1816  * @{
1817  */
1818
1819 /** Debug all */
1820 #define CRYPT_DEBUG_ALL  -1
1821 /** Debug all with additional JSON dump (for LUKS2) */
1822 #define CRYPT_DEBUG_JSON  -2
1823 /** Debug none */
1824 #define CRYPT_DEBUG_NONE  0
1825
1826 /**
1827  * Set the debug level for library
1828  *
1829  * @param level debug level
1830  *
1831  */
1832 void crypt_set_debug_level(int level);
1833 /** @} */
1834
1835 /**
1836  * @defgroup crypt-keyfile Function to read keyfile
1837  * @addtogroup crypt-keyfile
1838  * @{
1839  */
1840
1841 /**
1842  * Read keyfile
1843  *
1844  * @param cd crypt device handle
1845  * @param keyfile keyfile to read
1846  * @param key buffer for key
1847  * @param key_size_read size of read key
1848  * @param keyfile_offset key offset in keyfile
1849  * @param key_size exact key length to read from file or 0
1850  * @param flags keyfile read flags
1851  *
1852  * @return @e 0 on success or negative errno value otherwise.
1853  *
1854  * @note If key_size is set to zero we read internal max length
1855  *       and actual size read is returned via key_size_read parameter.
1856  */
1857 int crypt_keyfile_device_read(struct crypt_device *cd,
1858         const char *keyfile,
1859         char **key, size_t *key_size_read,
1860         uint64_t keyfile_offset,
1861         size_t key_size,
1862         uint32_t flags);
1863
1864 /**
1865  * Backward compatible crypt_keyfile_device_read() (with size_t offset).
1866  */
1867 int crypt_keyfile_read(struct crypt_device *cd,
1868         const char *keyfile,
1869         char **key, size_t *key_size_read,
1870         size_t keyfile_offset,
1871         size_t key_size,
1872         uint32_t flags);
1873
1874 /** Read key only to the first end of line (\\n). */
1875 #define CRYPT_KEYFILE_STOP_EOL   (1 << 0)
1876 /** @} */
1877
1878 /**
1879  * @defgroup crypt-wipe Function to wipe device
1880  * @addtogroup crypt-wipe
1881  * @{
1882  */
1883 /**
1884  * Wipe pattern
1885  */
1886 typedef enum {
1887         CRYPT_WIPE_ZERO,           /**< Fill with zeroes */
1888         CRYPT_WIPE_RANDOM,         /**< Use RNG to fill data */
1889         CRYPT_WIPE_ENCRYPTED_ZERO, /**< Add encryption and fill with zeroes as plaintext */
1890         CRYPT_WIPE_SPECIAL,        /**< Compatibility only, do not use (Gutmann method) */
1891 } crypt_wipe_pattern;
1892
1893 /**
1894  * Wipe/Fill (part of) a device with the selected pattern.
1895  *
1896  * @param cd crypt device handle
1897  * @param dev_path path to device to wipe or @e NULL if data device should be used
1898  * @param pattern selected wipe pattern
1899  * @param offset offset on device (in bytes)
1900  * @param length length of area to be wiped (in bytes)
1901  * @param wipe_block_size used block for wiping (one step) (in bytes)
1902  * @param flags wipe flags
1903  * @param progress callback function called after each @e wipe_block_size or @e NULL
1904  * @param usrptr provided identification in callback
1905  *
1906  * @return @e 0 on success or negative errno value otherwise.
1907  *
1908  * @note A @e progress callback can interrupt wipe process by returning non-zero code.
1909  *
1910  * @note If the error values is -EIO or -EINTR, some part of the device could
1911  *       be overwritten. Other error codes (-EINVAL, -ENOMEM) means that no IO was performed.
1912  */
1913 int crypt_wipe(struct crypt_device *cd,
1914         const char *dev_path, /* if null, use data device */
1915         crypt_wipe_pattern pattern,
1916         uint64_t offset,
1917         uint64_t length,
1918         size_t wipe_block_size,
1919         uint32_t flags,
1920         int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
1921         void *usrptr
1922 );
1923
1924 /** Use direct-io */
1925 #define CRYPT_WIPE_NO_DIRECT_IO (1 << 0)
1926 /** @} */
1927
1928 /**
1929  * @defgroup crypt-tokens LUKS2 token wrapper access
1930  *
1931  * Utilities for handling tokens LUKS2
1932  * Token is a device or a method how to read password for particular keyslot
1933  * automatically. It can be chunk of data stored on hardware token or
1934  * just a metadata how to generate the password.
1935  *
1936  * @addtogroup crypt-tokens
1937  * @{
1938  */
1939
1940 /** Iterate through all tokens */
1941 #define CRYPT_ANY_TOKEN -1
1942
1943 /**
1944  * Get content of a token definition in JSON format.
1945  *
1946  * @param cd crypt device handle
1947  * @param token token id
1948  * @param json buffer with JSON
1949  *
1950  * @return allocated token id or negative errno otherwise.
1951  */
1952 int crypt_token_json_get(struct crypt_device *cd,
1953         int token,
1954         const char **json);
1955
1956 /**
1957  * Store content of a token definition in JSON format.
1958  *
1959  * @param cd crypt device handle
1960  * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
1961  * @param json buffer with JSON or @e NULL to remove token
1962  *
1963  * @return allocated token id or negative errno otherwise.
1964  *
1965  * @note The buffer must be in proper JSON format and must contain at least
1966  *       string "type" with slot type and an array of string names "keyslots".
1967  *       Keyslots array contains assignments to particular slots and can be empty.
1968  */
1969 int crypt_token_json_set(struct crypt_device *cd,
1970         int token,
1971         const char *json);
1972
1973 /**
1974  * Token info
1975  */
1976 typedef enum {
1977         CRYPT_TOKEN_INVALID,          /**< token is invalid */
1978         CRYPT_TOKEN_INACTIVE,         /**< token is empty (free) */
1979         CRYPT_TOKEN_INTERNAL,         /**< active internal token with driver */
1980         CRYPT_TOKEN_INTERNAL_UNKNOWN, /**< active internal token (reserved name) with missing token driver */
1981         CRYPT_TOKEN_EXTERNAL,         /**< active external (user defined) token with driver */
1982         CRYPT_TOKEN_EXTERNAL_UNKNOWN, /**< active external (user defined) token with missing token driver */
1983 } crypt_token_info;
1984
1985 /**
1986  * Get info for specific token.
1987  *
1988  * @param cd crypt device handle
1989  * @param token existing token id
1990  * @param type pointer for returned type string
1991  *
1992  * @return token status info. For any returned status (besides CRYPT_TOKEN_INVALID
1993  *         and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will
1994  *         contain address of type string.
1995  *
1996  * @note if required, create a copy of string referenced in *type before calling next
1997  *       libcryptsetup API function. The reference may become invalid.
1998  */
1999 crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
2000
2001 /**
2002  * LUKS2 keyring token parameters.
2003  *
2004  * @see crypt_token_builtin_set
2005  *
2006  */
2007 struct crypt_token_params_luks2_keyring {
2008         const char *key_description; /**< Reference in keyring */
2009 };
2010
2011 /**
2012  * Create a new luks2 keyring token.
2013  *
2014  * @param cd crypt device handle
2015  * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
2016  * @param params luks2 keyring token params
2017  *
2018  * @return allocated token id or negative errno otherwise.
2019  *
2020  */
2021 int crypt_token_luks2_keyring_set(struct crypt_device *cd,
2022         int token,
2023         const struct crypt_token_params_luks2_keyring *params);
2024
2025 /**
2026  * Get LUKS2 keyring token params
2027  *
2028  * @param cd crypt device handle
2029  * @param token existing luks2 keyring token id
2030  * @param params returned luks2 keyring token params
2031  *
2032  * @return allocated token id or negative errno otherwise.
2033  *
2034  * @note do not call free() on params members. Members are valid only
2035  *       until next libcryptsetup function is called.
2036  */
2037 int crypt_token_luks2_keyring_get(struct crypt_device *cd,
2038         int token,
2039         struct crypt_token_params_luks2_keyring *params);
2040
2041 /**
2042  * Assign a token to particular keyslot.
2043  * (There can be more keyslots assigned to one token id.)
2044  *
2045  * @param cd crypt device handle
2046  * @param token token id
2047  * @param keyslot keyslot to be assigned to token (CRYPT_ANY SLOT
2048  *        assigns all active keyslots to token)
2049  *
2050  * @return allocated token id or negative errno otherwise.
2051  */
2052 int crypt_token_assign_keyslot(struct crypt_device *cd,
2053         int token,
2054         int keyslot);
2055
2056 /**
2057  * Unassign a token from particular keyslot.
2058  * (There can be more keyslots assigned to one token id.)
2059  *
2060  * @param cd crypt device handle
2061  * @param token token id
2062  * @param keyslot keyslot to be unassigned from token (CRYPT_ANY SLOT
2063  *        unassigns all active keyslots from token)
2064  *
2065  * @return allocated token id or negative errno otherwise.
2066  */
2067 int crypt_token_unassign_keyslot(struct crypt_device *cd,
2068         int token,
2069         int keyslot);
2070
2071 /**
2072  * Get info about token assignment to particular keyslot.
2073  *
2074  * @param cd crypt device handle
2075  * @param token token id
2076  * @param keyslot keyslot
2077  *
2078  * @return 0 on success (token exists and is assigned to the keyslot),
2079  *         -ENOENT if token is not assigned to a keyslot (token, keyslot
2080  *         or both may be inactive) or other negative errno otherwise.
2081  */
2082 int crypt_token_is_assigned(struct crypt_device *cd,
2083         int token,
2084         int keyslot);
2085
2086 /**
2087  * Token handler open function prototype.
2088  * This function retrieves password from a token and return allocated buffer
2089  * containing this password. This buffer has to be deallocated by calling
2090  * free() function and content should be wiped before deallocation.
2091  *
2092  * @param cd crypt device handle
2093  * @param token token id
2094  * @param buffer returned allocated buffer with password
2095  * @param buffer_len length of the buffer
2096  * @param usrptr user data in @link crypt_activate_by_token @endlink
2097  */
2098 typedef int (*crypt_token_open_func) (
2099         struct crypt_device *cd,
2100         int token,
2101         char **buffer,
2102         size_t *buffer_len,
2103         void *usrptr);
2104
2105 /**
2106  * Token handler buffer free function prototype.
2107  * This function is used by library to free the buffer with keyslot
2108  * passphrase when it's no longer needed. If not defined the library
2109  * overwrites buffer with zeroes and call free().
2110  *
2111  * @param buffer the buffer with keyslot passphrase
2112  * @param buffer_len the buffer length
2113  */
2114 typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
2115
2116 /**
2117  * Token handler validate function prototype.
2118  * This function validates JSON representation of user defined token for additional data
2119  * specific for its token type. If defined in the handler, it's called
2120  * during @link crypt_activate_by_token @endlink. It may also be called during
2121  * @link crypt_token_json_set @endlink when appropriate token handler was registered before
2122  * with @link crypt_token_register @endlink.
2123  *
2124  * @param cd crypt device handle
2125  * @param json buffer with JSON
2126  */
2127 typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
2128
2129 /**
2130  * Token handler dump function prototype.
2131  * This function is supposed to print token implementation specific details. It gets
2132  * called during @link crypt_dump @endlink if token handler was registered before.
2133  *
2134  * @param cd crypt device handle
2135  * @param json buffer with token JSON
2136  *
2137  * @note dump implementations are advised to use @link crypt_log @endlink function
2138  *       to dump token details.
2139  */
2140 typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
2141
2142 /**
2143  * Token handler
2144  */
2145 typedef struct  {
2146         const char *name;           /**< token handler name */
2147         crypt_token_open_func open; /**< token handler open function */
2148         crypt_token_buffer_free_func buffer_free; /**< token handler buffer_free function (optional) */
2149         crypt_token_validate_func validate; /**< token handler validate function (optional) */
2150         crypt_token_dump_func dump; /**< token handler dump function (optional) */
2151 } crypt_token_handler;
2152
2153 /**
2154  * Register token handler
2155  *
2156  * @param handler token handler to register
2157  *
2158  * @return @e 0 on success or negative errno value otherwise.
2159  */
2160 int crypt_token_register(const crypt_token_handler *handler);
2161
2162 /**
2163  * Activate device or check key using a token.
2164  *
2165  * @param cd crypt device handle
2166  * @param name name of device to create, if @e NULL only check token
2167  * @param token requested token to check or CRYPT_ANY_TOKEN to check all
2168  * @param usrptr provided identification in callback
2169  * @param flags activation flags
2170  *
2171  * @return unlocked key slot number or negative errno otherwise.
2172  */
2173 int crypt_activate_by_token(struct crypt_device *cd,
2174         const char *name,
2175         int token,
2176         void *usrptr,
2177         uint32_t flags);
2178 /** @} */
2179
2180 /**
2181  * @defgroup crypt-reencryption LUKS2 volume reencryption support
2182  *
2183  * Set of functions to handling LUKS2 volume reencryption
2184  *
2185  * @addtogroup crypt-reencryption
2186  * @{
2187  */
2188
2189 /** Initialize reencryption metadata but do not run reencryption yet. (in) */
2190 #define CRYPT_REENCRYPT_INITIALIZE_ONLY    (1 << 0)
2191 /** Move the first segment, used only with data shift. (in/out) */
2192 #define CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT (1 << 1)
2193 /** Resume already initialized reencryption only. (in) */
2194 #define CRYPT_REENCRYPT_RESUME_ONLY        (1 << 2)
2195 /** Run reencryption recovery only. (in) */
2196 #define CRYPT_REENCRYPT_RECOVERY           (1 << 3)
2197
2198 /**
2199  * Reencryption direction
2200  */
2201 typedef enum {
2202         CRYPT_REENCRYPT_FORWARD = 0, /**< forward direction */
2203         CRYPT_REENCRYPT_BACKWARD     /**< backward direction */
2204 } crypt_reencrypt_direction_info;
2205
2206 /**
2207  * Reencryption mode
2208  */
2209 typedef enum {
2210         CRYPT_REENCRYPT_REENCRYPT = 0, /**< Reencryption mode */
2211         CRYPT_REENCRYPT_ENCRYPT,       /**< Encryption mode */
2212         CRYPT_REENCRYPT_DECRYPT,       /**< Decryption mode */
2213 } crypt_reencrypt_mode_info;
2214
2215 /**
2216  * LUKS2 reencryption options.
2217  */
2218 struct crypt_params_reencrypt {
2219         crypt_reencrypt_mode_info mode;           /**< Reencryption mode, immutable after first init. */
2220         crypt_reencrypt_direction_info direction; /**< Reencryption direction, immutable after first init. */
2221         const char *resilience;                   /**< Resilience mode: "none", "checksum", "journal" or "shift" (only "shift" is immutable after init) */
2222         const char *hash;                         /**< Used hash for "checksum" resilience type, ignored otherwise. */
2223         uint64_t data_shift;                      /**< Used in "shift" mode, must be non-zero, immutable after first init. */
2224         uint64_t max_hotzone_size;                /**< Exact hotzone size for "none" mode. Maximum hotzone size for "checksum" and "journal" modes. */
2225         uint64_t device_size;                     /**< Reencrypt only initial part of the data device. */
2226         const struct crypt_params_luks2 *luks2;   /**< LUKS2 parameters for the final reencryption volume.*/
2227         uint32_t flags;                           /**< Reencryption flags. */
2228 };
2229
2230 /**
2231  * Initialize reencryption metadata using passphrase.
2232  *
2233  * This function initializes on-disk metadata to include all reencryption segments,
2234  * according to the provided options.
2235  * If metadata already contains ongoing reencryption metadata, it loads these parameters
2236  * (in this situation all parameters except @e name and @e passphrase can be omitted).
2237  *
2238  * @param cd crypt device handle
2239  * @param name name of active device or @e NULL for offline reencryption
2240  * @param passphrase passphrase used to unlock volume key
2241  * @param passphrase_size size of @e passphrase (binary data)
2242  * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2243  * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2244  * @param cipher cipher specification (e.g. "aes")
2245  * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2246  * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2247  *
2248  * @return reencryption key slot number or negative errno otherwise.
2249  */
2250 int crypt_reencrypt_init_by_passphrase(struct crypt_device *cd,
2251         const char *name,
2252         const char *passphrase,
2253         size_t passphrase_size,
2254         int keyslot_old,
2255         int keyslot_new,
2256         const char *cipher,
2257         const char *cipher_mode,
2258         const struct crypt_params_reencrypt *params);
2259
2260 /**
2261  * Initialize reencryption metadata using passphrase in keyring.
2262  *
2263  * This function initializes on-disk metadata to include all reencryption segments,
2264  * according to the provided options.
2265  * If metadata already contains ongoing reencryption metadata, it loads these parameters
2266  * (in this situation all parameters except @e name and @e key_description can be omitted).
2267  *
2268  * @param cd crypt device handle
2269  * @param name name of active device or @e NULL for offline reencryption
2270  * @param key_description passphrase (key) identification in keyring
2271  * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2272  * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2273  * @param cipher cipher specification (e.g. "aes")
2274  * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2275  * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2276  *
2277  * @return reencryption key slot number or negative errno otherwise.
2278  */
2279 int crypt_reencrypt_init_by_keyring(struct crypt_device *cd,
2280         const char *name,
2281         const char *key_description,
2282         int keyslot_old,
2283         int keyslot_new,
2284         const char *cipher,
2285         const char *cipher_mode,
2286         const struct crypt_params_reencrypt *params);
2287
2288 /**
2289  * Run data reencryption.
2290  *
2291  * @param cd crypt device handle
2292  * @param progress is a callback funtion reporting device \b size,
2293  * current \b offset of reencryption and provided \b usrptr identification
2294  *
2295  * @return @e 0 on success or negative errno value otherwise.
2296  */
2297 int crypt_reencrypt(struct crypt_device *cd,
2298                     int (*progress)(uint64_t size, uint64_t offset, void *usrptr));
2299
2300 /**
2301  * Reencryption status info
2302  */
2303 typedef enum {
2304         CRYPT_REENCRYPT_NONE = 0, /**< No reencryption in progress */
2305         CRYPT_REENCRYPT_CLEAN,    /**< Ongoing reencryption in a clean state. */
2306         CRYPT_REENCRYPT_CRASH,    /**< Aborted reencryption that need internal recovery. */
2307         CRYPT_REENCRYPT_INVALID   /**< Invalid state. */
2308 } crypt_reencrypt_info;
2309
2310 /**
2311  * LUKS2 reencryption status.
2312  *
2313  * @param cd crypt device handle
2314  * @param params reencryption parameters
2315  *
2316  * @return reencryption status info and parameters.
2317  */
2318 crypt_reencrypt_info crypt_reencrypt_status(struct crypt_device *cd,
2319                 struct crypt_params_reencrypt *params);
2320 /** @} */
2321
2322 /**
2323  * @defgroup crypt-memory Safe memory helpers functions
2324  * @addtogroup crypt-memory
2325  * @{
2326  */
2327
2328 /**
2329  * Allocate safe memory (content is safely wiped on deallocation).
2330  *
2331  * @param size size of memory in bytes
2332  *
2333  * @return pointer to allocate memory or @e NULL.
2334  */
2335 void *crypt_safe_alloc(size_t size);
2336
2337 /**
2338  * Release safe memory, content is safely wiped
2339  * The pointer must be allocated with @link crypt_safe_alloc @endlink
2340  *
2341  * @param data pointer to memory to be deallocated
2342  *
2343  * @return pointer to allocate memory or @e NULL.
2344  */
2345 void crypt_safe_free(void *data);
2346
2347 /**
2348  * Reallocate safe memory (content is copied and safely wiped on deallocation).
2349  *
2350  * @param data pointer to memory to be deallocated
2351  * @param size new size of memory in bytes
2352  *
2353  * @return pointer to allocate memory or @e NULL.
2354  */
2355 void *crypt_safe_realloc(void *data, size_t size);
2356
2357 /**
2358  * Safe clear memory area (compile should not compile this call out).
2359  *
2360  * @param data pointer to memory to cleared
2361  * @param size new size of memory in bytes
2362  *
2363  * @return pointer to allocate memory or @e NULL.
2364  */
2365 void crypt_safe_memzero(void *data, size_t size);
2366
2367 /** @} */
2368
2369 #ifdef __cplusplus
2370 }
2371 #endif
2372 #endif /* _LIBCRYPTSETUP_H */