1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * fscrypt_private.h
4 *
5 * Copyright (C) 2015, Google, Inc.
6 *
7 * Originally written by Michael Halcrow, Ildar Muslukhov, and Uday Savagaonkar.
8 * Heavily modified since then.
9 */
10
11 #ifndef _FSCRYPT_PRIVATE_H
12 #define _FSCRYPT_PRIVATE_H
13
14 #include <linux/fscrypt.h>
15 #include <crypto/hash.h>
16 #include <linux/bio-crypt-ctx.h>
17
18 #define CONST_STRLEN(str) (sizeof(str) - 1)
19
20 #define FS_KEY_DERIVATION_NONCE_SIZE 16
21
22 #define FSCRYPT_MIN_KEY_SIZE 16
23 #define FSCRYPT_MAX_HW_WRAPPED_KEY_SIZE 128
24
25 #define FSCRYPT_CONTEXT_V1 1
26 #define FSCRYPT_CONTEXT_V2 2
27
28 struct fscrypt_context_v1 {
29 u8 version; /* FSCRYPT_CONTEXT_V1 */
30 u8 contents_encryption_mode;
31 u8 filenames_encryption_mode;
32 u8 flags;
33 u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
34 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
35 };
36
37 struct fscrypt_context_v2 {
38 u8 version; /* FSCRYPT_CONTEXT_V2 */
39 u8 contents_encryption_mode;
40 u8 filenames_encryption_mode;
41 u8 flags;
42 u8 __reserved[4];
43 u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
44 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
45 };
46
47 /**
48 * fscrypt_context - the encryption context of an inode
49 *
50 * This is the on-disk equivalent of an fscrypt_policy, stored alongside each
51 * encrypted file usually in a hidden extended attribute. It contains the
52 * fields from the fscrypt_policy, in order to identify the encryption algorithm
53 * and key with which the file is encrypted. It also contains a nonce that was
54 * randomly generated by fscrypt itself; this is used as KDF input or as a tweak
55 * to cause different files to be encrypted differently.
56 */
57 union fscrypt_context {
58 u8 version;
59 struct fscrypt_context_v1 v1;
60 struct fscrypt_context_v2 v2;
61 };
62
63 /*
64 * Return the size expected for the given fscrypt_context based on its version
65 * number, or 0 if the context version is unrecognized.
66 */
fscrypt_context_size(const union fscrypt_context * ctx)67 static inline int fscrypt_context_size(const union fscrypt_context *ctx)
68 {
69 switch (ctx->version) {
70 case FSCRYPT_CONTEXT_V1:
71 BUILD_BUG_ON(sizeof(ctx->v1) != 28);
72 return sizeof(ctx->v1);
73 case FSCRYPT_CONTEXT_V2:
74 BUILD_BUG_ON(sizeof(ctx->v2) != 40);
75 return sizeof(ctx->v2);
76 }
77 return 0;
78 }
79
80 #undef fscrypt_policy
81 union fscrypt_policy {
82 u8 version;
83 struct fscrypt_policy_v1 v1;
84 struct fscrypt_policy_v2 v2;
85 };
86
87 /*
88 * Return the size expected for the given fscrypt_policy based on its version
89 * number, or 0 if the policy version is unrecognized.
90 */
fscrypt_policy_size(const union fscrypt_policy * policy)91 static inline int fscrypt_policy_size(const union fscrypt_policy *policy)
92 {
93 switch (policy->version) {
94 case FSCRYPT_POLICY_V1:
95 return sizeof(policy->v1);
96 case FSCRYPT_POLICY_V2:
97 return sizeof(policy->v2);
98 }
99 return 0;
100 }
101
102 /* Return the contents encryption mode of a valid encryption policy */
103 static inline u8
fscrypt_policy_contents_mode(const union fscrypt_policy * policy)104 fscrypt_policy_contents_mode(const union fscrypt_policy *policy)
105 {
106 switch (policy->version) {
107 case FSCRYPT_POLICY_V1:
108 return policy->v1.contents_encryption_mode;
109 case FSCRYPT_POLICY_V2:
110 return policy->v2.contents_encryption_mode;
111 }
112 BUG();
113 }
114
115 /* Return the filenames encryption mode of a valid encryption policy */
116 static inline u8
fscrypt_policy_fnames_mode(const union fscrypt_policy * policy)117 fscrypt_policy_fnames_mode(const union fscrypt_policy *policy)
118 {
119 switch (policy->version) {
120 case FSCRYPT_POLICY_V1:
121 return policy->v1.filenames_encryption_mode;
122 case FSCRYPT_POLICY_V2:
123 return policy->v2.filenames_encryption_mode;
124 }
125 BUG();
126 }
127
128 /* Return the flags (FSCRYPT_POLICY_FLAG*) of a valid encryption policy */
129 static inline u8
fscrypt_policy_flags(const union fscrypt_policy * policy)130 fscrypt_policy_flags(const union fscrypt_policy *policy)
131 {
132 switch (policy->version) {
133 case FSCRYPT_POLICY_V1:
134 return policy->v1.flags;
135 case FSCRYPT_POLICY_V2:
136 return policy->v2.flags;
137 }
138 BUG();
139 }
140
141 static inline bool
fscrypt_is_direct_key_policy(const union fscrypt_policy * policy)142 fscrypt_is_direct_key_policy(const union fscrypt_policy *policy)
143 {
144 return fscrypt_policy_flags(policy) & FSCRYPT_POLICY_FLAG_DIRECT_KEY;
145 }
146
147 /**
148 * For encrypted symlinks, the ciphertext length is stored at the beginning
149 * of the string in little-endian format.
150 */
151 struct fscrypt_symlink_data {
152 __le16 len;
153 char encrypted_path[1];
154 } __packed;
155
156 /**
157 * struct fscrypt_prepared_key - a key prepared for actual encryption/decryption
158 * @tfm: crypto API transform object
159 * @blk_key: key for blk-crypto
160 *
161 * Normally only one of the fields will be non-NULL.
162 */
163 struct fscrypt_prepared_key {
164 struct crypto_skcipher *tfm;
165 #ifdef CONFIG_FS_ENCRYPTION_INLINE_CRYPT
166 struct fscrypt_blk_crypto_key *blk_key;
167 #endif
168 };
169
170 /*
171 * fscrypt_info - the "encryption key" for an inode
172 *
173 * When an encrypted file's key is made available, an instance of this struct is
174 * allocated and stored in ->i_crypt_info. Once created, it remains until the
175 * inode is evicted.
176 */
177 struct fscrypt_info {
178
179 /* The key in a form prepared for actual encryption/decryption */
180 struct fscrypt_prepared_key ci_key;
181
182 /* True if the key should be freed when this fscrypt_info is freed */
183 bool ci_owns_key;
184
185 #ifdef CONFIG_FS_ENCRYPTION_INLINE_CRYPT
186 /*
187 * True if this inode will use inline encryption (blk-crypto) instead of
188 * the traditional filesystem-layer encryption.
189 */
190 bool ci_inlinecrypt;
191 #endif
192
193 /*
194 * Encryption mode used for this inode. It corresponds to either the
195 * contents or filenames encryption mode, depending on the inode type.
196 */
197 struct fscrypt_mode *ci_mode;
198
199 /* Back-pointer to the inode */
200 struct inode *ci_inode;
201
202 /*
203 * The master key with which this inode was unlocked (decrypted). This
204 * will be NULL if the master key was found in a process-subscribed
205 * keyring rather than in the filesystem-level keyring.
206 */
207 struct key *ci_master_key;
208
209 /*
210 * Link in list of inodes that were unlocked with the master key.
211 * Only used when ->ci_master_key is set.
212 */
213 struct list_head ci_master_key_link;
214
215 /*
216 * If non-NULL, then encryption is done using the master key directly
217 * and ci_key will equal ci_direct_key->dk_key.
218 */
219 struct fscrypt_direct_key *ci_direct_key;
220
221 /* The encryption policy used by this inode */
222 union fscrypt_policy ci_policy;
223
224 /* This inode's nonce, copied from the fscrypt_context */
225 u8 ci_nonce[FS_KEY_DERIVATION_NONCE_SIZE];
226 };
227
228 typedef enum {
229 FS_DECRYPT = 0,
230 FS_ENCRYPT,
231 } fscrypt_direction_t;
232
fscrypt_valid_enc_modes(u32 contents_mode,u32 filenames_mode)233 static inline bool fscrypt_valid_enc_modes(u32 contents_mode,
234 u32 filenames_mode)
235 {
236 if (contents_mode == FSCRYPT_MODE_AES_128_CBC &&
237 filenames_mode == FSCRYPT_MODE_AES_128_CTS)
238 return true;
239
240 if (contents_mode == FSCRYPT_MODE_AES_256_XTS &&
241 filenames_mode == FSCRYPT_MODE_AES_256_CTS)
242 return true;
243
244 if (contents_mode == FSCRYPT_MODE_ADIANTUM &&
245 filenames_mode == FSCRYPT_MODE_ADIANTUM)
246 return true;
247
248 return false;
249 }
250
251 /* crypto.c */
252 extern struct kmem_cache *fscrypt_info_cachep;
253 extern int fscrypt_initialize(unsigned int cop_flags);
254 extern int fscrypt_crypt_block(const struct inode *inode,
255 fscrypt_direction_t rw, u64 lblk_num,
256 struct page *src_page, struct page *dest_page,
257 unsigned int len, unsigned int offs,
258 gfp_t gfp_flags);
259 extern struct page *fscrypt_alloc_bounce_page(gfp_t gfp_flags);
260 extern const struct dentry_operations fscrypt_d_ops;
261
262 extern void __printf(3, 4) __cold
263 fscrypt_msg(const struct inode *inode, const char *level, const char *fmt, ...);
264
265 #define fscrypt_warn(inode, fmt, ...) \
266 fscrypt_msg((inode), KERN_WARNING, fmt, ##__VA_ARGS__)
267 #define fscrypt_err(inode, fmt, ...) \
268 fscrypt_msg((inode), KERN_ERR, fmt, ##__VA_ARGS__)
269
270 #define FSCRYPT_MAX_IV_SIZE 32
271
272 union fscrypt_iv {
273 struct {
274 /* logical block number within the file */
275 __le64 lblk_num;
276
277 /* per-file nonce; only set in DIRECT_KEY mode */
278 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
279 };
280 u8 raw[FSCRYPT_MAX_IV_SIZE];
281 __le64 dun[FSCRYPT_MAX_IV_SIZE / sizeof(__le64)];
282 };
283
284 void fscrypt_generate_iv(union fscrypt_iv *iv, u64 lblk_num,
285 const struct fscrypt_info *ci);
286
287 /* fname.c */
288 extern int fname_encrypt(struct inode *inode, const struct qstr *iname,
289 u8 *out, unsigned int olen);
290 extern bool fscrypt_fname_encrypted_size(const struct inode *inode,
291 u32 orig_len, u32 max_len,
292 u32 *encrypted_len_ret);
293
294 /* hkdf.c */
295
296 struct fscrypt_hkdf {
297 struct crypto_shash *hmac_tfm;
298 };
299
300 extern int fscrypt_init_hkdf(struct fscrypt_hkdf *hkdf, const u8 *master_key,
301 unsigned int master_key_size);
302
303 /*
304 * The list of contexts in which fscrypt uses HKDF. These values are used as
305 * the first byte of the HKDF application-specific info string to guarantee that
306 * info strings are never repeated between contexts. This ensures that all HKDF
307 * outputs are unique and cryptographically isolated, i.e. knowledge of one
308 * output doesn't reveal another.
309 */
310 #define HKDF_CONTEXT_KEY_IDENTIFIER 1
311 #define HKDF_CONTEXT_PER_FILE_KEY 2
312 #define HKDF_CONTEXT_DIRECT_KEY 3
313 #define HKDF_CONTEXT_IV_INO_LBLK_64_KEY 4
314
315 extern int fscrypt_hkdf_expand(struct fscrypt_hkdf *hkdf, u8 context,
316 const u8 *info, unsigned int infolen,
317 u8 *okm, unsigned int okmlen);
318
319 extern void fscrypt_destroy_hkdf(struct fscrypt_hkdf *hkdf);
320
321 /* inline_crypt.c */
322 #ifdef CONFIG_FS_ENCRYPTION_INLINE_CRYPT
323 extern void fscrypt_select_encryption_impl(struct fscrypt_info *ci);
324
325 static inline bool
fscrypt_using_inline_encryption(const struct fscrypt_info * ci)326 fscrypt_using_inline_encryption(const struct fscrypt_info *ci)
327 {
328 return ci->ci_inlinecrypt;
329 }
330
331 extern int fscrypt_prepare_inline_crypt_key(
332 struct fscrypt_prepared_key *prep_key,
333 const u8 *raw_key,
334 unsigned int raw_key_size,
335 const struct fscrypt_info *ci);
336
337 extern void fscrypt_destroy_inline_crypt_key(
338 struct fscrypt_prepared_key *prep_key);
339
340 extern int fscrypt_derive_raw_secret(struct super_block *sb,
341 const u8 *wrapped_key,
342 unsigned int wrapped_key_size,
343 u8 *raw_secret,
344 unsigned int raw_secret_size);
345
346 /*
347 * Check whether the crypto transform or blk-crypto key has been allocated in
348 * @prep_key, depending on which encryption implementation the file will use.
349 */
350 static inline bool
fscrypt_is_key_prepared(struct fscrypt_prepared_key * prep_key,const struct fscrypt_info * ci)351 fscrypt_is_key_prepared(struct fscrypt_prepared_key *prep_key,
352 const struct fscrypt_info *ci)
353 {
354 /*
355 * The READ_ONCE() here pairs with the smp_store_release() in
356 * fscrypt_prepare_key(). (This only matters for the per-mode keys,
357 * which are shared by multiple inodes.)
358 */
359 if (fscrypt_using_inline_encryption(ci))
360 return READ_ONCE(prep_key->blk_key) != NULL;
361 return READ_ONCE(prep_key->tfm) != NULL;
362 }
363
364 #else /* CONFIG_FS_ENCRYPTION_INLINE_CRYPT */
365
fscrypt_select_encryption_impl(struct fscrypt_info * ci)366 static inline void fscrypt_select_encryption_impl(struct fscrypt_info *ci)
367 {
368 }
369
fscrypt_using_inline_encryption(const struct fscrypt_info * ci)370 static inline bool fscrypt_using_inline_encryption(
371 const struct fscrypt_info *ci)
372 {
373 return false;
374 }
375
376 static inline int
fscrypt_prepare_inline_crypt_key(struct fscrypt_prepared_key * prep_key,const u8 * raw_key,unsigned int raw_key_size,const struct fscrypt_info * ci)377 fscrypt_prepare_inline_crypt_key(struct fscrypt_prepared_key *prep_key,
378 const u8 *raw_key, unsigned int raw_key_size,
379 const struct fscrypt_info *ci)
380 {
381 WARN_ON(1);
382 return -EOPNOTSUPP;
383 }
384
385 static inline void
fscrypt_destroy_inline_crypt_key(struct fscrypt_prepared_key * prep_key)386 fscrypt_destroy_inline_crypt_key(struct fscrypt_prepared_key *prep_key)
387 {
388 }
389
fscrypt_derive_raw_secret(struct super_block * sb,const u8 * wrapped_key,unsigned int wrapped_key_size,u8 * raw_secret,unsigned int raw_secret_size)390 static inline int fscrypt_derive_raw_secret(struct super_block *sb,
391 const u8 *wrapped_key,
392 unsigned int wrapped_key_size,
393 u8 *raw_secret,
394 unsigned int raw_secret_size)
395 {
396 fscrypt_warn(NULL,
397 "kernel built without support for hardware-wrapped keys");
398 return -EOPNOTSUPP;
399 }
400
401 static inline bool
fscrypt_is_key_prepared(struct fscrypt_prepared_key * prep_key,const struct fscrypt_info * ci)402 fscrypt_is_key_prepared(struct fscrypt_prepared_key *prep_key,
403 const struct fscrypt_info *ci)
404 {
405 return READ_ONCE(prep_key->tfm) != NULL;
406 }
407 #endif /* !CONFIG_FS_ENCRYPTION_INLINE_CRYPT */
408
409 /* keyring.c */
410
411 /*
412 * fscrypt_master_key_secret - secret key material of an in-use master key
413 */
414 struct fscrypt_master_key_secret {
415
416 /*
417 * For v2 policy keys: HKDF context keyed by this master key.
418 * For v1 policy keys: not set (hkdf.hmac_tfm == NULL).
419 */
420 struct fscrypt_hkdf hkdf;
421
422 /* Size of the raw key in bytes. Set even if ->raw isn't set. */
423 u32 size;
424
425 /* True if the key in ->raw is a hardware-wrapped key. */
426 bool is_hw_wrapped;
427
428 /*
429 * For v1 policy keys: the raw key. Wiped for v2 policy keys, unless
430 * ->is_hw_wrapped is true, in which case this contains the wrapped key
431 * rather than the key with which 'hkdf' was keyed.
432 */
433 u8 raw[FSCRYPT_MAX_HW_WRAPPED_KEY_SIZE];
434
435 } __randomize_layout;
436
437 /*
438 * fscrypt_master_key - an in-use master key
439 *
440 * This represents a master encryption key which has been added to the
441 * filesystem and can be used to "unlock" the encrypted files which were
442 * encrypted with it.
443 */
444 struct fscrypt_master_key {
445
446 /*
447 * The secret key material. After FS_IOC_REMOVE_ENCRYPTION_KEY is
448 * executed, this is wiped and no new inodes can be unlocked with this
449 * key; however, there may still be inodes in ->mk_decrypted_inodes
450 * which could not be evicted. As long as some inodes still remain,
451 * FS_IOC_REMOVE_ENCRYPTION_KEY can be retried, or
452 * FS_IOC_ADD_ENCRYPTION_KEY can add the secret again.
453 *
454 * Locking: protected by key->sem (outer) and mk_secret_sem (inner).
455 * The reason for two locks is that key->sem also protects modifying
456 * mk_users, which ranks it above the semaphore for the keyring key
457 * type, which is in turn above page faults (via keyring_read). But
458 * sometimes filesystems call fscrypt_get_encryption_info() from within
459 * a transaction, which ranks it below page faults. So we need a
460 * separate lock which protects mk_secret but not also mk_users.
461 */
462 struct fscrypt_master_key_secret mk_secret;
463 struct rw_semaphore mk_secret_sem;
464
465 /*
466 * For v1 policy keys: an arbitrary key descriptor which was assigned by
467 * userspace (->descriptor).
468 *
469 * For v2 policy keys: a cryptographic hash of this key (->identifier).
470 */
471 struct fscrypt_key_specifier mk_spec;
472
473 /*
474 * Keyring which contains a key of type 'key_type_fscrypt_user' for each
475 * user who has added this key. Normally each key will be added by just
476 * one user, but it's possible that multiple users share a key, and in
477 * that case we need to keep track of those users so that one user can't
478 * remove the key before the others want it removed too.
479 *
480 * This is NULL for v1 policy keys; those can only be added by root.
481 *
482 * Locking: in addition to this keyrings own semaphore, this is
483 * protected by the master key's key->sem, so we can do atomic
484 * search+insert. It can also be searched without taking any locks, but
485 * in that case the returned key may have already been removed.
486 */
487 struct key *mk_users;
488
489 /*
490 * Length of ->mk_decrypted_inodes, plus one if mk_secret is present.
491 * Once this goes to 0, the master key is removed from ->s_master_keys.
492 * The 'struct fscrypt_master_key' will continue to live as long as the
493 * 'struct key' whose payload it is, but we won't let this reference
494 * count rise again.
495 */
496 refcount_t mk_refcount;
497
498 /*
499 * List of inodes that were unlocked using this key. This allows the
500 * inodes to be evicted efficiently if the key is removed.
501 */
502 struct list_head mk_decrypted_inodes;
503 spinlock_t mk_decrypted_inodes_lock;
504
505 /* Per-mode keys for DIRECT_KEY policies, allocated on-demand */
506 struct fscrypt_prepared_key mk_direct_keys[__FSCRYPT_MODE_MAX + 1];
507
508 /* Per-mode keys for IV_INO_LBLK_64 policies, allocated on-demand */
509 struct fscrypt_prepared_key mk_iv_ino_lblk_64_keys[__FSCRYPT_MODE_MAX + 1];
510
511 } __randomize_layout;
512
513 static inline bool
is_master_key_secret_present(const struct fscrypt_master_key_secret * secret)514 is_master_key_secret_present(const struct fscrypt_master_key_secret *secret)
515 {
516 /*
517 * The READ_ONCE() is only necessary for fscrypt_drop_inode() and
518 * fscrypt_key_describe(). These run in atomic context, so they can't
519 * take ->mk_secret_sem and thus 'secret' can change concurrently which
520 * would be a data race. But they only need to know whether the secret
521 * *was* present at the time of check, so READ_ONCE() suffices.
522 */
523 return READ_ONCE(secret->size) != 0;
524 }
525
master_key_spec_type(const struct fscrypt_key_specifier * spec)526 static inline const char *master_key_spec_type(
527 const struct fscrypt_key_specifier *spec)
528 {
529 switch (spec->type) {
530 case FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR:
531 return "descriptor";
532 case FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER:
533 return "identifier";
534 }
535 return "[unknown]";
536 }
537
master_key_spec_len(const struct fscrypt_key_specifier * spec)538 static inline int master_key_spec_len(const struct fscrypt_key_specifier *spec)
539 {
540 switch (spec->type) {
541 case FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR:
542 return FSCRYPT_KEY_DESCRIPTOR_SIZE;
543 case FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER:
544 return FSCRYPT_KEY_IDENTIFIER_SIZE;
545 }
546 return 0;
547 }
548
549 extern struct key *
550 fscrypt_find_master_key(struct super_block *sb,
551 const struct fscrypt_key_specifier *mk_spec);
552
553 extern int fscrypt_verify_key_added(struct super_block *sb,
554 const u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]);
555
556 extern int __init fscrypt_init_keyring(void);
557
558 /* keysetup.c */
559
560 struct fscrypt_mode {
561 const char *friendly_name;
562 const char *cipher_str;
563 int keysize;
564 int ivsize;
565 enum blk_crypto_mode_num blk_crypto_mode;
566 int logged_impl_name;
567 };
568
569 extern struct fscrypt_mode fscrypt_modes[];
570
571 static inline bool
fscrypt_mode_supports_direct_key(const struct fscrypt_mode * mode)572 fscrypt_mode_supports_direct_key(const struct fscrypt_mode *mode)
573 {
574 return mode->ivsize >= offsetofend(union fscrypt_iv, nonce);
575 }
576
577 extern int fscrypt_prepare_key(struct fscrypt_prepared_key *prep_key,
578 const u8 *raw_key, unsigned int raw_key_size,
579 const struct fscrypt_info *ci);
580
581 extern void fscrypt_destroy_prepared_key(struct fscrypt_prepared_key *prep_key);
582
583 extern int fscrypt_set_derived_key(struct fscrypt_info *ci,
584 const u8 *derived_key);
585
586 /* keysetup_v1.c */
587
588 extern void fscrypt_put_direct_key(struct fscrypt_direct_key *dk);
589
590 extern int fscrypt_setup_v1_file_key(struct fscrypt_info *ci,
591 const u8 *raw_master_key);
592
593 extern int fscrypt_setup_v1_file_key_via_subscribed_keyrings(
594 struct fscrypt_info *ci);
595 /* policy.c */
596
597 extern bool fscrypt_policies_equal(const union fscrypt_policy *policy1,
598 const union fscrypt_policy *policy2);
599 extern bool fscrypt_supported_policy(const union fscrypt_policy *policy_u,
600 const struct inode *inode);
601 extern int fscrypt_policy_from_context(union fscrypt_policy *policy_u,
602 const union fscrypt_context *ctx_u,
603 int ctx_size);
604
605 #endif /* _FSCRYPT_PRIVATE_H */
606