DM-Crypt with LUKS

Introduction
The main purpose of this document is to describe the process of encrypting your system with DM-Crypt and cryptsetup-luks from the moment you start your Gentoo installation. It's worth pointing out that while this document was written for Gentoo based systems in mind, it should be generic enough to be used with other meta-distributions as well.

DM-Crypt is part of the kernel that handles the disk encryption. The advantage of using DM-Crypt is that maintaining patches to meet the current kernel version is less problematic. LUKS is a standard that is platform independent and software independent meaning that you can access your LUKS volumes on Windows machines assuming that the filesystem chosen uses a compatible filesystem like NTFS or FAT32. FreeOTFE makes this possible. Cryptsetup is the CLI frontend for the backend DM-Crypt that you will be using.

Alternatives
An alternative to dm-crypt is loop-AES by Jari Ruusu. It's up to you to investigate which one suits your needs best.

Important
Please note that this document does not use Gentoo's utility to generate the initramfs. The guide uses its own custom init script (not distro specific) and has a "get your hands dirty" approach.

A simpler approach requiring fewer manual modifications is available by following the Gentoo-luks instructions. They should make your life easier.

Why?
People against the use of cryptography might argue that "if you're innocent, you have nothing to hide." In a utopian society this would be true; unfortunately the world is not black and white, there is a lot of grey in between.

It's not the objective of this document to convince you to use cryptography. You might, however, find the following papers interesting.
 * The Eternal Value of Privacy
 * by Bruce Schneier


 * Why I wrote PGP
 * by Philip Zimmermann

Back on topic, by encrypting your system you're not only protecting sensitive data your system might contain, you're also ensuring that the system won't get compromised by someone with physical access to it.

Now let's talk about what encrypting your system won't protect you against:
 * Someone wiping out your disk(s).
 * Someone breaking into your system from your network (internet).
 * Someone steals your computer when it's on (notebook OR desktop). (1)
 * Someone plants a hardware keylogger when you're sleeping. (2)
 * Someone tortures you to death to get the passphrase. (3)

''(1) - Authorities have a tool that allows them to extract a desktop/server from a running environment while not disrupting power. Two ways to deal with this are: a) Rebooting the system automatically when a paired bluetooth device is lost, or b) rebooting when the network is disconnected''

(2) - If you use a keyfile on a removable media(USB-stick) this doesn't quite apply to you anymore.

(3) - More about this on the next section.

Why squashfs+aufs2
Well nothing particular or... speed up your system and get rid of some annoying waiting especially for laptops. See this thread for more info. Do you want to speed up your system? Do you want to save much more more inodes that you never hoped for? Waste a single minute or less for restoring a rm-ed system directory/files--after rm-ed usr, for example,--? Have your laptop as fast as it could be,--as fast as a desktop,--without a 7200rpm disk that could eat up your battery/battery life? And much more...
 * after squashing usr:opt, your system will be very fast;
 * portage:layman:cache:db:edb for gentoo users, your emerge -s/e/c/avDuN/pv atom/world/set or revdep-rebuild -ip wont be anything like your previous unsquashed system;
 * recover a whole rm-ed system dir/fies in less than a minute: after rm-ed a squashed usr, I don't remember re-installing my system, a single minute to restor usr.sfs and everything was set up running again;
 * save hundreds of thousands of inodes for your root partition;
 * save muche more space of your root partition: after rm-ed the real usr:opt:*/portage:var/lib/layman:var/db:var/cache/edb your system will take a much less space--my system only take less than 3GB which was roughly 10GB before with hundreds of thousands of inodes;--

Keyfiles on removable media
Keyfiles stored on removable media (such as a USB stick) provide protection against a rubberhose attack (torture). In this situation, the passphrase exists solely on the removal media. As you do not know the passphrase, you cannot reveal it, regardless of the amount of torture applied to you.

This depends heavily upon the total destruction of the removable media - if it is destroyed, the encrypted data it protects can never be recovered.

Loop Back Device encrypted key file using LUKS
This method provides a fast and simple way to achieve a high security level. You don't need to bother with GnuPG in your initramfs because you can not easily get gpg to work in your initramfs. Futhermore, you don't have to add a 2MB executable in your initramfs, neither compiling a static version in the first place. Details on how to create an encrypted key-file with loop back device is here Initramfs.

