kernel.git/Documentation/filesystems/fscrypt.rst, branch linux-6.4.y

fscrypt: support decrypting data from large folios

2023-01-28T23:10:12Z

Try to make the filesystem-level decryption functions in fs/crypto/ aware of large folios. This includes making fscrypt_decrypt_bio() support the case where the bio contains large folios, and making fscrypt_decrypt_pagecache_blocks() take a folio instead of a page. There's no way to actually test this with large folios yet, but I've tested that this doesn't cause any regressions. Note that this patch just handles *decryption*, not encryption which will be a little more difficult. Signed-off-by: Eric Biggers Reviewed-by: Matthew Wilcox (Oracle) Link: https://lore.kernel.org/r/20230127224202.355629-1-ebiggers@kernel.org

fscrypt: add additional documentation for SM4 support

2022-12-02T18:43:00Z

Add a paragraph about SM4, like there is for the other modes. Signed-off-by: Eric Biggers Reviewed-by: Tianjia Zhang Link: https://lore.kernel.org/r/20221201191452.6557-1-ebiggers@kernel.org

fscrypt: Add SM4 XTS/CTS symmetric algorithm support

2022-12-01T19:23:58Z

Add support for XTS and CTS mode variant of SM4 algorithm. The former is used to encrypt file contents, while the latter (SM4-CTS-CBC) is used to encrypt filenames. SM4 is a symmetric algorithm widely used in China, and is even mandatory algorithm in some special scenarios. We need to provide these users with the ability to encrypt files or disks using SM4-XTS. Signed-off-by: Tianjia Zhang Signed-off-by: Eric Biggers Link: https://lore.kernel.org/r/20221201125819.36932-3-tianjia.zhang@linux.alibaba.com

fscrypt: Add HCTR2 support for filename encryption

2022-06-10T08:40:18Z

HCTR2 is a tweakable, length-preserving encryption mode that is intended for use on CPUs with dedicated crypto instructions. HCTR2 has the property that a bitflip in the plaintext changes the entire ciphertext. This property fixes a known weakness with filename encryption: when two filenames in the same directory share a prefix of >= 16 bytes, with AES-CTS-CBC their encrypted filenames share a common substring, leaking information. HCTR2 does not have this problem. More information on HCTR2 can be found here: "Length-preserving encryption with HCTR2": https://eprint.iacr.org/2021/1441.pdf Signed-off-by: Nathan Huckleberry Reviewed-by: Ard Biesheuvel Acked-by: Eric Biggers Signed-off-by: Herbert Xu

fs: Add read_folio documentation

2022-05-09T20:21:44Z

Convert all the ->readpage documentation to ->read_folio. Signed-off-by: Matthew Wilcox (Oracle)

fscrypt: update documentation for direct I/O support

2022-02-08T19:02:18Z

Now that direct I/O is supported on encrypted files in some cases, document what these cases are. Link: https://lore.kernel.org/r/20220128233940.79464-6-ebiggers@kernel.org Reviewed-by: Christoph Hellwig Signed-off-by: Eric Biggers

fscrypt: allow 256-bit master keys with AES-256-XTS

2021-09-22T18:29:38Z

fscrypt currently requires a 512-bit master key when AES-256-XTS is used, since AES-256-XTS keys are 512-bit and fscrypt requires that the master key be at least as long any key that will be derived from it. However, this is overly strict because AES-256-XTS doesn't actually have a 512-bit security strength, but rather 256-bit. The fact that XTS takes twice the expected key size is a quirk of the XTS mode. It is sufficient to use 256 bits of entropy for AES-256-XTS, provided that it is first properly expanded into a 512-bit key, which HKDF-SHA512 does. Therefore, relax the check of the master key size to use the security strength of the derived key rather than the size of the derived key (except for v1 encryption policies, which don't use HKDF). Besides making things more flexible for userspace, this is needed in order for the use of a KDF which only takes a 256-bit key to be introduced into the fscrypt key hierarchy. This will happen with hardware-wrapped keys support, as all known hardware which supports that feature uses an SP800-108 KDF using AES-256-CMAC, so the wrapped keys are wrapped 256-bit AES keys. Moreover, there is interest in fscrypt supporting the same type of AES-256-CMAC based KDF in software as an alternative to HKDF-SHA512. There is no security problem with such features, so fix the key length check to work properly with them. Reviewed-by: Paul Crowley Link: https://lore.kernel.org/r/20210921030303.5598-1-ebiggers@kernel.org Signed-off-by: Eric Biggers

fscrypt: improve documentation for inline encryption

2021-09-21T02:32:34Z

Currently the fscrypt inline encryption support is documented in the "Implementation details" section, and it doesn't go into much detail. It's really more than just an "implementation detail" though, as there is a user-facing mount option. Also, hardware-wrapped key support (an upcoming feature) will depend on inline encryption and will affect the on-disk format; by definition that's not just an implementation detail. Therefore, move this documentation into its own section and expand it. Link: https://lore.kernel.org/r/20210916174928.65529-4-ebiggers@kernel.org Signed-off-by: Eric Biggers

fscrypt: align Base64 encoding with RFC 4648 base64url

2021-07-26T03:47:05Z

fscrypt uses a Base64 encoding to encode no-key filenames (the filenames that are presented to userspace when a directory is listed without its encryption key). There are many variants of Base64, but the most common ones are specified by RFC 4648. fscrypt can't use the regular RFC 4648 "base64" variant because "base64" uses the '/' character, which isn't allowed in filenames. However, RFC 4648 also specifies a "base64url" variant for use in URLs and filenames. "base64url" is less common than "base64", but it's still implemented in many programming libraries. Unfortunately, what fscrypt actually uses is a custom Base64 variant that differs from "base64url" in several ways: - The binary data is divided into 6-bit chunks differently. - Values 62 and 63 are encoded with '+' and ',' instead of '-' and '_'. - '='-padding isn't used. This isn't a problem per se, as the padding isn't technically necessary, and RFC 4648 doesn't strictly require it. But it needs to be properly documented. There have been two attempts to copy the fscrypt Base64 code into lib/ (https://lkml.kernel.org/r/20200821182813.52570-6-jlayton@kernel.org and https://lkml.kernel.org/r/20210716110428.9727-5-hare@suse.de), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late. Therefore, switch the fscrypt Base64 variant to base64url, in order to align more closely with RFC 4648 and other implementations and uses of Base64. However, I opted not to implement '='-padding, as '='-padding adds complexity, is unnecessary, and isn't required by the RFC. Link: https://lore.kernel.org/r/20210718000125.59701-1-ebiggers@kernel.org Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers

fscrypt: remove mention of symlink st_size quirk from documentation

2021-07-26T03:01:07Z

Now that the correct st_size is reported for encrypted symlinks on all filesystems, update the documentation accordingly. Link: https://lore.kernel.org/r/20210702065350.209646-6-ebiggers@kernel.org Signed-off-by: Eric Biggers