### Locate cryptsetup Code Examples

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Code examples for cryptsetup can be found within the source package. Navigate to the 'docs/examples' directory to access them.

```text
docs/examples
```

--------------------------------

### Add New Keyslot with systemd-tpm2 Tokens

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-luksAddKey.8.adoc

This example demonstrates adding a new keyslot using systemd-tpm2 tokens. It requires the systemd-tpm2 token plugin to be installed and available. The existing keyslot is unlocked via the token, and the new passphrase is provided interactively.

```bash
cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device
```

--------------------------------

### Minimal Initrd Script Example

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

A basic initrd script that sets up essential directories and mounts sysfs and proc, then drops to a login shell. Useful for testing init script logic.

```bash
#!/bin/sh
export PATH=/sbin:/bin  
[ -d /sys ] || mkdir /sys
[ -d /proc ] || mkdir /proc
[ -d /tmp ] || mkdir /tmp
mount -t sysfs -o nodev,noexec,nosuid sysfs /sys
mount -t proc -o nodev,noexec,nosuid proc /proc
echo "initrd is running, starting BusyBox..."
exec /bin/sh --login
```

--------------------------------

### Manually Start Encrypted Swap

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

These commands can be used to manually start the encrypted swap service and activate the swap partition. This is useful for testing or if automatic mounting fails.

```bash
/etc/init.d/cryptdisks start
```

```bash
swapon /dev/mapper/swap
```

--------------------------------

### Install Fedora Build Dependencies

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Installs the necessary packages to build cryptsetup on Fedora. Optionally includes packages for Argon2 and password quality checks.

```bash
git gcc make autoconf automake gettext-devel pkgconfig openssl-devel popt-devel device-mapper-devel libuuid-devel json-c-devel libblkid-devel findutils libtool libssh-devel tar rubygem-asciidoctor

Optionally: libargon2-devel libpwquality-devel
```

--------------------------------

### Install Debian/Ubuntu Build Dependencies

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Installs the necessary packages to build cryptsetup on Debian and Ubuntu. Optionally includes packages for Argon2 and password quality checks.

```bash
git gcc make autoconf automake autopoint pkg-config libtool gettext libssl-dev libdevmapper-dev libpopt-dev uuid-dev libsepol-dev libjson-c-dev libssh-dev libblkid-dev tar asciidoctor

Optionally: libargon2-0-dev libpwquality-dev
```

--------------------------------

### Access Man Page

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Displays the cryptsetup man page after installation. This provides detailed information about the command-line utility.

```bash
man cryptsetup
```

--------------------------------

### Install Fedora Test Suite Dependencies

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Installs additional packages required to run the internal test suite for cryptsetup on Fedora.

```bash
sharutils device-mapper jq vim-common expect keyutils netcat shadow-utils openssh-clients openssh sshpass
```

--------------------------------

### Install Debian/Ubuntu Test Suite Dependencies

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Installs additional packages required to run the internal test suite for cryptsetup on Debian and Ubuntu.

```bash
sharutils dmsetup jq xxd expect keyutils netcat-openbsd passwd openssh-client sshpass
```

--------------------------------

### LUKS Partition Opening Initrd Script Example

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

An initrd script designed to find and open the first LUKS partition it detects using a hardcoded password ('test2'). It then mounts the decrypted partition as the root filesystem and switches to the init process on the mounted partition. This script includes debug output and is intended for secure environments like USB sticks.

```bash
#!/bin/sh
export PATH=/sbin:/bin
[ -d /sys ] || mkdir /sys
[ -d /proc ] || mkdir /proc
[ -d /tmp ] || mkdir /tmp
mount -t sysfs -o nodev,noexec,nosuid sysfs /sys
mount -t proc -o nodev,noexec,nosuid proc /proc
echo "detecting LUKS containers in sda1-10, sdb1-10"; sleep 1
for i in a b
do
  for j in 1 2 3 4 5 6 7 8 9 10
  do
    sleep 0.5
    d="/dev/sd"$i""$j
    echo -n $d
    cryptsetup isLuks $d >/dev/null 2>&1
    r=$?
    echo -n "  result: "$r""
    # 0 = is LUKS, 1 = is not LUKS, 4 = other error

```

