FAQ 118 KB
Newer Older
1
Frequently Asked Questions.
Arno Wagner's avatar
Arno Wagner committed
2

3
Sections
Arno Wagner's avatar
Arno Wagner committed
4 5 6 7 8 9
1. General Questions
2. Setup
3. Common Problems
4. Troubleshooting
5. Security Aspects
6. Backup and Data Recovery
Arno Wagner's avatar
Arno Wagner committed
10 11
7. Interoperability with other Disk Encryption Tools
8. Issues with Specific Versions of cryptsetup
Arno Wagner's avatar
Arno Wagner committed
12 13
9. The Initrd question
10. References and Further Reading
Arno Wagner's avatar
Arno Wagner committed
14
A. Contributors
Arno Wagner's avatar
Arno Wagner committed
15

16
1. General Questions
Arno Wagner's avatar
Arno Wagner committed
17 18


19
  * 1.1 What is this?
Arno Wagner's avatar
Arno Wagner committed
20

21 22 23 24 25 26
  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
Milan Broz's avatar
Milan Broz committed
27
  https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
Arno Wagner's avatar
Arno Wagner committed
28

Arno Wagner's avatar
Arno Wagner committed
29

30
  * 1.2 WARNINGS
Arno Wagner's avatar
Arno Wagner committed
31

Arno Wagner's avatar
Arno Wagner committed
32
  ATTENTION: If you are going to read just one thing, make it the
33
  section on Backup and Data Recovery.  By far the most questions on
34
  the cryptsetup mailing list are from people that managed to damage
35 36 37 38 39 40 41 42 43 44 45
  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.

  DEBUG COMMANDS: While the --debug option does not leak 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.
46

Arno Wagner's avatar
Arno Wagner committed
47 48
  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
49 50
  full set of security features intact.  This may or may not be a
  problem, depending on the attacker model.  See Section 5.19.
Arno Wagner's avatar
Arno Wagner committed
51

52 53
  BACKUP: Yes, encrypted disks die, just as normal ones do.  A full
  backup is mandatory, see Section "6.  Backup and Data Recovery" on
Arno Wagner's avatar
Arno Wagner committed
54 55
  options for doing encrypted backup.

Debian User's avatar
Debian User committed
56
  CLONING/IMAGING: If you clone or image a LUKS container, you make a
57 58 59 60 61
  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
Debian User's avatar
Debian User committed
62
  passphrase on that machine can decrypt all other copies, breaking
63
  security.  See also Item 6.15.
Debian User's avatar
Debian User committed
64

65 66 67 68 69 70
  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.
71

wagner's avatar
wagner committed
72
  UBUNTU INSTALLER: In particular the Ubuntu installer seems to be
73
  quite willing to kill LUKS containers in several different ways. 
wagner's avatar
wagner committed
74 75 76 77 78
  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.

Arno Wagner's avatar
Arno Wagner committed
79
  NO WARNING ON NON-INTERACTIVE FORMAT: If you feed cryptsetup from
80 81 82 83 84 85
  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.
Arno Wagner's avatar
Arno Wagner committed
86

87
  LUKS PASSPHRASE IS NOT THE MASTER KEY: The LUKS passphrase is not
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
  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

  - Ubuntu as of 4/2011: It seems the installer offers to create LUKS
  partitions in a way that several people mistook for an offer to
  activate their existing LUKS partition.  The installer gives no or an
  inadequate warning and will destroy your old LUKS header, causing
  permanent data loss.  See also the section on Backup and Data
  Recovery.

  This issue has been acknowledged by the Ubuntu dev team, see
  here: http://launchpad.net/bugs/420080

  Update 4/2013: I am still unsure whether this has been fixed by now,
  best be careful.  They also seem to have added even more LUKS killer
  functionality to the Ubuntu installer.  I can only strongly
wagner's avatar
wagner committed
128 129
  recommended to not install Ubuntu on a system with existing LUKS
  containers without complete backups.
Arno Wagner's avatar
Arno Wagner committed
130

131 132 133 134
  Update 11/2014: There seem to be other problems withe existing LUKS
  containers and Ubuntu as well, be extra careful when using LUKS
  on Ubuntu in any way, but exactly as the Ubuntu installer does.

135

136
  * 1.4 My LUKS-device is broken! Help!
137 138 139 140

  First: Do not panic! In many cases the data is still recoverable.
  Do not do anything hasty! Steps:

141 142
  - Take some deep breaths. Maybe add some relaxing music.  This may
  sound funny, but I am completely serious.  Often, critical damage is
143 144
  done only after the initial problem.

145 146
  - Do not reboot. The keys may still be in the kernel if the device is
  mapped.
147 148 149 150

  - Make sure others do not reboot the system.

  - Do not write to your disk without a clear understanding why this
151 152
  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
153 154 155 156 157 158 159 160 161
  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.


162
  * 1.5 Who wrote this?
Arno Wagner's avatar
Arno Wagner committed
163

164 165 166
  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.
wagner's avatar
wagner committed
167 168 169 170

  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
171 172 173
  ..." 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.
Arno Wagner's avatar
Arno Wagner committed
174 175 176

  This work is under the "Attribution-Share Alike 3.0 Unported"
  license, which means distribution is unlimited, you may create
177 178 179 180
  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.
Arno Wagner's avatar
Arno Wagner committed
181

182 183 184
  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.
Arno Wagner's avatar
Arno Wagner committed
185

Arno Wagner's avatar
Arno Wagner committed
186

187
  * 1.6 Where is the project website?
Arno Wagner's avatar
Arno Wagner committed
188

189 190 191 192
  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.
Arno Wagner's avatar
Arno Wagner committed
193

Arno Wagner's avatar
Arno Wagner committed
194

195
  * 1.7 Is there a mailing-list?
Arno Wagner's avatar
Arno Wagner committed
196 197

  Instructions on how to subscribe to the mailing-list are at on the
198
  project website.  People are generally helpful and friendly on the
Arno Wagner's avatar
Arno Wagner committed
199 200 201
  list.

  The question of how to unsubscribe from the list does crop up
202 203 204 205
  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.
Arno Wagner's avatar
Arno Wagner committed
206 207

  Alternatively, you can send an Email to dm-crypt-request@saout.de
208
  with just the word "help" in the subject or message body.  Make sure
Arno Wagner's avatar
Arno Wagner committed
209 210
  to send it from your list address.

211
  The mailing list archive is here:
212
  https://marc.info/?l=dm-crypt
213

Arno Wagner's avatar
Arno Wagner committed
214

215
  * 1.8 Unsubscribe from the mailing-list
wagner's avatar
wagner committed
216 217 218 219 220

  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
221
  unsubscribed.  The listserver admin functions are not very fast.  It
wagner's avatar
wagner committed
222 223 224 225 226 227 228
  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.

229 230 231 232
  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):
wagner's avatar
wagner committed
233

234
    Subject: confirm 9964cf10.....
wagner's avatar
wagner committed
235

236 237 238 239
  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.
wagner's avatar
wagner committed
240

Arno Wagner's avatar
Arno Wagner committed
241

242
2. Setup
Arno Wagner's avatar
Arno Wagner committed
243

244
  * 2.1 LUKS Container Setup mini-HOWTO
wagner's avatar
wagner committed
245 246

  This item tries to give you a very brief list of all the steps you
247
  should go though when creating a new LUKS encrypted container, i.e. 
wagner's avatar
wagner committed
248 249
  encrypted disk, partition or loop-file.

250
  01) All data will be lost, if there is data on the target, make a
wagner's avatar
wagner committed
251 252 253 254 255
  backup.

  02) Make very sure you have the right target disk, partition or
  loop-file.

