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

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

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

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

41 42
struct crypt_device; /* crypt device handle */

43
/**
44
 * Initialize crypt device handle and check if provided device exists.
45
 *
46 47 48 49 50 51
 * @param cd Returns pointer to crypt device handle
 * @param device Path to the backing device.
 * 	  If @e device is not a block device but a path to some file,
 * 	  the function will try to create a loopdevice and attach
 * 	  the file to the loopdevice with AUTOCLEAR flag set.
 * 	  If @e device is @e NULL function it will initialize dm backend only.
52
 *
53
 * @return @e 0 on success or negative errno value otherwise.
54
 *
55 56
 * @note Note that logging is not initialized here, possible messages uses
 * 	 default log function.
57 58
 */
int crypt_init(struct crypt_device **cd, const char *device);
59

60
/**
61
 * Initialize crypt device handle from provided active device name,
62
 * and, optionally, from separate metadata (header) device
63 64
 * and check if provided device exists.
 *
65 66 67 68 69 70
 * @return @e 0 on success or negative errno value otherwise.
 *
 * @param cd returns crypt device handle for active device
 * @param name name of active crypt device
 * @param header_device optional device containing on-disk header
 * 	  (@e NULL if it the same as underlying device on there is no on-disk header)
71
 *
72 73 74
 * @post In case @e device points to active LUKS device but header load fails,
 * context device type is set to @e NULL and @e 0 is returned as if it were successful.
 * Context with @e NULL device type can only be deactivated by crypt_deactivate
75
 *
76 77
 * @note @link crypt_init_by_name @endlink is equivalent to calling
 * 	 crypt_init_by_name_and_header(cd, name, NULL);
78
 */
79 80 81
int crypt_init_by_name_and_header(struct crypt_device **cd,
				  const char *name,
				  const char *header_device);
82 83 84 85 86 87 88

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

91
/**
92
 * @defgroup loglevel Cryptsetup logging
93 94 95
 *
 * Set of functions and defines used in cryptsetup for
 * logging purposes
96 97
 *
 */
98 99 100 101 102 103 104

/**
 * @addtogroup loglevel
 * @{
 */

/** normal log level */
105
#define CRYPT_LOG_NORMAL 0
106
/** error log level */
107
#define CRYPT_LOG_ERROR  1
108
/** verbose log level */
109
#define CRYPT_LOG_VERBOSE  2
110 111 112 113 114 115 116 117 118 119 120 121
/** debug log level - always on stdout */
#define CRYPT_LOG_DEBUG -1

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

126
/**
127 128 129
 * Defines log function or use the default one otherwise.
 *
 * @see crypt_set_log_callback
130
 *
131 132 133
 * @param cd crypt device handle
 * @param level log level
 * @param msg log message
134
 */
135
void crypt_log(struct crypt_device *cd, int level, const char *msg);
136
/** @} */
137

138 139 140
/**
 * Set confirmation callback (yes/no)
 *
141 142
 * If code need confirmation (like resetting uuid or restoring LUKS header from file)
 * this function is called. If not defined, everything is confirmed.
143
 *
144 145
 * Callback function @e confirm should return @e 0 if operation is declined,
 * other values mean accepted.
146
 *
147 148 149 150 151 152
 * @param cd crypt device handle
 * @param confirm user defined confirm callback reference
 * @param usrptr provided identification in callback
 * @param msg Message for user to confirm
 *
 * @note Current version of cryptsetup API requires confirmation only when UUID is being changed
153 154 155 156 157 158 159 160
 */
void crypt_set_confirm_callback(struct crypt_device *cd,
	int (*confirm)(const char *msg, void *usrptr),
	void *usrptr);

/**
 * Set password query callback.
 *
161
 * If code need @e _interactive_ query for password, this callback is called.
162 163
 * If not defined, compiled-in default is called (uses terminal input).
 *
164
 * Callback should return length of password in buffer
Milan Broz's avatar
Milan Broz committed
165 166
 * or negative errno value in case of error.
 *
167
 * @param cd crypt device handle
168
 * @param password user defined password callback reference
169 170 171 172 173 174
 * @param usrptr provided identification in callback
 * @param msg Message for user
 * @param buf buffer for password
 * @param length size of buffer
 *
 * @note Note that if this function is defined, verify option is ignored
175
 *   (caller which provided callback is responsible for password verification)
176
 * @note Only zero terminated passwords can be entered this way, for complex
Milan Broz's avatar
Milan Broz committed
177
 *   use API functions directly.
178
 * @note Maximal length of password is limited to @e length @e - @e 1 (minimal 511 chars)
179 180
 * @note Internal compiled-in terminal input is DEPRECATED and will be removed
 *   in future versions.
181 182 183 184 185 186 187 188 189
 *
 * @see Callback function is used in these call provided, that certain conditions are met:
 * @li crypt_keyslot_add_by_passphrase
 * @li crypt_activate_by_passphrase
 * @li crypt_resume_by_passphrase
 * @li crypt_resume_by_keyfile
 * @li crypt_keyslot_add_by_keyfile
 * @li crypt_keyslot_add_by_volume_key
 *
190 191 192 193 194 195
 */