--------------------------------

### Example strace output with passphrase

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

This example demonstrates how a passphrase might appear in strace output. Avoid sharing such traces from live containers; use test containers or temporary passphrases instead.

```bash
strace cryptsetup luksOpen /dev/sda10 c1
    ...
    read(6, "test\n", 512)                  = 5
    ...
```

--------------------------------

### Format Device for LUKS Encryption

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Initializes a device with the LUKS (Linux Unified Key Setup) format, setting up the header and the initial passphrase for keyslot 0. Supports LUKS1 and LUKS2 formats.

```bash
cryptsetup luksFormat <device> [<key file>]
```

--------------------------------

### Benchmark Ciphers, Hashes, and Modes

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Run the cryptsetup benchmark command to evaluate the performance of different encryption algorithms. Requires root privileges.

```bash
cryptsetup benchmark
```

--------------------------------

### cryptsetup-luksFormat

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-luksFormat.8.adoc

Initializes a LUKS partition and sets the initial passphrase. It can prompt for a passphrase, read it from a file, or from stdin. It also supports various options for encryption, key management, and hardware encryption.

```APIDOC
## cryptsetup luksFormat

### Description
Initializes a LUKS partition and sets the passphrase via prompting or a key file. The passphrase can be read from stdin if '-' is provided as the key file.

### Method
Command-line utility

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
- **device** (string) - Required - The block device to format with LUKS.
- **key file** (string) - Optional - A file containing the passphrase. If omitted, the passphrase is prompted for.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
cryptsetup luksFormat /dev/sdX1
```

### Response
#### Success Response (0)
- **Output**: Success messages indicating the LUKS header has been created and the passphrase set.

#### Response Example
```
Device /dev/sdX1 already formatted with luks, will overwrite? (y/n): y
Formatting 'cryptroot' (aes-xts-plain64, sha256) using random device
... (passphrase prompts) ...
```

### Options
* **Common Options**: `--hash`, `--cipher`, `--verify-passphrase`, `--key-size`, `--key-slot`, `--key-file`, `--keyfile-offset`, `--keyfile-size`, `--use-random`, `--use-urandom`, `--uuid`, `--volume-key-file`, `--iter-time`, `--header`, `--pbkdf-force-iterations`, `--force-password`, `--disable-locks`, `--timeout`, `--offset`, `--align-payload (DEPRECATED)`
* **LUKS2 Specific Options**: `--integrity`, `--integrity-no-wipe`, `--sector-size`, `--label`, `--subsystem`, `--pbkdf`, `--pbkdf-memory`, `--pbkdf-parallel`, `--disable-locks`, `--disable-keyring`, `--luks2-metadata-size`, `--luks2-keyslots-size`, `--keyslot-cipher`, `--keyslot-key-size`, `--integrity-legacy-padding`, `--hw-opal`, `--hw-opal-only`

### Notes
- Cannot be called on a device or filesystem that is mapped or in use (e.g., mounted, LVM, RAID).
- The device must be unmounted before calling `luksFormat`.
- Doing a `luksFormat` on an existing LUKS container regenerates the volume key and makes old encrypted data irretrievable without a header backup.
- `luksFormat` does not wipe or overwrite the data area; it only creates a new LUKS header.
- For hardware encryption on OPAL drives, use `--hw-opal` or `--hw-opal-only`. Some drives may require a PSID reset first.
```

--------------------------------

### Cryptsetup Options

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

This section details various options available for cryptsetup commands, categorized by their applicability to different actions.

```APIDOC
## OPTIONS

### --align-payload

*--align-payload* _<number of 512 byte sectors>_ (DEPRECATED, use --offset)::
Align payload at a boundary of _value_ 512-byte sectors.

If not specified, cryptsetup tries to use the topology info provided by the kernel for the underlying device to get the optimal alignment.
If not available (or the calculated value is a multiple of the default), data is by default aligned to a 1MiB boundary (i.e., 2048 512-byte sectors).

