Provided by: cryptsetup_1.0.3-0ubuntu1_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 up  dm-crypt  managed  device-
       mapper   mappings.   For   basic  dm-crypt  mappings,  there  are  five
       operations.

ACTIONS

       These strings are valid for <action>, followed by their <action args>:

       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, --readonly]

       remove <name>

              removes an existing mapping <name>. No options.

       status <name>

              reports the status for the mapping <name>. No options.

       reload <name>

              modifies an active mapping <name>. Same options as for create.

       resize <name>

              resizes an active mapping <name>. <options> must include --size

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   revoked
       effectively  and  that  are  protected  against dictionary attacks with
       PBKDF2.

       These are valid LUKS actions:

       luksFormat <device> [<key file>]

              initializes a LUKS partition and set the initial key, either via
              prompting  or  via  <key  file>.   <options>  can  be [--cipher,
              --verify-passphrase, --key-size]

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

       luksClose <name>

              identical to remove.

       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  after  luksAddKey as positional
              argument. <options> can be [--key-file].

       luksDelKey <key slot number>

              remove key from key slot. No options.

       luksUUID <device>

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

       isLuks <device>

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

       luksDump <device>

              dumps the header information of a LUKS partition. No options.

       For more information about LUKS, see http://luks.endorphin.org

OPTIONS

       --hash, -h
              specifies  hash to use for password hashing. This option is only
              relevant for the "create" action. The hash string is  passed  to
              libgcrypt, so all hashes accepted by gcrypt are supported.

       --cipher, -c
              set  cipher  specification  string.  Usually,  this is "aes-cbc-
              plain". For pre-2.6.10 kernels, use "aes-plain"  as  they  don’t
              understand  the new cipher spec strings. To use ESSIV, use "aes-
              cbc-essiv:sha256".

       --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.  If
              you  want  to  set  a  new key via a key file, you have to use a
              positional arg to luksFormat or luksAddKey.

       --key-size, -s
              set key size in bits. Usually, this is 128, 192 or 256.  Can  be
              used  for  create  or  luksFormat,  all  other LUKS actions will
              ignore this flag, as the key-size is specified by the  partition
              header.

       --size, -b
              force the size of the underlaying device in sectors.

       --offset, -o
              start offset in the backend device.

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

       --readonly
              setup a read-only mapping.

       --iter-time, -i
              The  number  of  microseconds  to  spend  with  PBKDF2  password
              processing. This options is only relevant to  LUKS  key  setting
              operations as luksFormat or luksAddKey.

       --batch-mode, -q
              Do  not  ask  for confirmation. This option is only relevant for
              luksFormat.

       --timeout, -t
              The number of seconds to wait before  timeout.  This  option  is
              relevant  evertime  a  password is asked, like create, luksOpen,
              luksFormat or luksAddKey.

       --align-payload=value
              Align payload at a boundary of  value  512-byte  sectors.   This
              option  is  relevant for luksFormat.  If your block device lives
              on a RAID it is useful to align the filesystem  at  full  stripe
              boundaries so it can take advantage of the RAID’s geometry.  See
              for instance the sunit and swidth options in the mkfs.xfs manual
              page.   By  default  the payload is aligned at an 8 sector (4096
              byte) boundary.

       --version
              Show the version.

NOTES ON PASSWORD PROCESSING FOR REGULAR MAPPINGS

       From a file descriptor or a terminal: Password processing  is  new-line
       sensitive, meaning the reading will stop after encountering \n. It will
       processed the read material with the default hash or the hash given  by
       --hash.  After  hashing  it will be cropped to the key size given by -s
       (or default 256bit).

       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.

NOTES ON PASSWORD PROCESSING FOR LUKS

       Password processing is totally different for LUKS. LUKS uses PBKDF2  to
       protect  against  dictionary  attacks (see RFC 2898).  LUKS will always
       use SHA1 in HMAC mode, and no other mode is supported  at  the  moment.
       Hence, -h is ignored.

       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.

       LUKS  saves  the  processing  options  when  a  password  is set to the
       respective key slot.  Therefore, no options can be given  to  luksOpen.
       For  any password creation action (luksAddKey, or luksFormat), the user
       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.

NOTES ON PASSWORDS

       Mathematic  can’t  be  bribed.  Make sure you keep your passwords save.
       There are a few nice tricks for constructing a fallback,  when  suddely
       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.

AUTHORS

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

REPORTING BUGS

       Report bugs to <dm-crypt@saout.de>.

COPYRIGHT

       Copyright © 2004 Christophe Saout
       Copyright © 2004-2006 Clemens Fruhwirth

       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

       dm-crypt website, http://www.saout.de/misc/dm-crypt/

       LUKS website, http://luks.endorphin.org

       dm-crypt TWiki, http://www.saout.de/tikiwiki/tiki-index.php