Changes/Stratis 2.3.0

Stratis 2.3.0

Summary

Stratis 2.3.0 adds additional flexibility to its encryption support via Clevis.

Owner

• Name: Dennis Keefe, Anne Mulhern, John Baublitz

• Email: dkeefe@redhat.com, amulhern@redhat.com, jbaublitz@redhat.com

Current status

• Targeted release: Fedora 34
• Last updated: 2021-01-07
• FESCo issue: #2521
• Tracker bug: #1912509
• Release notes tracker: #623

Detailed Description

Stratis 2.3.0

This release extends the pool unlock command, and adds two new commands, pool bind and pool unbind.

The pool bind command establishes an alternative mechanism for unlocking a pool. The user may select either the "tang" mechanism, which implements NBDE (Network-bound Disc Encryption) by means of a Tang server, or the "tpm2" mechanism, which uses TPM 2.0 (Trusted Platform Module) encryption. Binding the devices in a pool to a supplementary Clevis encryption policy does not remove the primary encryption mechanism, which uses a key in the kernel keyring.

The pool unbind command simply unbinds a previously added encryption policy from all the devices in the specified pool.

In the pool unlock command it is now necessary to specify the mechanism. Use clevis to make use of the Clevis unlocking policy previously specified for the devices in the pool. Use keyring, to make use of the mechanism that uses a key in the kernel keyring, which was introduced in Stratis 2.1.0. Note that the pool unlock command unlocks all currently locked pools.

This version also includes changes that were in Stratis 2.2.0 (see: https://fedoraproject.org/wiki/Changes/Stratis_2.2.0)

• Major changes in 2.2.0:
  • Stratis filesystem symlinks are now in /dev/stratis
  • Extends the D-Bus interface in a few ways
  • Allows the user to specify their preferred log level
  • Also includes a number of minor bug fixes

Detailed Description

stratisd 2.3.0

This release introduces two D-Bus interface revisions, which differ in the following way from the previous revisions.

org.storage.stratis2.Manager.r3 modifies the UnlockPool method to take an additional parameter, unlock_method, which may be keyring or clevis.

org.storage.stratis2.pool.r3 adds two new method: Bind and Unbind. The Bind method takes two arguments, pin and json. The pin argument designates the Clevis pin as a string, and the json argument encodes a Clevis configuration appropriate to the designated pin. The configuration is a JSON object. Besides Clevis information, it may include Stratis-specific keys that encode configuration decisions that Stratis may implement. At present there is just one such key: stratis:tang:trust_url. The Unbind method reverses a Bind action.

Remarks

The Bind method may be called with any Clevis pin and configuration; we expect that any valid Clevis pin and configuration can be used to bind the devices in a pool. However the Stratis project officially supports only the "tang" and "tpm2" pins as those are the pins that may be designated via stratis. Support for additional Clevis policies may be introduced into stratis in later releases.

When binding a supplementary encryption policy to the devices in a pool using Clevis, the primary key, which is the key in the kernel keyring which was originally used to encrypt each device, must be supplied. stratisd obtains the appropriate key from the kernel keyring in order to provide it to the Clevis binding mechanism. The correct key must be present in the keyring for the bind operation to succeed. It is not necessary for the user to specify the key, stratisd obtains the necessary information from the LUKS2 metadata on the devices in the pool.

In general, it is unwise to write a key consisting of arbitrary binary data to a keyfile. An accidental newline character in the data may cause the contents of the file to be truncated at the newline when read in one context while all the data may be read from the file in some other context.

We are not aware that such a mistake would result in any error in Stratis's operation when Stratis is used in the way that we recommend. We explicitly acknowledge that it might be possible, through some direct interaction with the stratisd D-Bus API, or by, e.g., setting a key in the kernel keyring without using stratis, to manufacture a situation where stratisd could not bind the devices in a pool, even when the correct key is set in the kernel keyring. We would not treat such a situation as evidence of a bug in Stratis.

Benefits to Fedora

Users of Fedora will now benefit from Stratis 2.3.0 by:

• Multiple methods of unlocking Stratis pools using
  • Kernel keyring
  • Tang server
  • TPM2 Device

Carried over from 2.2.0:

• Devices being located in an existing and known top level directory.
• Applications that are restricted from using non-default top level directories can now use Stratis symlinks
• Better integration with udev

Scope

• Proposal owners:
  • 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

There is no know impact when upgrading from Stratis 2.2.0 to 2.3.0

How To Test

• Bind using Tang server

 echo "secret" > /tmp/testkey
 stratis key set --keyfile-path /tmp/testkey testkey
 stratis pool create --key-desc testkey testpool /dev/vdb
 stratis pool bind tang --trust-url testpool testkey tang.yourdomain.org

• Bind using TPM2

 echo "secret" > /tmp/testkey
 stratis key set --keyfile-path /tmp/testkey testkey
 stratis pool create --key-desc testkey testpool /dev/vdb
 stratis pool bind tpm2 testpool testkey 

• Unlock encrypted pool using Clevis (after reboot)

 stratis pool unlock clevis
 stratis pool list

• Testing new filesystem paths can be done using the CLI provided by stratis-cli package or D-Bus API provided by stratisd package.
• Create a pool and filesystem using stratis command

 stratis pool create p1 /dev/sdb
 stratis fs create p1 fs1

• Check that the new path is in /dev/stratis/<pool name>/<filesystem name>

 ls /dev/stratis/<pool name>
 stratis fs list

User Experience

Users with existing Stratis filesystems will notice a change in the filesystem path from /stratis/<pool name>/<filesystem name> to /dev/stratis/<pool name>/<filesystem name>. Appropriate action will need to be taken to update system configurations that make use of the older filesystem paths.

Dependencies

Two new dependencies have been added for clevis and clevis-luks

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/

Release Notes

Includes recent version of Stratis