fscrypt update for 6.6

Just a small documentation improvement.
 -----BEGIN PGP SIGNATURE-----
 
 iIoEABYIADIWIQSacvsUNc7UX4ntmEPzXCl4vpKOKwUCZOwUaRQcZWJpZ2dlcnNA
 Z29vZ2xlLmNvbQAKCRDzXCl4vpKOKyGLAQC3nfSZ/sNNyUwPV46yBWzIDTuKXuCD
 iyd6L1N99pwMiwD5AT0PAylP7xQew7sMBimLvFJLoATP0OPApGR241yH4wo=
 =CYAT
 -----END PGP SIGNATURE-----

Merge tag 'fscrypt-for-linus' of git://git.kernel.org/pub/scm/fs/fscrypt/linux

Pull fscrypt update from Eric Biggers:
 "Just a small documentation improvement"

* tag 'fscrypt-for-linus' of git://git.kernel.org/pub/scm/fs/fscrypt/linux:
  fscrypt: improve the "Encryption modes and usage" section

Documentation/filesystems/fscrypt.rst

@@ -332,54 +332,121 @@ Encryption modes and usage
 fscrypt allows one encryption mode to be specified for file contents
 and one encryption mode to be specified for filenames.  Different
 directory trees are permitted to use different encryption modes.
+
+Supported modes
+---------------
+
 Currently, the following pairs of encryption modes are supported:
 
 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
-- AES-128-CBC for contents and AES-128-CTS-CBC for filenames
+- AES-256-XTS for contents and AES-256-HCTR2 for filenames
 - Adiantum for both contents and filenames
-- AES-256-XTS for contents and AES-256-HCTR2 for filenames (v2 policies only)
+- AES-128-CBC-ESSIV for contents and AES-128-CTS-CBC for filenames
-- SM4-XTS for contents and SM4-CTS-CBC for filenames (v2 policies only)
+- SM4-XTS for contents and SM4-CTS-CBC for filenames
 
