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 */