void crypt_set_password_callback(struct crypt_device *cd,
	int (*password)(const char *msg, char *buf, size_t length, void *usrptr),
	void *usrptr);

/**
196 197
 * Set timeout for interactive password entry using default
 * password callback
198
 *
199 200
 * @param cd crypt device handle
 * @param timeout_sec timeout in seconds
201 202
 */
void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
203 204 205 206 207 208 209

/**
 * Set number of retries in case password input has been incorrect
 *
 * @param cd crypt device handle
 * @param tries the number
 */
210
void crypt_set_password_retry(struct crypt_device *cd, int tries);
211 212

/**
213
 * Set how long should cryptsetup iterate in PBKDF2 function.
214 215 216 217 218
 * Default value heads towards the iterations which takes around 1 second
 *
 * @param cd crypt device handle
 * @param iteration_time_ms the time in ms
 */
219 220
void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);
/* Don't ask :-) */
221
void crypt_set_iterarion_time(struct crypt_device *cd, uint64_t iteration_time_ms);
222 223 224 225 226 227 228 229

/**
 * Set whether passphrase will be verified on input
 * (user has to input same passphrase twice)
 *
 * @param cd crypt device handle
 * @param password_verify @e 0 = false, @e !0 true
 */
230 231
void crypt_set_password_verify(struct crypt_device *cd, int password_verify);

232
/**
233 234 235
 * Set data device
 * For LUKS it is encrypted data device when LUKS header is separated.
 * For VERITY it is data device when hash device is separated.
236 237 238 239
 *
 * @param cd crypt device handle
 * @param device path to device
 *
240 241 242
 */
int crypt_set_data_device(struct crypt_device *cd, const char *device);

243
/**
244
 * @defgroup rng Cryptsetup RNG
245 246 247
 *
 * @addtogroup rng
 * @{
248 249
 *
 */
250 251

/** CRYPT_RNG_URANDOM - use /dev/urandom */
252
#define CRYPT_RNG_URANDOM 0
253
/** CRYPT_RNG_RANDOM  - use /dev/random (waits if no entropy in system) */
254
#define CRYPT_RNG_RANDOM  1
255 256 257 258 259 260 261 262

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

/**
 * Get which RNG (random number generator) is used for generating long term key
 *
268 269
 * @param cd crypt device handle
 * @return RNG type on success or negative errno value otherwise.
270 271 272 273
 *
 */
int crypt_get_rng_type(struct crypt_device *cd);

274 275
/** @} */

276
/**
277
 * Helper to lock/unlock memory to avoid swap sensitive data to disk
278
 *
279 280 281 282
 * @param cd crypt device handle, can be @e NULL
 * @param lock 0 to unlock otherwise lock memory
 *
 * @returns Value indicating whether the memory is locked (function can be called multiple times).
283
 *
284 285
 * @note Only root can do this.
 * @note It locks/unlocks all process memory, not only crypt context.
286 287 288
 */
int crypt_memory_lock(struct crypt_device *cd, int lock);

289
/**
290
 * @defgroup crypt_type Cryptsetup on-disk format types
291 292 293 294 295 296 297 298 299 300
 *
 * Set of functions, \#defines and structs related
 * to on-disk format types
 */

/**
 * @addtogroup crypt_type
 * @{
 */

301
/** plain crypt device, no on-disk header */
302 303 304 305 306
#define CRYPT_PLAIN "PLAIN"
/** LUKS version 1 header on-disk */
#define CRYPT_LUKS1 "LUKS1"
/** loop-AES compatibility mode */
#define CRYPT_LOOPAES "LOOPAES"
307 308
/** dm-verity mode */
#define CRYPT_VERITY "VERITY"
309
/** TCRYPT (TrueCrypt-compatible and VeraCrypt-compatible) mode */
Milan Broz's avatar
Milan Broz committed
310
#define CRYPT_TCRYPT "TCRYPT"
311

312 313 314
/**
 * Get device type
 *
315 316
 * @param cd crypt device handle
 * @return string according to device type or @e NULL if not known.
317 318 319
 */
const char *crypt_get_type(struct crypt_device *cd);

