History

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

Pull fscrypt updates from Eric Biggers: "Some cleanups for fs/crypto/: - Allow 256-bit master keys with AES-256-XTS - Improve documentation and comments - Remove unneeded field fscrypt_operations::max_namelen" * tag 'fscrypt-for-linus' of git://git.kernel.org/pub/scm/fs/fscrypt/fscrypt: fscrypt: improve a few comments fscrypt: allow 256-bit master keys with AES-256-XTS fscrypt: improve documentation for inline encryption fscrypt: clean up comments in bio.c fscrypt: remove fscrypt_operations::max_namelen

Linus Torvalds committed 5 years ago

Commit cd3e8ea2 parents 1990116 b7e072f11 files · +150 −65Browse files

Unified · Split

11 files
  1. Documentation/block/inline-encryption.rst +2 −0
  2. Documentation/filesystems/fscrypt.rst +61 −22
  3. fs/crypto/bio.c +17 −15
  4. fs/crypto/fname.c +1 −2
  5. fs/crypto/fscrypt_private.h +13 −3
  6. fs/crypto/hkdf.c +8 −3
  7. fs/crypto/keysetup.c +48 −14
  8. fs/ext4/super.c +0 −1
  9. fs/f2fs/super.c +0 −1
  10. fs/ubifs/crypto.c +0 −1
  11. include/linux/fscrypt.h +0 −3
