Branch data Line data Source code
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 [ # # # ]: 0 : 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 [ # # # # : 0 : 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 : 0 : fscrypt_policy_contents_mode(const union fscrypt_policy *policy)
103 : : {
104 [ # # # ]: 0 : switch (policy->version) {
105 : : case FSCRYPT_POLICY_V1:
106 : 0 : return policy->v1.contents_encryption_mode;
107 : : case FSCRYPT_POLICY_V2:
108 : 0 : return policy->v2.contents_encryption_mode;
109 : : }
110 : 0 : BUG();
111 : : }
112 : :
113 : : /* Return the filenames encryption mode of a valid encryption policy */
114 : : static inline u8
115 : 0 : fscrypt_policy_fnames_mode(const union fscrypt_policy *policy)
116 : : {
117 [ # # # ]: 0 : switch (policy->version) {
118 : : case FSCRYPT_POLICY_V1:
119 : 0 : return policy->v1.filenames_encryption_mode;
120 : : case FSCRYPT_POLICY_V2:
121 : 0 : return policy->v2.filenames_encryption_mode;
122 : : }
123 : 0 : BUG();
124 : : }
125 : :
126 : : /* Return the flags (FSCRYPT_POLICY_FLAG*) of a valid encryption policy */
127 : : static inline u8
128 : 0 : fscrypt_policy_flags(const union fscrypt_policy *policy)
129 : : {
130 [ # # # ]: 0 : switch (policy->version) {
131 : : case FSCRYPT_POLICY_V1:
132 : 0 : return policy->v1.flags;
133 : : case FSCRYPT_POLICY_V2:
134 : 0 : return policy->v2.flags;
135 : : }
136 : 0 : BUG();
137 : : }
138 : :
139 : : static inline bool
140 : : fscrypt_is_direct_key_policy(const union fscrypt_policy *policy)
141 : : {
142 : 0 : 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 [ # # # # ]: 0 : if (contents_mode == FSCRYPT_MODE_AES_128_CBC &&
218 : 0 : filenames_mode == FSCRYPT_MODE_AES_128_CTS)
219 : : return true;
220 : :
221 [ # # # # ]: 0 : if (contents_mode == FSCRYPT_MODE_AES_256_XTS &&
222 : 0 : filenames_mode == FSCRYPT_MODE_AES_256_CTS)
223 : : return true;
224 : :
225 [ # # # # ]: 0 : if (contents_mode == FSCRYPT_MODE_ADIANTUM &&
226 : 0 : 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 : 0 : 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 [ # # # ]: 0 : 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 [ # # # # : 0 : 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 : 0 : 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 */
|