320 321 322 323 324 325
/**
 *
 * Structure used as parameter for PLAIN device type
 *
 * @see crypt_format
 */
326
struct crypt_params_plain {
327 328 329 330
	const char *hash; /**< password hash function */
	uint64_t offset; /**< offset in sectors */
	uint64_t skip; /**< IV offset / initialization sector */
	uint64_t size; /**< size of mapped device or @e 0 for autodetection */
331 332
};

333 334 335 336 337 338 339 340 341
/**
 * Structure used as parameter for LUKS device type
 *
 * @see crypt_format, crypt_load
 *
 * @note during crypt_format @e data_device attribute determines
 * 	 if the LUKS header is separated from encrypted payload device
 *
 */
342
struct crypt_params_luks1 {
343 344 345
	const char *hash; /**< hash used in LUKS header */
	size_t data_alignment; /**< data alignment in sectors, data offset is multiple of this */
	const char *data_device; /**< detached encrypted data device or @e NULL */
346 347
};

348 349 350 351 352 353 354
/**
 *
 * Structure used as parameter for loop-AES device type
 *
 * @see crypt_format
 *
 */
355
struct crypt_params_loopaes {
356 357 358
	const char *hash; /**< key hash function */
	uint64_t offset;  /**< offset in sectors */
	uint64_t skip;    /**< IV offset / initialization sector */
359
};
360

361 362 363 364 365 366 367 368 369 370
/**
 *
 * Structure used as parameter for dm-verity device type
 *
 * @see crypt_format, crypt_load
 *
 */
struct crypt_params_verity {
	const char *hash_name;     /**< hash function */
	const char *data_device;   /**< data_device (CRYPT_VERITY_CREATE_HASH) */
Milan Broz's avatar
Milan Broz committed
371
	const char *hash_device;   /**< hash_device (output only) */
372
	const char *salt;          /**< salt */
373 374
	uint32_t salt_size;        /**< salt size (in bytes) */
	uint32_t hash_type;        /**< in-kernel hashing type */
375 376 377 378 379 380 381
	uint32_t data_block_size;  /**< data block size (in bytes) */
	uint32_t hash_block_size;  /**< hash block size (in bytes) */
	uint64_t data_size;        /**< data area size (in data blocks) */
	uint64_t hash_area_offset; /**< hash/header offset (in bytes) */
	uint32_t flags;            /**< CRYPT_VERITY* flags */
};

382 383 384 385 386 387 388
/** No on-disk header (only hashes) */
#define CRYPT_VERITY_NO_HEADER   (1 << 0)
/** Verity hash in userspace before activation */
#define CRYPT_VERITY_CHECK_HASH  (1 << 1)
/** Create hash - format hash device */
#define CRYPT_VERITY_CREATE_HASH (1 << 2)

Milan Broz's avatar
Milan Broz committed
389 390 391 392
/**
 *
 * Structure used as parameter for TCRYPT device type
 *
393
 * @see crypt_load
Milan Broz's avatar
Milan Broz committed
394 395 396
 *
 */
struct crypt_params_tcrypt {
Milan Broz's avatar
Milan Broz committed
397
	const char *passphrase;    /**< passphrase to unlock header (input only) */
398
	size_t passphrase_size;    /**< passphrase size (input only, max length is 64) */
Milan Broz's avatar
Milan Broz committed
399 400
	const char **keyfiles;     /**< keyfile paths to unlock header (input only) */
	unsigned int keyfiles_count;/**< keyfiles count (input only) */
Milan Broz's avatar
Milan Broz committed
401
	const char *hash_name;     /**< hash function for PBKDF */
402
	const char *cipher;        /**< cipher chain c1[-c2[-c3]] */
Milan Broz's avatar
Milan Broz committed
403
	const char *mode;          /**< cipher block mode */
404
	size_t key_size;           /**< key size in bytes (the whole chain) */
Milan Broz's avatar
Milan Broz committed
405 406 407
	uint32_t flags;            /**< CRYPT_TCRYPT* flags */
};

408
/** Include legacy modes when scanning for header*/
409 410 411 412 413 414 415
#define CRYPT_TCRYPT_LEGACY_MODES    (1 << 0)
/** Try to load hidden header (describing hidden device) */
#define CRYPT_TCRYPT_HIDDEN_HEADER   (1 << 1)
/** Try to load backup header */
#define CRYPT_TCRYPT_BACKUP_HEADER   (1 << 2)
/** Device contains encrypted system (with boot loader) */
#define CRYPT_TCRYPT_SYSTEM_HEADER   (1 << 3)
416 417 418 419
/** Include VeraCrypt modes when scanning for header,
 *  all other TCRYPT flags applies as well.
 *  VeraCrypt device is reported as TCRYPT type.
 */
