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-2021 Red Hat, Inc. All rights reserved.
   7  * Copyright (C) 2009-2021 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 /** dm-integrity device does not protect superblock with HMAC (old kernels) */
 656 #define CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC (1 << 1)
 657 /** dm-integrity allow recalculating of volumes with HMAC keys (old kernels) */
 658 #define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (1 << 2)
 659
 660 /**
 661  * Convert to new type for already existing device.
 662  *
 663  * @param cd crypt device handle
 664  * @param type type of device (optional params struct must be of this type)
 665  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 666  *
 667  * @returns 0 on success or negative errno value otherwise.
 668  *
 669  * @note Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported.
 670  *       Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion
 671  *       possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf
 672  *       type must be PBKDF2) and device cannot be formatted with any authenticated
 673  *       encryption mode.
 674  *
 675  * @note Device must be offline for conversion. UUID change is not possible for active
 676  *       devices.
 677  */
 678 int crypt_convert(struct crypt_device *cd,
 679         const char *type,
 680         void *params);
 681
 682 /**
 683  * Set new UUID for already existing device.
 684  *
 685  * @param cd crypt device handle
 686  * @param uuid requested UUID or @e NULL if it should be generated
 687  *
 688  * @returns 0 on success or negative errno value otherwise.
 689  *
 690  * @note Currently, only LUKS device type are supported
 691  */
 692 int crypt_set_uuid(struct crypt_device *cd,
 693         const char *uuid);
 694
 695 /**
 696  * Set new labels (label and subsystem) for already existing device.
 697  *
 698  * @param cd crypt device handle
 699  * @param label requested label or @e NULL
 700  * @param subsystem requested subsystem label or @e NULL
 701  *
 702  * @returns 0 on success or negative errno value otherwise.
 703  *
 704  * @note Currently, only LUKS2 device type is supported
 705  */
 706 int crypt_set_label(struct crypt_device *cd,
 707         const char *label,
 708         const char *subsystem);
 709
 710 /**
 711  * Enable or disable loading of volume keys via kernel keyring. When set to
 712  * 'enabled' library loads key in kernel keyring first and pass the key
 713  * description to dm-crypt instead of binary key copy. If set to 'disabled'
 714  * library fallbacks to old method of loading volume key directly in
 715  * dm-crypt target.
 716  *
 717  * @param cd crypt device handle, can be @e NULL
 718  * @param enable 0 to disable loading of volume keys via kernel keyring
 719  *        (classical method) otherwise enable it (default)
 720  *
 721  * @returns @e 0 on success or negative errno value otherwise.
 722  *
 723  * @note Currently loading of volume keys via kernel keyring is supported
 724  *       (and enabled by default) only for LUKS2 devices.
 725  * @note The switch is global on the library level.
 726  */
 727 int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
 728
 729 /**
 730  * Load crypt device parameters from on-disk header.
 731  *
 732  * @param cd crypt device handle
 733  * @param requested_type @link crypt-type @endlink or @e NULL for all known
 734  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 735  *
 736  * @returns 0 on success or negative errno value otherwise.
 737  *
 738  * @post In case LUKS header is read successfully but payload device is too small
 739  * error is returned and device type in context is set to @e NULL
 740  *
 741  * @note Note that in current version load works only for LUKS and VERITY device type.
 742  *
 743  */
 744 int crypt_load(struct crypt_device *cd,
 745         const char *requested_type,
 746         void *params);
 747
 748 /**
 749  * Try to repair crypt device LUKS on-disk header if invalid.
 750  *
 751  * @param cd crypt device handle
 752  * @param requested_type @link crypt-type @endlink or @e NULL for all known
 753  * @param params crypt type specific parameters (see @link crypt-type @endlink)
 754  *
 755  * @returns 0 on success or negative errno value otherwise.
 756  *
 757  * @note For LUKS2 device crypt_repair bypass blkid checks and
 758  *       perform auto-recovery even though there're third party device
 759  *       signatures found by blkid probes. Currently the crypt_repair on LUKS2
 760  *       works only if exactly one header checksum does not match or exactly
 761  *       one header is missing.
 762  */
 763 int crypt_repair(struct crypt_device *cd,
 764         const char *requested_type,
 765         void *params);
 766
 767 /**
 768  * Resize crypt device.
 769  *
 770  * @param cd - crypt device handle
 771  * @param name - name of device to resize
 772  * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
 773  *
 774  * @return @e 0 on success or negative errno value otherwise.
 775  *
 776  * @note Most notably it returns -EPERM when device was activated with volume key
 777  *       in kernel keyring and current device handle (context) doesn't have verified key
 778  *       loaded in kernel. To load volume key for already active device use any of
 779  *       @link crypt_activate_by_passphrase @endlink, @link crypt_activate_by_keyfile @endlink,
 780  *       @link crypt_activate_by_keyfile_offset @endlink, @link crypt_activate_by_volume_key @endlink,
 781  *       @link crypt_activate_by_keyring @endlink or @link crypt_activate_by_token @endlink with flag
 782  *       @e CRYPT_ACTIVATE_KEYRING_KEY raised and @e name parameter set to @e NULL.
 783  */
 784 int crypt_resize(struct crypt_device *cd,
 785         const char *name,
 786         uint64_t new_size);
 787
 788 /**
 789  * Suspend crypt device.
 790  *
 791  * @param cd crypt device handle, can be @e NULL
 792  * @param name name of device to suspend
 793  *
 794  * @return 0 on success or negative errno value otherwise.
 795  *
 796  * @note Only LUKS device type is supported
 797  *
 798  */
 799 int crypt_suspend(struct crypt_device *cd,
 800         const char *name);
 801
 802 /**
 803  * Resume crypt device using passphrase.
 804  *
 805  *
 806  * @param cd crypt device handle
 807  * @param name name of device to resume
 808  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 809  * @param passphrase passphrase used to unlock volume key
 810  * @param passphrase_size size of @e passphrase (binary data)
 811  *
 812  * @return unlocked key slot number or negative errno otherwise.
 813  *
 814  * @note Only LUKS device type is supported
 815  */
 816 int crypt_resume_by_passphrase(struct crypt_device *cd,
 817         const char *name,
 818         int keyslot,
 819         const char *passphrase,
 820         size_t passphrase_size);
 821
 822 /**
 823  * Resume crypt device using key file.
 824  *
 825  * @param cd crypt device handle
 826  * @param name name of device to resume
 827  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 828  * @param keyfile key file used to unlock volume key
 829  * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
 830  * @param keyfile_offset number of bytes to skip at start of keyfile
 831  *
 832  * @return unlocked key slot number or negative errno otherwise.
 833  */
 834 int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
 835         const char *name,
 836         int keyslot,
 837         const char *keyfile,
 838         size_t keyfile_size,
 839         uint64_t keyfile_offset);
 840
 841 /**
 842  * Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
 843  */
 844 int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
 845         const char *name,
 846         int keyslot,
 847         const char *keyfile,
 848         size_t keyfile_size,
 849         size_t keyfile_offset);
 850
 851 /**
 852  * Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
 853  */
 854 int crypt_resume_by_keyfile(struct crypt_device *cd,
 855         const char *name,
 856         int keyslot,
 857         const char *keyfile,
 858         size_t keyfile_size);
 859 /**
 860  * Resume crypt device using provided volume key.
 861  *
 862  * @param cd crypt device handle
 863  * @param name name of device to resume
 864  * @param volume_key provided volume key
 865  * @param volume_key_size size of volume_key
 866  *
 867  * @return @e 0 on success or negative errno value otherwise.
 868  */
 869 int crypt_resume_by_volume_key(struct crypt_device *cd,
 870         const char *name,
 871         const char *volume_key,
 872         size_t volume_key_size);
 873 /** @} */
 874
 875 /**
 876  * @defgroup crypt-keyslot LUKS keyslots
 877  * @addtogroup crypt-keyslot
 878  * @{
 879  */
 880
 881 /** iterate through all keyslots and find first one that fits */
 882 #define CRYPT_ANY_SLOT -1
 883
 884 /**
 885  * Add key slot using provided passphrase.
 886  *
 887  * @pre @e cd contains initialized and formatted LUKS device context
 888  *
 889  * @param cd crypt device handle
 890  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 891  * @param passphrase passphrase used to unlock volume key
 892  * @param passphrase_size size of passphrase (binary data)
 893  * @param new_passphrase passphrase for new keyslot
 894  * @param new_passphrase_size size of @e new_passphrase (binary data)
 895  *
 896  * @return allocated key slot number or negative errno otherwise.
 897  */
 898 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
 899         int keyslot,
 900         const char *passphrase,
 901         size_t passphrase_size,
 902         const char *new_passphrase,
 903         size_t new_passphrase_size);
 904
 905 /**
 906  * Change defined key slot using provided passphrase.
 907  *
 908  * @pre @e cd contains initialized and formatted LUKS device context
 909  *
 910  * @param cd crypt device handle
 911  * @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
 912  * @param keyslot_new new keyslot (can be the same as old)
 913  * @param passphrase passphrase used to unlock volume key
 914  * @param passphrase_size size of passphrase (binary data)
 915  * @param new_passphrase passphrase for new keyslot
 916  * @param new_passphrase_size size of @e new_passphrase (binary data)
 917  *
 918  * @return allocated key slot number or negative errno otherwise.
 919  */
 920 int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
 921         int keyslot_old,
 922         int keyslot_new,
 923         const char *passphrase,
 924         size_t passphrase_size,
 925         const char *new_passphrase,
 926         size_t new_passphrase_size);
 927
 928 /**
 929 * Add key slot using provided key file path.
 930  *
 931  * @pre @e cd contains initialized and formatted LUKS device context
 932  *
 933  * @param cd crypt device handle
 934  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 935  * @param keyfile key file used to unlock volume key
 936  * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
 937  * @param keyfile_offset number of bytes to skip at start of keyfile
 938  * @param new_keyfile keyfile for new keyslot
 939  * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
 940  * @param new_keyfile_offset number of bytes to skip at start of new_keyfile
 941  *
 942  * @return allocated key slot number or negative errno otherwise.
 943  */
 944 int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
 945         int keyslot,
 946         const char *keyfile,
 947         size_t keyfile_size,
 948         uint64_t keyfile_offset,
 949         const char *new_keyfile,
 950         size_t new_keyfile_size,
 951         uint64_t new_keyfile_offset);
 952
 953 /**
 954  * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
 955  */
 956 int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
 957         int keyslot,
 958         const char *keyfile,
 959         size_t keyfile_size,
 960         size_t keyfile_offset,
 961         const char *new_keyfile,
 962         size_t new_keyfile_size,
 963         size_t new_keyfile_offset);
 964
 965 /**
 966  * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
 967  */
 968 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
 969         int keyslot,
 970         const char *keyfile,
 971         size_t keyfile_size,
 972         const char *new_keyfile,
 973         size_t new_keyfile_size);
 974
 975 /**
 976  * Add key slot using provided volume key.
 977  *
 978  * @pre @e cd contains initialized and formatted LUKS device context
 979  *
 980  * @param cd crypt device handle
 981  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 982  * @param volume_key provided volume key or @e NULL if used after crypt_format
 983  * @param volume_key_size size of volume_key
 984  * @param passphrase passphrase for new keyslot
 985  * @param passphrase_size size of passphrase
 986  *
 987  * @return allocated key slot number or negative errno otherwise.
 988  */
 989 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
 990         int keyslot,
 991         const char *volume_key,
 992         size_t volume_key_size,
 993         const char *passphrase,
 994         size_t passphrase_size);
 995
 996 /** create keyslot with volume key not associated with current dm-crypt segment */
 997 #define CRYPT_VOLUME_KEY_NO_SEGMENT (1 << 0)
 998
 999 /** create keyslot with new volume key and assign it to current dm-crypt segment */