For a detached LUKS header, this option specifies the offset on the data device.
See also the --header option.

This option is DEPRECATED and has an unexpected impact on the data offset and keyslot area size (for LUKS2) due to the complex rounding.
For fixed data device offset, use --offset option instead.

### --allow-discards

*--allow-discards*::
Allow the use of discard (TRIM) requests for the device.
This is also not supported for LUKS2 devices with data integrity protection.

*WARNING:* This command can have a negative security impact because it can make filesystem-level operations visible on the physical device.
For example, information leaking filesystem type, used space, etc., may be extractable from the physical device if the discarded blocks can be located later.
If in doubt, do not use it.

A kernel version of 3.1 or later is needed.
For earlier kernels, this option is ignored.

### --batch-mode, -q

*--batch-mode*, *-q*::
Suppresses all confirmation questions.
Use with care!

If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

### --block-size

*--block-size* _value_ (LUKS1 only)::
Use re-encryption block size of _value_ in MiB.

Values can be between 1 and 64 MiB.

### --cancel-deferred

*--cancel-deferred*::
Removes a previously configured deferred device removal in the _close_ command.

### --cipher, -c

*--cipher*, *-c* _<cipher-spec>_::
Set the cipher specification string.

*LUKS2*:
Set the cipher specification string for the data segment only.

*LUKS1*:
Set the cipher specification string for the data segment and keyslots.

The default cipher is applied if the cipher specification is omitted in encrypt mode.

In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain.
The only exception is if the cipher is "cipher_null", then the default cipher is used.

_cryptsetup --help_ shows the compiled-in defaults.

If a hash is part of the cipher specification, then it is used as part of the IV generation.
For example, ESSIV needs a hash function, while "plain64" does not and hence none is specified.

For XTS mode, you can optionally set a key size of 512 bits with the -s option.
Key size for XTS mode is twice that for other modes for the same security level.

### --debug, --debug-json

*--debug* or *--debug-json*::
Run in debug mode with full diagnostic logs.
Debug output lines are always prefixed by *#*.

If --debug-json is used, additional LUKS2 JSON data structures are printed.

### --decrypt

*--decrypt*::
Initialize (and run) device decryption mode.

### --deferred

*--deferred*::
Defers device removal in the _close_ command until the last user closes it.

### --device-size

*--device-size* _size[units]_::
Instead of the real device size, use the specified value.

Sets the new size of the device.
If unset, the real device size is used.

It means that only the specified area (from the start of the device to the specified size) will be reencrypted.

*LUKS2*:
When used together with --reduce-device-size, only the initial _size_ value (--device-size parameter) of data is shifted backwards while being encrypted.

The sum of --device-size and --reduce-device-size values must not exceed the real device size.

*WARNING:* This is a destructive operation.
Data beyond --device-size limit may be lost after the operation is finished.

If no unit suffix is specified, the size is in bytes.

Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB, MiB, GiB, TiB) for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).

### --disable-blkid

*--disable-blkid*::

```

--------------------------------

### General and Utility Options

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/integritysetup.8.adoc

General configuration and utility options for cryptsetup.

```APIDOC
## --interleave-sectors _sectors_

### Description
Specifies the number of interleaved sectors.

## --sector-size, -s _bytes_

### Description
Sets the sector size. Must be a power of two (e.g., 512, 1024, 2048, 4096).

## --tag-size, -t _bytes_

### Description
Sets the size of the integrity tag per sector. This is the size where the integrity function stores the authentication tag. The size can be smaller than the hash function's output size, in which case only a portion of the hash is stored.

## --usage

### Description
Displays a short help message outlining the available options.

## --verbose, -v

### Description
Enables verbose output, printing more information during command execution.

## --version, -V

