https://fedoraproject.org/wiki/Changes/Stratis_2.3.0
== Summary ==
Stratis 2.3.0 adds additional flexibility to its encryption support via Clevis.
== Owner ==
* Name: [[User:dkeefe|Dennis Keefe]], [[User:mulhern|Anne Mulhern]], [[User:jbaublitz|John Baublitz]]
* Email: dkeefe@xxxxxxxxxx, amulhern@xxxxxxxxxx, jbaublitz@xxxxxxxxxx
Stratis 2.3.0 adds additional flexibility to its encryption support via Clevis.
== Owner ==
* Name: [[User:dkeefe|Dennis Keefe]], [[User:mulhern|Anne Mulhern]], [[User:jbaublitz|John Baublitz]]
* Email: dkeefe@xxxxxxxxxx, amulhern@xxxxxxxxxx, jbaublitz@xxxxxxxxxx
== 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.
== 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.
== Feedback ==
== 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
== 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
== User Experience ==
This latest release add a feature enhancement that will provide users with multiple unlock methods for encrypted Stratis pools
== 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
--
=== 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.
== 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.
== Feedback ==
== 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
== 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
== User Experience ==
This latest release add a feature enhancement that will provide users with multiple unlock methods for encrypted Stratis pools
== 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
Ben Cotton
He / Him / His
Senior Program Manager, Fedora & CentOS Stream
Red Hat
TZ=America/Indiana/Indianapolis
He / Him / His
Senior Program Manager, Fedora & CentOS Stream
Red Hat
TZ=America/Indiana/Indianapolis
_______________________________________________ devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/devel@xxxxxxxxxxxxxxxxxxxxxxx
