libcryptsetup.h 65.6 KB
Newer Older
Milan Broz's avatar
Milan Broz committed
1 2 3
/*
 * libcryptsetup - cryptsetup library
 *
Milan Broz's avatar
Milan Broz committed
4 5 6 7
 * Copyright (C) 2004 Jana Saout <jana@saout.de>
 * Copyright (C) 2004-2007 Clemens Fruhwirth <clemens@endorphin.org>
 * Copyright (C) 2009-2019 Red Hat, Inc. All rights reserved.
 * Copyright (C) 2009-2019 Milan Broz
Milan Broz's avatar
Milan Broz committed
8 9 10
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
11 12
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
Milan Broz's avatar
Milan Broz committed
13 14 15 16 17 18 19 20 21 22 23
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

24 25 26 27 28
/**
 * @file libcryptsetup.h
 * @brief Public cryptsetup API
 *
 * For more verbose examples of LUKS related use cases,
29
 * please read @ref index "examples".
30 31
 */

32 33
#ifndef _LIBCRYPTSETUP_H
#define _LIBCRYPTSETUP_H
34 35 36
#ifdef __cplusplus
extern "C" {
#endif
37

38
#include <stddef.h>
39 40
#include <stdint.h>

41 42 43 44 45 46 47
/**
 * @defgroup crypt-init Cryptsetup device context initialization
 * Set of functions for creating and destroying @e crypt_device context
 * @addtogroup crypt-init
 * @{
 */

48 49
struct crypt_device; /* crypt device handle */

50
/**
51
 * Initialize crypt device handle and check if the provided device exists.
52
 *
53 54 55 56 57 58
 * @param cd Returns pointer to crypt device handle
 * @param device Path to the backing device.
 * 	  If @e device is not a block device but a path to some file,
 * 	  the function will try to create a loopdevice and attach
 * 	  the file to the loopdevice with AUTOCLEAR flag set.
 * 	  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 69 70 71 72
/**
 * Initialize crypt device handle with optional data device and check
 * if devices exist.
 *
 * @param cd Returns pointer to crypt device handle
 * @param device Path to the backing device or detached header.
73
 * @param data_device Path to the data device or @e NULL.
74 75 76 77 78 79 80 81 82 83
 *
 * @return @e 0 on success or negative errno value otherwise.
 *
 * @note Note that logging is not initialized here, possible messages use
 * 	 default log function.
 */
int crypt_init_data_device(struct crypt_device **cd,
	const char *device,
	const char *data_device);

84
/**
85
 * Initialize crypt device handle from provided active device name,
86
 * and, optionally, from separate metadata (header) device
87 88
 * and check if provided device exists.
 *
89 90 91 92 93 94
 * @return @e 0 on success or negative errno value otherwise.
 *
 * @param cd returns crypt device handle for active device
 * @param name name of active crypt device
 * @param header_device optional device containing on-disk header
 * 	  (@e NULL if it the same as underlying device on there is no on-disk header)
95
 *
96 97 98
 * @post In case @e device points to active LUKS device but header load fails,
 * context device type is set to @e NULL and @e 0 is returned as if it were successful.
 * Context with @e NULL device type can only be deactivated by crypt_deactivate
99
 *
100 101
 * @note @link crypt_init_by_name @endlink is equivalent to calling
 * 	 crypt_init_by_name_and_header(cd, name, NULL);
102
 */
103
int crypt_init_by_name_and_header(struct crypt_device **cd,
104 105
	const char *name,
	const char *header_device);
106 107 108 109 110 111 112

/**
 * This is equivalent to call
 * @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
 *
 * @sa crypt_init_by_name_and_header
 */
113 114
int crypt_init_by_name(struct crypt_device **cd, const char *name);

115
/**
116
 * Release crypt device context and used memory.
117
 *
118 119 120 121 122 123 124 125 126 127 128 129
 * @param cd crypt device handle
 */
void crypt_free(struct crypt_device *cd);

/**
 * Set confirmation callback (yes/no).
 *
 * If code need confirmation (like resetting uuid or restoring LUKS header from file)
 * this function is called. If not defined, everything is confirmed.
 *
 * Callback function @e confirm should return @e 0 if operation is declined,
 * other values mean accepted.
130
 *
131 132 133 134 135
 * @param cd crypt device handle
 * @param confirm user defined confirm callback reference
 * @param usrptr provided identification in callback
 * @param msg Message for user to confirm
 *
136 137
 * @note Current version of cryptsetup API requires confirmation for UUID change and
 *	 LUKS header restore only.
138
 */
139 140 141
void crypt_set_confirm_callback(struct crypt_device *cd,
	int (*confirm)(const char *msg, void *usrptr),
	void *usrptr);
142 143

/**
144 145 146 147 148 149 150
 * Set data device
 * For LUKS it is encrypted data device when LUKS header is separated.
 * For VERITY it is data device when hash device is separated.
 *
 * @param cd crypt device handle
 * @param device path to device
 *
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 157 158 159 160 161 162 163 164 165 166 167

/**
 * Set data device offset in 512-byte sectors.
 * Used for LUKS.
 * This function is replacement for data alignment fields in LUKS param struct.
 * If set to 0 (default), old behaviour is preserved.
 * This value is reset on @link crypt_load @endlink.
 *
 * @param cd crypt device handle
 * @param data_offset data offset in bytes
 *
 * @returns 0 on success or negative errno value otherwise.
 *
 * @note Data offset must be aligned to multiple of 8 (alignment to 4096-byte sectors)
Rafael Fontenelle's avatar
Rafael Fontenelle committed
168
 * and must be big enough to accommodate the whole LUKS header with all keyslots.
169 170 171 172 173
 * @note Data offset is enforced by this function, device topology
 * information is no longer used after calling this function.
 */
int crypt_set_data_offset(struct crypt_device *cd, uint64_t data_offset);

174 175 176 177 178 179 180
/** @} */

/**
 * @defgroup crypt-log Cryptsetup logging
 * Set of functions and defines used in cryptsetup for
 * logging purposes
 * @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 191
/** debug log level - always on stdout */
#define CRYPT_LOG_DEBUG -1
192 193
/** debug log level - additional JSON output (for LUKS2) */
#define CRYPT_LOG_DEBUG_JSON -2
194 195 196 197 198 199 200 201 202 203

/**
 * Set log function.
 *
 * @param cd crypt device handle (can be @e NULL to set default log function)
 * @param log user defined log function reference
 * @param usrptr provided identification in callback
 * @param level log level below (debug messages can uses other levels)
 * @param msg log message
 */
204
void crypt_set_log_callback(struct crypt_device *cd,
205
	void (*log)(int level, const char *msg, void *usrptr),
206 207
	void *usrptr);

208
/**
209 210 211
 * Defines log function or use the default one otherwise.
 *
 * @see crypt_set_log_callback
212
 *
213 214 215
 * @param cd crypt device handle
 * @param level log level
 * @param msg log message
216
 */
217
void crypt_log(struct crypt_device *cd, int level, const char *msg);
218
/** @} */
219

220
/**
221 222
 * @defgroup crypt-set Cryptsetup settings (RNG, PBKDF, locking)
 * @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 233 234 235 236 237

/**
 * Set which RNG (random number generator) is used for generating long term key
 *
 * @param cd crypt device handle
 * @param rng_type kernel random number generator to use
 *
 */
238 239 240
void crypt_set_rng_type(struct crypt_device *cd, int rng_type);

/**
241
 * Get which RNG (random number generator) is used for generating long term key.
242
 *
243 244
 * @param cd crypt device handle
 * @return RNG type on success or negative errno value otherwise.
245 246 247 248
 *
 */
int crypt_get_rng_type(struct crypt_device *cd);

Milan Broz's avatar
Milan Broz committed
249 250 251 252 253 254 255
/**
 * PBKDF parameters.
 */
struct crypt_pbkdf_type {
	const char *type;         /**< PBKDF algorithm  */
	const char *hash;         /**< Hash algorithm */
	uint32_t time_ms;         /**< Requested time cost [milliseconds] */
256 257
	uint32_t iterations;      /**< Iterations, 0 or benchmarked value. */
	uint32_t max_memory_kb;   /**< Requested or benchmarked  memory cost [kilobytes] */
Milan Broz's avatar
Milan Broz committed
258
	uint32_t parallel_threads;/**< Requested parallel cost [threads] */
259
	uint32_t flags;           /**< CRYPT_PBKDF* flags */
Milan Broz's avatar
Milan Broz committed
260 261
};

262 263 264 265 266 267
/** Iteration time set by crypt_set_iteration_time(), for compatibility only. */
#define CRYPT_PBKDF_ITER_TIME_SET   (1 << 0)
/** Never run benchmarks, use pre-set value or defaults. */
#define CRYPT_PBKDF_NO_BENCHMARK    (1 << 1)

/** PBKDF2 according to RFC2898, LUKS1 legacy */
Milan Broz's avatar
Milan Broz committed
268 269 270 271 272 273 274 275
#define CRYPT_KDF_PBKDF2   "pbkdf2"
/** Argon2i according to RFC */
#define CRYPT_KDF_ARGON2I  "argon2i"
/** Argon2id according to RFC */
#define CRYPT_KDF_ARGON2ID "argon2id"

/**
 * Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot
276
 * about to get created with any crypt_keyslot_add_*() call.
Milan Broz's avatar
Milan Broz committed
277 278 279 280 281 282
 *
 * @param cd crypt device handle
 * @param pbkdf PBKDF parameters
 *
 * @return 0 on success or negative errno value otherwise.
 *
Andrea Gelmini's avatar
Andrea Gelmini committed
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.
Milan Broz's avatar
Milan Broz committed
285 286 287 288
 */
int crypt_set_pbkdf_type(struct crypt_device *cd,
	 const struct crypt_pbkdf_type *pbkdf);

289 290 291
/**
 * Get PBKDF (Password-Based Key Derivation Algorithm) parameters.
 *
292
 * @param pbkdf_type type of PBKDF
293 294 295 296 297 298
 *
 * @return struct on success or NULL value otherwise.
 *
 */
const struct crypt_pbkdf_type *crypt_get_pbkdf_type_params(const char *pbkdf_type);

Milan Broz's avatar
Milan Broz committed
299
/**
300 301 302 303 304 305 306 307 308 309 310 311
 * Get default PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
 * Works only with LUKS device handles (both versions).
 *
 * @param type type of device (see @link crypt-type @endlink)
 *
 * @return struct on success or NULL value otherwise.
 *
 */
const struct crypt_pbkdf_type *crypt_get_pbkdf_default(const char *type);

/**
 * Get current PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
Milan Broz's avatar
Milan Broz committed
312 313 314 315 316 317 318 319 320
 * Works only with LUKS device handles (both versions).
 *
 * @param cd crypt device handle
 *
 * @return struct on success or NULL value otherwise.
 *
 */
const struct crypt_pbkdf_type *crypt_get_pbkdf_type(struct crypt_device *cd);

321 322 323
/**
 * Set how long should cryptsetup iterate in PBKDF2 function.
 * Default value heads towards the iterations which takes around 1 second.
324 325
 * \b Deprecated, only for backward compatibility.
 * Use @link crypt_set_pbkdf_type @endlink.
326 327 328 329 330 331 332 333
 *
 * @param cd crypt device handle
 * @param iteration_time_ms the time in ms
 *
 * @note If the time value is not acceptable for active PBKDF, value is quietly ignored.
 */
void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);

