+ - Reencrypt the LUKS header with a different hash. (Requires entering
+ all keyslot passphrases. If you do not have all, remove the ones you
+ do not have before.):
+
+ cryptsetup-reencrypt --keep-key --hash sha256 <your luks device>
+
+ If gcrypt is at version 1.6.1 or later:
+
+ - Patch the hash name in the LUKS header from "whirlpool" to
+ "whirlpool_gcryptbug". This activates the broken implementation.
+ The detailed header layout is in Item 6.12 of this FAQ and in the
+ LUKS on-disk format specification. One way to change the hash is
+ with the following command:
+
+ echo -n -e 'whirlpool_gcryptbug\0' | dd of=<luks device> bs=1 seek=72 conv=notrunc
+
+ - You can now open the device again. It is highly advisable to change
+ the hash now with cryptsetup-reencrypt as described above. While you
+ can reencrypt to use the fixed whirlpool, that may not be a good idea
+ as almost nobody seems to use it and hence the long time until the
+ bug was discovered.
+
+
+9. The Initrd question
+
+
+ * 9.1 My initrd is broken with cryptsetup
+
+ That is not nice! However the initrd is supplied by your distribution,
+ not by the cryptsetup project and hence you should complain to them. We
+ cannot really do anything about it.
+
+
+ * 9.2 CVE-2016-4484 says cryptsetup is broken!
+
+ Not really. It says the initrd in some Debian versions have a behavior
+ that under some very special and unusual conditions may be considered
+ a vulnerability.
+
+ What happens is that you can trick the initrd to go to a rescue-shell if
+ you enter the LUKS password wrongly in a specific way. But falling back
+ to a rescue shell on initrd errors is a sensible default behavior in the
+ first place. It gives you about as much access as booting a rescue
+ system from CD or USB-Stick or as removing the disk would give you. So
+ this only applies when an attacker has physical access, but cannot boot
+ anything else or remove the disk. These will be rare circumstances
+ indeed, and if you rely on the default distribution initrd to keep you
+ safe under these circumstances, then you have bigger problems than this
+ somewhat expected behavior.
+
+ The CVE was exagerrated and should not be assigned to upstream
+ cryptsetup in the first place (it is a distro specific initrd issue).
+ It was driven more by a try to make a splash for self-aggrandizement,
+ than by any actual security concerns. Ignore it.
+
+
+ * 9.3 How do I do my own initrd with cryptsetup?
+
+ Note: The instructions here apply to an initrd in initramfs format, not
+ to an initrd in initrd format. The latter is a filesystem image, not a
+ cpio-archive, and seems to not be widely used anymore.
+
+ It depends on the distribution. Below, I give a very simple example and
+ step-by-step instructions for Debian. With a bit of work, it should be
+ possible to adapt this to other distributions. Note that the
+ description is pretty general, so if you want to do other things with an
+ initrd it provides a useful starting point for that too.
+
+ 01) Unpacking an existing initrd to use as template
+
+ A Linux initrd is in gzip'ed cpio format. To unpack it, use something
+ like this:
+
+ md tmp; cd tmp; cat ../initrd | gunzip | cpio -id
+
+ After this, you have the full initrd content in tmp/
+
+ 02) Inspecting the init-script
+
+ The init-script is the only thing the kernel cares about. All activity
+ starts there. Its traditional location is /sbin/init on disk, but /init
+ in an initrd. In an initrd unpacked as above it is tmp/init.
+
+ While init can be a binary despite usually being called "init script",
+ in Debian the main init on the root partition is a binary, but the init
+ in the initrd (and only that one is called by the kernel) is a script
+ and starts like this:
+
+ #!/bin/sh
+ ....
+
+ The "sh" used here is in tmp/bin/sh as just unpacked, and in Debian it
+ currently is a busybox.
+
+ 03) Creating your own initrd
+
+ The two examples below should give you most of what is needed. This is
+ tested with LUKS1 and should work with LUKS2 as well. If not, please
+ let me know.
+
+ Here is a really minimal example. It does nothing but set up some
+ things and then drop to an interactive shell. It is perfect to try out
+ things that you want to go into the init-script.
+
+ #!/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
+
+
+ Here is an example that opens the first LUKS-partition it finds with the
+ hard-coded password "test2" and then mounts it as root-filesystem. This
+ is intended to be used on an USB-stick that after boot goes into a safe,
+ as it contains the LUKS-passphrase in plain text and is not secure to be
+ left in the system. The script contains debug-output that should make it
+ easier to see what is going on. Note that the final hand-over to the init
+ on the encrypted root-partition is done by "exec switch_root /mnt/root
+ /sbin/init", after mounting the decrypted LUKS container with "mount
+ /dev/mapper/c1 /mnt/root". The second argument of switch_root is relative
+ to the first argument, i.e. the init started with this command is really
+ /mnt/sbin/init before switch_root runs.
+
+ #!/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
+ if expr $r = 0 > /dev/null
+ then
+ echo " is LUKS, attempting unlock"
+ echo -n "test2" | cryptsetup luksOpen --key-file=- $d c1
+ r=$?
+ echo " result of unlock attempt: "$r""
+ sleep 2
+ if expr $r = 0 > /dev/null
+ then
+ echo "*** LUKS partition unlocked, switching root ***
+ echo " (waiting 30 seconds before doing that)"
+ mount /dev/mapper/c1 /mnt/root
+ sleep 30
+ exec switch_root /mnt/root /sbin/init
+ fi
+ else
+ echo " is not LUKS"
+ fi
+ done
+ done
+ echo "FAIL finding root on LUKS, loading BusyBox..."; sleep 5
+ exec /bin/sh --login
+
+
+ 04) What if I want a binary in the initrd, but libraries are missing?
+
+ That is a bit tricky. One option is to compile statically, but that
+ does not work for everything. Debian puts some libraries into lib/ and
+ lib64/ which are usually enough. If you need more, you can add the
+ libraries you need there. That may or may not need a configuration
+ change for the dynamic linker "ld" as well. Refer to standard Linux
+ documentation on how to add a library to a Linux system. A running
+ initrd is just a running Linux system after all, it is not special in
+ any way.
+
+ 05) How do I repack the initrd?
+
+ Simply repack the changed directory. While in tmp/, do
+ the following:
+ ```
+ find . | cpio --create --format='newc' | gzip > ../new_initrd
+ ```
+ Rename "new_initrd" to however you want it called (the name of
+ the initrd is a kernel-parameter) and move to /boot. That is it.
+
+
+10. LUKS2 Questions
+
+
+ * 10.1 Is the cryptography of LUKS2 different?
+
+ Mostly not. The header has changed in its structure, but the
+ crytpgraphy is the same. The one exception is that PBKDF2 has been
+ replaced by Argon2 to give better resilience against attacks attacks by
+ graphics cards and other hardware with lots of computing power but
+ limited local memory per computing element.
+
+
+ * 10.2 What new features does LUKS2 have?
+
+ There are quite a few. I recommend reading the man-page and the on-disk
+ format specification, see Item 1.2.
+
+ To list just some:
+ - A lot of the metadata is JSON, allowing for easier extension
+ - Max 32 key-slots per default
+ - Better protection for bad passphrases now available with Argon2
+ - Authenticated encryption
+ - The LUKS2 header is less vulnerable to corruption and has a 2nd copy
+
+
+ * 10.3 Why does LUKS2 need so much memory?
+
+ LUKS2 uses Argon2 instead of PBKDF2. That causes the increase in memory.
+ See next item.
+
+
+ * 10.4 Why use Argon2 in LUKS 2 instead of PBKDF2?
+
+ LUKS tries to be secure with not-so-good passwords. Bad passwords need to
+ be protected in some way against an attacker that just tries all possible
+ combinations. (For good passwords, you can just wait for the attacker to
+ die of old age...) The situation with LUKS is not quite the same as with a
+ password stored in a database, but there are similarities.
+
+ LUKS does not store passwords on disk. Instead, the passwords are used to
+ decrypt the master-key with it and that one is stored on disk in encrypted
+ form. If you have a good password, with, say, more than 80 bits of
+ entropy, you could just put the password through a single crypto-hash (to
+ turn it into something that can be used as a key) and that would be secure.
+ This is what plain dm-crypt does.
+
+ If the password has lower entropy, you want to make this process cost some
+ effort, so that each try takes time and resources and slows the attacker
+ down. LUKS1 uses PBKDF2 for that, adding an iteration count and a salt.
+ The iteration count is per default set to that it takes 1 second per try on
+ the CPU of the device where the respective passphrase was set. The salt is
+ there to prevent precomputation.
+
+ The problem with that is that if you use a graphics card, you can massively
+ speed up these computations as PBKDF2 needs very little memeory to compute
+ it. A graphics card is (grossly simplified) a mass of small CPUs with some
+ small very fast local memory per CPU and a large slow memory (the 4/6/8 GB
+ a current card may have). If you can keep a computation in the small,
+ CPU-local memory, you can gain a speed factor of 1000 or more when trying
+ passwords with PBKDF2.
+
+ Argon2 was created to address this problem. It adds a "large memory
+ property" where computing the result with less memory than the memory
+ parameter requires is massively (exponentially) slowed down. That means,
+ if you set, for example, 4GB of memory, computing Argon2 on a graphics card
+ with around 100kB of memory per "CPU" makes no sense at all because it is
+ far too slow. An attacker has hence to use real CPUs and furthermore is
+ limited by main memory bandwith.
+
+ Hence the large amount of memory used is a security feature and should not
+ be turned off or reduced. If you really (!) understand what you are doing
+ and can assure good passwords, you can either go back to PBKDF2 or set a
+ low amount of memory used for Argon2 when creating the header.
+
+
+ * 10.5 LUKS2 is insecure! It uses less memory than the Argon2 RFC say!
+
+ Well, not really. The RFC recommends 6GiB of memory for use with disk
+ encryption. That is a bit insane and something clearly went wrong in the
+ standardization process here. First, that makes Argon2 unusable on any 32
+ bit Linux and that is clearly a bad thing. Second, there are many small
+ Linux devices around that do not have 6GiB of RAM in the first place. For
+ example, the current Raspberry Pi has 1GB, 2GB or 4GB of RAM, and with the
+ RFC recommendations, none of these could compute Argon2 hashes.
+
+ Hence LUKS2 uses a more real-world approach. Iteration is set to a
+ minimum of 4 because there are some theoretical attacks that work up to an
+ iteration count of 3. The thread parameter is set to 4. To achieve 2
+ second/slot unlock time, LUKS2 adjusts the memory parameter down if
+ needed. In the other direction, it will respect available memory and not
+ exceed it. On a current PC, the memory parameter will be somewhere around
+ 1GB, which should quite generous. The minimum I was able to set in an
+ experiment with "-i 1" was 400kB of memory and that is too low to be
+ secure. A Raspberry Pi would probably end up somewhere around 50MB (have
+ not tried it) and that should still be plenty.
+
+ That said, if you have a good, high-entropy passphrase, LUKS2 is secure
+ with any memory parameter.
+
+
+ * 10.6 How does re-encryption store data while it is running?
+
+ All metadata necessary to perform a recovery of said segment (in case of
+ crash) is stored in the LUKS2 metadata area. No matter if the LUKS2
+ reencryption was run in online or offline mode.
+
+
+ * 10.7 What do I do if re-encryption crashes?
+
+ In case of a reencryption application crash, try to close the original
+ device via following command first:
+
+ cryptsetup close <my_crypt_device>.
+
+ Cryptsetup assesses if it's safe to teardown the reencryption device stack
+ or not. It will also cut off I/O (via dm-error mapping) to current
+ hotzone segment (to make later recovery possible). If it can't be torn
+ down, i.e. due to a mounted fs, you must unmount the filesystem first.
+ Never try to tear down reencryption dm devices manually using e.g.
+ dmsetup tool, at least not unless cryptsetup says it's safe to do so. It
+ could damage the data beyond repair.
+
+
+ * 10.8 Do I need to enter two passphrases to recover a crashed
+ re-encryption?
+
+ Cryptsetup (command line utility) expects the passphrases to be identical
+ for the keyslot containing old volume key and for the keyslot containing
+ new one. So the recovery happens during normal the "cryptsetup open"
+ operation or the equivalent during boot.
+
+ Re-encryption recovery can be also performed in offline mode by
+ the "cryptsetup repair" command.
+
+
+ * 10.9 What is an unbound keyslot and what is it used for?
+
+ Quite simply, an 'unbound key' is an independent 'key' stored in a luks2
+ keyslot that cannot be used to unlock a LUKS2 data device. More specifically,
+ an 'unbound key' or 'unbound luks2 keyslot' contains a secret that is not
+ currently associated with any data/crypt segment (encrypted area) in the
+ LUKS2 'Segments' section (displayed by luksDump).
+
+ This is a bit of a more general idea. It basically allows to use a keyslot
+ as a container for a key to be used in other things than decrypting a
+ data segment.
+
+ As of April 2020, the following uses are defined:
+
+ 1) LUKS2 re-encryption. The new volume key is stored in an unbound keyslot
+ which becomes a regular LUKS2 keyslot later when re-encryption is
+ finished.
+
+ 2) Somewhat similar is the use with a wrapped key scheme (e.g. with the
+ paes cipher). In this case, the VK (Volume Key) stored in a keyslot
+ is an encrypted binary binary blob. The KEK (Key Encryption Key) for
+ that blob may be refreshed (Note that this KEK is not managed by
+ cryptsetup!) and the binary blob gets changed. The KEK refresh process
+ uses an 'unbound keyslot'. First the future effective VK is placed
+ in the unbound keyslot and later it gets turned into the new real VK
+ (and bound to the respective crypt segment).
+
+
+ * 10.10 What about the size of the LUKS2 header?
+
+ While the LUKS1 header has a fixed size that is determined by the cipher
+ spec (see Item 6.12), LUKS2 is more variable. The default size is 16MB,
+ but it can be adjusted on creation by using the --luks2-metadata-size
+ and --luks2-keyslots-size options. Refer to the man-page for details.
+ While adjusting the size in an existing LUKS2 container is possible,
+ it is somewhat complicated and risky. My advice is to do a backup,
+ recreate the container with changed parameters and restore that backup.
+
+
+ * 10.11 Does LUKS2 store metadata anywhere except in the header?
+
+ It does not. But note that if you use the experimental integrity support,
+ there will be an integrity header as well at the start of the data area
+ and things get a bit more complicated. All metadata will still be at the
+ start of the device, nothing gets stored somewhere in the middle or at
+ the end.
+
+
+11. References and Further Reading
+
+ * Purpose of this Section
+
+ The purpose of this section is to collect references to all materials
+ that do not fit the FAQ but are relevant in some fashion. This can be
+ core topics like the LUKS spec or disk encryption, but it can also be
+ more tangential, like secure storage management or cryptography used in
+ LUKS. It should still have relevance to cryptsetup and its
+ applications.
+
+ If you want to see something added here, send email to the maintainer
+ (or the cryptsetup mailing list) giving an URL, a description (1-3 lines
+ preferred) and a section to put it in. You can also propose new
+ sections.
+
+ At this time I would like to limit the references to things that are
+ available on the web.
+
+ * Specifications
+
+ - LUKS on-disk format spec: See Item 1.2
+
+ * Other Documentation
+
+ - Arch Linux on LUKS, LVM and full-disk encryption:
+ https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system
+
+ * Code Examples
+
+ - Some code examples are in the source package under docs/examples
+
+ - LUKS AF Splitter in Ruby by John Lane: https://rubygems.org/gems/afsplitter
+
+ * Brute-forcing passphrases
+
+ - http://news.electricalchemy.net/2009/10/password-cracking-in-cloud-part-5.html
+
+ - http://it.slashdot.org/story/12/12/05/0623215/new-25-gpu-monster-devours-strong-passwords-in-minutes
+
+ * Tools
+
+ * SSD and Flash Disk Related
+
+ * Disk Encryption
+
+ * Attacks Against Disk Encryption
+
+ * Risk Management as Relevant for Disk Encryption
+
+ * Cryptography
+
+ * Secure Storage
+
+
+A. Contributors
+In no particular order: