Frequently Asked Questions Cryptsetup/LUKS

Sections

1. General Questions

2. Setup

3. Common Problems

4. Troubleshooting

5. Security Aspects

6. Backup and Data Recovery

7. Interoperability with other Disk Encryption Tools

8. Issues with Specific Versions of cryptsetup

9. The Initrd question

10. LUKS2 Questions

11. References and Further Reading

A. Contributors

1. General Questions

  * 1.1 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 metadata on disk) and LUKS (multiple user keys with one

  master key, anti-forensic features, metadata block at start of device,

  ...).  The latest version of this FAQ should usually be available at

  https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions

  * 1.2 WARNINGS

  LUKS2 COMPATIBILITY: This FAQ was originally written for LUKS1, not

  LUKS2.  Hence regarding LUKS2, some of the answers found here may not

  apply.  Updates for LUKS2 have been done and anything not applying to

  LUKS2 should clearly say LUKS1.  However, this is a Frequently Asked

  Questions, and questions for LUKS2 are limited at this time or at least

  those that have reached me are.  In the following, "LUKS" refers to both

  LUKS1 and LUKS2.

  The LUKS1 on-disk format specification is at  

  https://www.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf  

  The LUKS2 on-disk format specification is at  

  https://gitlab.com/cryptsetup/LUKS2-docs

  ATTENTION: If you are going to read just one thing, make it the section

  on Backup and Data Recovery.  By far the most questions on the

  cryptsetup mailing list are from people that managed to damage the start

  of their LUKS partitions, i.e.  the LUKS header.  In most cases, there

  is nothing that can be done to help these poor souls recover their data. 

  Make sure you understand the problem and limitations imposed by the LUKS

  security model BEFORE you face such a disaster!  In particular, make

  sure you have a current header backup before doing any potentially

  dangerous operations.  The LUKS2 header should be a bit more resilient

  as critical data starts later and is stored twice, but you can decidely

  still destroy it or a keyslot permanently by accident.

  DEBUG COMMANDS: While the --debug and --debug-json options should not

  leak secret data, "strace" and the like can leak your full passphrase. 

  Do not post an strace output with the correct passphrase to a

  mailing-list or online!  See Item 4.5 for more explanation.

  SSDs/FLASH DRIVES: SSDs and Flash are different.  Currently it is

  unclear how to get LUKS or plain dm-crypt to run on them with the full

  set of security assurances intact.  This may or may not be a problem,

  depending on the attacker model.  See Section 5.19.

  BACKUP: Yes, encrypted disks die, just as normal ones do.  A full backup

  is mandatory, see Section "6.  Backup and Data Recovery" on options for

  doing encrypted backup.

  CLONING/IMAGING: If you clone or image a LUKS container, you make a copy

  of the LUKS header and the master key will stay the same!  That means

  that if you distribute an image to several machines, the same master key

  will be used on all of them, regardless of whether you change the

  passphrases.  Do NOT do this!  If you do, a root-user on any of the

  machines with a mapped (decrypted) container or a passphrase on that

  machine can decrypt all other copies, breaking security.  See also Item

  6.15.

  DISTRIBUTION INSTALLERS: Some distribution installers offer to create

  LUKS containers in a way that can be mistaken as activation of an

  existing container.  Creating a new LUKS container on top of an existing

  one leads to permanent, complete and irreversible data loss.  It is

  strongly recommended to only use distribution installers after a

  complete backup of all LUKS containers has been made.

  UBUNTU INSTALLER: In particular the Ubuntu installer seems to be quite

  willing to kill LUKS containers in several different ways.  Those

  responsible at Ubuntu seem not to care very much (it is very easy to

  recognize a LUKS container), so treat the process of installing Ubuntu

  as a severe hazard to any LUKS container you may have.

  NO WARNING ON NON-INTERACTIVE FORMAT: If you feed cryptsetup from STDIN

  (e.g.  via GnuPG) on LUKS format, it does not give you the warning that

  you are about to format (and e.g.  will lose any pre-existing LUKS

  container on the target), as it assumes it is used from a script.  In

  this scenario, the responsibility for warning the user and possibly

  checking for an existing LUKS header is shifted to the script.  This is

  a more general form of the previous item.

  LUKS PASSPHRASE IS NOT THE MASTER KEY: The LUKS passphrase is not used

  in deriving the master key.  It is used in decrypting a master key that

  is randomly selected on header creation.  This means that if you create

  a new LUKS header on top of an old one with exactly the same parameters

  and exactly the same passphrase as the old one, it will still have a

  different master key and your data will be permanently lost.

  PASSPHRASE CHARACTER SET: Some people have had difficulties with this

  when upgrading distributions.  It is highly advisable to only use the 95

  printable characters from the first 128 characters of the ASCII table,

  as they will always have the same binary representation.  Other

  characters may have different encoding depending on system configuration

  and your passphrase will not work with a different encoding.  A table of

  the standardized first 128 ASCII characters can, e.g.  be found on

  http://en.wikipedia.org/wiki/ASCII

  KEYBOARD NUM-PAD: Apparently some pre-boot authentication environments

  (these are done by the distro, not by cryptsetup, so complain there)

  treat digits entered on the num-pad and ones entered regularly

  different.  This may be because the BIOS USB keyboard driver is used and

  that one may have bugs on some computers.  If you cannot open your

  device in pre-boot, try entering the digits over the regular digit keys.

  * 1.3 System specific warnings

  - The Ubuntu Natty uinstaller has a "won't fix" defect that may destroy

  LUKS containers.  This is quite old an not relevant for most people. 

  Reference:

  https://bugs.launchpad.net/ubuntu/+source/partman-crypto/+bug/420080

  * 1.4 My LUKS-device is broken! Help!

  First: Do not panic! In many cases the data is still recoverable.

  Do not do anything hasty! Steps:

  - Take some deep breaths. Maybe add some relaxing music.  This may

  sound funny, but I am completely serious.  Often, critical damage is

  done only after the initial problem.

  - Do not reboot. The keys may still be in the kernel if the device is

  mapped.

  - Make sure others do not reboot the system.

  - Do not write to your disk without a clear understanding why this will

  not make matters worse.  Do a sector-level backup before any writes. 

  Often you do not need to write at all to get enough access to make a

  backup of the data.

  - Relax some more.

  - Read section 6 of this FAQ.

  - Ask on the mailing-list if you need more help.

  * 1.5 Who wrote this?

  Current FAQ maintainer is Arno Wagner <arno@wagner.name>.  If you want

  to send me encrypted email, my current PGP key is DSA key CB5D9718,

  fingerprint 12D6 C03B 1B30 33BB 13CF B774 E35C 5FA1 CB5D 9718.

  Other contributors are listed at the end.  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.  You can also send more raw information and have

  me write the section.  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.

  * 1.6 Where is the project website?

  There is the project website at

  https://gitlab.com/cryptsetup/cryptsetup/ Please do not post

  questions there, nobody will read them.  Use the mailing-list

  instead.

  * 1.7 Is there a mailing-list?

  Instructions on how to subscribe to the mailing-list are at on the

  project website.  People are generally helpful and friendly on the

  list.

  The question of how to unsubscribe from the list does crop up sometimes. 

  For this you need your list management URL, which is sent to you

  initially and once at the start of each month.  Go to the URL mentioned

  in the email and select "unsubscribe".  This page also allows you to

  request a password reminder.

  Alternatively, you can send an Email to dm-crypt-request@saout.de with

  just the word "help" in the subject or message body.  Make sure to send

  it from your list address.

  The mailing list archive is here:

  https://marc.info/?l=dm-crypt

  * 1.8 Unsubscribe from the mailing-list

  Send mail to dm-crypt-unsubscribe@saout.de from the subscribed account. 

  You will get an email with instructions.

  Basically, you just have to respond to it unmodified to get

  unsubscribed.  The listserver admin functions are not very fast.  It can

  take 15 minutes or longer for a reply to arrive (I suspect greylisting

  is in use), so be patient.

  Also note that nobody on the list can unsubscribe you, sending demands

  to be unsubscribed to the list just annoys people that are entirely

  blameless for you being subscribed.

  If you are subscribed, a subscription confirmation email was sent to

  your email account and it had to be answered before the subscription

  went active.  The confirmation emails from the listserver have subjects

  like these (with other numbers):

    Subject: confirm 9964cf10.....

  and are sent from dm-crypt-request@saout.de.  You should check whether

  you have anything like it in your sent email folder.  If you find

  nothing and are sure you did not confirm, then you should look into a

  possible compromise of your email account.

