cryptsetup/FAQ

Sections 

1. General Questions
2. Setup
3. Common Problems
4. Security Aspects
5. Backup and Data Recovery
6. Issues with Specific Versions of cryptsetup
A. Contributors


1. General Questions 


  * What is this?

  This is the FAQ (Frequently Asked Questions) for cryptsetup. It
  covers Linux disk encryption with plain dm-crypt (one passphrase,
  no management, no descriptor on disk) and LUKS (multiple user keys
  with one master key, anti-forensics, descriptor block at start of
  device, ...). The latest version should usually be available at
  http://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions


  * Who wrote this?

  Current FAQ maintainer is Arno Wagner <arno@wagner.name>. Wherever
  contributions are from other people, their name should be included
  in brackets with the respective article. If you want to contribute,
  send your article, including a descriptive headline, to the
  maintainer, or the dm-crypt mailing list with something like "FAQ
  ..." in the subject. Please note that by contributing to this FAQ,
  you accept the license described below.

  This work is under the "Attribution-Share Alike 3.0 Unported"
  license, which means distribution is unlimited, you may create
  derived works, but attributions to original authors and this
  license statement must be retained and the derived work must be
  under the same license. See
  http://creativecommons.org/licenses/by-sa/3.0/ for more details of
  the license.

  Side note: I did text license research some time ago and I think
  this license is best suited for the purpose at hand and creates the
  least problems.


2. Setup 


  * Can I encrypt an already existing, non-empty partition to use
  LUKS?

  There is no converter, and it is not really needed. The way to do
  this is to make a backup of the device in question, securely wipe
  the device (as LUKS device initialization does not clear away old
  data), do a luksFormat, optionally overwrite the encrypted device,
  create a new filesystem and restore your backup on the now
  encrypted device. Also refer to sections "Security Aspects" and
  "Backup and Data Recovery".

  For backup, plain GNU tar works well and backs up anything likely
  to be in a filesystem.


  * How do I use LUKS with a loop-device?

  Just the same as with any block device. If you want, for example,
  to use a 100MB file as LUKS container, do something like this:

      head -c 100M /dev/zero > luksfile   # create empty file
      losetup /dev/loop0 luksfile         # map luksfile to /dev/loop0
      cryptsetup luksFormat /dev/loop0    # create LUKS on the loop device
 
  Afterwards just use /dev/loop0 as a you would use a LUKS partition.
  To unmap the file when done, use "losetup -d /dev/loop0".


  * How do I read a dm-crypt key from file?

  Note that the file will still be hashed first, just like keyboard
  input. Use the --key-file option, like this:

      cryptsetup create --key-file keyfile e1 /dev/loop0
 

  * How do I read a LUKS slot key from file?

  What you really do here is to read a passphrase from file, just as
  you would with manual entry of a passphrase for a key-slot. You can
  add a new passphrase to a free key-slot, set the passphrase of an
  specific key-slot or put an already configured passphrase into a
  file. In the last case make sure no trailing newline (0x0a) is
  contained in the key file, or the passphrase will not work because
  the whole file is used as input.

  To add a new passphrase to a free key slot from file, use something
  like this:

      cryptsetup luksAddKey /dev/loop0 keyfile
 
  To add a new passphrase to a specific key-slot, use something like
  this:

      cryptsetup luksAddKey --key-slot 7 /dev/loop0 keyfile
 
  To supply a key from file to any LUKS command, use the --key-file
  option, e.g. like this:

      cryptsetup luksOpen --key-file keyfile /dev/loop0 e1
 

  * How do I read the LUKS master key from file?

  The question you should ask yourself first, is why you would want
  to do this. The only legitimate reason I can think of is if you
  want to have two LUKS devices with the same master key. Even then,
  I think it would be preferable to just use key-slots with the same
  passphrase, or to use plain dm-crypt instead. If you really have a
  good reason, please tell me. If I am convinced, I will add how to
  do this here.


  * What are the security requirements for a key read from file?

  A file-stored key or passphrase has the same security requirements
  as one entered interactively, however you can use random bytes and
  thereby use bytes you cannot type on the keyboard. You can use any
  file you like as key file, for example a plain text file with a
  human readable passphrase. To generate a file with random bytes,
  use something like this:

      head -c 256 /dev/random > keyfile
 

  * If I map a journaled file system using dm-crypt/LUKS, does it
  still provide its usual transactional guarantees?

  As far as I know you do (but I may be wrong), but please note that
  these "guarantees" are far weaker than they appear to be. For
  example, you not not get a hard flush to disk surface even on a
  call to fsync. In addition, the HDD itself may do independent
  write reordering. Some other things can go wrong as well. The
  filesystem developers are aware of these problems and typically
  can make it work anyways. That said, dm-crypt/LUKS should not make
  things worse.

  Personally, I have several instances of ext3 on dm-crypt and have
  not noticed any specific issues so far.


  * Can I use LUKS or cryptsetup with a more secure (external) medium
  for key storage, e.g. TPM or a smartcard?

  Yes, see the answers on using a file-supplied key. You do have to
  write the glue-logic yourself though. Basically you can have
  cryptsetup read the key from STDIN and write it there with your
  own tool that in turn gets the key from the more secure key
  storage.


  * Can I resize a dm-crypt or LUKS partition?

  Yes, you can, as neither dm-crypt nor LUKS stores partition size.
  Whether you should is a different question. Personally I recommend
  backup, recreation of the encrypted partition with new size,
  recreation of the filesystem and restore. This gets around the
  tricky business of resizing the filesystem. The backup is really
  non-optional here, as a lot can go wrong, resulting in partial or
  complete data loss. Using something like gparted to resize an
  encrypted partition is slow, but pretty safe and should be fine.
  This will not change the size of the filesystem hidden under the
  encryption though.

  You also need to be aware of size-based limitations. The one
  currently relevant is that aes-xts-plain should not be used for
  encrypted container sizes larger than 2TB.


