Difference between revisions of "Dm-crypt/System configuration"

From ArchWiki
Jump to: navigation, search
(Configuring mkinitcpio: new section)
(Boot loader: adding crypto parameter)
(13 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
[[Category:Security]]
 
[[Category:Security]]
 
[[Category:File systems]]
 
[[Category:File systems]]
{{Stub|This article is currently under heavy restructuring: for its latest stable revision see [[Dm-crypt with LUKS]]}}
 
 
{{Expansion|Aggregate here all the generic information on system configuration from the other sub-articles of [[Dm-crypt]].}}
 
{{Expansion|Aggregate here all the generic information on system configuration from the other sub-articles of [[Dm-crypt]].}}
 
Back to [[Dm-crypt]].
 
Back to [[Dm-crypt]].
  
=== Configuring mkinitcpio ===
+
== mkinitcpio ==
 
When encrypting a system it is necessary to regenerate the initial ramdisk after properly configuring [[mkinitcpio]]. Depending on the particular scenarios, a subset of the following hooks will have to be enabled:
 
When encrypting a system it is necessary to regenerate the initial ramdisk after properly configuring [[mkinitcpio]]. Depending on the particular scenarios, a subset of the following hooks will have to be enabled:
  
 
* {{ic|encrypt}}: always needed when encrypting the root partition, or a partition that needs to be mounted ''before'' root; it must come ''before'' the {{ic|filesystems}} hook; it is not needed in all the other cases, as system initialization scripts like {{ic|/etc/crypttab}} take care of unencrypting any other partitions.
 
* {{ic|encrypt}}: always needed when encrypting the root partition, or a partition that needs to be mounted ''before'' root; it must come ''before'' the {{ic|filesystems}} hook; it is not needed in all the other cases, as system initialization scripts like {{ic|/etc/crypttab}} take care of unencrypting any other partitions.
* {{ic|shutdown}}: ensures controlled unmounting during system shutdown.
+
* {{ic|shutdown}}: recommended before ''mkinitcpio 0.16'' to ensure controlled unmounting during system shutdown. It is still functional, but not deemed necessary [https://mailman.archlinux.org/pipermail/arch-dev-public/2013-December/025742.html anymore].  
 
* {{ic|keymap}}: provides support for foreign keymaps for typing encryption passwords; it must come ''before'' the {{ic|encrypt}} hook.
 
* {{ic|keymap}}: provides support for foreign keymaps for typing encryption passwords; it must come ''before'' the {{ic|encrypt}} hook.
 
* {{ic|keyboard}}: needed to make USB keyboards work in early userspace.
 
* {{ic|keyboard}}: needed to make USB keyboards work in early userspace.
Line 17: Line 16:
 
Other hooks needed should be clear from other manual steps followed during the installation of the system.
 
Other hooks needed should be clear from other manual steps followed during the installation of the system.
  
{{Accuracy|Is this still needed?}}
+
== Boot loader ==
In {{ic|/etc/mkinitcpio.conf}}, you may want to add {{ic|dm_mod}} and the filesystem types used to {{ic|MODULES}}, e.g: {{ic|1=MODULES="dm_mod ext4"}}.
+
In order to enable booting an encrypted root partition, a subset of the following kernel parameters need to be set. See [[kernel parameters]] for instructions specific to your [[boot loader]].
 +
 
 +
=== cryptdevice ===
 +
This parameter will make the system prompt for the passphrase to unlock the root device on a cold boot. It is parsed by the {{ic|encrypt}} hook to identify which device contains the encrypted system:
 +
 
 +
cryptdevice=''device'':''dmname''
 +
 
 +
* {{ic|''device''}} is the path to the raw encrypted device. Usage of [[Persistent block device naming]] is advisable.
 +
* {{ic|''dmname''}} is the '''d'''evice-'''m'''apper name given to the device after decryption, which will be available as {{ic|/dev/mapper/''dmname''}}.
 +
 
 +
=== root ===
 +
This parameter is needed when ''not'' using [[GRUB]]. The reason GRUB does not require this is because the auto-generated {{ic|grub.cfg}} is meant to handle specifying the root for you.
 +
 
 +
root=''device''
 +
 
 +
* {{ic|''device''}} is the device file of the actual (decrypted) root file system. If the file system is formatted directly on the decrypted device file this will be {{ic|/dev/mapper/''dmname''}}.
 +
 
 +
=== resume ===
 +
resume=''device''
 +
 
 +
* {{ic|''device''}} is the device file of the decrypted (swap) filesystem used for suspend2disk. If swap is on a separate partition, it will be in the form of {{ic|/dev/mapper/swap}}. See also [[Dm-crypt/Swap Encryption]].
 +
 
 +
=== cryptkey ===
 +
This parameter is required by the ''encrypt'' hook for reading a keyfile to unlock the ''cryptdevice''. It can have two parameter sets, depending on whether the keyfile exists as a file or a bitstream starting on a specific location.  
 +
 
 +
For a file the format is: 
 +
 
 +
cryptkey=''device'':''fstype'':''path''
 +
 
 +
*{{ic|''device''}} is the raw block device where the key exists.
 +
*{{ic|''fstype''}} is the filesystem type of {{ic|''device''}} (or auto).
 +
*{{ic|''path''}} is the absolute path of the keyfile within the device.
 +
 
 +
Example: {{ic|cryptkey<nowiki>=</nowiki>//dev/usbstick:vfat:/secretkey}}
 +
 
 +
For a bitstream on a device the key's location is specified with the following:
 +
cryptkey=''device'':''offset'':''size''
 +
 
 +
Example: {{ic|cryptkey<nowiki>=</nowiki>/dev/sdZ:0:512}} reads a 512 bit keyfile starting at the beginning of the device.
 +
 
 +
See also [[Dm-crypt/Device Encryption#Cryptsetup and keyfiles]].
 +
 
 +
=== crypto ===
 +
This parameter is specific to pass ''dm-crypt'' plain mode options to the ''encrypt'' hook.
 +
 
 +
It takes the form
 +
{{bc|<nowiki>crypto=</nowiki><hash>:<cipher>:<keysize>:<offset>:<skip>}}
 +
 
 +
The arguments relate directly to the ''cryptsetup'' options. See [[Dm-crypt/Device_Encryption#Encryption_options_for_plain_mode]]
 +
 
 +
For a disk encrypted with just ''plain'' default options, the {{ic|crypto}} arguments must be specified, but each entry can be left blank:
 +
{{bc|<nowiki>crypto=::::</nowiki>}}
 +
A specific example of arguments is 
 +
{{bc|<nowiki>crypto=sha512:twofish-xts-plain64:512:0:</nowiki>}}
 +
 
 +
== crypttab ==
 +
The {{ic|/etc/crypttab}} (or, encrypted device table) file contains a list of encrypted devices that are to be unlocked when the system boots, similar to [[fstab]]. This file can be used for automatically mounting encrypted swap devices or secondary filesystems. It is read ''before'' [[fstab]], so that dm-crypt containers can be unlocked before the filesystem inside is mounted. Note that crypttab is read ''after'' the system has booted, so it is not a replacement for [[#mkinitcpio|mkinitcpio]] hooks or [[#Boot loader|boot loader options]] in the case of an [[Dm-crypt/Encrypting an Entire System|encrypted root]] scenario. See the crypttab [http://linux.die.net/man/5/crypttab man page] for details.
 +
 
 +
{{hc|/etc/crypttab|
 +
#Example crypttab file. Fields are: name, underlying device, passphrase, cryptsetup options.
 +
#Mount /dev/lvm/swap as /dev/mapper/swap using plain dm-crypt with passphrase "SWAP"
 +
swap /dev/lvm/swap SWAP -c aes-xts-plain -h whirlpool -s 512
 +
#Mount /dev/lvm/tmp as /dev/mapper/tmp using plain dm-crypt with a random passphrase, making its contents unrecoverable after it is dismounted.
 +
tmp /dev/lvm/tmp /dev/urandom -c aes-xts-plain -s 512
 +
#Mount /dev/lvm/home as /dev/mapper/home using LUKS, and prompt for the passphrase at boot time.
 +
home  /dev/lvm/home
 +
#Mount /dev/sdb1 as /dev/mapper/backup using LUKS, with a passphrase stored in a file.
 +
backup /dev/sdb1      /home/alice/backup.key
 +
}}

Revision as of 21:36, 9 February 2014

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Aggregate here all the generic information on system configuration from the other sub-articles of Dm-crypt. (Discuss in Talk:Dm-crypt/System configuration#)

Back to Dm-crypt.

mkinitcpio

When encrypting a system it is necessary to regenerate the initial ramdisk after properly configuring mkinitcpio. Depending on the particular scenarios, a subset of the following hooks will have to be enabled:

  • encrypt: always needed when encrypting the root partition, or a partition that needs to be mounted before root; it must come before the filesystems hook; it is not needed in all the other cases, as system initialization scripts like /etc/crypttab take care of unencrypting any other partitions.
  • shutdown: recommended before mkinitcpio 0.16 to ensure controlled unmounting during system shutdown. It is still functional, but not deemed necessary anymore.
  • keymap: provides support for foreign keymaps for typing encryption passwords; it must come before the encrypt hook.
  • keyboard: needed to make USB keyboards work in early userspace.
    • usbinput: deprecated, but can be given a try in case keyboard does not work.

Other hooks needed should be clear from other manual steps followed during the installation of the system.

Boot loader

In order to enable booting an encrypted root partition, a subset of the following kernel parameters need to be set. See kernel parameters for instructions specific to your boot loader.

cryptdevice

This parameter will make the system prompt for the passphrase to unlock the root device on a cold boot. It is parsed by the encrypt hook to identify which device contains the encrypted system:

cryptdevice=device:dmname
  • device is the path to the raw encrypted device. Usage of Persistent block device naming is advisable.
  • dmname is the device-mapper name given to the device after decryption, which will be available as /dev/mapper/dmname.

root

This parameter is needed when not using GRUB. The reason GRUB does not require this is because the auto-generated grub.cfg is meant to handle specifying the root for you.

root=device
  • device is the device file of the actual (decrypted) root file system. If the file system is formatted directly on the decrypted device file this will be /dev/mapper/dmname.

resume

resume=device
  • device is the device file of the decrypted (swap) filesystem used for suspend2disk. If swap is on a separate partition, it will be in the form of /dev/mapper/swap. See also Dm-crypt/Swap Encryption.

cryptkey

This parameter is required by the encrypt hook for reading a keyfile to unlock the cryptdevice. It can have two parameter sets, depending on whether the keyfile exists as a file or a bitstream starting on a specific location.

For a file the format is:

cryptkey=device:fstype:path
  • device is the raw block device where the key exists.
  • fstype is the filesystem type of device (or auto).
  • path is the absolute path of the keyfile within the device.

Example: cryptkey=//dev/usbstick:vfat:/secretkey

For a bitstream on a device the key's location is specified with the following:

cryptkey=device:offset:size 

Example: cryptkey=/dev/sdZ:0:512 reads a 512 bit keyfile starting at the beginning of the device.

See also Dm-crypt/Device Encryption#Cryptsetup and keyfiles.

crypto

This parameter is specific to pass dm-crypt plain mode options to the encrypt hook.

It takes the form

crypto=<hash>:<cipher>:<keysize>:<offset>:<skip>

The arguments relate directly to the cryptsetup options. See Dm-crypt/Device_Encryption#Encryption_options_for_plain_mode

For a disk encrypted with just plain default options, the crypto arguments must be specified, but each entry can be left blank:

crypto=::::

A specific example of arguments is

crypto=sha512:twofish-xts-plain64:512:0:

crypttab

The /etc/crypttab (or, encrypted device table) file contains a list of encrypted devices that are to be unlocked when the system boots, similar to fstab. This file can be used for automatically mounting encrypted swap devices or secondary filesystems. It is read before fstab, so that dm-crypt containers can be unlocked before the filesystem inside is mounted. Note that crypttab is read after the system has booted, so it is not a replacement for mkinitcpio hooks or boot loader options in the case of an encrypted root scenario. See the crypttab man page for details.

/etc/crypttab
 #Example crypttab file. Fields are: name, underlying device, passphrase, cryptsetup options.
 #Mount /dev/lvm/swap as /dev/mapper/swap using plain dm-crypt with passphrase "SWAP"
 swap	/dev/lvm/swap	SWAP		-c aes-xts-plain -h whirlpool -s 512
 #Mount /dev/lvm/tmp as /dev/mapper/tmp using plain dm-crypt with a random passphrase, making its contents unrecoverable after it is dismounted.
 tmp	/dev/lvm/tmp	/dev/urandom	-c aes-xts-plain -s 512
 #Mount /dev/lvm/home as /dev/mapper/home using LUKS, and prompt for the passphrase at boot time.
 home   /dev/lvm/home
 #Mount /dev/sdb1 as /dev/mapper/backup using LUKS, with a passphrase stored in a file.
 backup /dev/sdb1       /home/alice/backup.key