[id='creating-encrypted-block-devices_{context}']
= Creating encrypted block devices

This procedure describes the steps to create and configure encrypted block devices after installation.

[id='proc_preparing_block_device_for_encrypting']
== Step 1: Preparing a block device

* Install the `cryptsetup` package:
+
----------
# dnf install cryptsetup-luks
----------

* Create the block devices you want to encrypt using `parted`, `pvcreate`, `lvcreate`, and `mdadm`.

* Optionally, fill the device, for example, `/dev/sda3` with random data before encrypting it as this increases the strength of encryption.
+
[NOTE]
========
Filling the device with random data increases the time necessary for encryption.
========
+
[WARNING]
=========
The commands below destroy any existing data on the device.
=========

** To fill the device with high-quality random data:
+
-------
dd if=/dev/urandom of=<device>
-------
+
This takes several minutes per gigabyte on most systems.
+
** To fill the device with lower-quality random data:
+
--------
badblocks -c 10240 -s -w -t random -v <device>
--------
+
This is quicker compared to the high-quality random data method.

[id='proc_format-device-as-dmcrypt-encrypted-device']
== Step 2: Formatting an encrypted device

. Format the device:
+
---------
# cryptsetup luksFormat <device>
---------
+
Sample output:
+
--------
WARNING!
========
This will overwrite data on <device> (for example, /dev/xvdc) irrevocably.

Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase:
Verify passphrase:
Command successful.
--------
This command initializes the volume, and sets an initial key or passphrase.
+
[NOTE]
==========
The passphrase is not recoverable so do not forget it.
==========

. To verify the formatting:
+
-----
# cryptsetup isLuks <device> && echo Success
-----

. To see a summary of the encryption information for the device:
+
---------
# cryptsetup luksDump <device>
---------

[id='proc_create-mapping-to-allow-access-to-decrypted-contents']
== Step 3: Creating mapping to allow access to a decrypted content

To access a decrypted content on a device, you need to create a mapping using the kernel `device-mapper`.

LUKS provides a UUID (Universally Unique Identifier) for each device. This UUID is guranteed to remain the same as long as the LUKS header remains intact. To find a LUKS UUID for the device, run the following command:

--------
# cryptsetup luksUUID <device>
--------

An example of a reliable, informative and unique mapping name would be `luks-<uuid>`, where `<uuid>` is replaced with the LUKS UUID for the device (for example, luks-50ec957a-5b5a-47ee-85e6-f8085bbc97a8).

. Create a mapping to access the decrypted contents on the device:
+
--------
# cryptsetup luksOpen <device> <name>
--------
+
You are prompted to enter the passphrase for the device. Once you have authenticated, you can see the mapping `/dev/mapper/<name>` which represents the decrypted device. You can read from and write to this device like you would any other unencrypted block device.

. To see the status of the mapping:
+
------
# cryptsetup -v status <name>
------
+
Sample output:
+
--------
/dev/mapper/<name> is active.
  type:    LUKS1
  cipher:  aes-cbc-essiv:sha256
  keysize: 256 bits
  device:  /dev/xvdc
  offset:  4096 sectors
  size:    419426304 sectors
  mode:    read/write
Command successful.
--------

[id='proc_create-filesystems-on-mapped-device']
== Step 4: Creating filesystems on a mapped device

After <<proc_create-mapping-to-allow-access-to-decrypted-contents>>, you can now use the mapped device node `/dev/mapper/<name>` like any other block device.

. To create an `ext2` filesystem on the mapped device:
+
-------
# mke2fs /dev/mapper/<name>
-------

. To mount this file system:
+
--------
# mkdir /mnt/test/
# mount /dev/mapper/<name> /mnt/test
--------

[id='proc_add-mapping-information-to-etc-fstab']
== Step 5: Adding the mapping information to `/etc/fstab`

In order for a system to setup mapping to a device, add a corresponding entry in the `/etc/crypttab` file.

. If your system does not have the `/etc/crypttab` file, create a new file and change the owner and group to `root` (`root:root`):
+
----------
# touch /etc/crypttab
# chmod 0744
----------

. To identify the correct device in case the device name changes, add:
+
---------
<name>  <device>  none
---------
+
Here, the `<device>` field should be given in the form `UUID=<luks_uuid>`, where `<luks_uuid>` is the LUKS UUID.

[id='proc_add-entry-to-etc-fstab']
== Step 6: Adding an entry to `/etc/fstab`

To ensure a persistent mapping between the device and the mount point, add the entry in the `/etc/fstab` file:

------
/dev/mapper/<name>
------

== Additional resources

 * https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions[LUKS Project Wiki: Frequently Asked Questions]

 * http://man7.org/linux/man-pages/man8/cryptsetup.8.html[cryptsetup(8) man page]

 * http://man7.org/linux/man-pages/man8/dmsetup.8.html[dmsetup(8) man page]