420
#define CRYPT_TCRYPT_VERA_MODES      (1 << 4)
421

422 423
/** @} */

424 425 426
/**
 * Create (format) new crypt device (and possible header on-disk) but not activates it.
 *
427 428 429 430 431 432 433 434 435 436
 * @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
 *
 * @param cd crypt device handle
 * @param type type of device (optional params struct must be of this type)
 * @param cipher (e.g. "aes")
 * @param cipher_mode including IV specification (e.g. "xts-plain")
 * @param uuid requested UUID or @e NULL if it should be generated
 * @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
 * @param volume_key_size size of volume key in bytes.
 * @param params crypt type specific parameters (see @link crypt_type @endlink)
437
 *
438
 * @returns @e 0 on success or negative errno value otherwise.
439
 *
440 441 442 443
 * @note Note that crypt_format does not enable any keyslot (in case of work with LUKS device),
 * 	but it stores volume key internally and subsequent crypt_keyslot_add_* calls can be used.
 * @note For VERITY @link crypt_type @endlink, only uuid parameter is used, others paramaters
 * 	are ignored and verity specific attributes are set through mandatory params option.
444 445 446 447 448 449 450 451 452 453
 */
int crypt_format(struct crypt_device *cd,
	const char *type,
	const char *cipher,
	const char *cipher_mode,
	const char *uuid,
	const char *volume_key,
	size_t volume_key_size,
	void *params);

Milan Broz's avatar
Milan Broz committed
454
/**
455
 * Set new UUID for already existing device
Milan Broz's avatar
Milan Broz committed
456
 *
457 458
 * @param cd crypt device handle
 * @param uuid requested UUID or @e NULL if it should be generated
Milan Broz's avatar
Milan Broz committed
459
 *
460 461 462
 * @returns 0 on success or negative errno value otherwise.
 *
 * @note Currently, only LUKS device type are supported
Milan Broz's avatar
Milan Broz committed
463 464 465 466
 */
int crypt_set_uuid(struct crypt_device *cd,
		   const char *uuid);

467 468 469
/**
 * Load crypt device parameters from on-disk header
 *
470
 * @param cd crypt device handle
471
 * @param requested_type @link crypt_type @endlink or @e NULL for all known
472 473 474 475 476 477 478
 * @param params crypt type specific parameters (see @link crypt_type @endlink)
 *
 * @returns 0 on success or negative errno value otherwise.
 *
 * @post In case LUKS header is read successfully but payload device is too small
 * error is returned and device type in context is set to @e NULL
 *
479
 * @note Note that in current version load works only for LUKS and VERITY device type.
480 481 482 483 484 485
 *
 */
int crypt_load(struct crypt_device *cd,
	       const char *requested_type,
	       void *params);

486 487 488 489
/**
 * Try to repair crypt device on-disk header if invalid
 *
 * @param cd crypt device handle
490
 * @param requested_type @link crypt_type @endlink or @e NULL for all known
491 492 493 494 495 496 497
 * @param params crypt type specific parameters (see @link crypt_type @endlink)
 *
 * @returns 0 on success or negative errno value otherwise.
 *
 */
int crypt_repair(struct crypt_device *cd,
		 const char *requested_type,
498
		 void *params);
499

500 501 502
/**
 * Resize crypt device
 *
503 504 505
 * @param cd - crypt device handle
 * @param name - name of device to resize
 * @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
506
 *
507
 * @return @e 0 on success or negative errno value otherwise.
508 509 510 511 512
 */
int crypt_resize(struct crypt_device *cd,
		 const char *name,
		 uint64_t new_size);

513 514 515
/**
 * Suspends crypt device.
 *
516 517 518 519 520 521
 * @param cd crypt device handle, can be @e NULL
 * @param name name of device to suspend
 *
 * @return 0 on success or negative errno value otherwise.
 *
 * @note Only LUKS device type is supported
522 523 524 525 526 527 528 529 530
 *
 */
int crypt_suspend(struct crypt_device *cd,
		  const char *name);

/**
 * Resumes crypt device using passphrase.
 *
 *
531 532 533 534 535 536 537 538 539
 * @param cd crypt device handle
 * @param name name of device to resume
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 * @param passphrase passphrase used to unlock volume key, @e NULL for query
 * @param passphrase_size size of @e passphrase (binary data)
 *
 * @return unlocked key slot number or negative errno otherwise.
 *
 * @note Only LUKS device type is supported
540 541
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
542 543
 */