3. Common Problems 


  * My dm-crypt/LUKS mapping does not work! What general steps are
  there to investigate the problem?

  If you get a specific error message, investigate what it claims
  first. If not, you may want to check the following things.

  - Check that "/dev", including "/dev/mapper/control" is there. If it is 
  missing, you may have a problem with the "/dev" tree itself or you
  may have broken udev rules.

  - Check that you have the device mapper and the crypt target in your kernel.
  The output of "dmsetup targets" should list a "crypt" target. If it
  is not there or the command fails, add device mapper and
  crypt-target to the kernel.

  - Check that the hash-functions and ciphers you want to use are in the kernel.
  The output of "cat /proc/crypto" needs to list them.


  * My dm-crypt mapping suddenly stopped when upgrading cryptsetup.

  The default cipher, hash or mode may have changed (the mode changed
  from 1.0.x to 1.1.x). See under "6. Issues With Specific Versions of
  cryptsetup".


  * When I call cryptsetup from cron/CGI, I get errors about unknown
  features?

  If you get errors about unknown parameters or the like that are not
  present when cryptsetup is called from the shell, make sure you
  have no older version of cryptsetup on your system that then gets
  called by cron/CGI.For example some distributions install
  cryptsetup into /usr/sbin, while a manual install could go to
  /usr/local/sbin. As a debugging aid, call "cryptsetup --version"
  from cron/CGI or the non-shell mechanism to be sure you have the
  right version.


  * Unlocking a LUKS device takes very long. Why?

  The iteration time for every key-slot (iteration is needed to
  prevent dictionary attacks) is calculated during the luksFormat
  operation. By default it is 1 second on the machine where the
  format operation is done. If you format a device on a fast machine
  and then unlock it on a slow machine, the unlocking time can be
  much more longer. Also take into account that up to 8 key-slots
  have to be tried in order to find the right one.

  If this is problem, you can add another key-slot using the slow
  machine with the same passphrase and then remove the old key-slot.
  The new key-slot will have an iteration count adjusted to 1 second
  on the slow machine. Use luksKeyAdd and then luksKillSlot or
  luksRemoveKey. However, this operation will not change volume key
  iteration count. In order to change that, you will have to backup
  the data in the LUKS container, luksFormat on the slow machine and
  restore the data.


  * "blkid" sees a LUKS UUID and an ext2/swap UUID on the same device.
  What is wrong?

  Some old versions of cryptsetup have a bug where the header does
  not get completely wiped during LUKS format and an older ext2/swap
  signature remains on the device. This confuses blkid.

  Fix: Wipe the unused header areas by doing a backup and restore of
  the header with cryptsetup 1.1.x:

      cryptsetup luksHeaderBackup --header-backup-file <file> <device>
      cryptsetup luksHeaderRestore --header-backup-file <file> <device>
 
  If you cannot use a 1.1.x cryptsetup, you can also do a manual wipe
  of the area in question with the command below. Be very, VERY,
  careful and make sure to do a backup of the header before. If you
  get this wrong, your device may become permanently inaccessible.

      dd if=/dev/zero of=<device> bs=512 seek=2 count=6
   

  * cryptsetup segfaults on Gentoo amd64 hardened ...

  There seems to be some inteference between the hardening and and
  the way cryptsetup benchmarks PBKDF2. The solution to this is
  currently not quite clear for an encrypted root filesystem.     For
  other uses, you can apparently specify USE="dynamic" as compile
  flag, see http://bugs.gentoo.org/show_bug.cgi?id=283470