256 257 258 259 260 261 262
  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.
wagner's avatar
wagner committed
263

264
  To just quickly wipe file systems (old data may remain), use
wagner's avatar
wagner committed
265

266 267 268
    wipefs -a <target device>


269 270
  To wipe file system and data, use something like

271 272 273 274 275 276 277 278 279 280
    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>

wagner's avatar
wagner committed
281 282 283

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

284 285
  Note that automatic wiping is on the TODO list for cryptsetup, so at
  some time in the future this will become unnecessary.
wagner's avatar
wagner committed
286

287
  Alternatively, plain dm-crypt can be used for a very fast wipe with
wagner's avatar
wagner committed
288 289
  crypto-grade randomness, see Item 2.19

wagner's avatar
wagner committed
290
  04) Create the LUKS container:
291 292 293 294

    cryptsetup luksFormat <target device>


wagner's avatar
wagner committed
295 296
  Just follow the on-screen instructions.

wagner's avatar
wagner committed
297
  Note: Passphrase iteration is determined by cryptsetup depending on
298 299 300
  CPU power.  On a slow device, this may be lower than you want.  I
  recently benchmarked this on a Raspberry Pi and it came out at about
  1/15 of the iteration count for a typical PC.  If security is
wagner's avatar
wagner committed
301
  paramount, you may want to increase the time spent in iteration, at
302 303 304
  the cost of a slower unlock later.  For the Raspberry Pi, using

    cryptsetup luksFormat -i 15000 <target device>
wagner's avatar
wagner committed
305 306

  gives you an iteration count and security level equal to an average
307
  PC for passphrase iteration and master-key iteration.  If in doubt,
wagner's avatar
wagner committed
308 309
  check the iteration counts with

310 311
    cryptsetup luksDump <target device>

wagner's avatar
wagner committed
312 313
  and adjust the iteration count accordingly by creating the container
  again with a different iteration time (the number after '-i' is the
Arno Wagner's avatar
Arno Wagner committed
314
  iteration time in milliseconds) until your requirements are met.
wagner's avatar
wagner committed
315

wagner's avatar
wagner committed
316
  05) Map the container. Here it will be mapped to /dev/mapper/c1:
317 318 319 320 321 322 323 324 325 326

    cryptsetup luksOpen <target device> c1


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

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


wagner's avatar
wagner committed
327
  Note that this creates a small information leak, as an attacker can
328 329 330 331 332
  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.
wagner's avatar
wagner committed
333 334 335 336

  Note that at some time in the future, cryptsetup will do this for
  you, but currently it is a TODO list item.

337
  07) Create a file system in the mapped container, for example an
wagner's avatar
wagner committed
338 339
  ext3 file system (any other file system is possible):

340 341 342
    mke2fs -j /dev/mapper/c1


wagner's avatar
wagner committed
343
  08) Mount your encrypted file system, here on /mnt:
344 345 346 347 348

    mount /dev/mapper/c1 /mnt


  Done. You can now use the encrypted file system to store data.  Be
wagner's avatar
wagner committed
349
  sure to read though the rest of the FAQ, these are just the very
350 351
  basics.  In particular, there are a number of mistakes that are easy
  to make, but will compromise your security.
wagner's avatar
wagner committed
352 353


354
  * 2.2 LUKS on partitions or raw disks?
wagner's avatar
wagner committed
355 356

  This is a complicated question, and made more so by the availability
357 358 359 360 361
  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.
wagner's avatar
wagner committed
362

363
  Be aware that if you add LVM into the mix, things can get very
364 365
  complicated.  Same with RAID but less so.  In particular, data
  recovery can get exceedingly difficult.  Only do so if you have a
366
  really good reason and always remember KISS is what separates an
367 368 369
  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
370 371 372
  needs to be fought without mercy when encountered.

  Also consider using RAID instead of LVM, as at least with the old
373 374 375 376 377 378 379 380
  superblock format 0.90, the RAID superblock is in the place (end of
  disk) where the risk of it permanently 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.  Be aware that you lose
  autodetection with them and have to fall back to some user-space
  script to do it.
wagner's avatar
wagner committed
381 382 383

  Scenarios:

384 385 386 387
  (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,
wagner's avatar
wagner committed
388
  non-confidential data, data for some specific applications,
389
  user-homes, root, etc.  Advantages are simplicity as there is a 1:1
wagner's avatar
wagner committed
390 391 392 393 394
  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
395
  initrd.  On the other hand, an initrd is about as vulnerable to a
wagner's avatar
wagner committed
396
  competent attacker as a non-encrypted root, so there really is no
397 398 399 400 401
  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 move that to
  additional encrypted partitions.  If you really are concerned your
wagner's avatar
wagner committed
402
  root partition may be sabotaged by somebody with physical access
403 404 405
  (that 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).
wagner's avatar
wagner committed
406

407 408 409 410 411
  (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.
wagner's avatar
wagner committed
412 413

  (3) Encrypted RAID: Create your RAID from partitions and/or full
414 415 416
  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
wagner's avatar
wagner committed
417 418 419
  it: You can do RAID1 with an arbitrary number of components in
  Linux.) See also Item 2.8.

420
  (4) Now, some people advocate doing the encryption below the RAID
421 422 423 424 425 426 427 428
  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
  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.
wagner's avatar
wagner committed
429 430


431
  * 2.3 How do I set up encrypted swap?
wagner's avatar
wagner committed
432 433

  As things that are confidential can end up in swap (keys,
434
  passphrases, etc.  are usually protected against being swapped to
wagner's avatar
wagner committed
435
  disk, but other things may not be), it may be advisable to do
436 437 438
  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
wagner's avatar
wagner committed
439 440 441
  that is to encrypt swap with a random key at boot-time.

  NOTE: This is for Debian, and should work for Debian-derived
442
  distributions.  For others you may have to write your own startup
wagner's avatar
wagner committed
443 444
  script or use other mechanisms.

445 446 447 448 449
  01) Add the swap partition to /etc/crypttab. A line like the
  following should do it:

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

wagner's avatar
wagner committed
450 451 452 453

  Warning: While Debian refuses to overwrite partitions with a
  filesystem or RAID signature on it, if your disk IDs may change
  (adding or removing disks, failure of disk during boot, etc.), you
454 455 456 457 458 459 460 461 462 463
  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-disk RAID1 or by using LVM), so that it 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.
wagner's avatar
wagner committed
464 465

  Note: Use /dev/random if you are paranoid or in a potential
466 467 468
  low-entropy situation (embedded system, etc.).  This may cause the
  operation to take a long time during boot.  If you are in a "no
  entropy" situation, you cannot encrypt swap securely.  In this
wagner's avatar
wagner committed
469 470 471
  situation you should find some entropy, also because nothing else
  using crypto will be secure, like ssh, ssl or GnuPG.

472 473
  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
wagner's avatar
wagner committed
474 475 476 477 478
  it late.

  02) Add the swap partition to /etc/fstab. A line like the following
  should do it:

479 480 481 482
    /dev/mapper/swap none swap sw 0 0


  That is it. Reboot or start it manually to activate encrypted swap. 
wagner's avatar
wagner committed
483 484
  Manual start would look like this:

485 486 487
    /etc/init.d/crypdisks start
    swapon /dev/mapper/swap

wagner's avatar
wagner committed
488

489 490

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

Arno Wagner's avatar
Arno Wagner committed
492
  First, unless you happen to understand the cryptographic background
493 494
  well, you should use LUKS.  It does protect the user from a lot of
  common mistakes.  Plain dm-crypt is for experts.
Arno Wagner's avatar
Arno Wagner committed
495

