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