The Wayback Machine - https://web.archive.org/web/20061225094038/http://luks.endorphin.org:80/dm-crypt

It's all about cryptsetup

LUKS for dm-crypt is implemented in cryptsetup. cryptsetup-luks is intended as a complete replacement for the original cryptsetup. It provides all the functionally of the original version plus all LUKS features, that are accessable by luks* action.

Files

cryptsetup-luks-1.0.4.tar.bz2 - Stable source tarball

cryptsetup-1.0-3-i686-pc-linux-gnu-static.bz2 - Precompiled binary, version 1.0.3 for x86

cryptsetup-1.0.3-x86_64-pc-linux-gnu-static.bz2 - Precompiled binary, version 1.0.3 for amd64

News

(2006/10/13)

Version 1.0.4
Changes:

  • lib/setup.c: Added terminal timeout rewrite as forwarded by Jonas Meurer
  • Merged patch from Marc Merlin to allow user selection of key slot.
  • lib/setup.c (get_key): Applied patch from David H�rdeman for reading binary keys from stdin using the "-" as key file.
  • Applied patches from David H�rdeman to fix 64 bit compiler warning issues.
  • src/cryptsetup.c (yesDialog): Fix getline problem for 64-bit archs.
cryptsetup-luks-1.0.4.tar.bz2

(2006/04/05)

Version 1.0.3
Changes:

  • alignPayload patch Peter Palfrader
  • meaningful exit codes and password retrying by Johannes Weißl
cryptsetup-luks-1.0.3.tar.bz2

(2006/03/15)

Version 1.0.3-rc3
Changes:

  • Fix sector size of the temporary mapping to be an integral of the block's sector size.
  • More verbose error logging.
cryptsetup-luks-1.0.3-rc3.tar.bz2

(2006/02/25)

Version 1.0.3-rc2
Changes:

  • Change duplicate target checking in LUKS, so we attribute libdevmapper behaviour change in 1.02-02.
cryptsetup-luks-1.0.3-rc2.tar.bz2

(2006/02/22)

Version 1.0.3-rc1
Changes:

  • REVERT an incorrect default change. This change is NOT allowed as we are bound to the calling semantics of our cryptsetup heritage. This release candidate limits the default change to new LUKS volumes.
cryptsetup-luks-1.0.3-rc1.tar.bz2

(2006/02/21)

Version 1.0.2 - incompatible semantic change. Do not use.
Changes:

  • Bug fix from Bastian Blank in libdevmapper.c See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=344313
  • Prevent existing mapping from being removed when a mapping with the same name is added
  • Add timeout patch from Jonas Meurer
  • Verify passphrase for LUKS volumes per default. Verification is suppressed in batch mode (-q).
  • Change default mode complition to essiv:sha256. Warning: This introduces a dependency on the sha256 kernel module
  • Merge patch from Gentoo: change gettext(..) to _(..).
  • Add --version
  • Fixed two incompatibilities from my get_key rewrite with original cryptsetup.
  • Patch from Michael Gebetsroither to silent all confirmation dialogs.
cryptsetup-luks-1.0.2.tar.bz2

(2005/06/20)

Version 1.0.1
Changes:

  • 64bit bug in sha fixed thanks to Oliver Paukstadt.
  • Fixed hash inconsistancy bug between cryptsetup-luks and original for piped passwords.
  • confirmation dialog when purging the last key slot.
  • changed the disk layout generation to generate layouts that are readable directly from devices with blocksize != 512 (cdroms for instance..), though you still have to supply the -r flag when luksOpen'ing the device.
cryptsetup-luks-1.0.1.tar.bz2

(2005/03/25)

Version 1.0
Changes:

  • Man page added.
  • Rename luksInit to luksFormat.
  • Changed default LUKS key bits to 128.
  • LUKS dump command
cryptsetup-luks-1.0.tar.bz2

(2005/02/10)

Version 0.993.
Fixes:

  • A user reported endian messed headers after luksInit. Obviously, gcc doesn't like passing a struct on stack. If you have problems to luksOpen after luksInit, try this version. There will be a CVS or SVN repository soon to remedy this excessive version bumping. cryptsetup-luks-0.993.tar.bz2

(2005/02/09)

Version 0.992.
Fixes:

  • Previous version suffered from a race condition triggered by lazy dm-crypt buffer flushing of the kernel. This version uses direct blockwise I/O on the device. cryptsetup-luks-0.992.tar.bz2

