# Support for TCG Opal 2-compliant Self-Encrypting Disks

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

The term "SED" refers to any kind of self-encrypting disk.
A "TCG Opal 2-compliant disk" or short "Opal disk" is a variant of an SED which implements the Opal 2 standard.
There are/were other SED variants on the market using proprietary protocols.

In general, these disks all provide full disk encryption in hardware, similar to what LUKS does in software. 

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
[download from Drive Trust Alliance](https://github.com/Drive-Trust-Alliance/exec/blob/master/sedutil_LINUX.tgz?raw=true)
(check version compatibility), or see
<<How to Build sedutil-cli Version {sedutil-cli-version}>>.

## Quick Start: Setting up Self-Encrypting Disks

NOTE: This section assumes that ReaR was installed from a package repository. If you are using ReaR locally from GitHub: `cd` into the project's base directory, use the configuration file `etc/rear/local.conf`, invoke `usr/sbin/rear`.

### Step 1: Install Prerequisites

* Download the low-level utility `sedutil-cli` (version 1.15.1) from https://github.com/Drive-Trust-Alliance/exec/blob/master/sedutil_LINUX.tgz?raw=true[Drive-Trust-Alliance on GitHub].
* Install it into a directory within root's search path (e.g. `/usr/local/sbin`).

### Step 2: Create Disk Images for PBA and Rescue System

* In `/etc/rear/local.conf` add these two lines:

    OUTPUT=RAWDISK
    OUTPUT_URL="file:///var/lib/rear/output"

** To support secure boot, add another line specifying your secure boot loader, e.g. on Ubuntu:

    SECURE_BOOT_BOOTLOADER="/boot/efi/EFI/ubuntu/shimx64.efi"

* Run `sudo rear mkopalpba` (ignore messages about keyboard mappings)
* Run `sudo rear mkrescue` (ignore messages about keyboard mappings)

### Step 3: Create a Bootable USB Stick with the Rescue System

* Plug in the USB stick to use.
* Use `lsblk -o +MODEL` to find the correct disk device path for your USB stick (typically `/dev/sdX`).
* *RE-CHECK. The following command will overwrite the entire USB stick.*
* Use the following command, replacing `USB-DEVICE` with the USB stick's device name.

        sudo zcat "/var/lib/rear/output/$(hostname)/rear-$(hostname).raw.gz" | sudo dd bs=1M of=/dev/USB-DEVICE

### Step 4: Set up Opal 2 Disk Drives

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.*

* Boot the rescue system just created.
* *RE-CHECK. The following command will erase selected disks.*
* Run `rear opaladmin setupERASE _DEVICE_ ...`
* `_DEVICE_` is the disk device path like `/dev/sda`, or `ALL` for all available
devices.
* Verify that disk unlocking works:
.. Turn off power.
.. Remove the rescue USB stick.
.. Turn on power.
.. Check the PBA boots and unlocks disks.

NOTE: After unlocking, there is no OS. This is expected.

### Step 5: Install the Operating System

* Boot the rescue system.
* Deactivate locking:

    rear opaladmin deactivate

* Install the Operating System.
* Boot the rescue system.
* Reactivate locking:


    rear opaladmin reactivate

* Remove the rescue USB stick and shutdown the system.

## 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 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 onto a disk boot medium (a 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 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:


    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:

    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`

* Persistently deactivate the locking mechanism on disk(s): `rear opaladmin deactivate`

* Reactivate the locking mechanism on disk(s): `rear opaladmin reactivate`

* 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](https://github.com/Drive-Trust-Alliance/sedutil/tags)

* Download [Drive-Trust-Alliance/sedutil version 1.49.13](https://github.com/Drive-Trust-Alliance/sedutil/archive/refs/tags/1.49.13.tar.gz) source code.

* Extract the archive, creating a directory `sedutil-{sedutil-cli-version}`:

    tar xof sedutil-{sedutil-cli-version}.tar.gz

* Configure the build system:

        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):

        cd linux/CLI
        make CONF=Release_x86_64

* Install the executable into a directory root's search path (`/usr/local/bin`
in this example):

        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:
    * 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.

### Automatic Disk Unlock

Relax-and-Recover supports automatic unlocking of TCG Opal 2-compliant self-encrypting disks (SED) by storing the disk password securely in one of the following:

* directly on the system’s Trusted Platform Module (TPM), or
* encrypted on a small partition (removable media is ideal for easier setup and more security).

This enhancement allows fully unattended disk unlock at boot time, without requiring user password entry.

#### Enabling Automatic Unlock

To enable automatic unlock, configure the desired key storage method before generating the pre-boot authentication (PBA) environment:

* Edit /etc/rear/local.conf and set one of the following options:

        # Store password in TPM
        OPAL_PBA_TPMNVINDEX="0xXXXXXXX" # TPM nonvolatile memory index
        
        # Or store password as Authtoken (see default.conf for more settings)
        OPAL_PBA_TKNPATH=( /dev/xxx ) # Path to linux block device to use as AuthToken container

NOTE: These options are mutually exclusive. Only one storage method can be selected.

* Then create the PBA image with:

        sudo rear mkopalpba

#### Boot-Time Behavior

* During boot, the PBA system will:
* Detect the presence of the selected setting (TPM or USB).
* Retrieve the stored disk password.
* Automatically unlock the encrypted disk(s).
* Proceed with booting the regular operating system.
* If the key is not found, manual password entry will be required and it will be proposed to store it in the selected means.

#### Security Considerations

If an attacker gains access to a PBA image — for example, by booting the system from a live USB and dumping the shadow MBR — they could extract the Opal password in clear text. Should they also obtain the associated AuthToken (e.g. from a USB key), they would be able to fully recover the original disk password.

In other words, automating the unlocking process introduces certain risks.

Using a USB key as an AuthToken container in combination with TPM2-assisted encryption provides the best security, but requires physical possession of the USB key during boot.

Storing the password in the TPM alone is simpler and more convenient. However, since the password is currently stored in plain text, this method should only be used with Secure Boot enabled and with booting from external media disabled in the BIOS or firmware settings.

Note: the entire unlock process is performed locally and offline — no network access or remote dependency is introduced.

#### Tested Environments

This functionality has been tested successfully on Ubuntu 24.04.1 LTS with TPM 2.0 and various USB storage devices.

### References

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

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

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