496
  Plain format is just that: It has no metadata on disk, reads all
Arno Wagner's avatar
Arno Wagner committed
497
  parameters from the commandline (or the defaults), derives a
498 499 500
  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.
501 502

  Primary advantage is high resilience to damage, as one damaged
503 504 505 506
  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.
507

508
  Side-note: That has limited value against the authorities.  In
509
  civilized countries, they cannot force you to give up a crypto-key
510 511 512 513 514 515 516 517 518 519
  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.
wagner's avatar
wagner committed
520 521

  My advice is to either be ready to give up the keys or to not have
522
  encrypted data when traveling to those countries, especially when
523 524 525 526
  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.
527

528 529 530 531
  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..
532 533

  LUKS format uses a metadata header and 8 key-slot areas that are
534 535 536
  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
537 538 539 540
  stripes.

  Advantages are a higher usability, automatic configuration of
  non-default crypto parameters, defenses against low-entropy
541 542
  passphrases like salting and iterated PBKDF2 passphrase hashing, the
  ability to change passphrases, and others.
543

544 545 546 547 548 549 550
  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 (1MB+4096B for defaults
  and 2MB for the most commonly used non-default XTS mode).
551 552


553
  * 2.5 Can I encrypt an already existing, non-empty partition to use LUKS?
Arno Wagner's avatar
Arno Wagner committed
554 555

  There is no converter, and it is not really needed. The way to do
556 557 558 559 560 561
  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".
Arno Wagner's avatar
Arno Wagner committed
562 563 564 565

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

Arno Wagner's avatar
Arno Wagner committed
566

567
  * 2.6 How do I use LUKS with a loop-device?
Arno Wagner's avatar
Arno Wagner committed
568

Arno Wagner's avatar
Arno Wagner committed
569
  This can be very handy for experiments. Setup is just the same as
570
  with any block device.  If you want, for example, to use a 100MiB
Arno Wagner's avatar
Arno Wagner committed
571
  file as LUKS container, do something like this:
Arno Wagner's avatar
Arno Wagner committed
572

573 574 575 576
    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 loop device

Arno Wagner's avatar
Arno Wagner committed
577 578 579
  Afterwards just use /dev/loop0 as a you would use a LUKS partition.
  To unmap the file when done, use "losetup -d /dev/loop0".

Arno Wagner's avatar
Arno Wagner committed
580

581 582 583
  * 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?
Arno Wagner's avatar
Arno Wagner committed
584 585 586

  That is as intended. You are asked a passphrase of an existing
  key-slot first, before you can enter the passphrase for the new
587 588
  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
Arno Wagner's avatar
Arno Wagner committed
589 590 591
  the already configured key-slots in order to be able to configure a
  new key-slot.

Arno Wagner's avatar
Arno Wagner committed
592

593
  * 2.8 Encryption on top of RAID or the other way round?
Arno Wagner's avatar
Arno Wagner committed
594 595

  Unless you have special needs, place encryption between RAID and
596
  filesystem, i.e.  encryption on top of RAID.  You can do it the other
Arno Wagner's avatar
Arno Wagner committed
597
  way round, but you have to be aware that you then need to give the
598 599 600
  passphrase for each individual disk and RAID autodetection will not
  work anymore.  Therefore it is better to encrypt the RAID device,
  e.g.  /dev/dm0 .
Arno Wagner's avatar
Arno Wagner committed
601

wagner's avatar
wagner committed
602 603 604 605 606 607 608 609 610 611 612 613
  This means that the typical layering looks like this:

  Filesystem     <- top
  |
  Encryption
  |
  RAID
  |
  Raw partitions
  |
  Raw disks      <- bottom

614 615
  The big advantage is that you can manage the RAID container just like
  any RAID container, it does not care that what is in it is encrypted.
Arno Wagner's avatar
Arno Wagner committed
616

617 618

  * 2.9 How do I read a dm-crypt key from file?
Arno Wagner's avatar
Arno Wagner committed
619

wagner's avatar
wagner committed
620
  Use the --key-file option, like this:
Arno Wagner's avatar
Arno Wagner committed
621

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

wagner's avatar
wagner committed
624 625
  This will read the binary key from file, i.e. no hashing or
  transformation will be applied to the keyfile before its bits are
626 627 628
  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 still
  be hashed, just as a key read interactively from the terminal.  See
wagner's avatar
wagner committed
629 630 631
  the man-page sections "NOTES ON PASSPHRASE PROCESSING..." for more
  detail.

632
  * 2.10 How do I read a LUKS slot key from file?
Arno Wagner's avatar
Arno Wagner committed
633 634

  What you really do here is to read a passphrase from file, just as
635
  you would with manual entry of a passphrase for a key-slot.  You can
Arno Wagner's avatar
Arno Wagner committed
636 637
  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
638
  file.  In the last case make sure no trailing newline (0x0a) is
Arno Wagner's avatar
Arno Wagner committed
639 640 641 642 643 644
  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:

645 646 647 648 649 650 651 652
    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

Arno Wagner's avatar
Arno Wagner committed
653 654 655 656

  To supply a key from file to any LUKS command, use the --key-file
  option, e.g. like this:

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

Arno Wagner's avatar
Arno Wagner committed
659

660 661

  * 2.11 How do I read the LUKS master key from file?
Arno Wagner's avatar
Arno Wagner committed
662

Arno Wagner's avatar
Arno Wagner committed
663
  The question you should ask yourself first is why you would want to
664 665 666 667 668 669 670
  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.

Arno Wagner's avatar
Arno Wagner committed
671

672
  * 2.12 What are the security requirements for a key read from file?
Arno Wagner's avatar
Arno Wagner committed
673

674 675 676 677 678 679
  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:
Arno Wagner's avatar
Arno Wagner committed
680

681
    head -c 256 /dev/random > keyfile
Arno Wagner's avatar
Arno Wagner committed
682

Arno Wagner's avatar
Arno Wagner committed
683

684 685 686

  * 2.13 If I map a journaled file system using dm-crypt/LUKS, does
    it still provide its usual transactional guarantees?
Arno Wagner's avatar
Arno Wagner committed
687

Arno Wagner's avatar
Arno Wagner committed
688 689
  Yes, it does, unless a very old kernel is used. The required flags
  come from the filesystem layer and are processed and passed onwards
690
  by dm-crypt.  A bit more information on the process by which
Arno Wagner's avatar
Arno Wagner committed
691 692 693 694 695
  transactional guarantees are implemented can be found here:

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

  Please note that these "guarantees" are weaker than they appear to
696 697 698 699 700
  be.  One problem is that quite a few disks lie to the OS about having
  flushed their buffers.  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.
Arno Wagner's avatar
Arno Wagner committed
701 702

  One specific problem you can run into though is that you can get
703 704
  short freezes and other slowdowns due to the encryption layer. 
  Encryption takes time and forced flushes will block for that time. 
Arno Wagner's avatar
Arno Wagner committed
705
  For example, I did run into frequent small freezes (1-2 sec) when
706 707 708 709 710
  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).  It should improve
  further and eventually the problem should go away.
Arno Wagner's avatar
Arno Wagner committed
711

Arno Wagner's avatar
Arno Wagner committed
712

713 714
  * 2.14 Can I use LUKS or cryptsetup with a more secure (external)
    medium for key storage, e.g. TPM or a smartcard?
Arno Wagner's avatar
Arno Wagner committed
715 716

  Yes, see the answers on using a file-supplied key. You do have to
717 718 719
  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.
Arno Wagner's avatar
Arno Wagner committed
720

wagner's avatar
wagner committed
721
  For TPM support, you may want to have a look at tpm-luks at
