On Wed, Dec 18, 2019 at 06:51:30AM -0800, Satya Tangirala wrote: > diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst > new file mode 100644 > index 000000000000..330106b23c09 > --- /dev/null > +++ b/Documentation/block/inline-encryption.rst > @@ -0,0 +1,183 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +================= > +Inline Encryption > +================= > + > +Objective > +========= > + > +We want to support inline encryption (IE) in the kernel. > +To allow for testing, we also want a crypto API fallback when actual > +IE hardware is absent. We also want IE to work with layered devices > +like dm and loopback (i.e. we want to be able to use the IE hardware > +of the underlying devices if present, or else fall back to crypto API > +en/decryption). > + > + > +Constraints and notes > +===================== > + > +- IE hardware have a limited number of "keyslots" that can be programmed > + with an encryption context (key, algorithm, data unit size, etc.) at any time. > + One can specify a keyslot in a data request made to the device, and the > + device will en/decrypt the data using the encryption context programmed into > + that specified keyslot. When possible, we want to make multiple requests with > + the same encryption context share the same keyslot. > + > +- We need a way for filesystems to specify an encryption context to use for > + en/decrypting a struct bio, and a device driver (like UFS) needs to be able > + to use that encryption context when it processes the bio. > + > +- We need a way for device drivers to expose their capabilities in a unified > + way to the upper layers. > + Can you add an explicit explanation about how inline encryption is different from "self-encrypting drives", like ones based on the TCG Opal or ATA Security standards? That seems to be a common point of confusion. Also, this documentation file really ought to start by briefly explaining what inline encryption is and why it's important. Then only after that get into the implementation. Don't assume the reader has already read a bunch of commit messages, cover letters, articles, code, etc. - Eric
