# CryptSetup | LUKS cryptocontainer CheatSheet

Simple guide for creating and managing a LUKS container (5 GB, ext4).
Сontainer creation, key management, slot operations, testing keys, creating custom key files from images, managing detached headers, handling complex passphrases, and generating passphrases from BIP-39 seed phrases.

---

## Prerequisites

- **System**: Used Arch Linux.
- **Packages**: Install `cryptsetup` and `e2fsprogs`:
  ```bash
  sudo pacman -S cryptsetup e2fsprogs --noconfirm
  ```

---

## Container operations

### Create a LUKS container

1. **Create a 5 GB container file**:
   ```bash
   dd if=/dev/urandom of=/home/user/luks_container.img bs=1M count=5000 status=progress
   ```

2. **Fast LUKS container setup**

This configuration prioritizes speed while maintaining reasonable security, suitable for quick setups or less sensitive data.

```bash
cryptsetup luksFormat --type luks2 --cipher aes-xts-plain64 --key-size 256 --hash sha256 --pbkdf pbkdf2 --pbkdf-force-iterations 1000000 --use-random /home/user/luks_container.img --debug --verbose
```

- **Cryptography**: AES-XTS (AES with XTS mode), 256-bit key (128-bit AES keys split for XTS).
- **Hash**: SHA-256 for key derivation.
- **PBKDF**: PBKDF2 with 1,000,000 iterations, balancing speed and security.

2.1 **Secure LUKS container setup**

This configuration maximizes security for sensitive data, using stronger cryptographic parameters and Argon2id for key derivation, at the cost of slower setup and unlocking.

```bash
cryptsetup luksFormat --type luks2 --cipher aes-xts-plain64 --key-size 512 --hash sha512 --pbkdf argon2id --pbkdf-memory 4194304 --pbkdf-parallel 8 --iter-time 5000 --use-random --sector-size 4096 --keyslot-cipher aes-xts-plain64 --keyslot-key-size 512 --luks2-keyslots-size 16m --luks2-metadata-size 256k /home/user/luks_container.img --debug --verbose
```

- **Cryptography**: AES-XTS, 512-bit key (256-bit AES keys split for XTS); keyslots also use AES-XTS with 512-bit keys.
- **Hash**: SHA-512 for key derivation.
- **PBKDF**: Argon2id with 4 GiB memory, 8 threads, and 5-second iteration time.
- **Header**: 16 MiB keyslot area, 256 KiB metadata per copy, optimized for security and flexibility.
- **Note**: Uses `--pbkdf-memory 1048576` (1 GiB) instead of 4 GiB for better compatibility with systems having limited RAM (e.g., 4–8 GiB).


3. **Open container**:
   ```bash
   sudo cryptsetup luksOpen /home/user/luks_container.img luks_container
   ```

4. **Format with ext4**:
   ```bash
   sudo mkfs.ext4 /dev/mapper/luks_container
   ```

5. **Mount**:
   ```bash
   sudo mkdir /mnt/luks_container
   sudo mount /dev/mapper/luks_container /mnt/luks_container
   sudo chown $USER:$USER /mnt/luks_container
   ```

### Close container

1. **Unmount**:
   ```bash
   sudo umount /mnt/luks_container
   ```

2. **Close**:
   ```bash
   sudo cryptsetup luksClose luks_container --verbose --debug
   ```

---

## Key Management

### Add key file

1. **Create key file**:
   ```bash
   dd if=/dev/urandom of=/path/to/keyfile bs=4096 count=1
   ```

2. **Add to slot 3 using passphrase**:
   ```bash
   echo -n "your_passphrase" | cryptsetup luksAddKey /home/user/luks_container.img /path/to/keyfile --key-slot 3 --verbose --debug --key-file=-
   ```

3. **Add to slot 0 using key file from slot 3**:
   ```bash
   dd if=/dev/urandom of=/path/to/new_keyfile bs=4096 count=1
   cryptsetup luksKillSlot /home/user/luks_container.img 0 --key-file /path/to/keyfile_slot3 --verbose --debug
   cryptsetup luksAddKey /home/user/luks_container.img --key-slot 0 /path/to/new_keyfile --key-file /path/to/keyfile_slot3 --verbose --debug
   ```

