path: root/src/linux/cryptsetup.md

# [cryptsetup(8)][man-cryptsetup8]

```text
cryptsetup <action> [opts] <action args>

action:
    open <dev> <name> --type <type>    Open (decrypt) <dev> and map with <name>.
                                       Mapped as /dev/mapper/<name>.
                                       Type: {luks,plain,tcrypt,bitlk}
    close <name>                       Close existing mapping <name>.
    status <name>                      Print status for mapping <name>.

    luksFormat <dev>                   Create new LUKS partition and set initial passphrase.
                                       (Keyslot 0)
    luksAddKey <dev>                   Add a new passphrase.
    luksRemoveKey <dev>                Remove existing passphrase.
    luksChangeKey <dev>                Change existing passphrase.
    lusDump <dev>                      Dump LUKS header for device.
```

## Example: Create `LUKS` encrypted disk.

For this example we use a file as backing storage and set it up as
[loop(4)][man-loop4] device. The loop device can be replaced by any block
device file.

> Optional: Overwrite existing data on disk.\
> `sudo dd if=/dev/urandom of=/dev/sdX bs=1M`

First create the backing file and setup the loop device.

```sh
# Create 100MB file.
dd if=/dev/zero of=blkfile bs=1M count=100

# Attach file to first free (-f) loop device
sudo losetup -f ./blkfile
# List loop devices.
sudo losetup -l
# NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE              DIO LOG-SEC
# /dev/loop0         0      0         0  0 /home/johannst/blkfile   0     512
```

Create a new LUKS partition and format new filesystem.

```sh
# Initialize LUKS partition and set initial passphrase.
sudo cryptsetup luksFormat /dev/loop0

file blkfile
# blkfile: LUKS encrypted file, ver 2 [, , sha256] UUID: 8...

# Open (decrypt) the LUKS device, it will be mapped under /dev/mapper/loop0.
sudo cryptsetup open --type luks /dev/loop0 loop0

# Format partition with new filesystem.
sudo mkfs.vfat /dev/mapper/loop0

lsblk -f
# NAME        FSTYPE    FSVER LABEL  UUID  FSAVAIL FSUSE% MOUNTPOINTS
# loop0       crypto_LU 2            8...
# └─loop0     vfat      FAT16        D...    83.8M     0% /home/johannst/mnt

# Close (re-encrypt) LUKS device.
sudo cryptsetup close loop0
```

## Example: Using an existing LUKS device.

```sh
# Open (decrypt) the LUKS device, it will be mapped under /dev/mapper/loop0.
sudo cryptsetup open --type luks /dev/loop0 loop0

# Mount filesystem.
sudo mount /dev/mapper/loop0 <mntpoint>

# Use disk ...

# Unmount filesystem.
sudo umount <mntpoint>

# Close (re-encrypt) LUKS device.
sudo cryptsetup close loop0
```

[man-loop4]: https://man7.org/linux/man-pages/man4/loop.4.html
[man-cryptsetup8]: https://www.man7.org/linux/man-pages/man8/cryptsetup.8.html