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-2023 Red Hat, Inc. All rights reserved.
7 * Copyright (C) 2009-2023 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 */
49 struct crypt_keyslot_context;
52 * Initialize crypt device handle and check if the provided device exists.
54 * @param cd Returns pointer to crypt device handle
55 * @param device Path to the backing device.
56 * If @e device is not a block device but a path to some file,
57 * the function will try to create a loopdevice and attach
58 * the file to the loopdevice with AUTOCLEAR flag set.
59 * If @e device is @e NULL function it will initialize dm backend only.
61 * @return @e 0 on success or negative errno value otherwise.
63 * @note Note that logging is not initialized here, possible messages use
64 * default log function.
66 int crypt_init(struct crypt_device **cd, const char *device);
69 * Initialize crypt device handle with optional data device and check
72 * @param cd Returns pointer to crypt device handle
73 * @param device Path to the backing device or detached header.
74 * @param data_device Path to the data device or @e NULL.
76 * @return @e 0 on success or negative errno value otherwise.
78 * @note Note that logging is not initialized here, possible messages use
79 * default log function.
81 int crypt_init_data_device(struct crypt_device **cd,
83 const char *data_device);
86 * Initialize crypt device handle from provided active device name,
87 * and, optionally, from separate metadata (header) device
88 * and check if provided device exists.
90 * @return @e 0 on success or negative errno value otherwise.
92 * @param cd returns crypt device handle for active device
93 * @param name name of active crypt device
94 * @param header_device optional device containing on-disk header
95 * (@e NULL if it the same as underlying device on there is no on-disk header)
97 * @post In case @e device points to active LUKS device but header load fails,
98 * context device type is set to @e NULL and @e 0 is returned as if it were successful.
99 * Context with @e NULL device type can only be deactivated by crypt_deactivate
101 * @note @link crypt_init_by_name @endlink is equivalent to calling
102 * crypt_init_by_name_and_header(cd, name, NULL);
104 int crypt_init_by_name_and_header(struct crypt_device **cd,
106 const char *header_device);
109 * This is equivalent to call
110 * @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
112 * @sa crypt_init_by_name_and_header
114 int crypt_init_by_name(struct crypt_device **cd, const char *name);
117 * Release crypt device context and used memory.
119 * @param cd crypt device handle
121 void crypt_free(struct crypt_device *cd);
124 * Set confirmation callback (yes/no).
126 * If code need confirmation (like resetting uuid or restoring LUKS header from file)
127 * this function is called. If not defined, everything is confirmed.
129 * Callback function @e confirm should return @e 0 if operation is declined,
130 * other values mean accepted.
132 * @param cd crypt device handle
133 * @param confirm user defined confirm callback reference; use
134 * @p msg for message for user to confirm and
135 * @p usrptr for identification in callback
136 * @param usrptr provided identification in callback
138 * @note Current version of cryptsetup API requires confirmation for UUID change and
139 * LUKS header restore only.
141 void crypt_set_confirm_callback(struct crypt_device *cd,
142 int (*confirm)(const char *msg, void *usrptr),
147 * For LUKS it is encrypted data device when LUKS header is separated.
148 * For VERITY it is data device when hash device is separated.
150 * @param cd crypt device handle
151 * @param device path to device
153 * @returns 0 on success or negative errno value otherwise.
155 int crypt_set_data_device(struct crypt_device *cd, const char *device);
158 * Set data device offset in 512-byte sectors.
160 * This function is replacement for data alignment fields in LUKS param struct.
161 * If set to 0 (default), old behaviour is preserved.
162 * This value is reset on @link crypt_load @endlink.
164 * @param cd crypt device handle
165 * @param data_offset data offset in bytes
167 * @returns 0 on success or negative errno value otherwise.
169 * @note Data offset must be aligned to multiple of 8 (alignment to 4096-byte sectors)
170 * and must be big enough to accommodate the whole LUKS header with all keyslots.
171 * @note Data offset is enforced by this function, device topology
172 * information is no longer used after calling this function.
174 int crypt_set_data_offset(struct crypt_device *cd, uint64_t data_offset);
179 * @defgroup crypt-log Cryptsetup logging
180 * Set of functions and defines used in cryptsetup for
182 * @addtogroup crypt-log
186 /** normal log level */
187 #define CRYPT_LOG_NORMAL 0
188 /** error log level */
189 #define CRYPT_LOG_ERROR 1
190 /** verbose log level */
191 #define CRYPT_LOG_VERBOSE 2
192 /** debug log level - always on stdout */
193 #define CRYPT_LOG_DEBUG -1
194 /** debug log level - additional JSON output (for LUKS2) */
195 #define CRYPT_LOG_DEBUG_JSON -2
200 * @param cd crypt device handle (can be @e NULL to set default log function)
201 * @param log user defined log function reference; use
202 * @p level for log level,
203 * @p msg for message, and
204 * @p usrptr for identification in callback
205 * @param usrptr provided identification in callback
207 void crypt_set_log_callback(struct crypt_device *cd,
208 void (*log)(int level, const char *msg, void *usrptr),
212 * Defines log function or use the default one otherwise.
214 * @see crypt_set_log_callback
216 * @param cd crypt device handle
217 * @param level log level
218 * @param msg log message
220 void crypt_log(struct crypt_device *cd, int level, const char *msg);
223 * Log function with variable arguments.
225 * @param cd crypt device handle
226 * @param level log level
227 * @param format formatted log message
229 void crypt_logf(struct crypt_device *cd, int level, const char *format, ...);
233 * @defgroup crypt-set Cryptsetup settings (RNG, PBKDF, locking)
234 * @addtogroup crypt-set
238 /** CRYPT_RNG_URANDOM - use /dev/urandom */
239 #define CRYPT_RNG_URANDOM 0
240 /** CRYPT_RNG_RANDOM - use /dev/random (waits if no entropy in system) */
241 #define CRYPT_RNG_RANDOM 1
244 * Set which RNG (random number generator) is used for generating long term key
246 * @param cd crypt device handle
247 * @param rng_type kernel random number generator to use
250 void crypt_set_rng_type(struct crypt_device *cd, int rng_type);
253 * Get which RNG (random number generator) is used for generating long term key.
255 * @param cd crypt device handle
256 * @return RNG type on success or negative errno value otherwise.
259 int crypt_get_rng_type(struct crypt_device *cd);
264 struct crypt_pbkdf_type {
265 const char *type; /**< PBKDF algorithm */
266 const char *hash; /**< Hash algorithm */
267 uint32_t time_ms; /**< Requested time cost [milliseconds] */
268 uint32_t iterations; /**< Iterations, 0 or benchmarked value. */
269 uint32_t max_memory_kb; /**< Requested or benchmarked memory cost [kilobytes] */
270 uint32_t parallel_threads;/**< Requested parallel cost [threads] */
271 uint32_t flags; /**< CRYPT_PBKDF* flags */
274 /** Iteration time set by crypt_set_iteration_time(), for compatibility only. */
275 #define CRYPT_PBKDF_ITER_TIME_SET (UINT32_C(1) << 0)
276 /** Never run benchmarks, use pre-set value or defaults. */
277 #define CRYPT_PBKDF_NO_BENCHMARK (UINT32_C(1) << 1)
279 /** PBKDF2 according to RFC2898, LUKS1 legacy */
280 #define CRYPT_KDF_PBKDF2 "pbkdf2"
281 /** Argon2i according to RFC */
282 #define CRYPT_KDF_ARGON2I "argon2i"
283 /** Argon2id according to RFC */
284 #define CRYPT_KDF_ARGON2ID "argon2id"
287 * Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot
288 * about to get created with any crypt_keyslot_add_*() call.
290 * @param cd crypt device handle
291 * @param pbkdf PBKDF parameters
293 * @return 0 on success or negative errno value otherwise.
295 * @note For LUKS1, only PBKDF2 is supported, other settings will be rejected.
296 * @note For non-LUKS context types the call succeeds, but PBKDF is not used.
298 int crypt_set_pbkdf_type(struct crypt_device *cd,
299 const struct crypt_pbkdf_type *pbkdf);
302 * Get PBKDF (Password-Based Key Derivation Algorithm) parameters.
304 * @param pbkdf_type type of PBKDF
306 * @return struct on success or NULL value otherwise.
309 const struct crypt_pbkdf_type *crypt_get_pbkdf_type_params(const char *pbkdf_type);
312 * Get default PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
313 * Works only with LUKS device handles (both versions).
315 * @param type type of device (see @link crypt-type @endlink)
317 * @return struct on success or NULL value otherwise.
320 const struct crypt_pbkdf_type *crypt_get_pbkdf_default(const char *type);
323 * Get current PBKDF (Password-Based Key Derivation Algorithm) settings for keyslots.
324 * Works only with LUKS device handles (both versions).
326 * @param cd crypt device handle
328 * @return struct on success or NULL value otherwise.
331 const struct crypt_pbkdf_type *crypt_get_pbkdf_type(struct crypt_device *cd);
334 * Set how long should cryptsetup iterate in PBKDF2 function.
335 * Default value heads towards the iterations which takes around 1 second.
336 * \b Deprecated, only for backward compatibility.
337 * Use @link crypt_set_pbkdf_type @endlink.
339 * @param cd crypt device handle
340 * @param iteration_time_ms the time in ms
342 * @note If the time value is not acceptable for active PBKDF, value is quietly ignored.
344 void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);
347 * Helper to lock/unlock memory to avoid swap sensitive data to disk.
348 * \b Deprecated, only for backward compatibility. Memory with keys are locked automatically.
350 * @param cd crypt device handle, can be @e NULL
351 * @param lock 0 to unlock otherwise lock memory
353 * @returns Value indicating whether the memory is locked (function can be called multiple times).
355 * @note Only root can do this.
356 * @note It locks/unlocks all process memory, not only crypt context.
358 int crypt_memory_lock(struct crypt_device *cd, int lock) __attribute__((deprecated));
361 * Set global lock protection for on-disk metadata (file-based locking).
363 * @param cd crypt device handle, can be @e NULL
364 * @param enable 0 to disable locking otherwise enable it (default)
366 * @returns @e 0 on success or negative errno value otherwise.
368 * @note Locking applied only for some metadata formats (LUKS2).
369 * @note The switch is global on the library level.
370 * In current version locking can be only switched off and cannot be switched on later.
372 int crypt_metadata_locking(struct crypt_device *cd, int enable);
375 * Set metadata header area sizes. This applies only to LUKS2.
376 * These values limit amount of metadata anf number of supportable keyslots.
378 * @param cd crypt device handle, can be @e NULL
379 * @param metadata_size size in bytes of JSON area + 4k binary header
380 * @param keyslots_size size in bytes of binary keyslots area
382 * @returns @e 0 on success or negative errno value otherwise.
384 * @note The metadata area is stored twice and both copies contain 4k binary header.
385 * Only 16,32,64,128,256,512,1024,2048 and 4096 kB value is allowed (see LUKS2 specification).
386 * @note Keyslots area size must be multiple of 4k with maximum 128MB.
388 int crypt_set_metadata_size(struct crypt_device *cd,
389 uint64_t metadata_size,
390 uint64_t keyslots_size);
393 * Get metadata header area sizes. This applies only to LUKS2.
394 * These values limit amount of metadata anf number of supportable keyslots.
396 * @param cd crypt device handle
397 * @param metadata_size size in bytes of JSON area + 4k binary header
398 * @param keyslots_size size in bytes of binary keyslots area
400 * @returns @e 0 on success or negative errno value otherwise.
402 int crypt_get_metadata_size(struct crypt_device *cd,
403 uint64_t *metadata_size,
404 uint64_t *keyslots_size);
409 * @defgroup crypt-type Cryptsetup on-disk format types
410 * Set of functions, \#defines and structs related
411 * to on-disk format types
412 * @addtogroup crypt-type
416 /** plain crypt device, no on-disk header */
417 #define CRYPT_PLAIN "PLAIN"
418 /** LUKS version 1 header on-disk */
419 #define CRYPT_LUKS1 "LUKS1"
420 /** LUKS version 2 header on-disk */
421 #define CRYPT_LUKS2 "LUKS2"
422 /** loop-AES compatibility mode */
423 #define CRYPT_LOOPAES "LOOPAES"
424 /** dm-verity mode */
425 #define CRYPT_VERITY "VERITY"
426 /** TCRYPT (TrueCrypt-compatible and VeraCrypt-compatible) mode */
427 #define CRYPT_TCRYPT "TCRYPT"
428 /** INTEGRITY dm-integrity device */
429 #define CRYPT_INTEGRITY "INTEGRITY"
430 /** BITLK (BitLocker-compatible mode) */
431 #define CRYPT_BITLK "BITLK"
432 /** FVAULT2 (FileVault2-compatible mode) */
433 #define CRYPT_FVAULT2 "FVAULT2"
435 /** LUKS any version */
436 #define CRYPT_LUKS NULL
441 * @param cd crypt device handle
442 * @return string according to device type or @e NULL if not known.
444 const char *crypt_get_type(struct crypt_device *cd);
447 * Get device default LUKS type
449 * @return string according to device type (CRYPT_LUKS1 or CRYPT_LUKS2).
451 const char *crypt_get_default_type(void);
455 * Structure used as parameter for PLAIN device type.
459 struct crypt_params_plain {
460 const char *hash; /**< password hash function */
461 uint64_t offset; /**< offset in sectors */
462 uint64_t skip; /**< IV offset / initialization sector */
463 uint64_t size; /**< size of mapped device or @e 0 for autodetection */
464 uint32_t sector_size; /**< sector size in bytes (@e 0 means 512 for compatibility) */
468 * Structure used as parameter for LUKS device type.
470 * @see crypt_format, crypt_load
472 * @note during crypt_format @e data_device attribute determines
473 * if the LUKS header is separated from encrypted payload device
476 struct crypt_params_luks1 {
477 const char *hash; /**< hash used in LUKS header */
478 size_t data_alignment; /**< data area alignment in 512B sectors, data offset is multiple of this */
479 const char *data_device; /**< detached encrypted data device or @e NULL */
484 * Structure used as parameter for loop-AES device type.
489 struct crypt_params_loopaes {
490 const char *hash; /**< key hash function */
491 uint64_t offset; /**< offset in sectors */
492 uint64_t skip; /**< IV offset / initialization sector */
497 * Structure used as parameter for dm-verity device type.
499 * @see crypt_format, crypt_load
502 struct crypt_params_verity {
503 const char *hash_name; /**< hash function */
504 const char *data_device; /**< data_device (CRYPT_VERITY_CREATE_HASH) */
505 const char *hash_device; /**< hash_device (output only) */
506 const char *fec_device; /**< fec_device (output only) */
507 const char *salt; /**< salt */
508 uint32_t salt_size; /**< salt size (in bytes) */
509 uint32_t hash_type; /**< in-kernel hashing type */
510 uint32_t data_block_size; /**< data block size (in bytes) */
511 uint32_t hash_block_size; /**< hash block size (in bytes) */
512 uint64_t data_size; /**< data area size (in data blocks) */
513 uint64_t hash_area_offset; /**< hash/header offset (in bytes) */
514 uint64_t fec_area_offset; /**< FEC/header offset (in bytes) */
515 uint32_t fec_roots; /**< Reed-Solomon FEC roots */
516 uint32_t flags; /**< CRYPT_VERITY* flags */
519 /** No on-disk header (only hashes) */
520 #define CRYPT_VERITY_NO_HEADER (UINT32_C(1) << 0)
521 /** Verity hash in userspace before activation */
522 #define CRYPT_VERITY_CHECK_HASH (UINT32_C(1) << 1)
523 /** Create hash - format hash device */
524 #define CRYPT_VERITY_CREATE_HASH (UINT32_C(1) << 2)
525 /** Root hash signature required for activation */
526 #define CRYPT_VERITY_ROOT_HASH_SIGNATURE (UINT32_C(1) << 3)
530 * Structure used as parameter for TCRYPT device type.
535 struct crypt_params_tcrypt {
536 const char *passphrase; /**< passphrase to unlock header (input only) */
537 size_t passphrase_size; /**< passphrase size (input only, max length is 64) */
538 const char **keyfiles; /**< keyfile paths to unlock header (input only) */
539 unsigned int keyfiles_count;/**< keyfiles count (input only) */
540 const char *hash_name; /**< hash function for PBKDF */
541 const char *cipher; /**< cipher chain c1[-c2[-c3]] */
542 const char *mode; /**< cipher block mode */
543 size_t key_size; /**< key size in bytes (the whole chain) */
544 uint32_t flags; /**< CRYPT_TCRYPT* flags */
545 uint32_t veracrypt_pim; /**< VeraCrypt Personal Iteration Multiplier */
548 /** Include legacy modes when scanning for header */
549 #define CRYPT_TCRYPT_LEGACY_MODES (UINT32_C(1) << 0)
550 /** Try to load hidden header (describing hidden device) */
551 #define CRYPT_TCRYPT_HIDDEN_HEADER (UINT32_C(1) << 1)
552 /** Try to load backup header */
553 #define CRYPT_TCRYPT_BACKUP_HEADER (UINT32_C(1) << 2)
554 /** Device contains encrypted system (with boot loader) */
555 #define CRYPT_TCRYPT_SYSTEM_HEADER (UINT32_C(1) << 3)
556 /** Include VeraCrypt modes when scanning for header,
557 * all other TCRYPT flags applies as well.
558 * VeraCrypt device is reported as TCRYPT type.
560 #define CRYPT_TCRYPT_VERA_MODES (UINT32_C(1) << 4)
564 * Structure used as parameter for dm-integrity device type.
566 * @see crypt_format, crypt_load
568 * @note In bitmap tracking mode, the journal is implicitly disabled.
569 * As an ugly workaround for compatibility, journal_watermark is overloaded
570 * to mean 512-bytes sectors-per-bit and journal_commit_time means bitmap flush time.
571 * All other journal parameters are not applied in the bitmap mode.
573 struct crypt_params_integrity {
574 uint64_t journal_size; /**< size of journal in bytes */
575 unsigned int journal_watermark; /**< journal flush watermark in percents; in bitmap mode sectors-per-bit */
576 unsigned int journal_commit_time; /**< journal commit time (or bitmap flush time) in ms */
577 uint32_t interleave_sectors; /**< number of interleave sectors (power of two) */
578 uint32_t tag_size; /**< tag size per-sector in bytes */
579 uint32_t sector_size; /**< sector size in bytes */
580 uint32_t buffer_sectors; /**< number of sectors in one buffer */
581 const char *integrity; /**< integrity algorithm, NULL for LUKS2 */
582 uint32_t integrity_key_size; /**< integrity key size in bytes, info only, 0 for LUKS2 */
584 const char *journal_integrity; /**< journal integrity algorithm */
585 const char *journal_integrity_key; /**< journal integrity key, only for crypt_load */
586 uint32_t journal_integrity_key_size; /**< journal integrity key size in bytes, only for crypt_load */
588 const char *journal_crypt; /**< journal encryption algorithm */
589 const char *journal_crypt_key; /**< journal crypt key, only for crypt_load */
590 uint32_t journal_crypt_key_size; /**< journal crypt key size in bytes, only for crypt_load */
594 * Structure used as parameter for LUKS2 device type.
596 * @see crypt_format, crypt_load
598 * @note during crypt_format @e data_device attribute determines
599 * if the LUKS2 header is separated from encrypted payload device
602 struct crypt_params_luks2 {
603 const struct crypt_pbkdf_type *pbkdf; /**< PBKDF (and hash) parameters or @e NULL*/
604 const char *integrity; /**< integrity algorithm or @e NULL */
605 const struct crypt_params_integrity *integrity_params; /**< Data integrity parameters or @e NULL*/
606 size_t data_alignment; /**< data area alignment in 512B sectors, data offset is multiple of this */
607 const char *data_device; /**< detached encrypted data device or @e NULL */
608 uint32_t sector_size; /**< encryption sector size, 0 triggers auto-detection for optimal encryption sector size */
609 const char *label; /**< header label or @e NULL*/
610 const char *subsystem; /**< header subsystem label or @e NULL*/
615 * @defgroup crypt-actions Cryptsetup device context actions
616 * Set of functions for formatting and manipulating with specific crypt_type
617 * @addtogroup crypt-actions
622 * Create (format) new crypt device (and possible header on-disk) but do not activate it.
624 * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
626 * @param cd crypt device handle
627 * @param type type of device (optional params struct must be of this type)
628 * @param cipher (e.g. "aes")
629 * @param cipher_mode including IV specification (e.g. "xts-plain")
630 * @param uuid requested UUID or @e NULL if it should be generated
631 * @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
632 * @param volume_key_size size of volume key in bytes.
633 * @param params crypt type specific parameters (see @link crypt-type @endlink)
635 * @returns @e 0 on success or negative errno value otherwise.
637 * @note Note that crypt_format does not create LUKS keyslot (any version). To create keyslot
638 * call any crypt_keyslot_add_* function.
639 * @note For VERITY @link crypt-type @endlink, only uuid parameter is used, other parameters
640 * are ignored and verity specific attributes are set through mandatory params option.
642 int crypt_format(struct crypt_device *cd,
645 const char *cipher_mode,
647 const char *volume_key,
648 size_t volume_key_size,
652 * Set format compatibility flags.
654 * @param cd crypt device handle
655 * @param flags CRYPT_COMPATIBILITY_* flags
657 void crypt_set_compatibility(struct crypt_device *cd, uint32_t flags);
660 * Get compatibility flags.
662 * @param cd crypt device handle
664 * @returns compatibility flags
666 uint32_t crypt_get_compatibility(struct crypt_device *cd);
668 /** dm-integrity device uses less effective (legacy) padding (old kernels) */
669 #define CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING (UINT32_C(1) << 0)
670 /** dm-integrity device does not protect superblock with HMAC (old kernels) */
671 #define CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC (UINT32_C(1) << 1)
672 /** dm-integrity allow recalculating of volumes with HMAC keys (old kernels) */
673 #define CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC (UINT32_C(1) << 2)
676 * Convert to new type for already existing device.
678 * @param cd crypt device handle
679 * @param type type of device (optional params struct must be of this type)
680 * @param params crypt type specific parameters (see @link crypt-type @endlink)
682 * @returns 0 on success or negative errno value otherwise.
684 * @note Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported.
685 * Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion
686 * possible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf
687 * type must be PBKDF2) and device cannot be formatted with any authenticated
690 * @note Device must be offline for conversion. UUID change is not possible for active
693 int crypt_convert(struct crypt_device *cd,
698 * Set new UUID for already existing device.
700 * @param cd crypt device handle
701 * @param uuid requested UUID or @e NULL if it should be generated
703 * @returns 0 on success or negative errno value otherwise.
705 * @note Currently, only LUKS device type are supported
707 int crypt_set_uuid(struct crypt_device *cd,
711 * Set new labels (label and subsystem) for already existing device.
713 * @param cd crypt device handle
714 * @param label requested label or @e NULL
715 * @param subsystem requested subsystem label or @e NULL
717 * @returns 0 on success or negative errno value otherwise.
719 * @note Currently, only LUKS2 device type is supported
721 int crypt_set_label(struct crypt_device *cd,
723 const char *subsystem);
726 * Get the label of an existing device.
728 * @param cd crypt device handle
730 * @return label, or @e NULL otherwise
732 const char *crypt_get_label(struct crypt_device *cd);
735 * Get the subsystem of an existing device.
737 * @param cd crypt device handle
739 * @return subsystem, or @e NULL otherwise
741 const char *crypt_get_subsystem(struct crypt_device *cd);
744 * Enable or disable loading of volume keys via kernel keyring. When set to
745 * 'enabled' library loads key in kernel keyring first and pass the key
746 * description to dm-crypt instead of binary key copy. If set to 'disabled'
747 * library fallbacks to old method of loading volume key directly in
750 * @param cd crypt device handle, can be @e NULL
751 * @param enable 0 to disable loading of volume keys via kernel keyring
752 * (classical method) otherwise enable it (default)
754 * @returns @e 0 on success or negative errno value otherwise.
756 * @note Currently loading of volume keys via kernel keyring is supported
757 * (and enabled by default) only for LUKS2 devices.
758 * @note The switch is global on the library level.
760 int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
763 * Load crypt device parameters from on-disk header.
765 * @param cd crypt device handle
766 * @param requested_type @link crypt-type @endlink or @e NULL for all known
767 * @param params crypt type specific parameters (see @link crypt-type @endlink)
769 * @returns 0 on success or negative errno value otherwise.
771 * @post In case LUKS header is read successfully but payload device is too small
772 * error is returned and device type in context is set to @e NULL
774 * @note Note that load works only for device types with on-disk metadata.
775 * @note Function does not print visible error message if metadata is not present.
778 int crypt_load(struct crypt_device *cd,
779 const char *requested_type,
783 * Try to repair crypt device LUKS on-disk header if invalid.
785 * @param cd crypt device handle
786 * @param requested_type @link crypt-type @endlink or @e NULL for all known
787 * @param params crypt type specific parameters (see @link crypt-type @endlink)
789 * @returns 0 on success or negative errno value otherwise.
791 * @note For LUKS2 device crypt_repair bypass blkid checks and
792 * perform auto-recovery even though there're third party device
793 * signatures found by blkid probes. Currently the crypt_repair on LUKS2
794 * works only if exactly one header checksum does not match or exactly
795 * one header is missing.
797 int crypt_repair(struct crypt_device *cd,
798 const char *requested_type,
802 * Resize crypt device.
804 * @param cd - crypt device handle
805 * @param name - name of device to resize
806 * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
808 * @return @e 0 on success or negative errno value otherwise.
810 * @note Most notably it returns -EPERM when device was activated with volume key
811 * in kernel keyring and current device handle (context) doesn't have verified key
812 * loaded in kernel. To load volume key for already active device use any of
813 * @link crypt_activate_by_passphrase @endlink, @link crypt_activate_by_keyfile @endlink,
814 * @link crypt_activate_by_keyfile_offset @endlink, @link crypt_activate_by_volume_key @endlink,
815 * @link crypt_activate_by_keyring @endlink or @link crypt_activate_by_token @endlink with flag
816 * @e CRYPT_ACTIVATE_KEYRING_KEY raised and @e name parameter set to @e NULL.
818 int crypt_resize(struct crypt_device *cd,
823 * Suspend crypt device.
825 * @param cd crypt device handle, can be @e NULL
826 * @param name name of device to suspend
828 * @return 0 on success or negative errno value otherwise.
830 * @note Only LUKS device type is supported
833 int crypt_suspend(struct crypt_device *cd,
837 * Resume crypt device using passphrase.
840 * @param cd crypt device handle
841 * @param name name of device to resume
842 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
843 * @param passphrase passphrase used to unlock volume key
844 * @param passphrase_size size of @e passphrase (binary data)
846 * @return unlocked key slot number or negative errno otherwise.
848 * @note Only LUKS device type is supported
850 int crypt_resume_by_passphrase(struct crypt_device *cd,
853 const char *passphrase,
854 size_t passphrase_size);
857 * Resume crypt device using key file.
859 * @param cd crypt device handle
860 * @param name name of device to resume
861 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
862 * @param keyfile key file used to unlock volume key
863 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
864 * @param keyfile_offset number of bytes to skip at start of keyfile
866 * @return unlocked key slot number or negative errno otherwise.
868 int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
873 uint64_t keyfile_offset);
876 * Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
878 int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
883 size_t keyfile_offset);
886 * Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
888 int crypt_resume_by_keyfile(struct crypt_device *cd,
892 size_t keyfile_size);
894 * Resume crypt device using provided volume key.
896 * @param cd crypt device handle
897 * @param name name of device to resume
898 * @param volume_key provided volume key
899 * @param volume_key_size size of volume_key
901 * @return @e 0 on success or negative errno value otherwise.
903 int crypt_resume_by_volume_key(struct crypt_device *cd,
905 const char *volume_key,
906 size_t volume_key_size);
908 * Resume crypt device using LUKS2 token.
910 * @param cd LUKS2 crypt device handle
911 * @param name name of device to resume
912 * @param type restrict type of token, if @e NULL all types are allowed
913 * @param pin passphrase (or PIN) to unlock token (may be binary data)
914 * @param pin_size size of @e pin
915 * @param usrptr provided identification in callback
917 * @return unlocked key slot number or negative errno otherwise.
919 * @note EPERM errno means token provided passphrase successfully, but
920 * passphrase did not unlock any keyslot associated with the token.
922 * @note ENOENT errno means no token (or subsequently assigned keyslot) was
923 * eligible to resume LUKS2 device.
925 * @note ENOANO errno means that token is PIN protected and was either missing
928 * @note Negative EAGAIN errno means token handler requires additional hardware
929 * not present in the system to unlock keyslot.
931 * @note with @param token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop
932 * to resume device using any available token. It may happen that various token handlers
933 * return different error codes. At the end loop returns error codes in the following
934 * order (from the most significant to the least) any negative errno except those
935 * listed below, non negative token id (success), -ENOANO, -EAGAIN, -EPERM, -ENOENT.
937 int crypt_resume_by_token_pin(struct crypt_device *cd,
947 * @defgroup crypt-keyslot LUKS keyslots
948 * @addtogroup crypt-keyslot
952 /** iterate through all keyslots and find first one that fits */
953 #define CRYPT_ANY_SLOT -1
956 * Add key slot using provided passphrase.
958 * @pre @e cd contains initialized and formatted LUKS device context
960 * @param cd crypt device handle
961 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
962 * @param passphrase passphrase used to unlock volume key
963 * @param passphrase_size size of passphrase (binary data)
964 * @param new_passphrase passphrase for new keyslot
965 * @param new_passphrase_size size of @e new_passphrase (binary data)
967 * @return allocated key slot number or negative errno otherwise.
969 int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
971 const char *passphrase,
972 size_t passphrase_size,
973 const char *new_passphrase,
974 size_t new_passphrase_size);
977 * Change defined key slot using provided passphrase.
979 * @pre @e cd contains initialized and formatted LUKS device context
981 * @param cd crypt device handle
982 * @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
983 * @param keyslot_new new keyslot (can be the same as old)
984 * @param passphrase passphrase used to unlock volume key
985 * @param passphrase_size size of passphrase (binary data)
986 * @param new_passphrase passphrase for new keyslot
987 * @param new_passphrase_size size of @e new_passphrase (binary data)
989 * @return allocated key slot number or negative errno otherwise.
991 int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
994 const char *passphrase,
995 size_t passphrase_size,
996 const char *new_passphrase,
997 size_t new_passphrase_size);
1000 * Add key slot using provided key file path.
1002 * @pre @e cd contains initialized and formatted LUKS device context
1004 * @param cd crypt device handle
1005 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
1006 * @param keyfile key file used to unlock volume key
1007 * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
1008 * @param keyfile_offset number of bytes to skip at start of keyfile
1009 * @param new_keyfile keyfile for new keyslot
1010 * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
1011 * @param new_keyfile_offset number of bytes to skip at start of new_keyfile
1013 * @return allocated key slot number or negative errno otherwise.
1015 int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
1017 const char *keyfile,
1018 size_t keyfile_size,
1019 uint64_t keyfile_offset,
1020 const char *new_keyfile,
1021 size_t new_keyfile_size,
1022 uint64_t new_keyfile_offset);
1025 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
1027 int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
1029 const char *keyfile,
1030 size_t keyfile_size,
1031 size_t keyfile_offset,
1032 const char *new_keyfile,
1033 size_t new_keyfile_size,
1034 size_t new_keyfile_offset);
1037 * Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
1039 int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
1041 const char *keyfile,
1042 size_t keyfile_size,
1043 const char *new_keyfile,
1044 size_t new_keyfile_size);
1047 * Add key slot using provided volume key.
1049 * @pre @e cd contains initialized and formatted LUKS device context
1051 * @param cd crypt device handle
1052 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
1053 * @param volume_key provided volume key or @e NULL if used after crypt_format
1054 * @param volume_key_size size of volume_key
1055 * @param passphrase passphrase for new keyslot
1056 * @param passphrase_size size of passphrase
1058 * @return allocated key slot number or negative errno otherwise.
1060 int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
1062 const char *volume_key,
1063 size_t volume_key_size,
1064 const char *passphrase,
1065 size_t passphrase_size);
1067 /** create keyslot with volume key not associated with current dm-crypt segment */
1068 #define CRYPT_VOLUME_KEY_NO_SEGMENT (UINT32_C(1) << 0)
1070 /** create keyslot with new volume key and assign it to current dm-crypt segment */
1071 #define CRYPT_VOLUME_KEY_SET (UINT32_C(1) << 1)
1073 /** Assign key to first matching digest before creating new digest */
1074 #define CRYPT_VOLUME_KEY_DIGEST_REUSE (UINT32_C(1) << 2)
1077 * Add key slot using provided key.
1079 * @pre @e cd contains initialized and formatted LUKS2 device context
1081 * @param cd crypt device handle
1082 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
1083 * @param volume_key provided volume key or @e NULL (see note below)
1084 * @param volume_key_size size of volume_key
1085 * @param passphrase passphrase for new keyslot
1086 * @param passphrase_size size of passphrase
1087 * @param flags key flags to set
1089 * @return allocated key slot number or negative errno otherwise.
1091 * @note in case volume_key is @e NULL following first matching rule will apply:
1092 * @li if cd is device handle used in crypt_format() by current process, the volume
1093 * key generated (or passed) in crypt_format() will be stored in keyslot.
1094 * @li if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be
1095 * generated and stored in keyslot. The keyslot will become unbound (unusable to
1096 * dm-crypt device activation).
1097 * @li fails with -EINVAL otherwise
1099 * @warning CRYPT_VOLUME_KEY_SET flag force updates volume key. It is @b not @b reencryption!
1100 * By doing so you will most probably destroy your ciphertext data device. It's supposed
1101 * to be used only in wrapped keys scheme for key refresh process where real (inner) volume
1102 * key stays untouched. It may be involed on active @e keyslot which makes the (previously
1103 * unbound) keyslot new regular keyslot.
1105 int crypt_keyslot_add_by_key(struct crypt_device *cd,
1107 const char *volume_key,
1108 size_t volume_key_size,
1109 const char *passphrase,
1110 size_t passphrase_size,
1114 * @defgroup crypt-keyslot-context Crypt keyslot context
1115 * @addtogroup crypt-keyslot-context
1120 * Release crypt keyslot context and used memory.
1122 * @param kc crypt keyslot context
1124 void crypt_keyslot_context_free(struct crypt_keyslot_context *kc);
1127 * Initialize keyslot context via passphrase.
1129 * @param cd crypt device handle initialized to LUKS device context
1130 * @param passphrase passphrase for a keyslot
1131 * @param passphrase_size size of passphrase
1132 * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_PASSPHRASE
1134 * @return zero on success or negative errno otherwise.
1136 int crypt_keyslot_context_init_by_passphrase(struct crypt_device *cd,
1137 const char *passphrase,
1138 size_t passphrase_size,
1139 struct crypt_keyslot_context **kc);
1142 * Initialize keyslot context via key file path.
1144 * @param cd crypt device handle initialized to LUKS device context
1146 * @param keyfile key file with passphrase for a keyslot
1147 * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
1148 * @param keyfile_offset number of bytes to skip at start of keyfile
1149 * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_KEYFILE
1151 * @return zero on success or negative errno otherwise.
1153 int crypt_keyslot_context_init_by_keyfile(struct crypt_device *cd,
1154 const char *keyfile,
1155 size_t keyfile_size,
1156 uint64_t keyfile_offset,
1157 struct crypt_keyslot_context **kc);
1160 * Initialize keyslot context via LUKS2 token.
1162 * @param cd crypt device handle initialized to LUKS2 device context
1164 * @param token token providing passphrase for a keyslot or CRYPT_ANY_TOKEN
1165 * @param type restrict type of token, if @e NULL all types are allowed
1166 * @param pin passphrase (or PIN) to unlock token (may be binary data)
1167 * @param pin_size size of @e pin
1168 * @param usrptr provided identification in callback
1169 * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_TOKEN
1171 * @return zero on success or negative errno otherwise.
1173 int crypt_keyslot_context_init_by_token(struct crypt_device *cd,
1176 const char *pin, size_t pin_size,
1178 struct crypt_keyslot_context **kc);
1181 * Initialize keyslot context via key.
1183 * @param cd crypt device handle initialized to LUKS device context
1185 * @param volume_key provided volume key or @e NULL if used after crypt_format
1186 * or with CRYPT_VOLUME_KEY_NO_SEGMENT flag
1187 * @param volume_key_size size of volume_key
1188 * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_KEY
1190 * @return zero on success or negative errno otherwise.
1192 int crypt_keyslot_context_init_by_volume_key(struct crypt_device *cd,
1193 const char *volume_key,
1194 size_t volume_key_size,
1195 struct crypt_keyslot_context **kc);
1198 * Get error code per keyslot context from last failed call.
1200 * @note If @link crypt_keyslot_add_by_keyslot_context @endlink passed with
1201 * no negative return code. The return value of this function is undefined.
1203 * @param kc keyslot context involved in failed @link crypt_keyslot_add_by_keyslot_context @endlink
1205 * @return Negative errno if keyslot context caused a failure, zero otherwise.
1207 int crypt_keyslot_context_get_error(struct crypt_keyslot_context *kc);
1210 * Set new pin to token based keyslot context.
1212 * @note Use when @link crypt_keyslot_add_by_keyslot_context @endlink failed
1213 * and token keyslot context returned -ENOANO error code via
1214 * @link crypt_keyslot_context_get_error @endlink.
1216 * @param cd crypt device handle initialized to LUKS2 device context
1217 * @param pin passphrase (or PIN) to unlock token (may be binary data)
1218 * @param pin_size size of @e pin
1219 * @param kc LUKS2 keyslot context (only @link CRYPT_KC_TYPE_TOKEN @endlink is allowed)
1221 * @return zero on success or negative errno otherwise
1223 int crypt_keyslot_context_set_pin(struct crypt_device *cd,
1224 const char *pin, size_t pin_size,
1225 struct crypt_keyslot_context *kc);
1228 * @defgroup crypt-keyslot-context-types Crypt keyslot context
1229 * @addtogroup crypt-keyslot-context-types
1232 /** keyslot context initialized by passphrase (@link crypt_keyslot_context_init_by_passphrase @endlink) */
1233 #define CRYPT_KC_TYPE_PASSPHRASE INT16_C(1)
1234 /** keyslot context initialized by keyfile (@link crypt_keyslot_context_init_by_keyfile @endlink) */
1235 #define CRYPT_KC_TYPE_KEYFILE INT16_C(2)
1236 /** keyslot context initialized by token (@link crypt_keyslot_context_init_by_token @endlink) */
1237 #define CRYPT_KC_TYPE_TOKEN INT16_C(3)
1238 /** keyslot context initialized by volume key or unbound key (@link crypt_keyslot_context_init_by_volume_key @endlink) */
1239 #define CRYPT_KC_TYPE_KEY INT16_C(4)
1243 * Get type identifier for crypt keyslot context.
1245 * @param kc keyslot context
1247 * @return crypt keyslot context type id (see @link crypt-keyslot-context-types @endlink) or negative errno otherwise.
1249 int crypt_keyslot_context_get_type(const struct crypt_keyslot_context *kc);
1253 * Add key slot by volume key provided by keyslot context (kc). New
1254 * keyslot will be protected by passphrase provided by new keyslot context (new_kc).
1255 * See @link crypt-keyslot-context @endlink for context initialization routines.
1257 * @pre @e cd contains initialized and formatted LUKS device context.
1259 * @param cd crypt device handle
1260 * @param keyslot_existing existing keyslot or CRYPT_ANY_SLOT to get volume key from.
1261 * @param kc keyslot context providing volume key.
1262 * @param keyslot_new new keyslot or CRYPT_ANY_SLOT (first free number is used).
1263 * @param new_kc keyslot context providing passphrase for new keyslot.
1264 * @param flags key flags to set
1266 * @return allocated key slot number or negative errno otherwise.
1268 * @note new_kc can not be @e CRYPT_KC_TYPE_KEY type keyslot context.
1270 * @note For kc parameter with type @e CRYPT_KC_TYPE_KEY the keyslot_existing
1271 * parameter is ignored.
1273 * @note in case there is no active LUKS keyslot to get existing volume key from, one of following must apply:
1274 * @li @e cd must be device handle used in crypt_format() by current process (it holds reference to generated volume key)
1275 * @li kc must be of @e CRYPT_KC_TYPE_KEY type with valid volume key.
1277 * @note With CRYPT_VOLUME_KEY_NO_SEGMENT flag raised and kc of type @e CRYPT_KC_TYPE_KEY with @e volume_key set to @e NULL
1278 * the new volume_key will be generated and stored in new keyslot. The keyslot will become unbound (unusable to
1279 * dm-crypt device activation).
1281 * @warning CRYPT_VOLUME_KEY_SET flag force updates volume key. It is @b not @b reencryption!
1282 * By doing so you will most probably destroy your ciphertext data device. It's supposed
1283 * to be used only in wrapped keys scheme for key refresh process where real (inner) volume
1284 * key stays untouched. It may be involed on active @e keyslot which makes the (previously
1285 * unbound) keyslot new regular keyslot.
1287 int crypt_keyslot_add_by_keyslot_context(struct crypt_device *cd,
1288 int keyslot_existing,
1289 struct crypt_keyslot_context *kc,
1291 struct crypt_keyslot_context *new_kc,
1295 * Destroy (and disable) key slot.
1297 * @pre @e cd contains initialized and formatted LUKS device context
1299 * @param cd crypt device handle
1300 * @param keyslot requested key slot to destroy
1302 * @return @e 0 on success or negative errno value otherwise.
1304 * @note Note that there is no passphrase verification used.
1306 int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
1310 * @defgroup crypt-aflags Device runtime attributes
1312 * @addtogroup crypt-aflags
1316 /** device is read only */
1317 #define CRYPT_ACTIVATE_READONLY (UINT32_C(1) << 0)
1318 /** only reported for device without uuid */
1319 #define CRYPT_ACTIVATE_NO_UUID (UINT32_C(1) << 1)
1320 /** activate even if cannot grant exclusive access (DANGEROUS) */
1321 #define CRYPT_ACTIVATE_SHARED (UINT32_C(1) << 2)
1322 /** enable discards aka TRIM */
1323 #define CRYPT_ACTIVATE_ALLOW_DISCARDS (UINT32_C(1) << 3)
1324 /** skip global udev rules in activation ("private device"), input only */
1325 #define CRYPT_ACTIVATE_PRIVATE (UINT32_C(1) << 4)
1326 /** corruption detected (verity), output only */
1327 #define CRYPT_ACTIVATE_CORRUPTED (UINT32_C(1) << 5)
1328 /** use same_cpu_crypt option for dm-crypt */
1329 #define CRYPT_ACTIVATE_SAME_CPU_CRYPT (UINT32_C(1) << 6)
1330 /** use submit_from_crypt_cpus for dm-crypt */
1331 #define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (UINT32_C(1) << 7)
1332 /** dm-verity: ignore_corruption flag - ignore corruption, log it only */
1333 #define CRYPT_ACTIVATE_IGNORE_CORRUPTION (UINT32_C(1) << 8)
1334 /** dm-verity: restart_on_corruption flag - restart kernel on corruption */
1335 #define CRYPT_ACTIVATE_RESTART_ON_CORRUPTION (UINT32_C(1) << 9)
1336 /** dm-verity: ignore_zero_blocks - do not verify zero blocks */
1337 #define CRYPT_ACTIVATE_IGNORE_ZERO_BLOCKS (UINT32_C(1) << 10)
1338 /** key loaded in kernel keyring instead directly in dm-crypt */
1339 #define CRYPT_ACTIVATE_KEYRING_KEY (UINT32_C(1) << 11)
1340 /** dm-integrity: direct writes, do not use journal */
1341 #define CRYPT_ACTIVATE_NO_JOURNAL (UINT32_C(1) << 12)
1342 /** dm-integrity: recovery mode - no journal, no integrity checks */
1343 #define CRYPT_ACTIVATE_RECOVERY (UINT32_C(1) << 13)
1344 /** ignore persistently stored flags */
1345 #define CRYPT_ACTIVATE_IGNORE_PERSISTENT (UINT32_C(1) << 14)
1346 /** dm-verity: check_at_most_once - check data blocks only the first time */
1347 #define CRYPT_ACTIVATE_CHECK_AT_MOST_ONCE (UINT32_C(1) << 15)
1348 /** allow activation check including unbound keyslots (keyslots without segments) */
1349 #define CRYPT_ACTIVATE_ALLOW_UNBOUND_KEY (UINT32_C(1) << 16)
1350 /** dm-integrity: activate automatic recalculation */
1351 #define CRYPT_ACTIVATE_RECALCULATE (UINT32_C(1) << 17)
1352 /** reactivate existing and update flags, input only */
1353 #define CRYPT_ACTIVATE_REFRESH (UINT32_C(1) << 18)
1354 /** Use global lock to serialize memory hard KDF on activation (OOM workaround) */
1355 #define CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF (UINT32_C(1) << 19)
1356 /** dm-integrity: direct writes, use bitmap to track dirty sectors */
1357 #define CRYPT_ACTIVATE_NO_JOURNAL_BITMAP (UINT32_C(1) << 20)
1358 /** device is suspended (key should be wiped from memory), output only */
1359 #define CRYPT_ACTIVATE_SUSPENDED (UINT32_C(1) << 21)
1360 /** use IV sector counted in sector_size instead of default 512 bytes sectors */
1361 #define CRYPT_ACTIVATE_IV_LARGE_SECTORS (UINT32_C(1) << 22)
1362 /** dm-verity: panic_on_corruption flag - panic kernel on corruption */
1363 #define CRYPT_ACTIVATE_PANIC_ON_CORRUPTION (UINT32_C(1) << 23)
1364 /** dm-crypt: bypass internal workqueue and process read requests synchronously. */
1365 #define CRYPT_ACTIVATE_NO_READ_WORKQUEUE (UINT32_C(1) << 24)
1366 /** dm-crypt: bypass internal workqueue and process write requests synchronously. */
1367 #define CRYPT_ACTIVATE_NO_WRITE_WORKQUEUE (UINT32_C(1) << 25)
1368 /** dm-integrity: reset automatic recalculation */
1369 #define CRYPT_ACTIVATE_RECALCULATE_RESET (UINT32_C(1) << 26)
1370 /** dm-verity: try to use tasklets */
1371 #define CRYPT_ACTIVATE_TASKLETS (UINT32_C(1) << 27)
1374 * Active device runtime attributes
1376 struct crypt_active_device {
1377 uint64_t offset; /**< offset in sectors */
1378 uint64_t iv_offset; /**< IV initialization sector */
1379 uint64_t size; /**< active device size */
1380 uint32_t flags; /**< activation flags */
1384 * Receive runtime attributes of active crypt device.
1386 * @param cd crypt device handle (can be @e NULL)
1387 * @param name name of active device
1388 * @param cad preallocated active device attributes to fill
1390 * @return @e 0 on success or negative errno value otherwise
1393 int crypt_get_active_device(struct crypt_device *cd,
1395 struct crypt_active_device *cad);
1398 * Get detected number of integrity failures.
1400 * @param cd crypt device handle (can be @e NULL)
1401 * @param name name of active device
1403 * @return number of integrity failures or @e 0 otherwise
1406 uint64_t crypt_get_active_integrity_failures(struct crypt_device *cd,
1411 * @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
1412 * @addtogroup crypt-pflags
1417 * LUKS2 header requirements
1419 /** Unfinished offline reencryption */
1420 #define CRYPT_REQUIREMENT_OFFLINE_REENCRYPT (UINT32_C(1) << 0)
1421 /** Online reencryption in-progress */
1422 #define CRYPT_REQUIREMENT_ONLINE_REENCRYPT (UINT32_C(1) << 1)
1423 /** unknown requirement in header (output only) */
1424 #define CRYPT_REQUIREMENT_UNKNOWN (UINT32_C(1) << 31)
1427 * Persistent flags type
1430 CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
1431 CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
1435 * Set persistent flags.
1437 * @param cd crypt device handle (can be @e NULL)
1438 * @param type type to set (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1439 * @param flags flags to set
1441 * @return @e 0 on success or negative errno value otherwise
1443 * @note Valid only for LUKS2.
1445 * @note Not all activation flags can be stored. Only ALLOW_DISCARD,
1446 * SAME_CPU_CRYPT, SUBMIT_FROM_CRYPT_CPU and NO_JOURNAL can be
1447 * stored persistently.
1449 * @note Only requirements flags recognised by current library may be set.
1450 * CRYPT_REQUIREMENT_UNKNOWN is illegal (output only) in set operation.
1452 int crypt_persistent_flags_set(struct crypt_device *cd,
1453 crypt_flags_type type,
1457 * Get persistent flags stored in header.
1459 * @param cd crypt device handle (can be @e NULL)
1460 * @param type flags type to retrieve (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
1461 * @param flags reference to output variable
1463 * @return @e 0 on success or negative errno value otherwise
1465 int crypt_persistent_flags_get(struct crypt_device *cd,
1466 crypt_flags_type type,
1471 * @defgroup crypt-activation Device activation
1472 * @addtogroup crypt-activation
1477 * Activate device or check passphrase.
1479 * @param cd crypt device handle
1480 * @param name name of device to create, if @e NULL only check passphrase
1481 * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
1482 * @param passphrase passphrase used to unlock volume key
1483 * @param passphrase_size size of @e passphrase
1484 * @param flags activation flags
1486 * @return unlocked key slot number or negative errno otherwise.
1488 int crypt_activate_by_passphrase(struct crypt_device *cd,
1491 const char *passphrase,
1492 size_t passphrase_size,
1496 * Activate device or check using key file.
1498 * @param cd crypt device handle
1499 * @param name name of device to create, if @e NULL only check keyfile
1500 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1501 * @param keyfile key file used to unlock volume key
1502 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
1503 * @param keyfile_offset number of bytes to skip at start of keyfile
1504 * @param flags activation flags
1506 * @return unlocked key slot number or negative errno otherwise.
1508 int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
1511 const char *keyfile,
1512 size_t keyfile_size,
1513 uint64_t keyfile_offset,
1517 * Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
1519 int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
1522 const char *keyfile,
1523 size_t keyfile_size,
1524 size_t keyfile_offset,
1528 * Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
1530 int crypt_activate_by_keyfile(struct crypt_device *cd,
1533 const char *keyfile,
1534 size_t keyfile_size,
1538 * Activate device using provided volume key.
1540 * @param cd crypt device handle
1541 * @param name name of device to create, if @e NULL only check volume key
1542 * @param volume_key provided volume key (or @e NULL to use internal)
1543 * @param volume_key_size size of volume_key
1544 * @param flags activation flags
1546 * @return @e 0 on success or negative errno value otherwise.
1548 * @note If @e NULL is used for volume_key, device has to be initialized
1549 * by previous operation (like @ref crypt_format
1550 * or @ref crypt_init_by_name)
1551 * @note For VERITY the volume key means root hash required for activation.
1552 * Because kernel dm-verity is always read only, you have to provide
1553 * CRYPT_ACTIVATE_READONLY flag always.
1554 * @note For TCRYPT the volume key should be always NULL
1555 * the key from decrypted header is used instead.
1557 int crypt_activate_by_volume_key(struct crypt_device *cd,
1559 const char *volume_key,
1560 size_t volume_key_size,
1564 * Activate VERITY device using provided key and optional signature).
1566 * @param cd crypt device handle
1567 * @param name name of device to create
1568 * @param volume_key provided volume key
1569 * @param volume_key_size size of volume_key
1570 * @param signature buffer with signature for the key
1571 * @param signature_size bsize of signature buffer
1572 * @param flags activation flags
1574 * @return @e 0 on success or negative errno value otherwise.
1576 * @note For VERITY the volume key means root hash required for activation.
1577 * Because kernel dm-verity is always read only, you have to provide
1578 * CRYPT_ACTIVATE_READONLY flag always.
1580 int crypt_activate_by_signed_key(struct crypt_device *cd,
1582 const char *volume_key,
1583 size_t volume_key_size,
1584 const char *signature,
1585 size_t signature_size,
1589 * Activate device using passphrase stored in kernel keyring.
1591 * @param cd crypt device handle
1592 * @param name name of device to create, if @e NULL only check passphrase in keyring
1593 * @param key_description kernel keyring key description library should look
1595 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1596 * @param flags activation flags
1598 * @return @e unlocked keyslot number on success or negative errno value otherwise.
1600 * @note Keyslot passphrase must be stored in 'user' key type
1601 * and the key has to be reachable for process context
1602 * on behalf of which this function is called.
1604 int crypt_activate_by_keyring(struct crypt_device *cd,
1606 const char *key_description,
1610 /** lazy deactivation - remove once last user releases it */
1611 #define CRYPT_DEACTIVATE_DEFERRED (UINT32_C(1) << 0)
1612 /** force deactivation - if the device is busy, it is replaced by error device */
1613 #define CRYPT_DEACTIVATE_FORCE (UINT32_C(1) << 1)
1614 /** if set, remove lazy deactivation */
1615 #define CRYPT_DEACTIVATE_DEFERRED_CANCEL (UINT32_C(1) << 2)
1618 * Deactivate crypt device. This function tries to remove active device-mapper
1619 * mapping from kernel. Also, sensitive data like the volume key are removed from
1622 * @param cd crypt device handle, can be @e NULL
1623 * @param name name of device to deactivate
1624 * @param flags deactivation flags
1626 * @return @e 0 on success or negative errno value otherwise.
1629 int crypt_deactivate_by_name(struct crypt_device *cd,
1634 * Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
1636 int crypt_deactivate(struct crypt_device *cd, const char *name);
1640 * @defgroup crypt-key Volume Key manipulation
1641 * @addtogroup crypt-key
1646 * Get volume key from crypt device.
1648 * @param cd crypt device handle
1649 * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
1650 * @param volume_key buffer for volume key
1651 * @param volume_key_size on input, size of buffer @e volume_key,
1652 * on output size of @e volume_key
1653 * @param passphrase passphrase used to unlock volume key
1654 * @param passphrase_size size of @e passphrase
1656 * @return unlocked key slot number or negative errno otherwise.
1658 * @note For TCRYPT cipher chain is the volume key concatenated
1659 * for all ciphers in chain.
1660 * @note For VERITY the volume key means root hash used for activation.
1661 * @note For LUKS devices, if passphrase is @e NULL and volume key is cached in
1662 * device context it returns the volume key generated in preceding
1663 * @link crypt_format @endlink call.
1665 int crypt_volume_key_get(struct crypt_device *cd,
1668 size_t *volume_key_size,
1669 const char *passphrase,
1670 size_t passphrase_size);
1673 * Get volume key from crypt device by keyslot context.
1675 * @param cd crypt device handle
1676 * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
1677 * @param volume_key buffer for volume key
1678 * @param volume_key_size on input, size of buffer @e volume_key,
1679 * on output size of @e volume_key
1680 * @param kc keyslot context used to unlock volume key
1682 * @return unlocked key slot number or negative errno otherwise.
1684 * @note See @link crypt-keyslot-context-types @endlink for info on keyslot
1685 * context initialization.
1686 * @note For TCRYPT cipher chain is the volume key concatenated
1687 * for all ciphers in chain (kc may be NULL).
1688 * @note For VERITY the volume key means root hash used for activation
1690 * @note For LUKS devices, if kc is @e NULL and volume key is cached in
1691 * device context it returns the volume key generated in preceding
1692 * @link crypt_format @endlink call.
1693 * @note @link CRYPT_KC_TYPE_TOKEN @endlink keyslot context is usable only with LUKS2 devices.
1694 * @note @link CRYPT_KC_TYPE_KEY @endlink keyslot context can not be used.
1695 * @note To get LUKS2 unbound key, keyslot parameter must not be @e CRYPT_ANY_SLOT.
1696 * @note EPERM errno means provided keyslot context could not unlock any (or selected)
1698 * @note ENOENT errno means no LUKS keyslot is available to retrieve volume key from
1699 * and there's no cached volume key in device handle.
1701 int crypt_volume_key_get_by_keyslot_context(struct crypt_device *cd,
1704 size_t *volume_key_size,
1705 struct crypt_keyslot_context *kc);
1708 * Verify that provided volume key is valid for crypt device.
1710 * @param cd crypt device handle
1711 * @param volume_key provided volume key
1712 * @param volume_key_size size of @e volume_key
1714 * @return @e 0 on success or negative errno value otherwise.
1716 * @note Negative EPERM return value means that passed volume_key
1717 * did not pass digest verification routine (not a valid volume
1720 int crypt_volume_key_verify(struct crypt_device *cd,
1721 const char *volume_key,
1722 size_t volume_key_size);
1726 * @defgroup crypt-devstat Crypt and Verity device status
1727 * @addtogroup crypt-devstat
1735 CRYPT_INVALID, /**< device mapping is invalid in this context */
1736 CRYPT_INACTIVE, /**< no such mapped device */
1737 CRYPT_ACTIVE, /**< device is active */
1738 CRYPT_BUSY /**< device is active and has open count > 0 */
1739 } crypt_status_info;
1742 * Get status info about device name.
1744 * @param cd crypt device handle, can be @e NULL
1745 * @param name crypt device name
1747 * @return value defined by crypt_status_info.
1750 crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
1753 * Dump text-formatted information about crypt or verity device to log output.
1755 * @param cd crypt device handle
1757 * @return @e 0 on success or negative errno value otherwise.
1759 int crypt_dump(struct crypt_device *cd);
1762 * Dump JSON-formatted information about LUKS2 device
1764 * @param cd crypt device handle (only LUKS2 format supported)
1765 * @param json buffer with JSON, if NULL use log callback for output
1766 * @param flags dump flags (reserved)
1768 * @return @e 0 on success or negative errno value otherwise.
1770 int crypt_dump_json(struct crypt_device *cd, const char **json, uint32_t flags);
1773 * Get cipher used in device.
1775 * @param cd crypt device handle
1777 * @return used cipher, e.g. "aes" or @e NULL otherwise
1780 const char *crypt_get_cipher(struct crypt_device *cd);
1783 * Get cipher mode used in device.
1785 * @param cd crypt device handle
1787 * @return used cipher mode e.g. "xts-plain" or @e otherwise
1790 const char *crypt_get_cipher_mode(struct crypt_device *cd);
1795 * @param cd crypt device handle
1797 * @return device UUID or @e NULL if not set
1800 const char *crypt_get_uuid(struct crypt_device *cd);
1803 * Get path to underlying device.
1805 * @param cd crypt device handle
1807 * @return path to underlying device name
1810 const char *crypt_get_device_name(struct crypt_device *cd);
1813 * Get path to detached metadata device or @e NULL if it is not detached.
1815 * @param cd crypt device handle
1817 * @return path to underlying device name
1820 const char *crypt_get_metadata_device_name(struct crypt_device *cd);
1823 * Get device offset in 512-bytes sectors where real data starts (on underlying device).
1825 * @param cd crypt device handle
1827 * @return device offset in sectors
1830 uint64_t crypt_get_data_offset(struct crypt_device *cd);
1833 * Get IV offset in 512-bytes sectors (skip).
1835 * @param cd crypt device handle
1840 uint64_t crypt_get_iv_offset(struct crypt_device *cd);
1843 * Get size (in bytes) of volume key for crypt device.
1845 * @param cd crypt device handle
1847 * @return volume key size
1849 * @note For LUKS2, this function can be used only if there is at least
1850 * one keyslot assigned to data segment.
1852 int crypt_get_volume_key_size(struct crypt_device *cd);
1855 * Get size (in bytes) of encryption sector for crypt device.
1857 * @param cd crypt device handle
1859 * @return sector size
1862 int crypt_get_sector_size(struct crypt_device *cd);
1865 * Check if initialized LUKS context uses detached header
1866 * (LUKS header located on a different device than data.)
1868 * @param cd crypt device handle
1870 * @return @e 1 if detached header is used, @e 0 if not
1871 * or negative errno value otherwise.
1873 * @note This is a runtime attribute, it does not say
1874 * if a LUKS device requires detached header.
1875 * This function works only with LUKS devices.
1877 int crypt_header_is_detached(struct crypt_device *cd);
1880 * Get device parameters for VERITY device.
1882 * @param cd crypt device handle
1883 * @param vp verity device info
1885 * @e 0 on success or negative errno value otherwise.
1888 int crypt_get_verity_info(struct crypt_device *cd,
1889 struct crypt_params_verity *vp);
1892 * Get device parameters for INTEGRITY device.
1894 * @param cd crypt device handle
1895 * @param ip verity device info
1897 * @e 0 on success or negative errno value otherwise.
1900 int crypt_get_integrity_info(struct crypt_device *cd,
1901 struct crypt_params_integrity *ip);
1905 * @defgroup crypt-benchmark Benchmarking
1906 * Benchmarking of algorithms
1907 * @addtogroup crypt-benchmark
1912 * Informational benchmark for ciphers.
1914 * @param cd crypt device handle
1915 * @param cipher (e.g. "aes")
1916 * @param cipher_mode (e.g. "xts"), IV generator is ignored
1917 * @param volume_key_size size of volume key in bytes
1918 * @param iv_size size of IV in bytes
1919 * @param buffer_size size of encryption buffer in bytes used in test
1920 * @param encryption_mbs measured encryption speed in MiB/s
1921 * @param decryption_mbs measured decryption speed in MiB/s
1923 * @return @e 0 on success or negative errno value otherwise.
1925 * @note If encryption_buffer_size is too small and encryption time
1926 * cannot be properly measured, -ERANGE is returned.
1928 int crypt_benchmark(struct crypt_device *cd,
1930 const char *cipher_mode,
1931 size_t volume_key_size,
1934 double *encryption_mbs,
1935 double *decryption_mbs);
1938 * Informational benchmark for PBKDF.
1940 * @param cd crypt device handle
1941 * @param pbkdf PBKDF parameters
1942 * @param password password for benchmark
1943 * @param password_size size of password
1944 * @param salt salt for benchmark
1945 * @param salt_size size of salt
1946 * @param volume_key_size output volume key size
1947 * @param progress callback function
1948 * @param usrptr provided identification in callback
1950 * @return @e 0 on success or negative errno value otherwise.
1952 int crypt_benchmark_pbkdf(struct crypt_device *cd,
1953 struct crypt_pbkdf_type *pbkdf,
1954 const char *password,
1955 size_t password_size,
1958 size_t volume_key_size,
1959 int (*progress)(uint32_t time_ms, void *usrptr),
1964 * @addtogroup crypt-keyslot
1969 * Crypt keyslot info
1972 CRYPT_SLOT_INVALID, /**< invalid keyslot */
1973 CRYPT_SLOT_INACTIVE, /**< keyslot is inactive (free) */
1974 CRYPT_SLOT_ACTIVE, /**< keyslot is active (used) */
1975 CRYPT_SLOT_ACTIVE_LAST,/**< keylost is active (used)
1976 * and last used at the same time */
1977 CRYPT_SLOT_UNBOUND /**< keyslot is active and not bound
1978 * to any crypt segment (LUKS2 only) */
1979 } crypt_keyslot_info;
1982 * Get information about particular key slot.
1984 * @param cd crypt device handle
1985 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
1987 * @return value defined by crypt_keyslot_info
1990 crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
1993 * Crypt keyslot priority
1996 CRYPT_SLOT_PRIORITY_INVALID =-1, /**< no such slot */
1997 CRYPT_SLOT_PRIORITY_IGNORE = 0, /**< CRYPT_ANY_SLOT will ignore it for open */
1998 CRYPT_SLOT_PRIORITY_NORMAL = 1, /**< default priority, tried after preferred */
1999 CRYPT_SLOT_PRIORITY_PREFER = 2, /**< will try to open first */
2000 } crypt_keyslot_priority;
2003 * Get keyslot priority (LUKS2)
2005 * @param cd crypt device handle
2006 * @param keyslot keyslot number
2008 * @return value defined by crypt_keyslot_priority
2010 crypt_keyslot_priority crypt_keyslot_get_priority(struct crypt_device *cd, int keyslot);
2013 * Set keyslot priority (LUKS2)
2015 * @param cd crypt device handle
2016 * @param keyslot keyslot number
2017 * @param priority priority defined in crypt_keyslot_priority
2019 * @return @e 0 on success or negative errno value otherwise.
2021 int crypt_keyslot_set_priority(struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority);
2024 * Get number of keyslots supported for device type.
2026 * @param type crypt device type
2028 * @return slot count or negative errno otherwise if device
2029 * doesn't not support keyslots.
2031 int crypt_keyslot_max(const char *type);
2034 * Get keyslot area pointers (relative to metadata device).
2036 * @param cd crypt device handle
2037 * @param keyslot keyslot number
2038 * @param offset offset on metadata device (in bytes)
2039 * @param length length of keyslot area (in bytes)
2041 * @return @e 0 on success or negative errno value otherwise.
2044 int crypt_keyslot_area(struct crypt_device *cd,
2050 * Get size (in bytes) of stored key in particular keyslot.
2051 * Use for LUKS2 unbound keyslots, for other keyslots it is the same as @ref crypt_get_volume_key_size
2053 * @param cd crypt device handle
2054 * @param keyslot keyslot number
2056 * @return volume key size or negative errno value otherwise.
2059 int crypt_keyslot_get_key_size(struct crypt_device *cd, int keyslot);
2062 * Get cipher and key size for keyslot encryption.
2063 * Use for LUKS2 keyslot to set different encryption type than for data encryption.
2064 * Parameters will be used for next keyslot operations.
2066 * @param cd crypt device handle
2067 * @param keyslot keyslot number of CRYPT_ANY_SLOT for default
2068 * @param key_size encryption key size (in bytes)
2070 * @return cipher specification on success or @e NULL.
2072 * @note This is the encryption of keyslot itself, not the data encryption algorithm!
2074 const char *crypt_keyslot_get_encryption(struct crypt_device *cd, int keyslot, size_t *key_size);
2077 * Get PBKDF parameters for keyslot.
2079 * @param cd crypt device handle
2080 * @param keyslot keyslot number
2081 * @param pbkdf struct with returned PBKDF parameters
2083 * @return @e 0 on success or negative errno value otherwise.
2085 int crypt_keyslot_get_pbkdf(struct crypt_device *cd, int keyslot, struct crypt_pbkdf_type *pbkdf);
2088 * Set encryption for keyslot.
2089 * Use for LUKS2 keyslot to set different encryption type than for data encryption.
2090 * Parameters will be used for next keyslot operations that create or change a keyslot.
2092 * @param cd crypt device handle
2093 * @param cipher (e.g. "aes-xts-plain64")
2094 * @param key_size encryption key size (in bytes)
2096 * @return @e 0 on success or negative errno value otherwise.
2098 * @note To reset to default keyslot encryption (the same as for data)
2099 * set cipher to NULL and key size to 0.
2101 int crypt_keyslot_set_encryption(struct crypt_device *cd,
2106 * Get directory where mapped crypt devices are created
2108 * @return the directory path
2110 const char *crypt_get_dir(void);
2115 * @defgroup crypt-backup Device metadata backup
2116 * @addtogroup crypt-backup
2120 * Backup header and keyslots to file.
2122 * @param cd crypt device handle
2123 * @param requested_type @link crypt-type @endlink or @e NULL for all known
2124 * @param backup_file file to backup header to
2126 * @return @e 0 on success or negative errno value otherwise.
2129 int crypt_header_backup(struct crypt_device *cd,
2130 const char *requested_type,
2131 const char *backup_file);
2134 * Restore header and keyslots from backup file.
2136 * @param cd crypt device handle
2137 * @param requested_type @link crypt-type @endlink or @e NULL for all known
2138 * @param backup_file file to restore header from
2140 * @return @e 0 on success or negative errno value otherwise.
2143 int crypt_header_restore(struct crypt_device *cd,
2144 const char *requested_type,
2145 const char *backup_file);
2149 * @defgroup crypt-dbg Library debug level
2150 * Set library debug level
2151 * @addtogroup crypt-dbg
2156 #define CRYPT_DEBUG_ALL -1
2157 /** Debug all with additional JSON dump (for LUKS2) */
2158 #define CRYPT_DEBUG_JSON -2
2160 #define CRYPT_DEBUG_NONE 0
2163 * Set the debug level for library
2165 * @param level debug level
2168 void crypt_set_debug_level(int level);
2172 * @defgroup crypt-keyfile Function to read keyfile
2173 * @addtogroup crypt-keyfile
2180 * @param cd crypt device handle
2181 * @param keyfile keyfile to read
2182 * @param key buffer for key
2183 * @param key_size_read size of read key
2184 * @param keyfile_offset key offset in keyfile
2185 * @param key_size exact key length to read from file or 0
2186 * @param flags keyfile read flags
2188 * @return @e 0 on success or negative errno value otherwise.
2190 * @note If key_size is set to zero we read internal max length
2191 * and actual size read is returned via key_size_read parameter.
2193 int crypt_keyfile_device_read(struct crypt_device *cd,
2194 const char *keyfile,
2195 char **key, size_t *key_size_read,
2196 uint64_t keyfile_offset,
2201 * Backward compatible crypt_keyfile_device_read() (with size_t offset).
2203 int crypt_keyfile_read(struct crypt_device *cd,
2204 const char *keyfile,
2205 char **key, size_t *key_size_read,
2206 size_t keyfile_offset,
2210 /** Read key only to the first end of line (\\n). */
2211 #define CRYPT_KEYFILE_STOP_EOL (UINT32_C(1) << 0)
2215 * @defgroup crypt-wipe Function to wipe device
2216 * @addtogroup crypt-wipe
2223 CRYPT_WIPE_ZERO, /**< Fill with zeroes */
2224 CRYPT_WIPE_RANDOM, /**< Use RNG to fill data */
2225 CRYPT_WIPE_ENCRYPTED_ZERO, /**< Obsolete, same as CRYPT_WIPE_RANDOM */
2226 CRYPT_WIPE_SPECIAL, /**< Compatibility only, do not use (Gutmann method) */
2227 } crypt_wipe_pattern;
2230 * Wipe/Fill (part of) a device with the selected pattern.
2232 * @param cd crypt device handle
2233 * @param dev_path path to device to wipe or @e NULL if data device should be used
2234 * @param pattern selected wipe pattern
2235 * @param offset offset on device (in bytes)
2236 * @param length length of area to be wiped (in bytes)
2237 * @param wipe_block_size used block for wiping (one step) (in bytes)
2238 * @param flags wipe flags
2239 * @param progress callback function called after each @e wipe_block_size or @e NULL
2240 * @param usrptr provided identification in callback
2242 * @return @e 0 on success or negative errno value otherwise.
2244 * @note A @e progress callback can interrupt wipe process by returning non-zero code.
2246 * @note If the error values is -EIO or -EINTR, some part of the device could
2247 * be overwritten. Other error codes (-EINVAL, -ENOMEM) means that no IO was performed.
2249 int crypt_wipe(struct crypt_device *cd,
2250 const char *dev_path, /* if null, use data device */
2251 crypt_wipe_pattern pattern,
2254 size_t wipe_block_size,
2256 int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
2260 /** Use direct-io */
2261 #define CRYPT_WIPE_NO_DIRECT_IO (UINT32_C(1) << 0)
2265 * @defgroup crypt-tokens LUKS2 token wrapper access
2267 * Utilities for handling tokens LUKS2
2268 * Token is a device or a method how to read password for particular keyslot
2269 * automatically. It can be chunk of data stored on hardware token or
2270 * just a metadata how to generate the password.
2272 * @addtogroup crypt-tokens
2277 * Get number of tokens supported for device type.
2279 * @param type crypt device type
2281 * @return token count or negative errno otherwise if device
2282 * doesn't not support tokens.
2284 * @note Real number of supported tokens for a particular device depends
2285 * on usable metadata area size.
2287 int crypt_token_max(const char *type);
2289 /** Iterate through all tokens */
2290 #define CRYPT_ANY_TOKEN -1
2293 * Get content of a token definition in JSON format.
2295 * @param cd crypt device handle
2296 * @param token token id
2297 * @param json buffer with JSON
2299 * @return allocated token id or negative errno otherwise.
2301 int crypt_token_json_get(struct crypt_device *cd,
2306 * Store content of a token definition in JSON format.
2308 * @param cd crypt device handle
2309 * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
2310 * @param json buffer with JSON or @e NULL to remove token
2312 * @return allocated token id or negative errno otherwise.
2314 * @note The buffer must be in proper JSON format and must contain at least
2315 * string "type" with slot type and an array of string names "keyslots".
2316 * Keyslots array contains assignments to particular slots and can be empty.
2318 int crypt_token_json_set(struct crypt_device *cd,
2326 CRYPT_TOKEN_INVALID, /**< token is invalid */
2327 CRYPT_TOKEN_INACTIVE, /**< token is empty (free) */
2328 CRYPT_TOKEN_INTERNAL, /**< active internal token with driver */
2329 CRYPT_TOKEN_INTERNAL_UNKNOWN, /**< active internal token (reserved name) with missing token driver */
2330 CRYPT_TOKEN_EXTERNAL, /**< active external (user defined) token with driver */
2331 CRYPT_TOKEN_EXTERNAL_UNKNOWN, /**< active external (user defined) token with missing token driver */
2335 * Get info for specific token.
2337 * @param cd crypt device handle
2338 * @param token existing token id
2339 * @param type pointer for returned type string
2341 * @return token status info. For any returned status (besides CRYPT_TOKEN_INVALID
2342 * and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will
2343 * contain address of type string.
2345 * @note if required, create a copy of string referenced in *type before calling next
2346 * libcryptsetup API function. The reference may become invalid.
2348 crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
2351 * LUKS2 keyring token parameters.
2353 * @see crypt_token_builtin_set
2356 struct crypt_token_params_luks2_keyring {
2357 const char *key_description; /**< Reference in keyring */
2361 * Create a new luks2 keyring token.
2363 * @param cd crypt device handle
2364 * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
2365 * @param params luks2 keyring token params
2367 * @return allocated token id or negative errno otherwise.
2370 int crypt_token_luks2_keyring_set(struct crypt_device *cd,
2372 const struct crypt_token_params_luks2_keyring *params);
2375 * Get LUKS2 keyring token params
2377 * @param cd crypt device handle
2378 * @param token existing luks2 keyring token id
2379 * @param params returned luks2 keyring token params
2381 * @return allocated token id or negative errno otherwise.
2383 * @note do not call free() on params members. Members are valid only
2384 * until next libcryptsetup function is called.
2386 int crypt_token_luks2_keyring_get(struct crypt_device *cd,
2388 struct crypt_token_params_luks2_keyring *params);
2391 * Assign a token to particular keyslot.
2392 * (There can be more keyslots assigned to one token id.)
2394 * @param cd crypt device handle
2395 * @param token token id
2396 * @param keyslot keyslot to be assigned to token (CRYPT_ANY SLOT
2397 * assigns all active keyslots to token)
2399 * @return allocated token id or negative errno otherwise.
2401 int crypt_token_assign_keyslot(struct crypt_device *cd,
2406 * Unassign a token from particular keyslot.
2407 * (There can be more keyslots assigned to one token id.)
2409 * @param cd crypt device handle
2410 * @param token token id
2411 * @param keyslot keyslot to be unassigned from token (CRYPT_ANY SLOT
2412 * unassigns all active keyslots from token)
2414 * @return allocated token id or negative errno otherwise.
2416 int crypt_token_unassign_keyslot(struct crypt_device *cd,
2421 * Get info about token assignment to particular keyslot.
2423 * @param cd crypt device handle
2424 * @param token token id
2425 * @param keyslot keyslot
2427 * @return 0 on success (token exists and is assigned to the keyslot),
2428 * -ENOENT if token is not assigned to a keyslot (token, keyslot
2429 * or both may be inactive) or other negative errno otherwise.
2431 int crypt_token_is_assigned(struct crypt_device *cd,
2436 * Token handler open function prototype.
2437 * This function retrieves password from a token and return allocated buffer
2438 * containing this password. This buffer has to be deallocated by calling
2439 * free() function and content should be wiped before deallocation.
2441 * @param cd crypt device handle
2442 * @param token token id
2443 * @param buffer returned allocated buffer with password
2444 * @param buffer_len length of the buffer
2445 * @param usrptr user data in @link crypt_activate_by_token @endlink
2447 * @return 0 on success (token passed LUKS2 keyslot passphrase in buffer) or
2448 * negative errno otherwise.
2450 * @note Negative ENOANO errno means that token is PIN protected and caller should
2451 * use @link crypt_activate_by_token_pin @endlink with PIN provided.
2453 * @note Negative EAGAIN errno means token handler requires additional hardware
2454 * not present in the system.
2456 typedef int (*crypt_token_open_func) (
2457 struct crypt_device *cd,
2464 * Token handler open with passphrase/PIN function prototype.
2465 * This function retrieves password from a token and return allocated buffer
2466 * containing this password. This buffer has to be deallocated by calling
2467 * free() function and content should be wiped before deallocation.
2469 * @param cd crypt device handle
2470 * @param token token id
2471 * @param pin passphrase (or PIN) to unlock token (may be binary data)
2472 * @param pin_size size of @e pin
2473 * @param buffer returned allocated buffer with password
2474 * @param buffer_len length of the buffer
2475 * @param usrptr user data in @link crypt_activate_by_token @endlink
2477 * @return 0 on success (token passed LUKS2 keyslot passphrase in buffer) or
2478 * negative errno otherwise.
2480 * @note Negative ENOANO errno means that token is PIN protected and PIN was
2483 * @note Negative EAGAIN errno means token handler requires additional hardware
2484 * not present in the system.
2486 typedef int (*crypt_token_open_pin_func) (
2487 struct crypt_device *cd,
2496 * Token handler buffer free function prototype.
2497 * This function is used by library to free the buffer with keyslot
2498 * passphrase when it's no longer needed. If not defined the library
2499 * overwrites buffer with zeroes and call free().
2501 * @param buffer the buffer with keyslot passphrase
2502 * @param buffer_len the buffer length
2504 typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
2507 * Token handler validate function prototype.
2508 * This function validates JSON representation of user defined token for additional data
2509 * specific for its token type. If defined in the handler, it's called
2510 * during @link crypt_activate_by_token @endlink. It may also be called during
2511 * @link crypt_token_json_set @endlink when appropriate token handler was registered before
2512 * with @link crypt_token_register @endlink.
2514 * @param cd crypt device handle
2515 * @param json buffer with JSON
2517 typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
2520 * Token handler dump function prototype.
2521 * This function is supposed to print token implementation specific details. It gets
2522 * called during @link crypt_dump @endlink if token handler was registered before.
2524 * @param cd crypt device handle
2525 * @param json buffer with token JSON
2527 * @note dump implementations are advised to use @link crypt_log @endlink function
2528 * to dump token details.
2530 typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
2533 * Token handler version function prototype.
2534 * This function is supposed to return pointer to version string information.
2536 * @note The returned string is advised to contain only version.
2537 * For example '1.0.0' or 'v1.2.3.4'.
2540 typedef const char * (*crypt_token_version_func) (void);
2546 const char *name; /**< token handler name */
2547 crypt_token_open_func open; /**< token handler open function */
2548 crypt_token_buffer_free_func buffer_free; /**< token handler buffer_free function (optional) */
2549 crypt_token_validate_func validate; /**< token handler validate function (optional) */
2550 crypt_token_dump_func dump; /**< token handler dump function (optional) */
2551 } crypt_token_handler;
2554 * Register token handler
2556 * @param handler token handler to register
2558 * @return @e 0 on success or negative errno value otherwise.
2560 int crypt_token_register(const crypt_token_handler *handler);
2563 * Report configured path where library searches for external token handlers
2565 * @return @e absolute path when external tokens are enabled or @e NULL otherwise.
2567 const char *crypt_token_external_path(void);
2570 * Disable external token handlers (plugins) support
2571 * If disabled, it cannot be enabled again.
2573 void crypt_token_external_disable(void);
2575 /** ABI version for external token in libcryptsetup-token-[name].so */
2576 #define CRYPT_TOKEN_ABI_VERSION1 "CRYPTSETUP_TOKEN_1.0"
2578 /** open by token - ABI exported symbol for external token (mandatory) */
2579 #define CRYPT_TOKEN_ABI_OPEN "cryptsetup_token_open"
2580 /** open by token with PIN - ABI exported symbol for external token */
2581 #define CRYPT_TOKEN_ABI_OPEN_PIN "cryptsetup_token_open_pin"
2582 /** deallocate callback - ABI exported symbol for external token */
2583 #define CRYPT_TOKEN_ABI_BUFFER_FREE "cryptsetup_token_buffer_free"
2584 /** validate token metadata - ABI exported symbol for external token */
2585 #define CRYPT_TOKEN_ABI_VALIDATE "cryptsetup_token_validate"
2586 /** dump token metadata - ABI exported symbol for external token */
2587 #define CRYPT_TOKEN_ABI_DUMP "cryptsetup_token_dump"
2588 /** token version - ABI exported symbol for external token */
2589 #define CRYPT_TOKEN_ABI_VERSION "cryptsetup_token_version"
2592 * Activate device or check key using a token.
2594 * @param cd crypt device handle
2595 * @param name name of device to create, if @e NULL only check token
2596 * @param token requested token to check or CRYPT_ANY_TOKEN to check all
2597 * @param usrptr provided identification in callback
2598 * @param flags activation flags
2600 * @return unlocked key slot number or negative errno otherwise.
2602 * @note EPERM errno means token provided passphrase successfully, but
2603 * passphrase did not unlock any keyslot associated with the token.
2605 * @note ENOENT errno means no token (or subsequently assigned keyslot) was
2606 * eligible to unlock device.
2608 * @note ENOANO errno means that token is PIN protected and you should call
2609 * @link crypt_activate_by_token_pin @endlink with PIN
2611 * @note Negative EAGAIN errno means token handler requires additional hardware
2612 * not present in the system.
2614 * @note with @e token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop
2615 * to unlock device using any available token. It may happen that various token handlers
2616 * return different error codes. At the end loop returns error codes in the following
2617 * order (from the most significant to the least) any negative errno except those
2618 * listed below, non negative token id (success), -ENOANO, -EAGAIN, -EPERM, -ENOENT.
2620 int crypt_activate_by_token(struct crypt_device *cd,
2627 * Activate device or check key using a token with PIN.
2629 * @param cd crypt device handle
2630 * @param name name of device to create, if @e NULL only check token
2631 * @param type restrict type of token, if @e NULL all types are allowed
2632 * @param token requested token to check or CRYPT_ANY_TOKEN to check all
2633 * @param pin passphrase (or PIN) to unlock token (may be binary data)
2634 * @param pin_size size of @e pin
2635 * @param usrptr provided identification in callback
2636 * @param flags activation flags
2638 * @return unlocked key slot number or negative errno otherwise.
2640 * @note EPERM errno means token provided passphrase successfully, but
2641 * passphrase did not unlock any keyslot associated with the token.
2643 * @note ENOENT errno means no token (or subsequently assigned keyslot) was
2644 * eligible to unlock device.
2646 * @note ENOANO errno means that token is PIN protected and was either missing
2649 * @note Negative EAGAIN errno means token handler requires additional hardware
2650 * not present in the system.
2652 * @note with @e token set to CRYPT_ANY_TOKEN libcryptsetup runs best effort loop
2653 * to unlock device using any available token. It may happen that various token handlers
2654 * return different error codes. At the end loop returns error codes in the following
2655 * order (from the most significant to the least) any negative errno except those
2656 * listed below, non negative token id (success), -ENOANO, -EAGAIN, -EPERM, -ENOENT.
2658 int crypt_activate_by_token_pin(struct crypt_device *cd,
2669 * @defgroup crypt-reencryption LUKS2 volume reencryption support
2671 * Set of functions to handling LUKS2 volume reencryption
2673 * @addtogroup crypt-reencryption
2677 /** Initialize reencryption metadata but do not run reencryption yet. (in) */
2678 #define CRYPT_REENCRYPT_INITIALIZE_ONLY (UINT32_C(1) << 0)
2679 /** Move the first segment, used only with datashift resilience mode
2680 * and subvariants. (in/out) */
2681 #define CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT (UINT32_C(1) << 1)
2682 /** Resume already initialized reencryption only. (in) */
2683 #define CRYPT_REENCRYPT_RESUME_ONLY (UINT32_C(1) << 2)
2684 /** Run reencryption recovery only. (in) */
2685 #define CRYPT_REENCRYPT_RECOVERY (UINT32_C(1) << 3)
2686 /** Reencryption requires metadata protection. (in/out) */
2687 #define CRYPT_REENCRYPT_REPAIR_NEEDED (UINT32_C(1) << 4)
2690 * Reencryption direction
2693 CRYPT_REENCRYPT_FORWARD = 0, /**< forward direction */
2694 CRYPT_REENCRYPT_BACKWARD /**< backward direction */
2695 } crypt_reencrypt_direction_info;
2701 CRYPT_REENCRYPT_REENCRYPT = 0, /**< Reencryption mode */
2702 CRYPT_REENCRYPT_ENCRYPT, /**< Encryption mode */
2703 CRYPT_REENCRYPT_DECRYPT, /**< Decryption mode */
2704 } crypt_reencrypt_mode_info;
2707 * LUKS2 reencryption options.
2709 struct crypt_params_reencrypt {
2710 crypt_reencrypt_mode_info mode; /**< Reencryption mode, immutable after first init. */
2711 crypt_reencrypt_direction_info direction; /**< Reencryption direction, immutable after first init. */
2712 const char *resilience; /**< Resilience mode: "none", "checksum", "journal", "datashift",
2713 "datashift-checksum" or "datashift-journal".
2714 "datashift" mode is immutable, "datashift-" subvariant can be only
2715 changed to other "datashift-" subvariant */
2716 const char *hash; /**< Used hash for "checksum" resilience type, ignored otherwise. */
2717 uint64_t data_shift; /**< Used in "datashift" mode (and subvariants), must be non-zero,
2718 immutable after first init. */
2719 uint64_t max_hotzone_size; /**< Maximum hotzone size (may be lowered by library). For "datashift-" subvariants
2720 it is used to set size of moved segment (decryption only). */
2721 uint64_t device_size; /**< Reencrypt only initial part of the data device. */
2722 const struct crypt_params_luks2 *luks2; /**< LUKS2 parameters for the final reencryption volume.*/
2723 uint32_t flags; /**< Reencryption flags. */
2727 * Initialize reencryption metadata using passphrase.
2729 * This function initializes on-disk metadata to include all reencryption segments,
2730 * according to the provided options.
2731 * If metadata already contains ongoing reencryption metadata, it loads these parameters
2732 * (in this situation all parameters except @e name and @e passphrase can be omitted).
2734 * @param cd crypt device handle
2735 * @param name name of active device or @e NULL for offline reencryption
2736 * @param passphrase passphrase used to unlock volume key
2737 * @param passphrase_size size of @e passphrase (binary data)
2738 * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2739 * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2740 * @param cipher cipher specification (e.g. "aes")
2741 * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2742 * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2744 * @return reencryption key slot number or negative errno otherwise.
2746 int crypt_reencrypt_init_by_passphrase(struct crypt_device *cd,
2748 const char *passphrase,
2749 size_t passphrase_size,
2753 const char *cipher_mode,
2754 const struct crypt_params_reencrypt *params);
2757 * Initialize reencryption metadata using passphrase in keyring.
2759 * This function initializes on-disk metadata to include all reencryption segments,
2760 * according to the provided options.
2761 * If metadata already contains ongoing reencryption metadata, it loads these parameters
2762 * (in this situation all parameters except @e name and @e key_description can be omitted).
2764 * @param cd crypt device handle
2765 * @param name name of active device or @e NULL for offline reencryption
2766 * @param key_description passphrase (key) identification in keyring
2767 * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
2768 * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
2769 * @param cipher cipher specification (e.g. "aes")
2770 * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
2771 * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
2773 * @return reencryption key slot number or negative errno otherwise.
2775 int crypt_reencrypt_init_by_keyring(struct crypt_device *cd,
2777 const char *key_description,
2781 const char *cipher_mode,
2782 const struct crypt_params_reencrypt *params);
2785 * Legacy data reencryption function.
2787 * @param cd crypt device handle
2788 * @param progress is a callback function reporting device \b size,
2789 * current \b offset of reencryption and provided \b usrptr identification
2791 * @return @e 0 on success or negative errno value otherwise.
2793 * @deprecated Use @link crypt_reencrypt_run @endlink instead.
2795 int crypt_reencrypt(struct crypt_device *cd,
2796 int (*progress)(uint64_t size, uint64_t offset, void *usrptr))
2797 __attribute__((deprecated));
2800 * Run data reencryption.
2802 * @param cd crypt device handle
2803 * @param progress is a callback function reporting device \b size,
2804 * current \b offset of reencryption and provided \b usrptr identification
2805 * @param usrptr progress specific data
2807 * @return @e 0 on success or negative errno value otherwise.
2809 int crypt_reencrypt_run(struct crypt_device *cd,
2810 int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
2814 * Reencryption status info
2817 CRYPT_REENCRYPT_NONE = 0, /**< No reencryption in progress */
2818 CRYPT_REENCRYPT_CLEAN, /**< Ongoing reencryption in a clean state. */
2819 CRYPT_REENCRYPT_CRASH, /**< Aborted reencryption that need internal recovery. */
2820 CRYPT_REENCRYPT_INVALID /**< Invalid state. */
2821 } crypt_reencrypt_info;
2824 * LUKS2 reencryption status.
2826 * @param cd crypt device handle
2827 * @param params reencryption parameters
2829 * @return reencryption status info and parameters.
2831 crypt_reencrypt_info crypt_reencrypt_status(struct crypt_device *cd,
2832 struct crypt_params_reencrypt *params);
2836 * @defgroup crypt-memory Safe memory helpers functions
2837 * @addtogroup crypt-memory
2842 * Allocate safe memory (content is safely wiped on deallocation).
2844 * @param size size of memory in bytes
2846 * @return pointer to allocated memory or @e NULL.
2848 void *crypt_safe_alloc(size_t size);
2851 * Release safe memory, content is safely wiped.
2852 * The pointer must be allocated with @link crypt_safe_alloc @endlink
2854 * @param data pointer to memory to be deallocated
2856 void crypt_safe_free(void *data);
2859 * Reallocate safe memory (content is copied and safely wiped on deallocation).
2861 * @param data pointer to memory to be deallocated
2862 * @param size new size of memory in bytes
2864 * @return pointer to allocated memory or @e NULL.
2866 void *crypt_safe_realloc(void *data, size_t size);
2869 * Safe clear memory area (compile should not compile this call out).
2871 * @param data pointer to memory to be cleared
2872 * @param size size of memory in bytes
2874 void crypt_safe_memzero(void *data, size_t size);
2881 #endif /* _LIBCRYPTSETUP_H */