Dm-crypt

Kernel Configuration[edit | edit source]

To use dm-crypt there are a number of configuration entries that are necessary.

First of all, support for the device mapper infrastructure as well as the crypt target must be included:

[*] Enable loadable module support
Device Drivers --->
    [*] Multiple devices driver support (RAID and LVM) --->
        <*> Device mapper support
        <*>   Crypt target support

Next, the Linux kernel needs to support the set of cryptographic APIs that the administrator wants to use for encryption. These can be found under the Cryptographic API section:

[*] Cryptographic API --->
    <*> XTS support
    <*> SHA224 and SHA256 digest algorithm
    <*> AES cipher algorithms
    <*> AES cipher algorithms (x86_64)
    <*> User-space interface for hash algorithms
    <*> User-space interface for symmetric key cipher algorithms

If the root file system will be encrypted as well, then an initial ram file system needs to be created in which the root filesystem is decrypted before it is mounted. Thus this requires initramfs support as well:

General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support

If using the tcrypt encryption option (TrueCrypt/tcplay/VeraCrypt compatibility mode), then the following items will also need to be added to the kernel. Otherwise, cryptsetup will return the following errors: "device-mapper: reload ioctl failed: Invalid argument" and "Kernel doesn't support TCRYPT compatible mapping".

Device Drivers --->
    [*] Block Devices ---> 
        <*> Loopback device support 
File systems ---> 
     <*> FUSE (Filesystem in Userspace) support 
[*] Cryptographic API ---> 
     <*> RIPEMD-160 digest algorithm 
     <*> SHA384 and SHA512 digest algorithms 
     <*> Whirlpool digest algorithms 
     <*> LRW support 
     <*> Serpent cipher algorithm 
     <*> Twofish cipher algorithm

Cryptsetup installation[edit | edit source]

The sys-fs/cryptsetup package provides the cryptsetup command, which is used to open or close the encrypted storage as well as manage the passphrases or keys associated with it.

Keyfile or passphrase[edit | edit source]

In order to start with encrypted storage, the administrator will need to decide which method to use for the encryption key. With cryptsetup the choice is either a passphrase or a keyfile. In case of a keyfile, this can be any file, but it is recommended to use a file with random data which is properly protected (considering that access to this keyfile will mean access to the encrypted data).

To create a keyfile, one can use the dd command:

In the next sections, we will show every command for both situations - passphrase and keyfile. Of course, only one method is necessary.

Creating an encrypted storage platform[edit | edit source]

In order to create an encrypted storage platform (which can be a disk, partition, file, ...) use the cryptsetup command with the luksFormat action.

For instance, to have /dev/vdb2 as the storage medium for the encrypted data:

This will overwrite data on /dev/vdb2 irrevocably.
  
Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: ...
Verify passphrase: ...

To use a keyfile instead of a passphrase:

This will overwrite data on /dev/vdb2 irrevocably.
  
Are you sure? (Type uppercase yes): YES

The -s 512 tells cryptsetup which keylength to use for the real encryption key (unlike the passphrase or keyfile, which are used to access this real encryption key).

Opening the encrypted storage[edit | edit source]

In order to open up the encrypted storage (i.e. make the real data accessible through transparent decryption), use the luksOpen action.

Enter passphrase for /dev/vdb2: ...

If a keyfile is used, then the command would look like so:

When the command finishes successfully, then a new device file called /dev/mapper/myname will be made available.

If this is the first time this encrypted device is used, it needs to be formatted. The following example uses the Btrfs file system but of course any other file system will do:

Once the file system is formatted, or the formatting was already done in the past, then the device file can be mounted on the system:

Closing the encrypted storage[edit | edit source]

In order to close the encrypted storage (i.e. ensure that the real data is no longer accessible through transparent decryption), use the luksClose action:

Of course, make sure that the device is no longer in use.

Listing the slots[edit | edit source]

With the luksDump action, information about the encrypted partition, disk or file can be shown. This includes the slots:

LUKS header information for /dev/vdb2
  
Version:        1
Cipher name:    aes
Cipher mode:    xts-plain64
Hash spec:      sha1
Payload offset: 4096
MK bits:        512
MK digest:      34 3b ec ac 10 af 19 e7 e2 d4 c8 90 eb a8 da 3c e4 4f 2e ce
MK salt:        ff 7c 7f 53 db 53 48 02 a4 32 dc e0 22 fc a3 51
                06 ba b3 48 b3 28 13 a8 7a 68 43 d6 46 79 14 fe
