2 * libcryptsetup - cryptsetup library
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
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.
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.
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.
25 * @file libcryptsetup.h
26 * @brief Public cryptsetup API
28 * For more verbose examples of LUKS related use cases,
29 * please read @ref index "examples".
32 #ifndef _LIBCRYPTSETUP_H
33 #define _LIBCRYPTSETUP_H
42 * @defgroup crypt-init Cryptsetup device context initialization
43 * Set of functions for creating and destroying @e crypt_device context
44 * @addtogroup crypt-init
48 struct crypt_device; /* crypt device handle */
51 * Initialize crypt device handle and check if the provided device exists.
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.
60 * @return @e 0 on success or negative errno value otherwise.
62 * @note Note that logging is not initialized here, possible messages use
63 * default log function.
65 int crypt_init(struct crypt_device **cd, const char *device);
68 * Initialize crypt device handle with optional data device and check
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.
75 * @return @e 0 on success or negative errno value otherwise.
77 * @note Note that logging is not initialized here, possible messages use
78 * default log function.
80 int crypt_init_data_device(struct crypt_device **cd,
82 const char *data_device);
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.
89 * @return @e 0 on success or negative errno value otherwise.
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)
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
100 * @note @link crypt_init_by_name @endlink is equivalent to calling
101 * crypt_init_by_name_and_header(cd, name, NULL);
103 int crypt_init_by_name_and_header(struct crypt_device **cd,
105 const char *header_device);
108 * This is equivalent to call
109 * @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
111 * @sa crypt_init_by_name_and_header
113 int crypt_init_by_name(struct crypt_device **cd, const char *name);
116 * Release crypt device context and used memory.
118 * @param cd crypt device handle
120 void crypt_free(struct crypt_device *cd);
123 * Set confirmation callback (yes/no).
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.
128 * Callback function @e confirm should return @e 0 if operation is declined,
129 * other values mean accepted.
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
136 * @note Current version of cryptsetup API requires confirmation for UUID change and
137 * LUKS header restore only.
139 void crypt_set_confirm_callback(struct crypt_device *cd,
140 int (*confirm)(const char *msg, void *usrptr),
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.
148 * @param cd crypt device handle
149 * @param device path to device
151 * @returns 0 on success or negative errno value otherwise.
153 int crypt_set_data_device(struct crypt_device *cd, const char *device);
156 * Set data device offset in 512-byte sectors.
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.
162 * @param cd crypt device handle
163 * @param data_offset data offset in bytes
165 * @returns 0 on success or negative errno value otherwise.
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.
172 int crypt_set_data_offset(struct crypt_device *cd, uint64_t data_offset);
177 * @defgroup crypt-log Cryptsetup logging
178 * Set of functions and defines used in cryptsetup for
180 * @addtogroup crypt-log
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
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
204 void crypt_set_log_callback(struct crypt_device *cd,
205 void (*log)(int level, const char *msg, void *usrptr),
209 * Defines log function or use the default one otherwise.
211 * @see crypt_set_log_callback
213 * @param cd crypt device handle
214 * @param level log level
215 * @param msg log message
217 void crypt_log(struct crypt_device *cd, int level, const char *msg);
221 * @defgroup crypt-set Cryptsetup settings (RNG, PBKDF, locking)
222 * @addtogroup crypt-set
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
232 * Set which RNG (random number generator) is used for generating long term key
234 * @param cd crypt device handle
235 * @param rng_type kernel random number generator to use
238 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.
243 * @param cd crypt device handle
244 * @return RNG type on success or negative errno value otherwise.
247 int crypt_get_rng_type(struct crypt_device *cd);
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 */
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)
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"
275 * Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot
276 * about to get created with any crypt_keyslot_add_*() call.
278 * @param cd crypt device handle
279 * @param pbkdf PBKDF parameters
281 * @return 0 on success or negative errno value otherwise.
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.
286 int crypt_set_pbkdf_type(struct crypt_device *cd,
287 const struct crypt_pbkdf_type *pbkdf);
290 * Get PBKDF (Password-Based Key Derivation Algorithm) parameters.
292 * @param pbkdf_type type of PBKDF
294 * @return struct on success or NULL value otherwise.
297 const struct crypt_pbkdf_type *crypt_get_pbkdf_type_params(const char *pbkdf_type);
300 * Get default PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
301 * Works only with LUKS device handles (both versions).
303 * @param type type of device (see @link crypt-type @endlink)
305 * @return struct on success or NULL value otherwise.
308 const struct crypt_pbkdf_type *crypt_get_pbkdf_default(const char *type);
311 * Get current PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
312 * Works only with LUKS device handles (both versions).
314 * @param cd crypt device handle
316 * @return struct on success or NULL value otherwise.
319 const struct crypt_pbkdf_type *crypt_get_pbkdf_type(struct crypt_device *cd);
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.
327 * @param cd crypt device handle
328 * @param iteration_time_ms the time in ms
330 * @note If the time value is not acceptable for active PBKDF, value is quietly ignored.
332 void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);
335 * Helper to lock/unlock memory to avoid swap sensitive data to disk.
337 * @param cd crypt device handle, can be @e NULL
338 * @param lock 0 to unlock otherwise lock memory
340 * @returns Value indicating whether the memory is locked (function can be called multiple times).
342 * @note Only root can do this.
343 * @note It locks/unlocks all process memory, not only crypt context.
345 int crypt_memory_lock(struct crypt_device *cd, int lock);
348 * Set global lock protection for on-disk metadata (file-based locking).
350 * @param cd crypt device handle, can be @e NULL
351 * @param enable 0 to disable locking otherwise enable it (default)
353 * @returns @e 0 on success or negative errno value otherwise.
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.
359 int crypt_metadata_locking(struct crypt_device *cd, int enable);
362 * Set metadata header area sizes. This applies only to LUKS2.
363 * These values limit amount of metadata anf number of supportable keyslots.
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
369 * @returns @e 0 on success or negative errno value otherwise.
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.
375 int crypt_set_metadata_size(struct crypt_device *cd,
376 uint64_t metadata_size,
377 uint64_t keyslots_size);
380 * Get metadata header area sizes. This applies only to LUKS2.
381 * These values limit amount of metadata anf number of supportable keyslots.
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
387 * @returns @e 0 on success or negative errno value otherwise.
389 int crypt_get_metadata_size(struct crypt_device *cd,
390 uint64_t *metadata_size,
391 uint64_t *keyslots_size);
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
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"
420 /** LUKS any version */
421 #define CRYPT_LUKS NULL
426 * @param cd crypt device handle
427 * @return string according to device type or @e NULL if not known.
429 const char *crypt_get_type(struct crypt_device *cd);
432 * Get device default LUKS type
434 * @return string according to device type (CRYPT_LUKS1 or CRYPT_LUKS2).
436 const char *crypt_get_default_type(void);
440 * Structure used as parameter for PLAIN device type.
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) */
453 * Structure used as parameter for LUKS device type.
455 * @see crypt_format, crypt_load
457 * @note during crypt_format @e data_device attribute determines
458 * if the LUKS header is separated from encrypted payload device
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 */
469 * Structure used as parameter for loop-AES device type.
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 */
482 * Structure used as parameter for dm-verity device type.
484 * @see crypt_format, crypt_load
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 */
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)
515 * Structure used as parameter for TCRYPT device type.
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 */
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.
545 #define CRYPT_TCRYPT_VERA_MODES (1 << 4)
549 * Structure used as parameter for dm-integrity device type.
551 * @see crypt_format, crypt_load
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.
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 */
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 */
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 */
579 * Structure used as parameter for LUKS2 device type.
581 * @see crypt_format, crypt_load
583 * @note during crypt_format @e data_device attribute determines
584 * if the LUKS2 header is separated from encrypted payload device
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*/
600 * @defgroup crypt-actions Cryptsetup device context actions
601 * Set of functions for formatting and manipulating with specific crypt_type
602 * @addtogroup crypt-actions
607 * Create (format) new crypt device (and possible header on-disk) but do not activate it.
609 * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
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)
620 * @returns @e 0 on success or negative errno value otherwise.
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.
627 int crypt_format(struct crypt_device *cd,
630 const char *cipher_mode,
632 const char *volume_key,
633 size_t volume_key_size,
637 * Set format compatibility flags.
639 * @param cd crypt device handle
640 * @param flags CRYPT_COMPATIBILITY_* flags
642 void crypt_set_compatibility(struct crypt_device *cd, uint32_t flags);
645 * Get compatibility flags.
647 * @param cd crypt device handle
649 * @returns compatibility flags
651 uint32_t crypt_get_compatibility(struct crypt_device *cd);
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)
661 * Convert to new type for already existing device.
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)
667 * @returns 0 on success or negative errno value otherwise.
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
675 * @note Device must be offline for conversion. UUID change is not possible for active
678 int crypt_convert(struct crypt_device *cd,
683 * Set new UUID for already existing device.
685 * @param cd crypt device handle
686 * @param uuid requested UUID or @e NULL if it should be generated
688 * @returns 0 on success or negative errno value otherwise.
690 * @note Currently, only LUKS device type are supported
692 int crypt_set_uuid(struct crypt_device *cd,
696 * Set new labels (label and subsystem) for already existing device.
698 * @param cd crypt device handle
699 * @param label requested label or @e NULL
700 * @param subsystem requested subsystem label or @e NULL
702 * @returns 0 on success or negative errno value otherwise.
704 * @note Currently, only LUKS2 device type is supported
706 int crypt_set_label(struct crypt_device *cd,
708 const char *subsystem);
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
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)
721 * @returns @e 0 on success or negative errno value otherwise.
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.
727 int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
730 * Load crypt device parameters from on-disk header.
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)
736 * @returns 0 on success or negative errno value otherwise.
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
741 * @note Note that in current version load works only for LUKS and VERITY device type.
744 int crypt_load(struct crypt_device *cd,
745 const char *requested_type,
749 * Try to repair crypt device LUKS on-disk header if invalid.
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)
755 * @returns 0 on success or negative errno value otherwise.
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.
763 int crypt_repair(struct crypt_device *cd,
764 const char *requested_type,
768 * Resize crypt device.
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
774 * @return @e 0 on success or negative errno value otherwise.
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.
784 int crypt_resize(struct crypt_device *cd,
789 * Suspend crypt device.
791 * @param cd crypt device handle, can be @e NULL
792 * @param name name of device to suspend
794 * @return 0 on success or negative errno value otherwise.
796 * @note Only LUKS device type is supported
799 int crypt_suspend(struct crypt_device *cd,
803 * Resume crypt device using passphrase.
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)
812 * @return unlocked key slot number or negative errno otherwise.
814 * @note Only LUKS device type is supported
816 int crypt_resume_by_passphrase(struct crypt_device *cd,
819 const char *passphrase,
820 size_t passphrase_size);
823 * Resume crypt device using key file.
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
832 * @return unlocked key slot number or negative errno otherwise.
834 int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
839 uint64_t keyfile_offset);
842 * Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
844 int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
849 size_t keyfile_offset);
852 * Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
854 int crypt_resume_by_keyfile(struct crypt_device *cd,
858 size_t keyfile_size);
860 * Resume crypt device using provided volume key.
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
867 * @return @e 0 on success or negative errno value otherwise.
869 int crypt_resume_by_volume_key(struct crypt_device *cd,
871 const char *volume_key,
872 size_t volume_key_size);
876 * @defgroup crypt-keyslot LUKS keyslots
877 * @addtogroup crypt-keyslot
881 /** iterate through all keyslots and find first one that fits */
882 #define CRYPT_ANY_SLOT -1
885 * Add key slot using provided passphrase.
887 * @pre @e cd contains initialized and formatted LUKS device context
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)
896 * @return allocated key slot number or negative errno otherwise.
898 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
900 const char *passphrase,
901 size_t passphrase_size,
902 const char *new_passphrase,
903 size_t new_passphrase_size);
906 * Change defined key slot using provided passphrase.
908 * @pre @e cd contains initialized and formatted LUKS device context
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)
918 * @return allocated key slot number or negative errno otherwise.
920 int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
923 const char *passphrase,
924 size_t passphrase_size,
925 const char *new_passphrase,
926 size_t new_passphrase_size);
929 * Add key slot using provided key file path.
931 * @pre @e cd contains initialized and formatted LUKS device context
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
942 * @return allocated key slot number or negative errno otherwise.
944 int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
948 uint64_t keyfile_offset,
949 const char *new_keyfile,
950 size_t new_keyfile_size,
951 uint64_t new_keyfile_offset);
954 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
956 int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
960 size_t keyfile_offset,
961 const char *new_keyfile,
962 size_t new_keyfile_size,
963 size_t new_keyfile_offset);
966 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
968 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
972 const char *new_keyfile,
973 size_t new_keyfile_size);
976 * Add key slot using provided volume key.
978 * @pre @e cd contains initialized and formatted LUKS device context
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
987 * @return allocated key slot number or negative errno otherwise.
989 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
991 const char *volume_key,
992 size_t volume_key_size,
993 const char *passphrase,
994 size_t passphrase_size);
996 /** create keyslot with volume key not associated with current dm-crypt segment */
997 #define CRYPT_VOLUME_KEY_NO_SEGMENT (1 << 0)
999 /** create keyslot with new volume key and assign it to current dm-crypt segment */
1000 #define CRYPT_VOLUME_KEY_SET (1 << 1)
1002 /** Assign key to first matching digest before creating new digest */
1003 #define CRYPT_VOLUME_KEY_DIGEST_REUSE (1 << 2)
1006 * Add key slot using provided key.
1008 * @pre @e cd contains initialized and formatted LUKS2 device context
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
1018 * @return allocated key slot number or negative errno otherwise.
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
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.
1034 int crypt_keyslot_add_by_key(struct crypt_device *cd,
1036 const char *volume_key,
1037 size_t volume_key_size,
1038 const char *passphrase,
1039 size_t passphrase_size,
1043 * Destroy (and disable) key slot.
1045 * @pre @e cd contains initialized and formatted LUKS device context
1047 * @param cd crypt device handle
1048 * @param keyslot requested key slot to destroy
1050 * @return @e 0 on success or negative errno value otherwise.
1052 * @note Note that there is no passphrase verification used.
1054 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
1058 * @defgroup crypt-aflags Device runtime attributes
1060 * @addtogroup crypt-aflags
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)
1118 * Active device runtime attributes
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 */
1128 * Receive runtime attributes of active crypt device.
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
1134 * @return @e 0 on success or negative errno value otherwise
1137 int crypt_get_active_device(struct crypt_device *cd,
1139 struct crypt_active_device *cad);
1142 * Get detected number of integrity failures.
1144 * @param cd crypt device handle (can be @e NULL)
1145 * @param name name of active device
1147 * @return number of integrity failures or @e 0 otherwise
1150 uint64_t crypt_get_active_integrity_failures(struct crypt_device *cd,
1155 * @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
1156 * @addtogroup crypt-pflags
1161 * LUKS2 header requirements
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)
1171 * Persistent flags type
1174 CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
1175 CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
1179 * Set persistent flags.
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
1185 * @return @e 0 on success or negative errno value otherwise
1187 * @note Valid only for LUKS2.
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.
1193 * @note Only requirements flags recognised by current library may be set.
1194 * CRYPT_REQUIREMENT_UNKNOWN is illegal (output only) in set operation.
1196 int crypt_persistent_flags_set(struct crypt_device *cd,
1197 crypt_flags_type type,
1201 * Get persistent flags stored in header.
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
1207 * @return @e 0 on success or negative errno value otherwise
1209 int crypt_persistent_flags_get(struct crypt_device *cd,
1210 crypt_flags_type type,
1215 * @defgroup crypt-activation Device activation
1216 * @addtogroup crypt-activation
1221 * Activate device or check passphrase.
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
1230 * @return unlocked key slot number or negative errno otherwise.
1232 int crypt_activate_by_passphrase(struct crypt_device *cd,
1235 const char *passphrase,
1236 size_t passphrase_size,
1240 * Activate device or check using key file.
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
1250 * @return unlocked key slot number or negative errno otherwise.
1252 int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
1255 const char *keyfile,
1256 size_t keyfile_size,
1257 uint64_t keyfile_offset,
1261 * Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
1263 int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
1266 const char *keyfile,
1267 size_t keyfile_size,
1268 size_t keyfile_offset,
1272 * Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
1274 int crypt_activate_by_keyfile(struct crypt_device *cd,
1277 const char *keyfile,
1278 size_t keyfile_size,
1282 * Activate device using provided volume key.
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
1290 * @return @e 0 on success or negative errno value otherwise.
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.
1301 int crypt_activate_by_volume_key(struct crypt_device *cd,
1303 const char *volume_key,
1304 size_t volume_key_size,
1308 * Activate VERITY device using provided key and optional signature).
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
1318 * @return @e 0 on success or negative errno value otherwise.
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.
1324 int crypt_activate_by_signed_key(struct crypt_device *cd,
1326 const char *volume_key,
1327 size_t volume_key_size,
1328 const char *signature,
1329 size_t signature_size,
1333 * Activate device using passphrase stored in kernel keyring.
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
1339 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1340 * @param flags activation flags
1342 * @return @e unlocked keyslot number on success or negative errno value otherwise.
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.
1348 int crypt_activate_by_keyring(struct crypt_device *cd,
1350 const char *key_description,
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)
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
1364 * @param cd crypt device handle, can be @e NULL
1365 * @param name name of device to deactivate
1366 * @param flags deactivation flags
1368 * @return @e 0 on success or negative errno value otherwise.
1371 int crypt_deactivate_by_name(struct crypt_device *cd,
1376 * Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
1378 int crypt_deactivate(struct crypt_device *cd, const char *name);
1382 * @defgroup crypt-key Volume Key manipulation
1383 * @addtogroup crypt-key
1388 * Get volume key from crypt device.
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
1398 * @return unlocked key slot number or negative errno otherwise.
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.
1404 int crypt_volume_key_get(struct crypt_device *cd,
1407 size_t *volume_key_size,
1408 const char *passphrase,
1409 size_t passphrase_size);
1412 * Verify that provided volume key is valid for crypt device.
1414 * @param cd crypt device handle
1415 * @param volume_key provided volume key
1416 * @param volume_key_size size of @e volume_key
1418 * @return @e 0 on success or negative errno value otherwise.
1420 int crypt_volume_key_verify(struct crypt_device *cd,
1421 const char *volume_key,
1422 size_t volume_key_size);
1426 * @defgroup crypt-devstat Crypt and Verity device status
1427 * @addtogroup crypt-devstat
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;
1442 * Get status info about device name.
1444 * @param cd crypt device handle, can be @e NULL
1445 * @param name crypt device name
1447 * @return value defined by crypt_status_info.
1450 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
1453 * Dump text-formatted information about crypt or verity device to log output.
1455 * @param cd crypt device handle
1457 * @return @e 0 on success or negative errno value otherwise.
1459 int crypt_dump(struct crypt_device *cd);
1462 * Get cipher used in device.
1464 * @param cd crypt device handle
1466 * @return used cipher, e.g. "aes" or @e NULL otherwise
1469 const char *crypt_get_cipher(struct crypt_device *cd);
1472 * Get cipher mode used in device.
1474 * @param cd crypt device handle
1476 * @return used cipher mode e.g. "xts-plain" or @e otherwise
1479 const char *crypt_get_cipher_mode(struct crypt_device *cd);
1484 * @param cd crypt device handle
1486 * @return device UUID or @e NULL if not set
1489 const char *crypt_get_uuid(struct crypt_device *cd);
1492 * Get path to underlying device.
1494 * @param cd crypt device handle
1496 * @return path to underlying device name
1499 const char *crypt_get_device_name(struct crypt_device *cd);
1502 * Get path to detached metadata device or @e NULL if it is not detached.
1504 * @param cd crypt device handle
1506 * @return path to underlying device name
1509 const char *crypt_get_metadata_device_name(struct crypt_device *cd);
1512 * Get device offset in 512-bytes sectors where real data starts (on underlying device).
1514 * @param cd crypt device handle
1516 * @return device offset in sectors
1519 uint64_t crypt_get_data_offset(struct crypt_device *cd);
1522 * Get IV offset in 512-bytes sectors (skip).
1524 * @param cd crypt device handle
1529 uint64_t crypt_get_iv_offset(struct crypt_device *cd);
1532 * Get size (in bytes) of volume key for crypt device.
1534 * @param cd crypt device handle
1536 * @return volume key size
1538 * @note For LUKS2, this function can be used only if there is at least
1539 * one keyslot assigned to data segment.
1541 int crypt_get_volume_key_size(struct crypt_device *cd);
1544 * Get size (in bytes) of encryption sector for crypt device.
1546 * @param cd crypt device handle
1548 * @return sector size
1551 int crypt_get_sector_size(struct crypt_device *cd);
1554 * Get device parameters for VERITY device.
1556 * @param cd crypt device handle
1557 * @param vp verity device info
1559 * @e 0 on success or negative errno value otherwise.
1562 int crypt_get_verity_info(struct crypt_device *cd,
1563 struct crypt_params_verity *vp);
1566 * Get device parameters for INTEGRITY device.
1568 * @param cd crypt device handle
1569 * @param ip verity device info
1571 * @e 0 on success or negative errno value otherwise.
1574 int crypt_get_integrity_info(struct crypt_device *cd,
1575 struct crypt_params_integrity *ip);
1579 * @defgroup crypt-benchmark Benchmarking
1580 * Benchmarking of algorithms
1581 * @addtogroup crypt-benchmark
1586 * Informational benchmark for ciphers.
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
1597 * @return @e 0 on success or negative errno value otherwise.
1599 * @note If encryption_buffer_size is too small and encryption time
1600 * cannot be properly measured, -ERANGE is returned.
1602 int crypt_benchmark(struct crypt_device *cd,
1604 const char *cipher_mode,
1605 size_t volume_key_size,
1608 double *encryption_mbs,
1609 double *decryption_mbs);
1612 * Informational benchmark for PBKDF.
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
1624 * @return @e 0 on success or negative errno value otherwise.
1626 int crypt_benchmark_pbkdf(struct crypt_device *cd,
1627 struct crypt_pbkdf_type *pbkdf,
1628 const char *password,
1629 size_t password_size,
1632 size_t volume_key_size,
1633 int (*progress)(uint32_t time_ms, void *usrptr),
1638 * @addtogroup crypt-keyslot
1643 * Crypt keyslot info
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;
1656 * Get information about particular key slot.
1658 * @param cd crypt device handle
1659 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1661 * @return value defined by crypt_keyslot_info
1664 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
1667 * Crypt keyslot priority
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;
1677 * Get keyslot priority (LUKS2)
1679 * @param cd crypt device handle
1680 * @param keyslot keyslot number
1682 * @return value defined by crypt_keyslot_priority
1684 crypt_keyslot_priority crypt_keyslot_get_priority(struct crypt_device *cd, int keyslot);
1687 * Set keyslot priority (LUKS2)
1689 * @param cd crypt device handle
1690 * @param keyslot keyslot number
1691 * @param priority priority defined in crypt_keyslot_priority
1693 * @return @e 0 on success or negative errno value otherwise.
1695 int crypt_keyslot_set_priority(struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority);
1698 * Get number of keyslots supported for device type.
1700 * @param type crypt device type
1702 * @return slot count or negative errno otherwise if device
1703 * doesn't not support keyslots.
1705 int crypt_keyslot_max(const char *type);
1708 * Get keyslot area pointers (relative to metadata device).
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)
1715 * @return @e 0 on success or negative errno value otherwise.
1718 int crypt_keyslot_area(struct crypt_device *cd,
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
1727 * @param cd crypt device handle
1728 * @param keyslot keyslot number
1730 * @return volume key size or negative errno value otherwise.
1733 int crypt_keyslot_get_key_size(struct crypt_device *cd, int keyslot);
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.
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)
1744 * @return cipher specification on success or @e NULL.
1746 * @note This is the encryption of keyslot itself, not the data encryption algorithm!
1748 const char *crypt_keyslot_get_encryption(struct crypt_device *cd, int keyslot, size_t *key_size);
1751 * Get PBKDF parameters for keyslot.
1753 * @param cd crypt device handle
1754 * @param keyslot keyslot number
1755 * @param pbkdf struct with returned PBKDF parameters
1757 * @return @e 0 on success or negative errno value otherwise.
1759 int crypt_keyslot_get_pbkdf(struct crypt_device *cd, int keyslot, struct crypt_pbkdf_type *pbkdf);
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.
1766 * @param cd crypt device handle
1767 * @param cipher (e.g. "aes-xts-plain64")
1768 * @param key_size encryption key size (in bytes)
1770 * @return @e 0 on success or negative errno value otherwise.
1772 * @note To reset to default keyslot encryption (the same as for data)
1773 * set cipher to NULL and key size to 0.
1775 int crypt_keyslot_set_encryption(struct crypt_device *cd,
1780 * Get directory where mapped crypt devices are created
1782 * @return the directory path
1784 const char *crypt_get_dir(void);
1789 * @defgroup crypt-backup Device metadata backup
1790 * @addtogroup crypt-backup
1794 * Backup header and keyslots to file.
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
1800 * @return @e 0 on success or negative errno value otherwise.
1803 int crypt_header_backup(struct crypt_device *cd,
1804 const char *requested_type,
1805 const char *backup_file);
1808 * Restore header and keyslots from backup file.
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
1814 * @return @e 0 on success or negative errno value otherwise.
1817 int crypt_header_restore(struct crypt_device *cd,
1818 const char *requested_type,
1819 const char *backup_file);
1823 * @defgroup crypt-dbg Library debug level
1824 * Set library debug level
1825 * @addtogroup crypt-dbg
1830 #define CRYPT_DEBUG_ALL -1
1831 /** Debug all with additional JSON dump (for LUKS2) */
1832 #define CRYPT_DEBUG_JSON -2
1834 #define CRYPT_DEBUG_NONE 0
1837 * Set the debug level for library
1839 * @param level debug level
1842 void crypt_set_debug_level(int level);
1846 * @defgroup crypt-keyfile Function to read keyfile
1847 * @addtogroup crypt-keyfile
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
1862 * @return @e 0 on success or negative errno value otherwise.
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.
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,
1875 * Backward compatible crypt_keyfile_device_read() (with size_t offset).
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,
1884 /** Read key only to the first end of line (\\n). */
1885 #define CRYPT_KEYFILE_STOP_EOL (1 << 0)
1889 * @defgroup crypt-wipe Function to wipe device
1890 * @addtogroup crypt-wipe
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;
1904 * Wipe/Fill (part of) a device with the selected pattern.
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
1916 * @return @e 0 on success or negative errno value otherwise.
1918 * @note A @e progress callback can interrupt wipe process by returning non-zero code.
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.
1923 int crypt_wipe(struct crypt_device *cd,
1924 const char *dev_path, /* if null, use data device */
1925 crypt_wipe_pattern pattern,
1928 size_t wipe_block_size,
1930 int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
1934 /** Use direct-io */
1935 #define CRYPT_WIPE_NO_DIRECT_IO (1 << 0)
1939 * @defgroup crypt-tokens LUKS2 token wrapper access
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.
1946 * @addtogroup crypt-tokens
1950 /** Iterate through all tokens */
1951 #define CRYPT_ANY_TOKEN -1
1954 * Get content of a token definition in JSON format.
1956 * @param cd crypt device handle
1957 * @param token token id
1958 * @param json buffer with JSON
1960 * @return allocated token id or negative errno otherwise.
1962 int crypt_token_json_get(struct crypt_device *cd,
1967 * Store content of a token definition in JSON format.
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
1973 * @return allocated token id or negative errno otherwise.
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.
1979 int crypt_token_json_set(struct crypt_device *cd,
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 */
1996 * Get info for specific token.
1998 * @param cd crypt device handle
1999 * @param token existing token id
2000 * @param type pointer for returned type string
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.
2006 * @note if required, create a copy of string referenced in *type before calling next
2007 * libcryptsetup API function. The reference may become invalid.
2009 crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
2012 * LUKS2 keyring token parameters.
2014 * @see crypt_token_builtin_set
2017 struct crypt_token_params_luks2_keyring {
2018 const char *key_description; /**< Reference in keyring */
2022 * Create a new luks2 keyring token.
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
2028 * @return allocated token id or negative errno otherwise.
2031 int crypt_token_luks2_keyring_set(struct crypt_device *cd,
2033 const struct crypt_token_params_luks2_keyring *params);
2036 * Get LUKS2 keyring token params
2038 * @param cd crypt device handle
2039 * @param token existing luks2 keyring token id
2040 * @param params returned luks2 keyring token params
2042 * @return allocated token id or negative errno otherwise.
2044 * @note do not call free() on params members. Members are valid only
2045 * until next libcryptsetup function is called.
2047 int crypt_token_luks2_keyring_get(struct crypt_device *cd,
2049 struct crypt_token_params_luks2_keyring *params);
2052 * Assign a token to particular keyslot.
2053 * (There can be more keyslots assigned to one token id.)
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)
2060 * @return allocated token id or negative errno otherwise.
2062 int crypt_token_assign_keyslot(struct crypt_device *cd,
2067 * Unassign a token from particular keyslot.
2068 * (There can be more keyslots assigned to one token id.)
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)
2075 * @return allocated token id or negative errno otherwise.
2077 int crypt_token_unassign_keyslot(struct crypt_device *cd,
2082 * Get info about token assignment to particular keyslot.
2084 * @param cd crypt device handle
2085 * @param token token id
2086 * @param keyslot keyslot
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.
2092 int crypt_token_is_assigned(struct crypt_device *cd,
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.
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
2108 typedef int (*crypt_token_open_func) (
2109 struct crypt_device *cd,
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().
2121 * @param buffer the buffer with keyslot passphrase
2122 * @param buffer_len the buffer length
2124 typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
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.
2134 * @param cd crypt device handle
2135 * @param json buffer with JSON
2137 typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
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.
2144 * @param cd crypt device handle
2145 * @param json buffer with token JSON
2147 * @note dump implementations are advised to use @link crypt_log @endlink function
2148 * to dump token details.
2150 typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
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;
2164 * Register token handler
2166 * @param handler token handler to register
2168 * @return @e 0 on success or negative errno value otherwise.
2170 int crypt_token_register(const crypt_token_handler *handler);
2173 * Activate device or check key using a token.
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
2181 * @return unlocked key slot number or negative errno otherwise.
2183 int crypt_activate_by_token(struct crypt_device *cd,
2191 * @defgroup crypt-reencryption LUKS2 volume reencryption support
2193 * Set of functions to handling LUKS2 volume reencryption
2195 * @addtogroup crypt-reencryption
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)
2211 * Reencryption direction
2214 CRYPT_REENCRYPT_FORWARD = 0, /**< forward direction */
2215 CRYPT_REENCRYPT_BACKWARD /**< backward direction */
2216 } crypt_reencrypt_direction_info;
2222 CRYPT_REENCRYPT_REENCRYPT = 0, /**< Reencryption mode */
2223 CRYPT_REENCRYPT_ENCRYPT, /**< Encryption mode */
2224 CRYPT_REENCRYPT_DECRYPT, /**< Decryption mode */
2225 } crypt_reencrypt_mode_info;
2228 * LUKS2 reencryption options.
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. */
2243 * Initialize reencryption metadata using passphrase.
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).
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.
2260 * @return reencryption key slot number or negative errno otherwise.
2262 int crypt_reencrypt_init_by_passphrase(struct crypt_device *cd,
2264 const char *passphrase,
2265 size_t passphrase_size,
2269 const char *cipher_mode,
2270 const struct crypt_params_reencrypt *params);
2273 * Initialize reencryption metadata using passphrase in keyring.
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).
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.
2289 * @return reencryption key slot number or negative errno otherwise.
2291 int crypt_reencrypt_init_by_keyring(struct crypt_device *cd,
2293 const char *key_description,
2297 const char *cipher_mode,
2298 const struct crypt_params_reencrypt *params);
2301 * Run data reencryption.
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
2307 * @return @e 0 on success or negative errno value otherwise.
2309 int crypt_reencrypt(struct crypt_device *cd,
2310 int (*progress)(uint64_t size, uint64_t offset, void *usrptr));
2313 * Reencryption status info
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;
2323 * LUKS2 reencryption status.
2325 * @param cd crypt device handle
2326 * @param params reencryption parameters
2328 * @return reencryption status info and parameters.
2330 crypt_reencrypt_info crypt_reencrypt_status(struct crypt_device *cd,
2331 struct crypt_params_reencrypt *params);
2335 * @defgroup crypt-memory Safe memory helpers functions
2336 * @addtogroup crypt-memory
2341 * Allocate safe memory (content is safely wiped on deallocation).
2343 * @param size size of memory in bytes
2345 * @return pointer to allocated memory or @e NULL.
2347 void *crypt_safe_alloc(size_t size);
2350 * Release safe memory, content is safely wiped.
2351 * The pointer must be allocated with @link crypt_safe_alloc @endlink
2353 * @param data pointer to memory to be deallocated
2355 void crypt_safe_free(void *data);
2358 * Reallocate safe memory (content is copied and safely wiped on deallocation).
2360 * @param data pointer to memory to be deallocated
2361 * @param size new size of memory in bytes
2363 * @return pointer to allocated memory or @e NULL.
2365 void *crypt_safe_realloc(void *data, size_t size);
2368 * Safe clear memory area (compile should not compile this call out).
2370 * @param data pointer to memory to be cleared
2371 * @param size size of memory in bytes
2373 void crypt_safe_memzero(void *data, size_t size);
2380 #endif /* _LIBCRYPTSETUP_H */