+/** @} */
+
+/**
+ * @defgroup crypt-keyfile Function to read keyfile
+ * @addtogroup crypt-keyfile
+ * @{
+ */
+
+/**
+ * Read keyfile
+ *
+ * @param cd crypt device handle
+ * @param keyfile keyfile to read
+ * @param key buffer for key
+ * @param key_size_read size of read key
+ * @param keyfile_offset key offset in keyfile
+ * @param key_size exact key length to read from file or 0
+ * @param flags keyfile read flags
+ *
+ * @return @e 0 on success or negative errno value otherwise.
+ *
+ * @note If key_size is set to zero we read internal max length
+ * and actual size read is returned via key_size_read parameter.
+ */
+int crypt_keyfile_device_read(struct crypt_device *cd,
+ const char *keyfile,
+ char **key, size_t *key_size_read,
+ uint64_t keyfile_offset,
+ size_t key_size,
+ uint32_t flags);
+
+/**
+ * Backward compatible crypt_keyfile_device_read() (with size_t offset).
+ */
+int crypt_keyfile_read(struct crypt_device *cd,
+ const char *keyfile,
+ char **key, size_t *key_size_read,
+ size_t keyfile_offset,
+ size_t key_size,
+ uint32_t flags);
+
+/** Read key only to the first end of line (\\n). */
+#define CRYPT_KEYFILE_STOP_EOL (1 << 0)
+/** @} */
+
+/**
+ * @defgroup crypt-wipe Function to wipe device
+ * @addtogroup crypt-wipe
+ * @{
+ */
+/**
+ * Wipe pattern
+ */
+typedef enum {
+ CRYPT_WIPE_ZERO, /**< Fill with zeroes */
+ CRYPT_WIPE_RANDOM, /**< Use RNG to fill data */
+ CRYPT_WIPE_ENCRYPTED_ZERO, /**< Add encryption and fill with zeroes as plaintext */
+ CRYPT_WIPE_SPECIAL, /**< Compatibility only, do not use (Gutmann method) */
+} crypt_wipe_pattern;
+
+/**
+ * Wipe/Fill (part of) a device with the selected pattern.
+ *
+ * @param cd crypt device handle
+ * @param dev_path path to device to wipe or @e NULL if data device should be used
+ * @param pattern selected wipe pattern
+ * @param offset offset on device (in bytes)
+ * @param length length of area to be wiped (in bytes)
+ * @param wipe_block_size used block for wiping (one step) (in bytes)
+ * @param flags wipe flags
+ * @param progress callback function called after each @e wipe_block_size or @e NULL
+ * @param usrptr provided identification in callback
+ *
+ * @return @e 0 on success or negative errno value otherwise.
+ *
+ * @note A @e progress callback can interrupt wipe process by returning non-zero code.
+ *
+ * @note If the error values is -EIO or -EINTR, some part of the device could
+ * be overwritten. Other error codes (-EINVAL, -ENOMEM) means that no IO was performed.
+ */
+int crypt_wipe(struct crypt_device *cd,
+ const char *dev_path, /* if null, use data device */
+ crypt_wipe_pattern pattern,
+ uint64_t offset,
+ uint64_t length,
+ size_t wipe_block_size,
+ uint32_t flags,
+ int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
+ void *usrptr
+);
+
+/** Use direct-io */
+#define CRYPT_WIPE_NO_DIRECT_IO (1 << 0)
+/** @} */
+
+/**
+ * @defgroup crypt-tokens LUKS2 token wrapper access
+ *
+ * Utilities for handling tokens LUKS2
+ * Token is a device or a method how to read password for particular keyslot
+ * automatically. It can be chunk of data stored on hardware token or
+ * just a metadata how to generate the password.
+ *
+ * @addtogroup crypt-tokens
+ * @{
+ */
+
+/** Iterate through all tokens */
+#define CRYPT_ANY_TOKEN -1
+
+/**
+ * Get content of a token definition in JSON format.
+ *
+ * @param cd crypt device handle
+ * @param token token id
+ * @param json buffer with JSON
+ *
+ * @return allocated token id or negative errno otherwise.
+ */
+int crypt_token_json_get(struct crypt_device *cd,
+ int token,
+ const char **json);
+
+/**
+ * Store content of a token definition in JSON format.
+ *
+ * @param cd crypt device handle
+ * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
+ * @param json buffer with JSON or @e NULL to remove token
+ *
+ * @return allocated token id or negative errno otherwise.
+ *
+ * @note The buffer must be in proper JSON format and must contain at least
+ * string "type" with slot type and an array of string names "keyslots".
+ * Keyslots array contains assignments to particular slots and can be empty.
+ */
+int crypt_token_json_set(struct crypt_device *cd,
+ int token,
+ const char *json);
+
+/**
+ * Token info
+ */
+typedef enum {
+ CRYPT_TOKEN_INVALID, /**< token is invalid */
+ CRYPT_TOKEN_INACTIVE, /**< token is empty (free) */
+ CRYPT_TOKEN_INTERNAL, /**< active internal token with driver */
+ CRYPT_TOKEN_INTERNAL_UNKNOWN, /**< active internal token (reserved name) with missing token driver */
+ CRYPT_TOKEN_EXTERNAL, /**< active external (user defined) token with driver */
+ CRYPT_TOKEN_EXTERNAL_UNKNOWN, /**< active external (user defined) token with missing token driver */
+} crypt_token_info;
+
+/**
+ * Get info for specific token.
+ *
+ * @param cd crypt device handle
+ * @param token existing token id
+ * @param type pointer for returned type string
+ *
+ * @return token status info. For any returned status (besides CRYPT_TOKEN_INVALID
+ * and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will
+ * contain address of type string.
+ *
+ * @note if required, create a copy of string referenced in *type before calling next
+ * libcryptsetup API function. The reference may become invalid.
+ */
+crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
+
+/**
+ * LUKS2 keyring token parameters.
+ *
+ * @see crypt_token_builtin_set
+ *
+ */
+struct crypt_token_params_luks2_keyring {
+ const char *key_description; /**< Reference in keyring */
+};
+
+/**
+ * Create a new luks2 keyring token.
+ *
+ * @param cd crypt device handle
+ * @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
+ * @param params luks2 keyring token params
+ *
+ * @return allocated token id or negative errno otherwise.
+ *
+ */
+int crypt_token_luks2_keyring_set(struct crypt_device *cd,
+ int token,
+ const struct crypt_token_params_luks2_keyring *params);
+
+/**
+ * Get LUKS2 keyring token params
+ *
+ * @param cd crypt device handle
+ * @param token existing luks2 keyring token id
+ * @param params returned luks2 keyring token params
+ *
+ * @return allocated token id or negative errno otherwise.
+ *
+ * @note do not call free() on params members. Members are valid only
+ * until next libcryptsetup function is called.
+ */
+int crypt_token_luks2_keyring_get(struct crypt_device *cd,
+ int token,
+ struct crypt_token_params_luks2_keyring *params);
+
+/**
+ * Assign a token to particular keyslot.
+ * (There can be more keyslots assigned to one token id.)
+ *
+ * @param cd crypt device handle
+ * @param token token id
+ * @param keyslot keyslot to be assigned to token (CRYPT_ANY SLOT
+ * assigns all active keyslots to token)
+ *
+ * @return allocated token id or negative errno otherwise.
+ */
+int crypt_token_assign_keyslot(struct crypt_device *cd,
+ int token,
+ int keyslot);
+
+/**
+ * Unassign a token from particular keyslot.
+ * (There can be more keyslots assigned to one token id.)
+ *
+ * @param cd crypt device handle
+ * @param token token id
+ * @param keyslot keyslot to be unassigned from token (CRYPT_ANY SLOT
+ * unassigns all active keyslots from token)
+ *
+ * @return allocated token id or negative errno otherwise.
+ */
+int crypt_token_unassign_keyslot(struct crypt_device *cd,
+ int token,
+ int keyslot);
+
+/**
+ * Get info about token assignment to particular keyslot.
+ *
+ * @param cd crypt device handle
+ * @param token token id
+ * @param keyslot keyslot
+ *
+ * @return 0 on success (token exists and is assigned to the keyslot),
+ * -ENOENT if token is not assigned to a keyslot (token, keyslot
+ * or both may be inactive) or other negative errno otherwise.
+ */
+int crypt_token_is_assigned(struct crypt_device *cd,
+ int token,
+ int keyslot);
+
+/**
+ * Token handler open function prototype.
+ * This function retrieves password from a token and return allocated buffer
+ * containing this password. This buffer has to be deallocated by calling
+ * free() function and content should be wiped before deallocation.
+ *
+ * @param cd crypt device handle
+ * @param token token id
+ * @param buffer returned allocated buffer with password
+ * @param buffer_len length of the buffer
+ * @param usrptr user data in @link crypt_activate_by_token @endlink
+ */
+typedef int (*crypt_token_open_func) (
+ struct crypt_device *cd,
+ int token,
+ char **buffer,
+ size_t *buffer_len,
+ void *usrptr);
+
+/**
+ * Token handler buffer free function prototype.
+ * This function is used by library to free the buffer with keyslot
+ * passphrase when it's no longer needed. If not defined the library
+ * overwrites buffer with zeroes and call free().
+ *
+ * @param buffer the buffer with keyslot passphrase
+ * @param buffer_len the buffer length
+ */
+typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
+
+/**
+ * Token handler validate function prototype.
+ * This function validates JSON representation of user defined token for additional data
+ * specific for its token type. If defined in the handler, it's called
+ * during @link crypt_activate_by_token @endlink. It may also be called during
+ * @link crypt_token_json_set @endlink when appropriate token handler was registered before
+ * with @link crypt_token_register @endlink.
+ *
+ * @param cd crypt device handle
+ * @param json buffer with JSON
+ */
+typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
+
+/**
+ * Token handler dump function prototype.
+ * This function is supposed to print token implementation specific details. It gets
+ * called during @link crypt_dump @endlink if token handler was registered before.
+ *
+ * @param cd crypt device handle
+ * @param json buffer with token JSON
+ *
+ * @note dump implementations are advised to use @link crypt_log @endlink function
+ * to dump token details.
+ */
+typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
+
+/**
+ * Token handler
+ */
+typedef struct {
+ const char *name; /**< token handler name */
+ crypt_token_open_func open; /**< token handler open function */
+ crypt_token_buffer_free_func buffer_free; /**< token handler buffer_free function (optional) */
+ crypt_token_validate_func validate; /**< token handler validate function (optional) */
+ crypt_token_dump_func dump; /**< token handler dump function (optional) */
+} crypt_token_handler;
+
+/**
+ * Register token handler
+ *
+ * @param handler token handler to register
+ *
+ * @return @e 0 on success or negative errno value otherwise.
+ */
+int crypt_token_register(const crypt_token_handler *handler);
+
+/**
+ * Activate device or check key using a token.
+ *
+ * @param cd crypt device handle
+ * @param name name of device to create, if @e NULL only check token
+ * @param token requested token to check or CRYPT_ANY_TOKEN to check all
+ * @param usrptr provided identification in callback
+ * @param flags activation flags
+ *
+ * @return unlocked key slot number or negative errno otherwise.
+ */
+int crypt_activate_by_token(struct crypt_device *cd,
+ const char *name,
+ int token,
+ void *usrptr,
+ uint32_t flags);
+/** @} */
+
+/**
+ * @defgroup crypt-reencryption LUKS2 volume reencryption support
+ *
+ * Set of functions to handling LUKS2 volume reencryption
+ *
+ * @addtogroup crypt-reencryption
+ * @{
+ */
+
+/** Initialize reencryption metadata but do not run reencryption yet. (in) */
+#define CRYPT_REENCRYPT_INITIALIZE_ONLY (1 << 0)
+/** Move the first segment, used only with data shift. (in/out) */
+#define CRYPT_REENCRYPT_MOVE_FIRST_SEGMENT (1 << 1)
+/** Resume already initialized reencryption only. (in) */
+#define CRYPT_REENCRYPT_RESUME_ONLY (1 << 2)
+/** Run reencryption recovery only. (in) */
+#define CRYPT_REENCRYPT_RECOVERY (1 << 3)
+
+/**
+ * Reencryption direction
+ */
+typedef enum {
+ CRYPT_REENCRYPT_FORWARD = 0, /**< forward direction */
+ CRYPT_REENCRYPT_BACKWARD /**< backward direction */
+} crypt_reencrypt_direction_info;
+
+/**
+ * Reencryption mode
+ */
+typedef enum {
+ CRYPT_REENCRYPT_REENCRYPT = 0, /**< Reencryption mode */
+ CRYPT_REENCRYPT_ENCRYPT, /**< Encryption mode */
+ CRYPT_REENCRYPT_DECRYPT, /**< Decryption mode */
+} crypt_reencrypt_mode_info;
+
+/**
+ * LUKS2 reencryption options.
+ */
+struct crypt_params_reencrypt {
+ crypt_reencrypt_mode_info mode; /**< Reencryption mode, immutable after first init. */
+ crypt_reencrypt_direction_info direction; /**< Reencryption direction, immutable after first init. */
+ const char *resilience; /**< Resilience mode: "none", "checksum", "journal" or "shift" (only "shift" is immutable after init) */
+ const char *hash; /**< Used hash for "checksum" resilience type, ignored otherwise. */
+ uint64_t data_shift; /**< Used in "shift" mode, must be non-zero, immutable after first init. */
+ uint64_t max_hotzone_size; /**< Exact hotzone size for "none" mode. Maximum hotzone size for "checksum" and "journal" modes. */
+ uint64_t device_size; /**< Reencrypt only initial part of the data device. */
+ const struct crypt_params_luks2 *luks2; /**< LUKS2 parameters for the final reencryption volume.*/
+ uint32_t flags; /**< Reencryption flags. */
+};
+
+/**
+ * Initialize reencryption metadata using passphrase.
+ *
+ * This function initializes on-disk metadata to include all reencryption segments,
+ * according to the provided options.
+ * If metadata already contains ongoing reencryption metadata, it loads these parameters
+ * (in this situation all parameters except @e name and @e passphrase can be omitted).
+ *
+ * @param cd crypt device handle
+ * @param name name of active device or @e NULL for offline reencryption
+ * @param passphrase passphrase used to unlock volume key
+ * @param passphrase_size size of @e passphrase (binary data)
+ * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
+ * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
+ * @param cipher cipher specification (e.g. "aes")
+ * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
+ * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
+ *
+ * @return reencryption key slot number or negative errno otherwise.
+ */
+int crypt_reencrypt_init_by_passphrase(struct crypt_device *cd,
+ const char *name,
+ const char *passphrase,
+ size_t passphrase_size,
+ int keyslot_old,
+ int keyslot_new,
+ const char *cipher,
+ const char *cipher_mode,
+ const struct crypt_params_reencrypt *params);
+
+/**
+ * Initialize reencryption metadata using passphrase in keyring.
+ *
+ * This function initializes on-disk metadata to include all reencryption segments,
+ * according to the provided options.
+ * If metadata already contains ongoing reencryption metadata, it loads these parameters
+ * (in this situation all parameters except @e name and @e key_description can be omitted).
+ *
+ * @param cd crypt device handle
+ * @param name name of active device or @e NULL for offline reencryption
+ * @param key_description passphrase (key) identification in keyring
+ * @param keyslot_old keyslot to unlock existing device or CRYPT_ANY_SLOT
+ * @param keyslot_new existing (unbound) reencryption keyslot; must be set except for decryption
+ * @param cipher cipher specification (e.g. "aes")
+ * @param cipher_mode cipher mode and IV (e.g. "xts-plain64")
+ * @param params reencryption parameters @link crypt_params_reencrypt @endlink.
+ *
+ * @return reencryption key slot number or negative errno otherwise.
+ */
+int crypt_reencrypt_init_by_keyring(struct crypt_device *cd,
+ const char *name,
+ const char *key_description,
+ int keyslot_old,
+ int keyslot_new,
+ const char *cipher,
+ const char *cipher_mode,
+ const struct crypt_params_reencrypt *params);
+
+/**
+ * Run data reencryption.
+ *
+ * @param cd crypt device handle
+ * @param progress is a callback funtion reporting device \b size,
+ * current \b offset of reencryption and provided \b usrptr identification
+ *
+ * @return @e 0 on success or negative errno value otherwise.
+ */
+int crypt_reencrypt(struct crypt_device *cd,
+ int (*progress)(uint64_t size, uint64_t offset, void *usrptr));
+
+/**
+ * Reencryption status info
+ */
+typedef enum {
+ CRYPT_REENCRYPT_NONE = 0, /**< No reencryption in progress */
+ CRYPT_REENCRYPT_CLEAN, /**< Ongoing reencryption in a clean state. */
+ CRYPT_REENCRYPT_CRASH, /**< Aborted reencryption that need internal recovery. */
+ CRYPT_REENCRYPT_INVALID /**< Invalid state. */
+} crypt_reencrypt_info;
+
+/**
+ * LUKS2 reencryption status.
+ *
+ * @param cd crypt device handle
+ * @param params reencryption parameters
+ *
+ * @return reencryption status info and parameters.
+ */
+crypt_reencrypt_info crypt_reencrypt_status(struct crypt_device *cd,
+ struct crypt_params_reencrypt *params);
+/** @} */
+
+/**
+ * @defgroup crypt-memory Safe memory helpers functions
+ * @addtogroup crypt-memory
+ * @{
+ */
+
+/**
+ * Allocate safe memory (content is safely wiped on deallocation).
+ *
+ * @param size size of memory in bytes
+ *
+ * @return pointer to allocate memory or @e NULL.
+ */
+void *crypt_safe_alloc(size_t size);
+
+/**
+ * Release safe memory, content is safely wiped
+ * The pointer must be allocated with @link crypt_safe_alloc @endlink
+ *
+ * @param data pointer to memory to be deallocated
+ *
+ * @return pointer to allocate memory or @e NULL.
+ */
+void crypt_safe_free(void *data);
+
+/**
+ * Reallocate safe memory (content is copied and safely wiped on deallocation).
+ *
+ * @param data pointer to memory to be deallocated
+ * @param size new size of memory in bytes
+ *
+ * @return pointer to allocate memory or @e NULL.
+ */
+void *crypt_safe_realloc(void *data, size_t size);
+
+/**
+ * Safe clear memory area (compile should not compile this call out).
+ *
+ * @param data pointer to memory to cleared
+ * @param size new size of memory in bytes
+ *
+ * @return pointer to allocate memory or @e NULL.
+ */
+void crypt_safe_memzero(void *data, size_t size);