int crypt_resume_by_passphrase(struct crypt_device *cd,
544 545 546 547
	const char *name,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size);
548 549 550 551

/**
 * Resumes crypt device using key file.
 *
552 553 554 555
 * @param cd crypt device handle
 * @param name name of device to resume
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
556
 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
557
 * @param keyfile_offset number of bytes to skip at start of keyfile
558
 *
559
 * @return unlocked key slot number or negative errno otherwise.
560 561 562
 *
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
563
 */
564 565 566 567 568 569 570 571 572
int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset);
/**
 * Backward compatible crypt_resume_by_keyfile_offset() (without offset).
 */
573
int crypt_resume_by_keyfile(struct crypt_device *cd,
574 575 576 577
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size);
578

579 580 581
/**
 * Releases crypt device context and used memory.
 *
582
 * @param cd crypt device handle
583 584 585
 */
void crypt_free(struct crypt_device *cd);

586
/**
587
 * @defgroup keyslot Cryptsetup LUKS keyslots
588 589 590 591 592 593 594 595
 * @addtogroup keyslot
 * @{
 *
 */

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

596 597 598
/**
 * Add key slot using provided passphrase
 *
599 600 601 602 603
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 * @param passphrase passphrase used to unlock volume key, @e NULL for query
604
 * @param passphrase_size size of passphrase (binary data)
605 606
 * @param new_passphrase passphrase for new keyslot, @e NULL for query
 * @param new_passphrase_size size of @e new_passphrase (binary data)
607
 *
608
 * @return allocated key slot number or negative errno otherwise.
609 610 611
 *
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
612 613 614 615 616 617 618 619
 */
int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size,
	const char *new_passphrase,
	size_t new_passphrase_size);

620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637
/**
 * Change defined key slot using provided passphrase
 *
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
 * @param keyslot_new new keyslot (can be the same as old)
 * @param passphrase passphrase used to unlock volume key, @e NULL for query
 * @param passphrase_size size of passphrase (binary data)
 * @param new_passphrase passphrase for new keyslot, @e NULL for query
 * @param new_passphrase_size size of @e new_passphrase (binary data)
 *
 * @return allocated key slot number or negative errno otherwise.
 *
 * @note This function is just internal implementation of luksChange
 * command to avoid reading of volume key outside libcryptsetup boundary
 * in FIPS mode.
638 639 640
 *
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
641 642 643 644 645 646 647 648 649
 */
int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
	int keyslot_old,
	int keyslot_new,
	const char *passphrase,
	size_t passphrase_size,
	const char *new_passphrase,
	size_t new_passphrase_size);

650 651 652
/**
* Add key slot using provided key file path
 *
653 654 655 656 657
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
 * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
658
 * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
659
 * @param keyfile_offset number of bytes to skip at start of keyfile
660 661
 * @param new_keyfile keyfile for new keyslot, @e NULL for passphrase query
 * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
662
 * @param new_keyfile_offset number of bytes to skip at start of new_keyfile
663
 *
664 665 666
 * @return allocated key slot number or negative errno otherwise.
 *
 * @note Note that @e keyfile can be "-" for STDIN
667
 */
668 669 670 671 672 673 674 675 676 677 678
int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset,
	const char *new_keyfile,
	size_t new_keyfile_size,
	size_t new_keyfile_offset);
/**
 * Backward compatible crypt_keyslot_add_by_keyfile_offset() (without offset).
 */
679 680 681 682 683 684 685 686 687 688
int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	const char *new_keyfile,
	size_t new_keyfile_size);

/**
 * Add key slot using provided volume key
 *
689 690 691 692 693
 * @pre @e cd contains initialized and formatted LUKS device context
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot or CRYPT_ANY_SLOT
 * @param volume_key provided volume key or @e NULL if used after crypt_format
694
 * @param volume_key_size size of volume_key
695
 * @param passphrase passphrase for new keyslot, @e NULL for query
696
 * @param passphrase_size size of passphrase
697 698
 *
 * @return allocated key slot number or negative errno otherwise.
699
 *
700 701
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
702 703 704 705 706 707 708 709 710 711 712
 */
int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
	int keyslot,
	const char *volume_key,
	size_t volume_key_size,
	const char *passphrase,
	size_t passphrase_size);

/**
 * Destroy (and disable) key slot
 *
713
 * @pre @e cd contains initialized and formatted LUKS device context
714
 *
715 716
 * @param cd crypt device handle
 * @param keyslot requested key slot to destroy
717
 *
718 719 720
 * @return @e 0 on success or negative errno value otherwise.
 *
 * @note Note that there is no passphrase verification used.
721 722 723
 */
int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);

724 725
/** @} */

