OpenSDV
/
original_kernel
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fscrypt: write CBC-CTS instead of CTS-CBC 

Calling CBC with ciphertext stealing "CBC-CTS" seems to be more common
than calling it "CTS-CBC".  E.g., CBC-CTS is used by OpenSSL, Crypto++,
RFC3962, and RFC6803.  The NIST SP800-38A addendum uses CBC-CS1,
CBC-CS2, and CBC-CS3, distinguishing between different CTS conventions
but similarly putting the CBC part first.  In the interest of avoiding
any idiosyncratic terminology, update the fscrypt documentation and the
fscrypt_mode "friendly names" to align with the more common convention.

Changing the "friendly names" only affects some log messages.  The
actual mode constants in the API are unchanged; those call it simply
"CTS".  Add a note to the documentation that clarifies that "CBC" and
"CTS" in the API really mean CBC-ESSIV and CBC-CTS, respectively.

Link: https://lore.kernel.org/r/20240224053550.44659-1-ebiggers@kernel.org
Signed-off-by: Eric Biggers <ebiggers@google.com>
This commit is contained in:
Eric Biggers 2024-02-23 21:35:49 -08:00
parent d3a7bd4200
commit 2f944c66ae
2 changed files with 18 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Documentation/filesystems/fscrypt.rst
View File

