= Support for TCG Opal 2-compliant Self-Encrypting Disks
:sedutil-cli-version: 1.15.1

Beginning with version 2.4, Relax-and-Recover supports self-encrypting disks
(SEDs) compliant with the TCG Opal 2 specification.

Self-encrypting disk support includes

* recovery (saving and restoring the system's SED configuration),
* setting up SEDs, including assigning a disk password,
* providing a pre-boot authentication (PBA) system to unlock SEDs at boot time.

== Prerequisites

To enable Relax-and-Recover's TCG Opal 2 support, install the `sedutil-cli`
(version {sedutil-cli-version}) executable into a directory within root's search
path. `sedutil-cli` is available for
https://github.com/Drive-Trust-Alliance/exec/blob/master/sedutil_LINUX.tgz?raw=true[download from Drive Trust Alliance]
(check version compatibility), or see
<<How to Build sedutil-cli Version {sedutil-cli-version}>>.

== TCG Opal 2-compliant Self-Encrypting Disks

NOTE: This is a simplified explanation to help understand self-encrypting disks
in the context of Relax-and-Recover support.

An Opal 2-compliant self-encrypting disk (SED) encrypts disk contents in
hardware. The SED can be configured to store a user-assigned password and to
lock itself when powered off. Unlocking the disk after powering up requires the
user to supply the password.

=== Booting From a Self-Encrypting Disk

How can a system boot from a disk which is locked? The Opal solution is
metamorphosis. An Opal disk hides or presents different contents depending on
whether it is locked or not:

* In addition to its regular contents, an Opal disk contains a special area for
additional boot code, the (unfortunately named) _shadow MBR_. It is small (the
spec guarantees just 128 MB), write-protected, and normally hidden.

* When *unlocked*, an Opal disk shows its regular contents like any other disk.
In this state, the system firmware would boot the regular operating system.

* When *locked*, an Opal boot disk exposes its _shadow MBR_ at the start,
followed by zeroed blocks. In this state, the system firmware would boot the
code residing in the shadow MBR.

The shadow MBR, when enabled, can be prepared with a _pre-boot authentication_
(PBA) system. The PBA system is a purpose-built operating system which

. is booted by the firmware like any other operating system,
. asks the user for the disk password,
. unlocks the boot disk (and possibly other Opal 2-compliant SEDs as well), and
. continues to boot the regular operating system.

== Administering Self-Encrypting Disks

=== Creating a Pre-Boot Authentication (PBA) System

NOTE: This is only required if an SED is to be used as boot disk.

To create a pre-boot authentication (PBA) system image:

. Run `sudo rear -v mkopalpba`

* The PBA image will appear below the `OPAL_PBA_OUTPUT_URL` directory (see
`default.conf`) as `$HOSTNAME/TCG-Opal-PBA-$HOSTNAME.raw`.

. If you want to test the PBA system image,

* copy it it onto a disk boot medium (an USB stick will do) with `dd
if="$image_file" bs=1MB of="$usb_device"` (use the entire disk device, not a
partition),

* boot from the medium just created.

To create a rescue system with an integrated PBA system image:

. Verify that the `OPAL_PBA_OUTPUT_URL` configuration variable points to a local
directory (which is the default), or set `OPAL_PBA_IMAGE_FILE` to the image
file's full path.

. Run `sudo rear -v mkrescue`

=== Setting Up Self-Encrypting Disks

WARNING: Setting up an SED normally *ERASES ALL DATA ON THE DISK*, as a new data
encryption key (DEK) will be generated. While `rear opaladmin` includes safety
measures to avoid accidentally erasing a partitioned disk, do not rely on this
solely. *Always back up your data and have a current rescue system available.*

To set up SEDs:

. Boot the Relax-and-Recover rescue system.

* If SED boot support is required, ensure that the rescue system was built with
an integrated PBA system image.

. Run `rear opaladmin setupERASE DEVICE ...`

* _DEVICE_ is the disk device path like `/dev/sda`, or `ALL` for all available
devices
* This will set up Opal 2-compliant disks specified by the DEVICE arguments.
* You will be asked for a new disk password. The same password will be used for
all disks being set up.
* If a PBA is available on the rescue system, you will be asked for each disk
whether it should act as a boot device for disk unlocking (in which case the PBA
will be installed).
* *DISK CONTENTS WILL BE ERASED*, with the following exceptions:
** If the disk has mounted partitions, the disk's contents will be left
untouched.
** If unmounted disk partitions are detected, you will be asked whether the
disk's contents shall be erased.

. On UEFI systems, see
<<Setting up UEFI Firmware to Boot From a Self-Encrypting Disk>>.

=== Verifying Disk Setup

If you want to ensure that disks have been set up correctly:

. Power off, then power on the system.

. Boot directly into the Relax-and-Recover rescue system.

. Run `rear opaladmin info` and verify that output looks like this:
+
[options="nowrap"]
----
DEVICE         MODEL                          I/F    FIRMWARE     SETUP  ENCRYPTED  LOCKED  SHADOW MBR
/dev/sda       Samsung SSD 850 PRO 256GB      ATA    EXM04B6Q     y      y          y       visible
----
+
The device should appear with _SETUP_=`y`, _ENCRYPTED_=`y` and _LOCKED_=`y`,
_SHADOW MBR_ on boot disks should be `visible`, otherwise `disabled`.

. Run `rear opaladmin unlock`, supplying the correct disk password.

. Run `rear opaladmin info` and verify that output looks like this:
+
[options="nowrap"]
----
DEVICE         MODEL                          I/F    FIRMWARE     SETUP  ENCRYPTED  LOCKED  SHADOW MBR
/dev/sda       Samsung SSD 850 PRO 256GB      ATA    EXM04B6Q     y      y          n       hidden
----
+
The device should appear with _SETUP_=`y`, _ENCRYPTED_=`y` and _LOCKED_=`n`,
_SHADOW MBR_ on boot disks should be `hidden`, otherwise `disabled`.

=== Routine Administrative Tasks

The following tasks can be safely performed on the original system (with `sudo`)
or on the rescue system.

* Display disk information: `rear opaladmin info`

* Change the disk password: `rear opaladmin changePW`

* Upload the PBA onto the boot disk(s): `rear opaladmin uploadPBA`

* Unlock disk(s): `rear opaladmin unlock`

* For help: `rear opaladmin help`

=== Erasing a Self-Encrypting Disk

To *ERASE ALL DATA ON THE DISK* but retain the setup:

. Boot the Relax-and-Recover rescue system.

. Run `rear opaladmin resetDEK DEVICE ...`
* _DEVICE_ is the disk device path like `/dev/sda`, or `ALL` for all available
devices
* If mounted disk partitions are detected, the disk's contents will not be
erased.
* If unmounted disk partitions are detected, you will be asked whether the
disk's contents shall be erased.

To *ERASE ALL DATA ON THE DISK* and reset the disk to factory settings:

. Boot the Relax-and-Recover rescue system.

. Run `rear opaladmin factoryRESET DEVICE ...`
* _DEVICE_ is the disk device path like `/dev/sda`, or `ALL` for all available
devices
* If mounted disk partitions are detected, the disk's contents will not be
erased.
* If unmounted disk partitions are detected, you will be asked whether the
disk's contents shall be erased.

== Details

=== How to Build sedutil-cli Version {sedutil-cli-version}

. Download https://github.com/Drive-Trust-Alliance/sedutil/archive/{sedutil-cli-version}.tar.gz[Drive-Trust-Alliance/sedutil version {sedutil-cli-version}] source code.

. Extract the archive, creating a directory `sedutil-{sedutil-cli-version}`:
+
[source,bash,subs="attributes"]
----
tar xof sedutil-{sedutil-cli-version}.tar.gz
----

. Configure the build system:
+
[source,bash,subs="attributes"]
----
cd sedutil-{sedutil-cli-version}
aclocal
autoconf
./configure
----
+
NOTE: Ignore the following error: `configure: error: cannot find install-sh,
install.sh, or shtool in "." "./.." "./../.."`
+
NOTE: If there are any other error messages, you may have to install required
packages like `build-essential`, then re-run `./configure`.

. Compile the executable (on the x86_64 architecture in this example):
+
[source,bash,subs="attributes"]
----
cd linux/CLI
make CONF=Release_x86_64
----

. Install the executable into a directory root's search path (`/usr/local/bin`
in this example):
+
[source,bash,subs="attributes"]
----
cp dist/Release_x86_64/GNU-Linux/sedutil-cli /usr/local/bin
----