726
/**
727
 * @defgroup aflags Device runtime attributes
728
 *
729
 * Activation flags
730 731 732 733
 *
 * @addtogroup aflags
 * @{
 *
734
 */
735
/** device is read only */
736
#define CRYPT_ACTIVATE_READONLY (1 << 0)
Milan Broz's avatar
Milan Broz committed
737
/** only reported for device without uuid */
738
#define CRYPT_ACTIVATE_NO_UUID  (1 << 1)
739
/** activate even if cannot grant exclusive access (DANGEROUS) */
740
#define CRYPT_ACTIVATE_SHARED   (1 << 2)
741 742
/** enable discards aka TRIM */
#define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
743 744
/** skip global udev rules in activation ("private device"), input only */
#define CRYPT_ACTIVATE_PRIVATE (1 << 4)
Milan Broz's avatar
Milan Broz committed
745 746
/** corruption detected (verity), output only */
#define CRYPT_ACTIVATE_CORRUPTED (1 << 5)
747 748 749 750 751
/** use same_cpu_crypt option for dm-crypt */
#define CRYPT_ACTIVATE_SAME_CPU_CRYPT (1 << 6)
/** use submit_from_crypt_cpus for dm-crypt */
#define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (1 << 7)

752

753 754 755 756
/**
 * Active device runtime attributes
 */
struct crypt_active_device {
757 758 759 760
	uint64_t offset; /**< offset in sectors */
	uint64_t iv_offset; /**< IV initialization sector */
	uint64_t size; /**< active device size */
	uint32_t flags; /**< activation flags */
761 762 763 764 765
};

/**
 * Receives runtime attributes of active crypt device
 *
766 767 768 769 770
 * @param cd crypt device handle (can be @e NULL)
 * @param name name of active device
 * @param cad preallocated active device attributes to fill
 *
 * @return @e 0 on success or negative errno value otherwise
771 772 773 774 775 776
 *
 */
int crypt_get_active_device(struct crypt_device *cd,
			    const char *name,
			    struct crypt_active_device *cad);

777 778
/** @} */

779 780 781
/**
 * Activate device or check passphrase
 *
782 783 784 785 786 787
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check passphrase
 * @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
 * @param passphrase passphrase used to unlock volume key, @e NULL for query
 * @param passphrase_size size of @e passphrase
 * @param flags activation flags
788
 *
789
 * @return unlocked key slot number or negative errno otherwise.
790 791 792
 *
 * @note If passphrase is @e NULL always use crypt_set_password_callback.
 * Internal terminal password query is DEPRECATED and will be removed in next version.
793 794 795 796 797 798 799 800 801 802 803
 */
int crypt_activate_by_passphrase(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *passphrase,
	size_t passphrase_size,
	uint32_t flags);

/**
 * Activate device or check using key file
 *
804 805 806 807
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check keyfile
 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 * @param keyfile key file used to unlock volume key
808
 * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
809
 * @param keyfile_offset number of bytes to skip at start of keyfile
810
 * @param flags activation flags
811
 *
812
 * @return unlocked key slot number or negative errno otherwise.
813
 */
814 815 816 817 818 819 820 821 822 823
int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	size_t keyfile_offset,
	uint32_t flags);
/**
 * Backward compatible crypt_activate_by_keyfile_offset() (without offset).
 */
824 825 826 827 828 829 830 831 832 833 834
int crypt_activate_by_keyfile(struct crypt_device *cd,
	const char *name,
	int keyslot,
	const char *keyfile,
	size_t keyfile_size,
	uint32_t flags);

/**
 * Activate device using provided volume key
 *
 *
835 836 837
 * @param cd crypt device handle
 * @param name name of device to create, if @e NULL only check volume key
 * @param volume_key provided volume key (or @e NULL to use internal)
838
 * @param volume_key_size size of volume_key
839 840 841
 * @param flags activation flags
 *
 * @return @e 0 on success or negative errno value otherwise.
842
 *
843
 * @note If @e NULL is used for volume_key, device has to be initialized
844 845
 * 	 by previous operation (like @ref crypt_format
 * 	 or @ref crypt_init_by_name)
846 847 848
 * @note For VERITY the volume key means root hash required for activation.
 * 	 Because kernel dm-verity is always read only, you have to provide
 * 	 CRYPT_ACTIVATE_READONLY flag always.
Milan Broz's avatar
Milan Broz committed
849 850
 * @note For TCRYPT the volume key should be always NULL and because master
 * 	 key from decrypted header is used instead.
851 852 853 854 855 856 857 858
 */
int crypt_activate_by_volume_key(struct crypt_device *cd,
	const char *name,
	const char *volume_key,
	size_t volume_key_size,
	uint32_t flags);