MK iterations:  59375
UUID:           2921a7c9-7ccb-4300-92f4-38160804e08c
  
Key Slot 0: ENABLED
        Iterations:             241053
        Salt:                   90 0f 0f db cf 66 ea a9 6c 7c 0c 0d b0 28 05 2f
                                8a 5c 14 54 98 62 1a 29 f3 08 25 0c ec c2 b1 68
        Key material offset:    8
        AF stripes:             4000
Key Slot 1: ENABLED
        Iterations:             273211
        Salt:                   01 4c 26 ed ff 18 75 31 b9 89 5d a6 e0 b5 f4 14
                                48 d0 23 47 a9 85 78 fb 76 c4 a9 d0 cd 63 fb d7
        Key material offset:    512
        AF stripes:             4000
Key Slot 2: DISABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

In the above example, two slots are used. Note that luksDump does not give away anything sensitive - it is merely displaying the LUKS header content. No decryption key has to be provided in order to call luksDump.

Adding a keyfile or passphrase[edit | edit source]

In order to add an additional keyfile or passphrase to access the encrypted storage, use the luksAddKey action:

Enter any passphrase: (Enter a valid, previously used passphrase to unlock the key)
Enter new passphrase for key slot: ... 
Verify passphrase: ...

To use a keyfile to unlock the key (but still add in a passphrase):

Enter new passphrase for key slot: ...
Verify passphrase: '''

If a keyfile is to be added (say /etc/keys/backup.key):

Or, to use the first keyfile to unlock the main key:

Removing a keyfile or passphrase[edit | edit source]

With the luksRemoveKey action, a keyfile or passphrase can be removed (so they can no longer be used to decrypt the storage):

Enter LUKS passphrase to be deleted: ...

Or to remove a keyfile:

Make sure that at least one method for accessing the data is still available. Once a passphrase or keyfile is removed for use, this cannot be recovered again.

Emptying a slot[edit | edit source]

Suppose the passphrase or keyfile is no longer known, then the slot can be freed. Of course, this does require prior knowledge of which slot that the passphrase or keyfile was stored in.

For instance, to empty out slot 2 (which is the third slot as slots are numbered starting from 0):

This command will ask for a valid passphrase before continuing. Or one can pass on the keyfile to use:

Configuring dm-crypt[edit | edit source]

Edit the /etc/conf.d/dmcrypt file and add in entries for each file system. The supported entries are well documented in the file, the below example is just that - an example:

# Definition for /dev/mapper/home (for /home)
target=home
source=UUID="abcdef12-321a-a324-a88c-cac412befd98"
key=/etc/keys/home.key
 
# Definition for /dev/mapper/local (for /usr/local)
target=local
source=UUID="fedcba34-4823-b423-a94c-cadbefda2943"
key=/etc/keys/local.key
 
# Using an encrypted partition as key source.
target=other
source=UUID="ff24303e-49e1-4d13-b8ad-fc6b7e1d8174"
key=/keys/other.key                                # Relative to the root of the encrypted partition.
remdev=/dev/mapper/home                            # The recently decrypted partition.
 
# An empty line is important at the end of the file

Configuring fstab[edit | edit source]

The next step is to configure /etc/fstab to automatically mount the (decrypted) file systems when they become available. It is recommended to first obtain the UUID of the decrypted (mounted) file system:

/dev/mapper/home: UUID="4321421a-4321-a6c9-de52-ba6421efab76" TYPE="ext4"

Then, update the /etc/fstab file accordingly:

UUID="4321421a-4321-a6c9-de52-ba6421efab76"   /home        ext4   defaults   0   0
UUID="bdef2432-3bd1-4ab4-523d-badcf234a342"   /usr/local   ext4   defaults   0   0

Add initscript to bootlevel[edit | edit source]

Don't forget to have the dmcrypt init service launched at boot:

Make decrypted device nodes visible[edit | edit source]

If you have decrypted/unlocked a device before the services were started for example your root disk in an with an initramfs then it's possible that the mapped device is not visible. In this case you can run the following to recreate it.