### Description
Displays the program version.
```

--------------------------------

### Configure Options

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Displays available configuration options for the cryptsetup build process. Use --disable-[feature] and --enable-[feature] to customize the build.

```bash
./configure --help
```

--------------------------------

### Compile from Git Snapshot

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Compiles the cryptsetup project from a git snapshot using autogen.sh, configure, and make.

```bash
./autogen.sh && ./configure && make
```

--------------------------------

### Cryptsetup LUKS Actions

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Actions specific to LUKS (Linux Unified Key Setup) encrypted volumes.

```APIDOC
## FORMAT (LUKS)

### Description
Initializes a LUKS partition and sets the initial passphrase.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **device** (string) - Required - The device to format as LUKS.
- **key file** (string) - Optional - A file containing the passphrase.

#### Query Parameters
- **--type luks1** (string) - Optional - Specifies LUKS version 1.
- **--type luks2** (string) - Optional - Specifies LUKS version 2 (default).

### Request Example
```bash
cryptsetup luksFormat /dev/sdc1
cryptsetup luksFormat /dev/sdc1 my_keyfile.txt --type luks2
```

## OPEN (LUKS)

### Description
Opens a LUKS encrypted volume, creating a device mapping.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **device** (string) - Required - The LUKS device to open.
- **name** (string) - Required - The name for the new device mapping.

#### Query Parameters
- **--type** (string) - Required - Must be set to 'luks'.
- **--header** (string) - Optional - Path to a detached LUKS header.

### Request Example
```bash
cryptsetup open --type luks /dev/sdc1 my_luks_volume
cryptsetup open --type luks --header /path/to/detached_header /dev/sdc1 my_luks_volume
```
```

--------------------------------

### Cryptsetup for loop-aes v1 format (OpenSUSE)

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Provides the cryptsetup command used successfully by a user to open a loop-aes v1 format volume on older OpenSUSE distributions.

```bash
cryptsetup create <target> <device> -c aes -s 128 -h sha256
```

--------------------------------

### Device Size and Skip Offset

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Options to specify the size of the device in 512-byte sectors and the starting offset for IV calculation.

```APIDOC
## --size, -b <number of 512 byte sectors>

### Description
Set the size of the device in sectors of 512 bytes. Usable only with the _plain_ device type.

### Method
(Implicitly part of cryptsetup open operations)

### Endpoint
N/A (Command-line option)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
cryptsetup open --size 4096 plain_device mymappedname
```

### Response
None
```

```APIDOC
## --skip, -p <number of 512 byte sectors>

### Description
Start offset used in IV calculation in 512-byte sectors (how many sectors of the encrypted data to skip at the beginning). This option is only relevant with plain or loopaes device types.

### Method
(Implicitly part of cryptsetup open operations)

### Endpoint
N/A (Command-line option)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
cryptsetup open --skip 100 plain_device mymappedname
```

### Response
None

### Notes
- If `--offset n` and `--skip s` are used, sector `n` (the first sector of the encrypted device) will get a sector number of `s` for the IV calculation.
```

--------------------------------

### Get Encrypted Device Status

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Reports the current status of an active mapping. This is useful for verifying if a device is open and its configuration.

```bash
cryptsetup status <name>
```

--------------------------------

### cryptsetup open - General Usage

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-open.8.adoc

The general syntax for opening an encrypted device and creating a mapping.

```APIDOC
## cryptsetup open - General Usage

### Description
Opens (creates a mapping with) a specified name backed by a given device. The device type can be specified, with LUKS being the default.

### Method
`cryptsetup open`

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`cryptsetup open --type <device_type> [<options>] <device> <name>`

### Response
#### Success Response (200)
Mapping created successfully.