GPG-protected keys
GPG-protected keys provide protection from an attacker managing to obtain removable media that contains keyfiles. Unlike regular keyfiles, an attacker would need a secondary passphrase to decrypt the keys. This comes with the drawback of having to enter a GPG passphrase upon each boot.

Plausible deniability
plausible deniability involves the possession of encrypted data which cannot be proven to exist. This is often done by using steganography. Keys hidden in this way are currently not supported by the init script.

To implement this, check out StegFS and Scubed.

Two things to remember

 * Security = Usability-1
 * There is a fine line between being paranoid and not being in touch with reality.

Minimum Requirements

 * Kernel: >= 2.6.10
 * Udev support Gentoo Udev Guide
 * Minimal Gentoo Live-CD or similar with proper kernel configuration (1)
 * Patience

You can use zgrep  /proc/config.gz to check whether your kernel meets the requirements. Look for the following options:
 * CONFIG_BLK_DEV_DM=y
 * CONFIG_DM_CRYPT=y
 * Kernel >= 2.6.19: pay attention to the new SATA configs and enable CONFIG_CRYPTO_CBC=y

You can see the available ciphers by doing cat /proc/crypto. Some Live-CDs have ciphers available as modules instead of built-in, so you might need to load them first.

''(1) It is recommended that you use a multi-purpose Live-CD such as Knoppix (or the new Gentoo Live-CD), because minimal Live-CDs aim to be … minimal, and may lack some of useful tools or ciphers for you to use. However, the minimal install CD snapshots provided in the release/ /autobuild directory of your favorite gentoo mirror should work as they provide almost all ciphers according to http://bugs.gentoo.org/245655.''

Before you begin
Since you will be encrypting your system from the moment you start your Gentoo installation, you'll need to divert a lot from the official Gentoo Installation guide.

To make your life easier, the guide contains links to the Gentoo Installation guide sections when needed, so just fire up lynx (or links2) in its own virtual console and keep reading.

You should consider turning write caching off for your disk. The reason is that write caching stores the I/O data on its own volatile memory before writing it to the disk. So in the event of a power failure, data loss and filesystem corruption might happen (even on journaling filesystems).

You can use hdparm to turn write caching off. Kernels >=2.6.15 now use the ATA passthru from Jeff Garzik by default, so patching the kernel is no longer required.

UPS powered systems don't have this problem and it is safe to turn write caching on.

Laptop users: make sure you shutdown/suspend the system when it's low on battery (write a script or something).

Begin
Follow the Gentoo installation guide until you reach section 4 (Preparing the Disks).

Checking the hard disk for errors
badblocks output

Filling the disk with random data
Note: using an SSD to store confidential data needs more consideration because of the way that an SSD relocates data in order to provide "wear levelling". Should an attacker have unfettered physical access to the drive, they will be able to read data that the operating system appeared to have overwritten by bypassing the flash controller. Even if you filled the entire disk, there's a large amount of "hidden" space for wear levelling that will contain previously written and now discarded data. You should instead consider using an SSD that does its own encryption.

When you checked the disk for bad blocks it was filled with not-so-random data; now you're going to fill it again, but this time you're going to use which produces "random" data.

Doing this before you actually start storing encrypted data on the disk makes it practically impossible to know how much data has been written, therefore breaking it becomes much harder.

Below is a list of possible ways to fill the disk with random data:
 * Badblocks:
 * badblock uses 'libc' random, but is fast (your limitation will be disk speed, not CPU speed).


 * will fill the disk with "random" data. It won't be as random as though, but it's the best practical solution available. It will protect you against a full cryptoanalytic attack better than badblocks.
 * will fill the disk with "random" data. It won't be as random as though, but it's the best practical solution available. It will protect you against a full cryptoanalytic attack better than badblocks.


 * shred:
 * From the man page: shred overwrites the specified FILE(s) repeatedly, in order to make it harder for even very expensive hardware probing to recover the data. Shred looks better than just dding /dev/urandom since it does many writes (default 25, changed with -n option) and still takes input from /dev/urandom by default (changed with --random-source option). There's even a -v option which shows the progress. Note that the purpose of shred is to totally obliterate any data currently on a disk. Only the final pass of shred is useful on a brand-new disk. In such a case, you may as well just dd from /dev/urandom directly, which is about 25 times faster than using shred (in the default case).


 * In theory, this is the best way to fill your disk with random data, since it is much more random than any of the above. It works by using the kernel entropy pool, so if you run out of entropy it will kind of freeze. You can see what this means by doing ; it will eventually stop. Now move your mouse to produce some more entropy for the kernel to use.
 * In theory, this is the best way to fill your disk with random data, since it is much more random than any of the above. It works by using the kernel entropy pool, so if you run out of entropy it will kind of freeze. You can see what this means by doing ; it will eventually stop. Now move your mouse to produce some more entropy for the kernel to use.