722
  https://github.com/shpedoikal/tpm-luks.  Note that tpm-luks is not
wagner's avatar
wagner committed
723 724
  related to the cryptsetup project.

Arno Wagner's avatar
Arno Wagner committed
725

726
  * 2.15 Can I resize a dm-crypt or LUKS partition?
Arno Wagner's avatar
Arno Wagner committed
727 728

  Yes, you can, as neither dm-crypt nor LUKS stores partition size.
729
  Whether you should is a different question.  Personally I recommend
Arno Wagner's avatar
Arno Wagner committed
730
  backup, recreation of the encrypted partition with new size,
731 732 733 734 735 736 737
  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.  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 typically works.  This will not
  change the size of the filesystem hidden under the encryption though.
Arno Wagner's avatar
Arno Wagner committed
738 739 740

  You also need to be aware of size-based limitations. The one
  currently relevant is that aes-xts-plain should not be used for
741 742
  encrypted container sizes larger than 2TiB.  Use aes-xts-plain64 for
  that.
Arno Wagner's avatar
Arno Wagner committed
743 744


745
  * 2.16 How do I Benchmark the Ciphers, Hashes and Modes?
wagner's avatar
wagner committed
746

747
  Since version 1.60 cryptsetup supports the "benchmark" command. 
wagner's avatar
wagner committed
748 749
  Simply run as root:

750 751
    cryptsetup benchmark

wagner's avatar
wagner committed
752
  It will output first iterations/second for the key-derivation
753 754 755 756 757 758
  function PBKDF2 parameterized with different hash-functions, and then
  the raw encryption speed of ciphers with different modes and
  key-sizes.  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.
wagner's avatar
wagner committed
759 760


761
  * 2.17 How do I Verify I have an Authentic cryptsetup Source Package?
wagner's avatar
wagner committed
762 763

  Current maintainer is Milan Broz and he signs the release packages
764 765 766 767 768 769
  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.
wagner's avatar
wagner committed
770 771

  That said, as cryptsetup is under good version control, a malicious
772
  change should be noticed sooner or later, but it may take a while. 
wagner's avatar
wagner committed
773
  Also, the attacker model makes compromising the sources in a
774
  non-obvious way pretty hard.  Sure, you could put the master-key
wagner's avatar
wagner committed
775
  somewhere on disk, but that is rather obvious as soon as somebody
776 777 778 779 780
  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.
wagner's avatar
wagner committed
781 782

  That said, this discussion is really a lot more complicated and
783
  longer as an FAQ can sustain.  If in doubt, ask on the mailing list.
wagner's avatar
wagner committed
784 785


786
  * 2.18 Is there a concern with 4k Sectors?
wagner's avatar
wagner committed
787

788 789
  Not from dm-crypt itself. Encryption will be done in 512B blocks, but
  if the partition and filesystem are aligned correctly and the
wagner's avatar
wagner committed
790 791
  filesystem uses multiples of 4kiB as block size, the dm-crypt layer
  will just process 8 x 512B = 4096B at a time with negligible
792 793 794
  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
wagner's avatar
wagner committed
795 796 797
  misaligned, dm-crypt can make the effect worse though.


798
  * 2.19 How can I wipe a device with crypto-grade randomness?
wagner's avatar
wagner committed
799 800 801 802

  The conventional recommendation if you want to not just do a
  zero-wipe is to use something like

803 804
    cat /dev/urandom >  <taget-device>

wagner's avatar
wagner committed
805
  That is very slow and painful at 10-20MB/s on a fast computer.
806 807
  Using cryptsetup and a plain dm-crypt device with a random key,
  it is much faster and gives you the same level of security. The
wagner's avatar
wagner committed
808 809 810 811
  defaults are quite enough.

  For device set-up, do the following:

Arno Wagner's avatar
Arno Wagner committed
812
    cryptsetup open --type plain -d /dev/urandom /dev/<block-device> to_be_wiped
813 814 815 816 817 818

  This maps the container as plain under /dev/mapper/to_be_wiped with a
  random password.  For the actual wipe you have several options. 
  Simple wipe without progress-indicator:

    cat /dev/zero > /dev/mapper/to_be_wiped
wagner's avatar
wagner committed
819 820 821

  Progress-indicator by dd_rescue:

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

wagner's avatar
wagner committed
824 825 826
  Progress-indicator by my "wcs" stream meter (available from
  http://www.tansi.org/tools/index.html ):

827 828 829
    cat /dev/zero | wcs > /dev/mapper/to_be_wiped


wagner's avatar
wagner committed
830 831
  Remove the mapping at the end and you are done.

Arno Wagner's avatar
Arno Wagner committed
832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
  * 2.20 How to I wipe only the LUKS header?

  This is not the emergency wipe procedure. That is in Item 5.4. This procedure
  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.

  Most safe way is this (backup is still a good idea):
 
  01) Determine header size in 512 Byte sectors with "luksDump":

     cryptsetup luksDump <device with LUKS container>

->   ...
     Payload offset: <number>
     ...

  02) Take the result number and write number * 512 zeros to the start of the
      device, e.g. like this:

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

  That is it.   

wagner's avatar
wagner committed
855

856
3. Common Problems
Arno Wagner's avatar
Arno Wagner committed
857 858


859 860
  * 3.1 My dm-crypt/LUKS mapping does not work! What general steps
    are there to investigate the problem?
Arno Wagner's avatar
Arno Wagner committed
861 862

  If you get a specific error message, investigate what it claims
863
  first.  If not, you may want to check the following things.
Arno Wagner's avatar
Arno Wagner committed
864

Arno Wagner's avatar
Arno Wagner committed
865
  - Check that "/dev", including "/dev/mapper/control" is there. If it
866 867
  is missing, you may have a problem with the "/dev" tree itself or you
  may have broken udev rules.
Arno Wagner's avatar
Arno Wagner committed
868

Arno Wagner's avatar
Arno Wagner committed
869
  - Check that you have the device mapper and the crypt target in your
870 871
  kernel.  The output of "dmsetup targets" should list a "crypt"
  target.  If it is not there or the command fails, add device mapper
Arno Wagner's avatar
Arno Wagner committed
872
  and crypt-target to the kernel.
Arno Wagner's avatar
Arno Wagner committed
873

Arno Wagner's avatar
Arno Wagner committed
874
  - Check that the hash-functions and ciphers you want to use are in
875
  the kernel.  The output of "cat /proc/crypto" needs to list them.
Arno Wagner's avatar
Arno Wagner committed
876

Arno Wagner's avatar
Arno Wagner committed
877

878
  * 3.2 My dm-crypt mapping suddenly stopped when upgrading cryptsetup.
Arno Wagner's avatar
Arno Wagner committed
879 880

  The default cipher, hash or mode may have changed (the mode changed
881
  from 1.0.x to 1.1.x).  See under "Issues With Specific Versions of
Arno Wagner's avatar
Arno Wagner committed
882 883
  cryptsetup".

Arno Wagner's avatar
Arno Wagner committed
884

885 886
  * 3.3 When I call cryptsetup from cron/CGI, I get errors about
    unknown features?
Arno Wagner's avatar
Arno Wagner committed
887 888

  If you get errors about unknown parameters or the like that are not
889 890 891 892 893 894
  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 the right version gets called.
Arno Wagner's avatar
Arno Wagner committed
895

Arno Wagner's avatar
Arno Wagner committed
896

897
  * 3.4 Unlocking a LUKS device takes very long. Why?
Arno Wagner's avatar
Arno Wagner committed
898

Arno Wagner's avatar
Arno Wagner committed
899
  The iteration time for a key-slot (see Section 5 for an explanation
900 901
  what iteration does) is calculated when setting a passphrase.  By
  default it is 1 second on the machine where the passphrase is set. 