334
/**
335
 * Helper to lock/unlock memory to avoid swap sensitive data to disk.
336
 *
337 338 339 340
 * @param cd crypt device handle, can be @e NULL
 * @param lock 0 to unlock otherwise lock memory
 *
 * @returns Value indicating whether the memory is locked (function can be called multiple times).
341
 *
342 343
 * @note Only root can do this.
 * @note It locks/unlocks all process memory, not only crypt context.
344 345 346
 */
int crypt_memory_lock(struct crypt_device *cd, int lock);

347
/**
348
 * Set global lock protection for on-disk metadata (file-based locking).
349
 *
350 351 352 353 354 355 356 357
 * @param cd crypt device handle, can be @e NULL
 * @param enable 0 to disable locking otherwise enable it (default)
 *
 * @returns @e 0 on success or negative errno value otherwise.
 *
 * @note Locking applied only for some metadata formats (LUKS2).
 * @note The switch is global on the library level.
 * 	 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 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392

/**
 * Set metadata header area sizes. This applies only to LUKS2.
 * These values limit amount of metadata anf number of supportable keyslots.
 *
 * @param cd crypt device handle, can be @e NULL
 * @param metadata_size size in bytes of JSON area + 4k binary header
 * @param keyslots_size size in bytes of binary keyslots area
 *
 * @returns @e 0 on success or negative errno value otherwise.
 *
 * @note The metadata area is stored twice and both copies contain 4k binary header.
 * Only 16,32,64,128,256,512,1024,2048 and 4096 kB value is allowed (see LUKS2 specification).
 * @note Keyslots area size must be multiple of 4k with maximum 128MB.
 */
int crypt_set_metadata_size(struct crypt_device *cd,
	uint64_t metadata_size,
	uint64_t keyslots_size);

