opal-functions.sh

#
# TCG Opal 2 functions to manage self-encrypting disks
#
# References:
# - TCG Storage Opal SSC Specification Version 2.01 [Opal 2 spec]
#   https://trustedcomputinggroup.org/wp-content/uploads/TCG_Storage-Opal_SSC_v2.01_rev1.00.pdf
# - DTA sedutil Self encrypting drive software
#   https://github.com/Drive-Trust-Alliance/sedutil
#
# Notes:
# - In Opal, different authorities with different passwords are responsible for device administration and locking.
#   To avoid confusion, this code uses (and expects) identical passwords for
#     1. the SID (Security ID) as the authority of the Administrative Security Provider, and
#     2. the Admin1 user as the authority of the Locking Security Provider.
# - sedutil-cli outputs messages geared towards developers on failure. Callers of non-printing functions are expected
#   to redirect stdout and stderr and to display user-tailored messages after checking return codes.

#
# Functions in this section are meant to be used independently from ReaR. They do not rely on any external
# script code unless stated otherwise. Return codes must be checked by the caller.
# Before using these functions ensure that pattern matching extensions are enabled : 'shopt -s nullglob extglob'.
#

function opal_devices() {
    # prints a list of TCG Opal 2-compliant devices.

    sedutil-cli --scan | awk '$1 ~ /\/dev\// && $2 ~ /2/ { print $1; }'
}

function opal_device_disks() {
    local device="${1:?}"
    # prints all block devices belonging to the given Opal device.
    # Normally, this is just the Opal device itself, however, NVME devices have one or more namespaces per primary
    # device and these namespaces act as disks.

    case "$device" in
        (*/nvme*)
            echo "$device"n+([0-9])  # consider all namespace block devices (NOTE: relies on nullglob extglob)
            ;;
        (*)
            echo "$device"
            ;;
    esac
}

