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