#### Response Example
N/A (Command-line tool output)
```

--------------------------------

### Cryptsetup options for key size and offsets

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Shows the translation of losetup key size and offset options to cryptsetup's -s (key size in bits) and -o/-p (offsets in 512-byte sectors).

```bash
-k 128                 => -s 128
```

```bash
-o 2560                => -o 5 -p 5       # 2560/512 = 5
```

--------------------------------

### Wipe Target Device with Progress

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Wipe a target device while showing progress using the `wcs` tool. Ensure `wcs` is installed and accessible.

```bash
cat /dev/zero | wcs > <target device>
```

--------------------------------

### Cryptsetup options for cipher, mode, and hash

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Illustrates how losetup options for cipher, mode, and hash translate to cryptsetup's -c and -H flags. Note that -s 256 is often implied.

```bash
-e cipher [-N]        => -c cipher-cbc-plain -H plain [-s 256]
```

```bash
-e cipher             => -c cipher-cbc-plain -H ripemd160 [-s 256]
```

--------------------------------

### Device Offset Configuration

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Option to specify the start offset for data within a device, relevant for specific device types and encryption modes.

```APIDOC
## --offset, -o <number of 512 byte sectors>

### Description
Specifies the start offset in the backend device in 512-byte sectors. This option is relevant for plain or loopaes device types when opening a device. For re-encryption in encrypt mode, it sets the data offset and must be aligned to 4096-byte sectors (a multiple of 8). Cannot be combined with `--align-payload`.

### Method
(Used with OPEN, LUKSFORMAT, REENCRYPT)

### Endpoint
N/A (Command-line option)
```

--------------------------------

### Add Encrypted Swap to /etc/fstab

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Add this line to your /etc/fstab file to automatically mount the encrypted swap partition on boot. Ensure the device path matches your setup.

```bash
/dev/mapper/swap none swap sw 0 0
```

--------------------------------

### Run Test Suite

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Executes the internal test suite for the cryptsetup project. Requires root privileges and may simulate dangerous storage failures. Do not run on production systems.

```bash
make check
```

--------------------------------

### Open Device with Default Parameters

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/integritysetup.8.adoc

Activates a previously formatted integrity device using default parameters. Replace <device> with the actual device path.

```bash
integritysetup open <device> test
```

--------------------------------

### cryptsetup LUKS2 Resume Reencryption

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Resumes a reencryption operation that is already described in the LUKS2 metadata. This command fails if no reencrypt operation is initialized. It is useful for resuming without accidentally starting a new operation.

```bash
cryptsetup --resume-only --reencrypt <device>
```

--------------------------------

### Format Verity Device with Hash Offset

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/veritysetup.8.adoc

Stores verification data (hashes) on the same device as the data, starting at a specified hash offset. The hash offset must be greater than the number of blocks in the data area.

```bash
veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <device>
```

--------------------------------

### JSON Progress Output Example

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

This JSON output format is used for machine processing of progress data during operations like formatting or reencryption. Numbers are represented as strings to support full 64-bit unsigned integers.

```json
{
  "device":"/dev/sda",      // backing device or file
  "device_bytes":"8192",    // bytes of I/O so far
  "device_size":"44040192", // total bytes of I/O to go
  "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
  "eta_ms":"2520012",       // estimated time to finish an operation in milliseconds
  "time_ms":"5561235"       // total time spent in IO operation in milliseconds
}
```

--------------------------------

### Run cryptsetup in debugger with libtool

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/CONTRIBUTING.md

This command allows you to run the cryptsetup tool within a debugger (gdb) without prior installation, ensuring that a properly compiled libcryptsetup file is used. It's useful for debugging compilation issues.

```bash
libtool --mode=execute gdb --args ./cryptsetup --debug $@

```

--------------------------------

### Key File Usage

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Details on how to use key files for passphrase management with cryptsetup, including differences between interactive and key file modes.

```APIDOC
## Key File Usage

If you want to set a new passphrase via a key file, you have to use a positional argument.

With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt. Unlike the interactive mode (stdin), where the digest of the passphrase is passed in dm-crypt instead.

See section _NOTES ON PASSPHRASE PROCESSING_ in *cryptsetup*(8) for more information.

The --key-file option can be used only if there is only one active keyslot, or alternatively, also if --key-slot option is specified (then all other keyslots will be disabled in the new LUKS device).

If this option is not used, cryptsetup will ask for all active keyslot passphrases.
```

--------------------------------

### New Key File and Description

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Options for specifying a new key file and its description.

```APIDOC
## --new-keyfile <name>