### Add Passphrase to specific slot

- **Add complex passphrase to slot 4 using existing key file**:
  ```bash
  echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | cryptsetup luksAddKey /home/user/luks_container.img --key-slot 4 --key-file /path/to/keyfile --verbose --debug --new-keyfile=-
  ```
  - Replace `/path/to/keyfile` with the path to your existing key file.
  - `--new-keyfile=-` reads the new passphrase from stdin.


- **Add to LUKS with escaped passphrase**:
  ```bash
  echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | cryptsetup luksAddKey /home/user/luks_container.img --key-slot 4 --key-file /path/to/keyfile --verbose --debug --new-keyfile=-
  ```

- **Test complex passphrase**:
  ```bash
  echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | cryptsetup open --test-passphrase --key-slot 4 /home/user/luks_container.img --verbose --debug --key-file=-
  ```

### Generate passphrase from BIP-39 seed phrase

Generate passphrase from a 12-word BIP-39 seed phrase using a deterministic password generator (7w) and add it to a LUKS key slot. 
This method allows passphrase recovery from the seed phrase alone.

#### Steps

1. **Generate a 12-word BIP-39 seed phrase**:
   - Use a secure BIP-39 seed phrase generator, preferably offline, to create a 12-word mnemonic compliant with the BIP-39 standard. Example tool: https://cryptony.app/seed-phase-generator/
   
   - **Example seed phrase**:
     ```
     property iron shove feature tide parent army neglect stable lab ostrich zone
     ```

