X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=man%2Fcryptsetup.8;h=df3cadc3d49bb6de37fb4da4d2b7805d2762d006;hb=664eff9e76e90702137268116873cbfc8719568e;hp=aa683f9fe56aa38499826ebb25e2bcd62e62a921;hpb=bce295738bad54f22bb5851bc7c9a9607b4e1298;p=platform%2Fupstream%2Fcryptsetup.git diff --git a/man/cryptsetup.8 b/man/cryptsetup.8 index aa683f9..df3cadc 100644 --- a/man/cryptsetup.8 +++ b/man/cryptsetup.8 @@ -1,448 +1,931 @@ -.TH CRYPTSETUP "8" "" "cryptsetup" "Maintenance Commands" +.TH CRYPTSETUP "8" "May 2012" "cryptsetup" "Maintenance Commands" .SH NAME -cryptsetup - setup cryptographic volumes for dm-crypt (including LUKS extension) +cryptsetup - manage plain dm-crypt and LUKS encrypted volumes .SH SYNOPSIS .B cryptsetup .SH DESCRIPTION .PP -cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings. -.SH PLAIN MODE -For basic (plain) dm-crypt mappings, there are four operations. - -\fIcreate\fR +cryptsetup is used to conveniently setup dm-crypt managed +device-mapper mappings. These include plain dm-crypt volumes and +LUKS volumes. The difference is that LUKS uses a metadata header +and can hence offer more features than plain dm-crypt. On the other +hand, the header is visible and vulnerable to damage. +.SH PLAIN DM-CRYPT OR LUKS? +.PP +Unless you understand the cryptographic background well, use LUKS. +With plain dm-crypt there are a number of possible user errors +that massively decrease security. While LUKS cannot fix them +all, it can lessen the impact for many of them. +.SH WARNINGS +.PP +A lot of good information on the risks of using encrypted storage, +on handling problems and on security aspects can be found in the +\fICryptsetup FAQ\fR. Read it. Nonetheless, some risks deserve +to be mentioned here. + +\fBBackup:\fR Storage media die. Encryption has no influence on that. +Backup is mandatory for encrypted data as well, if the data has any +worth. See the Cryptsetup FAQ for advice on how to do backup of an +encrypted volume. + +\fBCharacter encoding:\fR If you enter a +passphrase with special symbols, the passphrase can change +depending character encoding. Keyboard settings can also change, +which can make blind input hard or impossible. For +example, switching from some ASCII 8-bit variant to UTF-8 +can lead to a different binary encoding and hence different +passphrase seen by cryptsetup, even if what you see on +the terminal is exactly the same. It is therefore highly +recommended to select passphrase characters only from 7-bit +ASCII, as the encoding for 7-bit ASCII stays the same for +all ASCII variants and UTF-8. + +\fBLUKS header:\fR If the header of a LUKS volume gets damaged, +all data is permanently lost unless you have a header-backup. +If a key-slot is damaged, it can only be restored from a header-backup +or if another active key-slot with known passphrase is undamaged. +Damaging the LUKS header is something people manage to do with +surprising frequency. This risk is the result of a trade-off +between security and safety, as LUKS is designed for fast and +secure wiping by just overwriting header and key-slot area. + +\fBPreviously used partitions:\fR If a partition was previously used, +it is a very good idea to wipe filesystem signatures, data, etc. before +creating a LUKS or plain dm-crypt container on it. +For a quick removal of filesystem signatures, use "wipefs". Take care +though that this may not remove everything. In particular md (RAID) +signatures at the end of a device may survive. It also does not +remove data. For a full wipe, overwrite the whole partition before +container creation. If you do not know how to to that, the +cryptsetup FAQ describes several options. + +.SH BASIC COMMANDS +The following are valid actions for all supported device types. + +\fIopen\fR \-\-type .IP -creates a mapping with backed by device . +Opens (creates a mapping) with backed by device . -\fB\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase, -\-\-key-file, \-\-key-size, \-\-offset, \-\-skip, \-\-readonly] +Device type can be \fIplain\fR, \fIluks\fR (default), \fIloopaes\fR +or \fItcrypt\fR. + +For backward compatibility there are \fBopen\fR command aliases: + +\fBcreate\fR: open \-\-type plain \fR switched arguments) +.br +\fBplainOpen\fR: open \-\-type plain +.br +\fBluksOpen\fR: open \-\-type luks +.br +\fBloopaesOpen\fR: open \-\-type loopaes +.br +\fBtcryptOpen\fR: open \-\-type tcrypt + +\fB\fR are type specific and are described below +for individual device types. .PP -\fIremove\fR +\fIclose\fR .IP -removes an existing mapping . +Removes the existing mapping and wipes the key from kernel memory. + +For backward compatibility there are \fBclose\fR command aliases: +\fBremove\fR, \fBplainClose\fR, \fBluksClose\fR, \fBloopaesClose\fR, +\fBtcryptClose\fR (all behaves exactly the same, device type is +determined automatically from active device). .PP \fIstatus\fR .IP -reports the status for the mapping . +Reports the status for the mapping . .PP \fIresize\fR .IP -resizes an active mapping . +Resizes an active mapping . -If \-\-size (in sectors) is not specified, the size of the underlying block device is used. -.SH 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. +If \-\-size (in sectors) is not specified, the size of the +underlying block device is used. Note that this does not +change the raw device geometry, it just changes how many +sectors of the raw device are represented in the mapped device. +.SH PLAIN MODE +Plain dm-crypt encrypts the device sector-by-sector with a +single, non-salted hash of the passphrase. No checks +are performed, no metadata is used. There is no formatting operation. +When the raw device is mapped (created), the usual device operations +can be used on the mapped device, including filesystem creation. +Mapped devices usually reside in /dev/mapper/. -These are valid LUKS actions: +The following are valid plain device type actions: + +\fIopen\fR \-\-type plain +.br +\fIcreate\fR (\fBOBSOLETE syntax\fR) +.IP +Creates a mapping with backed by device . + +\fB\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase, +\-\-key-file, \-\-keyfile-offset, \-\-key-size, \-\-offset, \-\-skip, \-\-size, +\-\-readonly, \-\-shared, \-\-allow-discards] + +Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw +encrypted device /dev/sda10 to the mapped (decrypted) device +/dev/mapper/e1, which can then be mounted, fsck-ed or have a +filesystem created on it. +.SH LUKS EXTENSION +LUKS, the Linux Unified Key Setup, is a standard for disk encryption. +It adds a standardized header at the start of the device, +a key-slot area directly behind the header and the bulk +data area behind that. The whole set is called a 'LUKS container'. +The device that a LUKS container resides on is called a 'LUKS device'. +For most purposes both terms can be used interchangeably. But +note that when the LUKS header is at a nonzero offset +in a device, then the device is not a LUKS device anymore, but +has a LUKS container stored in it at an offset. + +LUKS can manage multiple passphrases that can be individually revoked +or changed and that can be securely scrubbed from persistent +media due to the use of anti-forensic stripes. Passphrases +are protected against brute-force and dictionary +attacks by PBKDF2, which implements hash iteration and salting +in one function. + +Each passphrase, also called a +.B key +in this document, is associated with one of 8 key-slots. +Key operations that do not specify a slot affect the first slot +that matches the supplied passphrase or the first empty slot if +a new passphrase is added. + +The following are valid LUKS actions: \fIluksFormat\fR [] .IP -initializes a LUKS partition and sets the initial key, either via prompting or via . +Initializes a LUKS partition and sets the initial passphrase +(for key-slot 0), +either via prompting or via . Note that +if the second argument is present, then the passphrase +is taken from the file given there, without the need +to use the \-\-key-file option. Also note that for both forms +of reading the passphrase from file you can +give '-' as file name, which results in the passphrase being read +from stdin and the safety-question being skipped. + +You can only call luksFormat on a LUKS device that is not mapped. \fB\fR can be [\-\-cipher, \-\-verify-passphrase, \-\-key-size, \-\-key-slot, \-\-key-file (takes precedence over optional second argument), -\-\-keyfile-size, \-\-use-random | \-\-use-urandom, \-\-uuid]. -.PP -\fIluksOpen\fR -.IP -opens the LUKS partition and sets up a mapping after -successful verification of the supplied key material -(either via key file by \-\-key-file, or via prompting). +\-\-keyfile-offset, \-\-keyfile-size, \-\-use-random | \-\-use-urandom, +\-\-uuid, \-\-master-key-file]. -\fB\fR can be [\-\-key-file, \-\-keyfile-size, \-\-readonly]. +\fBWARNING:\fR Doing a luksFormat on an existing LUKS container will +make all data the old container permanently irretrievable, unless +you have a header backup. .PP -\fIluksClose\fR +\fIopen\fR \-\-type luks +.br +\fIluksOpen\fR (\fBold syntax\fR) .IP -identical to \fIremove\fR. +Opens the LUKS device and sets up a mapping after +successful verification of the supplied passphrase. +If the passphrase is not supplied via \-\-key-file, the command +prompts for it interactively. + +The parameter can be also specified by LUKS UUID in the +format UUID=, which uses the symlinks in /dev/disk/by-uuid. + +\fB\fR can be [\-\-key-file, \-\-keyfile-offset, +\-\-keyfile-size, \-\-readonly, \-\-test-passphrase, +\-\-allow-discards, \-\-header, \-\-key-slot, \-\-master-key-file]. .PP \fIluksSuspend\fR .IP -suspends active device (all IO operations are frozen) and wipes encryption -key from kernel. Kernel version 2.6.19 or later is required. +Suspends an active device (all IO operations will blocked +and accesses to the device will wait indefinitely) +and wipes the encryption +key from kernel memory. Needs kernel 2.6.19 or later. + +After this operation you have to use \fIluksResume\fR to reinstate +the encryption key and unblock the device or \fIclose\fR to remove +the mapped device. -After that operation you have to use \fIluksResume\fR to reinstate -encryption key (and resume device) or \fIluksClose\fR to remove mapped device. +\fBWARNING:\fR never suspend the device on which the cryptsetup binary resides. -\fBWARNING:\fR never try to suspend device where is the cryptsetup binary itself. +\fB\fR can be [\-\-header]. .PP \fIluksResume\fR .IP -Resumes suspended device and reinstates encryption key. You will need provide passphrase -identical to \fIluksOpen\fR command (using prompting or key file). +Resumes a suspended device and reinstates the encryption key. +Prompts interactively for a passphrase if \-\-key-file is not given. -\fB\fR can be [\-\-key-file, \-\-keyfile-size] +\fB\fR can be [\-\-key-file, \-\-keyfile-size, \-\-header] .PP -\fIluksAddKey\fR [] +\fIluksAddKey\fR [] .IP -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. - -\fB\fR can be [\-\-key-file, \-\-keyfile-size, \-\-new-keyfile-size, \-\-key-slot]. +adds a new passphrase. An existing passphrase must be supplied +interactively or via \-\-key-file. +The new passphrase to be added can be specified interactively +or read from the file given as positional argument. + +\fB\fR can be [\-\-key-file, \-\-keyfile-offset, +\-\-keyfile-size, \-\-new-keyfile-offset, +\-\-new-keyfile-size, \-\-key-slot, \-\-master-key-file]. .PP -\fIluksRemoveKey\fR [] +\fIluksRemoveKey\fR [] .IP -remove supplied key or key file from LUKS device +Removes the supplied passphrase from the LUKS device. The +passphrase to be removed can be specified interactively, +as positional argument or via \-\-key-file. + +\fB\fR can be [\-\-key-file, \-\-keyfile-offset, +\-\-keyfile-size] + +\fBWARNING:\fR If you read the passphrase from stdin +(without further argument or with '-' as argument +to \-\-key-file), batch-mode (-q) will be implicitely +switched on and no warning will be given when you remove the +last remaining passphrase from a LUKS container. Removing +the last passphrase makes the LUKS container permanently +inaccessible. .PP \fIluksChangeKey\fR [] .IP -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 \fB\-\-key\-slot\fR option is specified (or there is no free slot) -command will overwrite existing slot. - -\fBWARNING:\fR 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). - -\fB\fR can be [\-\-key-file, \-\-keyfile-size,\-\-new-keyfile-size, -\-\-key-slot]. +Changes an existing passphrase. The passphrase +to be changed must be supplied interactively or via \-\-key-file. +The new passphrase can be supplied interactively or in +a file given as positional argument. + +If a key-slot is specified (via \-\-key-slot), the passphrase +for that key-slot must be given and the new passphrase +will overwrite the specified key-slot. If no key-slot +is specified and there is still a free key-slot, then +the new passphrase will be put into a free key-slot before the +key-slot containing the old passphrase is purged. If there is +no free key-slot, then the key-slot with the old passphrase is +overwritten directly. + +\fBWARNING:\fR If a key-slot is overwritten, a media failure +during this operation can cause the overwrite to fail after +the old passphrase has been wiped and make the LUKS container +inaccessible. + +\fB\fR can be [\-\-key-file, \-\-keyfile-offset, +\-\-keyfile-size, \-\-new-keyfile-offset, +\-\-new-keyfile-size, \-\-key-slot]. .PP \fIluksKillSlot\fR .IP -wipe key with number from LUKS device. A remaining passphrase or -key file (via \-\-key-file) must be supplied. - -\fB\fR can be [\-\-key-file, \-\-keyfile-size]. +Wipe the key-slot number from the LUKS device. A remaining +passphrase must be supplied, either interactively or via \-\-key-file. +This command can remove the last remaining key-slot, but requires +an interactive confirmation when doing so. Removing the last +passphrase makes a LUKS container permanently inaccessible. + +\fB\fR can be [\-\-key-file, \-\-keyfile-offset, \-\-keyfile-size]. + +\fBWARNING:\fR If you read the passphrase from stdin +(without further argument or with '-' as argument +to \-\-key-file), batch-mode (-q) will be implicitely +switched on and no warning will be given when you remove the +last remaining passphrase from a LUKS container. Removing +the last passphrase makes the LUKS container permanently +inaccessible. .PP \fIluksUUID\fR .IP -print UUID, if has a LUKS header. - -set new UUID if \fI\-\-uuid\fR option is specified. +Print the UUID of a LUKS device. +.br +Set new UUID if \fI\-\-uuid\fR option is specified. .PP \fIisLuks\fR .IP -returns true, if is a LUKS partition. Otherwise, false. +Returns true, if is a LUKS device, false otherwise. +Use option \-v to get human-readable feedback. 'Command successful.' +means the device is a LUKS device. .PP \fIluksDump\fR .IP -dumps the header information of a LUKS partition. +Dump the header information of a LUKS device. -If \-\-dump-master-key option is used, the volume (master) key is dumped -instead of keyslot info. +If the \-\-dump-master-key option is used, the LUKS device master key is +dumped instead of the keyslot info. Beware that the master key cannot be +changed and can be used to decrypt the data stored in the LUKS container +without a passphrase and even without the LUKS header. This means +that if the master key is compromised, the whole device has to be +erased to prevent further access. Use this option carefully. -Because this information can be used to access encrypted device without -passphrase knowledge (even without LUKS header) use this option -very carefully. +In order to dump the master key, a passphrase has to be supplied, +either interactively or via \-\-key-file. -Dump with volume key (either printed or stored to file) should be always -stored encrypted and on safe place. +\fB\fR can be [\-\-dump-master-key, \-\-key-file, +\-\-keyfile-offset, \-\-keyfile-size]. -LUKS passphrase or key file is required for volume key dump. - -\fB\fR can be [\-\-dump-master-key, \-\-key-file, \-\-keyfile-size]. +\fBWARNING:\fR If \-\-dump-master-key is used with \-\-key-file +and the argument to \-\-key-file is '-', no validation question +will be asked and no warning given. .PP \fIluksHeaderBackup\fR \-\-header-backup-file .IP -Stores binary backup of LUKS header and keyslot areas. +Stores a binary backup of the LUKS header and keyslot area. +.br +Note: Using '-' as filename writes the header backup to a file named '-'. + +\fBWARNING:\fR This backup file and a passphrase valid +at the time of backup allows decryption of the +LUKS data area, even if the passphrase was later changed or +removed from the LUKS device. Also note that with a header +backup you lose the ability to securely wipe the LUKS +device by just overwriting the header and key-slots. You +either need to securely erase all header backups in +addition or overwrite the encrypted data area as well. +The second option is less secure, as some sectors +can survive, e.g. due to defect management. +.PP +\fIluksHeaderRestore\fR \-\-header-backup-file +.IP +Restores a binary backup of the LUKS header and keyslot area +from the specified file. +.br +Note: Using '-' as filename reads the header backup from a file named '-'. -\fBWARNING:\fR Please note that with this backup file (and old passphrase -knowledge) you can decrypt data even if old passphrase was wiped from real device. +\fBWARNING:\fR Header and keyslots will be replaced, only +the passphrases from the backup will work afterwards. -Also note that anti-forensic splitter is not used during manipulation with backup file. +This command requires that the master key size and data offset +of the LUKS header already on the device and of the header backup +match. Alternatively, if there is no LUKS header on the device, +the backup will also be written to it. +.SH loop-AES EXTENSION +cryptsetup supports mapping loop-AES encrypted partition using +a compatibility mode. .PP -\fIluksHeaderRestore\fR \-\-header-backup-file +\fIopen\fR \-\-type loopaes \-\-key-file +.br +\fIloopaesOpen\fR \-\-key-file (\fBold syntax\fR) .IP -Restores binary backup of LUKS header and keyslot areas from specified file. +Opens the loop-AES and sets up a mapping . -\fBWARNING:\fR All the keyslot areas are overwritten, only active keyslots -form backup file are available after issuing this command. +If the key file is encrypted with GnuPG, then you have to use +\-\-key-file=- and decrypt it before use, e.g. like this: +.br +gpg \-\-decrypt | cryptsetup loopaesOpen \-\-key-file=- -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. +Use \fB\-\-keyfile-size\fR to specify the proper key length if needed. + +Use \fB\-\-offset\fR to specify device offset. Note that the units +need to be specified in number of 512 byte sectors. + +Use \fB\-\-skip\fR to specify the IV offset. If the original device +used an offset and but did not use it in IV sector calculations, +you have to explicitly use \fB\-\-skip 0\fR in addition to the offset +parameter. + +Use \fB\-\-hash\fR to override the default hash function for +passphrase hashing (otherwise it is detected according to key +size). + +\fB\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-skip, +\-\-hash, \-\-readonly, \-\-allow-discards]. .PP -For more information about LUKS, see -\fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR -.SH loop-AES EXTENSION -cryptsetup supports mapping of loop-AES encrypted partition using -compatible dm-crypt mode. +See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR +for more information regarding loop-AES. +.SH TCRYPT (TrueCrypt-compatible) EXTENSION +cryptsetup supports mapping of TrueCrypt or tcplay encrypted partition +using a native Linux kernel API. +Header formatting and TCRYPT header change is not supported, cryptsetup +never changes TCRYPT header on-device. + +TCRYPT extension requires kernel userspace +crypto API to be available (introduced in Linux kernel 2.6.38). +If you are configuring kernel yourself, enable +"User-space interface for symmetric key cipher algorithms" in +"Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). + +Because TCRYPT header is encrypted, you have to always provide valid +passphrase and keyfiles. + +Cryptsetup should recognize all header variants, except legacy cipher chains +using LRW encryption mode with 64 bits encryption block (namely Blowfish +in LRW mode is not recognized, this is limitation of kernel crypto API). + +\fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains +using LRW or XTS encryption modes. + +The \fBtcryptDump\fR command should work for all recognized TCRYPT devices +and doesn't require superuser privilege. + +To map system device (device with boot loader where the whole encrypted +system resides) use \fB\-\-tcrypt-system\fR option. Use the whole +device not the system partition as the device parameter. + +To use hidden header (and map hidden device, if available), +use \fB\-\-tcrypt-hidden\fR option. .PP -\fIloopaesOpen\fR \-\-key-file +\fIopen\fR \-\-type tcrypt +.br +\fItcryptOpen\fR (\fBold syntax\fR) .IP -opens the loop-AES and sets up a mapping . +Opens the TCRYPT (a TrueCrypt-compatible) and sets up a mapping . + +\fB\fR can be [\-\-key-file, \-\-tcrypt-hidden, \-\-tcrypt-system, +\-\-readonly, \-\-test-passphrase]. -N.B. If key file is in GPG encrypted format, you have to use -\-\-key-file=- and decrypt it before use. -gpg --decrypt | cryptsetup loopaesOpen \-\-key-file=- +The keyfile parameter allows combination of file content with the +passphrase and can be repeated. Note that using keyfiles is compatible +with TCRYPT and is different from LUKS keyfile logic. +.PP +\fItcryptDump\fR +.IP +Dump the header information of a TCRYPT device. -Use \fB\-\-key-file\fR to specify proper key length, default compiled-in -parameters are visible in \fB\-\-help\fR output. +If the \-\-dump-master-key option is used, the TCRYPT device master key is +dumped instead of TCRYPT header info. Beware that the master key +(or concatenated master keys if cipher chain is used) +can be used to decrypt the data stored in the TCRYPT container without +a passphrase. +This means that if the master key is compromised, the whole device has +to be erased to prevent further access. Use this option carefully. -Use \fB\-\-offset\fR to specify device offset. Note the units need to be -specified in 512 bytes sectors. +\fB\fR can be [\-\-dump-master-key, \-\-key-file, \-\-tcrypt-hidden, +\-\-tcrypt-system]. -\fB\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-readonly]. +The keyfile parameter allows combination of file content with the +passphrase and can be repeated. .PP -\fIloopaesClose\fR +See also \fBhttp://www.truecrypt.org\fR for more information regarding +TrueCrypt. + +Please note that cryptsetup does not use TrueCrypt code, please report +all problems related to this compatibility extension to cryptsetup project. +.SH MISCELLANEOUS +.PP +\fIrepair\fR .IP -identical to \fIremove\fR. +Tries to repair the device metadata if possible. Currently supported only +for LUKS device type. + +This command is useful to fix some known benign LUKS metadata +header corruptions. Only basic corruptions of unused keyslot +are fixable. This command will only change the LUKS header, not +any key-slot data. + +\fBWARNING:\fR Always create a binary backup of the original +header before calling this command. .PP -For more information about loop-AES, see \fBhttp://loop-aes.sourceforge.net\fR +\fIbenchmark\fR +.IP +Benchmarks ciphers and KDF (key derivation function). +Without parameters it tries to measure few common configurations. + +To benchmark other ciphers or modes, you need to specify \fB\-\-cipher\fR +and \fB\-\-key-size\fR options or \fB\-\-hash\fR for KDF test. + +\fBNOTE:\fR This benchmark is using memory only and is only informative. +You cannot directly predict real storage encryption speed from it. + +For testing block ciphers, this benchmark requires kernel userspace +crypto API to be available (introduced in Linux kernel 2.6.38). +If you are configuring kernel yourself, enable +"User-space interface for symmetric key cipher algorithms" in +"Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). + +\fB\fR can be [\-\-cipher, \-\-key-size, \-\-hash]. .SH OPTIONS .TP .B "\-\-verbose, \-v" -Print more verbose messages. +Print more information on command execution. .TP .B "\-\-debug" -Run in debug mode with full diagnostic logs. +Run in debug mode with full diagnostic logs. Debug output +lines are always prefixed by '#'. .TP -.B "\-\-hash, \-h" -For \fIcreate\fR action specifies hash to use for password hashing. +.B "\-\-hash, \-h \fI\fR" +Specifies the passphrase hash for \fIopen\fR (for plain and loopaes device types). -For \fIluksFormat\fR action specifies hash used in LUKS key setup scheme -and volume key digest. +Specifies the hash used in the LUKS key setup scheme and volume key digest +for \fIluksFormat\fR. -\fBWARNING:\fR setting hash other than \fBsha1\fR causes LUKS device -incompatible with older version of cryptsetup. +The specified hash name is passed to the compiled-in crypto backend. +Different backends may support different hashes. +For \fIluksFormat\fR, the hash +algorithm must provide at least 160 bits of output, which +excludes, e.g., MD5. Do not use a non-crypto hash like +\fB"crc32"\fR as this breaks security. -The hash string is passed to libgcrypt, so all hash algorithms are supported -(for \fIluksFormat\fR algorithm must provide at least 20 byte long hash). -Default is set during compilation, compatible values with old version of cryptsetup are -\fB"ripemd160"\fR for \fIcreate\fR action and \fB"sha1"\fR for \fIluksFormat\fR. +Values compatible with old version of cryptsetup are +\fB"ripemd160"\fR for \fIopen \-\-type plain\fR and +\fB"sha1"\fR for \fIluksFormat\fR. -Use \fIcryptsetup \-\-help\fR to show defaults. +Use \fIcryptsetup \-\-help\fR to show the defaults. .TP -.B "\-\-cipher, \-c" -set cipher specification string. - -Default mode is configurable during compilation, -you can see compiled-in default using \fIcryptsetup \-\-help\fR. -If not changed, the default is for plain dm-crypt and LUKS mappings -"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". - -For XTS mode, kernel version 2.6.24 or more recent is required. -Use "aes-xts-plain" cipher specification and set key size to 256 -(or 512) bits (see \-s option). +.B "\-\-cipher, \-c \fI\fR" +Set the cipher specification string. + +\fIcryptsetup \-\-help\fR shows the compiled-in defaults. +The current default in the distributed sources is +"aes-cbc-essiv:sha256" for both plain dm-crypt and LUKS. + +For XTS mode (a possible future default), use "aes-xts-plain" +or better "aes-xts-plain64" +as cipher specification and optionally set a key size of +512 bits with the \-s option. Key size for XTS +mode is twice that for other modes for the same +security level. + +XTS mode requires kernel 2.6.24 or later and plain64 requires +kernel 2.6.33 or later. More information can be found in the FAQ. .TP .B "\-\-verify-passphrase, \-y" -query for passwords twice. Useful when creating a (regular) mapping -for the first time, or when running \fIluksFormat\fR. +When interactively asking for a passphrase, ask for it twice +and complain if both inputs do not match. Advised when creating +a regular mapping for the first time, or when running +\fIluksFormat\fR. Ignores on input from file or stdin. .TP -.B "\-\-key-file, \-d" -use file as key material. +.B "\-\-key-file, \-d \fIname\fR" +Read the passphrase from file. -With LUKS, key material supplied in key files via \-d are always used -for existing passphrases, except in \fIluksFormat\fR action where -\-d is equivalent to positional key file argument. +If the name given is "-", then the passphrase will be read from stdin. +In this case, reading will not stop at newline characters. -If you want to set a new key via a key file, you have to use -a positional arg to \fIluksAddKey\fR. +With LUKS, passphrases supplied via \-\-key-file are always +the existing passphrases requested by a command, except in +the case of \fIluksFormat\fR where \-\-key-file is equivalent +to the positional key file argument. -If the key file is "-", stdin will be used. With the "-" key file -reading will not stop when new line character is detected. +If you want to set a new passphrase via key file, you have to +use a positional argument to \fIluksAddKey\fR. -See section \fBNOTES ON PASSWORD PROCESSING\fR for more information. +See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information. +.TP +.B "\-\-keyfile-offset \fIvalue\fR" +Skip \fIvalue\fR bytes at the beginning of the key file. +Works with all commands that accepts key files. .TP .B "\-\-keyfile-size, \-l \fIvalue\fR" -Limits read from key file to \fIvalue\fR bytes. -Usable together with all commands using key file. +Read a maximum of \fIvalue\fR bytes from the key file. +Default is to read the whole file up to the compiled-in +maximum that can be queried with \-\-help. Supplying more +data than the compiled-in maximum aborts the operation. + +This option is useful +to cut trailing newlines, for example. If \-\-keyfile-offset +is also given, the size count starts after the offset. +Works with all commands that accepts key files. +.TP +.B "\-\-new-keyfile-offset \fIvalue\fR" +Skip \fIvalue\fR bytes at the start when +adding a new passphrase from key file with +\fIluksAddKey\fR. .TP .B "\-\-new-keyfile-size \fIvalue\fR" -Limits read from new key file to \fIvalue\fR bytes in \fIluksAddKey\fR when -adding new key file. Default is exhaustive read from key file. +Read a maximum of \fIvalue\fR bytes when adding +a new passphrase from key file with \fIluksAddKey\fR. +Default is to read the whole file up to the compiled-in +maximum length that can be queried with \-\-help. +Supplying more than the compiled in maximum aborts the +operation. +When \-\-new-keyfile-offset is also given, reading starts +after the offset. .TP .B "\-\-master-key-file" -Use pre-generated master key stored in file. For \fIluksFormat\fR it allows -LUKS header reformatting with the same master key (if all other parameters -are the same existing encrypted data remains intact). +Use a master key stored in a file. + +For \fIluksFormat\fR this +allows creating a LUKS header with this specific +master key. If the master key was taken from an existing +LUKS header and all other parameters are the same, +then the new header decrypts the data encrypted with the +header the master key was taken from. + +For \fIluksAddKey\fR this allows adding a new passphrase +without having to know an exiting one. -For \fIluksAddKey\fR it allows adding new passphrase with only master key knowledge. +For \fIopen\fR this allows to open the LUKS device +without giving a passphrase. .TP .B "\-\-dump-master-key" -For \fIluksDump\fR it allows LUKS header dump including volume (master) key. -Use with care (this information allows access to device without passphrase knowledge). - -See \fIluksDump\fR for more info. +For \fIluksDump\fR this option includes the master key in the displayed +information. Use with care, as the master key can be used to +bypass the passphrases, see also option \-\-master-key-file. .TP .B "\-\-use-random" .TP .B "\-\-use-urandom" -For \fIluksFormat\fR it defines which kernel random number generator will -be used for long-term key (volume key). - -See \fBNOTES ON RNG\fR for more information. Use \fIcryptsetup \-\-help\fR -to show default RNG. +For \fIluksFormat\fR these options define which kernel random number +generator will be used to create the master key (which is a +long-term key). + +See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more +information. Use \fIcryptsetup \-\-help\fR +to show the compiled-in default random number generator. + +\fBWARNING:\fR In a low-entropy situation (e.g. in an +embedded system), both selections are problematic. +Using /dev/urandom can lead to weak keys. +Using /dev/random can block a long time, potentially +forever, if not enough entropy can be harvested by +the kernel. .TP -.B "\-\-key-slot, \-S" +.B "\-\-key-slot, \-S <0-7>" 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 \fIluksFormat\fR and \fIluksAddKey\fR. +This option can be used for \fIluksFormat\fR, +and \fIluksAddKey\fR. +.br +In addition, for \fIopen\fR, this option selects a +specific key-slot to compare the passphrase against. +If the given passphrase would only match a different key-slot, +the operation fails. .TP -.B "\-\-key-size, \-s" -set key size in bits. +.B "\-\-key-size, \-s " +Sets key size in bits. The argument has to be a multiple of +8. The possible key-sizes are limited by the cipher and +mode used. -Has to be a multiple of 8 bits. The key size is limited by the used cipher. +See /proc/crypto for more information. Note that key-size +in /proc/crypto is stated in bytes. -See output of /proc/crypto for more information. - -Can be used for \fIcreate\fR or \fIluksFormat\fR, 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 \fIcryptsetup \-\-help\fR to show defaults. +This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR. +All other LUKS actions will use the key-size specified in the LUKS header. +Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults. .TP -.B "\-\-size, \-b" -force the size of the underlying device in sectors. -This option is only relevant for \fIcreate\fR and \fIresize\fR action. +.B "\-\-size, \-b " +Force the size of the underlying device in sectors of 512 bytes. +This option is only relevant for the \fIopen\fR and \fIresize\fR +actions. .TP -.B "\-\-offset, \-o" -start offset in the backend device (in 512-byte sectors). -This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action. +.B "\-\-offset, \-o " +Start offset in the backend device in 512-byte sectors. +This option is only relevant for the \fIopen\fR action with plain +or loopaes device types. .TP -.B "\-\-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. +.B "\-\-skip, \-p " +How many sectors of the encrypted data to skip at the beginning. +This option is only relevant for the \fIopen\fR action with plain +or loopaes device types. + +This is different from the \-\-offset options with respect to +the sector numbers used in IV calculation. Using \-\-offset will shift the IV calculation by the same negative amount. -Hence, if \-\-offset \fIn\fR, sector \fIn\fR will be the first sector -on the mapping with IV \fI0\fR. Using \-\-skip would have resulted in sector -\fIn\fR being the first sector also, but with IV \fIn\fR. -This option is only relevant for \fIcreate\fR action. +Hence, if \-\-offset \fIn\fR, sector \fIn\fR will get a sector +number of \fI0\fR for the IV calculation. +Using \-\-skip causes sector \fIn\fR to also be the first sector +of the mapped device, but with its number for IV generation is \fIn\fR. .TP -.B "\-\-readonly" +.B "\-\-readonly, \-r" set up a read-only mapping. .TP -.B "\-\-iter-time, \-i" -The number of milliseconds to spend with PBKDF2 password processing. -This option is only relevant to the LUKS operations as -\fIluksFormat\fR or \fIluksAddKey\fR. -Note that 0 means default. +.B "\-\-shared" +Creates an additional mapping for one common +ciphertext device. Arbitrary mappings are supported. +This option is only relevant for the +\fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to +specify the mapped area. +.TP +.B "\-\-iter-time, \-i " +The number of milliseconds to spend with PBKDF2 passphrase processing. +This option is only relevant for LUKS operations that set or change +passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR. +Specifying 0 as parameter selects the compiled-in default. .TP .B "\-\-batch-mode, \-q" -Do not ask for confirmation. Use with care! This option is only relevant -for \fIluksFormat\fR, \fIluksAddKey\fR, \fIluksRemoveKey\fR or \fIluksKillSlot\fR. +Suppresses all confirmation questions. Use with care! + +If the \-y option is not specified, this option also switches off +the passphrase verification for \fIluksFormat\fR. .TP -.B "\-\-timeout, \-t" -The number of seconds to wait before timeout. This option is relevant every -time a password is asked, like \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR -or \fIluksAddKey\fR. It has no effect if used in conjunction with \-\-key-file. +.B "\-\-timeout, \-t " +The number of seconds to wait before timeout on passphrase input +via terminal. It is relevant every time a passphrase is asked, +for example for \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR. +It has no effect if used in conjunction with \-\-key-file. +.br +This option is useful when the system +should not stall if the user does not input a passphrase, +e.g. during boot. The default is a value of 0 seconds, +which means to wait forever. .TP .B "\-\-tries, \-T" -How often the input of the passphrase shall be retried. This option is relevant -every time a password is asked, like \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR -or \fIluksAddKey\fR. The default is 3 tries. +How often the input of the passphrase shall be retried. +This option is relevant +every time a passphrase is asked, for example for +\fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR. +The default is 3 tries. .TP -.B "\-\-align-payload=\fIvalue\fR" +.B "\-\-align-payload " Align payload at a boundary of \fIvalue\fR 512-byte sectors. This option is relevant for \fIluksFormat\fR. -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). +If not specified, cryptsetup tries to use the topology info +provided by kernel for the underlying device to get optimal alignment. +If not available (or the calculated value is a multiple of the default) +data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors). + +For a detached LUKS header this option specifies the offset on the +data device. See also the \-\-header option. .TP .B "\-\-uuid=\fIUUID\fR" -Use provided \fIUUID\fR in \fIluksFormat\fR command instead of generating -new one or change existing UUID in \fIluksUUID\fR command. +Use the provided \fIUUID\fR for the \fIluksFormat\fR command +instead of generating new one. Changes the existing UUID when +used with the \fIluksUUID\fR command. -The UUID must be provided in standard UUID format -(e.g. 12345678-1234-1234-1234-123456789abc). +The UUID must be provided in the standard UUID format, +e.g. 12345678-1234-1234-1234-123456789abc. +.TP +.B "\-\-allow-discards\fR" +Allow the use of discard (TRIM) requests for device. +This option is only relevant for \fIopen\fR action. + +\fBWARNING:\fR This command can have a negative security impact +because it can make filesystem-level operations visible on +the physical device. For example, information leaking +filesystem type, used space, etc. may be extractable from +the physical device if the discarded blocks can be located +later. If in doubt, do no use it. + +A kernel version of 3.1 or later is needed. For earlier kernels +this option is ignored. +.TP +.B "\-\-test-passphrase\fR" +Do not activate device, just verify passphrase. +This option is only relevant for \fIopen\fR action (the device +mapping name is not mandatory if this option is used). +.TP +.B "\-\-header\fR " +Use a detached (separated) metadata device or file where the +LUKS header is stored. This options allows to store ciphertext +and LUKS header on different devices. + +This option is only relevant for LUKS devices and can be +used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR, +\fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands. + +For \fIluksFormat\fR with a file name as argument to \-\-header, +it has to exist and be large enough to contain the LUKS header. +See the cryptsetup FAQ for header size calculation. + +For other commands that change the LUKS header (e.g. \fIluksAddKey\fR), +specify the device or file with the LUKS header directly as the +LUKS device. + +If used with \fIluksFormat\fR, the \-\-align-payload option is taken +as absolute sector alignment on ciphertext device and can be zero. + +\fBWARNING:\fR There is no check whether the ciphertext device specified +actually belongs to the header given. In fact you can specify an +arbitrary device as the ciphertext device for \fIopen\fR +with the \-\-header option. Use with care. +.TP +.B "\-\-force-password\fR" +Do not use password quality checking for new LUKS passwords. + +This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and +\fIluksChangeKey\fR and is ignored if cryptsetup is built without +password quality checking support. + +For more info about password quality check, see manual page +for \fBpwquality.conf(5)\fR. .TP .B "\-\-version" -Show the version. -.SH NOTES ON PASSWORD PROCESSING FOR PLAIN MODE -\fBFrom a terminal\fR: 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. - -\fBFrom stdin\fR: 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. +Show the program version. +.TP +.B "\-\-usage" +Show short option help. +.TP +.B "\-\-help, \-?" +Show help text and default parameters. +.SH RETURN CODES +Cryptsetup returns 0 on success and a non-zero value 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. +.SH NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE +Note that no iterated hashing or salting is done in plain mode. +If hashing is done, it is a single direct hash. This means that +low-entropy passphrases are easy to attack in plain mode. + +\fBFrom a terminal\fR: The passphrase is read until the +first newline, i.e. '\\n'. +The input without the newline character is processed with +the default hash or the hash specified with \-\-hash. +The has result will be truncated to the key size +of the used cipher, or the size specified with \-s. + +\fBFrom stdin\fR: Reading will continue until a newline (or until +the 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 and can +be overwritten using \-\-keyfile-size option. + +The data read will be hashed with the default hash +or the hash specified with \-\-hash. +The has result will be truncated to the key size +of the used cipher, or the size specified with \-s. + +Note that if \-\-key-file=- is used for reading the key +from stdin, trailing newlines are not stripped from the input. + +If "plain" is used as argument to \-\-hash, the input +data will not be hashed. Instead, it will be zero padded (if +shorter than the key size) or truncated (if longer than the +key size) and used directly as the binary key. This is useful for +directly specifying a binary key. No warning will be given if the amount of data read from stdin is -less than the keysize. +less than the key size. -\fBFrom a key file\fR: It will be cropped to the size given by \-s. -If there is insufficient key material in the key file, cryptsetup +\fBFrom a key file\fR: It will be truncated to the +key size of the used cipher or the size given by \-s +and directly used as binary key. +if the key file is shorter than the key, 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. -.SH 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. -.SH 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. +.SH NOTES ON PASSPHRASE PROCESSING FOR LUKS +LUKS uses PBKDF2 to protect against dictionary attacks +and to give some protection to low-entropy passphrases +(see RFC 2898 and the cryptsetup FAQ). + +\fBFrom a terminal\fR: The passphrase is read until the +first newline and then processed by PBKDF2 without +the newline character. + +\fBFrom stdin\fR: +LUKS will read passphrases from stdin up to the +first newline character or the compiled-in +maximum key file length. If \-\-keyfile-size is +given, it is ignored. + +\fBFrom key file\fR: +The complete keyfile is read up to the compiled-in +maximum size. Newline characters do not terminate the +input. The \-\-keyfile-size option can be used to limit +what is read. + +\fBPassphrase processing\fR: +Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), +the user may specify how much the time the passphrase processing +should consume. The time is used to determine the iteration count +for PBKDF2 and higher times will offer better protection for +low-entropy passphrases, but open will take longer to +complete. For passphrases that have entropy higher than the +used key length, higher iteration times will not increase security. + +The default setting of one second is sufficient for most +practical cases. The only exception is a low-entropy +passphrase used on a slow device. +.SH INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS +LUKS checks for a valid passphrase when an encrypted partition +is unlocked. The behavior of plain dm-crypt is different. +It will always decrypt with the passphrase given. If the +given passphrase is wrong, the device mapped by plain +dm-crypt will essentially still contain encrypted data and +will be unreadable. .SH 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. -.SH NOTES ON PASSWORDS -Mathematics can't be bribed. Make sure you keep your passwords safe. +For the \-\-hash option, if the crypto backend is libgcrypt, +then all algorithms supported by the gcrypt library are available. +For other crypto backends some algorithms may be missing. +.SH NOTES ON PASSPHRASES +Mathematics can't be bribed. Make sure you keep your passphrases 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. -.SH 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 \fP--use-random\fR and \fP--use-urandom\fR -options. Using /dev/random on system without enough entropy sources -can cause \fPluksFormat\fR to block until the requested amount of random data is gathered. +out of the blue, your brain refuses to cooperate. +These fallbacks need LUKS, as it's only possible with LUKS +to have multiple passphrases. Still, if your attacker model does +not prevent it, storing your passphrase in a sealed envelope somewhere +may be a good idea as well. +.SH NOTES ON RANDOM NUMBER GENERATORS +Random Number Generators (RNG) used in cryptsetup are always the +kernel RNGs without any modifications or additions to data stream +produced. + +There are two types of randomness cryptsetup/LUKS needs. One type +(which always uses /dev/urandom) is used for salts, the AF splitter +and for wiping deleted keyslots. + +The second type is used for the volume (master) key. You can switch +between using /dev/random and /dev/urandom here, see +\fP\-\-use-random\fR and \fP\-\-use-urandom\fR +options. Using /dev/random on a system without enough entropy sources +can cause \fPluksFormat\fR to block until the requested amount of +random data is gathered. In a low-entropy situation (embedded system), +this can take a very long time and potentially forever. At the same +time, using /dev/urandom in a low-entropy situation will +produce low-quality keys. This is a serious problem, but solving +it is out of scope for a mere man-page. See \fPurandom(4)\fR for more information. .SH 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). -.SH AUTHORS -cryptsetup is written by Christophe Saout -.br -LUKS extensions, and man page by Clemens Fruhwirth +Cryptsetup is usually used directly on a block device (disk +partition or LVM volume). However, if the device argument is a +file, cryptsetup tries to allocate a loopback device +and map it into this file. This mode requires Linux kernel 2.6.25 +or more recent which supports the loop autoclear flag (loop device is +cleared on last close automatically). Of course, you can +always map a file to a loop-device manually. See the +cryptsetup FAQ for an example. + +When device mapping is active, you can see the loop backing file in +the status command output. Also see losetup(8). .SH DEPRECATED ACTIONS .PP The \fIreload\fR action is no longer supported. @@ -452,16 +935,41 @@ directly manipulate with the device mapping table. The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR. .PP .SH REPORTING BUGS -Report bugs to or Issues section on LUKS website. -Please attach output of failed command with added \-\-debug option. +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +cryptsetup originally written by Christophe Saout +.br +The LUKS extensions and original man page were written by +Clemens Fruhwirth . +.br +Man page extensions by Milan Broz . +.br +Man page rewrite and extension by Arno Wagner . .SH COPYRIGHT Copyright \(co 2004 Christophe Saout .br Copyright \(co 2004-2006 Clemens Fruhwirth .br -Copyright \(co 2009-2011 Red Hat, Inc. +Copyright \(co 2009-2012 Red Hat, Inc. +.br +Copyright \(co 2009-2012 Milan Broz +.br +Copyright \(co 2012 Arno Wagner This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH SEE ALSO -LUKS website, \fBhttp://code.google.com/p/cryptsetup/\fR +The LUKS website at \fBhttp://code.google.com/p/cryptsetup/\fR + +The cryptsetup FAQ, contained in the distribution package and +online at +\fBhttp://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions\fR + +The cryptsetup mailing list and list archive, see FAQ entry 1.6. + +The LUKS on-disk format specification available at +\fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR