Provided by: cryptsetup-bin_1.4.1-2ubuntu4_i386 bug

NAME

       cryptsetup  -  setup cryptographic volumes for dm-crypt (including LUKS
       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
              underlying 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,
              --key-slot, --key-file (takes precedence  over  optional  second
              argument),   --keyfile-size,   --use-random   |   --use-urandom,
              --uuid].

       luksOpen <device> <name>

              opens the LUKS partition <device> and sets up a  mapping  <name>
              after  successful  verification  of  the  supplied  key material
              (either via key file by --key-file, or via prompting).

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

       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.

              WARNING: Be sure you have another slot active or  header  backup
              when  using explicit key slot (so you can unlock the device even
              after possible media failure during slot swap).

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

       luksKillSlot <device> <key slot number>

              wipe  key  with  number <key slot> from LUKS device. A remaining
              passphrase or key file (via --key-file) must be supplied.

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

              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.

       For        more        information        about        LUKS,        see
       http://code.google.com/p/cryptsetup/wiki/Specification

loop-AES EXTENSION

       cryptsetup supports  mapping  of  loop-AES  encrypted  partition  using
       compatible dm-crypt mode.

       loopaesOpen <device> <name> --key-file <keyfile>

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

              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
              explicitly use --skip 0 in addition to offset parameter.

              Use  --hash  to  override  hash  function  for  password hashing
              (otherwise 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.sourceforge.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
              incompatible 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.

              Default  mode  is  configurable  during compilation, you can see
              compiled-in default using cryptsetup --help.   If  not  changed,
              the  default  is  for plain dm-crypt and LUKS mappings "aes-cbc-
              essiv:sha256".

              For XTS mode, kernel version 2.6.24 or more recent is  required.
              Use  "aes-xts-plain64"  cipher specification and set key size to
              256 (or 512)  bits  (see  -s  option).   Note  that  plain64  IV
              (Initialization Vector) is available since kernel version 2.6.33
              and it is full 64bit version of plain IV. For more  info  please
              see FAQ.

       --verify-passphrase, -y
              query  for  passwords  twice.  Useful  when creating a (regular)
              mapping 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
              (master)  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
              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, luksOpen and luksAddKey.

       --key-size, -s
              set key size in bits.

              Has to be a multiple of 8 bits. The key size is limited  by  the
              used cipher.

              See output of /proc/crypto for more information.

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

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

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

              If not specified, cryptsetup tries to use topology info provided
              by kernel for underlying device to get  optimal  alignment.   If
              not  available (or calculated value is multiple of default) data
              is by default aligned to 1 MiB boundary (2048 512-byte sectors).

              For detached LUKS header it specifies  offset  on  data  device.
              See also --header option.

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

              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
       material  (without  newline) with the default hash or the hash given by
       --hash.  After hashing, it will be cropped to the key size given by -s.

       From stdin: Reading will continue until EOF  (or  until  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  or  can be overwrittten using --keysfile-size
       option.

       After that the read data will be hashed with the default  hash  or  the
       hash  given  by  --hash  and  the result will be cropped to the keysize
       given by -s.

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

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.

NOTES ON RNG

       Random Number Generator (RNG) used in cryptsetup always uses kernel RNG
       without  any  modifications  or  additions  to  data stream procudes by
       kernel (like internal random pool operations or mixing with  the  other
       random sources).

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

       Second  type  is  used  for 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 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
       partition or LVM volume).  However if  the  device  argument  is  file,
       cryptsetup 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@endorphin.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/