sync to Wiki

FAQ

@@ -51,7 +51,7 @@ A. Contributors
   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 decidedly
+  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
@@ -235,7 +235,6 @@ A. Contributors
   nothing and are sure you did not confirm, then you should look into a
   possible compromise of your email account.
 
-
   * 1.9 What can I do if cryptsetup is running out of memory?
 
   Memory issues are generally related to the key derivation function.  You may
@@ -262,7 +261,6 @@ A. Contributors
   Also, device mapper requires root access.  cryptsetup uses device mapper to 
   manage the decrypted container.
 
-
 2. Setup
 
   * 2.1 LUKS Container Setup mini-HOWTO
@@ -426,6 +424,14 @@ A. Contributors
   it in some other way.  The PC is just not set-up for a really secure
   boot-chain (whatever some people may claim).
 
+  That said, if you want an encrypted root partition, you have to store 
+  an initrd with cryptsetup somewhere else. The traditional approach is
+  to have a separate partition under /boot for that. You can also put that 
+  initrd on a bootable memory stick, bootable CD or bootable external
+  drive as well. The kernel and Grub typically go to the same location 
+  as that initrd. A minimal example what such an initrd can look like is 
+  given in Section 9.
+  
   (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
@@ -858,20 +864,26 @@ A. Contributors
      cryptsetup luksDump <device with LUKS container>
 
 ->   ...
-     Payload offset: <number>
+     Payload offset: <number> [of 512 byte sectors]
      ...
 
   02) Take the result number, multiply by 512 zeros and write to 
-      the start of the device, e.g. like this:
+      the start of the device, e.g. using one of the following alternatives:
 
      dd bs=512 count=<number> if=/dev/zero of=<device>
 
 
-  LUKS2:  (warning, untested!  Remember that backup?) This assumes the
+     head -c <number * 512> /dev/zero > /dev/<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
+  segment.  
+  01) Determine the data-segment offset using luksDump, same
       as above for LUKS1:
 
+     cryptsetup luksDump <device with LUKS container>
 ->   ...  
      Data segments:
         0: crypt
@@ -881,7 +893,7 @@ A. Contributors
   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>
+     head -c <number> /dev/zero > /dev/<device>
 
 
 3. Common Problems
@@ -996,7 +1008,7 @@ A. Contributors
   that is intact.
 
   In order to find out whether a key-slot is damaged one has to look for
-  "non-random looking" data in it.  There is a tool that automates this
+  "non-random looking" data in it.  There is a tool that automatizes this
   for LUKS1 in the cryptsetup distribution from version 1.6.0 onwards.  It
   is located in misc/keyslot_checker/.  Instructions how to use and how to
   interpret results are in the README file.  Note that this tool requires
@@ -1234,6 +1246,17 @@ A. Contributors
   countries like the US or the UK are not civilized and do not have fair
   laws.
 
+  As a side-note, standards for biometrics (fingerprint, retina, 
+  vein-pattern, etc.) are often different and much lower. If you put
+  your LUKS passphrase into a device that can be unlocked using biometrics,
+  they may force a biometric sample in many countries where they could not
+  force you to give them a passphrase you solely have in your memory and
+  can claim to have forgotten if needed (it happens). If you need protection
+  on this level, make sure you know what the respective legal situation is,
+  also while traveling, and make sure you decide beforehand what you
+  will do if push comes to shove as they will definitely put you under
+  as much pressure as they can legally apply. 
+
   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
@@ -1635,9 +1658,8 @@ A. Contributors
 
     cryptsetup -c aes-xts-plain64 luksFormat <device>
 
-  There is a potential security issue with XTS mode and blocks larger
-  than 2^20 bytes or so. LUKS and dm-crypt always use smaller blocks 
-  and the issue does not apply.
+  There is a potential security issue with XTS mode and large blocks. 
+  LUKS and dm-crypt always use 512B blocks and the issue does not apply.
 
 
   * 5.17 Is LUKS FIPS-140-2 certified?
@@ -2656,7 +2678,7 @@ offset  length  name                  data type  description
   safe under these circumstances, then you have bigger problems than this
   somewhat expected behavior.
 
-  The CVE was exaggerated and should not be assigned to upstream
+  The CVE was exagerrated and should not be assigned to upstream
   cryptsetup in the first place (it is a distro specific initrd issue). 
   It was driven more by a try to make a splash for self-aggrandizement,
   than by any actual security concerns.  Ignore it.
@@ -2980,9 +3002,24 @@ offset  length  name                  data type  description
   start of the device, nothing gets stored somewhere in the middle or at 
   the end. 
   
+  * 10.12 What is a LUKS2 Token?
+
+  A LUKS2 token is an object that describes "how to get a passphrase or 
+  key" to unlock particular keyslot. A LUKS2 token is stored as json data 
+  in the LUKS2 header. The token can be related to all keyslots or a 
+  specific one. As the token is stored in JSON formay it is text by 
+  default but binary data can be encoded into it according to the JSON 
+  conventions.
+ 
+  Documentation on the last changes to LUKS2 tokens can be found in the 
+  release notes. As of version 2.4 of cryptsetup, there are significant 
+  features. The standard documentation for working with tokens is 
+  in the luks2 reference available as PDF on the project page.
+
 
 11. References and Further Reading
 
+
   * Purpose of this Section
 
   The purpose of this section is to collect references to all materials