-If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
+Authenticated encryption modes are not currently supported because of
+the difficulty of dealing with ciphertext expansion.  Therefore,
+contents encryption uses a block cipher in `XTS mode
+<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or
+`CBC-ESSIV mode
+<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_,
+or a wide-block cipher.  Filenames encryption uses a
+block cipher in `CTS-CBC mode
+<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
+cipher.
 
-AES-128-CBC was added only for low-powered embedded devices with
+The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default.
-crypto accelerators such as CAAM or CESA that do not support XTS.  To
+It is also the only option that is *guaranteed* to always be supported
-use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or
+if the kernel supports fscrypt at all; see `Kernel config options`_.
-another SHA-256 implementation) must be enabled so that ESSIV can be
-used.
 
-Adiantum is a (primarily) stream cipher-based mode that is fast even
+The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
-on CPUs without dedicated crypto instructions.  It's also a true
+upgrades the filenames encryption to use a wide-block cipher.  (A
-wide-block mode, unlike XTS.  It can also eliminate the need to derive
+*wide-block cipher*, also called a tweakable super-pseudorandom
-per-file encryption keys.  However, it depends on the security of two
+permutation, has the property that changing one bit scrambles the
-primitives, XChaCha12 and AES-256, rather than just one.  See the
+entire result.)  As described in `Filenames encryption`_, a wide-block
-paper "Adiantum: length-preserving encryption for entry-level
+cipher is the ideal mode for the problem domain, though CTS-CBC is the
-processors" (https://eprint.iacr.org/2018/720.pdf) for more details.
+"least bad" choice among the alternatives.  For more information about
-To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled.  Also, fast
+HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_.
-implementations of ChaCha and NHPoly1305 should be enabled, e.g.
-CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
 
-AES-256-HCTR2 is another true wide-block encryption mode that is intended for
+Adiantum is recommended on systems where AES is too slow due to lack
-use on CPUs with dedicated crypto instructions.  AES-256-HCTR2 has the property
+of hardware acceleration for AES.  Adiantum is a wide-block cipher
-that a bitflip in the plaintext changes the entire ciphertext.  This property
+that uses XChaCha12 and AES-256 as its underlying components.  Most of
-makes it desirable for filename encryption since initialization vectors are
+the work is done by XChaCha12, which is much faster than AES when AES
-reused within a directory.  For more details on AES-256-HCTR2, see the paper
+acceleration is unavailable.  For more information about Adiantum, see
-"Length-preserving encryption with HCTR2"
+`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_.
-(https://eprint.iacr.org/2021/1441.pdf).  To use AES-256-HCTR2,
-CONFIG_CRYPTO_HCTR2 must be enabled.  Also, fast implementations of XCTR and
-POLYVAL should be enabled, e.g. CRYPTO_POLYVAL_ARM64_CE and
-CRYPTO_AES_ARM64_CE_BLK for ARM64.
 
-SM4 is a Chinese block cipher that is an alternative to AES.  It has
+The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support
-not seen as much security review as AES, and it only has a 128-bit key
+systems whose only form of AES acceleration is an off-CPU crypto
-size.  It may be useful in cases where its use is mandated.
+accelerator such as CAAM or CESA that does not support XTS.
-Otherwise, it should not be used.  For SM4 support to be available, it
-also needs to be enabled in the kernel crypto API.
 
-New encryption modes can be added relatively easily, without changes
+The remaining mode pairs are the "national pride ciphers":
-to individual filesystems.  However, authenticated encryption (AE)
+
-modes are not currently supported because of the difficulty of dealing
+- (SM4-XTS, SM4-CTS-CBC)
-with ciphertext expansion.
+
+Generally speaking, these ciphers aren't "bad" per se, but they
+receive limited security review compared to the usual choices such as
+AES and ChaCha.  They also don't bring much new to the table.  It is
+suggested to only use these ciphers where their use is mandated.
+
+Kernel config options
+---------------------
+
+Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in
+only the basic support from the crypto API needed to use AES-256-XTS
+and AES-256-CTS-CBC encryption.  For optimal performance, it is
+strongly recommended to also enable any available platform-specific
+kconfig options that provide acceleration for the algorithm(s) you
+wish to use.  Support for any "non-default" encryption modes typically
+requires extra kconfig options as well.
+
+Below, some relevant options are listed by encryption mode.  Note,
+acceleration options not listed below may be available for your
+platform; refer to the kconfig menus.  File contents encryption can
+also be configured to use inline encryption hardware instead of the
+kernel crypto API (see `Inline encryption support`_); in that case,
+the file contents mode doesn't need to supported in the kernel crypto
+API, but the filenames mode still does.
+
+- AES-256-XTS and AES-256-CTS-CBC
+    - Recommended:
+        - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
+        - x86: CONFIG_CRYPTO_AES_NI_INTEL
+
+- AES-256-HCTR2
+    - Mandatory:
+        - CONFIG_CRYPTO_HCTR2
+    - Recommended:
+        - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
+        - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
+        - x86: CONFIG_CRYPTO_AES_NI_INTEL
+        - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
+
+- Adiantum
+    - Mandatory:
+        - CONFIG_CRYPTO_ADIANTUM
+    - Recommended:
+        - arm32: CONFIG_CRYPTO_CHACHA20_NEON
+        - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
+        - arm64: CONFIG_CRYPTO_CHACHA20_NEON
+        - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
+        - x86: CONFIG_CRYPTO_CHACHA20_X86_64
+        - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
+        - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
+
+- AES-128-CBC-ESSIV and AES-128-CTS-CBC:
+    - Mandatory:
+        - CONFIG_CRYPTO_ESSIV
+        - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
+    - Recommended:
+        - AES-CBC acceleration
+
+fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
+acceleration is recommended:
+
+- SHA-512
+    - Recommended:
+        - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
+        - x86: CONFIG_CRYPTO_SHA512_SSSE3
 
 Contents encryption
 -------------------
@@ -493,7 +560,14 @@ This structure must be initialized as follows:
   be set to constants from ``<linux/fscrypt.h>`` which identify the
   encryption modes to use.  If unsure, use FSCRYPT_MODE_AES_256_XTS
   (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
-  (4) for ``filenames_encryption_mode``.
+  (4) for ``filenames_encryption_mode``.  For details, see `Encryption
+  modes and usage`_.
+
+  v1 encryption policies only support three combinations of modes:
+  (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS),
+  (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and
+  (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM).  v2 policies support
+  all combinations documented in `Supported modes`_.
 
 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``: