cryptsetup


SYNOPSIS
       cryptsetup <options> <action> <action args>

DESCRIPTION
       cryptsetup is used to conveniently setup dm-crypt managed device-mapper
       mappings. These include plain dm-crypt volumes and  LUKS  volumes.  The
       difference is that LUKS uses a metadata header and can hence offer more
       features than plain dm-crypt. On the other hand, the header is  visible
       and vulnerable to damage.

PLAIN DM-CRYPT OR LUKS?
       Unless  you  understand  the  cryptographic  background well, use LUKS.
       With plain dm-crypt there are a number of  possible  user  errors  that
       massively  decrease  security.  While  LUKS cannot fix them all, it can
       lessen the impact for many of them.

WARNINGS
       A lot of good information on the risks of using encrypted  storage,  on
       handling  problems  and  on security aspects can be found in the Crypt-
       setup FAQ. Read it. Nonetheless, some risks  deserve  to  be  mentioned
       here.

       Backup: Storage media die. Encryption has no influence on that.  Backup
       is mandatory for encrypted data as well, if the data has any worth. See
       the  Cryptsetup FAQ for advice on how to do backup of an encrypted vol-
       ume.

       Character encoding: If you enter a passphrase with special symbols, the
       passphrase  can  change depending character encoding. Keyboard settings
       can also change, which can make blind input  hard  or  impossible.  For
       example, switching from some ASCII 8-bit variant to UTF-8 can lead to a
       different binary encoding and hence different passphrase seen by crypt-
       setup,  even if what you see on the terminal is exactly the same. It is
       therefore highly recommended to select passphrase characters only  from
       7-bit  ASCII,  as  the  encoding for 7-bit ASCII stays the same for all
       ASCII variants and UTF-8.

       LUKS header: If the header of a LUKS volume gets damaged, all  data  is
       permanently  lost  unless  you  have a header-backup.  If a key-slot is
       damaged, it can only be restored from a  header-backup  or  if  another
       active  key-slot with known passphrase is undamaged.  Damaging the LUKS
       header is something people manage to do with surprising frequency. This
       risk  is the result of a trade-off between security and safety, as LUKS
       is designed for fast and secure wiping by just overwriting  header  and
       key-slot area.

       Previously used partitions: If a partition was previously used, it is a
       very good idea to wipe filesystem signatures, data, etc. before  creat-
       ing  a  LUKS or plain dm-crypt container on it.  For a quick removal of
       filesystem signatures, use "wipefs". Take care though that this may not
       remove  everything.  In particular md (RAID) signatures at the end of a
       device may survive. It also does not remove  data.  For  a  full  wipe,
       overwrite  the whole partition before container creation. If you do not
              For backward compatibility there are open command aliases:

              create: open --type plain <device> <name> switched arguments)
              plainOpen: open --type plain
              luksOpen: open --type luks
              loopaesOpen: open --type loopaes
              tcryptOpen: open --type tcrypt

              <options> are type specific and are described below for individ-
              ual device types.

       close <name>

              Removes  the existing mapping <name> and wipes the key from ker-
              nel memory.

              For backward compatibility  there  are  close  command  aliases:
              remove,  plainClose,  luksClose,  loopaesClose, tcryptClose (all
              behaves exactly the same, device type  is  determined  automati-
              cally from active device).

       status <name>

              Reports the status for the mapping <name>.

       resize <name>

              Resizes an active mapping <name>.

              If  --size (in sectors) is not specified, the size of the under-
              lying block device is used. Note that this does not  change  the
              raw device geometry, it just changes how many sectors of the raw
              device are represented in the mapped device.