/**
859 860 861
 * Deactivate crypt device. This function tries to remove active device-mapper
 * mapping from kernel. Also, sensitive data like the volume key are removed from
 * memory
862
 *
863 864 865 866 867 868
 * @param cd crypt device handle, can be @e NULL
 * @param name name of device to deactivate
 *
 * @return @e 0 on success or negative errno value otherwise.
 *
 */
869 870 871 872 873
int crypt_deactivate(struct crypt_device *cd, const char *name);

/**
 * Get volume key from of crypt device
 *
874 875 876 877 878 879 880
 * @param cd crypt device handle
 * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
 * @param volume_key buffer for volume key
 * @param volume_key_size on input, size of buffer @e volume_key,
 *        on output size of @e volume_key
 * @param passphrase passphrase used to unlock volume key
 * @param passphrase_size size of @e passphrase
881
 *
882
 * @return unlocked key slot number or negative errno otherwise.
Milan Broz's avatar
Milan Broz committed
883 884 885
 *
 * @note For TCRYPT cipher chain is  the volume key concatenated
 * 	 for all ciphers in chain.
886 887 888 889 890 891 892 893 894 895 896
 */
int crypt_volume_key_get(struct crypt_device *cd,
	int keyslot,
	char *volume_key,
	size_t *volume_key_size,
	const char *passphrase,
	size_t passphrase_size);

/**
 * Verify that provided volume key is valid for crypt device
 *
897 898 899
 * @param cd crypt device handle
 * @param volume_key provided volume key
 * @param volume_key_size size of @e volume_key
900
 *
901
 * @return @e 0 on success or negative errno value otherwise.
902 903 904 905 906
 */
int crypt_volume_key_verify(struct crypt_device *cd,
	const char *volume_key,
	size_t volume_key_size);

907
/**
908
 * @defgroup devstat Crypt and Verity device status
909 910 911 912
 * @addtogroup devstat
 * @{
 */

913 914 915
/**
 * Device status
 */
916 917 918 919 920 921 922
typedef enum {
	CRYPT_INVALID, /**< device mapping is invalid in this context */
	CRYPT_INACTIVE, /**< no such mapped device */
	CRYPT_ACTIVE, /**< device is active */
	CRYPT_BUSY /**< device is active and has open count > 0 */
} crypt_status_info;

923 924 925
/**
 * Get status info about device name
 *
926 927
 * @param cd crypt device handle, can be @e NULL
 * @param name crypt device name
928
 *
929
 * @return value defined by crypt_status_info.
930 931 932 933 934
 *
 */
crypt_status_info crypt_status(struct crypt_device *cd, const char *name);

/**
935
 * Dump text-formatted information about crypt or verity device to log output
936
 *
937
 * @param cd crypt device handle
938
 *
939
 * @return @e 0 on success or negative errno value otherwise.
940 941 942 943
 */
int crypt_dump(struct crypt_device *cd);

/**
944
 * Get cipher used in device
945
 *
946 947 948
 * @param cd crypt device handle
 *
 * @return used cipher, e.g. "aes" or @e NULL otherwise
949 950 951
 *
 */
const char *crypt_get_cipher(struct crypt_device *cd);
952 953 954 955 956 957 958 959 960

/**
 * Get cipher mode used in device
 *
 * @param cd crypt device handle
 *
 * @return used cipher mode e.g. "xts-plain" or @e otherwise
 *
 */
961
const char *crypt_get_cipher_mode(struct crypt_device *cd);
962 963 964 965 966 967 968 969 970

/**
 * Get device UUID
 *
 * @param cd crypt device handle
 *
 * @return device UUID or @e NULL if not set
 *
 */
971
const char *crypt_get_uuid(struct crypt_device *cd);
972 973 974 975 976 977 978 979 980

/**
 * Get path to underlaying device
 *
 * @param cd crypt device handle
 *
 * @return path to underlaying device name
 *
 */
981
const char *crypt_get_device_name(struct crypt_device *cd);
982 983 984 985 986 987 988 989 990

/**
 * Get device offset in sectors where real data starts on underlying device)
 *
 * @param cd crypt device handle
 *
 * @return device offset in sectors
 *
 */
991
uint64_t crypt_get_data_offset(struct crypt_device *cd);
992 993 994 995 996 997 998 999 1000

/**
 * Get IV offset in sectors (skip)
 *
 * @param cd crypt device handle
 *
 * @return IV offset
 *
 */
1001
uint64_t crypt_get_iv_offset(struct crypt_device *cd);
1002 1003