/**
 * Get metadata header area sizes. This applies only to LUKS2.
 * These values limit amount of metadata anf number of supportable keyslots.
 *
 * @param cd crypt device handle
 * @param metadata_size size in bytes of JSON area + 4k binary header
 * @param keyslots_size size in bytes of binary keyslots area
 *
 * @returns @e 0 on success or negative errno value otherwise.
 */
int crypt_get_metadata_size(struct crypt_device *cd,
	uint64_t *metadata_size,
	uint64_t *keyslots_size);

393
/** @} */
394

395
/**
396
 * @defgroup crypt-type Cryptsetup on-disk format types
397 398
 * Set of functions, \#defines and structs related
 * to on-disk format types
399
 * @addtogroup crypt-type
400 401 402
 * @{
 */

403
/** plain crypt device, no on-disk header */
404 405 406
#define CRYPT_PLAIN "PLAIN"
/** LUKS version 1 header on-disk */
#define CRYPT_LUKS1 "LUKS1"
Milan Broz's avatar
Milan Broz committed
407 408
/** LUKS version 2 header on-disk */
#define CRYPT_LUKS2 "LUKS2"
409 410
/** loop-AES compatibility mode */
#define CRYPT_LOOPAES "LOOPAES"
411 412
/** dm-verity mode */
#define CRYPT_VERITY "VERITY"
413
/** TCRYPT (TrueCrypt-compatible and VeraCrypt-compatible) mode */
Milan Broz's avatar
Milan Broz committed
414
#define CRYPT_TCRYPT "TCRYPT"
415 416
/** INTEGRITY dm-integrity device */
#define CRYPT_INTEGRITY "INTEGRITY"
417

418 419 420
/** LUKS any version */
#define CRYPT_LUKS NULL

421 422 423
/**
 * Get device type
 *
424 425
 * @param cd crypt device handle
 * @return string according to device type or @e NULL if not known.
426 427 428
 */
const char *crypt_get_type(struct crypt_device *cd);

429 430 431 432 433 434 435
/**
 * Get device default LUKS type
 *
 * @return string according to device type (CRYPT_LUKS1 or CRYPT_LUKS2).
 */
const char *crypt_get_default_type(void);

436 437
/**
 *
438
 * Structure used as parameter for PLAIN device type.
439 440 441
 *
 * @see crypt_format
 */
442
struct crypt_params_plain {
443 444 445 446
	const char *hash;     /**< password hash function */
	uint64_t offset;      /**< offset in sectors */
	uint64_t skip;        /**< IV offset / initialization sector */
	uint64_t size;        /**< size of mapped device or @e 0 for autodetection */
447
	uint32_t sector_size; /**< sector size in bytes (@e 0 means 512 for compatibility) */
448 449
};

450
/**
451
 * Structure used as parameter for LUKS device type.
452 453 454 455 456 457 458
 *
 * @see crypt_format, crypt_load
 *
 * @note during crypt_format @e data_device attribute determines
 * 	 if the LUKS header is separated from encrypted payload device
 *
 */
459
struct crypt_params_luks1 {
460
	const char *hash;        /**< hash used in LUKS header */
461
	size_t data_alignment;   /**< data area alignment in 512B sectors, data offset is multiple of this */
462
	const char *data_device; /**< detached encrypted data device or @e NULL */
463 464
};

465 466
/**
 *
467
 * Structure used as parameter for loop-AES device type.
468 469 470 471
 *
 * @see crypt_format
 *
 */
472
struct crypt_params_loopaes {
473 474 475
	const char *hash; /**< key hash function */
	uint64_t offset;  /**< offset in sectors */
	uint64_t skip;    /**< IV offset / initialization sector */
476
};
477

478 479
/**
 *
480
 * Structure used as parameter for dm-verity device type.
481 482 483 484 485 486 487
 *
 * @see crypt_format, crypt_load
 *
 */
struct crypt_params_verity {
	const char *hash_name;     /**< hash function */
	const char *data_device;   /**< data_device (CRYPT_VERITY_CREATE_HASH) */
488
	const char *hash_device;   /**< hash_device (output only) */
489
	const char *fec_device;    /**< fec_device (output only) */
490
	const char *salt;          /**< salt */
491 492
	uint32_t salt_size;        /**< salt size (in bytes) */
	uint32_t hash_type;        /**< in-kernel hashing type */
493 494 495 496
	uint32_t data_block_size;  /**< data block size (in bytes) */
	uint32_t hash_block_size;  /**< hash block size (in bytes) */
	uint64_t data_size;        /**< data area size (in data blocks) */
	uint64_t hash_area_offset; /**< hash/header offset (in bytes) */
497
	uint64_t fec_area_offset;  /**< FEC/header offset (in bytes) */
498
	uint32_t fec_roots;        /**< Reed-Solomon FEC roots */
499 500 501
	uint32_t flags;            /**< CRYPT_VERITY* flags */
};

502 503 504 505 506 507 508
/** No on-disk header (only hashes) */
#define CRYPT_VERITY_NO_HEADER   (1 << 0)
/** Verity hash in userspace before activation */
#define CRYPT_VERITY_CHECK_HASH  (1 << 1)
/** Create hash - format hash device */
#define CRYPT_VERITY_CREATE_HASH (1 << 2)

Milan Broz's avatar
Milan Broz committed
509 510
/**
 *
511
 * Structure used as parameter for TCRYPT device type.
Milan Broz's avatar
Milan Broz committed
512
 *
513
 * @see crypt_load
Milan Broz's avatar
Milan Broz committed
514 515 516
 *
 */
struct crypt_params_tcrypt {
Milan Broz's avatar
Milan Broz committed
517
	const char *passphrase;    /**< passphrase to unlock header (input only) */
518
	size_t passphrase_size;    /**< passphrase size (input only, max length is 64) */
Milan Broz's avatar
Milan Broz committed
519 520
	const char **keyfiles;     /**< keyfile paths to unlock header (input only) */
	unsigned int keyfiles_count;/**< keyfiles count (input only) */
Milan Broz's avatar
Milan Broz committed
521
	const char *hash_name;     /**< hash function for PBKDF */
522
	const char *cipher;        /**< cipher chain c1[-c2[-c3]] */
Milan Broz's avatar
Milan Broz committed
523
	const char *mode;          /**< cipher block mode */
524
	size_t key_size;           /**< key size in bytes (the whole chain) */
Milan Broz's avatar
Milan Broz committed
525
	uint32_t flags;            /**< CRYPT_TCRYPT* flags */
526
	uint32_t veracrypt_pim;    /**< VeraCrypt Personal Iteration Multiplier */
Milan Broz's avatar
Milan Broz committed
527 528
};