filling your disk with (pseudo-)random data

This usually takes a really long time to finish (depending on your harddisk). Just to give you an idea: on an 80GB SATA drive it took around 12 hours. The process is CPU bound as it took 23 hours to fill a 320GB drive on my AMD64 3500+ and two-and-a-half days to fill a 120GB drive on a dual Pentium II 400Mhz machine. And if you happen to have another linux box on the network, you can netcat the urandom bits from the network box to fill in different part of disk in parallel: (Also works to run one dd process per core you have) Parallel filling your disk with (pseudo-)random data

filling repeatedly your disk with (pseudo-)random data

Partitioning Scheme
Partitioning scheme

Now follow the Gentoo Installation Guide until you reach step 4.e (Creating Filesystems).

Create mapping between logical and physical partitions
The physical (encrypted) root partition will be /dev/sda3

The logical (unencrypted) root partition will be /dev/mapper/root

This document uses the serpent and blowfish ciphers. You can use whichever you want, though. Please refer to a subsection for more information on ciphers.

Loading necessary modules
The modules you need to load depend on the ciphers you plan to use. Please see this subsection for some information about different available ciphers, and of course edit the commands accordingly.

Loading modules

cryptsetup-luks executable
For all actions described from now on, you need a working cryptsetup-luks binary for your host platform.

If your Live-CD doesn't provide one you need to get it from somewhere else. Luckily for us a static precompiled cryptsetup-luks binary exists on.

cryptsetup(-luks) executable

You can check whether your Live-CD contains the LUKS version of cryptsetup with. If you don't see any options with "luks" in them your Live-CD doesn't have it.

Encrypting swap for installation
First you will encrypt swap for use during installation. This is important because you don't want the encryption keys swapped to an unencrypted disk.

Encrypting swap for installation (not for suspend2 users)

Hibernation users
The above example does not use LUKS and it reads the key from. For most setups this is appropriate, but not in your case because the hibernation image needs to be preserved between reboots.

You've to treat the swap partition just as if it were a regular partition, meaning you should encrypt it like it's explained in the "Creating the mapping(s)" section.

Randomly generated keys (optionally, encrypted with GnuPG)
If you plan to use randomly generated keys for your partition(s) and (optionally) encrypting the keys with GnuPG, then keep reading. Otherwise continue on the next section.

Randomly generated keys are better than passphrases for two reasons:
 * Passphrases created by humans are weaker than ones created randomly by modern computers.
 * No dictionary based attacks can be performed by an attacker.

Again, this is an extract from the loop-AES README stating the importance of having the swap partition encrypted.

''In the following examples the random keys are encrypted with gpg. If you want to use random keys as regular keyfiles do not pipe the output into gpg.''

Encrypting randomly generated keys with gpg
You'll need the uuencode utility (emerge sharutils</tt>) and GnuPG (emerge gnupg</tt>). Make sure you install gnupg-1.4.* or you'll get gpg-agent errors. Unfortunately not many Live-CDs ship with them. If this applies, these are your options:
 * Build the utilities first on a working system and copy the binaries (statically linked) to the Live-CD.
 * Create the encrypted keys on another system (do not store the keys on an unencrypted disk, and make sure swap is encrypted).
 * Find a Live-CD that contain the utilites.
 * Use passphrases for now. You can add (change) the gpg encrypted randomly generated keys later (once you're on the chrooted system you can emerge the utilities).

Instructions: head -c 45 /dev/random | uuencode -m - | head -n 2 | tail -n 1 | gpg --symmetric -a >./ key.gpg Explanation of command above:
 * 1) substitute with the partition this key is intended (eg:rootkey.gpg)

The head</tt> command is used to output the first lines (parts) of files.

head -c 45</tt> tells it to print the first 45 bytes generated from, which is large enough to generate a strong key.

The uuencode</tt> utility is used for binary to text encoding. The -m</tt> argument tells it to use base64 encoding.

Next comes head -n 2</tt>, tail -n 1</tt>. head</tt> outputs the first 2 lines and tail</tt> prints the last line.

Why?

Because the output before the two commands are executed looks like this: begin-base64 644 - ==== To finish up, the output (random key) is piped into gpg, which encrypts it using a symmetric cipher.

Note: ''The default symmetric cipher used is CAST5, but another may be chosen with the --cipher-algo option. (man gpg)''

Randomly generated key (another example)
Another way of generating a random key is using the dd</tt> utility. dd if=/dev/random count=1 | gpg --symmetric -a >./ _key.gpg

Warning:

If you cat a binary file, your terminal or tty might get corrupted!

If it does, type 'reset' and press enter, this should restore it.

Warning:

this method can generate keys with really short length (e.g 8 bytes )

Creating the mapping(s)
It's time to create the mapping for the partitions, repeat the steps below for every partition you want encrypted.

Since passphrases are the weakest link in all security implementations, Diceware is suggested to create strong, yet easy to remember passphrases.

Make sure you remember your passphrase.

If you ever forget it, it's game over.

Using a 256-bit key size means that if your data was under a brute force attack, the attacker would have to search among 2256 possible passphrases.

Such attack is practically impossible(for now).

{{Code|Creating the mapping for the / partition| Note: Feel free to substitute the cipher used (see this subsection for information on ciphers).

Example 1: partition: root -- key: passphrase cryptsetup -y --cipher serpent-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda3 WARNING!

=
This will overwrite data on /dev/sda3 irrevocably.

Are you sure? (Type uppercase yes): YES Enter LUKS passphrase: (enter your passphrase, and write it down somewhere!) Verify passphrase: (repeat passphrase) Example 2: partition: root -- key: keyfile cryptsetup -v --cipher serpent-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda3 /path/to/rootkey Example 3: partition: root -- key: gpg protected key

Make sure you enter the correct passphrase, if you see any "gpg decryption failed" messages, luksFormat again. gpg --quiet --decrypt rootkey.gpg | cryptsetup -v --key-file=- --cipher serpent-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda3 }}
 * 1) You can see it worked by using luksDump.
 * 2) If don't trust if it worked or not you can enter the key
 * 3) as a passphrase when "luksOpening" the partition.

Opening the LUKS partition.

It's time to open the LUKS partition, this will create the root mapping in. Opening LUKS partition

From now on, every time you have to operate on your root partition you must do so using.

Creating the filesystem on the logical root partition
Example from ref1

Create the filesystem for the partition as indicated on the Gentoo Installation Guide, but do not initialize or activate the swap partition since you already did this on a previous step.

Mounting the filesystem(s)
mounting partitions

Now follow the Gentoo Installation Guide from step 5, until you reach step 7.c (Default: Kernel Manual Configuration).

Choosing a hibernation implementation with dm-crypt
Hibernation allows you to save all running programs conditions before the machine powers off. When it powers off, you can resume immediately where you left off without needing to waste time waiting for loading programs. Here we describe dm-crypt support and the possibility of dataloss. We recommend any of the two either swsusp or TuxOnIce.


 * Suspend2:This was an older implementation included in the init script and now continues on as TuxOnIce.


 * swsusp:This suspend implementation is built in the kernel. The advantage of using this implementation is that it in mainline and also easy to use.  The disadvantage is that it is no longer in active development.  You can find this impelementation on a vanilla kernel.  The updated init script supports this.


 * TuxOnIce:This is project is still maintained and updated since 2009 and more up to date than suspend2 and swsusp. It has more features such as hibernating to a swap file, compressed hibernated images, etc.  It requires tuxonice-sources.  The updated init script now supports this for swap.

DM-crypt init scripts handling of hibernation
The init script provided will take care of all three implementations. You will need to adjust the kernel parameters. But what the script does is decrypts the partitions as soon as possible before hibernation implementations can read the hibernation images. As mentioned before, if you want to provide encryption to the partitions you need to partition it as a swap partition and "cryptsetup luksFormat" it instead of "cryptsetup create" it then mkswap it, etc. When you open up the swap partitions containing the hibernation images, you will not "cryptsetup create" it using /dev/urandom as key.

