Provided by: cryptsetup-bin_1.6.6-5ubuntu2_i386 bug

NAME

       cryptsetup - manage plain dm-crypt and LUKS encrypted volumes

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.

       In  addition,  cryptsetup  provides  limited  support  for  the  use of
       historic loopaes volumes and for TruerCrypt compatible volumes.

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
       Cryptsetup  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
       volume.

       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
       cryptsetup, 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
       creating 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
       know how to to that, the cryptsetup FAQ describes several options.

BASIC COMMANDS

       The following are valid actions for all supported device types.

       open <device> <name> --type <device_type>

              Opens (creates a mapping with) <name> backed by device <device>.

              Device type can be plain, luks (default), loopaes or tcrypt.

              For backward compatibility there are open command aliases:

              create (argument-order <name> <device>): open --type plain
              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
              individual device types. For create, the order of the <name> and
              <device>  options  is inverted for historical reasons, all other
              aliases use the standard <device> <name> order.

       close <name>

              Removes the existing mapping  <name>  and  wipes  the  key  from
              kernel memory.

              For  backward  compatibility  there  are  close command aliases:
              remove, plainClose, luksClose,  loopaesClose,  tcryptClose  (all
              behaves   exactly   the   same,   device   type   is  determined
              automatically 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
              underlying  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
       (opened), 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)

              Opens (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
              raw encrypted device /dev/sda10 to the mapped (decrypted) device
              /dev/mapper/e1, which can then be mounted,  fsck-ed  or  have  a
              filesystem created on it.

LUKS EXTENSION

       LUKS,  the  Linux Unified Key Setup, is a standard for disk encryption.
       It adds a standardized header at the start of the  device,  a  key-slot
       area directly behind the header and the bulk data area behind that. The
       whole set is called  a  'LUKS  container'.   The  device  that  a  LUKS
       container resides on is called a 'LUKS device'.  For most purposes both
       terms can be used interchangeably. But note that when the  LUKS  header
       is  at  a  nonzero  offset  in  a device, then the device is not a LUKS
       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   [--hash,  --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,
              --iter-time, --header, --force-password].

              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].

       luksSuspend <name>

              Suspends an active device (all IO operations  will  blocked  and
              accesses  to  the  device  will wait indefinitely) and wipes the
              encryption key from kernel memory. Needs kernel 2.6.19 or later.

              After this operation you have to use luksResume to reinstate the
              encryption  key  and  unblock  the device or close to remove the
              mapped device.

              WARNING: never suspend the device on which the cryptsetup binary
              resides.

              <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, --iter-time, --force-password].

       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
              container. 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
              overwrite 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
              passphrase  has  been  wiped  and  make   the   LUKS   container
              inaccessible.

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

       luksKillSlot <device> <key slot number>

              Wipe  the  key-slot  number  <key  slot> from the LUKS device. A
              remaining passphrase must be supplied, either  interactively  or
              via --key-file.  This command can remove the last remaining key-
              slot, but requires an interactive confirmation  when  doing  so.
              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
              container. Removing the last passphrase makes the LUKS container
              permanently inaccessible.

       erase <device>
       luksErase <device>

              Erase  all  keyslots  and  make  the  LUKS container permanently
              inaccessible.  You do not need to provide any password for  this
              operation.

              WARNING: This operation is irreversible.

       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
              successful.'  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
              master key cannot be changed and can be used to decrypt the data
              stored in the LUKS  container  without  a  passphrase  and  even
              without  the  LUKS  header. This means that if the master key is
              compromised, 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
              supplied, either interactively or via --key-file.

              <options>     can     be     [--dump-master-key,     --key-file,
              --keyfile-offset, --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.
              Also  note  that  with  a  header backup you lose the ability to
              securely wipe the LUKS device by just overwriting the header and
              key-slots.  You either need to securely erase all header backups
              in addition or overwrite the encrypted data area as  well.   The
              second  option is less secure, as some sectors can survive, e.g.
              due to defect management.

       luksHeaderRestore <device> --header-backup-file <file>

              Restores a binary backup of the LUKS  header  and  keyslot  area
              from the specified file.
              Note:  Using '-' as filename reads the header backup from a file
              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
       compatibility 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
              parameter.

              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
       algorithms" in "Cryptographic  API"  section  (CRYPTO_USER_API_SKCIPHER
       .config option).

       Because  TCRYPT  header  is encrypted, you have to always provide valid
       passphrase and keyfiles.

       Cryptsetup should recognize all header variants, except  legacy  cipher
       chains  using LRW encryption mode with 64 bits encryption block (namely
       Blowfish in LRW mode is not recognized, this is  limitation  of  kernel
       crypto API).

       NOTE:  Activation  with  tcryptOpen is supported only for cipher chains
       using LRW or XTS encryption modes.

       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.   You  can  use  partition
       device  as  the parameter (parameter must be real partition device, not
       image in file), then only this partition is mapped.

       If you have whole TCRYPT device as a file image and  you  want  to  map
       multiple  partition  encrypted  with  system  encryption, please create
       loopback mapping with partitions first (losetup -P, see losetup(8)  man
       page for more info), and use loop partition as the device parameter.

       If  you  use  whole  base device as parameter, one device for the whole
       system encryption is mapped. This mode is available only  for  backward
       compatibility with older cryptsetup versions which mapped TCRYPT system
       encryption using whole device.

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

       To  explicitly  use  backup  (secondary)  header,  use  --tcrypt-backup
       option.

       NOTE: There is no protection for a hidden volume if the outer volume is
       mounted.  The  reason  is  that  if there were any protection, it would
       require some metadata describing what to protect in  the  outer  volume
       and the hidden volume would become detectable.

       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,
              --tcrypt-backup,    --readonly,    --test-passphrase,   --allow-
              discards].

              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.

              WARNING: Option --allow-discards cannot be combined with  option
              --tcrypt-hidden.  For normal mapping it can cause destruction of
              hidden volume (hidden volume appears as unused space  for  outer
              volume so this space can be discarded).

       tcryptDump <device>

              Dump the header information of a TCRYPT device.

              If  the  --dump-master-key  option  is  used,  the TCRYPT device
              master 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 compromised, the whole device has to be erased to prevent
              further access. Use this option carefully.

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

              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
       TrueCrypt.

       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
              supported only for LUKS device type.

              This  command  is  useful to fix some known benign LUKS metadata
              header corruptions. Only basic corruptions of unused keyslot are
              fixable.  This command will only change the LUKS header, not any
              key-slot data.

              WARNING: Always create a binary backup of  the  original  header
              before calling this command.

       benchmark <options>

              Benchmarks  ciphers  and KDF (key derivation function).  Without
              parameters it tries to measure few common configurations.

              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
              informative.   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
              "Cryptographic  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 is used as hash-
              parameter for PBKDF2 and for the AF splitter.

              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
              plain dm-crypt and "aes-xts-plain64" for LUKS.

              If  a  hash is part of the cipher spefification, then it is used
              as part of the IV generation. For example, ESSIV  needs  a  hash
              function, while "plain64" does not and hence none is specified.

              For  XTS mode you can 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.

              XTS  mode  requires  kernel 2.6.24 or later and plain64 requires
              kernel 2.6.33 or later. More information can  be  found  in  the
              FAQ.

       --verify-passphrase, -y
              When interactively asking for a passphrase, ask for it twice and
              complain if both inputs do not match. Advised  when  creating  a
              regular  mapping for the first time, or when running luksFormat.
              Ignored on input from file or stdin.

       --key-file, -d name
              Read the passphrase from file.

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

              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
              specific  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.

              WARNING: If you create your own master key,  you  need  to  make
              sure to do it right. Otherwise you can end up with a low-entropy
              or  otherwise  partially  predictable  master  key  which   will
              compromise security.

              For  luksAddKey  this  allows  adding  a  new passphrase without
              having to know an exiting one.

              For open this allows one to open the LUKS device without  giving
              a passphrase.

       --dump-master-key
              For  luksDump  this  option  includes  the  master  key  in  the
              displayed information. Use with care, as the master key  can  be
              used    to    bypass    the   passphrases,   see   also   option
              --master-key-file.

       --use-random

       --use-urandom
              For luksFormat these options define which kernel  random  number
              generator  will  be  used  to  create the master key (which is 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
              system),  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>
              Start offset used in IV calculation  in  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.

              Hence,  if  --offset n, and --skip s, sector n (the first sector
              of encrypted device) will get a sector number of s  for  the  IV
              calculation.

       --readonly, -r
              set up a read-only mapping.

       --shared
              Creates  an additional mapping for one common ciphertext device.
              Arbitrary mappings are supported.  This option is only  relevant
              for  the  open  --type  plain  action.  Use --offset, --size and
              --skip to specify the mapped area.

       --iter-time, -i <number of milliseconds>
              The number of  milliseconds  to  spend  with  PBKDF2  passphrase
              processing.   This  option  is only relevant for LUKS operations
              that  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
              provided by kernel for the  underlying  device  to  get  optimal
              alignment.   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
              generating 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.

              A  kernel version of 3.1 or later is needed. For earlier kernels
              this option is ignored.

       --test-passphrase
              Do not activate device, just verify passphrase.  This option  is
              only  relevant  for  open action (the device mapping name is not
              mandatory if this option is used).

       --header <device or file storing the LUKS header>
              Use a detached (separated) metadata device  or  file  where  the
              LUKS  header  is  stored.  This  options  allows  one  to  store
              ciphertext 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.
              luksAddKey),  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
              specified actually belongs to the header given. In fact you  can
              specify  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.
       '\n'.  The input without the newline character is  processed  with  the
       default  hash  or the hash specified with --hash.  The hash result will
       be truncated to the key size of the used cipher, or the size  specified
       with -s.

       From stdin: Reading will continue until a newline (or until the maximum
       input size is reached), with the trailing newline stripped. The maximum
       input  size  is  defined  by  the  same  compiled-in default as for the
       maximum key file size and   can  be  overwritten  using  --keyfile-size
       option.

       The  data  read  will  be  hashed  with  the  default  hash or the hash
       specified with --hash.  The has result will be  truncated  to  the  key
       size of 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
       newline  character  or  the  compiled-in  maximum  key  file length. If
       --keyfile-size is given, it is ignored.

       From key file: The complete keyfile  is  read  up  to  the  compiled-in
       maximum  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
       protection for low-entropy passphrases, but open will  take  longer  to
       complete.  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 device
       with a slow CPU, as this will result in a low  iteration  count.  On  a
       slow  device  it  may be advisable to increase the iteration time using
       the --iter-time option in order to obtain  a  higher  iteration  count.
       This does slow down all later luksOpen operations accordingly.

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
       depend on kernel support. See /proc/crypto  for  a  list  of  available
       options.  You  might  need  to load additional kernel crypto modules in
       order to get more options.

       For the --hash option, if the crypto backend  is  libgcrypt,  then  all
       algorithms  supported  by  the gcrypt library are available.  For other
       crypto backends some algorithms may be missing.

NOTES ON PASSPHRASES

       Mathematics can't be bribed. Make sure you keep your passphrases  safe.
       There  are a few nice tricks for constructing a fallback, when suddenly
       out of the blue, your brain refuses to cooperate.  These fallbacks need
       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
       automatically).  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 Jana Saout <jana@saout.de>
       The  LUKS  extensions  and  original  man  page were written by Clemens
       Fruhwirth <clemens@endorphin.org>.
       Man page extensions by Milan Broz <gmazyland@gmail.com>.
       Man page rewrite and extension by Arno Wagner <arno@wagner.name>.

COPYRIGHT

       Copyright © 2004 Jana Saout
       Copyright © 2004-2006 Clemens Fruhwirth
       Copyright © 2009-2012 Red Hat, Inc.
       Copyright © 2009-2014 Milan Broz
       Copyright © 2012-2014 Arno Wagner

       This is free software; see the source for copying conditions.  There is
       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.

SEE ALSO

       The LUKS website at http://code.google.com/p/cryptsetup/

       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