### Description
Read the passphrase for a new keyslot from a file. If the name given is "-", then the passphrase will be read from stdin. In this case, reading will not stop at newline characters. This is an alternative method to positional argument when adding a new passphrase via keyfile.

### Method
Not applicable (Option description)

### Endpoint
Not applicable (Option description)

## --new-keyfile-offset <value>

### Description
Skip _value_ bytes at the start when adding a new passphrase from the key file.

### Method
Not applicable (Option description)

### Endpoint
Not applicable (Option description)

## --new-keyfile-size <value>

### Description
Read a maximum of _value_ bytes when adding a new passphrase from the key file. The default is to read the whole file up to the compiled-in maximum length that can be queried with --help. Supplying more than the compiled-in maximum aborts the operation. When --new-keyfile-offset is also given, reading starts after the offset.

### Method
Not applicable (Option description)

### Endpoint
Not applicable (Option description)

## --new-key-description <text>

### Description
Set the key description in the keyring that will be used for new passphrase retrieval.

### Method
Not applicable (Option description)

### Endpoint
Not applicable (Option description)
```

--------------------------------

### Build Docker Image and Fuzzers

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/tests/fuzz/README.md

Commands to build the Docker image and fuzzers for cryptsetup. Ensure you have sudo privileges.

```bash
sudo python3 infra/helper.py build_image cryptsetup
sudo python3 infra/helper.py build_fuzzers cryptsetup
```

--------------------------------

### Benchmark Cryptsetup Options

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Benchmarks various ciphers and key derivation functions (KDFs) supported by cryptsetup. Refer to cryptsetup-benchmark(8) for detailed options.

```bash
benchmark <options>
```

--------------------------------

### Verify cryptsetup Version

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Use this command to verify the correct version of cryptsetup is being called, especially when running from non-interactive environments like cron or CGI.

```bash
cryptsetup --version
```

--------------------------------

### Create Filesystem on Mapped Container

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Create an ext3 filesystem on the opened LUKS container. Other filesystem types can also be used.

```bash
mke2fs -j /dev/mapper/c1
```

--------------------------------

### cryptsetup-luksHeaderRestore

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-luksHeaderRestore.8.adoc

Restores a binary backup of the LUKS header and keyslot area.

```APIDOC
## cryptsetup luksHeaderRestore

### Description
Restores a binary backup of the LUKS header and keyslot area from the specified file. All keyslots will be replaced; only the passphrases from the backup will work afterward. This command requires that the volume key size and data offset of the LUKS header and backup match. Alternatively, the backup will also be written if the device has no LUKS header.

### Method
COMMAND

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
- **device** (string) - Required - The device to restore the header to.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
cryptsetup luksHeaderRestore --header-backup-file /path/to/backup.img /dev/sdX
```

### Response
#### Success Response (0)
- **stdout** (string) - Success message or output.

#### Response Example
```
Header and keyslot area restored successfully.
```

#### Error Handling
- **Non-zero exit code**: Indicates an error occurred. Check stderr for details.
- **Error messages**: Specific error messages will be printed to stderr.
```

--------------------------------

### Create Plain dm-crypt with Compatible Defaults

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Use this command when creating plain dm-crypt devices with cryptsetup 1.1.x to ensure compatibility with older versions and avoid security vulnerabilities. Explicitly specify cipher, key size, and hash algorithm.

```bash
cryptsetup create -c aes-cbc-plain -s 256 -h ripemd160 <name> <dev>
```

--------------------------------

### cryptsetup-config Command

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-config.8.adoc

Sets permanent configuration options for LUKS2 devices by storing them in the LUKS header.