=== Setting up UEFI Firmware to Boot From a Self-Encrypting Disk

If the UEFI firmware is configured to boot from the disk _device_ (instead of
some specific operating system entry), no further configuration is necessary.

Otherwise the UEFI firmware (formerly BIOS setup) must be configured to boot two
different targets:

. The PBA system (which is only accessible while the disk is locked).

. The regular operating system (which is only accessible while the disk is
unlocked).

This can be configured as follows:

. Ensure that the PBA system has been correctly installed to the boot drive.

. Power off, then power on the system.

. Enter the firmware setup.

. Configure the firmware to boot from the (only) EFI entry of the boot drive.

. Once a regular operating system has been installed:
[arabic]
.. Unlock the disk.

.. Reboot without powering off.

.. Enter the firmware setup.

.. Configure the firmware to boot from the EFI entry of your regular operating
system. Do not delete the previously configured boot entry for the PBA system.

=== References

* https://github.com/Drive-Trust-Alliance/sedutil[Drive-Trust-Alliance/sedutil:DTA sedutil Self encrypting drive software]

* https://trustedcomputinggroup.org/wp-content/uploads/TCG_Storage-Opal_SSC_v2.01_rev1.00.pdf[TCG Storage Security Subsystem Class: Opal Specification Version 2.01]

* https://trustedcomputinggroup.org[Trusted Computing Group]
