cryptsetup - manage plain dm-crypt and LUKS encrypted volumes


   cryptsetup <options> <action> <action args>


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


   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.


   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

   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.


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

   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,  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  <device>  parameter  can  be  also specified by a LUKS UUID in the
   format UUID=<uuid>. Translation to real device name  uses  symlinks  in
   /dev/disk/by-uuid directory.

   To specify a detached header, the --header parameter can be used in all
   LUKS commands and always  takes  precedence  over  positional  <device>

   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

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

          <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

          <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

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

   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

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

   luksKillSlot <device> <key slot number>

          Wipe the key-slot number <key slot> from the LUKS device. Except
          running  in  batch-mode  (-q)  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 implicitly 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.

          NOTE:  If  there  is no passphrase provided (on stdin or through
          --key-file argument) and batch-mode (-q) is active, the key-slot
          is removed without any other warning.

   erase <device>
   luksErase <device>

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

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

          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.


   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>

          WARNING:  The  loop-AES extension cannot use direct input of key
          file on real terminal because the keys are separated by  end-of-
          line and only part of the multi-key file would be read.
          If you need it in script, just use the pipe redirection:
          echo  $keyfile  |  cryptsetup  loopaesOpen --key-file=- <device>

          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

          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  for
   more information regarding loop-AES.

TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION

   cryptsetup  supports  mapping  of  TrueCrypt, tcplay or VeraCrypt (with
   --veracrypt option) 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).

   To recognize VeraCrypt device  use --veracrypt  option.   VeraCrypt  is
   just  extension  of  TrueCrypt header with increased iteration count so
   unlocking can take quite a lot  of  time  (in  comparison  with  TCRYPT

   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

   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-

          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  for  more  information  regarding

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


   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

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


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

          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 specification, 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

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

          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.

          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.

          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


          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

          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

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

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

          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

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

          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.

          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 not use it.

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

          Perform encryption using the same cpu that IO was submitted  on.
          The  default  is  to use an unbound workqueue so that encryption
          work is automatically balanced  between  available  CPUs.   This
          option is only relevant for open action.

          NOTE:  This  option  is  available  only  for low-level dm-crypt
          performance tuning, use only if you need a change to default dm-
          crypt behaviour. Needs kernel 4.0 or later.

          Disable offloading writes to a separate thread after encryption.
          There are some situations where offloading write bios  from  the
          encryption  threads  to  a  single  thread  degrades performance
          significantly.  The default is to offload write bios to the same
          thread.  This option is only relevant for open action.

          NOTE:  This  option  is  available  only  for low-level dm-crypt
          performance tuning, use only if you need a change to default dm-
          crypt behaviour. Needs kernel 4.0 or later.

          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.

          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) and passwdqc.conf(5).

          Show the program version.

          Show short option help.

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


   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.


   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

   The data read will  be  hashed  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.

   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.

   WARNING:  The  --hash  argument is being ignored.  The --hash option is
   usable only for stdin input in plain mode.

   If the key file is shorter than the key, cryptsetup will quit  with  an
   error.   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.


   LUKS uses PBKDF2 to protect against dictionary attacks and to give some
   protection to low-entropy passphrases (see RFC 2898 and the  cryptsetup

   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.


   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.


   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.


   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.


   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.


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


   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.


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


   cryptsetup originally written by Jana Saout <>
   The  LUKS  extensions  and  original  man  page were written by Clemens
   Fruhwirth <>.
   Man page extensions by Milan Broz <>.
   Man page rewrite and extension by Arno Wagner <>.


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

   This is free software; see the source for copying conditions.  There is


   The LUKS website at

   The cryptsetup FAQ, contained in the distribution package and online at

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

   The     LUKS     on-disk     format    specification    available    at


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.