2. **Convert seed phrase to passphrase**:
   - Use the 7w deterministic password generator (https://dlepex.github.io/7w/index.html) to convert the seed phrase into a complex passphrase. The tool operates client-side in the browser and does not store or transmit data.
   - **Configuration**:
     - Set `w=12` (12 words).
     - Set `mod=v` (visible mode).
   - **Steps**:
     - Open https://dlepex.github.io/7w/index.html#w=12&mod=v
     - Enter the seed phrase (e.g., `property iron shove feature tide parent army neglect stable lab ostrich zone`).
     - Generate the passphrase.
   - **Example Output**:
     ```
     <0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{
     ```

   **Sceenshot 1**: Convert seed phrase to passphrase
   ![1](https://gist.github.com/user-attachments/assets/1eb04ff6-fd80-4fd0-900d-03e39a2d651c)
  


3. **Add passphrase to LUKS key slot**:
   - Add the generated passphrase to slot 4 using an existing key file for authentication.
   - **Command**:
     ```bash
     echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | cryptsetup luksAddKey /home/user/luks_container.img --key-slot 4 --key-file /path/to/keyfile --verbose --debug --new-keyfile=-
     ```
     - Replace `/path/to/keyfile` with the path to your existing key file.
     - Ensure proper escaping (e.g., `\\` for `\`, `\`` for ```, `\\n` for `\n`).

   - **Verify output**:
     ```bash
     echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | hexdump -C
     ```
     Expected output:
     ```
     00000000  3c 30 62 6e 7d 30 58 39  4f 3c 52 55 66 3a 74 52  |<0bn}0X9O<RUf:tR|
     00000010  5f 43 5a 3b 6d 61 38 22  2c 3a 5c 44 51 2a 7d 39  |_CZ;ma8",:\DQ*}9|
     00000020  41 2a 78 42 34 38 53 2d  4c 50 36 4c 37 48 4a 28  |A*xB48S-LP6L7HJ(|
     00000030  4b 69 48 60 36 30 4c 0a  49 33 4f 41 48 6a 7b     |KiH`60L.I3OAHj{|
     0000003f
     ```
   - **Test passphrase**:
     ```bash
     echo -n '<0bn}0X9O<RUf:tR_CZ;ma8",:\DQ*}9A*xB48S-LP6L7HJ(KiH`60L\nI3OAHj{' | cryptsetup open --test-passphrase --key-slot 4 /home/user/luks_container.img --verbose --debug --key-file=-
     ```

### Test keys

- **Test passphrase**:
  ```bash
  cryptsetup open --test-passphrase /home/user/luks_container.img --verbose --debug
  ```

- **Test key file**:
  ```bash
  cryptsetup open --test-passphrase --key-file /path/to/keyfile /home/user/luks_container.img --verbose --debug
  ```

- **Test specific slot**:
  ```bash
  cryptsetup open --test-passphrase --key-slot 4 /home/user/luks_container.img --verbose --debug
  ```

### Remove key slot

- **Remove slot 0**:
  ```bash
  cryptsetup luksKillSlot /home/user/luks_container.img 0 --key-file /path/to/keyfile_slot3 --verbose --debug
  ```

### Custom key from image

Create a key file from an image by downloading it, verifying its SHA512 hash, modifying it with binary data (prepend 10 `0x31` bytes, append 10 `0x2E` bytes), and adding it to a LUKS container.

#### Steps

1. **Download and modify image**:
   Use this script to download image file, verify hash, and create a key file.

#### Bash script

```bash
#!/bin/bash

set -e

# Log function with timestamp (Python-style)
log() {
    local level="$1"
    local message="$2"
    local extra="${3:-}"
    printf "[%s] [%-5s] %s %s\n" "$(date '+%Y-%m-%d %H:%M:%S')" "$level" "$message" "$extra"
}

# Error exit with cleanup
error_exit() {
    log "ERROR" "$1"
    rm -f "$TMP_FILE" "$OUTPUT_KEY"
    exit 1
}

# Check dependencies
for cmd in wget sha512sum printf; do
    command -v "$cmd" &>/dev/null || error_exit "missing $cmd"
done

URL="https://upload.wikimedia.org/wikipedia/commons/2/2c/TerryFoxToronto19800712.JPG"
EXPECTED_HASH="f1db6ca08d665e29e4462a5384ee7cb440345d7147fd6589a2515b876f053b6f048de0bdb6507443336fcee51552e571ea2af3bc4e180472ccddf608ee06fc6f"
EXPECTED_MODIFIED_HASH="726f581b49461e5d48de1d94f2c64cd2510afd312bb093fe3a4ec106f7b035e1eaf10233112e8aeb04a5eeaf0bedacce503cfcd27a8c70b107538528a802301d"
TMP_FILE="/tmp/tmp_key"
OUTPUT_KEY="/tmp/luks_key"

# Download image
log "INFO" "downloading file" "$URL"
wget --no-check-certificate -O "$TMP_FILE" "$URL" 2>/dev/null || error_exit "download failed"

# Verify original file hash
log "INFO" "verifying original file hash"
HASH=$(sha512sum "$TMP_FILE" | cut -d' ' -f1)
[ "$HASH" = "$EXPECTED_HASH" ] || error_exit "hash mismatch: got $HASH, expected $EXPECTED_HASH"

# Modify: prepend 10 '1' (0x31), append 10 '.' (0x2E)
log "INFO" "modifying key file"
{ printf "\x31\x31\x31\x31\x31\x31\x31\x31\x31\x31"; cat "$TMP_FILE"; printf "\x2E\x2E\x2E\x2E\x2E\x2E\x2E\x2E\x2E\x2E"; } > "$OUTPUT_KEY" || error_exit "modification failed"
log "INFO" "key file modification completed"

# Verify modified file hash
log "INFO" "verifying modified file hash"
MODIFIED_HASH=$(sha512sum "$OUTPUT_KEY" | cut -d' ' -f1)
[ "$MODIFIED_HASH" = "$EXPECTED_MODIFIED_HASH" ] || error_exit "modified file hash mismatch: got $MODIFIED_HASH, expected $EXPECTED_MODIFIED_HASH"
log "INFO" "modified file hash verified successfully"

# Cleanup
log "INFO" "cleaning up temporary file"
rm -f "$TMP_FILE" || error_exit "cleanup failed"

log "INFO" "created $OUTPUT_KEY"
```

Prepend 10 `0x31` bytes:

  ```hexdump
     00000000: 3131 3131 3131 3131 3131 ffd8 ffe0 0010  1111111111......
     00000010: 4a46 4946 0001 0101 0060 0060 0000 ffe1  JFIF.....`.`....
     00000020: 1b02 4578 6966 0000 4949 2a00 0800 0000  ..Exif..II*.....
     00000030: 0700 1201 0300 0100 0000 0100 0000 1a01  ................
     00000040: 0500 0100 0000 6200 0000 1b01 0500 0100  ......b.........
     00000050: 0000 6a00 0000 2801 0300 0100 0000 0200  ..j...(.........
     00000060: 0000 3101                                ..1.
  ```

Append 10 `0x2E` bytes:

  ```hexdump
     00000000: d618 dff8 6ecf ff00 9353 e81f 2fff 00ae  ....n....S../...
     00000010: 8fff 007c 8fff 00c1 f51c f2af f5f1 dffd  ...|............
     00000020: e13f fd7f a7e7 10ff 00a3 e9ff 00f8 1a7f  .?..............
     00000030: fd7b 1f4d dd8f fa2c 7ff0 f57f f5a3 e9a4  .{.M...,........
     00000040: effa e74b ff00 88ff 00fe ad6f a6cb 3fea  ...K.......o..?.
     00000050: ec6f fdca 7ff9 87f5 ffd9 2e2e 2e2e 2e2e  .o..............
     00000060: 2e2e 2e2e                                ....
  ```


2. **Add key to LUKS**:
   ```bash
   sudo cryptsetup luksAddKey /home/user/luks_container.img /tmp/luks_key --key-slot 3 --verbose --debug
   ```

3. **Test key**:
   ```bash
   cryptsetup open --test-passphrase --key-file /tmp/luks_key /home/user/luks_container.img --verbose --debug
   ```


---

## Header backup

- **Backup header**:
  ```bash
  cryptsetup luksHeaderBackup /home/user/luks_container.img --header-backup-file /path/to/luks_header_backup --verbose --debug
  ```

- **Restore header**:
  ```bash
  cryptsetup luksHeaderRestore /home/user/luks_container.img --header-backup-file /path/to/luks_header_backup --verbose --debug
  ```

---

## Detached header management

Manage a LUKS container with a detached header for enhanced security by storing the header separately from the container data. 
This can be done by extracting the header from an existing container or creating a new one with a detached header.

### Create container with detached header

1. **Create container and header**:
   ```bash
   dd if=/dev/urandom of=/home/user/luks_container.img bs=1M count=5000 status=progress
   cryptsetup luksFormat --type luks2 --header /path/to/header.bin /home/user/luks_container.img --verbose --debug
   ```
   Set a strong passphrase.

2. **Open container**:
  ```bash
  cryptsetup luksOpen --header /path/to/header.bin /home/user/luks_container.img luks_container
  ```

3. **Format and mount**:
   ```bash
   sudo mkfs.ext4 /dev/mapper/luks_container
   sudo mkdir /mnt/luks_container                                     
   sudo mount /dev/mapper/luks_container /mnt/luks_container
   sudo chown $USER:$USER /mnt/luks_container
   ```

### Extract header from existing container

1. **Backup existing header**:  
   ```bash
   cryptsetup luksHeaderBackup /home/user/luks_container.img --header-backup-file /path/to/header.bin --verbose --debug
   ```

2. **Verify header**:
   ```bash
   cryptsetup luksDump --header /path/to/header.bin /home/user/luks_container.img
   ```

3. **Remove header from container** (optional, for security):
   ```bash
   dd if=/dev/zero of=/home/user/luks_container.img bs=1M count=4 conv=notrunc
   ```
   This overwrites the first 4 MB (typical LUKS header size) to remove the header from the container.

### Mount with detached header

1. **Open container**:
  ```bash
  cryptsetup luksOpen --header /path/to/header.bin /home/user/luks_container.img luks_container
  ```

2. **Mount**:
   ```bash
   sudo mount /dev/mapper/luks_container /mnt/luks_container
   ```

3. **Unmount and close**:
   ```bash
   sudo umount /mnt/luks_container
   sudo cryptsetup luksClose luks_container
   ```

### Backup and restore detached header

- **Backup header**:
   ```bash
   cryptsetup luksHeaderBackup --header /path/to/header.bin /home/user/luks_container.img --header-backup-file /path/to/header_backup.bin --verbose --debug
   ```

- **Restore header**:
   ```bash
   cryptsetup luksHeaderRestore --header /path/to/header.bin /home/user/luks_container.img --header-backup-file /path/to/header_backup.bin --verbose --debug
   ```

---