2. Setup

  * 2.1 LUKS Container Setup mini-HOWTO

  This item tries to give you a very brief list of all the steps you

  should go though when creating a new LUKS encrypted container, i.e. 

  encrypted disk, partition or loop-file.

  01) All data will be lost, if there is data on the target, make a

  backup.

  02) Make very sure you use the right target disk, partition or

  loop-file.

  03) If the target was in use previously, it is a good idea to wipe it

  before creating the LUKS container in order to remove any trace of old

  file systems and data.  For example, some users have managed to run

  e2fsck on a partition containing a LUKS container, possibly because of

  residual ext2 superblocks from an earlier use.  This can do arbitrary

  damage up to complete and permanent loss of all data in the LUKS

  container.

  To just quickly wipe file systems (old data may remain), use

    wipefs -a <target device>

  To wipe file system and data, use something like

    cat /dev/zero > <target device>

  This can take a while.  To get a progress indicator, you can use the

  tool dd_rescue (->google) instead or use my stream meter "wcs" (source

  here: http://www.tansi.org/tools/index.html) in the following fashion:

    cat /dev/zero | wcs > <target device>

  Plain "dd" also gives you the progress on a SIGUSR1, see its man-page.

  Be very sure you have the right target, all data will be lost!

  Note that automatic wiping is on the TODO list for cryptsetup, so at

  some time in the future this will become unnecessary.

  Alternatively, plain dm-crypt can be used for a very fast wipe with

  crypto-grade randomness, see Item 2.19

  04) Create the LUKS container.  

  LUKS1:

    cryptsetup luksFormat --type luks1 <target device>

  LUKS2:

    cryptsetup luksFormat --type luks2 <target device>

  Just follow the on-screen instructions.

  Note: Passprase iteration count is based on time and hence security

  level depends on CPU power of the system the LUKS container is created

  on.  For example on a Raspberry Pi and LUKS1, I found some time ago that

  the iteration count is 15 times lower than for a regular PC (well, for

  my old one).  Depending on security requirements, this may need

  adjustment.  For LUKS1, you can just look at the iteration count on

  different systems and select one you like.  You can also change the

  benchmark time with the -i parameter to create a header for a slower

  system.

  For LUKS2, the parameters are more complex.  ARGON2 has iteration,

  parallelism and memory parameter.  cryptsetup actually may adjust the

  memory parameter for time scaling.  Hence to use -i is the easiest way

  to get slower or faster opening (default: 2000 = 2sec).  Just make sure

  to not drop this too low or you may get a memory parameter that is to

  small to be secure.  The luksDump command lists the memory parameter of

  a created LUKS2 keyslot in kB.  That parameter should probably be not

  much lower than 100000, i.e.  100MB, but don't take my word for it.

  05) Map the container. Here it will be mapped to /dev/mapper/c1:

    cryptsetup luksOpen <target device> c1

  06) (Optionally) wipe the container (make sure you have the right

      target!): 

    cat /dev/zero > /dev/mapper/c1

  This will take a while.  Note that this creates a small information

  leak, as an attacker can determine whether a 512 byte block is zero if

  the attacker has access to the encrypted container multiple times. 

  Typically a competent attacker that has access multiple times can

  install a passphrase sniffer anyways, so this leakage is not very

  significant.  For getting a progress indicator, see step 03.

  07) Create a file system in the mapped container, for example an

  ext3 file system (any other file system is possible):

    mke2fs -j /dev/mapper/c1

  08) Mount your encrypted file system, here on /mnt:

    mount /dev/mapper/c1 /mnt

  09) Make a LUKS header backup and plan for a container backup.

      See Section 6 for details.

  Done.  You can now use the encrypted file system to store data.  Be sure

  to read though the rest of the FAQ, these are just the very basics.  In

  particular, there are a number of mistakes that are easy to make, but

  will compromise your security.

  * 2.2 LUKS on partitions or raw disks? What about RAID?

  Also see Item 2.8.  

  This is a complicated question, and made more so by the availability of

  RAID and LVM.  I will try to give some scenarios and discuss advantages

  and disadvantages.  Note that I say LUKS for simplicity, but you can do

  all the things described with plain dm-crypt as well.  Also note that

  your specific scenario may be so special that most or even all things I

  say below do not apply.

  Be aware that if you add LVM into the mix, things can get very

  complicated.  Same with RAID but less so.  In particular, data recovery

  can get exceedingly difficult.  Only add LVM if you have a really good

  reason and always remember KISS is what separates an engineer from an

  amateur.  Of course, if you really need the added complexity, KISS is

  satisfied.  But be very sure as there is a price to pay for it.  In

  engineering, complexity is always the enemy and needs to be fought

  without mercy when encountered.

  Also consider using RAID instead of LVM, as at least with the old

  superblock format 0.90, the RAID superblock is in the place (end of

  disk) where the risk of it damaging the LUKS header is smallest and you

  can have your array assembled by the RAID controller (i.e.  the kernel),

  as it should be.  Use partition type 0xfd for that.  I recommend staying

  away from superblock formats 1.0, 1.1 and 1.2 unless you really need

  them.

  Scenarios:

  (1) Encrypted partition: Just make a partition to your liking, and put

  LUKS on top of it and a filesystem into the LUKS container.  This gives

  you isolation of differently-tasked data areas, just as ordinary

  partitioning does.  You can have confidential data, non-confidential

  data, data for some specific applications, user-homes, root, etc. 

  Advantages are simplicity as there is a 1:1 mapping between partitions

  and filesystems, clear security functionality and the ability to

  separate data into different, independent (!) containers.

  Note that you cannot do this for encrypted root, that requires an

  initrd.  On the other hand, an initrd is about as vulnerable to a

  competent attacker as a non-encrypted root, so there really is no

  security advantage to doing it that way.  An attacker that wants to

  compromise your system will just compromise the initrd or the kernel

  itself.  The better way to deal with this is to make sure the root

  partition does not store any critical data and to move that to

  additional encrypted partitions.  If you really are concerned your root

  partition may be sabotaged by somebody with physical access (who would

  however strangely not, say, sabotage your BIOS, keyboard, etc.), protect

  it in some other way.  The PC is just not set-up for a really secure

  boot-chain (whatever some people may claim).

  (2) Fully encrypted raw block device: For this, put LUKS on the raw

  device (e.g.  /dev/sdb) and put a filesystem into the LUKS container, no

  partitioning whatsoever involved.  This is very suitable for things like

  external USB disks used for backups or offline data-storage.

  (3) Encrypted RAID: Create your RAID from partitions and/or full

  devices.  Put LUKS on top of the RAID device, just if it were an

  ordinary block device.  Applications are just the same as above, but you

  get redundancy.  (Side note as many people seem to be unaware of it: You

  can do RAID1 with an arbitrary number of components in Linux.) See also

  Item 2.8.

  (4) Now, some people advocate doing the encryption below the RAID layer. 

  That has several serious problems.  One is that suddenly debugging RAID

  issues becomes much harder.  You cannot do automatic RAID assembly

  anymore.  You need to keep the encryption keys for the different RAID

  components in sync or manage them somehow.  The only possible advantage

  is that things may run a little faster as more CPUs do the encryption,

  but if speed is a priority over security and simplicity, you are doing

  this wrong anyways.  A good way to mitigate a speed issue is to get a

  CPU that does hardware AES as most do today.

  * 2.3 How do I set up encrypted swap?

  As things that are confidential can end up in swap (keys, passphrases,

  etc.  are usually protected against being swapped to disk, but other

  things may not be), it may be advisable to do something about the issue. 

  One option is to run without swap, which generally works well in a

  desktop-context.  It may cause problems in a server-setting or under

  special circumstances.  The solution to that is to encrypt swap with a

  random key at boot-time.

  NOTE: This is for Debian, and should work for Debian-derived

  distributions.  For others you may have to write your own startup script

  or use other mechanisms.

  01) Add the swap partition to /etc/crypttab. A line like the

  following should do it:

    swap  /dev/<partition>  /dev/urandom   swap,noearly

  Warning: While Debian refuses to overwrite partitions with a filesystem

  or RAID signature on it, as your disk IDs may change (adding or removing

  disks, failure of disk during boot, etc.), you may want to take

  additional precautions.  Yes, this means that your kernel device names

  like sda, sdb, ...  can change between reboots!  This is not a concern

  if you have only one disk.  One possibility is to make sure the

  partition number is not present on additional disks or also swap there. 

  Another is to encapsulate the swap partition (by making it a 1-partition

  RAID1 or by using LVM), as that gets a persistent identifier. 

  Specifying it directly by UUID does not work, unfortunately, as the UUID

  is part of the swap signature and that is not visible from the outside

  due to the encryption and in addition changes on each reboot with this

  setup.

  Note: Use /dev/random if you are paranoid or in a potential low-entropy

  situation (embedded system, etc.).  This may cause the operation to take

  a long time during boot however.  If you are in a "no entropy"

  situation, you cannot encrypt swap securely.  In this situation you

  should find some entropy, also because nothing else using crypto will be

  secure, like ssh, ssl or GnuPG.

  Note: The "noearly" option makes sure things like LVM, RAID, etc.  are

  running.  As swap is non-critical for boot, it is fine to start it late.

  02) Add the swap partition to /etc/fstab. A line like the following

  should do it:

    /dev/mapper/swap none swap sw 0 0

  That is it. Reboot or start it manually to activate encrypted swap. 

  Manual start would look like this:

    /etc/init.d/crypdisks start

    swapon /dev/mapper/swap

  * 2.4 What is the difference between "plain" and LUKS format?

  First, unless you happen to understand the cryptographic background

  well, you should use LUKS.  It does protect the user from a lot of

  common mistakes.  Plain dm-crypt is for experts.

  Plain format is just that: It has no metadata on disk, reads all

  parameters from the commandline (or the defaults), derives a master-key

  from the passphrase and then uses that to de-/encrypt the sectors of the

  device, with a direct 1:1 mapping between encrypted and decrypted

  sectors.

  Primary advantage is high resilience to damage, as one damaged encrypted

  sector results in exactly one damaged decrypted sector.  Also, it is not

  readily apparent that there even is encrypted data on the device, as an

  overwrite with crypto-grade randomness (e.g.  from

  /dev/urandom) looks exactly the same on disk.

  Side-note: That has limited value against the authorities.  In civilized

  countries, they cannot force you to give up a crypto-key anyways.  In

  quite a few countries around the world, they can force you to give up

  the keys (using imprisonment or worse to pressure you, sometimes without

  due process), and in the worst case, they only need a nebulous

  "suspicion" about the presence of encrypted data.  Sometimes this

  applies to everybody, sometimes only when you are suspected of having

  "illicit data" (definition subject to change) and sometimes specifically

  when crossing a border.  Note that this is going on in countries like

  the US and the UK to different degrees and sometimes with courts

  restricting what the authorities can actually demand.

  My advice is to either be ready to give up the keys or to not have

  encrypted data when traveling to those countries, especially when

  crossing the borders.  The latter also means not having any high-entropy

  (random) data areas on your disk, unless you can explain them and

  demonstrate that explanation.  Hence doing a zero-wipe of all free

  space, including unused space, may be a good idea.

  Disadvantages are that you do not have all the nice features that the

  LUKS metadata offers, like multiple passphrases that can be changed, the

  cipher being stored in the metadata, anti-forensic properties like

  key-slot diffusion and salts, etc..

  LUKS format uses a metadata header and 8 key-slot areas that are being

  placed at the beginning of the disk, see below under "What does the LUKS

  on-disk format looks like?".  The passphrases are used to decrypt a

  single master key that is stored in the anti-forensic stripes.  LUKS2

  adds some more flexibility.

  Advantages are a higher usability, automatic configuration of

  non-default crypto parameters, defenses against low-entropy passphrases

  like salting and iterated PBKDF2 or ARGON 2 passphrase hashing, the

  ability to change passphrases, and others.

  Disadvantages are that it is readily obvious there is encrypted data on

  disk (but see side note above) and that damage to the header or

  key-slots usually results in permanent data-loss.  See below under "6. 

  Backup and Data Recovery" on how to reduce that risk.  Also the sector

  numbers get shifted by the length of the header and key-slots and there

  is a loss of that size in capacity.  Unless you have a specific need,

  use LUKS2.

  * 2.5 Can I encrypt an 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.

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

  This can be very handy for experiments.  Setup is just the same as with

  any block device.  If you want, for example, to use a 100MiB file as

  LUKS container, do something like this:

    head -c 100M /dev/zero > luksfile               # create empty file

    losetup /dev/loop0 luksfile                     # map file to /dev/loop0

    cryptsetup luksFormat --type luks2 /dev/loop0   # create LUKS2 container

  Afterwards just use /dev/loop0 as a you would use a LUKS partition.

  To unmap the file when done, use "losetup -d /dev/loop0".

  * 2.7 When I add a new key-slot to LUKS, it asks for a passphrase

    but then complains about there not being a key-slot with that

    passphrase?

  That is as intended.  You are asked a passphrase of an existing key-slot

  first, before you can enter the passphrase for the new key-slot. 

  Otherwise you could break the encryption by just adding a new key-slot. 

  This way, you have to know the passphrase of one of the already

  configured key-slots in order to be able to configure a new key-slot.

  * 2.8 Encryption on top of RAID or the other way round?

  Also see Item 2.2.  

  Unless you have special needs, place encryption between RAID and

  filesystem, i.e.  encryption on top of RAID.  You can do it the other

  way round, but you have to be aware that you then need to give the

  passphrase for each individual disk and RAID auto-detection will not

  work anymore.  Therefore it is better to encrypt the RAID device, e.g. 

  /dev/dm0 .

  This means that the typical layering looks like this:

  Filesystem     <- top

  |

  Encryption (LUKS)

  |

  RAID

  |

  Raw partitions (optional)

  |

  Raw disks      <- bottom

  The big advantage of this is that you can manage the RAID container just

  like any other regular RAID container, it does not care that its content

  is encrypted.  This strongly cuts down on complexity, something very

  valuable with storage encryption.

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

  Use the --key-file option, like this:

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

  This will read the binary key from file, i.e.  no hashing or

  transformation will be applied to the keyfile before its bits are used

  as key.  Extra bits (beyond the length of the key) at the end are

  ignored.  Note that if you read from STDIN, the data will be hashed,

  just as a key read interactively from the terminal.  See the man-page

  sections "NOTES ON PASSPHRASE PROCESSING..." for more detail.

  * 2.10 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.  Make sure

  no trailing newline (0x0a) is contained in the input 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

  * 2.11 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.

  * 2.12 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

  * 2.13 If I map a journaled file system using dm-crypt/LUKS, does

    it still provide its usual transactional guarantees?

  Yes, it does, unless a very old kernel is used.  The required flags come

  from the filesystem layer and are processed and passed onward by

  dm-crypt (regardless of direct key management or LUKS key management). 

  A bit more information on the process by which transactional guarantees

  are implemented can be found here:

  http://lwn.net/Articles/400541/

  Please note that these "guarantees" are weaker than they appear to be. 

  One problem is that quite a few disks lie to the OS about having flushed

  their buffers.  This is likely still true with SSDs.  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 will not make things worse.

  One specific problem you can run into is that you can get short freezes

  and other slowdowns due to the encryption layer.  Encryption takes time

  and forced flushes will block for that time.  For example, I did run

  into frequent small freezes (1-2 sec) when putting a vmware image on

  ext3 over dm-crypt.  When I went back to ext2, the problem went away. 

  This seems to have gotten better with kernel 2.6.36 and the reworking of

  filesystem flush locking mechanism (less blocking of CPU activity during

  flushes).  This should improve further and eventually the problem should

  go away.

  * 2.14 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.

  For TPM support, you may want to have a look at tpm-luks at

  https://github.com/shpedoikal/tpm-luks.  Note that tpm-luks is not

  related to the cryptsetup project.

  * 2.15 Can I resize a dm-crypt or LUKS container?

  Yes, you can, as neither dm-crypt nor LUKS1 stores partition size and

  LUKS2 uses a generic "whole device" size as default.  Note that LUKS2

  can use specified data-area sizes as a non-standard case and that these

  may cause issues when resizing a LUKS2 container if set to a specific

  value.

  Whether you should do this is a different question.  Personally I

  recommend backup, recreation of the dm-crypt or LUKS container with new

  size, recreation of the filesystem and restore.  This gets around the

  tricky business of resizing the filesystem.  Resizing a dm-crypt or LUKS

  container does not resize the filesystem in it.  A backup is really

  non-optional here, as a lot can go wrong, resulting in partial or

  complete data loss.  But if you have that backup, you can also just

  recreate everything.

  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 2TiB.  Use aes-xts-plain64 for that.

  * 2.16 How do I Benchmark the Ciphers, Hashes and Modes?

  Since version 1.60 cryptsetup supports the "benchmark" command. 

  Simply run as root:

    cryptsetup benchmark

  You can get more than the default benchmarks, see the man-page for the

  relevant parameters.  Note that XTS mode takes two keys, hence the

  listed key sizes are double that for other modes and half of it is the

  cipher key, the other half is the XTS key.

  * 2.17 How do I Verify I have an Authentic cryptsetup Source Package?

  Current maintainer is Milan Broz and he signs the release packages with

  his PGP key.  The key he currently uses is the "RSA key ID D93E98FC",

  fingerprint 2A29 1824 3FDE 4664 8D06 86F9 D9B0 577B D93E 98FC.  While I

  have every confidence this really is his key and that he is who he

  claims to be, don't depend on it if your life is at stake.  For that

  matter, if your life is at stake, don't depend on me being who I claim

  to be either.

  That said, as cryptsetup is under good version control and a malicious

  change should be noticed sooner or later, but it may take a while. 

  Also, the attacker model makes compromising the sources in a non-obvious

  way pretty hard.  Sure, you could put the master-key somewhere on disk,

  but that is rather obvious as soon as somebody looks as there would be

  data in an empty LUKS container in a place it should not be.  Doing this

  in a more nefarious way, for example hiding the master-key in the salts,

  would need a look at the sources to be discovered, but I think that

  somebody would find that sooner or later as well.

  That said, this discussion is really a lot more complicated and longer

  as an FAQ can sustain.  If in doubt, ask on the mailing list.

  * 2.18 Is there a concern with 4k Sectors?

  Not from dm-crypt itself.  Encryption will be done in 512B blocks, but

  if the partition and filesystem are aligned correctly and the filesystem

  uses multiples of 4kiB as block size, the dm-crypt layer will just

  process 8 x 512B = 4096B at a time with negligible overhead.  LUKS does

  place data at an offset, which is 2MiB per default and will not break

  alignment.  See also Item 6.12 of this FAQ for more details.  Note that

  if your partition or filesystem is misaligned, dm-crypt can make the

  effect worse though.  Also note that SSDs typically have much larger

  blocks internally (e.g.  128kB or even larger).

  * 2.19 How can I wipe a device with crypto-grade randomness?

  The conventional recommendation if you want to do more than just a

  zero-wipe is to use something like

    cat /dev/urandom >  <taget-device>

  That used to very slow and painful at 10-20MB/s on a fast computer, but

  newer kernels can give you > 200MB/s (depending on hardware).  An

  alternative is using cryptsetup and a plain dm-crypt device with a

  random key, which is fast and on the same level of security.  The

  defaults are quite enough.

  For device set-up, do the following:

    cryptsetup open --type plain -d /dev/urandom /dev/<device> target

  This maps the container as plain under /dev/mapper/target with a random

  password.  For the actual wipe you have several options.  Basically, you

  pipe zeroes into the opened container that then get encrypted.  Simple

  wipe without progress-indicator:

    cat /dev/zero > /dev/mapper/to_be_wiped

  Progress-indicator by dd_rescue:

    dd_rescue -w /dev/zero /dev/mapper/to_be_wiped

  Progress-indicator by my "wcs" stream meter (available from

  http://www.tansi.org/tools/index.html ):

    cat /dev/zero | wcs > /dev/mapper/to_be_wiped

  Or use plain "dd", which gives you the progress when sent a SIGUSR1, see

  the dd man page.

  Remove the mapping at the end and you are done.

  * 2.20 How to I wipe only the LUKS header?

  This does _not_ describe an emergency wipe procedure, see Item 5.4 for

  that.  This procedure here is intended to be used when the data should

  stay intact, e.g.  when you change your LUKS container to use a detached

  header and want to remove the old one.  Please only do this if you have

  a current backup.

  LUKS1:  

  01) Determine header size in 512 Byte sectors with luksDump:

     cryptsetup luksDump <device with LUKS container>

->   ...

     Payload offset: <number>

     ...

  02) Take the result number, multiply by 512 zeros and write to 

      the start of the device, e.g. like this:

     dd bs=512 count=<number> if=/dev/zero of=<device>

  LUKS2:  (warning, untested!  Remember that backup?) This assumes the

  LUKS2 container uses the defaults, in particular there is only one data

  segment.  01) Determine the data-segment offset using luksDump, same

      as above for LUKS1:

->   ...  

     Data segments:

        0: crypt

           offset: <number> [bytes]

     ...

  02) Overwrite the stated number of bytes from the start of the device.

      Just to give yet another way to get a defined number of zeros:

    head -c /dev/zero > /dev/<device>

3. Common Problems

  * 3.1 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.