Hibermation is fine for single user on one machine but one problem is the possibility of having multiple users on the machine. In this case, you can only have one person decrypt this partition or else they will resume and access your decrypted data.

Squashed directories
Here is a script to squash directories and an init script which takes care of mounting directories. More info can be found in the forums: topic:6694283 or topic:646289 or here for a dedicated topic for the alternate script.

The following scripts will automate [re-|]building squashed directories. It's better to mount usr:bin:sbin:lib{32,64} in initramfs script if those directories are wiped out, however, with a little care of need|before|afer dependencies, one can achieve the same result with `/etc/init.d/sqfdmount' init service. Note that, with the following script, it can handle mounting a wiped out usr directory before a few vital boot services. I don't recommend wiping bin:sbin:lib{32,64} because it won't save any significant space and those directories are necessary to boot in case of an issue for example. However wiping usr may be necessary because it will reduce the system size footprint.

Creating initramfs image
Before you continue with configuring your kernel(Step 7.c of Gentoo Installation Guide), you need to create an initramfs.

What's an initramfs and why do I need one ?

Since the root partition is encrypted, it has to be decrypted during the boot process, this task is not done by the Linux kernel, so it has to be done in userspace.

Enter early userspace:

Fine.., but what is an initramfs ?

An initramfs image is a gzipped cpio format archive, which in our case, when extracted into rootfs by the kernel, becomes the early userspace responsible for decrypting the root partition.

You probably have more questions, so for your convenience and mine, below is a list of documents that will explain it better than I can:
 * initramfs howto v3 -- backup
 * ramfs, rootfs and initramfs -- backup
 * ramfs, rootfs and initramfs -- backup

Dracut
Dracut is a sophisticated, yet quite easy to use tool for modularized initramfs creation from Red Hat. It is based on fully POSIX-compliant shell scripts which take care of finding all your volumes and key devices automatically or according to specified parameters at boot time. Especially in combination with Plymouth, dracut makes for a production quality boot frontend even for sophisticated encryption schemes, compared to handrolling your own tools and init scripts in the initramfs. It is always good to understand what's going on underneath though, so handrolling your own at least once is likely to make you understand and appreciate dracut's system even more.

Busybox
BusyBox - The Swiss Army Knife of Embedded Linux.

This document uses BusyBox for the initramfs image.

BusyBox:
 * "BusyBox combines tiny versions of many common UNIX utilities into a single small executable. It provides minimalist replacements for most of the utilities you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox generally have fewer options than their full-featured GNU cousins; however, the options that are included provide the expected functionality and behave very much like their GNU counterparts."


 * "BusyBox is a multi-call binary. A multi-call binary is an executable program that performs the same job as more than one utility program. That means there is just a single BusyBox binary, but that single binary acts like a large number of utilities. This allows BusyBox to be smaller since all the built-in utility programs (we call them applets) can share code for many common operations."

So, what does the above mean and why do I care ?

It means you will no longer have to go through the long and tedious process of finding the shared libraries dependencies for each utility(ls, cp, bash, etc..).

Instead of having separate utilities, you'll have one multi-call statically linked binary(BusyBox).

You also care because it'll save you time and it'll make the initramfs image smaller.

Choosing a C library (uClibc, glibc)
You need to decide which C library will be used to build BusyBox.


 * uClibc (recommended)
 * C library for developing embedded Linux systems.
 * This tiny C library is well suited for small embedded usage like this, plus it's what BusyBox developers recommend.
 * It currently doesn't support all architectures, if this is your case you'll have to use glibc.


 * glibc
 * GNU C library.
 * Not designed for small embedded usage, the size of the resulting binaries will much be bigger(>500k), it's not a big problem since the space occupied by the initramfs image gets deleted from memory when switching to the decrypted root.
 * It works, so use it if you can't use uClibc or simply don't want to create the uClibc toolchain.


 * klibc
 * The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is designed to be a tiny C library to statically link early userspace code against, along with some related utilities.
 * You won't be able to build BusyBox with it.
 * If you want to use it, you need to read the documentation listed in this section.
 * klcc is a a  wrapper  around gcc(1) and ld(1) which compiles and links a program against the klibc tiny C library.

Building BusyBox
Download BusyBox and extract it and go into its directory. Gentoo users can do this instead so it applys ebuild patches if any

