Provided by: cryptsetup_1.0.6+20090405.svn49-1ubuntu7_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. 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.

       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 sets the initial key, either
              via prompting or via <key file>.  <options>  can  be  [--cipher,
              --verify-passphrase, --key-size, --key-slot].

       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 a positional argument. <options> can
              be [--key-file, --key-slot].

       luksRemoveKey <device> [<key file>]

              remove supplied key or key file from LUKS device

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

       luksDelKey <device> <key slot number>

              identical to luksKillSlot, but deprecated action name.

       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.
              Default is "ripemd160".

       --cipher, -c
              set  cipher  specification  string. For plain dm-crypt mappings,
              the default is "aes-cbc-plain", for LUKS mappings it’s "aes-cbc-
              essiv:sha256".  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.

              If  the  key  file is "-", stdin will be used. This is different
              from how cryptsetup usually reads from stdin. See section  NOTES
              ON PASSWORD PROCESSING for more information.

       --key-slot, -S
              For  LUKS  operations that add key material, this options allows
              to you specify which key slot is selected for the new key.  This
              option can be used for luksFormat 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 ignore this flag,  as  the  key-size  is
              specified by the partition header. Default is 128 for luksFormat
              and 256 for create.

       --size, -b
              force the size of the underlying 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  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.

       --readonly
              set up a read-only mapping.

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

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

       From a file descriptor or 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 (so using e.g.  /dev/random
       as stdin will not work), with the trailing newline stripped. 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 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
       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.

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.

AUTHORS

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

COMPATABILITY WITH OLD SUSE TWOFISH PARTITIONS

       To  read  images  created with SuSE Linux 9.2’s loop_fish2 use --cipher
       twofish-cbc-null -s 256 -h sha512, for images created with  even  older
       SuSE Linux use --cipher twofish-cbc-null -s 192 -h ripemd160:20

DEPRECATED ACTIONS

       reload <name> <device>

              modifies  an  active mapping <name>. Same options as for create.
              WARNING: Do not use this for LUKS devices, as the semantics  are
              identical  to  the create action, which are totally incompatible
              with the LUKS key setup.

              This action is deprected because it proved to be rarely  useful.
              It  is  uncommon to change the underlying device, key, or offset
              on the fly. In case, you really want to do this,  you  certainly
              know  what  you  are  doing and then you are probably better off
              with the swiss knive tool for device mapper, namely dmsetup.  It
              provides you with the same functionality, see dmsetup reload.

       luksDelKey <device> <key slot number>

              identical  to  luksKillSlot,  but  deprecated  action name. This
              option was renamed, as we  introduced  luksRemoveKey,  a  softer
              method for disabling password slots. To make a clear distinction
              that luksDelKey was more brutal than luksRemoveKey

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