```APIDOC
## cryptsetup-config Command

### Description
Sets permanent configuration options (store to LUKS header). The `config` command is supported only for LUKS2.

### Method
Not applicable (command-line utility)

### Endpoint
Not applicable (command-line utility)

### Parameters
#### Command Options
- **--priority** (string) - Optional - Sets the priority for a keyslot (normal, prefer, ignore).
- **--label** (string) - Optional - Sets a label for the device.
- **--subsystem** (string) - Optional - Sets the subsystem for the device.
- **--key-slot** (integer) - Optional - Specifies the key slot to which the options apply.
- **--header** (string) - Optional - Path to the LUKS header file.
- **--disable-locks** - Optional - Disables locks.

### Request Example
```bash
cryptsetup config --priority prefer --key-slot 0 /dev/sda1
```

### Response
#### Success Response
Indicates successful configuration update. No specific output is detailed in the manpage.

#### Response Example
(No specific example provided in the manpage)
```

--------------------------------

### Cryptsetup Basic Actions

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Common actions applicable to all supported device types in cryptsetup.

```APIDOC
## OPEN

### Description
Opens (creates a mapping with) <name> backed by device <device>.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **device** (string) - Required - The block device or disk image to open.
- **name** (string) - Required - The name for the new device mapping.

#### Query Parameters
- **--type** (string) - Optional - Specifies the device type (e.g., 'plain', 'luks').

### Request Example
```bash
cryptsetup open /dev/sda1 my_encrypted_volume --type luks
```

## CLOSE

### Description
Removes the existing mapping <name> and wipes the key from kernel memory.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the device mapping to close.

### Request Example
```bash
cryptsetup close my_encrypted_volume
```

## STATUS

### Description
Reports the status for the mapping <name>.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the device mapping to check.

### Request Example
```bash
cryptsetup status my_encrypted_volume
```

## RESIZE

### Description
Resizes an active mapping <name>.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the active device mapping to resize.

### Request Example
```bash
cryptsetup resize my_encrypted_volume
```

## REFRESH

### Description
Refreshes parameters of active mapping <name>.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the active device mapping to refresh.

### Request Example
```bash
cryptsetup refresh my_encrypted_volume
```

## REENCRYPT

### Description
Runs LUKS device reencryption.

### Method
Not Applicable (Command-line utility)

### Endpoint
Not Applicable (Command-line utility)

### Parameters
#### Path Parameters
- **device** (string) - Required - The LUKS device to reencrypt.
- **--active-name** (string) - Required - The name of the active mapping.
- **new_name** (string) - Optional - The new name for the reencrypted mapping.

### Request Example
```bash
cryptsetup reencrypt /dev/sda1 --active-name my_luks_volume new_volume_name
```
```

--------------------------------

### Convert Volume Key to Binary with xxd

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Convert the hexadecimal volume key obtained from 'dmsetup' into a binary file using the 'xxd' utility. This binary key file is required for recreating a LUKS header or adding a new key.

```bash
echo "a1704d9....53d0d09" | xxd -r -p > <volume-key-file>
```

--------------------------------

### Compile from Release Tarball

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/README.md

Compiles the cryptsetup project from a release tarball. The configure script is pre-generated, so autogen.sh is not needed.

```bash
tar xf cryptsetup-X.Y.Z.tar.xz
cd cryptsetup-X.Y.Z
./configure && make
```

--------------------------------

### BITLK (Windows BitLocker-compatible) Extension

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup.8.adoc

Details on cryptsetup's support for mapping BitLocker and BitLocker to Go encrypted partitions.

```APIDOC
## BITLK (Windows BitLocker-compatible) Extension

### Description
Cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted partitions using a native Linux kernel API. Header formatting and BITLK header changes are not supported; cryptsetup never changes the BITLK header on-device. This extension requires the kernel userspace crypto API.

### Compatibility
Cryptsetup recognizes most BITLK header variants, except for legacy headers from Windows Vista and partially decrypted BitLocker devices. Activation of legacy devices encrypted in CBC mode requires Linux kernel version 5.3 or later, and for devices using the Elephant diffuser, kernel 5.6 or later.

### Commands

#### OPEN

##### Description
Opens a BITLK compatible device and sets up a mapping.

##### Method
`open`

##### Endpoint
`--type bitlk <device> <name>`

##### Old Syntax
`bitlkOpen <device> <name>`

##### Unlocking Methods
Requires a password, recovery passphrase, or startup key. Unlocking using the volume key is also supported via the `--volume-key-file` option. Other methods like TPM or SmartCard are not supported.

##### See Also
`cryptsetup-open(8)`

#### DUMP

##### Description
Dumps the header information of a BITLK device. This command does not require superuser privileges.

##### Method
`bitlkDump`

##### Endpoint
`<device>`

##### See Also
`cryptsetup-bitlkDump(8)`

**Note:** cryptsetup does not use any Windows BitLocker code. Report compatibility issues to the cryptsetup project.
```