@ -338,11 +338,14 @@ Supported modes
Currently, the following pairs of encryption modes are supported: Currently, the following pairs of encryption modes are supported:
- AES-256-XTS for contents and AES-256-CTS-CBC for filenames - AES-256-XTS for contents and AES-256-CBC-CTS for filenames
- AES-256-XTS for contents and AES-256-HCTR2 for filenames - AES-256-XTS for contents and AES-256-HCTR2 for filenames
- Adiantum for both contents and filenames - Adiantum for both contents and filenames
- AES-128-CBC-ESSIV for contents and AES-128-CTS-CBC for filenames - AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames
- SM4-XTS for contents and SM4-CTS-CBC for filenames - SM4-XTS for contents and SM4-CBC-CTS for filenames
Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
Authenticated encryption modes are not currently supported because of Authenticated encryption modes are not currently supported because of
the difficulty of dealing with ciphertext expansion. Therefore, the difficulty of dealing with ciphertext expansion. Therefore,
@ -351,11 +354,11 @@ contents encryption uses a block cipher in `XTS mode
`CBC-ESSIV mode `CBC-ESSIV mode
<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_, <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_,
or a wide-block cipher. Filenames encryption uses a or a wide-block cipher. Filenames encryption uses a
block cipher in `CTS-CBC mode block cipher in `CBC-CTS mode
<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
cipher. cipher.
The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default. The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
It is also the only option that is *guaranteed* to always be supported It is also the only option that is *guaranteed* to always be supported
if the kernel supports fscrypt at all; see `Kernel config options`_. if the kernel supports fscrypt at all; see `Kernel config options`_.
@ -364,7 +367,7 @@ upgrades the filenames encryption to use a wide-block cipher. (A
*wide-block cipher*, also called a tweakable super-pseudorandom *wide-block cipher*, also called a tweakable super-pseudorandom
permutation, has the property that changing one bit scrambles the permutation, has the property that changing one bit scrambles the
entire result.) As described in `Filenames encryption`_, a wide-block entire result.) As described in `Filenames encryption`_, a wide-block
cipher is the ideal mode for the problem domain, though CTS-CBC is the cipher is the ideal mode for the problem domain, though CBC-CTS is the
"least bad" choice among the alternatives. For more information about "least bad" choice among the alternatives. For more information about
HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_. HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_.
@ -375,13 +378,13 @@ the work is done by XChaCha12, which is much faster than AES when AES
acceleration is unavailable. For more information about Adiantum, see acceleration is unavailable. For more information about Adiantum, see
`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_. `the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_.
The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support
systems whose only form of AES acceleration is an off-CPU crypto systems whose only form of AES acceleration is an off-CPU crypto
accelerator such as CAAM or CESA that does not support XTS. accelerator such as CAAM or CESA that does not support XTS.
The remaining mode pairs are the "national pride ciphers": The remaining mode pairs are the "national pride ciphers":
- (SM4-XTS, SM4-CTS-CBC) - (SM4-XTS, SM4-CBC-CTS)
Generally speaking, these ciphers aren't "bad" per se, but they Generally speaking, these ciphers aren't "bad" per se, but they
receive limited security review compared to the usual choices such as receive limited security review compared to the usual choices such as
@ -393,7 +396,7 @@ Kernel config options
Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in
only the basic support from the crypto API needed to use AES-256-XTS 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 and AES-256-CBC-CTS encryption. For optimal performance, it is
strongly recommended to also enable any available platform-specific strongly recommended to also enable any available platform-specific
kconfig options that provide acceleration for the algorithm(s) you kconfig options that provide acceleration for the algorithm(s) you
wish to use. Support for any "non-default" encryption modes typically wish to use. Support for any "non-default" encryption modes typically
@ -407,7 +410,7 @@ kernel crypto API (see `Inline encryption support`_); in that case,
the file contents mode doesn't need to supported in the kernel crypto the file contents mode doesn't need to supported in the kernel crypto
API, but the filenames mode still does. API, but the filenames mode still does.
- AES-256-XTS and AES-256-CTS-CBC - AES-256-XTS and AES-256-CBC-CTS
- Recommended: - Recommended:
- arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
- x86: CONFIG_CRYPTO_AES_NI_INTEL - x86: CONFIG_CRYPTO_AES_NI_INTEL
@ -433,7 +436,7 @@ API, but the filenames mode still does.
- x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
- x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
- AES-128-CBC-ESSIV and AES-128-CTS-CBC: - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
- Mandatory: - Mandatory:
- CONFIG_CRYPTO_ESSIV - CONFIG_CRYPTO_ESSIV
- CONFIG_CRYPTO_SHA256 or another SHA-256 implementation - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
@ -521,7 +524,7 @@ alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
Thus, IV reuse is limited to within a single directory. Thus, IV reuse is limited to within a single directory.
With CTS-CBC, the IV reuse means that when the plaintext filenames share a With CBC-CTS, the IV reuse means that when the plaintext filenames share a
common prefix at least as long as the cipher block size (16 bytes for AES), the common prefix at least as long as the cipher block size (16 bytes for AES), the
corresponding encrypted filenames will also share a common prefix. This is corresponding encrypted filenames will also share a common prefix. This is
undesirable. Adiantum and HCTR2 do not have this weakness, as they are undesirable. Adiantum and HCTR2 do not have this weakness, as they are

6
fs/crypto/keysetup.c
View File

@ -23,7 +23,7 @@ struct fscrypt_mode fscrypt_modes[] = {
.blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_256_XTS, .blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_256_XTS,
}, },
[FSCRYPT_MODE_AES_256_CTS] = { [FSCRYPT_MODE_AES_256_CTS] = {
.friendly_name = "AES-256-CTS-CBC", .friendly_name = "AES-256-CBC-CTS",
.cipher_str = "cts(cbc(aes))", .cipher_str = "cts(cbc(aes))",
.keysize = 32, .keysize = 32,
.security_strength = 32, .security_strength = 32,
@ -38,7 +38,7 @@ struct fscrypt_mode fscrypt_modes[] = {
.blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_128_CBC_ESSIV, .blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_128_CBC_ESSIV,
}, },
[FSCRYPT_MODE_AES_128_CTS] = { [FSCRYPT_MODE_AES_128_CTS] = {
.friendly_name = "AES-128-CTS-CBC", .friendly_name = "AES-128-CBC-CTS",
.cipher_str = "cts(cbc(aes))", .cipher_str = "cts(cbc(aes))",
.keysize = 16, .keysize = 16,
.security_strength = 16, .security_strength = 16,
@ -53,7 +53,7 @@ struct fscrypt_mode fscrypt_modes[] = {
.blk_crypto_mode = BLK_ENCRYPTION_MODE_SM4_XTS, .blk_crypto_mode = BLK_ENCRYPTION_MODE_SM4_XTS,
}, },
[FSCRYPT_MODE_SM4_CTS] = { [FSCRYPT_MODE_SM4_CTS] = {
.friendly_name = "SM4-CTS-CBC", .friendly_name = "SM4-CBC-CTS",
.cipher_str = "cts(cbc(sm4))", .cipher_str = "cts(cbc(sm4))",
.keysize = 16, .keysize = 16,
.security_strength = 16, .security_strength = 16,