From Fedora Project Wiki
(Add trackers)
 
(24 intermediate revisions by 3 users not shown)
Line 2: Line 2:


== Summary ==
== Summary ==
Stratis supports per-pool encryption of the devices that form a pool's data tier. A pool may be encrypted, or its constituent encrypted devices may be activated, by means of a key stored in the kernel keyring.
Stratis now supports per-pool encryption of the devices that form a pool's data tier. A pool may be encrypted, or its constituent encrypted devices may be activated, by means of a key stored in the kernel keyring.


== Owner ==
== Owner ==
Line 9: Line 9:


== Current Status ==
== Current Status ==
[[Category:ChangePageIncomplete]]
[[Category:ChangeAcceptedF33]]
[[Category:SelfContainedChange]]
[[Category:SelfContainedChange]]


Line 21: Line 21:
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
-->
-->
* FESCo issue:  
* FESCo issue: [https://pagure.io/fesco/issue/2455 #2455]
* Tracker bug:
* Tracker bug: [https://bugzilla.redhat.com/show_bug.cgi?id=1866521 #1866521]
* Release notes tracker:
* Release notes tracker: [https://pagure.io/fedora-docs/release-notes/issue/543 #543]


== Detailed Description ==
== Detailed Description ==
Line 35: Line 35:
It implements encryption support in the following way:
It implements encryption support in the following way:


A single instance of stratisd can support both encrypted and unencrypted pools.
* A single instance of stratisd can support both encrypted and unencrypted pools.
The choice to encrypt a pool must be made at the time a pool is created.
The choice to encrypt a pool must be made at the time a pool is created.
At present, the use of a cache and of encryption are mutually exclusive; if the pool is created with encryption enabled, then it is not possible to create a cache.
 
Each pool may be encrypted by means of a key in the kernel keyring; each encrypted pool may make use of a different key, but all devices in a pool are encrypted with a single key.
* At present, the use of a cache and of encryption are mutually exclusive; if the pool is created with encryption enabled, then it is not possible to create a cache.
Any additional devices that are added to an encrypted pool's data tier will be encrypted using the key that was specified when the pool was initialized.
 
* Each pool may be encrypted by means of a key in the kernel keyring; each encrypted pool may make use of a different key, but all devices in a pool are encrypted with a single key.
 
* Any additional devices that are added to an encrypted pool's data tier will be encrypted using the key that was specified when the pool was initialized.


=== stratisd 2.1.0 supplies several new D-Bus interfaces: ===
=== stratisd 2.1.0 supplies several new D-Bus interfaces: ===


* org.storage.stratis2.manager.r1: This interface supplies an extended CreatePool method, to support an optional argument for encryption. In addition, it supplies a number of method for key management.
* org.storage.stratis2.manager.r1: This interface supplies an extended CreatePool method, to support an optional argument for encryption. In addition, it supplies a number of methods for key management.


* org.storage.stratis2.pool.r1: This interface supports explicit initialization of a cache tier. Previously, a cache was initialized as a side-effect of the addition of the first device to the cache tier. It also supports the new Encrypted property.
* org.storage.stratis2.pool.r1: This interface supports explicit initialization of a cache tier. Previously, a cache was initialized as a side-effect of the addition of the first device to the cache tier. It also supports the new Encrypted property.
Line 64: Line 67:
This release requires stratisd 2.1.0. The user will observe the following changes:
This release requires stratisd 2.1.0. The user will observe the following changes:


The pool create command has been extended to allow encryption.
* The pool create command has been extended to allow encryption.
There is a new pool init_cache command, for initializing a cache.
 
There is a new subcommand, key, for key management tasks.
* There is a new pool init_cache command for initializing a cache.
There is a new subcommand, report, which allows the display of certain reports generated by stratisd.
 
The output of pool list now includes a Properties column; each entry in the column is a string encoding the following properties of the pool:
* There is a new subcommand, key, for key management tasks.
whether or not it has a cache
 
whether or not it is encrypted
* There is a new subcommand, report, which allows the display of certain reports generated by stratisd.
All commands now verify that stratis is communicating with a compatible version of stratisd and will fail with an appropriate error if stratisd is found to have an incompatible version.
 
* The output of pool list now includes a Properties column; each entry in the column is a string encoding the following properties of the pool: (1) whether or not it has a cache, (2) whether or not it is encrypted.
 
* All commands now verify that stratis is communicating with a compatible version of stratisd and will fail with an appropriate error if stratisd is found to have an incompatible version.


=== Usage ===
=== Usage ===
To create an encrypted pool, a user must first ensure that a key is placed in the kernel keyring. We strongly encourage using the commands available via the stratis key subcommand for this task. This key, which is secret, has a corresponding key description, which is public.
To create an encrypted pool, a user must first ensure that a key is placed in the kernel keyring. We strongly encourage using the commands available via the stratis "key" subcommand for this task. This key, which is secret, has a corresponding key description, which is public.


An encrypted pool is then created by specifying the key description when using the pool create command.
An encrypted pool is then created by specifying the key description when using the pool create command.
Line 83: Line 89:


== Benefits to Fedora ==
== Benefits to Fedora ==
* A new feature that allows users to create pools of encrypted storage to protect data-at-rest
* A new feature that allows users to create pools that encrypt all data devices and consequently securely store all user data.


== Scope ==
== Scope ==
* Proposal owners:
* Proposal owners:
** Package Rust crate libcryptsetup-rs
** Package Rust crate libcryptsetup-rs
** Specfile changes for stratis-cli and stratisd
** Update existing stratis-cli package to specify new release
** Update existing stratisd package to specify new release
* Other developers: N/A
* Other developers: N/A
* Release engineering: Self Contained
* Release engineering: Self Contained
Line 95: Line 102:


== Upgrade/compatibility impact ==
== Upgrade/compatibility impact ==
Not expected to impact users this change should not impact upgrade-ability.
None anticipated.


== How To Test ==
== How To Test ==
* Testing encryption can be done using the CLI or API. 
* Testing encryption can be done using the CLI provided by stratis-cli or the D-Bus API provided by stratisd.
* Both stratisd and stratis-cli will need to be tested by maintainers to assure
* Basic testing of encrypted pool and filesystem create and destroy via stratis-cli:
the packages continue to work.
   stratis key set --keyfile-path keyfile k1 # requires that the file keyfile contains a key
* Basic testing of encrypted pool and filesystem create and destroy
   stratis key set --keyfile-path keyfile k1
   stratis pool create --key-desc k1 p1 /dev/sdb
   stratis pool create --key-desc k1 p1 /dev/sdb
   stratis fs create p1 fs1  # from here you can mount /stratis/p1/fs1 /mnt and write and read data
   stratis fs create p1 fs1  # from here you can mount /stratis/p1/fs1 and write and read data
   stratis blockdev list
   stratis blockdev list
   stratis pool list
   stratis pool list
Line 113: Line 118:
== User Experience ==
== User Experience ==
Users with existing filesystems will not notice any changes.
Users with existing filesystems will not notice any changes.
Users creating new pools can read the documentation on how to make use of the new encryption feature.
Users creating new pools can read the documentation on how to make use of the new encryption feature as well as the new mechanism for instantiating a cache.


== Dependencies ==
== Dependencies ==
libcryptsetup-rs is the major dependency, which has already landed.  Other minor dependencies are already available in Fedora
We are not aware of any packages that depend on stratisd besides stratis-cli which we are releasing with the necessary updates. In any case, such a package would continue to work with stratisd because of stratisd's support for versioned D-Bus interfaces. stratisd added a new dependency on libcryptsetup-rs; this crate has been packaged and is available in rawhide.
 
== Contingency Plan ==
== Contingency Plan ==
* Contingency mechanism:  
* Contingency mechanism:  
Line 129: Line 135:


== Release Notes ==
== Release Notes ==
Includes recent version of Stratis which supports encryption.

Latest revision as of 19:01, 5 August 2020

Stratis 2.1.0

Summary

Stratis now supports per-pool encryption of the devices that form a pool's data tier. A pool may be encrypted, or its constituent encrypted devices may be activated, by means of a key stored in the kernel keyring.

Owner

Current Status

Detailed Description

Stratis 2.1.0 introduces support for encryption.

It supports per-pool encryption of the devices that form a pool's data tier. A pool may be encrypted, or its constituent encrypted devices may be activated, by means of a key stored in the kernel keyring.

stratisd 2.1.0

This release implements encryption support and adds several new D-Bus interfaces to administer or monitor that support.

It implements encryption support in the following way:

  • A single instance of stratisd can support both encrypted and unencrypted pools.

The choice to encrypt a pool must be made at the time a pool is created.

  • At present, the use of a cache and of encryption are mutually exclusive; if the pool is created with encryption enabled, then it is not possible to create a cache.
  • Each pool may be encrypted by means of a key in the kernel keyring; each encrypted pool may make use of a different key, but all devices in a pool are encrypted with a single key.
  • Any additional devices that are added to an encrypted pool's data tier will be encrypted using the key that was specified when the pool was initialized.

stratisd 2.1.0 supplies several new D-Bus interfaces:

  • org.storage.stratis2.manager.r1: This interface supplies an extended CreatePool method, to support an optional argument for encryption. In addition, it supplies a number of methods for key management.
  • org.storage.stratis2.pool.r1: This interface supports explicit initialization of a cache tier. Previously, a cache was initialized as a side-effect of the addition of the first device to the cache tier. It also supports the new Encrypted property.
  • org.storage.stratis2.FetchProperties.r1: This interface supports an additional HasCache property.
  • org.storage.stratis2.Report.r1: This interface supports a set of ad-hoc reports about Stratis. The interface is unstable; the names by which the reports can be accesed are not guaranteed to remain stable, and the format of any report is only guaranteed to be valid JSON.

Please consult the D-Bus API Reference for the precise D-Bus specification.

The following are significant implementation details:

  • Each block device in an encrypted pool's data tier is encrypted with a distinct, randomly chosen MEK (Media Encryption Key) on initialization.
  • All devices belonging to a single encrypted pool share a single passphrase, supplied via the kernel keyring.
  • The release requires cryptsetup version 2.3.

stratis-cli 2.1.0

This release requires stratisd 2.1.0. The user will observe the following changes:

  • The pool create command has been extended to allow encryption.
  • There is a new pool init_cache command for initializing a cache.
  • There is a new subcommand, key, for key management tasks.
  • There is a new subcommand, report, which allows the display of certain reports generated by stratisd.
  • The output of pool list now includes a Properties column; each entry in the column is a string encoding the following properties of the pool: (1) whether or not it has a cache, (2) whether or not it is encrypted.
  • All commands now verify that stratis is communicating with a compatible version of stratisd and will fail with an appropriate error if stratisd is found to have an incompatible version.

Usage

To create an encrypted pool, a user must first ensure that a key is placed in the kernel keyring. We strongly encourage using the commands available via the stratis "key" subcommand for this task. This key, which is secret, has a corresponding key description, which is public.

An encrypted pool is then created by specifying the key description when using the pool create command.

It is necessary that the correct key and corresponding key description be set in the kernel keyring in order to set up a previously encrypted pool. Setting up a previously encrypted pool requires an explicit pool unlock command from the user. This command will attempt to unlock the devices belonging to any previously encrypted pool; it can only unlock all devices if a key for every encrypted pool is in the keyring. Once the devices belonging to a previously encrypted pool have been unlocked, the pool will be set up, and can be used in exactly the same manner as an unencrypted pool.

Feedback

Benefits to Fedora

  • A new feature that allows users to create pools that encrypt all data devices and consequently securely store all user data.

Scope

  • Proposal owners:
    • Package Rust crate libcryptsetup-rs
    • Update existing stratis-cli package to specify new release
    • Update existing stratisd package to specify new release
  • Other developers: N/A
  • Release engineering: Self Contained
  • Policies guidelines: N/A
  • Trademark approval: N/A

Upgrade/compatibility impact

None anticipated.

How To Test

  • Testing encryption can be done using the CLI provided by stratis-cli or the D-Bus API provided by stratisd.
  • Basic testing of encrypted pool and filesystem create and destroy via stratis-cli:
 stratis key set --keyfile-path keyfile k1 # requires that the file keyfile contains a key
 stratis pool create --key-desc k1 p1 /dev/sdb
 stratis fs create p1 fs1   # from here you can mount /stratis/p1/fs1 and write and read data
 stratis blockdev list
 stratis pool list
 stratis fs list
 stratis fs destroy p1 fs1
 stratis pool destroy p1

User Experience

Users with existing filesystems will not notice any changes. Users creating new pools can read the documentation on how to make use of the new encryption feature as well as the new mechanism for instantiating a cache.

Dependencies

We are not aware of any packages that depend on stratisd besides stratis-cli which we are releasing with the necessary updates. In any case, such a package would continue to work with stratisd because of stratisd's support for versioned D-Bus interfaces. stratisd added a new dependency on libcryptsetup-rs; this crate has been packaged and is available in rawhide.

Contingency Plan

  • Contingency mechanism:
  • Contingency deadline: N/A
  • Blocks release? No
  • Blocks product? No

Documentation

Please see https://stratis-storage.github.io/ for design documents and API reference.

Development and issue tracking is at https://github.com/stratis-storage/stratisd

Release Notes

Includes recent version of Stratis which supports encryption.