Documentation/block/inline-encryption.rst+2−0
@@ -1,5 +1,7 @@
11 .. SPDX-License-Identifier: GPL-2.0
22
3+.. _inline_encryption:
4+
35 =================
46 Inline Encryption
57 =================
Documentation/filesystems/fscrypt.rst+61−22
@@ -77,11 +77,11 @@ Side-channel attacks · 76 unmodified lines
7777
7878 fscrypt is only resistant to side-channel attacks, such as timing or
7979 electromagnetic attacks, to the extent that the underlying Linux
80−Cryptographic API algorithms are. If a vulnerable algorithm is used,
81−such as a table-based implementation of AES, it may be possible for an
82−attacker to mount a side channel attack against the online system.
83−Side channel attacks may also be mounted against applications
84−consuming decrypted data.
80+Cryptographic API algorithms or inline encryption hardware are. If a
81+vulnerable algorithm is used, such as a table-based implementation of
82+AES, it may be possible for an attacker to mount a side channel attack
83+against the online system. Side channel attacks may also be mounted
84+against applications consuming decrypted data.
8585
8686 Unauthorized file access
8787 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -176,11 +176,11 @@ Master Keys · 88 unmodified lines
176176
177177 Each encrypted directory tree is protected by a *master key*. Master
178178 keys can be up to 64 bytes long, and must be at least as long as the
179−greater of the key length needed by the contents and filenames
180−encryption modes being used. For example, if AES-256-XTS is used for
181−contents encryption, the master key must be 64 bytes (512 bits). Note
182−that the XTS mode is defined to require a key twice as long as that
183−required by the underlying block cipher.
179+greater of the security strength of the contents and filenames
180+encryption modes being used. For example, if any AES-256 mode is
181+used, the master key must be at least 256 bits, i.e. 32 bytes. A
182+stricter requirement applies if the key is used by a v1 encryption
183+policy and AES-256-XTS is used; such keys must be 64 bytes.
184184
185185 To "unlock" an encrypted directory tree, userspace must provide the
186186 appropriate master key. There can be any number of master keys, each
@@ -1135,6 +1135,50 @@ where applications may later write sensitive data. It is recommended · 948 unmodified lines
11351135 that systems implementing a form of "verified boot" take advantage of
11361136 this by validating all top-level encryption policies prior to access.
11371137
1138+Inline encryption support
1139+=========================
1140+
1141+By default, fscrypt uses the kernel crypto API for all cryptographic
1142+operations (other than HKDF, which fscrypt partially implements
1143+itself). The kernel crypto API supports hardware crypto accelerators,
1144+but only ones that work in the traditional way where all inputs and
1145+outputs (e.g. plaintexts and ciphertexts) are in memory. fscrypt can
1146+take advantage of such hardware, but the traditional acceleration
1147+model isn't particularly efficient and fscrypt hasn't been optimized
1148+for it.
1149+
1150+Instead, many newer systems (especially mobile SoCs) have *inline
1151+encryption hardware* that can encrypt/decrypt data while it is on its
1152+way to/from the storage device. Linux supports inline encryption
1153+through a set of extensions to the block layer called *blk-crypto*.
1154+blk-crypto allows filesystems to attach encryption contexts to bios
1155+(I/O requests) to specify how the data will be encrypted or decrypted
1156+in-line. For more information about blk-crypto, see
1157+:ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1158+
1159+On supported filesystems (currently ext4 and f2fs), fscrypt can use
1160+blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1161+contents. To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in
1162+the kernel configuration, and specify the "inlinecrypt" mount option
1163+when mounting the filesystem.
1164+
1165+Note that the "inlinecrypt" mount option just specifies to use inline
1166+encryption when possible; it doesn't force its use. fscrypt will
1167+still fall back to using the kernel crypto API on files where the
1168+inline encryption hardware doesn't have the needed crypto capabilities
1169+(e.g. support for the needed encryption algorithm and data unit size)
1170+and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1171+to be usable, it must be enabled in the kernel configuration with
1172+CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.)
1173+
1174+Currently fscrypt always uses the filesystem block size (which is
1175+usually 4096 bytes) as the data unit size. Therefore, it can only use
1176+inline encryption hardware that supports that data unit size.
1177+
1178+Inline encryption doesn't affect the ciphertext or other aspects of
1179+the on-disk format, so users may freely switch back and forth between
1180+using "inlinecrypt" and not using "inlinecrypt".
1181+
11381182 Implementation details
11391183 ======================
11401184
@@ -1184,6 +1228,13 @@ keys`_ and `DIRECT_KEY policies`_. · 43 unmodified lines
11841228 Data path changes
11851229 -----------------
11861230
1231+When inline encryption is used, filesystems just need to associate
1232+encryption contexts with bios to specify how the block layer or the
1233+inline encryption hardware will encrypt/decrypt the file contents.
1234+
1235+When inline encryption isn't used, filesystems must encrypt/decrypt
1236+the file contents themselves, as described below:
1237+
11871238 For the read path (->readpage()) of regular files, filesystems can
11881239 read the ciphertext into the page cache and decrypt it in-place. The
11891240 page lock must be held until decryption has finished, to prevent the
@@ -1197,18 +1248,6 @@ buffer. Some filesystems, such as UBIFS, already use temporary · 7 unmodified lines
11971248 buffers regardless of encryption. Other filesystems, such as ext4 and
11981249 F2FS, have to allocate bounce pages specially for encryption.
11991250
1200−Fscrypt is also able to use inline encryption hardware instead of the
1201−kernel crypto API for en/decryption of file contents. When possible,
1202−and if directed to do so (by specifying the 'inlinecrypt' mount option
1203−for an ext4/F2FS filesystem), it adds encryption contexts to bios and
1204−uses blk-crypto to perform the en/decryption instead of making use of
1205−the above read/write path changes. Of course, even if directed to
1206−make use of inline encryption, fscrypt will only be able to do so if
1207−either hardware inline encryption support is available for the
1208−selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK
1209−is selected. If neither is the case, fscrypt will fall back to using
1210−the above mentioned read/write path changes for en/decryption.
1211−
12121251 Filename hashing and encoding
12131252 -----------------------------
12141253
fs/crypto/bio.c+17−15
@@ -1,23 +1,10 @@
11 // SPDX-License-Identifier: GPL-2.0
22 /*
3− * This contains encryption functions for per-file encryption.
3+ * Utility functions for file contents encryption/decryption on
4+ * block device-based filesystems.
45 *
56 * Copyright (C) 2015, Google, Inc.
67 * Copyright (C) 2015, Motorola Mobility
7− *
8− * Written by Michael Halcrow, 2014.
9− *
10− * Filename encryption additions
11− * Uday Savagaonkar, 2014
12− * Encryption policy handling additions
13− * Ildar Muslukhov, 2014
14− * Add fscrypt_pullback_bio_page()
15− * Jaegeuk Kim, 2015.
16− *
17− * This has not yet undergone a rigorous security audit.
18− *
19− * The usage of AES-XTS should conform to recommendations in NIST
20− * Special Publication 800-38E and IEEE P1619/D16.
218 */
229
2310 #include <linux/pagemap.h>
@@ -26,6 +13,21 @@ · 2 unmodified lines
2613 #include <linux/namei.h>
2714 #include "fscrypt_private.h"
2815
16+/**
17+ * fscrypt_decrypt_bio() - decrypt the contents of a bio
18+ * @bio: the bio to decrypt
19+ *
20+ * Decrypt the contents of a "read" bio following successful completion of the
21+ * underlying disk read. The bio must be reading a whole number of blocks of an
22+ * encrypted file directly into the page cache. If the bio is reading the
23+ * ciphertext into bounce pages instead of the page cache (for example, because
24+ * the file is also compressed, so decompression is required after decryption),
25+ * then this function isn't applicable. This function may sleep, so it must be
26+ * called from a workqueue rather than from the bio's bi_end_io callback.
27+ *
28+ * This function sets PG_error on any pages that contain any blocks that failed
29+ * to be decrypted. The filesystem must not mark such pages uptodate.
30+ */
2931 void fscrypt_decrypt_bio(struct bio *bio)
3032 {
3133 struct bio_vec *bv;
fs/crypto/fname.c+1−2
@@ -429,8 +429,7 @@ int fscrypt_setup_filename(struct inode *dir, const struct qstr *iname, · 428 unmodified lines
429429
430430 if (fscrypt_has_encryption_key(dir)) {
431431 if (!fscrypt_fname_encrypted_size(&dir->i_crypt_info->ci_policy,
432− iname->len,
433− dir->i_sb->s_cop->max_namelen,
432+ iname->len, NAME_MAX,
434433 &fname->crypto_buf.len))
435434 return -ENAMETOOLONG;
436435 fname->crypto_buf.name = kmalloc(fname->crypto_buf.len,
fs/crypto/fscrypt_private.h+13−3
@@ -20,6 +20,11 @@ · 19 unmodified lines
2020
2121 #define FSCRYPT_FILE_NONCE_SIZE 16
2222
23+/*
24+ * Minimum size of an fscrypt master key. Note: a longer key will be required
25+ * if ciphers with a 256-bit security strength are used. This is just the
26+ * absolute minimum, which applies when only 128-bit encryption is used.
27+ */
2328 #define FSCRYPT_MIN_KEY_SIZE 16
2429
2530 #define FSCRYPT_CONTEXT_V1 1
@@ -413,7 +418,11 @@ struct fscrypt_master_key_secret { · 387 unmodified lines
413418 */
414419 struct fscrypt_hkdf hkdf;
415420
416− /* Size of the raw key in bytes. Set even if ->raw isn't set. */
421+ /*
422+ * Size of the raw key in bytes. This remains set even if ->raw was
423+ * zeroized due to no longer being needed. I.e. we still remember the
424+ * size of the key even if we don't need to remember the key itself.
425+ */
417426 u32 size;
418427
419428 /* For v1 policy keys: the raw key. Wiped for v2 policy keys. */
@@ -549,8 +558,9 @@ int __init fscrypt_init_keyring(void); · 129 unmodified lines
549558 struct fscrypt_mode {
550559 const char *friendly_name;
551560 const char *cipher_str;
552− int keysize;
553− int ivsize;
561+ int keysize; /* key size in bytes */
562+ int security_strength; /* security strength in bytes */
563+ int ivsize; /* IV size in bytes */
554564 int logged_impl_name;
555565 enum blk_crypto_mode_num blk_crypto_mode;
556566 };
fs/crypto/hkdf.c+8−3
@@ -16,9 +16,14 @@ · 15 unmodified lines
1616
1717 /*
1818 * HKDF supports any unkeyed cryptographic hash algorithm, but fscrypt uses
19− * SHA-512 because it is reasonably secure and efficient; and since it produces
20− * a 64-byte digest, deriving an AES-256-XTS key preserves all 64 bytes of
21− * entropy from the master key and requires only one iteration of HKDF-Expand.
19+ * SHA-512 because it is well-established, secure, and reasonably efficient.
20+ *
21+ * HKDF-SHA256 was also considered, as its 256-bit security strength would be
22+ * sufficient here. A 512-bit security strength is "nice to have", though.
23+ * Also, on 64-bit CPUs, SHA-512 is usually just as fast as SHA-256. In the
24+ * common case of deriving an AES-256-XTS key (512 bits), that can result in
25+ * HKDF-SHA512 being much faster than HKDF-SHA256, as the longer digest size of
26+ * SHA-512 causes HKDF-Expand to only need to do one iteration rather than two.
2227 */
2328 #define HKDF_HMAC_ALG "hmac(sha512)"
2429 #define HKDF_HASHLEN SHA512_DIGEST_SIZE
fs/crypto/keysetup.c+48−14
@@ -19,6 +19,7 @@ struct fscrypt_mode fscrypt_modes[] = { · 18 unmodified lines
1919 .friendly_name = "AES-256-XTS",
2020 .cipher_str = "xts(aes)",
2121 .keysize = 64,
22+ .security_strength = 32,
2223 .ivsize = 16,
2324 .blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_256_XTS,
2425 },
@@ -26,12 +27,14 @@ struct fscrypt_mode fscrypt_modes[] = { · 1 unmodified line
2627 .friendly_name = "AES-256-CTS-CBC",
2728 .cipher_str = "cts(cbc(aes))",
2829 .keysize = 32,
30+ .security_strength = 32,
2931 .ivsize = 16,
3032 },
3133 [FSCRYPT_MODE_AES_128_CBC] = {
3234 .friendly_name = "AES-128-CBC-ESSIV",
3335 .cipher_str = "essiv(cbc(aes),sha256)",
3436 .keysize = 16,
37+ .security_strength = 16,
3538 .ivsize = 16,
3639 .blk_crypto_mode = BLK_ENCRYPTION_MODE_AES_128_CBC_ESSIV,
3740 },
@@ -39,12 +42,14 @@ struct fscrypt_mode fscrypt_modes[] = { · 1 unmodified line
3942 .friendly_name = "AES-128-CTS-CBC",
4043 .cipher_str = "cts(cbc(aes))",
4144 .keysize = 16,
45+ .security_strength = 16,
4246 .ivsize = 16,
4347 },
4448 [FSCRYPT_MODE_ADIANTUM] = {
4549 .friendly_name = "Adiantum",
4650 .cipher_str = "adiantum(xchacha12,aes)",
4751 .keysize = 32,
52+ .security_strength = 32,
4853 .ivsize = 32,
4954 .blk_crypto_mode = BLK_ENCRYPTION_MODE_ADIANTUM,
5055 },
@@ -117,8 +122,9 @@ err_free_tfm: · 66 unmodified lines
117122
118123 /*
119124 * Prepare the crypto transform object or blk-crypto key in @prep_key, given the
120− * raw key, encryption mode, and flag indicating which encryption implementation
121− * (fs-layer or blk-crypto) will be used.
125+ * raw key, encryption mode (@ci->ci_mode), flag indicating which encryption
126+ * implementation (fs-layer or blk-crypto) will be used (@ci->ci_inlinecrypt),
127+ * and IV generation method (@ci->ci_policy.flags).
122128 */
123129 int fscrypt_prepare_key(struct fscrypt_prepared_key *prep_key,
124130 const u8 *raw_key, const struct fscrypt_info *ci)
@@ -357,6 +363,45 @@ static int fscrypt_setup_v2_file_key(struct fscrypt_info *ci, · 232 unmodified lines
357363 return 0;
358364 }
359365
366+/*
367+ * Check whether the size of the given master key (@mk) is appropriate for the
368+ * encryption settings which a particular file will use (@ci).
369+ *
370+ * If the file uses a v1 encryption policy, then the master key must be at least
371+ * as long as the derived key, as this is a requirement of the v1 KDF.
372+ *
373+ * Otherwise, the KDF can accept any size key, so we enforce a slightly looser
374+ * requirement: we require that the size of the master key be at least the
375+ * maximum security strength of any algorithm whose key will be derived from it
376+ * (but in practice we only need to consider @ci->ci_mode, since any other
377+ * possible subkeys such as DIRHASH and INODE_HASH will never increase the
378+ * required key size over @ci->ci_mode). This allows AES-256-XTS keys to be
379+ * derived from a 256-bit master key, which is cryptographically sufficient,
380+ * rather than requiring a 512-bit master key which is unnecessarily long. (We
381+ * still allow 512-bit master keys if the user chooses to use them, though.)
382+ */
383+static bool fscrypt_valid_master_key_size(const struct fscrypt_master_key *mk,
384+ const struct fscrypt_info *ci)
385+{
386+ unsigned int min_keysize;
387+
388+ if (ci->ci_policy.version == FSCRYPT_POLICY_V1)
389+ min_keysize = ci->ci_mode->keysize;
390+ else
391+ min_keysize = ci->ci_mode->security_strength;
392+
393+ if (mk->mk_secret.size < min_keysize) {
394+ fscrypt_warn(NULL,
395+ "key with %s %*phN is too short (got %u bytes, need %u+ bytes)",
396+ master_key_spec_type(&mk->mk_spec),
397+ master_key_spec_len(&mk->mk_spec),
398+ (u8 *)&mk->mk_spec.u,
399+ mk->mk_secret.size, min_keysize);
400+ return false;
401+ }
402+ return true;
403+}
404+
360405 /*
361406 * Find the master key, then set up the inode's actual encryption key.
362407 *
@@ -422,18 +467,7 @@ static int setup_file_encryption_key(struct fscrypt_info *ci, · 59 unmodified lines
422467 goto out_release_key;
423468 }
424469
425− /*
426− * Require that the master key be at least as long as the derived key.
427− * Otherwise, the derived key cannot possibly contain as much entropy as
428− * that required by the encryption mode it will be used for. For v1
429− * policies it's also required for the KDF to work at all.
430− */
431− if (mk->mk_secret.size < ci->ci_mode->keysize) {
432− fscrypt_warn(NULL,
433− "key with %s %*phN is too short (got %u bytes, need %u+ bytes)",
434− master_key_spec_type(&mk_spec),
435− master_key_spec_len(&mk_spec), (u8 *)&mk_spec.u,
436− mk->mk_secret.size, ci->ci_mode->keysize);
470+ if (!fscrypt_valid_master_key_size(mk, ci)) {
437471 err = -ENOKEY;
438472 goto out_release_key;
439473 }
fs/ext4/super.c+0−1
@@ -1572,7 +1572,6 @@ static const struct fscrypt_operations ext4_cryptops = { · 1571 unmodified lines
15721572 .set_context = ext4_set_context,
15731573 .get_dummy_policy = ext4_get_dummy_policy,
15741574 .empty_dir = ext4_empty_dir,
1575− .max_namelen = EXT4_NAME_LEN,
15761575 .has_stable_inodes = ext4_has_stable_inodes,
15771576 .get_ino_and_lblk_bits = ext4_get_ino_and_lblk_bits,
15781577 };
fs/f2fs/super.c+0−1
@@ -2976,7 +2976,6 @@ static const struct fscrypt_operations f2fs_cryptops = { · 2975 unmodified lines
29762976 .set_context = f2fs_set_context,
29772977 .get_dummy_policy = f2fs_get_dummy_policy,
29782978 .empty_dir = f2fs_empty_dir,
2979− .max_namelen = F2FS_NAME_LEN,
29802979 .has_stable_inodes = f2fs_has_stable_inodes,
29812980 .get_ino_and_lblk_bits = f2fs_get_ino_and_lblk_bits,
29822981 .get_num_devices = f2fs_get_num_devices,
fs/ubifs/crypto.c+0−1
@@ -82,5 +82,4 @@ const struct fscrypt_operations ubifs_crypt_operations = { · 81 unmodified lines
8282 .get_context = ubifs_crypt_get_context,
8383 .set_context = ubifs_crypt_set_context,
8484 .empty_dir = ubifs_crypt_empty_dir,
85− .max_namelen = UBIFS_MAX_NLEN,
8685 };
include/linux/fscrypt.h+0−3
@@ -118,9 +118,6 @@ struct fscrypt_operations { · 117 unmodified lines
118118 */
119119 bool (*empty_dir)(struct inode *inode);
120120
121− /* The filesystem's maximum ciphertext filename length, in bytes */
122− unsigned int max_namelen;
123−
124121 /*
125122 * Check whether the filesystem's inode numbers and UUID are stable,
126123 * meaning that they will never be changed even by offline operations

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t