529
/** Include legacy modes when scanning for header */
530 531 532 533 534 535 536
#define CRYPT_TCRYPT_LEGACY_MODES    (1 << 0)
/** Try to load hidden header (describing hidden device) */
#define CRYPT_TCRYPT_HIDDEN_HEADER   (1 << 1)
/** Try to load backup header */
#define CRYPT_TCRYPT_BACKUP_HEADER   (1 << 2)
/** Device contains encrypted system (with boot loader) */
#define CRYPT_TCRYPT_SYSTEM_HEADER   (1 << 3)
537 538 539 540
/** Include VeraCrypt modes when scanning for header,
 *  all other TCRYPT flags applies as well.
 *  VeraCrypt device is reported as TCRYPT type.
 */
541
#define CRYPT_TCRYPT_VERA_MODES      (1 << 4)
542

543 544 545 546 547 548 549 550
/**
 *
 * Structure used as parameter for dm-integrity device type.
 *
 * @see crypt_format, crypt_load
 *
 */
struct crypt_params_integrity {
551 552 553 554 555 556 557
	uint64_t journal_size;               /**< size of journal in bytes */
	unsigned int journal_watermark;      /**< journal flush watermark in percents */
	unsigned int journal_commit_time;    /**< journal commit time in ms */
	uint32_t interleave_sectors;         /**< number of interleave sectors (power of two) */
	uint32_t tag_size;                   /**< tag size per-sector in bytes */
	uint32_t sector_size;                /**< sector size in bytes */
	uint32_t buffer_sectors;             /**< number of sectors in one buffer */
Milan Broz's avatar
Milan Broz committed
558
	const char *integrity;               /**< integrity algorithm, NULL for LUKS2 */
559
	uint32_t integrity_key_size;         /**< integrity key size in bytes, info only, 0 for LUKS2 */
560 561 562

	const char *journal_integrity;       /**< journal integrity algorithm */
	const char *journal_integrity_key;   /**< journal integrity key, only for crypt_load */
563
	uint32_t journal_integrity_key_size; /**< journal integrity key size in bytes, only for crypt_load */
564 565 566

	const char *journal_crypt;           /**< journal encryption algorithm */
	const char *journal_crypt_key;       /**< journal crypt key, only for crypt_load */
567
	uint32_t journal_crypt_key_size;     /**< journal crypt key size in bytes, only for crypt_load */
568 569
};

Milan Broz's avatar
Milan Broz committed
570 571 572 573 574 575 576 577 578 579 580
/**
 * Structure used as parameter for LUKS2 device type.
 *
 * @see crypt_format, crypt_load
 *
 * @note during crypt_format @e data_device attribute determines
 * 	 if the LUKS2 header is separated from encrypted payload device
 *
 */
struct crypt_params_luks2 {
	const struct crypt_pbkdf_type *pbkdf; /**< PBKDF (and hash) parameters or @e NULL*/
581
	const char *integrity;                /**< integrity algorithm or @e NULL */
Milan Broz's avatar
Milan Broz committed
582
	const struct crypt_params_integrity *integrity_params; /**< Data integrity parameters or @e NULL*/
583
	size_t data_alignment;   /**< data area alignment in 512B sectors, data offset is multiple of this */
Milan Broz's avatar
Milan Broz committed
584
	const char *data_device; /**< detached encrypted data device or @e NULL */
585 586 587
	uint32_t sector_size;    /**< encryption sector size */
	const char *label;       /**< header label or @e NULL*/
	const char *subsystem;   /**< header subsystem label or @e NULL*/
Milan Broz's avatar
Milan Broz committed
588
};
589 590
/** @} */

591 592 593 594 595 596 597
/**
 * @defgroup crypt-actions Cryptsetup device context actions
 * Set of functions for formatting and manipulating with specific crypt_type
 * @addtogroup crypt-actions
 * @{
 */

598
/**
599
 * Create (format) new crypt device (and possible header on-disk) but do not activate it.
600
 *
601 602 603 604 605 606 607 608 609
 * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
 *
 * @param cd crypt device handle
 * @param type type of device (optional params struct must be of this type)
 * @param cipher (e.g. "aes")
 * @param cipher_mode including IV specification (e.g. "xts-plain")
 * @param uuid requested UUID or @e NULL if it should be generated
 * @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
 * @param volume_key_size size of volume key in bytes.
610
 * @param params crypt type specific parameters (see @link crypt-type @endlink)
611
 *
612
 * @returns @e 0 on success or negative errno value otherwise.
613
 *
614 615
 * @note Note that crypt_format does not create LUKS keyslot (any version). To create keyslot
 *	 call any crypt_keyslot_add_* function.
Andrea Gelmini's avatar
Andrea Gelmini committed
616
 * @note For VERITY @link crypt-type @endlink, only uuid parameter is used, other parameters
617
 * 	are ignored and verity specific attributes are set through mandatory params option.
618 619 620 621 622 623 624 625 626 627
 */
int crypt_format(struct crypt_device *cd,
	const char *type,
	const char *cipher,
	const char *cipher_mode,
	const char *uuid,
	const char *volume_key,
	size_t volume_key_size,
	void *params);

Milan Broz's avatar
Milan Broz committed
628 629 630 631 632
/**
 * Convert to new type for already existing device.
 *
 * @param cd crypt device handle
 * @param type type of device (optional params struct must be of this type)
633
 * @param params crypt type specific parameters (see @link crypt-type @endlink)
Milan Broz's avatar
Milan Broz committed
634 635 636
 *
 * @returns 0 on success or negative errno value otherwise.
 *
637 638
 * @note Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported.
 *	 Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion
Rafael Fontenelle's avatar
Rafael Fontenelle committed
639 640
 *	 possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf
 *	 type must be PBKDF2) and device cannot be formatted with any authenticated
641 642 643 644
 *	 encryption mode.
 *
 * @note Device must be offline for conversion. UUID change is not possible for active
 *	 devices.
Milan Broz's avatar
Milan Broz committed
645 646
 */
int crypt_convert(struct crypt_device *cd,
647 648
	const char *type,
	void *params);
Milan Broz's avatar
Milan Broz committed
649

650
/**
651
 * Set new UUID for already existing device.
652
 *
653 654
 * @param cd crypt device handle
 * @param uuid requested UUID or @e NULL if it should be generated
655
 *
656 657 658
 * @returns 0 on success or negative errno value otherwise.
 *
 * @note Currently, only LUKS device type are supported
659 660
 */
int crypt_set_uuid(struct crypt_device *cd,
661
	const char *uuid);
662