1000 #define CRYPT_VOLUME_KEY_SET (1 << 1)
1001
1002 /** Assign key to first matching digest before creating new digest */
1003 #define CRYPT_VOLUME_KEY_DIGEST_REUSE (1 << 2)
1004
1005 /**
1006  * Add key slot using provided key.
1007  *
1008  * @pre @e cd contains initialized and formatted LUKS2 device context
1009  *
1010  * @param cd crypt device handle
1011  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
1012  * @param volume_key provided volume key or @e NULL (see note below)
1013  * @param volume_key_size size of volume_key
1014  * @param passphrase passphrase for new keyslot
1015  * @param passphrase_size size of passphrase
1016  * @param flags key flags to set
1017  *
1018  * @return allocated key slot number or negative errno otherwise.
1019  *
1020  * @note in case volume_key is @e NULL following first matching rule will apply:
1021  * @li if cd is device handle used in crypt_format() by current process, the volume
1022  *     key generated (or passed) in crypt_format() will be stored in keyslot.
1023  * @li if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be
1024  *     generated and stored in keyslot. The keyslot will become unbound (unusable to
1025  *     dm-crypt device activation).
1026  * @li fails with -EINVAL otherwise
1027  *
1028  * @warning CRYPT_VOLUME_KEY_SET flag force updates volume key. It is @b not @b reencryption!
1029  *          By doing so you will most probably destroy your ciphertext data device. It's supposed
1030  *          to be used only in wrapped keys scheme for key refresh process where real (inner) volume
1031  *          key stays untouched. It may be involed on active @e keyslot which makes the (previously
1032  *          unbound) keyslot new regular keyslot.
1033  */
1034 int crypt_keyslot_add_by_key(struct crypt_device *cd,
1035         int keyslot,
1036         const char *volume_key,
1037         size_t volume_key_size,
1038         const char *passphrase,
1039         size_t passphrase_size,
1040         uint32_t flags);
1041
1042 /**
1043  * Destroy (and disable) key slot.
1044  *
1045  * @pre @e cd contains initialized and formatted LUKS device context
1046  *
1047  * @param cd crypt device handle
1048  * @param keyslot requested key slot to destroy
1049  *
1050  * @return @e 0 on success or negative errno value otherwise.
1051  *
1052  * @note Note that there is no passphrase verification used.
1053  */
1054 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
1055 /** @} */
1056
1057 /**
1058  * @defgroup crypt-aflags Device runtime attributes
1059  * Activation flags
1060  * @addtogroup crypt-aflags
1061  * @{
1062  */
1063
1064 /** device is read only */
1065 #define CRYPT_ACTIVATE_READONLY (1 << 0)
1066 /** only reported for device without uuid */
1067 #define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
1068 /** activate even if cannot grant exclusive access (DANGEROUS) */
1069 #define CRYPT_ACTIVATE_SHARED   (1 << 2)
1070 /** enable discards aka TRIM */
1071 #define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
1072 /** skip global udev rules in activation ("private device"), input only */
1073 #define CRYPT_ACTIVATE_PRIVATE (1 << 4)
1074 /** corruption detected (verity), output only */
1075 #define CRYPT_ACTIVATE_CORRUPTED (1 << 5)
1076 /** use same_cpu_crypt option for dm-crypt */
1077 #define CRYPT_ACTIVATE_SAME_CPU_CRYPT (1 << 6)
1078 /** use submit_from_crypt_cpus for dm-crypt */
1079 #define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (1 << 7)
1080 /** dm-verity: ignore_corruption flag - ignore corruption, log it only */
1081 #define CRYPT_ACTIVATE_IGNORE_CORRUPTION (1 << 8)
1082 /** dm-verity: restart_on_corruption flag - restart kernel on corruption */
1083 #define CRYPT_ACTIVATE_RESTART_ON_CORRUPTION (1 << 9)
1084 /** dm-verity: ignore_zero_blocks - do not verify zero blocks */
1085 #define CRYPT_ACTIVATE_IGNORE_ZERO_BLOCKS (1 << 10)
1086 /** key loaded in kernel keyring instead directly in dm-crypt */
1087 #define CRYPT_ACTIVATE_KEYRING_KEY (1 << 11)
1088 /** dm-integrity: direct writes, do not use journal */
1089 #define CRYPT_ACTIVATE_NO_JOURNAL (1 << 12)
1090 /** dm-integrity: recovery mode - no journal, no integrity checks */
1091 #define CRYPT_ACTIVATE_RECOVERY (1 << 13)
1092 /** ignore persistently stored flags */
1093 #define CRYPT_ACTIVATE_IGNORE_PERSISTENT (1 << 14)
1094 /** dm-verity: check_at_most_once - check data blocks only the first time */
1095 #define CRYPT_ACTIVATE_CHECK_AT_MOST_ONCE (1 << 15)
1096 /** allow activation check including unbound keyslots (keyslots without segments) */
1097 #define CRYPT_ACTIVATE_ALLOW_UNBOUND_KEY (1 << 16)
1098 /** dm-integrity: activate automatic recalculation */
1099 #define CRYPT_ACTIVATE_RECALCULATE (1 << 17)
1100 /** reactivate existing and update flags, input only */
1101 #define CRYPT_ACTIVATE_REFRESH  (1 << 18)
1102 /** Use global lock to serialize memory hard KDF on activation (OOM workaround) */
1103 #define CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF (1 << 19)
1104 /** dm-integrity: direct writes, use bitmap to track dirty sectors */
1105 #define CRYPT_ACTIVATE_NO_JOURNAL_BITMAP (1 << 20)
1106 /** device is suspended (key should be wiped from memory), output only */
1107 #define CRYPT_ACTIVATE_SUSPENDED (1 << 21)
1108 /** use IV sector counted in sector_size instead of default 512 bytes sectors */
1109 #define CRYPT_ACTIVATE_IV_LARGE_SECTORS (1 << 22)
1110 /** dm-verity: panic_on_corruption flag - panic kernel on corruption */
1111 #define CRYPT_ACTIVATE_PANIC_ON_CORRUPTION (1 << 23)
1112 /** dm-crypt: bypass internal workqueue and process read requests synchronously. */
1113 #define CRYPT_ACTIVATE_NO_READ_WORKQUEUE (1 << 24)
1114 /** dm-crypt: bypass internal workqueue and process write requests synchronously. */
1115 #define CRYPT_ACTIVATE_NO_WRITE_WORKQUEUE (1 << 25)
1116
1117 /**
1118  * Active device runtime attributes
1119  */
1120 struct crypt_active_device {
1121         uint64_t offset;    /**< offset in sectors */
1122         uint64_t iv_offset; /**< IV initialization sector */
1123         uint64_t size;      /**< active device size */
1124         uint32_t flags;     /**< activation flags */
1125 };
1126
1127 /**
1128  * Receive runtime attributes of active crypt device.
1129  *
1130  * @param cd crypt device handle (can be @e NULL)
1131  * @param name name of active device
1132  * @param cad preallocated active device attributes to fill
1133  *
1134  * @return @e 0 on success or negative errno value otherwise
1135  *
1136  */
1137 int crypt_get_active_device(struct crypt_device *cd,
1138         const char *name,
1139         struct crypt_active_device *cad);
1140
1141 /**
1142  * Get detected number of integrity failures.
1143  *
1144  * @param cd crypt device handle (can be @e NULL)
1145  * @param name name of active device
1146  *
1147  * @return number of integrity failures or @e 0 otherwise
1148  *
1149  */
1150 uint64_t crypt_get_active_integrity_failures(struct crypt_device *cd,
1151         const char *name);
1152 /** @} */
1153
1154 /**
1155  * @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
1156  * @addtogroup crypt-pflags
1157  * @{
1158  */
1159
1160 /**
1161  * LUKS2 header requirements
1162  */
1163 /** Unfinished offline reencryption */
1164 #define CRYPT_REQUIREMENT_OFFLINE_REENCRYPT     (1 << 0)
1165 /** Online reencryption in-progress */
1166 #define CRYPT_REQUIREMENT_ONLINE_REENCRYPT      (1 << 1)
1167 /** unknown requirement in header (output only) */
1168 #define CRYPT_REQUIREMENT_UNKNOWN               (1 << 31)
1169
1170 /**
1171  * Persistent flags type
1172  */
1173 typedef enum {
1174         CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
1175         CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
1176 } crypt_flags_type;
1177
1178 /**
1179  * Set persistent flags.
1180  *
1181  * @param cd crypt device handle (can be @e NULL)
1182  * @param type type to set (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1183  * @param flags flags to set
1184  *
1185  * @return @e 0 on success or negative errno value otherwise
1186  *
1187  * @note Valid only for LUKS2.
1188  *
1189  * @note Not all activation flags can be stored. Only ALLOW_DISCARD,
1190  *       SAME_CPU_CRYPT, SUBMIT_FROM_CRYPT_CPU and NO_JOURNAL can be
1191  *       stored persistently.
1192  *
1193  * @note Only requirements flags recognised by current library may be set.
1194  *       CRYPT_REQUIREMENT_UNKNOWN is illegal (output only) in set operation.
1195  */
1196 int crypt_persistent_flags_set(struct crypt_device *cd,
1197         crypt_flags_type type,
1198         uint32_t flags);
1199
1200 /**
1201  * Get persistent flags stored in header.
1202  *
1203  * @param cd crypt device handle (can be @e NULL)
1204  * @param type flags type to retrieve (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1205  * @param flags reference to output variable
1206  *
1207  * @return @e 0 on success or negative errno value otherwise
1208  */
1209 int crypt_persistent_flags_get(struct crypt_device *cd,
1210         crypt_flags_type type,
1211         uint32_t *flags);
1212 /** @} */
1213
1214 /**
1215  * @defgroup crypt-activation Device activation
1216  * @addtogroup crypt-activation
1217  * @{
1218  */
1219
1220 /**
1221  * Activate device or check passphrase.
1222  *
1223  * @param cd crypt device handle
1224  * @param name name of device to create, if @e NULL only check passphrase
1225  * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
1226  * @param passphrase passphrase used to unlock volume key
1227  * @param passphrase_size size of @e passphrase
1228  * @param flags activation flags
1229  *
1230  * @return unlocked key slot number or negative errno otherwise.
1231  */
1232 int crypt_activate_by_passphrase(struct crypt_device *cd,
1233         const char *name,
1234         int keyslot,
1235         const char *passphrase,
1236         size_t passphrase_size,
1237         uint32_t flags);
1238
1239 /**
1240  * Activate device or check using key file.
1241  *
1242  * @param cd crypt device handle
1243  * @param name name of device to create, if @e NULL only check keyfile
1244  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1245  * @param keyfile key file used to unlock volume key
1246  * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
1247  * @param keyfile_offset number of bytes to skip at start of keyfile
1248  * @param flags activation flags
1249  *
1250  * @return unlocked key slot number or negative errno otherwise.
1251  */
1252 int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
1253         const char *name,
1254         int keyslot,
1255         const char *keyfile,
1256         size_t keyfile_size,
1257         uint64_t keyfile_offset,
1258         uint32_t flags);
1259
1260 /**
1261  * Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
1262  */
1263 int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
1264         const char *name,
1265         int keyslot,
1266         const char *keyfile,
1267         size_t keyfile_size,
1268         size_t keyfile_offset,
1269         uint32_t flags);
1270
1271 /**
1272  * Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
1273  */
1274 int crypt_activate_by_keyfile(struct crypt_device *cd,
1275         const char *name,
1276         int keyslot,
1277         const char *keyfile,
1278         size_t keyfile_size,
1279         uint32_t flags);
1280
1281 /**
1282  * Activate device using provided volume key.
1283  *
1284  * @param cd crypt device handle
1285  * @param name name of device to create, if @e NULL only check volume key
1286  * @param volume_key provided volume key (or @e NULL to use internal)
1287  * @param volume_key_size size of volume_key
1288  * @param flags activation flags
1289  *
1290  * @return @e 0 on success or negative errno value otherwise.
1291  *
1292  * @note If @e NULL is used for volume_key, device has to be initialized
1293  *       by previous operation (like @ref crypt_format
1294  *       or @ref crypt_init_by_name)
1295  * @note For VERITY the volume key means root hash required for activation.
1296  *       Because kernel dm-verity is always read only, you have to provide
1297  *       CRYPT_ACTIVATE_READONLY flag always.
1298  * @note For TCRYPT the volume key should be always NULL and because master
1299  *       key from decrypted header is used instead.
1300  */
1301 int crypt_activate_by_volume_key(struct crypt_device *cd,
1302         const char *name,
1303         const char *volume_key,
1304         size_t volume_key_size,
1305         uint32_t flags);
1306
1307 /**
1308  * Activate VERITY device using provided key and optional signature).
1309  *
1310  * @param cd crypt device handle
1311  * @param name name of device to create
1312  * @param volume_key provided volume key
1313  * @param volume_key_size size of volume_key
1314  * @param signature buffer with signature for the key
1315  * @param signature_size bsize of signature buffer
1316  * @param flags activation flags
1317  *
1318  * @return @e 0 on success or negative errno value otherwise.
1319  *
1320  * @note For VERITY the volume key means root hash required for activation.
1321  *      Because kernel dm-verity is always read only, you have to provide
1322  *      CRYPT_ACTIVATE_READONLY flag always.
1323  */
1324 int crypt_activate_by_signed_key(struct crypt_device *cd,
1325         const char *name,
1326         const char *volume_key,
1327         size_t volume_key_size,
1328         const char *signature,
1329         size_t signature_size,
1330         uint32_t flags);
1331
1332 /**
1333  * Activate device using passphrase stored in kernel keyring.
1334  *
1335  * @param cd crypt device handle
1336  * @param name name of device to create, if @e NULL only check passphrase in keyring
1337  * @param key_description kernel keyring key description library should look
1338  *        for passphrase in
1339  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1340  * @param flags activation flags
1341  *
1342  * @return @e unlocked keyslot number on success or negative errno value otherwise.
1343  *
1344  * @note Keyslot passphrase must be stored in 'user' key type
1345  *       and the key has to be reachable for process context
1346  *       on behalf of which this function is called.
1347  */
1348 int crypt_activate_by_keyring(struct crypt_device *cd,
1349         const char *name,
1350         const char *key_description,
1351         int keyslot,
1352         uint32_t flags);
1353
1354 /** lazy deactivation - remove once last user releases it */
1355 #define CRYPT_DEACTIVATE_DEFERRED (1 << 0)
1356 /** force deactivation - if the device is busy, it is replaced by error device */
1357 #define CRYPT_DEACTIVATE_FORCE    (1 << 1)
1358
1359 /**
1360  * Deactivate crypt device. This function tries to remove active device-mapper
1361  * mapping from kernel. Also, sensitive data like the volume key are removed from
1362  * memory
1363  *
1364  * @param cd crypt device handle, can be @e NULL
1365  * @param name name of device to deactivate
1366  * @param flags deactivation flags
1367  *
1368  * @return @e 0 on success or negative errno value otherwise.
1369  *
1370  */
1371 int crypt_deactivate_by_name(struct crypt_device *cd,
1372         const char *name,
1373         uint32_t flags);
1374
1375 /**
1376  * Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
1377  */
1378 int crypt_deactivate(struct crypt_device *cd, const char *name);
1379 /** @} */
1380
1381 /**
1382  * @defgroup crypt-key Volume Key manipulation
1383  * @addtogroup crypt-key
1384  * @{
1385  */
1386
1387 /**
1388  * Get volume key from crypt device.
1389  *
1390  * @param cd crypt device handle
1391  * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
1392  * @param volume_key buffer for volume key
1393  * @param volume_key_size on input, size of buffer @e volume_key,
1394  *        on output size of @e volume_key
1395  * @param passphrase passphrase used to unlock volume key
1396  * @param passphrase_size size of @e passphrase
1397  *
1398  * @return unlocked key slot number or negative errno otherwise.
1399  *
1400  * @note For TCRYPT cipher chain is the volume key concatenated
1401  *       for all ciphers in chain.
1402  * @note For VERITY the volume key means root hash used for activation.
1403  */
1404 int crypt_volume_key_get(struct crypt_device *cd,
1405         int keyslot,
1406         char *volume_key,
1407         size_t *volume_key_size,
1408         const char *passphrase,
1409         size_t passphrase_size);
1410
1411 /**
1412  * Verify that provided volume key is valid for crypt device.
1413  *
1414  * @param cd crypt device handle
1415  * @param volume_key provided volume key
1416  * @param volume_key_size size of @e volume_key
1417  *
1418  * @return @e 0 on success or negative errno value otherwise.
1419  */
1420 int crypt_volume_key_verify(struct crypt_device *cd,
1421         const char *volume_key,
1422         size_t volume_key_size);
1423 /** @} */
1424
1425 /**
1426  * @defgroup crypt-devstat Crypt and Verity device status
1427  * @addtogroup crypt-devstat
1428  * @{
1429  */
1430
1431 /**
1432  * Device status
1433  */
1434 typedef enum {
1435         CRYPT_INVALID,  /**< device mapping is invalid in this context */
1436         CRYPT_INACTIVE, /**< no such mapped device */
1437         CRYPT_ACTIVE,   /**< device is active */
1438         CRYPT_BUSY      /**< device is active and has open count > 0 */
1439 } crypt_status_info;
1440
1441 /**
1442  * Get status info about device name.
1443  *
1444  * @param cd crypt device handle, can be @e NULL
1445  * @param name crypt device name
1446  *
1447  * @return value defined by crypt_status_info.
1448  *
1449  */
1450 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
1451
1452 /**
1453  * Dump text-formatted information about crypt or verity device to log output.
1454  *
1455  * @param cd crypt device handle
1456  *
1457  * @return @e 0 on success or negative errno value otherwise.
1458  */
1459 int crypt_dump(struct crypt_device *cd);
1460
1461 /**
1462  * Get cipher used in device.
1463  *
1464  * @param cd crypt device handle
1465  *
1466  * @return used cipher, e.g. "aes" or @e NULL otherwise
1467  *
1468  */
1469 const char *crypt_get_cipher(struct crypt_device *cd);
1470
1471 /**
1472  * Get cipher mode used in device.
1473  *
1474  * @param cd crypt device handle
1475  *
1476  * @return used cipher mode e.g. "xts-plain" or @e otherwise
1477  *
1478  */
1479 const char *crypt_get_cipher_mode(struct crypt_device *cd);
1480
1481 /**
1482  * Get device UUID.
1483  *
1484  * @param cd crypt device handle
1485  *
1486  * @return device UUID or @e NULL if not set
1487  *
1488  */
1489 const char *crypt_get_uuid(struct crypt_device *cd);
1490
1491 /**
1492  * Get path to underlying device.
1493  *
1494  * @param cd crypt device handle
1495  *
1496  * @return path to underlying device name
1497  *
1498  */
1499 const char *crypt_get_device_name(struct crypt_device *cd);
1500
1501 /**
1502  * Get path to detached metadata device or @e NULL if it is not detached.
1503  *
1504  * @param cd crypt device handle
1505  *
1506  * @return path to underlying device name
1507  *
1508  */
1509 const char *crypt_get_metadata_device_name(struct crypt_device *cd);
1510
1511 /**
1512  * Get device offset in 512-bytes sectors where real data starts (on underlying device).
1513  *
1514  * @param cd crypt device handle
1515  *
1516  * @return device offset in sectors
1517  *
1518  */
1519 uint64_t crypt_get_data_offset(struct crypt_device *cd);
1520
1521 /**
1522  * Get IV offset in 512-bytes sectors (skip).
1523  *
1524  * @param cd crypt device handle
1525  *
1526  * @return IV offset
1527  *
1528  */
1529 uint64_t crypt_get_iv_offset(struct crypt_device *cd);
1530
1531 /**
1532  * Get size (in bytes) of volume key for crypt device.
1533  *
1534  * @param cd crypt device handle
1535  *
1536  * @return volume key size
1537  *
1538  * @note For LUKS2, this function can be used only if there is at least
1539  *       one keyslot assigned to data segment.
1540  */
1541 int crypt_get_volume_key_size(struct crypt_device *cd);
1542
1543 /**
1544  * Get size (in bytes) of encryption sector for crypt device.
1545  *
1546  * @param cd crypt device handle
1547  *
1548  * @return sector size
1549  *
1550  */
1551 int crypt_get_sector_size(struct crypt_device *cd);
1552
1553 /**
1554  * Get device parameters for VERITY device.
1555  *
1556  * @param cd crypt device handle
1557  * @param vp verity device info
1558  *
1559  * @e 0 on success or negative errno value otherwise.
1560  *
1561  */
1562 int crypt_get_verity_info(struct crypt_device *cd,
1563         struct crypt_params_verity *vp);
1564
1565 /**
1566  * Get device parameters for INTEGRITY device.
1567  *
1568  * @param cd crypt device handle
1569  * @param ip verity device info
1570  *
1571  * @e 0 on success or negative errno value otherwise.
1572  *
1573  */
1574 int crypt_get_integrity_info(struct crypt_device *cd,
1575         struct crypt_params_integrity *ip);
1576 /** @} */
1577
1578 /**
1579  * @defgroup crypt-benchmark Benchmarking
1580  * Benchmarking of algorithms
1581  * @addtogroup crypt-benchmark
1582  * @{
1583  */
1584
1585 /**
1586  * Informational benchmark for ciphers.
1587  *
1588  * @param cd crypt device handle
1589  * @param cipher (e.g. "aes")
1590  * @param cipher_mode (e.g. "xts"), IV generator is ignored
1591  * @param volume_key_size size of volume key in bytes
1592  * @param iv_size size of IV in bytes
1593  * @param buffer_size size of encryption buffer in bytes used in test
1594  * @param encryption_mbs measured encryption speed in MiB/s
1595  * @param decryption_mbs measured decryption speed in MiB/s
1596  *
1597  * @return @e 0 on success or negative errno value otherwise.
1598  *
1599  * @note If encryption_buffer_size is too small and encryption time
1600  *       cannot be properly measured, -ERANGE is returned.
1601  */
1602 int crypt_benchmark(struct crypt_device *cd,
1603         const char *cipher,
1604         const char *cipher_mode,
1605         size_t volume_key_size,
1606         size_t iv_size,
1607         size_t buffer_size,
1608         double *encryption_mbs,
1609         double *decryption_mbs);
1610
1611 /**
1612  * Informational benchmark for PBKDF.
1613  *
1614  * @param cd crypt device handle
1615  * @param pbkdf PBKDF parameters
1616  * @param password password for benchmark
1617  * @param password_size size of password
1618  * @param salt salt for benchmark
1619  * @param salt_size size of salt
1620  * @param volume_key_size output volume key size
1621  * @param progress callback function
1622  * @param usrptr provided identification in callback
1623  *
1624  * @return @e 0 on success or negative errno value otherwise.
1625  */
1626 int crypt_benchmark_pbkdf(struct crypt_device *cd,
1627         struct crypt_pbkdf_type *pbkdf,
1628         const char *password,
1629         size_t password_size,
1630         const char *salt,
1631         size_t salt_size,
1632         size_t volume_key_size,
1633         int (*progress)(uint32_t time_ms, void *usrptr),
1634         void *usrptr);
1635 /** @} */
1636
1637 /**
1638  * @addtogroup crypt-keyslot
1639  * @{
1640  */
1641
1642 /**
1643  * Crypt keyslot info
1644  */
1645 typedef enum {
1646         CRYPT_SLOT_INVALID,    /**< invalid keyslot */
1647         CRYPT_SLOT_INACTIVE,   /**< keyslot is inactive (free) */
1648         CRYPT_SLOT_ACTIVE,     /**< keyslot is active (used) */
1649         CRYPT_SLOT_ACTIVE_LAST,/**< keylost is active (used)
1650                                  *  and last used at the same time */
1651         CRYPT_SLOT_UNBOUND     /**< keyslot is active and not bound
1652                                  *  to any crypt segment (LUKS2 only) */
1653 } crypt_keyslot_info;
1654
1655 /**
1656  * Get information about particular key slot.
1657  *
1658  * @param cd crypt device handle
1659  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1660  *
1661  * @return value defined by crypt_keyslot_info
1662  *
1663  */
1664 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
1665
1666 /**
1667  * Crypt keyslot priority
1668  */
1669 typedef enum {
1670         CRYPT_SLOT_PRIORITY_INVALID =-1, /**< no such slot */
1671         CRYPT_SLOT_PRIORITY_IGNORE  = 0, /**< CRYPT_ANY_SLOT will ignore it for open */
1672         CRYPT_SLOT_PRIORITY_NORMAL  = 1, /**< default priority, tried after preferred */
1673         CRYPT_SLOT_PRIORITY_PREFER  = 2, /**< will try to open first */
1674 } crypt_keyslot_priority;
1675
1676 /**
1677  * Get keyslot priority (LUKS2)
1678  *
1679  * @param cd crypt device handle
1680  * @param keyslot keyslot number
1681  *
1682  * @return value defined by crypt_keyslot_priority
1683  */
1684 crypt_keyslot_priority crypt_keyslot_get_priority(struct crypt_device *cd, int keyslot);
1685
1686 /**
1687  * Set keyslot priority (LUKS2)
1688  *
1689  * @param cd crypt device handle
1690  * @param keyslot keyslot number
1691  * @param priority priority defined in crypt_keyslot_priority
1692  *
1693  * @return @e 0 on success or negative errno value otherwise.
1694  */
1695 int crypt_keyslot_set_priority(struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority);
1696
1697 /**
1698  * Get number of keyslots supported for device type.
1699  *
1700  * @param type crypt device type
1701  *
1702  * @return slot count or negative errno otherwise if device
1703  * doesn't not support keyslots.
1704  */
1705 int crypt_keyslot_max(const char *type);
1706
1707 /**
1708  * Get keyslot area pointers (relative to metadata device).
1709  *
1710  * @param cd crypt device handle
1711  * @param keyslot keyslot number
1712  * @param offset offset on metadata device (in bytes)
1713  * @param length length of keyslot area (in bytes)
1714  *
1715  * @return @e 0 on success or negative errno value otherwise.
1716  *
1717  */
1718 int crypt_keyslot_area(struct crypt_device *cd,
1719         int keyslot,
1720         uint64_t *offset,
1721         uint64_t *length);
1722
1723 /**
1724  * Get size (in bytes) of stored key in particular keyslot.
1725  * Use for LUKS2 unbound keyslots, for other keyslots it is the same as @ref crypt_get_volume_key_size
1726  *
1727  * @param cd crypt device handle
1728  * @param keyslot keyslot number
1729  *
1730  * @return volume key size or negative errno value otherwise.
1731  *
1732  */
1733 int crypt_keyslot_get_key_size(struct crypt_device *cd, int keyslot);
1734
1735 /**
1736  * Get cipher and key size for keyslot encryption.
1737  * Use for LUKS2 keyslot to set different encryption type than for data encryption.
1738  * Parameters will be used for next keyslot operations.
1739  *
1740  * @param cd crypt device handle
1741  * @param keyslot keyslot number of CRYPT_ANY_SLOT for default
1742  * @param key_size encryption key size (in bytes)
1743  *
1744  * @return cipher specification on success or @e NULL.
1745  *
1746  * @note This is the encryption of keyslot itself, not the data encryption algorithm!
1747  */
1748 const char *crypt_keyslot_get_encryption(struct crypt_device *cd, int keyslot, size_t *key_size);
1749
1750 /**
1751  * Get PBKDF parameters for keyslot.
1752  *
1753  * @param cd crypt device handle
1754  * @param keyslot keyslot number
1755  * @param pbkdf struct with returned PBKDF parameters
1756  *
1757  * @return @e 0 on success or negative errno value otherwise.
1758  */
1759 int crypt_keyslot_get_pbkdf(struct crypt_device *cd, int keyslot, struct crypt_pbkdf_type *pbkdf);
1760
1761 /**
1762  * Set encryption for keyslot.
1763  * Use for LUKS2 keyslot to set different encryption type than for data encryption.
1764  * Parameters will be used for next keyslot operations that create or change a keyslot.
1765  *
1766  * @param cd crypt device handle
1767  * @param cipher (e.g. "aes-xts-plain64")
1768  * @param key_size encryption key size (in bytes)
1769  *
1770  * @return @e 0 on success or negative errno value otherwise.
1771  *
1772  * @note To reset to default keyslot encryption (the same as for data)
1773  *       set cipher to NULL and key size to 0.
1774  */
1775 int crypt_keyslot_set_encryption(struct crypt_device *cd,
1776         const char *cipher,
1777         size_t key_size);
1778
1779 /**
1780  * Get directory where mapped crypt devices are created
1781  *
1782  * @return the directory path
1783  */
1784 const char *crypt_get_dir(void);
1785
1786 /** @} */
1787
1788 /**
1789  * @defgroup crypt-backup Device metadata backup
1790  * @addtogroup crypt-backup
1791  * @{
1792  */
1793 /**
1794  * Backup header and keyslots to file.
1795  *
1796  * @param cd crypt device handle
1797  * @param requested_type @link crypt-type @endlink or @e NULL for all known
1798  * @param backup_file file to backup header to
1799  *
1800  * @return @e 0 on success or negative errno value otherwise.
1801  *
1802  */
1803 int crypt_header_backup(struct crypt_device *cd,
1804         const char *requested_type,
1805         const char *backup_file);
1806
1807 /**
1808  * Restore header and keyslots from backup file.
1809  *
1810  * @param cd crypt device handle
1811  * @param requested_type @link crypt-type @endlink or @e NULL for all known
1812  * @param backup_file file to restore header from
1813  *
1814  * @return @e 0 on success or negative errno value otherwise.
1815  *
1816  */
1817 int crypt_header_restore(struct crypt_device *cd,
1818         const char *requested_type,
1819         const char *backup_file);
1820 /** @} */
1821
1822 /**
1823  * @defgroup crypt-dbg Library debug level
1824  * Set library debug level
1825  * @addtogroup crypt-dbg
1826  * @{
1827  */
1828
1829 /** Debug all */
1830 #define CRYPT_DEBUG_ALL  -1
1831 /** Debug all with additional JSON dump (for LUKS2) */
1832 #define CRYPT_DEBUG_JSON  -2
1833 /** Debug none */
1834 #define CRYPT_DEBUG_NONE  0
1835
1836 /**
1837  * Set the debug level for library
1838  *
1839  * @param level debug level
1840  *
1841  */
1842 void crypt_set_debug_level(int level);
1843 /** @} */
1844
1845 /**
1846  * @defgroup crypt-keyfile Function to read keyfile
1847  * @addtogroup crypt-keyfile
1848  * @{
1849  */
1850
1851 /**
1852  * Read keyfile
1853  *
1854  * @param cd crypt device handle
1855  * @param keyfile keyfile to read
1856  * @param key buffer for key
1857  * @param key_size_read size of read key
1858  * @param keyfile_offset key offset in keyfile
1859  * @param key_size exact key length to read from file or 0
1860  * @param flags keyfile read flags
1861  *
1862  * @return @e 0 on success or negative errno value otherwise.
1863  *
1864  * @note If key_size is set to zero we read internal max length
1865  *       and actual size read is returned via key_size_read parameter.
1866  */
1867 int crypt_keyfile_device_read(struct crypt_device *cd,
1868         const char *keyfile,
1869         char **key, size_t *key_size_read,
1870         uint64_t keyfile_offset,
1871         size_t key_size,
1872         uint32_t flags);
1873
1874 /**
1875  * Backward compatible crypt_keyfile_device_read() (with size_t offset).
1876  */
1877 int crypt_keyfile_read(struct crypt_device *cd,
1878         const char *keyfile,
1879         char **key, size_t *key_size_read,
1880         size_t keyfile_offset,
1881         size_t key_size,
1882         uint32_t flags);
1883
1884 /** Read key only to the first end of line (\\n). */
1885 #define CRYPT_KEYFILE_STOP_EOL   (1 << 0)
1886 /** @} */
1887
1888 /**
1889  * @defgroup crypt-wipe Function to wipe device
1890  * @addtogroup crypt-wipe
1891  * @{
1892  */
1893 /**
1894  * Wipe pattern
1895  */
1896 typedef enum {
1897         CRYPT_WIPE_ZERO,           /**< Fill with zeroes */
1898         CRYPT_WIPE_RANDOM,         /**< Use RNG to fill data */
1899         CRYPT_WIPE_ENCRYPTED_ZERO, /**< Add encryption and fill with zeroes as plaintext */
1900         CRYPT_WIPE_SPECIAL,        /**< Compatibility only, do not use (Gutmann method) */
1901 } crypt_wipe_pattern;
1902
1903 /**
1904  * Wipe/Fill (part of) a device with the selected pattern.
1905  *
1906  * @param cd crypt device handle
1907  * @param dev_path path to device to wipe or @e NULL if data device should be used
1908  * @param pattern selected wipe pattern
1909  * @param offset offset on device (in bytes)
1910  * @param length length of area to be wiped (in bytes)
1911  * @param wipe_block_size used block for wiping (one step) (in bytes)
1912  * @param flags wipe flags
1913  * @param progress callback function called after each @e wipe_block_size or @e NULL
1914  * @param usrptr provided identification in callback
1915  *
1916  * @return @e 0 on success or negative errno value otherwise.
1917  *
1918  * @note A @e progress callback can interrupt wipe process by returning non-zero code.
1919  *
1920  * @note If the error values is -EIO or -EINTR, some part of the device could
1921  *       be overwritten. Other error codes (-EINVAL, -ENOMEM) means that no IO was performed.
1922  */
1923 int crypt_wipe(struct crypt_device *cd,
1924         const char *dev_path, /* if null, use data device */
1925         crypt_wipe_pattern pattern,
1926         uint64_t offset,
1927         uint64_t length,
1928         size_t wipe_block_size,
1929         uint32_t flags,
1930         int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
1931         void *usrptr
1932 );
1933
1934 /** Use direct-io */
1935 #define CRYPT_WIPE_NO_DIRECT_IO (1 << 0)
1936 /** @} */
1937
1938 /**
1939  * @defgroup crypt-tokens LUKS2 token wrapper access
1940  *
1941  * Utilities for handling tokens LUKS2
1942  * Token is a device or a method how to read password for particular keyslot
1943  * automatically. It can be chunk of data stored on hardware token or
1944  * just a metadata how to generate the password.
1945  *
1946  * @addtogroup crypt-tokens
1947  * @{
1948  */
1949
1950 /** Iterate through all tokens */
1951 #define CRYPT_ANY_TOKEN -1
1952
1953 /**
1954  * Get content of a token definition in JSON format.
1955  *
1956  * @param cd crypt device handle
1957  * @param token token id
1958  * @param json buffer with JSON
1959  *
1960  * @return allocated token id or negative errno otherwise.
1961  */
1962 int crypt_token_json_get(struct crypt_device *cd,
1963         int token,
1964         const char **json);
1965
1966 /**
1967  * Store content of a token definition in JSON format.
1968  *
1969  * @param cd crypt device handle
1970  * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
1971  * @param json buffer with JSON or @e NULL to remove token
1972  *
1973  * @return allocated token id or negative errno otherwise.
1974  *
1975  * @note The buffer must be in proper JSON format and must contain at least
1976  *       string "type" with slot type and an array of string names "keyslots".
1977  *       Keyslots array contains assignments to particular slots and can be empty.
1978  */
1979 int crypt_token_json_set(struct crypt_device *cd,
1980         int token,
1981         const char *json);
1982
1983 /**
1984  * Token info
1985  */
1986 typedef enum {
1987         CRYPT_TOKEN_INVALID,          /**< token is invalid */
1988         CRYPT_TOKEN_INACTIVE,         /**< token is empty (free) */
1989         CRYPT_TOKEN_INTERNAL,         /**< active internal token with driver */
1990         CRYPT_TOKEN_INTERNAL_UNKNOWN, /**< active internal token (reserved name) with missing token driver */
1991         CRYPT_TOKEN_EXTERNAL,         /**< active external (user defined) token with driver */
1992         CRYPT_TOKEN_EXTERNAL_UNKNOWN, /**< active external (user defined) token with missing token driver */
1993 } crypt_token_info;
1994
1995 /**
1996  * Get info for specific token.
1997  *
1998  * @param cd crypt device handle
1999  * @param token existing token id
2000  * @param type pointer for returned type string
2001  *
2002  * @return token status info. For any returned status (besides CRYPT_TOKEN_INVALID
2003  *         and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will
2004  *         contain address of type string.
2005  *
2006  * @note if required, create a copy of string referenced in *type before calling next
2007  *       libcryptsetup API function. The reference may become invalid.
2008  */
2009 crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
2010
2011 /**
2012  * LUKS2 keyring token parameters.
2013  *
2014  * @see crypt_token_builtin_set
2015  *
2016  */
2017 struct crypt_token_params_luks2_keyring {
2018         const char *key_description; /**< Reference in keyring */
2019 };
2020
2021 /**
2022  * Create a new luks2 keyring token.
2023  *
2024  * @param cd crypt device handle
2025  * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
2026  * @param params luks2 keyring token params
2027  *
2028  * @return allocated token id or negative errno otherwise.
2029  *
2030  */
2031 int crypt_token_luks2_keyring_set(struct crypt_device *cd,
2032         int token,
2033         const struct crypt_token_params_luks2_keyring *params);
2034
2035 /**
2036  * Get LUKS2 keyring token params
2037  *
2038  * @param cd crypt device handle
2039  * @param token existing luks2 keyring token id
2040  * @param params returned luks2 keyring token params
2041  *
2042  * @return allocated token id or negative errno otherwise.
2043  *
2044  * @note do not call free() on params members. Members are valid only
2045  *       until next libcryptsetup function is called.
2046  */
2047 int crypt_token_luks2_keyring_get(struct crypt_device *cd,
2048         int token,
2049         struct crypt_token_params_luks2_keyring *params);
2050
2051 /**
2052  * Assign a token to particular keyslot.
2053  * (There can be more keyslots assigned to one token id.)
2054  *
2055  * @param cd crypt device handle
2056  * @param token token id
2057  * @param keyslot keyslot to be assigned to token (CRYPT_ANY SLOT
2058  *        assigns all active keyslots to token)
2059  *
2060  * @return allocated token id or negative errno otherwise.
2061  */
2062 int crypt_token_assign_keyslot(struct crypt_device *cd,
2063         int token,
2064         int keyslot);
2065
2066 /**
2067  * Unassign a token from particular keyslot.
2068  * (There can be more keyslots assigned to one token id.)
2069  *
2070  * @param cd crypt device handle
2071  * @param token token id
2072  * @param keyslot keyslot to be unassigned from token (CRYPT_ANY SLOT
2073  *        unassigns all active keyslots from token)
2074  *
2075  * @return allocated token id or negative errno otherwise.
2076  */
2077 int crypt_token_unassign_keyslot(struct crypt_device *cd,
2078         int token,
2079         int keyslot);
2080
2081 /**
2082  * Get info about token assignment to particular keyslot.
2083  *
2084  * @param cd crypt device handle
2085  * @param token token id
2086  * @param keyslot keyslot
2087  *
2088  * @return 0 on success (token exists and is assigned to the keyslot),
2089  *         -ENOENT if token is not assigned to a keyslot (token, keyslot
2090  *         or both may be inactive) or other negative errno otherwise.
2091  */
2092 int crypt_token_is_assigned(struct crypt_device *cd,
2093         int token,
2094         int keyslot);
2095
2096 /**
2097  * Token handler open function prototype.
2098  * This function retrieves password from a token and return allocated buffer
2099  * containing this password. This buffer has to be deallocated by calling
2100  * free() function and content should be wiped before deallocation.
2101  *
2102  * @param cd crypt device handle
2103  * @param token token id
2104  * @param buffer returned allocated buffer with password
2105  * @param buffer_len length of the buffer
2106  * @param usrptr user data in @link crypt_activate_by_token @endlink
2107  */
2108 typedef int (*crypt_token_open_func) (
2109         struct crypt_device *cd,
2110         int token,
2111         char **buffer,
2112         size_t *buffer_len,
2113         void *usrptr);
2114
2115 /**
2116  * Token handler buffer free function prototype.
2117  * This function is used by library to free the buffer with keyslot
2118  * passphrase when it's no longer needed. If not defined the library
2119  * overwrites buffer with zeroes and call free().
2120  *
2121  * @param buffer the buffer with keyslot passphrase
2122  * @param buffer_len the buffer length
2123  */
2124 typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
2125
2126 /**
2127  * Token handler validate function prototype.
2128  * This function validates JSON representation of user defined token for additional data
2129  * specific for its token type. If defined in the handler, it's called
2130  * during @link crypt_activate_by_token @endlink. It may also be called during
2131  * @link crypt_token_json_set @endlink when appropriate token handler was registered before
2132  * with @link crypt_token_register @endlink.
2133  *
2134  * @param cd crypt device handle
2135  * @param json buffer with JSON
2136  */
2137 typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
2138
2139 /**
2140  * Token handler dump function prototype.
2141  * This function is supposed to print token implementation specific details. It gets
2142  * called during @link crypt_dump @endlink if token handler was registered before.
2143  *
2144  * @param cd crypt device handle
2145  * @param json buffer with token JSON
2146  *
2147  * @note dump implementations are advised to use @link crypt_log @endlink function
2148  *       to dump token details.
2149  */
2150 typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
2151
2152 /**
2153  * Token handler
2154  */
2155 typedef struct  {
2156         const char *name;           /**< token handler name */
2157         crypt_token_open_func open; /**< token handler open function */
2158         crypt_token_buffer_free_func buffer_free; /**< token handler buffer_free function (optional) */
2159         crypt_token_validate_func validate; /**< token handler validate function (optional) */
2160         crypt_token_dump_func dump; /**< token handler dump function (optional) */
2161 } crypt_token_handler;
2162
2163 /**
2164  * Register token handler
2165  *
2166  * @param handler token handler to register
2167  *
2168  * @return @e 0 on success or negative errno value otherwise.
2169  */
2170 int crypt_token_register(const crypt_token_handler *handler);
2171
2172 /**
2173  * Activate device or check key using a token.
2174  *
2175  * @param cd crypt device handle
2176  * @param name name of device to create, if @e NULL only check token
2177  * @param token requested token to check or CRYPT_ANY_TOKEN to check all
2178  * @param usrptr provided identification in callback
2179  * @param flags activation flags
2180  *
2181  * @return unlocked key slot number or negative errno otherwise.
2182  */
2183 int crypt_activate_by_token(struct crypt_device *cd,
2184         const char *name,
2185         int token,
2186         void *usrptr,
2187         uint32_t flags);
2188 /** @} */
2189
2190 /**
2191  * @defgroup crypt-reencryption LUKS2 volume reencryption support
2192  *
2193  * Set of functions to handling LUKS2 volume reencryption
2194  *
2195  * @addtogroup crypt-reencryption
2196  * @{
2197  */
2198
2199 /** Initialize reencryption metadata but do not run reencryption yet. (in) */
2200 #define CRYPT_REENCRYPT_INITIALIZE_ONLY    (1 << 0)
2201 /** Move the first segment, used only with data shift. (in/out) */
2202 #define CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT (1 << 1)
2203 /** Resume already initialized reencryption only. (in) */
2204 #define CRYPT_REENCRYPT_RESUME_ONLY        (1 << 2)
2205 /** Run reencryption recovery only. (in) */
2206 #define CRYPT_REENCRYPT_RECOVERY           (1 << 3)
2207 /** Reencryption requires metadata protection. (in/out) */
2208 #define CRYPT_REENCRYPT_REPAIR_NEEDED      (1 << 4)
2209
2210 /**
2211  * Reencryption direction
2212  */
2213 typedef enum {
2214         CRYPT_REENCRYPT_FORWARD = 0, /**< forward direction */
2215         CRYPT_REENCRYPT_BACKWARD     /**< backward direction */
2216 } crypt_reencrypt_direction_info;
2217
2218 /**
2219  * Reencryption mode
2220  */
2221 typedef enum {
2222         CRYPT_REENCRYPT_REENCRYPT = 0, /**< Reencryption mode */
2223         CRYPT_REENCRYPT_ENCRYPT,       /**< Encryption mode */
2224         CRYPT_REENCRYPT_DECRYPT,       /**< Decryption mode */
2225 } crypt_reencrypt_mode_info;
2226
2227 /**
2228  * LUKS2 reencryption options.
2229  */
2230 struct crypt_params_reencrypt {
2231         crypt_reencrypt_mode_info mode;           /**< Reencryption mode, immutable after first init. */
2232         crypt_reencrypt_direction_info direction; /**< Reencryption direction, immutable after first init. */
2233         const char *resilience;                   /**< Resilience mode: "none", "checksum", "journal" or "shift" (only "shift" is immutable after init) */
2234         const char *hash;                         /**< Used hash for "checksum" resilience type, ignored otherwise. */
2235         uint64_t data_shift;                      /**< Used in "shift" mode, must be non-zero, immutable after first init. */
2236         uint64_t max_hotzone_size;                /**< Exact hotzone size for "none" mode. Maximum hotzone size for "checksum" and "journal" modes. */
2237         uint64_t device_size;                     /**< Reencrypt only initial part of the data device. */
2238         const struct crypt_params_luks2 *luks2;   /**< LUKS2 parameters for the final reencryption volume.*/
2239         uint32_t flags;                           /**< Reencryption flags. */
2240 };
2241
2242 /**
2243  * Initialize reencryption metadata using passphrase.
2244  *
2245  * This function initializes on-disk metadata to include all reencryption segments,
2246  * according to the provided options.
2247  * If metadata already contains ongoing reencryption metadata, it loads these parameters
2248  * (in this situation all parameters except @e name and @e passphrase can be omitted).
2249  *
2250  * @param cd crypt device handle
2251  * @param name name of active device or @e NULL for offline reencryption
2252  * @param passphrase passphrase used to unlock volume key
2253  * @param passphrase_size size of @e passphrase (binary data)
2254  * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2255  * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2256  * @param cipher cipher specification (e.g. "aes")
2257  * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2258  * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2259  *
2260  * @return reencryption key slot number or negative errno otherwise.
2261  */
2262 int crypt_reencrypt_init_by_passphrase(struct crypt_device *cd,
2263         const char *name,
2264         const char *passphrase,
2265         size_t passphrase_size,
2266         int keyslot_old,
2267         int keyslot_new,
2268         const char *cipher,
2269         const char *cipher_mode,
2270         const struct crypt_params_reencrypt *params);
2271
2272 /**
2273  * Initialize reencryption metadata using passphrase in keyring.
2274  *
2275  * This function initializes on-disk metadata to include all reencryption segments,
2276  * according to the provided options.
2277  * If metadata already contains ongoing reencryption metadata, it loads these parameters
2278  * (in this situation all parameters except @e name and @e key_description can be omitted).
2279  *
2280  * @param cd crypt device handle
2281  * @param name name of active device or @e NULL for offline reencryption
2282  * @param key_description passphrase (key) identification in keyring
2283  * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2284  * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2285  * @param cipher cipher specification (e.g. "aes")
2286  * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2287  * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2288  *
2289  * @return reencryption key slot number or negative errno otherwise.
2290  */
2291 int crypt_reencrypt_init_by_keyring(struct crypt_device *cd,
2292         const char *name,
2293         const char *key_description,
2294         int keyslot_old,
2295         int keyslot_new,
2296         const char *cipher,
2297         const char *cipher_mode,
2298         const struct crypt_params_reencrypt *params);
2299
2300 /**
2301  * Run data reencryption.
2302  *
2303  * @param cd crypt device handle
2304  * @param progress is a callback function reporting device \b size,
2305  * current \b offset of reencryption and provided \b usrptr identification
2306  *
2307  * @return @e 0 on success or negative errno value otherwise.
2308  */
2309 int crypt_reencrypt(struct crypt_device *cd,
2310                     int (*progress)(uint64_t size, uint64_t offset, void *usrptr));
2311
2312 /**
2313  * Reencryption status info
2314  */
2315 typedef enum {
2316         CRYPT_REENCRYPT_NONE = 0, /**< No reencryption in progress */
2317         CRYPT_REENCRYPT_CLEAN,    /**< Ongoing reencryption in a clean state. */
2318         CRYPT_REENCRYPT_CRASH,    /**< Aborted reencryption that need internal recovery. */
2319         CRYPT_REENCRYPT_INVALID   /**< Invalid state. */
2320 } crypt_reencrypt_info;
2321
2322 /**
2323  * LUKS2 reencryption status.
2324  *
2325  * @param cd crypt device handle
2326  * @param params reencryption parameters
2327  *
2328  * @return reencryption status info and parameters.
2329  */
2330 crypt_reencrypt_info crypt_reencrypt_status(struct crypt_device *cd,
2331                 struct crypt_params_reencrypt *params);
2332 /** @} */
2333
2334 /**
2335  * @defgroup crypt-memory Safe memory helpers functions
2336  * @addtogroup crypt-memory
2337  * @{
2338  */
2339
2340 /**
2341  * Allocate safe memory (content is safely wiped on deallocation).
2342  *
2343  * @param size size of memory in bytes
2344  *
2345  * @return pointer to allocated memory or @e NULL.
2346  */
2347 void *crypt_safe_alloc(size_t size);
2348
2349 /**
2350  * Release safe memory, content is safely wiped.
2351  * The pointer must be allocated with @link crypt_safe_alloc @endlink
2352  *
2353  * @param data pointer to memory to be deallocated
2354  */
2355 void crypt_safe_free(void *data);
2356
2357 /**
2358  * Reallocate safe memory (content is copied and safely wiped on deallocation).
2359  *
2360  * @param data pointer to memory to be deallocated
2361  * @param size new size of memory in bytes
2362  *
2363  * @return pointer to allocated memory or @e NULL.
2364  */
2365 void *crypt_safe_realloc(void *data, size_t size);
2366
2367 /**
2368  * Safe clear memory area (compile should not compile this call out).
2369  *
2370  * @param data pointer to memory to be cleared
2371  * @param size size of memory in bytes
2372  */
2373 void crypt_safe_memzero(void *data, size_t size);
2374
2375 /** @} */
2376
2377 #ifdef __cplusplus
2378 }
2379 #endif
2380 #endif /* _LIBCRYPTSETUP_H */