Arno Wagner's avatar
Arno Wagner committed
902
  If you set a passphrase on a fast machine and then unlock it on a
903
  slow machine, the unlocking time can be much longer.  Also take into
Arno Wagner's avatar
Arno Wagner committed
904 905
  account that up to 8 key-slots have to be tried in order to find the
  right one.
Arno Wagner's avatar
Arno Wagner committed
906 907

  If this is problem, you can add another key-slot using the slow
908 909 910
  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
Arno Wagner's avatar
Arno Wagner committed
911 912 913
  luksRemoveKey.

  However, this operation will not change volume key iteration count
914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929
  (MK iterations in output of "cryptsetup luksDump").  In order to
  change that, you will have to backup the data in the LUKS container
  (i.e.  your encrypted data), luksFormat on the slow machine and
  restore the data.  Note that in the original LUKS specification this
  value was fixed to 10, but it is now derived from the PBKDF2
  benchmark as well and set to iterations in 0.125 sec or 1000,
  whichever is larger.  Also note that MK iterations are not very
  security relevant.  But as each key-slot already takes 1 second,
  spending the additional 0.125 seconds really does not matter.

  * 3.5 "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.
Arno Wagner's avatar
Arno Wagner committed
930 931 932 933

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

934 935 936
    cryptsetup luksHeaderBackup --header-backup-file <file> <device>
    cryptsetup luksHeaderRestore --header-backup-file <file> <device>

Arno Wagner's avatar
Arno Wagner committed
937

Arno Wagner's avatar
Arno Wagner committed
938

939
  * 3.6 cryptsetup segfaults on Gentoo amd64 hardened ...
Arno Wagner's avatar
Arno Wagner committed
940

941 942 943 944 945
  There seems to be some interference 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
Arno Wagner's avatar
Arno Wagner committed
946

947 948

4. Troubleshooting
Arno Wagner's avatar
Arno Wagner committed
949 950


951
  * 4.1 I get the error "LUKS keyslot x is invalid." What does that mean?
Arno Wagner's avatar
Arno Wagner committed
952

953 954 955 956 957 958
  This means that the given keyslot has an offset that points outside
  the valid keyslot area.  Typically, the reason is a corrupted LUKS
  header because something was written to the start of the device the
  LUKS container is on.  Refer to Section "Backup and Data Recovery"
  and ask on the mailing list if you have trouble diagnosing and (if
  still possible) repairing this.
Arno Wagner's avatar
Arno Wagner committed
959 960


961
  * 4.2 I cannot unlock my LUKS container! What could be the problem?
wagner's avatar
wagner committed
962 963

  First, make sure you have a correct passphrase. Then make sure you
964 965 966
  have the correct key-map and correct keyboard.  And then make sure
  you have the correct character set and encoding, see also "PASSPHRASE
  CHARACTER SET" under Section 1.2.
wagner's avatar
wagner committed
967 968

  If you are sure you are entering the passphrase right, there is the
969 970 971 972 973 974 975
  possibility that the respective key-slot has been damaged.  There is
  no way to recover a damaged key-slot, except from a header backup
  (see Section 6).  For security reasons, there is also no checksum in
  the key-slots that could tell you whether a key-slot has been
  damaged.  The only checksum present allows recognition of a correct
  passphrase, but that only works if the passphrase is correct and the
  respective key-slot is intact.
wagner's avatar
wagner committed
976 977

  In order to find out whether a key-slot is damaged one has to look
978
  for "non-random looking" data in it.  There is a tool that
wagner's avatar
wagner committed
979
  automatizes this in the cryptsetup distribution from version 1.6.0
980 981
  onwards.  It is located in misc/keyslot_checker/.  Instructions how
  to use and how to interpret results are in the README file.  Note
wagner's avatar
wagner committed
982
  that this tool requires a libcryptsetup from cryptsetup 1.6.0 or
983 984 985 986 987 988 989
  later (which means libcryptsetup.so.4.5.0 or later).  If the tool
  complains about missing functions in libcryptsetup, you likely have
  an earlier version from your distribution still installed.  You can
  either point the symbolic link(s) from libcryptsetup.so.4 to the new
  version manually, or you can uninstall the distribution version of
  cryptsetup and re-install that from cryptsetup >= 1.6.0 again to fix
  this.
wagner's avatar
wagner committed
990 991


992
  * 4.3 Can a bad RAM module cause problems?
Arno Wagner's avatar
Arno Wagner committed
993 994

  LUKS and dm-crypt can give the RAM quite a workout, especially when
995
  combined with software RAID.  In particular the combination RAID5 +
Arno Wagner's avatar
Arno Wagner committed
996
  LUKS + XFS seems to uncover RAM problems that never caused obvious
997
  problems before.  Symptoms vary, but often the problem manifest
Arno Wagner's avatar
Arno Wagner committed
998 999 1000
  itself when copying large amounts of data, typically several times
  larger than your main memory.

Arno Wagner's avatar
Arno Wagner committed
1001
  Side note: One thing you should always do on large data
1002 1003 1004 1005 1006
  copy/movements is to run a verify, for example with the "-d" option
  of "tar" or by doing a set of MD5 checksums on the source or target
  with

    find . -type f -exec md5sum \{\} \; > checksum-file
Arno Wagner's avatar
Arno Wagner committed
1007 1008

  and then a "md5sum -c checksum-file" on the other side. If you get
1009 1010 1011 1012
  mismatches here, RAM is the primary suspect.  A lesser suspect is an
  overclocked CPU.  I have found countless hardware problems in verify
  runs after copying or making backups.  Bit errors are much more
  common than most people think.
Arno Wagner's avatar
Arno Wagner committed
1013 1014

  Some RAM issues are even worse and corrupt structures in one of the
1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038
  layers.  This typically results in lockups, CPU state dumps in the
  system logs, kernel panic or other things.  It is quite possible to
  have the problem with an encrypted device, but not with an otherwise
  the same unencrypted device.  The reason for that is that encryption
  has an error amplification property: You flip one bit in an encrypted
  data block, and the decrypted version has half of its bits flipped. 
  This is an important security property for modern ciphers.  With the
  usual modes in cryptsetup (CBC, ESSIV, XTS), you get up to a
  completely changed 512 byte block per bit error.  A corrupt block
  causes a lot more havoc than the occasionally flipped single bit and
  can result in various obscure errors.

  Note that a verify run on copying between encrypted or unencrypted
  devices will reliably detect corruption, even when the copying itself
  did not report any problems.  If you find defect RAM, assume all
  backups and copied data to be suspect, unless you did a verify.


  * 4.4 How do I test RAM?

  First you should know that overclocking often makes memory problems
  worse.  So if you overclock (which I strongly recommend against in a
  system holding data that has some worth), run the tests with the
  overclocking active.
Arno Wagner's avatar
Arno Wagner committed
1039 1040

  There are two good options. One is Memtest86+ and the other is
1041 1042 1043 1044 1045
  "memtester" by Charles Cazabon.  Memtest86+ requires a reboot and
  then takes over the machine, while memtester runs from a root-shell. 
  Both use different testing methods and I have found problems fast
  with each one that the other needed long to find.  I recommend
  running the following procedure until the first error is found:
Arno Wagner's avatar
Arno Wagner committed
1046

Arno Wagner's avatar
Arno Wagner committed
1047 1048
  - Run Memtest86+ for one cycle

Arno Wagner's avatar
Arno Wagner committed
1049
  - Run memtester for one cycle (shut down as many other applications
1050
    as possible)
Arno Wagner's avatar
Arno Wagner committed
1051