(2005/02/08)

Version 0.991.
Correct two on-disk-format errors. Conversion from the flawed 0.99 header will happen automatically. cryptsetup-luks-0.991.tar.bz2

Changes:

(2005/02/05)

Version 0.99 is out!
Come and get it, while it's hot! cryptsetup-luks-0.99.tar.bz2

Changes:

  • adhere to the new on-disk format
  • add configurable PBKDF2 iteration delay, with "-i"
  • UUID support with luksUUID action
  • isLuks action for LUKS partition detection
  • syntax change for key files, to make distinction between opening keys and setting keys more consistant.
Fixes:
  • static compilation works again,
  • increase cipherName, cipherMode to accommodate large essiv description string
  • bug fix in get_key loop causing infinite reading from /dev/random

(2004/10/11)

POC Version 5:
* luksInit, luksOpen, luksAddKey are now able to deal with key files,
* new, more generic parsing structure for additional command line arguments
* totally changed key reading in get_key, dropped xgetpass, moved key processing to process_key
* partition header has a LUKS magic now

(2004/07/30)

POC Version 4: Stripped the internal Twofish implementation in favour of directly using dm-crypt. Better error handling, code cleanups aiming for ``merge-ability''. Include regression tests.

(2004/06/22)

POC Version 3: Proper handling of endianness for Twofish.

(2004/06/20)

The roadmap changed a bit: I'm not aiming for LILO/GRUB in the first place, but I will go for cryptsetup, a tool used to setup dm-crypt mappings similar to what's losetup been for cryptoloop. But since I will declare cryptoloop deprecated in a few months, I'm focusing on cryptsetup to implement a key setup procedure according to TKS1. The following patch is horrible wrt to error handling and spaghetti coding, but it is purpose is to serve as proof-of-concept patch to show, that the methods proposed are applicable.

Documentation

LUKS works by prepending a partition header (luks_phdr) to the partition, where setup information like cipher, keysize is stored as well as key slots. A key slots is holding an encrypted version of the master key. The master key is used to encrypt bulk data. It will never be stored to disk directly, but encrypted version of the master key will be stored. To be more precise, every version of the master key is encrypted by a different passphrase and stored a separate key slot. The user needs to provide one passphrase only, since any correct passphrase will restore a copy of the master key.

For simplicity, LUKS is using a fixed number of key slots. To add a new passphrase, the user has to provide an old, correct one to recover a copy of the master key, which can be encrypted to a free key slot with the new passphrase. Of course any key slot can be disabled by purging the data any time.

LUKS add 4 actions to cryptsetup, namely luksFormat, luksOpen, luksAddKey and luksDelKey. Although the names are quite self-explanatory I'll give brief examples of how to use them:

Initializing & Mapping

To test LUKS, you can use loop to make a blockdev out of any container file. The only requirement is that it's larger than 1mb. I'll use /dev/loop5 in the following examples.

# cryptsetup luksFormat /dev/loop5
Enter LUKS password: foobar
# cryptsetup luksOpen myvolumename /dev/loop5
Enter LUKS password: foobar
key slot 0 unlocked.
# ls -l /dev/mapper/myvolumename
brw-r-----  1 root root 254, 0 Jan  1  1970 /dev/mapper/myvolumename
# cryptsetup luksClose myvolumename

Adding Keys

# cryptsetup luksAddKey /dev/loop5
Enter any existing LUKS password: foobar
key slot 0 unlocked.
Enter new password for key slot: katze
# cryptsetup luksOpen myvolume /dev/loop5
Enter LUKS password: katze
key slot 1 unlocked.

Deleting Keys

# cryptsetup luksDelKey /dev/loop5 1
# cryptsetup luksOpen myvolume /dev/loop5
Enter LUKS password: katze
Command failed: No key available with this passphrase.

Using key files

cryptsetup-luks can also deal with key files. In general, files supplied by the -d switch are used for opening, and key files supplied as additional positional argument are treated to set keys. For instance, to set a key file on partition creation, call cryptsetup luksFormat blockdev keyfile. If you want to open a partition via a key file, call cryptsetup -d keyfile luksOpen blockdev mapping name. If you want add another key file using an existing key file, call cryptsetup -d existingkeyfile luksAddKey newkeyfile.

Converting to LUKS

At the moment there is no way, to convert to LUKS with an in-place dd.