Milan Broz's avatar
Milan Broz committed
663 664 665 666 667 668 669 670 671 672 673 674
/**
 * Set new labels (label and subsystem) for already existing device.
 *
 * @param cd crypt device handle
 * @param label requested label or @e NULL
 * @param subsystem requested subsystem label or @e NULL
 *
 * @returns 0 on success or negative errno value otherwise.
 *
 * @note Currently, only LUKS2 device type is supported
 */
int crypt_set_label(struct crypt_device *cd,
675 676 677 678
	const char *label,
	const char *subsystem);

/**
679 680 681 682 683
 * Enable or disable loading of volume keys via kernel keyring. When set to
 * 'enabled' library loads key in kernel keyring first and pass the key
 * description to dm-crypt instead of binary key copy. If set to 'disabled'
 * library fallbacks to old method of loading volume key directly in
 * dm-crypt target.
684 685 686 687 688 689 690 691 692 693 694 695
 *
 * @param cd crypt device handle, can be @e NULL
 * @param enable 0 to disable loading of volume keys via kernel keyring
 * 	  (classical method) otherwise enable it (default)
 *
 * @returns @e 0 on success or negative errno value otherwise.
 *
 * @note Currently loading of volume keys via kernel keyring is supported
 * 	 (and enabled by default) only for LUKS2 devices.
 * @note The switch is global on the library level.
 */
int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
Milan Broz's avatar
Milan Broz committed
696

697
/**
698
 * Load crypt device parameters from on-disk header.
699
 *
700
 * @param cd crypt device handle
701 702
 * @param requested_type @link crypt-type @endlink or @e NULL for all known
 * @param params crypt type specific parameters (see @link crypt-type @endlink)
703 704 705 706 707 708
 *
 * @returns 0 on success or negative errno value otherwise.
 *
 * @post In case LUKS header is read successfully but payload device is too small
 * error is returned and device type in context is set to @e NULL
 *
709
 * @note Note that in current version load works only for LUKS and VERITY device type.
710 711 712
 *
 */
int crypt_load(struct crypt_device *cd,
713 714
	const char *requested_type,
	void *params);
715

716
/**
717
 * Try to repair crypt device LUKS on-disk header if invalid.
718 719
 *
 * @param cd crypt device handle
720 721
 * @param requested_type @link crypt-type @endlink or @e NULL for all known
 * @param params crypt type specific parameters (see @link crypt-type @endlink)
722 723 724
 *
 * @returns 0 on success or negative errno value otherwise.
 *
725 726 727 728 729
 * @note For LUKS2 device crypt_repair bypass blkid checks and
 * 	 perform auto-recovery even though there're third party device
 * 	 signatures found by blkid probes. Currently the crypt_repair on LUKS2
 * 	 works only if exactly one header checksum does not match or exactly
 * 	 one header is missing.
730 731
 */
int crypt_repair(struct crypt_device *cd,
732 733
	const char *requested_type,
	void *params);
734

735
/**
736
 * Resize crypt device.
737
 *
738 739 740
 * @param cd - crypt device handle
 * @param name - name of device to resize
 * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
741
 *
742
 * @return @e 0 on success or negative errno value otherwise.
743 744
 *
 * @note Most notably it returns -EPERM when device was activated with volume key
745 746 747 748 749 750
 * 	 in kernel keyring and current device handle (context) doesn't have verified key
 * 	 loaded in kernel. To load volume key for already active device use any of
 * 	 @link crypt_activate_by_passphrase @endlink, @link crypt_activate_by_keyfile @endlink,
 * 	 @link crypt_activate_by_keyfile_offset @endlink, @link crypt_activate_by_volume_key @endlink,
 * 	 @link crypt_activate_by_keyring @endlink or @link crypt_activate_by_token @endlink with flag
 * 	 @e CRYPT_ACTIVATE_KEYRING_KEY raised and @e name parameter set to @e NULL.
751 752
 */
int crypt_resize(struct crypt_device *cd,
753 754
	const char *name,
	uint64_t new_size);
755

756
/**
757
 * Suspend crypt device.
758
 *
759 760 761 762 763 764
 * @param cd crypt device handle, can be @e NULL
 * @param name name of device to suspend
 *
 * @return 0 on success or negative errno value otherwise.
 *
 * @note Only LUKS device type is supported
765 766 767
 *
 */
int crypt_suspend(struct crypt_device *cd,
768
	const char *name);
769 770

/**
771
 * Resume crypt device using passphrase.
772 773
 *
 *
774 775 776
 * @param cd crypt device handle
 * @param name name of device to resume
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
777
 * @param passphrase passphrase used to unlock volume key
778 779 780 781 782
 * @param passphrase_size size of @e passphrase (binary data)
 *
 * @return unlocked key slot number or negative errno otherwise.
 *
 * @note Only LUKS device type is supported
783 784
 */
int crypt_resume_by_passphrase(struct crypt_device *cd,
785 786 787 788
	const char *name,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size);
789 790

/**
791
 * Resume crypt device using key file.
792
 *
793 794 795
 * @param cd crypt device handle
 * @param name name of device to resume
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
796
 * @param keyfile key file used to unlock volume key
797
 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
798
 * @param keyfile_offset number of bytes to skip at start of keyfile
799
 *
800
 * @return unlocked key slot number or negative errno otherwise.
801
 */
802 803 804 805 806 807 808 809 810 811
int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	uint64_t keyfile_offset);

/**
 * Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
 */
812 813 814 815 816 817
int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset);
818

819
/**
820
 * Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
821
 */
822
int crypt_resume_by_keyfile(struct crypt_device *cd,
823 824 825 826
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size);
827
/** @} */
828

829
/**
830 831
 * @defgroup crypt-keyslot LUKS keyslots
 * @addtogroup crypt-keyslot
832 833 834 835 836 837
 * @{
 */

/** iterate through all keyslots and find first one that fits */
#define CRYPT_ANY_SLOT -1

838
/**
839
 * Add key slot using provided passphrase.
840
 *
841 842 843 844
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
845
 * @param passphrase passphrase used to unlock volume key
846
 * @param passphrase_size size of passphrase (binary data)
847
 * @param new_passphrase passphrase for new keyslot
848
 * @param new_passphrase_size size of @e new_passphrase (binary data)
849
 *
850
 * @return allocated key slot number or negative errno otherwise.
851 852 853 854 855 856 857 858
 */
int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size,
	const char *new_passphrase,
	size_t new_passphrase_size);

859
/**
860
 * Change defined key slot using provided passphrase.
861 862 863 864 865 866
 *
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
 * @param keyslot_new new keyslot (can be the same as old)
867
 * @param passphrase passphrase used to unlock volume key
868
 * @param passphrase_size size of passphrase (binary data)
869
 * @param new_passphrase passphrase for new keyslot
870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885
 * @param new_passphrase_size size of @e new_passphrase (binary data)
 *
 * @return allocated key slot number or negative errno otherwise.
 *
 * @note This function is just internal implementation of luksChange
 * command to avoid reading of volume key outside libcryptsetup boundary
 * in FIPS mode.
 */
int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
	int keyslot_old,
	int keyslot_new,
	const char *passphrase,
	size_t passphrase_size,
	const char *new_passphrase,
	size_t new_passphrase_size);

886
/**
887
* Add key slot using provided key file path.
888
 *
889 890 891 892
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
893
 * @param keyfile key file used to unlock volume key
894
 * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
895
 * @param keyfile_offset number of bytes to skip at start of keyfile
896
 * @param new_keyfile keyfile for new keyslot
897
 * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
898
 * @param new_keyfile_offset number of bytes to skip at start of new_keyfile
899
 *
900
 * @return allocated key slot number or negative errno otherwise.
901
 */
902 903 904 905 906 907 908 909 910 911 912 913
int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	uint64_t keyfile_offset,
	const char *new_keyfile,
	size_t new_keyfile_size,
	uint64_t new_keyfile_offset);

/**
 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
 */
914 915 916 917 918 919 920 921
int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset,
	const char *new_keyfile,
	size_t new_keyfile_size,
	size_t new_keyfile_offset);
922

923
/**
924
 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
925
 */
926 927 928 929 930 931 932 933
int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	const char *new_keyfile,
	size_t new_keyfile_size);

/**
934
 * Add key slot using provided volume key.
935
 *
936 937 938 939 940
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 * @param volume_key provided volume key or @e NULL if used after crypt_format
941
 * @param volume_key_size size of volume_key
942
 * @param passphrase passphrase for new keyslot
943
 * @param passphrase_size size of passphrase
944 945
 *
 * @return allocated key slot number or negative errno otherwise.
946 947 948 949 950 951 952 953
 */
int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
	int keyslot,
	const char *volume_key,
	size_t volume_key_size,
	const char *passphrase,
	size_t passphrase_size);

954
/** create keyslot with volume key not associated with current dm-crypt segment */
Milan Broz's avatar
Milan Broz committed
955 956
#define CRYPT_VOLUME_KEY_NO_SEGMENT (1 << 0)

957 958 959
/** create keyslot with new volume key and assign it to current dm-crypt segment */
#define CRYPT_VOLUME_KEY_SET (1 << 1)

960 961 962
/** Assign key to first matching digest before creating new digest */
#define CRYPT_VOLUME_KEY_DIGEST_REUSE (1 << 2)

Milan Broz's avatar
Milan Broz committed
963 964 965 966 967 968 969 970 971
/**
 * Add key slot using provided key.
 *
 * @pre @e cd contains initialized and formatted LUKS2 device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 * @param volume_key provided volume key or @e NULL (see note below)
 * @param volume_key_size size of volume_key
972
 * @param passphrase passphrase for new keyslot
Milan Broz's avatar
Milan Broz committed
973
 * @param passphrase_size size of passphrase
974
 * @param flags key flags to set
Milan Broz's avatar
Milan Broz committed
975 976 977 978
 *
 * @return allocated key slot number or negative errno otherwise.
 *
 * @note in case volume_key is @e NULL following first matching rule will apply:
979 980 981 982 983 984 985 986 987 988 989 990
 * @li if cd is device handle used in crypt_format() by current process, the volume
 *     key generated (or passed) in crypt_format() will be stored in keyslot.
 * @li if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be
 *     generated and stored in keyslot. The keyslot will become unbound (unusable to
 *     dm-crypt device activation).
 * @li fails with -EINVAL otherwise
 *
 * @warning CRYPT_VOLUME_KEY_SET flag force updates volume key. It is @b not @b reencryption!
 * 	    By doing so you will most probably destroy your ciphertext data device. It's supposed
 * 	    to be used only in wrapped keys scheme for key refresh process where real (inner) volume
 * 	    key stays untouched. It may be involed on active @e keyslot which makes the (previously
 * 	    unbound) keyslot new regular keyslot.
Milan Broz's avatar
Milan Broz committed
991 992 993 994 995 996 997 998 999
 */
int crypt_keyslot_add_by_key(struct crypt_device *cd,
	int keyslot,
	const char *volume_key,
	size_t volume_key_size,
	const char *passphrase,
	size_t passphrase_size,
	uint32_t flags);

1000
/**
1001
 * Destroy (and disable) key slot.
1002
 *
1003
 * @pre @e cd contains initialized and formatted LUKS device context
1004
 *
1005 1006
 * @param cd crypt device handle
 * @param keyslot requested key slot to destroy
1007
 *
1008 1009 1010
 * @return @e 0 on success or negative errno value otherwise.
 *
 * @note Note that there is no passphrase verification used.
1011 1012
 */
int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
1013 1014
/** @} */

Milan Broz's avatar
Milan Broz committed
1015
/**
1016
 * @defgroup crypt-aflags Device runtime attributes
1017
 * Activation flags
1018
 * @addtogroup crypt-aflags
1019
 * @{
1020
 */
1021

1022
/** device is read only */
1023
#define CRYPT_ACTIVATE_READONLY (1 << 0)
1024
/** only reported for device without uuid */
1025
#define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
1026
/** activate even if cannot grant exclusive access (DANGEROUS) */
1027
#define CRYPT_ACTIVATE_SHARED   (1 << 2)
1028 1029
/** enable discards aka TRIM */
#define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
1030 1031
/** skip global udev rules in activation ("private device"), input only */
#define CRYPT_ACTIVATE_PRIVATE (1 << 4)
1032 1033
/** corruption detected (verity), output only */
#define CRYPT_ACTIVATE_CORRUPTED (1 << 5)
1034 1035 1036 1037
/** use same_cpu_crypt option for dm-crypt */
#define CRYPT_ACTIVATE_SAME_CPU_CRYPT (1 << 6)
/** use submit_from_crypt_cpus for dm-crypt */
#define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (1 << 7)
1038 1039 1040 1041 1042 1043
/** dm-verity: ignore_corruption flag - ignore corruption, log it only */
#define CRYPT_ACTIVATE_IGNORE_CORRUPTION (1 << 8)
/** dm-verity: restart_on_corruption flag - restart kernel on corruption */
#define CRYPT_ACTIVATE_RESTART_ON_CORRUPTION (1 << 9)
/** dm-verity: ignore_zero_blocks - do not verify zero blocks */
#define CRYPT_ACTIVATE_IGNORE_ZERO_BLOCKS (1 << 10)
1044 1045
/** key loaded in kernel keyring instead directly in dm-crypt */
#define CRYPT_ACTIVATE_KEYRING_KEY (1 << 11)
1046 1047 1048 1049
/** dm-integrity: direct writes, do not use journal */
#define CRYPT_ACTIVATE_NO_JOURNAL (1 << 12)
/** dm-integrity: recovery mode - no journal, no integrity checks */
#define CRYPT_ACTIVATE_RECOVERY (1 << 13)
Milan Broz's avatar
Milan Broz committed
1050 1051
/** ignore persistently stored flags */
#define CRYPT_ACTIVATE_IGNORE_PERSISTENT (1 << 14)
1052 1053
/** dm-verity: check_at_most_once - check data blocks only the first time */
#define CRYPT_ACTIVATE_CHECK_AT_MOST_ONCE (1 << 15)
1054
/** allow activation check including unbound keyslots (keyslots without segments) */
1055
#define CRYPT_ACTIVATE_ALLOW_UNBOUND_KEY (1 << 16)
1056 1057
/** dm-integrity: activate automatic recalculation */
#define CRYPT_ACTIVATE_RECALCULATE (1 << 17)
1058 1059
/** reactivate existing and update flags, input only */
#define CRYPT_ACTIVATE_REFRESH	(1 << 18)
1060 1061
/** Use global lock to serialize memory hard KDF on activation (OOM workaround) */
#define CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF (1 << 19)
1062