Arno Wagner's avatar
Arno Wagner committed
1052
  - Run Memtest86+ for 24h or more
Arno Wagner's avatar
Arno Wagner committed
1053 1054 1055

  - Run memtester for 24h or more

Arno Wagner's avatar
Arno Wagner committed
1056
  If all that does not produce error messages, your RAM may be sound,
1057 1058
  but I have had one weak bit that Memtest86+ needed around 60 hours to
  find.  If you can reproduce the original problem reliably, a good
Arno Wagner's avatar
Arno Wagner committed
1059 1060
  additional test may be to remove half of the RAM (if you have more
  than one module) and try whether the problem is still there and if
1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075
  so, try with the other half.  If you just have one module, get a
  different one and try with that.  If you do overclocking, reduce the
  settings to the most conservative ones available and try with that.


  * 4.5 Is there a risk using debugging tools like strace?

  There most definitely is. An dump from strace and friends can contain
  all data entered, including the full passphrase.  Example with strace
  and passphrase "test":

    > strace cryptsetup luksOpen /dev/sda10 c1
    ...
    read(6, "test\n", 512)                  = 5
    ...
Arno Wagner's avatar
Arno Wagner committed
1076

1077 1078 1079 1080 1081 1082 1083
  Depending on different factors and the tool used, the passphrase may
  also be encoded and not plainly visible.  Hence it is never a good
  idea to give such a trace from a live container to anybody.  Recreate
  the problem with a test container or set a temporary passphrase like
  "test" and use that for the trace generation.  Item 2.6 explains how
  to create a loop-file backed LUKS container that may come in handy
  for this purpose.
Arno Wagner's avatar
Arno Wagner committed
1084

1085 1086
  See also Item 6.10 for another set of data you should not give to
  others.
Arno Wagner's avatar
Arno Wagner committed
1087 1088


1089 1090 1091 1092
5. Security Aspects


  * 5.1 How long is a secure passphrase ?
wagner's avatar
wagner committed
1093

1094 1095 1096
  This is just the short answer. For more info and explanation of some
  of the terms used in this item, read the rest of Section 5.  The
  actual recommendation is at the end of this item.
wagner's avatar
wagner committed
1097

1098 1099 1100 1101 1102 1103 1104 1105 1106 1107
  First, passphrase length is not really the right measure, passphrase
  entropy is.  For example, a random lowercase letter (a-z) gives you
  4.7 bit of entropy, one element of a-z0-9 gives you 5.2 bits of
  entropy, an element of a-zA-Z0-9 gives you 5.9 bits and
  a-zA-Z0-9!@#$%\^&:-+ gives you 6.2 bits.  On the other hand, a random
  English word only gives you 0.6...1.3 bits of entropy per character. 
  Using sentences that make sense gives lower entropy, series of random
  words gives higher entropy.  Do not use sentences that can be tied to
  you or found on your computer.  This type of attack is done routinely
  today.
wagner's avatar
wagner committed
1108 1109 1110 1111 1112

  That said, it does not matter too much what scheme you use, but it
  does matter how much entropy your passphrase contains, because an
  attacker has to try on average

1113 1114
    1/2 * 2^(bits of entropy in passphrase)

wagner's avatar
wagner committed
1115 1116
  different passphrases to guess correctly.

1117 1118
  Historically, estimations tended to use computing time estimates, but
  more modern approaches try to estimate cost of guessing a passphrase.
wagner's avatar
wagner committed
1119 1120 1121

  As an example, I will try to get an estimate from the numbers in
  http://it.slashdot.org/story/12/12/05/0623215/new-25-gpu-monster-devours-strong-passwords-in-minutes
1122 1123 1124
  More references can be found a the end of this document.  Note that
  these are estimates from the defender side, so assuming something is
  easier than it actually is is fine.  An attacker may still have
wagner's avatar
wagner committed
1125 1126
  vastly higher cost than estimated here.

1127 1128 1129
  LUKS uses SHA1 for hashing per default. The claim in the reference is
  63 billion tries/second for SHA1.  We will leave aside the check
  whether a try actually decrypts a key-slot.  Now, the machine has 25
wagner's avatar
wagner committed
1130
  GPUs, which I will estimate at an overall lifetime cost of USD/EUR
1131
  1000 each, and an useful lifetime of 2 years.  (This is on the low
wagner's avatar
wagner committed
1132 1133
  side.) Disregarding downtime, the machine can then break

1134 1135
     N = 63*10^9 * 3600 * 24 * 365 * 2 ~ 4*10^18

wagner's avatar
wagner committed
1136
  passphrases for EUR/USD 25k. That is one 62 bit passphrase hashed
1137
  once with SHA1 for EUR/USD 25k.  Note that as this can be
wagner's avatar
wagner committed
1138 1139 1140 1141
  parallelized, it can be done faster than 2 years with several of
  these machines.

  For plain dm-crypt (no hash iteration) this is it. This gives (with
1142 1143
  SHA1, plain dm-crypt default is ripemd160 which seems to be slightly
  slower than SHA1):
wagner's avatar
wagner committed
1144

1145 1146
    Passphrase entropy  Cost to break
    60 bit              EUR/USD     6k
wagner's avatar
wagner committed
1147 1148 1149 1150 1151
    65 bit              EUR/USD   200K
    70 bit              EUR/USD     6M
    75 bit              EUR/USD   200M
    80 bit              EUR/USD     6B
    85 bit              EUR/USD   200B