Gentoo users

Next, you will have to configure it, first do the following to configure busybox with default options with additional adjustments:

Or if you're extremely desperate for space for your removable device, you can minimally configure for the init script needs by doing the following:

For uClibc users, you need to adjust the cross compiler prefix properly (i386-uclibc-) with the following command and run it

When you're done configuring BusyBox, enter. This will make a statically linked busybox executable. You also need the busybox.links file, which will be required for the creation of symlinks to the BusyBox binary for all the chosen shell commands.

Generating a kmap(binary keyboard translation table)
If you use a non US keyboard, you need to create a kmap(keymap) for it, otherwise you will have a hard time entering passphrases.

A kmap is a binary keyboard translation table for use with BusyBox's loadkmap utility, it's different from loadkeys, so you need to generate a kmap from the current loaded keymap.

The documentation for generating kmaps is quite scarce, it's a simple procedure so it will be explained below.

Generating the kmap

Save the kmap you just created because it'll be included into the initramfs image later.

''If you need to load a font(most people don't need to worry about this), have a look at /usr/share/consolefonts, you've to decompress the font you plan to use and don't forget to include it into the initramfs image later.

Initramfs's init
When you boot your system, the kernel will extract the initramfs cpio archive into rootfs(a special instance of ramfs) and will check if a file named "init" exist, if found it will execute it as PID 1(parent of all process).

This init process is then responsible for bringing the system the rest of the way up, in our case, its job will be to decrypt the root partition and switch to it, delegating the rest of your system boot process to the normal init.

The init script below is intedend for users following this document, please read its instructions(comments) before using it.

It's worth pointing out that it's not Gentoo specific, therefore it can be used no matter your distribution.

'''The link below for the new init script is broken. The new tuxonice wiki requires a login. There is no way to create a login. Will someone please post a working, up-to-date init script?'''

''Please, do not edit the script in the wiki directly, send changes to me(reikinio at gmail dot com) instead, thank you. ''

busybox 1.2.2.1 (and up?)

As you can see, the init script is quite big, if you find it hard to understand you might find the ABS guide helpful.

The script has its own set of arguments, look at the list below to understand what each one does.

You can see some examples in the init script comments, and later in the guide when configuring the bootloader.

About keys


 * regular keyfile
 * It'll be passed to cryptsetup as a "--key-file" argument.
 * gpg protected keyfile
 * It'll be decrypted and piped into cryptsetup as if it were a passphrase, the reason is quite simple, after reading in Peter Gutmann's paper that data could theoretically be recovered from volatile memory(RAM), I refrain from storing encryption keys in memory unprotected.
 * Since the key will be piped into cryptsetup, the latter will stop reading from input as soon as it encounters a "\n" (newline/linefeed) character, therefore it will only work if you used the same method(or entered the key yourself as a passphrase) when you "luksFormatted" the partition.
 * It will fail if you first decrypted the gpg file and then used it as an argument of "--key-file" when you "luksFormatted" the partition because in this case the "\n" character is part of the key.
 * This command erases the "\n" character:

Alternate init script with LVM2+squashfs+aufs+loop back encrypted keyfile+TuxOnIce
This is a major update/re-write intended first to satisfy the title requirements, but it ended up by updating/re-writing the whole script. The last update and comments can be found git repository or topic 879125.

Initramfs's structure
Structure -- BusyBox's applets not printed.


 * /etc/applets (download)
 * This file is a list of required BusyBox's applets for correct init execution, init will check if the applets listed are available and it'll abort if one is missing, it's optional and can be disabled in the init script.


 * /etc/msg
 * This file is used to print a message, you can use it to display ascii art to spice things up(like in the screenshot).
 * Just search the web for "ascii art"(skull).

Building initramfs image
Package: sys-fs/cryptsetup-luks Description Tool to setup encrypted devices with dm-crypt Developer: Clemens Fruhwirth License: GPL-2 Website: http://luks.endorphin.org/

An initramfs image is a gzipped cpio archive that will be unpacked into rootfs by the kernel, there're several ways to build such an archive but only one will be documented here.

The method used here is to populate a directory with initramfs's contents, and compressing it with the cpio and gzip utilities.

If you want to learn about other methods, this is what you want to read:
 * initramfs howto v3 -- backup
 * ramfs, rootfs and initramfs -- backup

Building initramfs image

fbsplash(Gensplash) suspend2 Compressing directory

Scripts to automatically build initramfs for this project
The following code will automatically generate an initramfs for cryptsetup-luks in your current directory. It will statically build cryptsetup, gpg 1* (hopefully 1.x), busybox. It also good if you decide to update your initramfs sometime in the future.

tree structure

You will need to copy the init from the above section 12.3 into your current directory.

makeinitramfs

Change DESTDIR to point to your usb disk, floppy, or boot folder.

Kernel Configuration
initramfs:

The initramfs image can be built into the kernel or passed from the bootloader, it's up to you to decide which method to use, if in doubt use the latter.

All 2.6.* kernels include a default initramfs if none is provided by the user, this initramfs gets created automatically when you compile the kernel.

In most systems it is ignored and the kernel falls back to legacy boot code.

initramfs built into the kernel:

The only thing you've to do is place your initramfs in. initramfs built into the kernel

Users with partition:

Copy the kernel to, plus the initramfs archive if you're going to pass it via the bootloader.

Users booting with usb-stick:

Copy the kernel to plus the initramfs archive if you're going to pass it via the bootloader, of course you have to do this after formatting the partition(next section).

Follow the Gentoo installation guide until you reach step 8.a

/etc/fstab
This section is only here to remind you to use mapping names and not the real devices.

Adjust it to suit your system.

Follow the Gentoo installation guide from step 8.b until you reach step 10(Configuring the Bootloader)

Bootloader configuration
GRUB:

extlinux:

Intended for people booting from usb-stick.

Booting from usb-stick
This section explain the steps to prepare an usb-stick to boot with an encrypted root partition. The kernel, keyfiles and (optional) the initramfs archive are stored on the usb-stick.

The procedure is similar to the one found on loop-AES README(section 7.7), with the exception that extlinux will be used instead of syslinux.

Requirements
 * Make sure your motherboard supports booting from a USB device.
 * Make sure you enable the proper BIOS options.
 * Make sure that you have a 16 MB or larger USB stick
 * Both USB 1.1 and USB 2.0 versions should work

extlinux is bootloader which boots from a Linux ext2/ext3 filesystem.

USB-stick - extlinux

Decrypting/Encrypting partitions at startup
This is handled by Gentoo's implementation scripts, you get them if you install  through portage.

Gentoo users can use this file to control which(and how) partitions should be decrypted.

Its documentation is available as comments inside the configuration file.

Gentoo users should use this file to decrypt all partitions(beside root) while system startup.

Non Gentoo users will have to check if their distribution has something similar, if not, they will have to write the scripts themeselves.

How to use (enough to get you started, but read its documentation as well):

The examples in are a bit confusing since they set the source to a device-mapper file instead of the underlying device and don't indicate where to specify the mount point. Here is an example of how to mount at startup using.

Plain-text and GnuPG-encrypted key files are supported; check the examples in the default version of the file for more information on the subject. First, for your encrypted drives and partitions excluding the root mount point add dmcrypt entry so that the mappings can be setup. Here is an example for the /home directory

We also need to mount the swap partition which uses swap= instead of target=. To do that add:

Note that by default, the scripts encrypt the swap with aes and uses sha1 for password hash. We want to be consistent with the crypto algorithm in the beginning of this guide used on the swap drive.

Second, add an fstab entries so that the mount point of the encrypted filesystem can be determined. If your hibernating to a swap partition it is safe to add your swap partition to fstab.

The last step
last steps

The End.

Support

 * Dm-crypt, cryptsetup-luks related support should be done in their mailing lists.
 * Support.
 * Before asking questions, please read the FAQ first, thank you.

Contributing
It's an open document and people are invited to contribute, only with your help it can become better, there are several ways to contribute:
 * Fixing typos.
 * Adding more content, explaining the rationale behind a step is always welcomed.
 * Helping people on the Gentoo's forums support thread.
 * Adding instructions and implementing the stuff on the ToDo list(see Discussion)
 * Fixing bugs on the init script.
 * Sharing some cool script you've made.
 * Mantaining the document, watch changes other people have made.
 * Peer review of the document and the init script.
 * Answering questions in the FAQ section.

Guidelines:
 * Do not remove content, even if you think you're right, post your reasons on the discussion page.
 * Be careful when fixing command typos.
 * Use the wiki code, examples are all over this guide, and you can get more information by pressing the "Help" link in the gentoo-wiki index.

Since the gentoo-wiki's notifications of the discussion page sometime seems to get lost, if you see that after some time I've not responded, drop me an email.

Thank you, and if you are helping out, it would be nice if you add your name to the Author(s) section.

Child Documents

 * Encrypting loopback devices

Ciphers
Some of the available ciphers/hash-functions found on the cryptographic kernel menu:


 * Blowfish
 * Serpent
 * AES
 * Twofish
 * DES
 * CAST5
 * CAST6
 * SHA*
 * Tiger
 * RIPEMD

FAQ
Please see LUKSFaq as well.

Deleting passphrases
 * How do I delete a LUKS passphrase ?

Changing passphrase for /
 * How do I change my LUKS passphrase ?

cryptsetup-luks-1.0.3 had bug which caused this. Upgrade to >=cryptsetup-1.0.5!
 * Why does LUKS not access my passphrase (which is > 32Byte)?


 * Could it be possible for someone to infect my computer so that my random number generator no longer produces "random" numbers?
 * Is this possible if I use a hardware random number generator?
 * It may be possible for someone to target a user in this way, if the root partition or kernel is not encrypted when the computer is shutdown. Even if you use hardware to generate random numbers, an infected machine could opt not to use those properly. Over time, new data on the drive could be decrypted more easily and the effective search space for the key would be reduced should a brute-force attack be attempted.
 * Solution: Do a hash of the relevant parts of your system and store it on removable media. Check intermittently to see if the hash has changed.


 * Help! I screwed my system, what should I do?
 * Keep trying if you do not find an answer below.

editing an initrd, summary
 * I need to edit an initrd, how shall I do it?

failed to setup dm-crypt mapping. failed to write to key storage. Command failed.
 * Help! I get the following error when "luksFormatting" a partition.
 * Make sure you're passing the right options to cryptsetup,
 * For example: --cipher serpent-cbc-essiv:sha256, is right
 * --cipher serpent-cbc-essiv --hash sha256 is wrong!

failed to setup dm-crypt mapping failed to read from key storage Command failed: No key available with this passphrase
 * failed to setup dm-crypt mapping, failed to read from key storage, please help!
 * Try -v as additional parameter.
 * Check that you have dm-crypt and device-mapper included in the kernel.
 * Check you have the necessary ciphers included in the kernel.
 * Check the devices nodes.
 * The minor device number of control during boot with live cd doesn't have to be the same with later kernel. The only way to be sure to have the correct one is to check it after booting with the final kernel. Temporaly add a /bin/bash to your linuxrc and uncomment the unmounting of proc, then boot it. Being in bash with the final kernel do a cat /proc/misc and see the "real" minor device number.

See LUKSFaq.


 * Help! When I rebooted, udev did not create any new device nodes for my devices!
 * Make sure that on your root partition, you have a /sys directory. This is important because udev requires a mounted sysfs virtual filesystem.

creating /sys


 * I already have a working system and I want to encrypt it, what shall I do?
 * Basically backup all the important data and follow the guide, if you're a Gentoo user, you might want to check out Stage4 on the Gentoo forums.


 * Is it possible to encrypt a cd/dvd ? 
 * Yes, see here.
 * Crypted DVD/CD media using Luks wiki.


 * I already have an encrypted system using dm-crypt and cryptsetup(luks), but I want to boot from an usb-stick, what shall I do?
 * Perform the relevant steps from your current system, there is no need to reinstall.


 * Is it possible to migrate from cryptsetup to cryptsetup-luks, without transfering the files to an uncrypted medium (that means: copy files, delete old device, create new one, move files back)?
 * You could transfer the data to an encrypted removable media first.

Failed to execute /init Kernel panic - not syncing: No init found. Try passing init= option to kernel.
 * Failed to execute /init, kernel panic, please help!
 * Your kernel is not unpacking the initramfs archive, please follow this steps:

Troubleshooting -- Users with initramfs built into the kernel Troubleshooting -- Users with initramfs passed via the bootloader Letting the kernel build process handle initramfs creation

''If it keeps failing, well.. you're on your own.''

You probably made a mistake along the way, either keep trying or try using genkernel.

DM-Crypt SECURITY System Encryption DM-Crypt with LUKS