1063 1064 1065 1066
/**
 * Active device runtime attributes
 */
struct crypt_active_device {
1067
	uint64_t offset;    /**< offset in sectors */
1068
	uint64_t iv_offset; /**< IV initialization sector */
1069 1070
	uint64_t size;      /**< active device size */
	uint32_t flags;     /**< activation flags */
1071 1072 1073
};

/**
1074
 * Receive runtime attributes of active crypt device.
1075
 *
1076 1077 1078 1079 1080
 * @param cd crypt device handle (can be @e NULL)
 * @param name name of active device
 * @param cad preallocated active device attributes to fill
 *
 * @return @e 0 on success or negative errno value otherwise
1081 1082 1083
 *
 */
int crypt_get_active_device(struct crypt_device *cd,
1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097
	const char *name,
	struct crypt_active_device *cad);

/**
 * Get detected number of integrity failures.
 *
 * @param cd crypt device handle (can be @e NULL)
 * @param name name of active device
 *
 * @return number of integrity failures or @e 0 otherwise
 *
 */
uint64_t crypt_get_active_integrity_failures(struct crypt_device *cd,
	const char *name);
1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108
/** @} */

/**
 * @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
 * @addtogroup crypt-pflags
 * @{
 */

/**
 * LUKS2 header requirements
 */
1109 1110
/** Unfinished offline reencryption */
#define CRYPT_REQUIREMENT_OFFLINE_REENCRYPT	(1 << 0)
1111 1112
/** unknown requirement in header (output only) */
#define CRYPT_REQUIREMENT_UNKNOWN		(1 << 31)
1113

Milan Broz's avatar
Milan Broz committed
1114 1115 1116 1117
/**
 * Persistent flags type
 */
typedef enum {
1118
	CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
Milan Broz's avatar
Milan Broz committed
1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137
	CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
} crypt_flags_type;

/**
 * Set persistent flags.
 *
 * @param cd crypt device handle (can be @e NULL)
 * @param type type to set (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
 * @param flags flags to set
 *
 * @return @e 0 on success or negative errno value otherwise
 *
 * @note Valid only for LUKS2.
 *
 * @note Not all activation flags can be stored. Only ALLOW_DISCARD,
 * 	 SAME_CPU_CRYPT, SUBMIT_FROM_CRYPT_CPU and NO_JOURNAL can be
 * 	 stored persistently.
 *
 * @note Only requirements flags recognised by current library may be set.
1138
 *	 CRYPT_REQUIREMENT_UNKNOWN is illegal (output only) in set operation.
Milan Broz's avatar
Milan Broz committed
1139 1140
 */
int crypt_persistent_flags_set(struct crypt_device *cd,
1141 1142
	crypt_flags_type type,
	uint32_t flags);
Milan Broz's avatar
Milan Broz committed
1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153

/**
 * Get persistent flags stored in header.
 *
 * @param cd crypt device handle (can be @e NULL)
 * @param type flags type to retrieve (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
 * @param flags reference to output variable
 *
 * @return @e 0 on success or negative errno value otherwise
 */
int crypt_persistent_flags_get(struct crypt_device *cd,
1154 1155
	crypt_flags_type type,
	uint32_t *flags);
1156 1157
/** @} */

1158 1159 1160 1161 1162 1163
/**
 * @defgroup crypt-activation Device activation
 * @addtogroup crypt-activation
 * @{
 */

1164
/**
1165
 * Activate device or check passphrase.
1166
 *
1167 1168 1169
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check passphrase
 * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
1170
 * @param passphrase passphrase used to unlock volume key
1171 1172
 * @param passphrase_size size of @e passphrase
 * @param flags activation flags
1173
 *
1174
 * @return unlocked key slot number or negative errno otherwise.
1175 1176 1177 1178 1179 1180 1181 1182 1183
 */
int crypt_activate_by_passphrase(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size,
	uint32_t flags);

/**
1184
 * Activate device or check using key file.
1185
 *
1186 1187 1188 1189
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check keyfile
 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 * @param keyfile key file used to unlock volume key
1190
 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
1191
 * @param keyfile_offset number of bytes to skip at start of keyfile
1192
 * @param flags activation flags
1193
 *
1194
 * @return unlocked key slot number or negative errno otherwise.
1195
 */
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	uint64_t keyfile_offset,
	uint32_t flags);

/**
 * Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
 */
1207 1208 1209 1210 1211 1212 1213
int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset,
	uint32_t flags);
1214

1215
/**
1216
 * Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
1217
 */
1218 1219 1220 1221 1222 1223 1224 1225
int crypt_activate_by_keyfile(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	uint32_t flags);

/**
1226
 * Activate device using provided volume key.
1227
 *
1228 1229 1230
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check volume key
 * @param volume_key provided volume key (or @e NULL to use internal)
1231
 * @param volume_key_size size of volume_key
1232 1233 1234
 * @param flags activation flags
 *
 * @return @e 0 on success or negative errno value otherwise.
1235
 *
1236
 * @note If @e NULL is used for volume_key, device has to be initialized
1237 1238
 * 	 by previous operation (like @ref crypt_format
 * 	 or @ref crypt_init_by_name)
1239 1240 1241
 * @note For VERITY the volume key means root hash required for activation.
 * 	 Because kernel dm-verity is always read only, you have to provide
 * 	 CRYPT_ACTIVATE_READONLY flag always.
Milan Broz's avatar
Milan Broz committed
1242 1243
 * @note For TCRYPT the volume key should be always NULL and because master
 * 	 key from decrypted header is used instead.
1244 1245 1246 1247 1248 1249 1250
 */