PLAIN MODE
       Plain dm-crypt encrypts the device sector-by-sector with a single, non-
       salted  hash of the passphrase. No checks are performed, no metadata is
       used. There is no formatting operation.  When the raw device is  mapped
       (created),  the  usual  device  operations  can  be  used on the mapped
       device, including filesystem creation.  Mapped devices  usually  reside
       in /dev/mapper/<name>.

       The following are valid plain device type actions:

       open --type plain <device> <name>
       create <name> <device> (OBSOLETE syntax)

              Creates a mapping with <name> backed by device <device>.

              <options>  can be [--hash, --cipher, --verify-passphrase, --key-
              file, --keyfile-offset, --key-size,  --offset,  --skip,  --size,
              --readonly, --shared, --allow-discards]

              Example:  'cryptsetup  open --type plain /dev/sda10 e1' maps the

       device anymore, but has a LUKS container stored in it at an offset.

       LUKS  can  manage multiple passphrases that can be individually revoked
       or changed and that can be securely scrubbed from persistent media  due
       to  the use of anti-forensic stripes. Passphrases are protected against
       brute-force and dictionary attacks by  PBKDF2,  which  implements  hash
       iteration and salting in one function.

       Each passphrase, also called a key in this document, is associated with
       one of 8 key-slots.  Key operations that do not specify a  slot  affect
       the  first slot that matches the supplied passphrase or the first empty
       slot if a new passphrase is added.

       The following are valid LUKS actions:

       luksFormat <device> [<key file>]

              Initializes a LUKS partition and  sets  the  initial  passphrase
              (for  key-slot  0), either via prompting or via <key file>. Note
              that if the second argument is present, then the  passphrase  is
              taken  from  the  file  given there, without the need to use the
              --key-file option. Also note that for both forms of reading  the
              passphrase  from  file  you  can  give  '-'  as file name, which
              results in the passphrase being read from stdin and the  safety-
              question being skipped.

              You  can  only  call  luksFormat  on  a  LUKS device that is not
              mapped.

              <options> can  be  [--cipher,  --verify-passphrase,  --key-size,
              --key-slot,  --key-file  (takes  precedence over optional second
              argument),  --keyfile-offset,  --keyfile-size,  --use-random   |
              --use-urandom, --uuid, --master-key-file].

              WARNING:  Doing  a luksFormat on an existing LUKS container will
              make all  data  the  old  container  permanently  irretrievable,
              unless you have a header backup.

       open --type luks <device> <name>
       luksOpen <device> <name> (old syntax)

              Opens  the  LUKS  device  <device>  and sets up a mapping <name>
              after successful verification of the  supplied  passphrase.   If
              the  passphrase  is  not  supplied  via  --key-file, the command
              prompts for it interactively.

              The <device> parameter can be also specified by LUKS UUID in the
              format  UUID=<uuid>,  which  uses  the symlinks in /dev/disk/by-
              uuid.

              <options> can be [--key-file, --keyfile-offset,  --keyfile-size,
              --readonly,   --test-passphrase,   --allow-discards,   --header,
              --key-slot, --master-key-file].


              <options> can be [--header].

       luksResume <name>

              Resumes  a  suspended  device and reinstates the encryption key.
              Prompts interactively for a  passphrase  if  --key-file  is  not
              given.

              <options> can be [--key-file, --keyfile-size, --header]

       luksAddKey <device> [<key file with new key>]

              adds  a  new passphrase. An existing passphrase must be supplied
              interactively or via --key-file.  The new passphrase to be added
              can  be  specified  interactively or read from the file given as
              positional argument.

              <options> can be [--key-file, --keyfile-offset,  --keyfile-size,
              --new-keyfile-offset,  --new-keyfile-size, --key-slot, --master-
              key-file].

       luksRemoveKey <device> [<key file with passphrase to be removed>]

              Removes the  supplied  passphrase  from  the  LUKS  device.  The
              passphrase  to  be  removed  can  be specified interactively, as
              positional argument or via --key-file.

              <options> can be [--key-file, --keyfile-offset, --keyfile-size]

              WARNING: If you read the passphrase from stdin (without  further
              argument or with '-' as argument to --key-file), batch-mode (-q)
              will be implicitely switched on and no  warning  will  be  given
              when  you  remove the last remaining passphrase from a LUKS con-
              tainer. Removing the last passphrase makes  the  LUKS  container
              permanently inaccessible.

       luksChangeKey <device> [<new key file>]

              Changes  an  existing  passphrase.  The passphrase to be changed
              must be supplied  interactively  or  via  --key-file.   The  new
              passphrase  can  be supplied interactively or in a file given as
              positional argument.

              If a key-slot is specified (via --key-slot), the passphrase  for
              that  key-slot  must  be given and the new passphrase will over-
              write the specified key-slot. If no key-slot  is  specified  and
              there  is still a free key-slot, then the new passphrase will be
              put into a free key-slot before the key-slot containing the  old
              passphrase  is  purged.  If  there is no free key-slot, then the
              key-slot with the old passphrase is overwritten directly.

              WARNING: If a key-slot is overwritten, a  media  failure  during
              this  operation  can  cause  the overwrite to fail after the old
              Removing the last passphrase makes a LUKS container  permanently
              inaccessible.

              <options> can be [--key-file, --keyfile-offset, --keyfile-size].

              WARNING:  If you read the passphrase from stdin (without further
              argument or with '-' as argument to --key-file), batch-mode (-q)
              will  be  implicitely  switched  on and no warning will be given
              when you remove the last remaining passphrase from a  LUKS  con-
              tainer.  Removing  the  last passphrase makes the LUKS container
              permanently inaccessible.

       luksUUID <device>

              Print the UUID of a LUKS device.
              Set new UUID if --uuid option is specified.

       isLuks <device>

              Returns true, if <device> is a  LUKS  device,  false  otherwise.
              Use  option -v to get human-readable feedback. 'Command success-
              ful.'  means the device is a LUKS device.

       luksDump <device>

              Dump the header information of a LUKS device.

              If the --dump-master-key option is used, the LUKS device  master
              key  is dumped instead of the keyslot info. Beware that the mas-
              ter key cannot be changed and can be used to  decrypt  the  data
              stored in the LUKS container without a passphrase and even with-
              out the LUKS header. This means that if the master key  is  com-
              promised,  the  whole device has to be erased to prevent further
              access. Use this option carefully.

              In order to dump the master key, a passphrase  has  to  be  sup-
              plied, either interactively or via --key-file.

              <options>  can be [--dump-master-key, --key-file, --keyfile-off-
              set, --keyfile-size].

              WARNING: If --dump-master-key is used with  --key-file  and  the
              argument  to  --key-file  is '-', no validation question will be
              asked and no warning given.

       luksHeaderBackup <device> --header-backup-file <file>

              Stores a binary backup of the LUKS header and keyslot area.
              Note: Using '-' as filename writes the header backup to  a  file
              named '-'.

              WARNING:  This backup file and a passphrase valid at the time of
              backup allows decryption of the LUKS  data  area,  even  if  the
              passphrase  was  later  changed or removed from the LUKS device.
              named '-'.

              WARNING:   Header  and  keyslots  will  be  replaced,  only  the
              passphrases from the backup will work afterwards.

              This command requires that the master key size and  data  offset
              of  the  LUKS  header  already  on  the device and of the header
              backup match. Alternatively, if there is no LUKS header  on  the
              device, the backup will also be written to it.