--------------------------------

### Open Plain Device with Keyring

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-open.8.adoc

Map a plain-format device using a volume key stored in a kernel keyring. The key size must match the preconfigured key in the keyring.

```bash
cryptsetup open --type plain /dev/sda10 e1 --volume-key-keyring=%trusted:mykey --cipher aes-xts-plain64 --key-size 256
```

--------------------------------

### FileVault2 Encryption

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-open.8.adoc

Instructions for opening FileVault2 compatible encrypted devices using cryptsetup.

```APIDOC
## cryptsetup fvault2Open / open --type fvault2

### Description
Opens a FVAULT2 (FileVault2 compatible) device and sets up a mapping.

### Method
`cryptsetup open --type fvault2` or `fvault2Open` (old syntax)

### Endpoint
`cryptsetup open --type fvault2 <device> <name>`

### Parameters
#### Query Parameters
- **<device>** (string) - Required - The device to open.
- **<name>** (string) - Required - The name for the mapping.

#### Other Options
- **--key-file** (string) - Optional - Path to the key file.
- **--keyfile-offset** (integer) - Optional - Offset for the key file.
- **--keyfile-size** (integer) - Optional - Size of the key file.
- **--key-size** (integer) - Optional - Size of the key.
- **--readonly** (boolean) - Optional - Open the volume in read-only mode.
- **--test-passphrase** (boolean) - Optional - Test the passphrase.
- **--allow-discards** (boolean) - Optional - Allows discard operations.
- **--volume-key-file** (string) - Optional - Path to the volume key file.
- **--tries** (integer) - Optional - Maximum number of password attempts.
- **--timeout** (integer) - Optional - Timeout for password attempts.
- **--verify-passphrase** (boolean) - Optional - Verify the passphrase.

### Available Options
* [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase]

### Request Example
```bash
cryptsetup open --type fvault2 /dev/sdX my_fvault2_volume --key-file=/path/to/keyfile
```
```

--------------------------------

### Initialize LUKS2 Encryption In-Place

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/cryptsetup-reencrypt.8.adoc

Use this command to initialize a LUKS2 encryption operation in-place without immediately encrypting the device. This prepares the device for future encryption.

```bash
cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device
```

--------------------------------

### Create dm-crypt Container with Key File

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Use the --key-file option to specify a binary key file for creating a dm-crypt container. Data read from STDIN is hashed, unlike direct key file usage.

```bash
cryptsetup create --key-file keyfile e1 /dev/loop0
```

--------------------------------

### Translate losetup to cryptsetup (Debian 5.x)

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/FAQ.md

Translates a losetup command with a byte offset to the equivalent cryptsetup command, noting that cryptsetup uses 512-byte sectors for offsets.

```bash
losetup -e twofish -o 2560 /dev/loop0 /dev/sdb1
mount /dev/loop0 mount-point
```

```bash
cryptsetup create -c twofish -o 5 --skip 5 e1 /dev/sdb1
mount /dev/mapper/e1 mount-point
```

--------------------------------

### Key File Options

Source: https://gitlab.com/cryptsetup/cryptsetup/-/blob/main/man/common_options.adoc

Documentation for options related to reading secrets from files, including handling admin PINs and PSIDs for LUKS2 devices with HW OPAL.

```APIDOC
## Key File Options

*--key-file*, *-d* _file_ (LUKS2 with HW OPAL only)::
Read the Admin PIN or PSID (with --hw-opal-factory-reset) from the file, depending on options used.

If the name given is "-", then the secret will be read from stdin. In this case, reading will not stop at newline characters.
```