/**
1004
 * Get size (in bytes) of volume key for crypt device
1005
 *
1006 1007 1008 1009 1010 1011 1012
 * @param cd crypt device handle
 *
 * @return volume key size
 *
 */
int crypt_get_volume_key_size(struct crypt_device *cd);

Milan Broz's avatar
Milan Broz committed
1013
/**
1014
 * Get device parameters for VERITY device
Milan Broz's avatar
Milan Broz committed
1015 1016 1017 1018 1019 1020 1021 1022 1023
 *
 * @param cd crypt device handle
 * @param vp verity device info
 *
 * @e 0 on success or negative errno value otherwise.
 *
 */
int crypt_get_verity_info(struct crypt_device *cd,
	struct crypt_params_verity *vp);
1024
/** @} */
Milan Broz's avatar
Milan Broz committed
1025

1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048
/**
 * @defgroup benchmark Benchmarking
 *
 * Benchmarking of algorithms
 *
 * @addtogroup benchmark
 * @{
 *
 */

/**
 * Informational benchmark for ciphers
 *
 * @param cd crypt device handle
 * @param cipher (e.g. "aes")
 * @param cipher_mode (e.g. "xts"), IV generator is ignored
 * @param volume_key_size size of volume key in bytes
 * @param iv_size size of IV in bytes
 * @param buffer_size size of encryption buffer in bytes used in test
 * @param encryption_mbs measured encryption speed in MiB/s
 * @param decryption_mbs measured decryption speed in MiB/s
 *
 * @return @e 0 on success or negative errno value otherwise.
Milan Broz's avatar
Milan Broz committed
1049 1050 1051
 *
 * @note If encryption_buffer_size is too small and encryption time
 *       cannot be properly measured, -ERANGE is returned.
1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085
 */
int crypt_benchmark(struct crypt_device *cd,
	const char *cipher,
	const char *cipher_mode,
	size_t volume_key_size,
	size_t iv_size,
	size_t buffer_size,
	double *encryption_mbs,
	double *decryption_mbs);

/**
 * Informational benchmark for KDF
 *
 * @param cd crypt device handle
 * @param kdf Key derivation function (e.g. "pbkdf2")
 * @param hash Hash algorithm used in KDF (e.g. "sha256")
 * @param password password for benchmark
 * @param password_size size of password
 * @param salt salt for benchmark
 * @param salt_size size of salt
 * @param iterations_sec returns measured KDF iterations per second
 *
 * @return @e 0 on success or negative errno value otherwise.
 */
int crypt_benchmark_kdf(struct crypt_device *cd,
	const char *kdf,
	const char *hash,
	const char *password,
	size_t password_size,
	const char *salt,
	size_t salt_size,
	uint64_t *iterations_sec);
/** @} */

1086 1087 1088
/**
 * @addtogroup keyslot
 * @{
1089 1090
 *
 */
1091 1092 1093 1094

/**
 * Crypt keyslot info
 */
1095
typedef enum {
1096 1097 1098 1099 1100
	CRYPT_SLOT_INVALID, /**< invalid keyslot */
	CRYPT_SLOT_INACTIVE, /**< keyslot is inactive (free) */
	CRYPT_SLOT_ACTIVE, /**< keyslot is active (used) */
	CRYPT_SLOT_ACTIVE_LAST /**< keylost is active (used)
				*   and last used at the same time */
1101
} crypt_keyslot_info;
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112

/**
 * Get information about particular key slot
 *
 *
 * @param cd crypt device handle
 * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
 *
 * @return value defined by crypt_keyslot_info
 *
 */
1113
crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
1114
/** @} */
1115

1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141
/**
 * Get number of keyslots supported for device type.
 *
 * @param type crypt device type
 *
 * @return slot count or negative errno otherwise if device
 * doesn't not support keyslots.
 */
int crypt_keyslot_max(const char *type);

/**
 * Get keyslot area pointers (relative to metadata device)
 *
 * @param cd crypt device handle
 * @param keyslot keyslot number
 * @param offset offset on metadata device (in bytes)
 * @param length length of keyslot area (in bytes)
 *
 * @return @e 0 on success or negative errno value otherwise.
 *
 */
int crypt_keyslot_area(struct crypt_device *cd,
	int keyslot,
	uint64_t *offset,
	uint64_t *length);

1142 1143 1144
/**
 * Backup header and keyslots to file
 *
1145
 * @param cd crypt device handle
1146
 * @param requested_type @link crypt_type @endlink or @e NULL for all known
1147 1148 1149
 * @param backup_file file to backup header to
 *
 * @return @e 0 on success or negative errno value otherwise.
1150 1151 1152 1153 1154 1155 1156