4. Security Aspects 


  * Should I initialize (overwrite) a new LUKS/dm-crypt partition?

  If you just create a filesystem on it, most of the old data will
  still be there. If the old data is sensitive, you should overwrite
  it before encrypting. In any case, not initializing will leave the
  old data there until the specific sector gets written. That may
  enable an attacker to determine how much and where on the
  partition data was written. If you think this is a risk, you can
  prevent this by overwriting the encrypted device (here assumed to
  be named "e1") with zeros like this:

      dd_rescue -w /dev/zero /dev/mapper/e1
 
 or alternatively with one of the following more standard commands:

      cat /dev/zero > /dev/mapper/e1
      dd if=/dev/zero of=/dev/mapper/e1
       

  * How do I securely erase a LUKS (or other) partition?

  For LUKS, if you are in a desperate hurry, overwrite the first few
  kilobytes of the LUKS partition. This erases the salts and makes
  access impossible. However a LUKS header backup or full backup will
  still grant access to most or all data.

  To do this right, overwrite the whole LUKS partition with a single
  pass of zeros. This is enough for current HDDs. For SDDs you may
  want to erase the whole drive several times to be sure data is not
  retained by wear leveling. This is possibly insecure as SDD
  technology is not fully understood in this regard. Still, due to
  the anti-forensic properties of the LUKS key-slots, a single
  overwrite of an SSD could be enough. If in doubt, use physical
  destruction in addition. Keep in mind to also erase all backups.

  Example for a zero-overwrite erase of partition sda10 done with
  dd_rescue:

      dd_rescue -w /dev/zero /dev/sda10   
 

  * How do I securely erase a backup of a LUKS partition or header?

  That depends on the medium it is stored on. For HDD and SSD, use
  overwrite with zeros. For an SSD, you may want to overwrite the
  complete SSD several times and use physical destruction in addition,
  see last item. Treat USB flash drives the same as SSDs. For
  re-writable CD/DVD, a single overwrite should also be enough, due
  to the anti-forensic properties of the LUKS keyslots. For
  write-once media, use physical destruction. For low security
  requirements, just cut the CD/DVD into several parts. For high
  security needs, shred or burn the medium. If your backup is on
  magnetic tape, I advise physical destruction by shredding or
  burning. The problem with magnetic tape is that it has a higher
  dynamic range than HDDs and older data may well be recoverable
  after overwrites. Also write-head alignment issues can lead to
  data not actually being deleted at all during overwrites.


  * Why was the default aes-cbc-plain replaced with aes-cbc-essiv?

  The problem is that cbc-plain has a fingerprint vulnerability, where
  a specially crafted file placed into the crypto-container can be
  recognized from the outside. The issue here is that for cbc-plain
  the initialization vector (IV) is the sector number. The IV gets
  XORed to the first data chunk of the sector to be encrypted. If you
  make sure that the first data block to be stored in a sector
  contains the sector number as well, the first data block to be
  encrypted is all zeros and always encrypted to the same ciphertext.
  This also works if the first data chunk just has a constant XOR
  with the sector number. By having several shifted patterns you can
  take care of the case of a non-power-of-two start sector number of
  the file.

  This mechanism allows you to create a pattern of sectors that have
  the same first ciphertext block and signal one bit per sector to the
  outside, allowing you to e.g. mark media files that way for
  recognition without decryption. For large files this is a
  practical attack. For small ones, you do not have enough blocks to
  signal and take care of different file starting offsets.

  In order to prevent this attack, the default was changed to
  cbc-essiv. ESSIV uses a keyed hash of the sector number, with the
  encryption key as key. This makes the IV unpredictable without
  knowing the encryption key and the watermarking attack fails.


  * Are there any problems with "plain" IV? What is "plain64"?

  First, "plain" and "plain64" are both not safe to use with CBC, see
  previous FAQ item.

  However there are modes, like XTS, that are secure with "plain" IV.
  The next limit is that "plain" is 64 bit, with the upper 32 bit set
  to zero. This means that on volumes larger than 2TB, the IV
  repeats, creating a vulnerability that potentially leaks some
  data. To avoid this, use "plain64", which uses the full sector
  number up to 64 bit. Note that "plain64" requires a kernel >=
  2.6.33. Also note that "plain64" is backwards compatible for
  volume sizes <= 2TB, but not for those > 2TB. Finally, "plain64"
  does not cause any performance penalty compared to "plain".


  * What about XTS mode?

  XTS mode is potentially even more secure than cbc-essiv (but only if
  cbc-essiv is insecure in your scenario). It is a NIST standard and
  used, e.g. in Truecrypt. At the moment, if you want to use it, you
  have to specify it manually as "aes-xts-plain", i.e.

      cryptsetup -c aes-xts-plain luksFormat <device>
 
  For volumes >2TB and kernels >= 2.6.33 use "plain64" (see FAQ item
  on "plain" and "plain64"):

      cryptsetup -c aes-xts-plain64 luksFormat <device>
 

