Documentation/block/inline-encryption.rst

Source file repositories/reference/linux-study-clean/Documentation/block/inline-encryption.rst

File Facts

System
Linux kernel
Corpus path
Documentation/block/inline-encryption.rst
Extension
.rst
Size
31214 bytes
Lines
557
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

.. _inline_encryption:

=================
Inline Encryption
=================

Background
==========

Inline encryption hardware sits logically between memory and disk, and can
en/decrypt data as it goes in/out of the disk.  For each I/O request, software
can control exactly how the inline encryption hardware will en/decrypt the data
in terms of key, algorithm, data unit size (the granularity of en/decryption),
and data unit number (a value that determines the initialization vector(s)).

Some inline encryption hardware accepts all encryption parameters including raw
keys directly in low-level I/O requests.  However, most inline encryption
hardware instead has a fixed number of "keyslots" and requires that the key,
algorithm, and data unit size first be programmed into a keyslot.  Each
low-level I/O request then just contains a keyslot index and data unit number.

Note that inline encryption hardware is very different from traditional crypto
accelerators, which are supported through the kernel crypto API.  Traditional
crypto accelerators operate on memory regions, whereas inline encryption
hardware operates on I/O requests.  Thus, inline encryption hardware needs to be
managed by the block layer, not the kernel crypto API.

Inline encryption hardware is also very different from "self-encrypting drives",
such as those based on the TCG Opal or ATA Security standards.  Self-encrypting
drives don't provide fine-grained control of encryption and provide no way to
verify the correctness of the resulting ciphertext.  Inline encryption hardware
provides fine-grained control of encryption, including the choice of key and
initialization vector for each sector, and can be tested for correctness.

Objective
=========

We want to support inline encryption in the kernel.  To make testing easier, we
also want support for falling back to the kernel crypto API when actual inline
encryption hardware is absent.  We also want inline encryption to work with
layered devices like device-mapper and loopback (i.e. we want to be able to use
the inline encryption hardware of the underlying devices if present, or else
fall back to crypto API en/decryption).

Constraints and notes
=====================

- We need a way for upper layers (e.g. filesystems) to specify an encryption
  context to use for en/decrypting a bio, and device drivers (e.g. UFSHCD) need
  to be able to use that encryption context when they process the request.
  Encryption contexts also introduce constraints on bio merging; the block layer
  needs to be aware of these constraints.

- Different inline encryption hardware has different supported algorithms,
  supported data unit sizes, maximum data unit numbers, etc.  We call these
  properties the "crypto capabilities".  We need a way for device drivers to
  advertise crypto capabilities to upper layers in a generic way.

- Inline encryption hardware usually (but not always) requires that keys be
  programmed into keyslots before being used.  Since programming keyslots may be
  slow and there may not be very many keyslots, we shouldn't just program the
  key for every I/O request, but rather keep track of which keys are in the
  keyslots and reuse an already-programmed keyslot when possible.

- Upper layers typically define a specific end-of-life for crypto keys, e.g.
  when an encrypted directory is locked or when a crypto mapping is torn down.
  At these times, keys are wiped from memory.  We must provide a way for upper
  layers to also evict keys from any keyslots they are present in.

Annotation

Implementation Notes