Password-based Uniform-Random-Equivalent Encryption

How do I install puree?

While the PUREE disk format is platform-independent, the puree command-line tool currently only supports Linux.

As a prerequisite, the following system libraries must be installed:

# Debian, Ubuntu:
sudo apt install python3 python3-pip python3-setuptools libsodium23

# Red Hat, Fedora:
sudo dnf install python3 python3-pip python3-setuptools libsodium

Install puree with:

sudo python3 -m pip install puree

(Usually, using sudo to perform pip install is not recommended. However, because puree uses device-mapper which usually requires root access, and because disk devices usually require root access, puree is usually invoked with sudo—therefore we install with sudo because, otherwise, sudo tends to hide userspace-installed Python packages from the PATH.)

How do I use it?

Let's go through the complete flow, from formatting a device with PUREE all the way to mounting it.

WARNING: By formatting a device with PUREE, you will be wiping (essentially) all data from it. Check and double-check that you are encrypting the device you think you are.

We'll encrypt device /dev/sdz with AES-256 in XTS mode.

First, format the disk with PUREE:

sudo puree format /dev/sdz aes256-xts-plain64

You will be prompted for a password. For now, just type "apassword".

NOTE: The first character of the password is important, because PUREE will require you to prefix your password with a "parameter character"; see the "Choosing a parameter character" section below for more information.

Your device should now be encrypted.

Next, you'll need to "map" your encrypted disk device to a new virtual device:

sudo puree map /dev/sdz /dev/mapper/sdz

(You will be prompted to enter the disk's password.)

The virtual device should now be available at /dev/mapper/sdz; you can now treat /dev/mapper/sdz as you would a normal disk device.

For example, to format it with a filesystem, then mount it:

sudo mkfs.ext4 /dev/mapper/sdz
sudo mount /dev/mapper/sdz /mnt

You now have an encrypted fileystem available at /mnt.

To unmap the device, run:

sudo puree unmap /dev/mapper/sdz

To prove to yourself that the disk is encrypted, try running sudo hexdump -C /dev/sdz | less, and you'll see something like this:

3ac41e42da074126fb9d4c6a01a15f56  |...B..A&..Lj.._V|
c71c6c473a891a0777af909a4efb1a8f  |..lG:...w...N...|
72fc3eac1766db1d55d2c0cd14a666bd  |r.>..f..U.....f.|
5592d610bbc3ad8146eb2bf7cec566b6  |U.......F.+...f.|
8c44df178868323dd175458d4327d107  |.D...h2=.uE.C'..|
6dbf3af811083156dd3bb23583826b62  |m.:...1V.;.5..kb|
fad3a02d48acebc57b79ce68ec9e68f1  |...-H...{y.h..h.|
4c5daf931a2bb71face7f417ca627d05  |L]...+.......b}.|
39568ce65ec12f5838c056d3d682d728  |9V..^./X8.V....(|
446df278d823fee0ff2f4c04434b5f5e  |Dm.x.#.../L.CK_^|
bc42583055c455cdb4439385c59bf3fd  |.BX0U.U..C......|
62019305a5f38ce912c0c13876f31f1b  |b..........8v...|
8e67545ae3abf95a2247fc0c5c55558c  |.gTZ...Z"G....U.|
01c623448fbb35df80b313da63269760  |..#D..5.....c&.`|
4dfbd88dd32a1179e4038d7c3c4412eb  |M....*.y...|<D..|
c856ecfe15e5c4a5d7f12165628c05b8  |.V........!eb...|
6c00f7e2dcb39dcedff67d1de9551eaa  |l.........}..U..|
d9e24fd60f42b399ed18adec4de8912a  |..O..B......M..*|
2316e4131712a0a7044b96d3154d1b2f  |#........K...M./|
67a623656f15d733f4541fc78781bfd3  |g.#eo..3.T......|

Now that you've done all that, be aware that, to truly keep your disk indistinguishable from random, you should first completely wipe the disk with random data:

sudo puree destroy /dev/sdz

Then repeat the previous steps. (Previously, we left this step out as it tends to take a while.)

Choosing a parameter character

puree encrypts disks in such a way that its primary key is derived using the argon2id password-key derivation function. In order to calculate a derived key from a password, however, a few parameters are required:

  1. Parallelism: the maximum number of parallel CPU threads
  2. Memory: the amount of RAM required
  3. Iterations: multiplier on amount of time required

One goal of PUREE is that the disk must be indistinguishable from random data. This means these parameters can not be stored on the disk. Instead, PUREE stores these parameters in the password. Every PUREE password must be prefixed with a special character, called the "parameter character". Current valid values are:

'b' =>175MiB1
'c' =>1250MiB1
'd' =>4250MiB4
'e' =>11GiB1
'f' =>41GiB4
'g' =>14GiB1
'h' =>44GiB4
'i' =>116GiB1
'j' =>416GiB4

There's also the (not recommended) character:

'a' =>simply hash the salt and password with blake2b

As CPU and RAM become cheaper, more parameter characters will be added to this table.