function opal_device_attributes() {
    local device="${1:?}"
    local result_variable_name="${2:?}"
    # returns a script assigning the Opal device's attributes to a local associative array variable:
    #   model=..., firmware=..., serial=..., interface=...
    #   support=[yn], setup=[yn], locked=[yn], encrypted=[yn], mbr={visible,hidden,disabled},
    #
    # Usage example:
    #   source "$(opal_device_attributes "$device" attributes)"
    #   if [[ "${attributes[setup]}" == "y" ]]; then ...

    local result_script="$(mktemp)"

    {
        echo -n "local -A $result_variable_name=( "
        sedutil-cli --query "$device" | awk '
            /^\/dev\// {
                gsub(/[$"]/, "*");  # strip characters interpreted by bash if part of a double-quoted string
                sub(/^\/dev\/[^ ]+ +/, "");  # strip device field from $0
                printf("[serial]=\"%s\" ", $(NF));
                printf("[firmware]=\"%s\" ", $(NF-1));
                sub(/ +[^ ]+ +[^ ]+ *$/, "");  # strip serial and firmware fields from $0
                printf("[interface]=\"%s\" ", $1);
                sub(/^[^ ]+ +/, "");  # strip type field from $0
                printf("[model]=\"%s\" ", $0);
            }
            /^Locking function \(0x0002\)/ {
                getline;
                gsub(/ /, "");
                split($0, field_assignments, ",");
                for (field_assignment_index in field_assignments) {
                    split(field_assignments[field_assignment_index], assignment_parts, "=");
                    raw_fields[assignment_parts[1]] = assignment_parts[2];
                }
                printf("[support]=\"%s\" ", tolower(raw_fields["LockingSupported"]));
                printf("[setup]=\"%s\" ", tolower(raw_fields["LockingEnabled"]));
                printf("[locked]=\"%s\" ", tolower(raw_fields["Locked"]));
                printf("[encrypted]=\"%s\" ", tolower(raw_fields["MediaEncrypt"]));
                printf("[mbr]=\"%s\" ", (raw_fields["MBREnabled"] == "Y" ? (raw_fields["MBRDone"] == "Y" ? "hidden" : "visible") : "disabled"));
            }
        '
        echo -e ")\nrm \"$result_script\""
    } > "$result_script"
    echo "$result_script"
}

function opal_device_attribute() {
    local device="${1:?}"
    local attribute_name="${2:?}"
    # prints the value of an Opal device attribute.

    source "$(opal_device_attributes "$device" attributes)"
    echo "${attributes[$attribute_name]}"
}

function opal_device_identification() {
    local device="${1:?}"
    # prints identification information for an Opal device.

    echo "'$device' ($(opal_device_attribute "$device" "model"))"
}

function opal_device_information() {
    # prints information about Opal devices given as arguments.

    local device
    local format="%-14s %-30s %-6s %-12s %-5s  %-9s  %-6s  %s\n"

    echo "$(printf "$format" "DEVICE" "MODEL" "I/F" "FIRMWARE" "SETUP" "ENCRYPTED" "LOCKED" "SHADOW MBR")"

    for device in "$@"; do
        source "$(opal_device_attributes "$device" attributes)"

        printf "$format" "$device" "${attributes[model]}" "${attributes[interface]}" \
            "${attributes[firmware]}" "${attributes[setup]}" "${attributes[encrypted]}" "${attributes[locked]}" \
            "${attributes[mbr]}"
    done
}

function opal_device_max_authentications() {
    local device="${1:?}"
    # prints the maximum number of authentication attempts for the device.
    # When the maximum number of authentication attempts has been reached, an Opal device needs to be power-cycled
    # before accepting any further authentications.

    sedutil-cli --query "$device" | sed -r -e '/MaxAuthentications/ { s/.*MaxAuthentications *= *([0-9]+).*/\1/; p }' -e 'd'
}

function opal_device_setup() {
    local device="${1:?}"
    local password="${2:?}"
    # enables Opal locking, sets an Admin1 and SID password, disables the MBR.
    # Returns 0 on success.

    sedutil-cli --initialSetup "$password" "$device" && sedutil-cli --enablelockingrange 0 "$password" "$device"
}

function opal_device_change_password() {
    local device="${1:?}"
    local old_password="${2:?}"
    local new_password="${3:?}"
    # sets a new Admin1 and SID password, returns 0 on success

    sedutil-cli --setSIDPassword "$old_password" "$new_password" "$device" &&
    sedutil-cli --setAdmin1Pwd "$old_password" "$new_password" "$device"
}

function opal_device_regenerate_dek_ERASING_ALL_DATA() {
    local device="${1:?}"
    local password="${2:?}"
    # re-generates the manufacturer-assigned data encryption key (DEK), ERASING ALL DATA ON THE DRIVE.
    # This is recommended initially to ensure that the data encryption key is not known by any third party.
    # Returns 0 on success.

    sedutil-cli --rekeyLockingRange 0 "$password" "$device" && partprobe $(opal_device_disks "$device")
}

function opal_device_factory_reset_ERASING_ALL_DATA() {
    local device="${1:?}"
    local password="${2:?}"
    # factory-resets the device, ERASING ALL DATA ON THE DRIVE, returns 0 on success

    sedutil-cli --reverttper "$password" "$device" && partprobe $(opal_device_disks "$device")
}

function opal_device_load_pba_image() {
    local device="${1:?}"
    local password="${2:?}"
    local pba_image_file="${3:?}"
    # loads a PBA image into the device's shadow MBR, returns 0 on success.

    sedutil-cli --loadPBAimage "$password" "$pba_image_file" "$device" >&7  # show progress
}

function opal_device_mbr_is_enabled() {
    local device="${1:?}"
    # returns 0 if the device's shadow MBR has been enabled.

    [[ "$(opal_device_attribute "$device" "mbr")" != "disabled" ]]
}

function opal_device_disable_mbr() {
    local device="${1:?}"
    local password="${2:?}"
    # disables the device's shadow MBR, returns 0 on success.

    sedutil-cli --setMBREnable off "$password" "$device" && partprobe $(opal_device_disks "$device")
}

function opal_device_enable_mbr() {
    local device="${1:?}"
    local password="${2:?}"
    # enables the device's shadow MBR in hidden mode, returns 0 on success.

    sedutil-cli --setMBREnable on "$password" "$device" && opal_device_hide_mbr "$device" "$password"
}

function opal_device_hide_mbr() {
    local device="${1:?}"
    local password="${2:?}"
    # hides the device's shadow MBR if one has been enabled, does nothing otherwise.
    # Returns 0 on success.

    sedutil-cli --setMBRDone on "$password" "$device" && partprobe $(opal_device_disks "$device")
}

function opal_device_unlock() {
    local device="${1:?}"
    local password="${2:?}"
    # attempts to unlock the device (locking range 0 spanning the entire disk) and hide the MBR, if any.
    # Returns 0 on success.

    sedutil-cli --setLockingRange 0 RW "$password" "$device" && opal_device_hide_mbr "$device" "$password"
}

function opal_device_deactivate_locking() {
    local device="${1:?}"
    local password="${2:?}"
    # attempts to permanently deactivate the locking mechanism (locking range 0 spanning the entire disk) on device
    # and disable the MBR.
    # Returns 0 on success.

    sedutil-cli --disableLockingRange 0 "$password" "$device" && opal_device_disable_mbr "$device" "$password"
}

function opal_device_reactivate_locking() {
    local device="${1:?}"
    local password="${2:?}"
    # attempts to permanently reactivate the locking mechanism (locking range 0 spanning the entire disk) on device
    # and re-enable the MBR.
    # Returns 0 on success.

    # Explicitly issuing an unlock command before reactivating locking seems strange as the device is not supposed
    # to be locked currently. However, this extra unlock command ensures that the device remains in an
    # unlocked state when locking is reactivated.
    # Otherwise, if (1) a system boots up with a locked device, (2) locking is deactivated, (3) locking is reactivated
    # without issuing an extra unlock command before, the device will lock immediately. A locked device may trigger lots
    # of kernel disk access errors:
    #    [...]
    #    kernel: ata1.00: status: { DRDY ERR }
    #    kernel: ata1.00: error: { ABRT }
    #    kernel: ata1.00: supports DRM functions and may not be fully accessible
    #    kernel: ata1.00: NCQ Send/Recv Log not supported
    #    [...]
    opal_device_unlock "$device" "$password"  # errors are intentionally ignored here

    sedutil-cli --enableLockingRange 0 "$password" "$device" && opal_device_enable_mbr "$device" "$password"
}

function opal_disk_partition_information() {
    local device="${1:?}"
    # prints disk and partition information.

    lsblk --fs --output NAME,MOUNTPOINT,FSTYPE,SIZE "$device"
}

function opal_disk_has_partitions() {
    local device="${1:?}"
    # returns 0 if the disk has one or more partitions.

    blkid "$device" | grep --quiet .
}

function opal_disk_has_mounted_partitions() {
    local device="${1:?}"
    # returns 0 if the disk has one or more mounted partitions.

    lsblk -l --fs --output MOUNTPOINT --noheadings "$device" | grep --quiet .
}

function opal_bytes_to_mib() {
    local bytes="${1:?}"
    # prints bytes converted to MiB with two decimal digits.

    bc <<< "scale=2; $bytes / (1024 * 1024)"
}


#
# These functions are meant to be used within ReaR. They require ReaR functions, the usual ReaR logging setup, and
# will raise errors via ReaR.
#

function opal_check_pba_image() {
    local pba_image_file="${1:?}"
    # generates an error if the PBA image is larger than the guaranteed MBR capacity.
    # REQUIRES ReaR.

    [[ -f "$pba_image_file" ]] || Error "'$pba_image_file' is not a regular file, thus cannot be used as TCG Opal 2 PBA image."

    local -i file_size=$(stat --printf="%s\n" "$pba_image_file")
    local -i mbr_size_limit=$((128 * 1024 * 1024))  # guaranteed minimum MBR size: 128 MiB (Opal 2 spec, section 4.3.5.4)

    if (( file_size > mbr_size_limit )); then
        local file_size_MiB="$(opal_bytes_to_mib $file_size) MiB"
        local mbr_size_limit_MiB="$(opal_bytes_to_mib $mbr_size_limit) MiB"
        Error "TCG Opal 2 PBA image file '$pba_image_file' is $file_size_MiB in size, allowed maximum is $mbr_size_limit_MiB."
    fi
}

function opal_local_pba_image_file() {
    # prints the path of a local TCG Opal 2 PBA image file, if available, else nothing.
    # REQUIRES ReaR.

    local image_file_path="$OPAL_PBA_IMAGE_FILE"

    if [[ -z "$image_file_path" && -n "$OPAL_PBA_OUTPUT_URL" ]]; then
        local image_base_scheme="$(url_scheme "$OPAL_PBA_OUTPUT_URL")"
        local image_base="$(url_path "$OPAL_PBA_OUTPUT_URL")"

        [[ "$image_base_scheme" == "file" ]] && image_file_path="$image_base/$HOSTNAME/TCG-Opal-PBA-$HOSTNAME.raw"
    fi

    if [[ -n "$image_file_path" ]]; then
        opal_check_pba_image "$image_file_path"
        echo "$image_file_path"
    fi
}

function opal_password_input() {
    local id="${1:?}"
    local prompt="${2:?}"
    # prints secret user input after verifying that it is non-empty.
    # REQUIRES ReaR.

    local password

    while true; do
        password="$(UserInput -I "$id" -C -r -s -t 0 -p "$prompt")"
        [[ -n "$password" ]] && break
        PrintError "Please enter a non-empty password."
    done

    UserOutput ""
    echo "$password"
}

function opal_checked_password_input() {
    local id="${1:?}"
    local password_name="${2:?}"
    # prints secret user input after verifying that it is non-empty and it has been entered identically twice.
    # REQUIRES ReaR.

    local password

    while true; do
        password="$(opal_password_input "$id" "Enter $password_name: ")"
        local password_repeated="$(opal_password_input "$id" "Repeat $password_name: ")"

        [[ "$password_repeated" == "$password" ]] && break

        PrintError "Passwords do not match."
    done

    echo "$password"
}

function opal_choice_input() {
    local id="${1:?}"
    local prompt="${2:?}"
    shift 2
    local choices=( "$@" )
    # prints user input after verifying that it complies with one of the choices specified.
    # Choices must be entered exactly.
    # REQUIRES ReaR.

    while true; do
        result="$(UserInput -I "$id" -t 0 -p "$prompt")"
        IsInArray "$result" "${choices[@]}" && break
    done

    echo "$result"
}

function opal_device_recreate_setup() {
    local device="${1:?}"
    local password="${2:?}"
    # sets up the device, initiates a factory reset if necessary.
    # REQUIRES ReaR.

    if [[ "$(opal_device_attribute "$device" "setup")" == "y" ]]; then
        if ! opal_device_factory_reset_ERASING_ALL_DATA "$device" "$password"; then
            LogPrintError "Could not reset Opal 2 disk $device to factory defaults."
            LogPrintError "If the log shows 'method status code NOT_AUTHORIZED', you could use"
            LogPrintError "'rear opaladmin factoryRESET $device' with a different password."
            LogPrintError "Otherwise, use 'sedutil-cli --PSIDrevert <PSID> $device' to factory-reset"
            LogPrintError "the disk using the 32 byte PSID printed on the drive label."
            Error "After factory-resetting the disk, you may continue recovery."
        fi
        Log "Opal 2 disk $device reset to factory defaults, data erased."
    fi

    opal_device_setup "$device" "$password" || Error "Could not set up $device."
    Log "Opal 2 disk $device set up."

    opal_device_regenerate_dek_ERASING_ALL_DATA "$device" "$password" ||
        Error "Could not reset data encryption key (DEK) of Opal 2 disk $device."
    Log "Data encryption key (DEK) of Opal 2 disk $device reset, data erased."
}

function opal_device_recreate_boot_support() {
    local device="${1:?}"
    local password="${2:?}"
    local pba_image_file="${3:?}"
    # prepares the device for booting.
    # REQUIRES ReaR.

    opal_device_enable_mbr "$device" "$password" ||
        Error "Could not enable the shadow MBR on Opal 2 disk $device."
    opal_device_load_pba_image "$device" "$password" "$pba_image_file" ||
        Error "Could not upload the PBA image '$pba_image_file' to Opal 2 disk $device."
    Log "Opal 2 disk $device: Shadow MBR enabled and PBA uploaded."
}