1152 1153 1154 1155 1156 1157
    ...                      ...


  For LUKS, you have to take into account hash iteration in PBKDF2. 
  For a current CPU, there are about 100k iterations (as can be queried
  with ''cryptsetup luksDump''.
wagner's avatar
wagner committed
1158 1159 1160

  The table above then becomes:

1161 1162
    Passphrase entropy  Cost to break
    50 bit              EUR/USD   600k
wagner's avatar
wagner committed
1163
    55 bit              EUR/USD    20M
1164
    60 bit              EUR/USD   600M
wagner's avatar
wagner committed
1165 1166 1167
    65 bit              EUR/USD    20B
    70 bit              EUR/USD   600B
    75 bit              EUR/USD    20T
1168 1169 1170
    ...                      ...


wagner's avatar
wagner committed
1171 1172
  Recommendation:

1173
  To get reasonable security for the  next 10 years, it is a good idea
wagner's avatar
wagner committed
1174 1175 1176
  to overestimate by a factor of at least 1000.

  Then there is the question of how much the attacker is willing to
1177
  spend.  That is up to your own security evaluation.  For general use,
wagner's avatar
wagner committed
1178
  I will assume the attacker is willing to spend up to 1 million
1179
  EUR/USD.  Then we get the following recommendations:
wagner's avatar
wagner committed
1180 1181 1182 1183

  Plain dm-crypt: Use > 80 bit. That is e.g. 17 random chars from a-z
  or a random English sentence of > 135 characters length.

1184 1185
  LUKS: Use > 65 bit. That is e.g. 14 random chars from a-z or a random
  English sentence of > 108 characters length.
wagner's avatar
wagner committed
1186 1187 1188 1189 1190 1191

  If paranoid, add at least 20 bit. That is roughly four additional
  characters for random passphrases and roughly 32 characters for a
  random English sentence.


1192
  * 5.2 Is LUKS insecure? Everybody can see I have encrypted data!
Arno Wagner's avatar
Arno Wagner committed
1193 1194

  In practice it does not really matter. In most civilized countries
1195
  you can just refuse to hand over the keys, no harm done.  In some
Arno Wagner's avatar
Arno Wagner committed
1196
  countries they can force you to hand over the keys, if they suspect
1197 1198
  encryption.  However the suspicion is enough, they do not have to
  prove anything.  This is for practical reasons, as even the presence
Arno Wagner's avatar
Arno Wagner committed
1199
  of a header (like the LUKS header) is not enough to prove that you
1200 1201 1202 1203
  have any keys.  It might have been an experiment, for example.  Or it
  was used as encrypted swap with a key from /dev/random.  So they make
  you prove you do not have encrypted data.  Of course that is just as
  impossible as the other way round.
Arno Wagner's avatar
Arno Wagner committed
1204

1205 1206 1207 1208 1209 1210
  This means that if you have a large set of random-looking data, they
  can already lock you up.  Hidden containers (encryption hidden within
  encryption), as possible with Truecrypt, do not help either.  They
  will just assume the hidden container is there and unless you hand
  over the key, you will stay locked up.  Don't have a hidden
  container?  Though luck.  Anybody could claim that.
Arno Wagner's avatar
Arno Wagner committed
1211

1212 1213 1214
  Still, if you are concerned about the LUKS header, use plain dm-crypt
  with a good passphrase.  See also Section 2, "What is the difference
  between "plain" and LUKS format?"
Arno Wagner's avatar
Arno Wagner committed
1215 1216


1217
  * 5.3 Should I initialize (overwrite) a new LUKS/dm-crypt partition?
Arno Wagner's avatar
Arno Wagner committed
1218 1219

  If you just create a filesystem on it, most of the old data will
1220 1221 1222 1223 1224 1225 1226 1227 1228 1229
  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

Arno Wagner's avatar
Arno Wagner committed
1230
  or alternatively with one of the following more standard commands:
Arno Wagner's avatar
Arno Wagner committed
1231

1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255
    cat /dev/zero > /dev/mapper/e1
    dd if=/dev/zero of=/dev/mapper/e1



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

  For LUKS, if you are in a desperate hurry, overwrite the LUKS header
  and key-slot area.  This means overwriting the first (keyslots x
  stripes x keysize) + offset bytes.  For the default parameters, this
  is the 1'052'672 bytes, i.e.  1MiB + 4096 of the LUKS partition.  For
  512 bit key length (e.g.  for aes-xts-plain with 512 bit key) this is
  2MiB.  (The different offset stems from differences in the sector
  alignment of the key-slots.) If in doubt, just be generous and
  overwrite the first 10MB or so, it will likely still be fast enough. 
  A single overwrite with zeros should be enough.  If you anticipate
  being in a desperate hurry, prepare the command beforehand.  Example
  with /dev/sde1 as the LUKS partition and default parameters:

    head -c 1052672 /dev/zero > /dev/sde1; sync

  A LUKS header backup or full backup will still grant access to most
  or all data, so make sure that an attacker does not have access to
  backups or destroy them as well.
Arno Wagner's avatar
Arno Wagner committed
1256 1257

  If you have time, overwrite the whole LUKS partition with a single
1258 1259 1260 1261 1262 1263 1264 1265 1266
  pass of zeros.  This is enough for current HDDs.  For SSDs or FLASH
  (USB sticks) you may want to overwrite the whole drive several times
  to be sure data is not retained by wear leveling.  This is possibly
  still insecure as SSD 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 or FLASH drive could be
  enough.  If in doubt, use physical destruction in addition.  Here is
  a link to some current research results on erasing SSDs and FLASH
  drives: http://www.usenix.org/events/fast11/tech/full_papers/Wei.pdf
1267 1268

  Keep in mind to also erase all backups.
Arno Wagner's avatar
Arno Wagner committed
1269 1270

  Example for a zero-overwrite erase of partition sde1 done with
Arno Wagner's avatar
Arno Wagner committed
1271 1272
  dd_rescue:

1273
    dd_rescue -w /dev/zero /dev/sde1
Arno Wagner's avatar
Arno Wagner committed
1274

1275 1276 1277


  * 5.5 How do I securely erase a backup of a LUKS partition or header?
Arno Wagner's avatar
Arno Wagner committed
1278 1279

  That depends on the medium it is stored on. For HDD and SSD, use
1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295
  overwrite with zeros.  For an SSD or FLASH drive (USB stick), you may
  want to overwrite the complete SSD several times and use physical
  destruction in addition, see last item.  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, after overwriting .  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.


  * 5.6 What about backup? Does it compromise security?
Arno Wagner's avatar
Arno Wagner committed
1296

Debian User's avatar
Debian User committed
1297
  That depends. See item 6.7.
Arno Wagner's avatar
Arno Wagner committed
1298

Arno Wagner's avatar
Arno Wagner committed
1299

1300
  * 5.7 Why is all my data permanently gone if I overwrite the LUKS header?
Arno Wagner's avatar
Arno Wagner committed
1301 1302

  Overwriting the LUKS header in part or in full is the most common
1303 1304 1305 1306
  reason why access to LUKS containers is lost permanently. 
  Overwriting can be done in a number of fashions, like creating a new
  filesystem on the raw LUKS partition, making the raw partition part
  of a raid array and just writing to the raw partition.
Arno Wagner's avatar
Arno Wagner committed
1307

wagner's avatar
wagner committed
1308
  The LUKS header contains a 256 bit "salt" per key-slot and without
1309 1310 1311 1312 1313 1314 1315 1316 1317
  that no decryption is possible.  While the salts are not secret, they
  are key-grade material and cannot be reconstructed.  This is a
  cryptographically strong "cannot".  From observations on the
  cryptsetup mailing-list, people typically go though the usual stages
  of grief (Denial, Anger, Bargaining, Depression, Acceptance) when
  this happens to them.  Observed times vary between 1 day and 2 weeks
  to complete the cycle.  Seeking help on the mailing-list is fine. 
  Even if we usually cannot help with getting back your data, most
  people found the feedback comforting.
Arno Wagner's avatar
Arno Wagner committed
1318

wagner's avatar
wagner committed
1319
  If your header does not contain an intact key-slot salt, best go
1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346
  directly to the last stage ("Acceptance") and think about what to do
  now.  There is one exception that I know of: If your LUKS container
  is still open, then it may be possible to extract the master key from
  the running system.  See Item "How do I recover the master key from a
  mapped LUKS container?" in Section "Backup and Data Recovery".


  * 5.8 What is a "salt"?

  A salt is a random key-grade value added to the passphrase before it
  is processed.  It is not kept secret.  The reason for using salts is
  as follows: If an attacker wants to crack the password for a single
  LUKS container, then every possible passphrase has to be tried. 
  Typically an attacker will not try every binary value, but will try
  words and sentences from a dictionary.

  If an attacker wants to attack several LUKS containers with the same
  dictionary, then a different approach makes sense: Compute the
  resulting slot-key for each dictionary element and store it on disk. 
  Then the test for each entry is just the slow unlocking with the slot
  key (say 0.00001 sec) instead of calculating the slot-key first (1
  sec).  For a single attack, this does not help.  But if you have more
  than one container to attack, this helps tremendously, also because
  you can prepare your table before you even have the container to
  attack!  The calculation is also very simple to parallelize.  You
  could, for example, use the night-time unused CPU power of your
  desktop PCs for this.
Arno Wagner's avatar
Arno Wagner committed
1347 1348

  This is where the salt comes in. If the salt is combined with the
1349 1350 1351
  passphrase (in the simplest form, just appended to it), you suddenly
  need a separate table for each salt value.  With a reasonably-sized
  salt value (256 bit, e.g.) this is quite infeasible.
Arno Wagner's avatar
Arno Wagner committed
1352

Arno Wagner's avatar
Arno Wagner committed
1353

1354
  * 5.9 Is LUKS secure with a low-entropy (bad) passphrase?
Arno Wagner's avatar
Arno Wagner committed
1355

1356
  Note: You should only use the 94 printable characters from 7 bit
1357 1358 1359
  ASCII code to prevent your passphrase from failing when the character
  encoding changes, e.g.  because of a system upgrade, see also the
  note at the very start of this FAQ under "WARNINGS".
1360

Arno Wagner's avatar
Arno Wagner committed
1361 1362
  This needs a bit of theory. The quality of your passphrase is
  directly related to its entropy (information theoretic, not
1363 1364
  thermodynamic).  The entropy says how many bits of "uncertainty" or
  "randomness" are in you passphrase.  In other words, that is how
Arno Wagner's avatar
Arno Wagner committed
1365 1366 1367
  difficult guessing the passphrase is.

  Example: A random English sentence has about 1 bit of entropy per
1368 1369
  character.  A random lowercase (or uppercase) character has about 4.7
  bit of entropy.
Arno Wagner's avatar
Arno Wagner committed
1370 1371 1372 1373 1374

  Now, if n is the number of bits of entropy in your passphrase and t
  is the time it takes to process a passphrase in order to open the
  LUKS container, then an attacker has to spend at maximum

1375 1376
    attack_time_max = 2^n * t

Arno Wagner's avatar
Arno Wagner committed
1377
  time for a successful attack and on average half that. There is no
1378
  way getting around that relationship.  However, there is one thing
Arno Wagner's avatar
Arno Wagner committed
1379 1380 1381 1382
  that does help, namely increasing t, the time it takes to use a
  passphrase, see next FAQ item.

  Still, if you want good security, a high-entropy passphrase is the
1383
  only option.  For example, a low-entropy passphrase can never be
Arno Wagner's avatar
Arno Wagner committed
1384
  considered secure against a TLA-level (Three Letter Agency level,
1385 1386
  i.e.  government-level) attacker, no matter what tricks are used in
  the key-derivation function.  Use at least 64 bits for secret stuff. 
Arno Wagner's avatar
Arno Wagner committed
1387 1388
  That is 64 characters of English text (but only if randomly chosen)
  or a combination of 12 truly random letters and digits.
Arno Wagner's avatar
Arno Wagner committed
1389 1390 1391

  For passphrase generation, do not use lines from very well-known
  texts (religious texts, Harry potter, etc.) as they are to easy to
1392 1393 1394 1395 1396 1397 1398
  guess.  For example, the total Harry Potter has about 1'500'000 words
  (my estimation).  Trying every 64 character sequence starting and
  ending at a word boundary would take only something like 20 days on a
  single CPU and is entirely feasible.  To put that into perspective,
  using a number of Amazon EC2 High-CPU Extra Large instances (each
  gives about 8 real cores), this test costs currently about 50USD/EUR,
  but can be made to run arbitrarily fast.
Arno Wagner's avatar
Arno Wagner committed
1399 1400

  On the other hand, choosing 1.5 lines from, say, the Wheel of Time
1401 1402 1403 1404
  is in itself not more secure, but the book selection adds quite
  a bit of entropy. (Now that I have mentioned it here, don't use
  tWoT either!) If you add 2 or 3 typos or switch some words around,
  then this is good passphrase material.
Arno Wagner's avatar
Arno Wagner committed
1405

Arno Wagner's avatar
Arno Wagner committed
1406

1407
  * 5.10 What is "iteration count" and why is decreasing it a bad idea?
Arno Wagner's avatar
Arno Wagner committed
1408 1409

  Iteration count is the number of PBKDF2 iterations a passphrase is
1410 1411 1412
  put through before it is used to unlock a key-slot.  Iterations are
  done with the explicit purpose to increase the time that it takes to
  unlock a key-slot.  This provides some protection against use of
Arno Wagner's avatar
Arno Wagner committed
1413 1414
  low-entropy passphrases.

1415
  The idea is that an attacker has to try all possible passphrases. 
Arno Wagner's avatar
Arno Wagner committed
1416
  Even if the attacker knows the passphrase is low-entropy (see last
1417
  item), it is possible to make each individual try take longer.  The
Arno Wagner's avatar
Arno Wagner committed
1418
  way to do this is to repeatedly hash the passphrase for a certain
1419 1420
  time.  The attacker then has to spend the same time (given the same
  computing power) as the user per try.  With LUKS, the default is 1
Arno Wagner's avatar
Arno Wagner committed
1421 1422 1423
  second of PBKDF2 hashing.

  Example 1: Lets assume we have a really bad passphrase (e.g. a
1424 1425 1426 1427
  girlfriends name) with 10 bits of entropy.  With the same CPU, an
  attacker would need to spend around 500 seconds on average to break
  that passphrase.  Without iteration, it would be more like 0.0001
  seconds on a modern CPU.
Arno Wagner's avatar
Arno Wagner committed
1428 1429

  Example 2: The user did a bit better and has 32 chars of English
1430
  text.  That would be about 32 bits of entropy.  With 1 second
Arno Wagner's avatar
Arno Wagner committed
1431
  iteration, that means an attacker on the same CPU needs around 136
1432
  years.  That is pretty impressive for such a weak passphrase. 
Arno Wagner's avatar
Arno Wagner committed
1433 1434 1435 1436
  Without the iterations, it would be more like 50 days on a modern
  CPU, and possibly far less.

  In addition, the attacker can both parallelize and use special
1437
  hardware like GPUs or FPGAs to speed up the attack.  The attack can
Arno Wagner's avatar
Arno Wagner committed
1438
  also happen quite some time after the luksFormat operation and CPUs
1439 1440 1441 1442 1443 1444 1445 1446 1447
  can have become faster and cheaper.  For that reason you want a bit
  of extra security.  Anyways, in Example 1 your are screwed.  In
  example 2, not necessarily.  Even if the attack is faster, it still
  has a certain cost associated with it, say 10000 EUR/USD with
  iteration and 1 EUR/USD without iteration.  The first can be
  prohibitively expensive, while the second is something you try even
  without solid proof that the decryption will yield something useful.

  The numbers above are mostly made up, but show the idea.  Of course
Arno Wagner's avatar
Arno Wagner committed
1448 1449
  the best thing is to have a high-entropy passphrase.

1450 1451 1452 1453 1454 1455 1456 1457
  Would a 100 sec iteration time be even better? Yes and no. 
  Cryptographically it would be a lot better, namely 100 times better. 
  However, usability is a very important factor for security technology
  and one that gets overlooked surprisingly often.  For LUKS, if you
  have to wait 2 minutes to unlock the LUKS container, most people will
  not bother and use less secure storage instead.  It is better to have
  less protection against low-entropy passphrases and people actually
  use LUKS, than having them do without encryption altogether.
Arno Wagner's avatar
Arno Wagner committed
1458 1459 1460

  Now, what about decreasing the iteration time? This is generally a
  very bad idea, unless you know and can enforce that the users only
1461 1462 1463 1464 1465 1466 1467
  use high-entropy passphrases.  If you decrease the iteration time
  without ensuring that, then you put your users at increased risk, and
  considering how rarely LUKS containers are unlocked in a typical
  work-flow, you do so without a good reason.  Don't do it.  The
  iteration time is already low enough that users with entropy low
  passphrases are vulnerable.  Lowering it even further increases this
  danger significantly.
Arno Wagner's avatar
Arno Wagner committed
1468

Arno Wagner's avatar
Arno Wagner committed
1469

1470
  * 5.11 Some people say PBKDF2 is insecure?
Debian User's avatar
Debian User committed
1471 1472

  There is some discussion that a hash-function should have a "large
1473 1474 1475 1476