loop-AES EXTENSION
       cryptsetup  supports  mapping loop-AES encrypted partition using a com-
       patibility mode.

       open --type loopaes <device> <name> --key-file <keyfile>
       loopaesOpen <device> <name> --key-file <keyfile>  (old syntax)

              Opens the loop-AES <device> and sets up a mapping <name>.

              If the key file is encrypted with GnuPG, then you  have  to  use
              --key-file=- and decrypt it before use, e.g. like this:
              gpg  --decrypt  <keyfile>  | cryptsetup loopaesOpen --key-file=-
              <device> <name>

              Use --keyfile-size to specify the proper key length if needed.

              Use --offset to specify device offset. Note that the units  need
              to be specified in number of 512 byte sectors.

              Use --skip to specify the IV offset. If the original device used
              an offset and but did not use it in IV sector calculations,  you
              have to explicitly use --skip 0 in addition to the offset param-
              eter.

              Use --hash to override the default hash function for  passphrase
              hashing (otherwise it is detected according to key size).

              <options>  can  be  [--key-file,  --key-size,  --offset, --skip,
              --hash, --readonly, --allow-discards].

       See also section 7 of the FAQ and  http://loop-aes.sourceforge.net  for
       more information regarding loop-AES.

TCRYPT (TrueCrypt-compatible) EXTENSION
       cryptsetup  supports mapping of TrueCrypt or tcplay encrypted partition
       using a native Linux kernel API.  Header formatting and  TCRYPT  header
       change  is  not  supported,  cryptsetup never changes TCRYPT header on-
       device.

       TCRYPT extension requires kernel userspace crypto API to  be  available
       (introduced  in  Linux  kernel  2.6.38).  If you are configuring kernel
       yourself, enable "User-space interface for symmetric key  cipher  algo-
       rithms"  in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .con-
       fig option).
       The  tcryptDump  command  should work for all recognized TCRYPT devices
       and doesn't require superuser privilege.

       To map system device (device with boot loader where the whole encrypted
       system  resides)  use  --tcrypt-system option. Use the whole device not
       the system partition as the device parameter.

       To use hidden  header  (and  map  hidden  device,  if  available),  use
       --tcrypt-hidden option.

       open --type tcrypt <device> <name>
       tcryptOpen <device> <name>  (old syntax)

              Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a
              mapping <name>.

              <options> can be [--key-file, --tcrypt-hidden,  --tcrypt-system,
              --readonly, --test-passphrase].

              The  keyfile  parameter  allows combination of file content with
              the passphrase and can be repeated. Note that using keyfiles  is
              compatible with TCRYPT and is different from LUKS keyfile logic.

       tcryptDump <device>

              Dump the header information of a TCRYPT device.

              If  the --dump-master-key option is used, the TCRYPT device mas-
              ter key is dumped instead of TCRYPT header info. Beware that the
              master key (or concatenated master keys if cipher chain is used)
              can be used to decrypt the data stored in the  TCRYPT  container
              without a passphrase.  This means that if the master key is com-
              promised, the whole device has to be erased to  prevent  further
              access. Use this option carefully.

              <options>  can  be [--dump-master-key, --key-file, --tcrypt-hid-
              den, --tcrypt-system].

              The keyfile parameter allows combination of  file  content  with
              the passphrase and can be repeated.

       See  also http://www.truecrypt.org for more information regarding True-
       Crypt.

       Please note that cryptsetup does not use TrueCrypt code, please  report
       all  problems  related  to  this  compatibility extension to cryptsetup
       project.