5. Backup and Data Recovery 


  * *What happens if I overwrite the start of a LUKS partition or

    damage the LUKS header or key-slots?*

  There are two critical components for decryption: The salt values
  in the header itself and the key-slots. If the salt values are
  overwritten or changed, nothing (in the cryptographically strong
  sense) can be done to access the data, unless there is a backup of
  the LUKS header. If a key-slot is damaged, the data can still be
  read with a different keys-lot, if one is in use.


  * What does the on-disk structure of dm-crypt look like?

  There is none. dm-crypt takes a block device and gives encrypted
  access to each of its blocks with a key derived from the passphrase
  given. If you use a cipher different than the default, you have to
  specify that as a parameter to cryptsetup too. If you want to
  change the password, you basically have to create a second
  encrypted device with the new passphrase and copy your data over.
  On the plus side, if you accidentally overwrite any part of a
  dm-crypt device, the damage will be limited to the are you
  overwrote.


  * What does the on-disk structure of LUKS look like?

  A LUKS partition consists of a header, followed by 8 key-slot
  descriptors, followed by 8 key slots, followed by the encrypted
  data area.

  Header and key-slot descriptors fill the first 592 bytes. The
  key-slot size depends on the creation parameters, namely on the
  number of anti-forensic stripes and on key block alignment.

  With 4000 stripes (the default), each key-slot is a bit less than
  128kB in size. Due to sector alignment of the key-slot start, that
  means the key block 0 is at offset 0x1000-0x20400, key block 1 at
  offset 0x21000-0x40400, and key block 7 at offset 0xc1000-0xe0400.
  The space to the next full sector address is padded with zeros.
  Never used key-slots are filled with what the disk originally
  contained there, a key-slot removed with "luksRemoveKey" or
  "luksKillSlot" gets filled with 0xff. Start of bulk data (with the
  default 4000 stripes and 8 key-slots) is at 0x101000, i.e. at
  1'052'672 bytes, i.e. at 1MiB + 4096 bytes from the start of the
  partition. This is also the value given by command "luksDump" with
  "Payload offset: 2056", just multiply by the sector size (512
  bytes). Incidentally, "luksHeaderBackup" dumps exactly the first
  1'052'672 bytes to file and "luksHeaderRestore" restores them.

  The exact specification of the format is here:
  http://code.google.com/p/cryptsetup/wiki/Specification


  * How do I backup a LUKS header?

  While you could just copy the appropriate number of bytes from the
  start of the LUKS partition, the best way is to use command option
  "luksHeaderBackup" of cryptsetup. This protects also against errors
  when non-standard parameters have been used in LUKS partition
  creation. Example:

 
      cryptsetup luksHeaderBackup --header-backup-file h_bak /dev/mapper/c1
 

  * How do I backup a LUKS partition?

  You do a sector-image of the whole partition. This will contain the
  LUKS header, the keys-slots and the data ares. It can be done
  under Linux e.g. with dd_rescue (for a direct image copy) and with
  "cat" or "dd". Example:

      cat /dev/sda10 > sda10.img
      dd_rescue /dev/sda10 sda10.img 
 
  You can also use any other backup software that is capable of making
  a sector image of a partition. Note that compression is
  ineffective for encrypted data, hence it does not sense to use it.


  * Do I need a backup of the full partition? Would the header and
  key-slots not be enough?

  Backup protects you against two things: Disk loss or corruption and
  user error. By far the most questions on the dm-crypt mailing list
  about how to recover a damaged LUKS partition are related to user
  error. For example, if you create a new filesystem on a LUKS
  partition, chances are good that all data is lost permanently.

  For this case, a header+key-slot backup would often be enough. But
  keep in mind that a HDD has roughly a failure risk of 5% per year.
  It is highly advisable to have a complete backup to protect against
  this case.


  * Are there security risks from a backup of the LUKS header or a
  whole LUKS partition?

  Yes. One risk is that if you remove access rights for specific
  key-slots by deleting their contents, the data can still be
  accessed with invalidated passphrase and the backup. The other risk
  is that if you erase a LUKS partition, a backup could still grant
  access, especially if you only erased the LUKS header and not the
  whole partition.


  * I think this is overly complicated. Is there an alternative?

  Yes, you can use plain dm-crypt. It does not allow multiple
  passphrases, but on the plus side, it has zero on disk description
  and if you overwrite some part of a plain dm-crypt partition,
  exactly the overwritten parts are lost (rounded up to sector
  borders).


6. Issues with Specific Versions of cryptsetup 


  * When using the create command for plain dm-crypt with cryptsetup
  1.1.x, the mapping is incompatible and my data is not accessible
  anymore!

  With cryptsetup 1.1.x, the distro maintainer can define different
  default encryption modes for LUKS and plain devices. You can check
  these compiled-in defaults using "cryptsetup --help". Moreover, the
  plain device default changed because the old IV mode was
  vulnerable to a watermarking attack.

  If you are using a plain device and you need a compatible mode, just
  specify cipher, key size and hash algorithm explicitly. For
  compatibility with cryptsetup 1.0.x defaults, simple use the
  following:

      cryptsetup create -c aes-cbc-plain -s 256 -h ripemd160 <name> <device>
 
   LUKS stores cipher and mode in the metadata on disk, avoiding this
  problem.


  * cryptsetup on SLED 10 has problems...

  SLED 10 is missing an essential kernel patch for dm-crypt, which
  is broken in its kernel as a result. There may be a very old
  version of cryptsetup (1.0.x) provided by SLED, which should also
  not be used anymore as well. My advice would be to drop SLED 10.

 A. Contributors In no particular order:

  - Arno Wagner
  - Milan Broz