From Fedora Project Wiki
No edit summary
(adding release notes tracker)
 
(7 intermediate revisions by 2 users not shown)
Line 3: Line 3:
= Self Encrypting Drives Support in the Installer =
= Self Encrypting Drives Support in the Installer =


{{Change_Proposal_Banner}}


== Summary ==
== Summary ==
Line 24: Line 23:


== Current status ==
== Current status ==
[[Category:ChangePageIncomplete]]
[[Category:ChangeAcceptedF41]]
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
Line 40: Line 39:
ON_QA -> change is fully code complete
ON_QA -> change is fully code complete
-->
-->
* [Announced]
* [https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/thread/KI2YKYTVJIYB6MQHF3OVMHU27CL3EUSF/ Announced]
* [<will be assigned by the Wrangler> Discussion thread]
* [https://discussion.fedoraproject.org/t/f41-change-proposal-self-encrypting-drives-support-in-the-installer-self-contained/125529 Discussion thread]
* FESCo issue: <will be assigned by the Wrangler>
* FESCo issue: [https://pagure.io/fesco/issue/3250 #3250]
* Tracker bug: <will be assigned by the Wrangler>
* Tracker bug: [https://bugzilla.redhat.com/show_bug.cgi?id=2304174 #2304174]
* Release notes tracker: <will be assigned by the Wrangler>
* Release notes tracker: [https://gitlab.com/fedora/docs/fedora-linux-documentation/release-notes/-/issues/119 #119]


== Detailed Description ==
== Detailed Description ==
Line 50: Line 49:
Some SATA and NVMe devices support hardware encryption (TCG OPAL2 standard) and with the latest cryptsetup LUKS devices can be configured to use hardware encryption to encrypt the data either by itself or together with the existing dm-crypt software encryption. Support for this feature was added in the latest cryptsetup upstream release and we'd like to provide an option for users to use this feature when installing Fedora with disk encryption.
Some SATA and NVMe devices support hardware encryption (TCG OPAL2 standard) and with the latest cryptsetup LUKS devices can be configured to use hardware encryption to encrypt the data either by itself or together with the existing dm-crypt software encryption. Support for this feature was added in the latest cryptsetup upstream release and we'd like to provide an option for users to use this feature when installing Fedora with disk encryption.


As this is an expert option, it will be available only through the kickstart interface. The existing `--luks-version` option which allows choosing between LUKS1 and LUKS2 versions will be extended to enable configuring hardware encryption as an addition to the software encryption layer or to select hardware encryption only.
As this is an expert option, it will be available only through the kickstart interface. The existing --luks-version option which allows choosing between LUKS1 and LUKS2 versions when configuring device encryption will be extended to enable using hardware encryption. There will be two new options to select either hardware encryption only or hardware encryption in combination with software encryption (analogous to the `--hw-opal-only` and `--hw-opal` options used when configuring hardware encryption with `cryptsetup`).


Using hardware encryption only can be beneficial on low-performance systems where utilising the CPU to encrypt the data when reading/writing from/to the disk can significantly affect the system's performance. Using both software and hardware encryption layers increases the security margin by adding an additional layer of protection.
Using hardware encryption only can be beneficial on low-performance systems where utilising the CPU to encrypt the data when reading/writing from/to the disk can significantly affect the system's performance. Using both software and hardware encryption layers increases the security margin by adding an additional layer of protection.


Note: We'd like to emphasise that we do not intend to enable this feature by default, it must be explicitly selected by the user. Using the option to set up only hardware encryption can be risky as it places the trust fully in the disk manufacturer's ability to implement the data encryption in the disk firmware correctly.
Note: We'd like to emphasize that we do not intend to enable this feature by default, it must be explicitly selected by the user. Using the option to set up only hardware encryption can be risky as it places the trust fully in the disk manufacturer's ability to implement the data encryption in the disk firmware correctly.


== Benefit to Fedora ==
== Benefit to Fedora ==
Line 79: Line 78:


== How To Test ==
== How To Test ==
A special hardware is required for testing -- you need a disk that supports the OPAL specification. You can check for OPAL support using the `sedutil-cli` utility (provided by the `sedutil` package), simply run `sudo sedutil-cli --scan` to scan for OPAL compliant disks.
A special hardware is required for testing -- you need a disk that supports the OPAL specification. You can check for OPAL support using the `sedutil-cli` utility (provided by the `sedutil` package), simply run `sudo sedutil-cli --scan` to scan for OPAL compliant disks (second column which shows OPAL version supported by the disk should show `2`).


Because this feature is not configurable from the GUI you need to run a [[Anaconda/Kickstart|kickstart installation]]. Sample kickstart file for encrypted automatic partitioning is shown below.
''Example of disk with OPAL2 support:''


   autopart --type=lvm --encrypted --passphrase="passphrase" --luks-version=luks2-hw-opal --opal-admin-passphrase="..."
  Scanning for Opal compliant disks
  /dev/nvme0  2  SAMSUNG MZVLB256HBHQ-000L7              5M2QEXH7
 
''Example of disk without OPAL2 support:''
 
  Scanning for Opal compliant disks
  /dev/nvme0 No  Force MP510                              ECFM22.5
 
'''Note:''' If something goes wrong, you might need to perform PSID reset of the disk to remove all OPAL locking ranges. You'll need to enter the disk PSID for this which is printed on the disk. '''Note that PSID reset will remove all data on the entire disk.''' We strongly discourage from testing this feature on a disk with any user data on it! To run PSID reset use `sudo cryptsetup luksErase --hw-opal-factory-reset`.
 
Because this feature is not configurable from the GUI you need to run a [[Anaconda/Kickstart|kickstart installation]]. Sample kickstart filse are shown below.
 
''Automatic partitioning with both software and hardware encryption configured:''
 
  ignoredisk --only-use=nvme0n1
   autopart --type=lvm --encrypted --luks-version=luks2-hw-opal --hw-passphrase="..." --passphrase="..."
 
''Automatic partitioning with hardware encryption only:''
 
  ignoredisk --only-use=nvme0n1
  autopart --type=lvm --encrypted --luks-version=luks2-hw-opal-only --hw-passphrase="..." --passphrase="..."
 
''Manual partitioning:''
 
  ignoredisk --only-use=nvme0n1
  reqpart
  part / --fstype="ext4" --size=7891 --encrypted --luks-version=luks2-hw-opal --hw-passphrase="..." --passphrase="..."
  part /boot --fstype="ext4" --size=1024
  part swap --fstype="swap" --size=1024


(The exact syntax might change, we'll provide more detailed kickstart files for testing later.)


After the installation check that the correct setup for LUKS was used by running `sudo cryptsetup luksDump <device>`. Check the `Data segments` section, it should say either `hw-opal-crypt` for combination of hardware and software encryption
After the installation check that the correct setup for LUKS was used by running `sudo cryptsetup luksDump <device>`. Check the `Data segments` section, it should say either `hw-opal-crypt` for combination of hardware and software encryption


  LUKS header information
  LUKS header information
  Version:       2
  Version:       2
    ...
  ...
  Data segments:
  Subsystem:    HW-OPAL
    0: hw-opal-crypt
  ...
  Requirements: opal
 
  Data segments:
      0: hw-opal-crypt
        offset: 16777216 [bytes]
        length: 254339448832 [bytes]
        cipher: aes-xts-plain64
        sector: 4096 [bytes]
        HW OPAL encryption:
            OPAL segment number: 3
  ...


or `hw-opal` for hardware encryption only
or `hw-opal` for hardware encryption only


   LUKS header information
   LUKS header information
   Version:       2
   ...
    ...
  Subsystem:     HW-OPAL
  ...
  Requirements: opal
 
   Data segments:
   Data segments:
       0: hw-opal
       0: hw-opal
        offset: 16777216 [bytes]
        length: 254339448832 [bytes]
        cipher: (no SW encryption)
        HW OPAL encryption:
            OPAL segment number: 3
  ...


(`crypt` is shown for software encryption only which is default behaviour).
(`crypt` is shown for software encryption only which is default behaviour).
'''Note:''' Anaconda currently cannot remove existing LUKS OPAL devices (including those created by the kickstart files above) because removing such devices require the OPAL administrator passphrase. To remove an existing device you must use `sudo cryptsetup luksErase /dev/nvme0n1pX` command. If you remove the LUKS header or the partition with any other tools (e.g. with `wipefs`) the only way to remove the OPAL locking range is by running PSID reset destroying all data on the disk!


== User Experience ==
== User Experience ==

Latest revision as of 15:28, 14 October 2024


Self Encrypting Drives Support in the Installer

Summary

Add optional support for using native hardware encryption on TCG OPAL2 compliant drives when configuring disk encryption in the installer.

Owner

Current status

Detailed Description

Some SATA and NVMe devices support hardware encryption (TCG OPAL2 standard) and with the latest cryptsetup LUKS devices can be configured to use hardware encryption to encrypt the data either by itself or together with the existing dm-crypt software encryption. Support for this feature was added in the latest cryptsetup upstream release and we'd like to provide an option for users to use this feature when installing Fedora with disk encryption.

As this is an expert option, it will be available only through the kickstart interface. The existing --luks-version option which allows choosing between LUKS1 and LUKS2 versions when configuring device encryption will be extended to enable using hardware encryption. There will be two new options to select either hardware encryption only or hardware encryption in combination with software encryption (analogous to the --hw-opal-only and --hw-opal options used when configuring hardware encryption with cryptsetup).

Using hardware encryption only can be beneficial on low-performance systems where utilising the CPU to encrypt the data when reading/writing from/to the disk can significantly affect the system's performance. Using both software and hardware encryption layers increases the security margin by adding an additional layer of protection.

Note: We'd like to emphasize that we do not intend to enable this feature by default, it must be explicitly selected by the user. Using the option to set up only hardware encryption can be risky as it places the trust fully in the disk manufacturer's ability to implement the data encryption in the disk firmware correctly.

Benefit to Fedora

Scope

  • Proposal owners:
    • This feature is not yet implemented in the upstream so we'll need to add support for the new LUKS-OPAL format to both the backend storage libraries (blivet and libblockdev) and the installer itself. As this is only expanding and existing feature (disk encryption) already present in the installer, the changes will be relatively small (especially in the installer itself).
  • Other developers:
    • No work from other developers should be needed.
  • Policies and guidelines: N/A (not needed for this Change)
  • Trademark approval: N/A (not needed for this Change)
  • Alignment with the Fedora Strategy:

Upgrade/compatibility impact

This change will affect only new installations.

How To Test

A special hardware is required for testing -- you need a disk that supports the OPAL specification. You can check for OPAL support using the sedutil-cli utility (provided by the sedutil package), simply run sudo sedutil-cli --scan to scan for OPAL compliant disks (second column which shows OPAL version supported by the disk should show 2).

Example of disk with OPAL2 support:

 Scanning for Opal compliant disks
 /dev/nvme0  2  SAMSUNG MZVLB256HBHQ-000L7               5M2QEXH7

Example of disk without OPAL2 support:

 Scanning for Opal compliant disks
 /dev/nvme0 No  Force MP510                              ECFM22.5

Note: If something goes wrong, you might need to perform PSID reset of the disk to remove all OPAL locking ranges. You'll need to enter the disk PSID for this which is printed on the disk. Note that PSID reset will remove all data on the entire disk. We strongly discourage from testing this feature on a disk with any user data on it! To run PSID reset use sudo cryptsetup luksErase --hw-opal-factory-reset.

Because this feature is not configurable from the GUI you need to run a kickstart installation. Sample kickstart filse are shown below.

Automatic partitioning with both software and hardware encryption configured:

 ignoredisk --only-use=nvme0n1
 autopart --type=lvm --encrypted --luks-version=luks2-hw-opal --hw-passphrase="..." --passphrase="..."

Automatic partitioning with hardware encryption only:

 ignoredisk --only-use=nvme0n1
 autopart --type=lvm --encrypted --luks-version=luks2-hw-opal-only --hw-passphrase="..." --passphrase="..."

Manual partitioning:

 ignoredisk --only-use=nvme0n1
 reqpart
 part / --fstype="ext4" --size=7891 --encrypted --luks-version=luks2-hw-opal --hw-passphrase="..." --passphrase="..."
 part /boot --fstype="ext4" --size=1024
 part swap --fstype="swap" --size=1024


After the installation check that the correct setup for LUKS was used by running sudo cryptsetup luksDump <device>. Check the Data segments section, it should say either hw-opal-crypt for combination of hardware and software encryption

  LUKS header information
  Version:       	2
  ...
  Subsystem:     	HW-OPAL
  ...
  Requirements:	opal 
  
  Data segments:
     0: hw-opal-crypt
        offset: 16777216 [bytes]
        length: 254339448832 [bytes]
        cipher: aes-xts-plain64
        sector: 4096 [bytes]
        HW OPAL encryption:
           OPAL segment number: 3
  ...

or hw-opal for hardware encryption only

  LUKS header information
  ...
  Subsystem:     	HW-OPAL
  ...
  Requirements:	opal 
  
  Data segments:
     0: hw-opal
        offset: 16777216 [bytes]
        length: 254339448832 [bytes]
        cipher: (no SW encryption)
        HW OPAL encryption:
           OPAL segment number: 3
  ...

(crypt is shown for software encryption only which is default behaviour).

Note: Anaconda currently cannot remove existing LUKS OPAL devices (including those created by the kickstart files above) because removing such devices require the OPAL administrator passphrase. To remove an existing device you must use sudo cryptsetup luksErase /dev/nvme0n1pX command. If you remove the LUKS header or the partition with any other tools (e.g. with wipefs) the only way to remove the OPAL locking range is by running PSID reset destroying all data on the disk!

User Experience

After the installation users shouldn't notice any differences, the system will behave in the same way as with "normal" disk encryption.

Dependencies

Following projects needs to be changed for this feature: anaconda, blivet, kickstart, libblockdev. All necessary changes will be done by the change owners.

cryptsetup with the LUKS-OPAL support is already available in Fedora 41 and no other changes will be needed for the support in the installer.

Once configured the LUKS-OPAL device works in the same way any other "normal" LUKS devices work so there is no need to change any other tools for this feature to work (e.g. unlocking the LUKS-OPAL device doesn't require special configuration).

Contingency Plan

  • Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
    • No specific contingency plan is needed, we will simply not include the feature if we fail to implement all the necessary changes in time.
  • Contingency deadline: N/A (not a System Wide Change)
  • Blocks release? No

Documentation

Release Notes