MISCELLANEOUS
       repair <device>

              Tries to repair the device metadata if possible. Currently  sup-
              ported only for LUKS device type.


              To benchmark  other  ciphers  or  modes,  you  need  to  specify
              --cipher and --key-size options or --hash for KDF test.

              NOTE:  This  benchmark is using memory only and is only informa-
              tive.  You cannot directly predict real storage encryption speed
              from it.

              For  testing  block  ciphers,  this  benchmark  requires  kernel
              userspace crypto API to be available (introduced in Linux kernel
              2.6.38).   If you are configuring kernel yourself, enable "User-
              space interface for symmetric key cipher algorithms" in "Crypto-
              graphic API" section (CRYPTO_USER_API_SKCIPHER .config option).

              <options> can be [--cipher, --key-size, --hash].

OPTIONS
       --verbose, -v
              Print more information on command execution.

       --debug
              Run  in debug mode with full diagnostic logs. Debug output lines
              are always prefixed by '#'.

       --hash, -h <hash-spec>
              Specifies the passphrase hash for open (for  plain  and  loopaes
              device types).

              Specifies  the hash used in the LUKS key setup scheme and volume
              key digest for luksFormat.

              The specified hash name is  passed  to  the  compiled-in  crypto
              backend.   Different backends may support different hashes.  For
              luksFormat, the hash algorithm must provide at least 160 bits of
              output,  which excludes, e.g., MD5. Do not use a non-crypto hash
              like "crc32" as this breaks security.

              Values compatible with old version of cryptsetup are "ripemd160"
              for open --type plain and "sha1" for luksFormat.

              Use cryptsetup --help to show the defaults.

       --cipher, -c <cipher-spec>
              Set the cipher specification string.

              cryptsetup  --help  shows the compiled-in defaults.  The current
              default in the distributed sources is "aes-cbc-essiv:sha256" for
              both plain dm-crypt and LUKS.

              For XTS mode (a possible future default), use "aes-xts-plain" or
              better "aes-xts-plain64" as cipher specification and  optionally
              set  a key size of 512 bits with the -s option. Key size for XTS
              mode is twice that for other modes for the same security level.


              If  the name given is "-", then the passphrase will be read from
              stdin.  In this case, reading will not stop at  newline  charac-
              ters.

              With  LUKS,  passphrases  supplied via --key-file are always the
              existing passphrases requested by a command, except in the  case
              of  luksFormat  where --key-file is equivalent to the positional
              key file argument.

              If you want to set a new passphrase via key file,  you  have  to
              use a positional argument to luksAddKey.

              See section NOTES ON PASSPHRASE PROCESSING for more information.

       --keyfile-offset value
              Skip  value  bytes at the beginning of the key file.  Works with
              all commands that accepts key files.

       --keyfile-size, -l value
              Read a maximum of value bytes from the key file.  Default is  to
              read  the  whole  file up to the compiled-in maximum that can be
              queried with --help. Supplying more data  than  the  compiled-in
              maximum aborts the operation.

              This  option is useful to cut trailing newlines, for example. If
              --keyfile-offset is also given, the size count starts after  the
              offset.  Works with all commands that accepts key files.

       --new-keyfile-offset value
              Skip  value bytes at the start when adding a new passphrase from
              key file with luksAddKey.

       --new-keyfile-size  value
              Read a maximum of value bytes when adding a new passphrase  from
              key  file with luksAddKey.  Default is to read the whole file up
              to the compiled-in maximum  length  that  can  be  queried  with
              --help.   Supplying more than the compiled in maximum aborts the
              operation.  When --new-keyfile-offset  is  also  given,  reading
              starts after the offset.

       --master-key-file
              Use a master key stored in a file.

              For luksFormat this allows creating a LUKS header with this spe-
              cific master key. If the master key was taken from  an  existing
              LUKS  header and all other parameters are the same, then the new
              header decrypts the data encrypted with the  header  the  master
              key was taken from.

              For  luksAddKey this allows adding a new passphrase without hav-
              ing to know an exiting one.

              For open this allows to open the LUKS device  without  giving  a
              long-term key).

              See  NOTES ON RANDOM NUMBER GENERATORS for more information. Use
              cryptsetup --help to show the compiled-in default random  number
              generator.

              WARNING:  In  a  low-entropy situation (e.g. in an embedded sys-
              tem), both selections are problematic.  Using  /dev/urandom  can
              lead  to  weak  keys.   Using /dev/random can block a long time,
              potentially forever, if not enough entropy can be  harvested  by
              the kernel.

       --key-slot, -S <0-7>
              For  LUKS  operations that add key material, this options allows
              you to specify which key slot is selected for the new key.  This
              option can be used for luksFormat, and luksAddKey.
              In  addition,  for open, this option selects a specific key-slot
              to compare the passphrase  against.   If  the  given  passphrase
              would only match a different key-slot, the operation fails.

       --key-size, -s <bits>
              Sets  key  size in bits. The argument has to be a multiple of 8.
              The possible key-sizes are limited by the cipher and mode used.

              See /proc/crypto for more information.  Note  that  key-size  in
              /proc/crypto is stated in bytes.

              This  option  can  be  used for open --type plain or luksFormat.
              All other LUKS actions will use the key-size  specified  in  the
              LUKS  header.   Use  cryptsetup  --help  to show the compiled-in
              defaults.

       --size, -b <number of 512 byte sectors>
              Force the size of the underlying device in sectors of 512 bytes.
              This option is only relevant for the open and resize actions.

       --offset, -o <number of 512 byte sectors>
              Start  offset  in  the backend device in 512-byte sectors.  This
              option is only relevant  for  the  open  action  with  plain  or
              loopaes device types.

       --skip, -p <number of 512 byte sectors>
              How many sectors of the encrypted data to skip at the beginning.
              This option is only relevant for the open action with  plain  or
              loopaes device types.

              This  is different from the --offset options with respect to the
              sector numbers used in  IV  calculation.   Using  --offset  will
              shift the IV calculation by the same negative amount.  Hence, if
              --offset n, sector n will get a sector number of 0  for  the  IV
              calculation.   Using --skip causes sector n to also be the first
              sector of the mapped device, but with its number for IV  genera-
              tion is n.

              set or change passphrases, such  as  luksFormat  or  luksAddKey.
              Specifying 0 as parameter selects the compiled-in default.

       --batch-mode, -q
              Suppresses all confirmation questions. Use with care!

              If the -y option is not specified, this option also switches off
              the passphrase verification for luksFormat.

       --timeout, -t <number of seconds>
              The number of seconds to wait before timeout on passphrase input
              via  terminal.  It is relevant every time a passphrase is asked,
              for example for open,  luksFormat  or  luksAddKey.   It  has  no
              effect if used in conjunction with --key-file.
              This  option  is  useful when the system should not stall if the
              user does not input a passphrase, e.g. during boot. The  default
              is a value of 0 seconds, which means to wait forever.

       --tries, -T
              How  often  the  input of the passphrase shall be retried.  This
              option is relevant every time a passphrase is asked, for example
              for open, luksFormat or luksAddKey.  The default is 3 tries.

       --align-payload <number of 512 byte sectors>
              Align  payload  at  a  boundary of value 512-byte sectors.  This
              option is relevant for luksFormat.

              If not specified, cryptsetup tries to use the topology info pro-
              vided  by kernel for the underlying device to get optimal align-
              ment.  If not available (or the calculated value is  a  multiple
              of  the  default)  data is by default aligned to a 1MiB boundary
              (i.e. 2048 512-byte sectors).

              For a detached LUKS header this option specifies the  offset  on
              the data device. See also the --header option.

       --uuid=UUID
              Use the provided UUID for the luksFormat command instead of gen-
              erating new one. Changes the existing UUID when  used  with  the
              luksUUID command.

              The  UUID  must  be  provided  in the standard UUID format, e.g.
              12345678-1234-1234-1234-123456789abc.

       --allow-discards
              Allow the use of  discard  (TRIM)  requests  for  device.   This
              option is only relevant for open action.

              WARNING:  This  command  can  have  a  negative  security impact
              because it can make filesystem-level operations visible  on  the
              physical  device.  For  example,  information leaking filesystem
              type, used space, etc. may  be  extractable  from  the  physical
              device  if  the  discarded  blocks  can  be located later. If in
              doubt, do no use it.
              and LUKS header on different devices.

              This  option  is  only relevant for LUKS devices and can be used
              with the luksFormat, open, luksSuspend, luksResume,  status  and
              resize commands.

              For  luksFormat with a file name as argument to --header, it has
              to exist and be large enough to contain the  LUKS  header.   See
              the cryptsetup FAQ for header size calculation.

              For  other  commands  that change the LUKS header (e.g. luksAdd-
              Key), specify the device or file with the LUKS  header  directly
              as the LUKS device.

              If  used with luksFormat, the --align-payload option is taken as
              absolute sector alignment on ciphertext device and can be zero.

              WARNING: There is no check whether the ciphertext device  speci-
              fied actually belongs to the header given. In fact you can spec-
              ify an arbitrary device as the ciphertext device for  open  with
              the --header option. Use with care.

       --force-password
              Do not use password quality checking for new LUKS passwords.

              This   option   applies   only  to  luksFormat,  luksAddKey  and
              luksChangeKey and is ignored  if  cryptsetup  is  built  without
              password quality checking support.

              For  more info about password quality check, see manual page for
              pwquality.conf(5).

       --version
              Show the program version.

       --usage
              Show short option help.

       --help, -?
              Show help text and default parameters.

