cryptsetup

       extension)

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

DESCRIPTION
       cryptsetup is used to conveniently setup dm-crypt managed device-mapper
       mappings.

PLAIN MODE
       For basic (plain) dm-crypt mappings, there are four operations.

       create <name> <device>

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

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

       remove <name>

              removes an existing mapping <name>.

       status <name>

              reports the status for the mapping <name>.

       resize <name>

              resizes an active mapping <name>.

              If  --size (in sectors) is not specified, the size of the under-
              lying block device is used.

LUKS EXTENSION
       LUKS, Linux Unified Key Setup, is a standard for hard disk  encryption.
       It  standardizes  a  partition header as well as the format of the bulk
       data.  LUKS can manage multiple  passwords  that  can  be  individually
       revoked  and  effectively  scrubbed from persistent media, and that are
       protected against dictionary attacks with PBKDF2.

       Each password, usually called a key in  this  document,  is  associated
       with  a  slot,  of which there are typically 8.  Key operations that do
       not specify a slot affect the first slot matching the supplied key.

       These are valid LUKS actions:

       luksFormat <device> [<key file>]

              initializes a LUKS partition and sets the  initial  key,  either
              via prompting or via <key file>.

              <options>  can  be  [--cipher,  --verify-passphrase, --key-size,

       luksClose <name>

              identical to remove.

       luksSuspend <name>

              suspends  active device (all IO operations are frozen) and wipes
              encryption key from kernel. Kernel version 2.6.19  or  later  is
              required.

              After  that  operation  you  have to use luksResume to reinstate
              encryption key (and resume device) or luksClose to remove mapped
              device.

              WARNING:  never  try  to  suspend device where is the cryptsetup
              binary itself.

              <options> can be [--header].

       luksResume <name>

              Resumes suspended device and reinstates encryption key. You will
              need  provide  passphrase  identical  to luksOpen command (using
              prompting or key file).

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

       luksAddKey <device> [<new key file>]

              add a new key file/passphrase. An  existing  passphrase  or  key
              file  (via  --key-file) must be supplied.  The key file with the
              new material is supplied as a positional argument.

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

       luksRemoveKey <device> [<key file>]

              remove  supplied  key or key file from LUKS device in the manner
              of luksKillSlot.

       luksChangeKey <device> [<new key file>]

              change existing key file or passphrase. An  existing  passphrase
              or  key  file  (via  --key-file) must be supplied.  The key file
              with the new material is supplied as a positional argument.

              If no key slot is specified (and there is still free key slot on
              device) new slot is allocated before the old is purged.

              If  --key-slot  option  is  specified (or there is no free slot)
              command will overwrite existing slot.

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

       luksUUID <device>

              print UUID, if <device> has a LUKS header.

              set new UUID if --uuid option is specified.

       isLuks <device>

              returns true, if <device> is a LUKS partition. Otherwise, false.

       luksDump <device>

              dumps the header information of a LUKS partition.

              If --dump-master-key option is used, the volume (master) key  is
              dumped instead of keyslot info.

              Because  this information can be used to access encrypted device
              without passphrase knowledge (even without LUKS header) use this
              option very carefully.

              Dump  with  volume key (either printed or stored to file) should
              be always stored encrypted and on safe place.

              LUKS passphrase or key file is required for volume key dump.

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

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

              Stores binary backup of LUKS header and keyslot areas.

              WARNING:  Please  note  that  with  this  backup  file  (and old
              passphrase  knowledge)  you  can  decrypt  data  even   if   old
              passphrase was wiped from real device.

              Also note that anti-forensic splitter is not used during manipu-
              lation with backup file.

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

              Restores binary backup of LUKS header  and  keyslot  areas  from
              specified file.

              WARNING:  All  the  keyslot  areas  are overwritten, only active
              keyslots form backup file are available after issuing this  com-
              mand.

              This  command  allows  restoring header if device do not contain
              LUKS header or if the master key size and data  offset  in  LUKS
              header on device match the backup file.
              N.B.  If  key  file  is in GPG encrypted format, you have to use
              --key-file=- and decrypt it before use.  gpg --decrypt <keyfile>
              | cryptsetup loopaesOpen --key-file=- <device> <name>

              Use --key-file to specify proper key length, default compiled-in
              parameters are visible in --help output.

              Use --offset to specify device offset. Note the units need to be
              specified in 512 bytes sectors.

              Use  --skip to specify IV offset. If original device used offset
              and not used it in IV sector calculations, you have  to  explic-
              itly use --skip 0 in addition to offset parameter.

              Use  --hash to override hash function for password hashing (oth-
              erwise it is detected according to key size).

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

       loopaesClose <name>

              identical to remove.

       For   more  information  about  loop-AES,  see  http://loop-aes.source-
       forge.net

OPTIONS
       --verbose, -v
              Print more verbose messages.

       --debug
              Run in debug mode with full diagnostic logs.

       --hash, -h
              For create and loopaesOpen action  specifies  hash  to  use  for
              password hashing.

              For  luksFormat  action  specifies  hash  used in LUKS key setup
              scheme and volume key digest.

              WARNING: setting hash other than sha1 causes LUKS device  incom-
              patible with older version of cryptsetup.

              The  hash  string is passed to libgcrypt, so all hash algorithms
              are supported (for luksFormat algorithm must provide at least 20
              byte  long hash).  Default is set during compilation, compatible
              values with old version of cryptsetup are "ripemd160" for create
              action and "sha1" for luksFormat.

              Use cryptsetup --help to show defaults.

       --cipher, -c
              set cipher specification string.

       --verify-passphrase, -y
              query for passwords twice. Useful when creating a (regular) map-
              ping for the first time, or when running luksFormat.

       --key-file, -d
              use file as key material.

              With LUKS, key material supplied in key files via -d are  always
              used for existing passphrases, except in luksFormat action where
              -d is equivalent to positional key file argument.

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

              If  the  key  file  is "-", stdin will be used. With the "-" key
              file reading will not stop when new line character is detected.

              See section NOTES ON PASSWORD PROCESSING for more information.

       --keyfile-size, -l value
              Limits read from key file to value bytes.  Usable together  with
              all commands using key file.

       --new-keyfile-size  value
              Limits  read from new key file to value bytes in luksAddKey when
              adding new key file. Default is exhaustive read from key file.

       --master-key-file
              Use pre-generated master key stored in file. For  luksFormat  it
              allows LUKS header reformatting with the same master key (if all
              other parameters are the same existing  encrypted  data  remains
              intact).

              For  luksAddKey it allows adding new passphrase with only master
              key knowledge.

       --dump-master-key
              For luksDump it allows LUKS header dump including  volume  (mas-
              ter)  key.   Use  with  care  (this information allows access to
              device without passphrase knowledge).

              See luksDump for more info.

       --use-random

       --use-urandom
              For luksFormat it defines which kernel random  number  generator
              will be used for long-term key (volume key).

              See  NOTES ON RNG for more information. Use cryptsetup --help to
              show default RNG.

       --key-slot, -S
              Can  be  used  for  create or luksFormat, all other LUKS actions
              will use key-size specified by the LUKS header.  Default is  set
              during compilation, if not changed it is 256 bits.

              Use cryptsetup --help to show defaults.

       --size, -b
              force the size of the underlying device in sectors.  This option
              is only relevant for create and resize action.

       --offset, -o
              start offset in the backend device (in 512-byte sectors).   This
              option is only relevant for create and loopaesOpen action.

       --skip, -p
              how many sectors of the encrypted data to skip at the beginning.
              This is different from the --offset options with respect  to  IV
              calculations.   Using  --offset will shift the IV calculation by
              the same negative amount.  Hence, if --offset n, sector  n  will
              be the first sector on the mapping with IV 0. Using --skip would
              have resulted in sector n being the first sector also, but  with
              IV  n.   This option is only relevant for create and loopaesOpen
              action.

       --readonly
              set up a read-only mapping.

       --shared
              create another non-overlapping mapping to one common  ciphertext
              device,  e.g.  to  create hidden device inside another encrypted
              device.  This option is only relevant for  create  action.   Use
              --offset, --size and --skip to specify mapped area.

       --iter-time, -i
              The  number  of  milliseconds to spend with PBKDF2 password pro-
              cessing.  This option is only relevant to the LUKS operations as
              luksFormat or luksAddKey.  Note that 0 means default.

       --batch-mode, -q
              Do  not ask for confirmation. Use with care! This option is only
              relevant for luksFormat, luksAddKey, luksRemoveKey or  luksKill-
              Slot.

       --timeout, -t
              The  number  of  seconds  to wait before timeout. This option is
              relevant every time a password is asked, like create,  luksOpen,
              luksFormat  or  luksAddKey. It has no effect if used in conjunc-
              tion with --key-file.

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

       --uuid=UUID
              Use  provided  UUID  in luksFormat command instead of generating
              new one or change existing UUID in luksUUID command.

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

       --allow-discards
              Allow using of discards (TRIM) requests for device.  This option
              is only relevant for create, luksOpen or loopaesOpen.

              WARNING: Assess the specific  security  risks  carefully  before
              enabling   this  option.   For  example,  allowing  discards  on
              encrypted devices may lead to the leak of information about  the
              ciphertext  device  (filesystem  type,  used space etc.)  if the
              discarded blocks can be located easily on the device later.

              Kernel version 3.1 or more recent is required.  For  older  ver-
              sions is the option ignored.

       --header
              Set  detached  (separated)  metadata  device  or  file with LUKS
              header.

              This options allows separation of ciphertext device and  on-disk
              metadata header.

              This option is only relevant for LUKS devices and can be used in
              luksFormat, luksOpen, luksSuspend, luksResume  and  resize  com-
              mands.

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

              For other commands with separated metadata device  you  have  to
              always  specify  path  to metadata device (not to the ciphertext
              device).

              WARNING: There is no possible check  that  specified  ciphertext
              device is correct if on-disk header is detached. Use with care.

       --version
              Show the version.

RETURN CODES
       Crypsetup returns 0 on success or non-zero 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 PASSWORD PROCESSING FOR PLAIN MODE
       From a terminal: Password processing is new-line sensitive, meaning the
       reading will stop after encountering \n.   It  will  process  the  read
       If  "plain"  is  used as an argument to the hash option, the input data
       will not be hashed.  Instead, it will be zero padded (if  shorter  than
       the  keysize)  or  truncated  (if  longer  than  the  keysize) and used
       directly as the key.  No warning will be given if the  amount  of  data
       read from stdin is less than the keysize.

       From  a key file: It will be cropped to the size given by -s.  If there
       is insufficient key material in the key file, cryptsetup will quit with
       an error.

       If  --key-file=-  is  used  for reading the key from stdin, no trailing
       newline is stripped from the input.  Without  that  option,  cryptsetup
       strips trailing newlines from stdin input.

NOTES ON PASSWORD PROCESSING FOR LUKS
       LUKS uses PBKDF2 to protect against dictionary attacks (see RFC 2898).

       LUKS  will  always  do an exhaustive password reading.  Hence, password
       can not be read from /dev/random, /dev/zero or any  other  stream  that
       does not terminate.  To prevent exhausting of system memory, cryptsetup
       limits maximum key file  size.  Compiled-in  default  is  displayed  in
       --help  output.  You  can  limit  reads  from key file using --key-size
       option, this option takes precedence over compiled-in default.

       For any password creation action (luksAddKey, or luksFormat), the  user
       may  specify  how much the time the password processing should consume.
       Increasing the time will lead to a more secure password, but also  will
       take luksOpen longer to complete.  The default setting of one second is
       sufficient for good security.

INCOHERENT BEHAVIOUR FOR INVALID PASSWORDS/KEYS
       LUKS checks for a valid password or key when an encrypted partition  is
       unlocked.  Thus the luksOpen action fails with invalid password or key,
       contrary to the plain dm-crypt create action.

       Please also be sure that you are using the same keyboard  and  language
       setting as during device format.

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 --hash option all algorithms supported by gcrypt library are avail-
       able.

NOTES ON PASSWORDS
       Mathematics  can't  be  bribed. Make sure you keep your passwords safe.
       There are a few nice tricks for constructing a fallback, when  suddenly
       out  of  (or after being) blue, your brain refuses to cooperate.  These
       fallbacks are possible with LUKS, as it's only possible  with  LUKS  to
       have multiple passwords.

       urandom options. Using /dev/random on  system  without  enough  entropy
       sources  can  cause  luksFormat  to block until the requested amount of
       random data is gathered.  See urandom(4) for more information.

NOTES ON LOOPBACK DEVICE USE
       Cryptsetup is usually used directly over block device (like disk parti-
       tion  or  LVM  volume).  However if the device argument is file, crypt-
       setup tries to allocate loopback device and map it into this file. This
       mode  requires  Linux  kernel 2.6.25 or more recent which supports loop
       autoclear flag (loop device is cleared on last close automatically).

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

AUTHORS
       cryptsetup is written by Christophe Saout <christophe@saout.de>
       LUKS  extensions,  and  man  page  by Clemens Fruhwirth <clemens@endor-
       phin.org>

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  to <dm-crypt@saout.de> or Issues section on LUKS website.
       Please attach output of failed command with added --debug option.

COPYRIGHT
       Copyright (C) 2004 Christophe Saout
       Copyright (C) 2004-2006 Clemens Fruhwirth
       Copyright (C) 2009-2011 Red Hat, Inc.

       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
       LUKS website, http://code.google.com/p/cryptsetup/



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