# Cryptsetup

## Table of contents <!-- omit in toc -->

1. [TL;DR](#tldr)
1. [Crypt a device](#crypt-a-device)
1. [Troubleshooting](#troubleshooting)
   1. [The process is killed due to too much memory used](#the-process-is-killed-due-to-too-much-memory-used)
1. [Further readings](#further-readings)

## TL;DR

```sh
# crypt a device
sudo cryptsetup luksFormat /dev/sdb
sudo cryptsetup luksOpen /dev/sdb crypted-device
sudo mkfs.btrfs --label data /dev/mapper/crypted-device
sudo mount --types btrfs --options compress-force=zstd:3 /dev/mapper/crypted-device /media/data
sudo umount /media/data
sudo cryptsetup luksClose /dev/mapper/crypted-device
```

## Crypt a device

1. create the luks partition

   ```sh
   sudo cryptsetup luksFormat /dev/sdb
   ```

   as of cryptsetup version 2.3.4, this is equivalent to

   ```sh
   cryptsetup --type luks2 --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 256 --pbkdf argon2i --sector-size 512 --use-urandom --verify-passphrase luksFormat device
   ```

1. open the luks partition

   ```sh
   sudo cryptsetup luksOpen /dev/sdb samsung_860_evo_1tb
   ```

1. format the partition

   ```sh
   sudo mkfs.btrfs --label samsung_860_evo_1tb /dev/mapper/samsung_860_evo_1tb
   ```

1. mount the partition

   ```sh
   sudo mount --types btrfs --options compress-force=zstd:0,nodev,nosuid,uhelper=udisks2 /dev/mapper/samsung_860_evo_1tb /mnt/samsung_860_evo_1tb
   ```

1. do what you need
1. umount the partition

   ```sh
   sudo umount /mnt/samsung_860_evo_1tb
   ```

1. close the luks partition

   ```sh
   sudo cryptsetup luksFormat /dev/sdb
   ```

## Troubleshooting

### The process is killed due to too much memory used

Should you get the following result during any operation:

```sh
$ sudo cryptsetup luksOpen /dev/sdb1 crypted-data
Enter passphrase for /dev/sdb1: ***
killed
```

it could be the process is using too much memory.<br/>
This is due to the LUKS2 format using by default the Argon2i key derivation function, that is so called _memory-hard function_ - it requires certain amount of physical memory (to make dictionary attacks more costly).

The solution is simple; either:

1. switch to LUKS1, or
1. use LUKS2, but switch to PBKDF2 (the one used in LUKS1); just add the `--pbkdf pbkdf2` option to luksFormat or to any command that creates keyslots, or
1. use LUKS2 but limit the memory assigned to Argon2i function; for example, to use up to 256kB just add the `--pbkdf-memory 256` option to the command as follows:

   ```sh
   $ sudo cryptsetup luksOpen --pbkdf-memory 256 /dev/sdb1 lacie
   Enter passphrase for /dev/sda1: ***
   ```

## Further readings

- [arch linux wiki]
- [btrfs man page]
- [High memory usage when opening a LUKS2 partition]

<!--
  References
  -->

<!-- Others -->
[arch linux wiki]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[btrfs man page]: https://btrfs.wiki.kernel.org/index.php/Manpage/btrfs(5)
[high memory usage when opening a luks2 partition]: https://gitlab.com/cryptsetup/cryptsetup/issues/372