RETURN CODES
       Cryptsetup returns 0 on success and a non-zero value on error.

       Error codes are: 1 wrong parameters, 2 no permission (bad  passphrase),
       3  out  of memory, 4 wrong device specified, 5 device already exists or
       device is busy.

NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
       Note that no iterated hashing or salting is done  in  plain  mode.   If
       hashing  is  done,  it  is  a  single direct hash. This means that low-
       entropy passphrases are easy to attack in plain mode.

       From a terminal: The passphrase is read until the first  newline,  i.e.
       the used cipher, or the size specified with -s.

       Note  that  if  --key-file=-  is  used  for reading the key from stdin,
       trailing newlines are not stripped from the input.

       If "plain" is used as argument to --hash, the input data  will  not  be
       hashed.  Instead, it will be zero padded (if shorter than the key size)
       or truncated (if longer than the key size) and  used  directly  as  the
       binary  key.  This  is useful for directly specifying a binary key.  No
       warning will be given if the amount of data read  from  stdin  is  less
       than the key size.

       From  a  key  file:  It  will  be truncated to the key size of the used
       cipher or the size given by -s and directly used as binary key.  if the
       key file is shorter than the key, cryptsetup will quit with an error.


NOTES ON PASSPHRASE PROCESSING FOR LUKS
       LUKS uses PBKDF2 to protect against dictionary attacks and to give some
       protection to low-entropy passphrases (see RFC 2898 and the  cryptsetup
       FAQ).

       From  a  terminal:  The  passphrase is read until the first newline and
       then processed by PBKDF2 without the newline character.

       From stdin: LUKS will read passphrases from stdin up to the first  new-
       line  character  or  the compiled-in maximum key file length. If --key-
       file-size is given, it is ignored.

       From key file: The complete keyfile is read up to the compiled-in maxi-
       mum size. Newline characters do not terminate the input. The --keyfile-
       size option can be used to limit what is read.

       Passphrase processing: Whenever a passphrase is added to a LUKS  header
       (luksAddKey,  luksFormat),  the  user may specify how much the time the
       passphrase processing should consume. The time is used to determine the
       iteration  count  for PBKDF2 and higher times will offer better protec-
       tion for low-entropy passphrases, but open will  take  longer  to  com-
       plete.  For  passphrases  that  have  entropy  higher than the used key
       length, higher iteration times will not increase security.

       The default setting of one second  is  sufficient  for  most  practical
       cases.  The  only  exception is a low-entropy passphrase used on a slow
       device.

INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
       LUKS checks for a valid  passphrase  when  an  encrypted  partition  is
       unlocked.  The behavior of plain dm-crypt is different.  It will always
       decrypt with the passphrase given. If the given  passphrase  is  wrong,
       the  device  mapped  by  plain  dm-crypt will essentially still contain
       encrypted data and will be unreadable.

NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
       The available combinations of ciphers,  modes,  hashes  and  key  sizes
       LUKS, as it's only possible with LUKS  to  have  multiple  passphrases.
       Still,  if  your  attacker  model  does  not  prevent  it, storing your
       passphrase in a sealed envelope somewhere may be a good idea as well.

NOTES ON RANDOM NUMBER GENERATORS
       Random Number Generators (RNG) used in cryptsetup are always the kernel
       RNGs without any modifications or additions to data stream produced.

       There  are  two  types  of  randomness  cryptsetup/LUKS needs. One type
       (which always uses /dev/urandom) is used for salts, the AF splitter and
       for wiping deleted keyslots.

       The  second  type  is  used for the volume (master) key. You can switch
       between using /dev/random and /dev/urandom  here, see --use-random  and
       --use-urandom  options.  Using  /dev/random  on a system without enough
       entropy sources can cause  luksFormat  to  block  until  the  requested
       amount of random data is gathered. In a low-entropy situation (embedded
       system), this can take a very long time and potentially forever. At the
       same  time,  using /dev/urandom in a low-entropy situation will produce
       low-quality keys. This is a serious problem, but solving it is  out  of
       scope for a mere man-page.  See urandom(4) for more information.