int crypt_activate_by_volume_key(struct crypt_device *cd,
	const char *name,
	const char *volume_key,
	size_t volume_key_size,
	uint32_t flags);

1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267
/**
 * Activate device using passphrase stored in kernel keyring.
 *
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check passphrase in keyring
 * @param key_description kernel keyring key description library should look
 *        for passphrase in
 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 * @param flags activation flags
 *
 * @return @e unlocked keyslot number on success or negative errno value otherwise.
 *
 * @note Keyslot passphrase must be stored in 'user' key type
 * 	 and the key has to be reachable for process context
 * 	 on behalf of which this function is called.
 */
int crypt_activate_by_keyring(struct crypt_device *cd,
1268 1269 1270 1271 1272 1273 1274 1275 1276
	const char *name,
	const char *key_description,
	int keyslot,
	uint32_t flags);

/** lazy deactivation - remove once last user releases it */
#define CRYPT_DEACTIVATE_DEFERRED (1 << 0)
/** force deactivation - if the device is busy, it is replaced by error device */
#define CRYPT_DEACTIVATE_FORCE    (1 << 1)
1277

1278
/**
1279 1280 1281
 * Deactivate crypt device. This function tries to remove active device-mapper
 * mapping from kernel. Also, sensitive data like the volume key are removed from
 * memory
1282
 *
1283 1284
 * @param cd crypt device handle, can be @e NULL
 * @param name name of device to deactivate
1285
 * @param flags deactivation flags
1286 1287 1288 1289
 *
 * @return @e 0 on success or negative errno value otherwise.
 *
 */
1290 1291 1292 1293 1294 1295 1296
int crypt_deactivate_by_name(struct crypt_device *cd,
	const char *name,
	uint32_t flags);

/**
 * Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
 */
1297
int crypt_deactivate(struct crypt_device *cd, const char *name);
1298 1299 1300 1301 1302 1303 1304
/** @} */

/**
 * @defgroup crypt-key Volume Key manipulation
 * @addtogroup crypt-key
 * @{
 */
1305 1306

/**
1307
 * Get volume key from crypt device.
1308
 *
1309 1310 1311 1312 1313 1314 1315
 * @param cd crypt device handle
 * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
 * @param volume_key buffer for volume key
 * @param volume_key_size on input, size of buffer @e volume_key,
 *        on output size of @e volume_key
 * @param passphrase passphrase used to unlock volume key
 * @param passphrase_size size of @e passphrase
1316
 *
1317
 * @return unlocked key slot number or negative errno otherwise.
Milan Broz's avatar
Milan Broz committed
1318
 *
1319
 * @note For TCRYPT cipher chain is the volume key concatenated
Milan Broz's avatar
Milan Broz committed
1320
 * 	 for all ciphers in chain.
1321 1322 1323 1324 1325 1326 1327 1328 1329
 */
int crypt_volume_key_get(struct crypt_device *cd,
	int keyslot,
	char *volume_key,
	size_t *volume_key_size,
	const char *passphrase,
	size_t passphrase_size);

/**
1330
 * Verify that provided volume key is valid for crypt device.
1331
 *
1332 1333 1334
 * @param cd crypt device handle
 * @param volume_key provided volume key
 * @param volume_key_size size of @e volume_key
1335
 *
1336
 * @return @e 0 on success or negative errno value otherwise.
1337 1338 1339 1340
 */
int crypt_volume_key_verify(struct crypt_device *cd,
	const char *volume_key,
	size_t volume_key_size);
1341
/** @} */
1342

1343
/**
1344 1345
 * @defgroup crypt-devstat Crypt and Verity device status
 * @addtogroup crypt-devstat
1346 1347 1348
 * @{
 */

1349 1350 1351
/**
 * Device status
 */
1352
typedef enum {
1353
	CRYPT_INVALID,  /**< device mapping is invalid in this context */
1354
	CRYPT_INACTIVE, /**< no such mapped device */
1355 1356
	CRYPT_ACTIVE,   /**< device is active */
	CRYPT_BUSY      /**< device is active and has open count > 0 */
1357 1358
} crypt_status_info;

1359
/**
1360
 * Get status info about device name.
1361
 *
1362 1363
 * @param cd crypt device handle, can be @e NULL
 * @param name crypt device name
1364
 *
1365
 * @return value defined by crypt_status_info.
1366 1367 1368 1369 1370
 *
 */
crypt_status_info crypt_status(struct crypt_device *cd, const char *name);

/**
1371
 * Dump text-formatted information about crypt or verity device to log output.
1372
 *
1373
 * @param cd crypt device handle
1374
 *
1375
 * @return @e 0 on success or negative errno value otherwise.
1376 1377 1378 1379
 */
int crypt_dump(struct crypt_device *cd);

/**
1380
 * Get cipher used in device.
1381
 *
1382 1383 1384
 * @param cd crypt device handle
 *
 * @return used cipher, e.g. "aes" or @e NULL otherwise
1385 1386 1387
 *
 */
const char *crypt_get_cipher(struct crypt_device *cd);
1388 1389

/**
1390
 * Get cipher mode used in device.
1391 1392 1393 1394 1395 1396
 *
 * @param cd crypt device handle
 *
 * @return used cipher mode e.g. "xts-plain" or @e otherwise
 *
 */
1397
const char *crypt_get_cipher_mode(struct crypt_device *cd);
1398 1399

/**
1400
 * Get device UUID.
1401 1402 1403 1404 1405 1406
 *
 * @param cd crypt device handle
 *
 * @return device UUID or @e NULL if not set
 *
 */
1407
const char *crypt_get_uuid(struct crypt_device *cd);
1408 1409

/**
1410
 * Get path to underlaying device.
1411 1412 1413 1414 1415 1416
 *
 * @param cd crypt device handle
 *
 * @return path to underlaying device name
 *
 */
1417
const char *crypt_get_device_name(struct crypt_device *cd);
1418

1419 1420 1421 1422 1423 1424 1425 1426 1427 1428
/**
 * Get path to detached metadata device or @e NULL if it is not detached.
 *
 * @param cd crypt device handle
 *
 * @return path to underlaying device name
 *
 */
const char *crypt_get_metadata_device_name(struct crypt_device *cd);

1429
/**
1430
 * Get device offset in 512-bytes sectors where real data starts (on underlying device).
1431 1432 1433 1434 1435 1436
 *
 * @param cd crypt device handle
 *
 * @return device offset in sectors
 *
 */