cryptsetup man page on Kali

Man page or keyword search:  
man Server   9211 pages
apropos Keyword Search (all sections)
Output format
Kali logo
[printable version]

CRYPTSETUP(8)		     Maintenance Commands		 CRYPTSETUP(8)

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 his‐
       toric loopaes volumes and for TrueCrypt 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	Crypt‐
       setup  FAQ.  Read  it.  Nonetheless, some risks deserve to be mentioned
       here.

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

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

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

       Previously used partitions: If a partition was previously used, it is a
       very  good idea to wipe filesystem signatures, data, etc. before creat‐
       ing a LUKS or plain dm-crypt container on it.  For a quick  removal  of
       filesystem signatures, use "wipefs". Take care though that this may not
       remove everything. In particular md (RAID) signatures at the end	 of  a
       device  may  survive.  It  also	does not remove data. For a full wipe,
       overwrite the whole partition before container creation. If you do  not
       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 individ‐
	      ual 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  ker‐
	      nel memory.

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

       status <name>

	      Reports the status for the mapping <name>.

       resize <name>

	      Resizes an active mapping <name>.

	      If --size (in sectors) is not specified, the  size  is  computed
	      from  the	 underlying  device.  For  LUKS	 it is the size of the
	      underlying device without the area reserved for LUKS header (see
	      data  payload  offset  in	 luksDump  command).   For plain crypt
	      device the whole device size 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 con‐
       tainer 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 for‐
       mat  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>
       parameter.

       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.

	      <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,	--mas‐
	      ter-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,
	      --header]

	      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	perma‐
	      nently inaccessible.

       luksChangeKey <device> [<new key file>]

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

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

	      WARNING: If a key-slot is overwritten, a	media  failure	during
	      this  operation  can  cause  the overwrite to fail after the old
	      passphrase has been wiped and make the LUKS container inaccessi‐
	      ble.

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

	      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 perma‐
	      nently 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 inac‐
	      cessible.	  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 success‐
	      ful.'  means the device is a LUKS device.

       luksDump <device>

	      Dump the header information of a LUKS device.

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

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

	      <options>	 can be [--dump-master-key, --key-file, --keyfile-off‐
	      set, --keyfile-size, --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.

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

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

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

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

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

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

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

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

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

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

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

TCRYPT (TrueCrypt-compatible 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 algo‐
       rithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER	 .con‐
       fig 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
       device).

       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-dis‐
	      cards].

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

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

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

       See also https://en.wikipedia.org/wiki/TrueCrypt 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 sup‐
	      ported 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  informa‐
	      tive.  You cannot directly predict real storage encryption speed
	      from it.

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

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

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

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

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

	      Specifies the hash used in the LUKS key setup scheme and	volume
	      key  digest  for luksFormat. The specified hash 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
	      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 charac‐
	      ters.

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

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

	      See section NOTES ON PASSPHRASE PROCESSING for more information.

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

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

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

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

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

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

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

	      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 compro‐
	      mise security.

	      For  luksAddKey this allows adding a new passphrase without hav‐
	      ing 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 dis‐
	      played 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 sys‐
	      tem), both selections are problematic.  Using  /dev/urandom  can
	      lead  to	weak  keys.   Using /dev/random can block a long time,
	      potentially forever, if not enough entropy can be	 harvested  by
	      the kernel.

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

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

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

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

       --size, -b <number of 512 byte sectors>
	      Set the size of the 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 pro‐
	      cessing.	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 pro‐
	      vided by kernel for the underlying device to get optimal	align‐
	      ment.   If  not available (or the calculated value is a multiple
	      of the default) data is by default aligned to  a	1MiB  boundary
	      (i.e. 2048 512-byte sectors).

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

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

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

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

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

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

       --perf-same_cpu_crypt
	      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 per‐
	      formance tuning, use only if you need a change  to  default  dm-
	      crypt behaviour. Needs kernel 4.0 or later.

       --perf-submit_from_crypt_cpus
	      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 sig‐
	      nificantly.  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 per‐
	      formance tuning, use only if you need a change  to  default  dm-
	      crypt behaviour. Needs kernel 4.0 or later.

       --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  cipher‐
	      text and LUKS header on different devices.

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

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

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

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

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

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

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

	      For  more info about password quality check, see manual page for
	      pwquality.conf(5) and passwdqc.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	 maxi‐
       mum key file size and can be overwritten using --keyfile-size option.

       The  data  read will be hashed with the default hash or the hash speci‐
       fied 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.

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

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

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

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

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

       The  default  setting  of  one  second is sufficient for most practical
       cases. The only exception is a low-entropy passphrase used on a	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 automati‐
       cally). Of course, you can always map a file to a loop-device manually.
       See the cryptsetup FAQ for an example.

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

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

       The luksDelKey was replaced with luksKillSlot.

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

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

COPYRIGHT
       Copyright © 2004 Jana Saout
       Copyright © 2004-2006 Clemens Fruhwirth
       Copyright © 2009-2017 Red Hat, Inc.
       Copyright © 2009-2017 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 https://gitlab.com/cryptsetup/cryptsetup/

       The cryptsetup FAQ, contained in the distribution package and online at
       https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions

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

       The  LUKS  on-disk  format  specification  available  at	  https://git‐
       lab.com/cryptsetup/cryptsetup/wikis/Specification

cryptsetup			  March 2017			 CRYPTSETUP(8)
[top]

List of man pages available for Kali

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net