NOTES ON LOOPBACK DEVICE USE
       Cryptsetup  is  usually used directly on a block device (disk partition
       or LVM volume). However, if the device argument is a  file,  cryptsetup
       tries  to  allocate  a  loopback device and map it into this file. This
       mode requires Linux kernel 2.6.25 or more  recent  which  supports  the
       loop  autoclear  flag  (loop  device is cleared on last close automati-
       cally). Of course, you can always map a file to a loop-device manually.
       See the cryptsetup FAQ for an example.

       When device mapping is active, you can see the loop backing file in the
       status command output. Also see losetup(8).

DEPRECATED ACTIONS
       The reload action is no longer supported.  Please use dmsetup(8) if you
       need to directly manipulate with the device mapping table.

       The luksDelKey was replaced with luksKillSlot.

REPORTING BUGS
       Report  bugs,  including  ones  in the documentation, on the cryptsetup
       mailing list at <dm-crypt@saout.de> or in the 'Issues' section on  LUKS
       website.   Please  attach  the  output  of  the failed command with the
       --debug option added.

AUTHORS
       cryptsetup originally written by Christophe Saout <christophe@saout.de>
       The LUKS extensions and original man page were written by Clemens Fruh-
       wirth <clemens@endorphin.org>.
       Man page extensions by Milan Broz <gmazyland@gmail.com>.
       Man page rewrite and extension by Arno Wagner <arno@wagner.name>.

COPYRIGHT

       The cryptsetup FAQ, contained in the distribution package and online at
       http://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions

       The cryptsetup mailing list and list archive, see FAQ entry 1.6.

       The    LUKS    on-disk    format     specification     available     at
       http://code.google.com/p/cryptsetup/wiki/Specification



cryptsetup                         May 2012                      CRYPTSETUP(8)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2018 Hurricane Electric. All Rights Reserved.