cryptsetup



CRYPTSETUP(8)                Maintainance Commands               CRYPTSETUP(8)




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


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  effec-
       tively 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, --ver-
              ify-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].

       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 argu-
              ment. <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 seconds to spend with PBKDF2 password  processing.
              This  options is only relevant to LUKS key setting operations as
              luksFormat or luksAddKey.



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 respec-
       tive 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@endor-
       phin.org>


REPORTING BUGS

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


COPYRIGHT

       Copyright © 2004 Christophe Saout
       Copyright © 2004-2005 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



cryptsetup 0.99                   March 2005                     CRYPTSETUP(8)

Man(1) output converted with man2html