include/linux/fscrypt.h

1 /* SPDX-License-Identifier: GPL-2.0 */
3  * fscrypt.h: declarations for per-file encryption
5  * Filesystems that implement per-file encryption must include this header
24  * some of the supported modes don't support arbitrarily byte-aligned messages.
28  * filesystem can generate arbitrarily byte-aligned block lengths (e.g., via
53 #define FSTR_TO_QSTR(f)		QSTR_INIT((f)->name, (f)->len)
54 #define fname_name(p)		((p)->disk_name.name)
55 #define fname_len(p)		((p)->disk_name.len)
67 	 * first time an encryption key is set up for a file.  The bounce page
70 	 * - fscrypt_encrypt_pagecache_blocks()
71 	 * - fscrypt_zeroout_range() for files not using inline crypto
83 	 * limited to 32-bit or 64-bit data unit numbers and where programming
92 	 * not compatible with filesystems that encrypt variable-length blocks
103 	 * contains the filesystem-specific key description prefix that is
120 	 *	   may be less than @len.  On failure, returns -ENODATA if the
121 	 *	   inode doesn't have a context, -ERANGE if the context is
122 	 *	   longer than @len, or another -errno code.
140 	 * Return: 0 on success, -errno on failure.
182 	 * On successful non-NULL return, *num_devs is set to the number of
200 	 * I.e., another task may publish ->i_crypt_info concurrently, executing  in fscrypt_get_inode_info()
204 	return smp_load_acquire(&inode->i_crypt_info);  in fscrypt_get_inode_info()
208  * fscrypt_needs_contents_encryption() - check whether an inode needs
220 	return IS_ENCRYPTED(inode) && S_ISREG(inode->i_mode);  in fscrypt_needs_contents_encryption()
224  * When d_splice_alias() moves a directory's no-key alias to its plaintext alias
225  * as a result of the encryption key being added, DCACHE_NOKEY_NAME must be
227  * because fscrypt doesn't allow no-key names to be the source or target of a
232 	dentry->d_flags &= ~DCACHE_NOKEY_NAME;  in fscrypt_handle_d_move()
236  * fscrypt_is_nokey_name() - test whether a dentry is a no-key name
239  * This returns true if the dentry is a no-key dentry.  A no-key dentry is a
241  * encryption key added yet.  Such dentries may be either positive or negative.
244  * and the new filename's dentry is a no-key dentry, it must fail the operation
245  * with ENOKEY.  This includes ->create(), ->mkdir(), ->mknod(), ->symlink(),
246  * ->rename(), and ->link().  (However, ->rename() and ->link() are already
250  * encryption key, but just checking for the key on the directory inode during
251  * the final filesystem operation doesn't guarantee that the key was available
252  * during the preceding dentry lookup.  And the key must have already been
255  * dentry not to be invalidated due to it incorrectly having the no-key flag.
257  * Return: %true if the dentry is a no-key name
261 	return dentry->d_flags & DCACHE_NOKEY_NAME;  in fscrypt_is_nokey_name()
283 	return page->mapping == NULL;  in fscrypt_is_bounce_page()
293 	return folio->mapping == NULL;  in fscrypt_is_bounce_folio()
298 	return bounce_folio->private;  in fscrypt_pagecache_folio()
325 	return dummy_policy->policy != NULL;  in fscrypt_is_dummy_policy_set()
330 	kfree(dummy_policy->policy);  in fscrypt_free_dummy_policy()
331 	dummy_policy->policy = NULL;  in fscrypt_free_dummy_policy()
358 	kfree(fname->crypto_buf.name);  in fscrypt_free_filename()
404 	sb->s_cop = s_cop;  in fscrypt_set_ops()
438 	return ERR_PTR(-EOPNOTSUPP);  in fscrypt_encrypt_pagecache_blocks()
447 	return -EOPNOTSUPP;  in fscrypt_encrypt_block_inplace()
453 	return -EOPNOTSUPP;  in fscrypt_decrypt_pagecache_blocks()
461 	return -EOPNOTSUPP;  in fscrypt_decrypt_block_inplace()
472 	return ERR_PTR(-EINVAL);  in fscrypt_pagecache_page()
483 	return ERR_PTR(-EINVAL);  in fscrypt_pagecache_folio()
494 	return -EOPNOTSUPP;  in fscrypt_ioctl_set_policy()
499 	return -EOPNOTSUPP;  in fscrypt_ioctl_get_policy()
505 	return -EOPNOTSUPP;  in fscrypt_ioctl_get_policy_ex()
510 	return -EOPNOTSUPP;  in fscrypt_ioctl_get_nonce()
521 	return -EOPNOTSUPP;  in fscrypt_set_context()
531 	return -EINVAL;  in fscrypt_parse_test_dummy_encryption()
565 	return -EOPNOTSUPP;  in fscrypt_ioctl_add_key()
570 	return -EOPNOTSUPP;  in fscrypt_ioctl_remove_key()
576 	return -EOPNOTSUPP;  in fscrypt_ioctl_remove_key_all_users()
582 	return -EOPNOTSUPP;  in fscrypt_ioctl_get_key_status()
592 		return -EOPNOTSUPP;  in fscrypt_prepare_new_inode()
616 		return -EOPNOTSUPP;  in fscrypt_setup_filename()
619 	fname->usr_fname = iname;  in fscrypt_setup_filename()
620 	fname->disk_name.name = (unsigned char *)iname->name;  in fscrypt_setup_filename()
621 	fname->disk_name.len = iname->len;  in fscrypt_setup_filename()
633 	return -EOPNOTSUPP;  in fscrypt_fname_alloc_buffer()
646 	return -EOPNOTSUPP;  in fscrypt_fname_disk_to_usr()
653 	if (de_name_len != fname->disk_name.len)  in fscrypt_match_name()
655 	return !memcmp(de_name, fname->disk_name.name, fname->disk_name.len);  in fscrypt_match_name()
680 	return -EOPNOTSUPP;  in fscrypt_zeroout_range()
688 		return -EOPNOTSUPP;  in fscrypt_file_open()
695 	return -EOPNOTSUPP;  in __fscrypt_prepare_link()
704 	return -EOPNOTSUPP;  in __fscrypt_prepare_rename()
711 	return -EOPNOTSUPP;  in __fscrypt_prepare_lookup()
717 	return -EOPNOTSUPP;  in fscrypt_prepare_lookup_partial()
722 	return -EOPNOTSUPP;  in __fscrypt_prepare_readdir()
728 	return -EOPNOTSUPP;  in __fscrypt_prepare_setattr()
745 		return -EOPNOTSUPP;  in fscrypt_prepare_symlink()
746 	disk_link->name = (unsigned char *)target;  in fscrypt_prepare_symlink()
747 	disk_link->len = len + 1;  in fscrypt_prepare_symlink()
748 	if (disk_link->len > max_len)  in fscrypt_prepare_symlink()
749 		return -ENAMETOOLONG;  in fscrypt_prepare_symlink()
758 	return -EOPNOTSUPP;  in __fscrypt_encrypt_symlink()
766 	return ERR_PTR(-EOPNOTSUPP);  in fscrypt_get_symlink()
772 	return -EOPNOTSUPP;  in fscrypt_symlink_getattr()
847  * fscrypt_inode_uses_inline_crypto() - test whether an inode uses inline
849  * @inode: an inode. If encrypted, its key must be set up.
852  *	   encryption should be done in the block layer via blk-crypto rather
862  * fscrypt_inode_uses_fs_layer_crypto() - test whether an inode uses fs-layer
864  * @inode: an inode. If encrypted, its key must be set up.
868  *	   block layer via blk-crypto.
877  * fscrypt_has_encryption_key() - check whether an inode has had its key set up
880  * Return: %true if the inode has had its encryption key set up, else %false.
883  * set up the key first.
891  * fscrypt_prepare_link() - prepare to link an inode into a possibly-encrypted
898  * encryption key is available --- since otherwise we'd have no way to encrypt
904  * Return: 0 on success, -ENOKEY if the directory's encryption key is missing,
905  * -EXDEV if the link would result in an inconsistent encryption policy, or
906  * another -errno code.
918  * fscrypt_prepare_rename() - prepare for a rename between possibly-encrypted
926  * Prepare for ->rename() where the source and/or target directories may be
928  * directory's encryption key is available --- since otherwise we'd have no way
930  * *is* cryptographically possible without the key.  However, we take the more
931  * conservative approach and just forbid all no-key renames.
936  * Return: 0 on success, -ENOKEY if an encryption key is missing, -EXDEV if the
937  * rename would cause inconsistent encryption policies, or another -errno code.
952  * fscrypt_prepare_lookup() - prepare to lookup a name in a possibly-encrypted
955  * @dentry: filename being looked up
956  * @fname: (output) the name to use to search the on-disk directory
958  * Prepare for ->lookup() in a directory which may be encrypted by determining
959  * the name that will actually be used to search the directory on-disk.  If the
961  * key is available, then the lookup is assumed to be by plaintext name;
962  * otherwise, it is assumed to be by no-key name.
964  * This will set DCACHE_NOKEY_NAME on the dentry if the lookup is by no-key
968  * directory's encryption key is later added.
970  * Return: 0 on success; -ENOENT if the directory's key is unavailable but the
971  * filename isn't a valid no-key name, so a negative dentry should be created;
972  * or another -errno code.
982 	fname->usr_fname = &dentry->d_name;  in fscrypt_prepare_lookup()
983 	fname->disk_name.name = (unsigned char *)dentry->d_name.name;  in fscrypt_prepare_lookup()
984 	fname->disk_name.len = dentry->d_name.len;  in fscrypt_prepare_lookup()
989  * fscrypt_prepare_readdir() - prepare to read a possibly-encrypted directory
992  * If the directory is encrypted and it doesn't already have its encryption key
993  * set up, try to set it up so that the filenames will be listed in plaintext
994  * form rather than in no-key form.
996  * Return: 0 on success; -errno on error.  Note that the encryption key being
999  *	   like the key being unavailable, so that files can still be deleted.
1009  * fscrypt_prepare_setattr() - prepare to change a possibly-encrypted inode's
1014  * Prepare for ->setattr() on a possibly-encrypted inode.  On an encrypted file,
1015  * most attribute changes are allowed even without the encryption key.  However,
1016  * without the encryption key we do have to forbid truncates.  This is needed
1019  * portion past i_size, and re-encrypt it.  (We *could* allow truncating to a
1020  * filesystem block boundary, but it's simpler to just forbid all truncates ---
1021  * and we already forbid all other contents modifications without the key.)
1023  * Return: 0 on success, -ENOKEY if the key is missing, or another -errno code
1024  * if a problem occurred while setting up the encryption key.
1035  * fscrypt_encrypt_symlink() - encrypt the symlink target if needed
1039  * @disk_link: (in/out) the on-disk symlink target being prepared
1042  * into @disk_link->name.  fscrypt_prepare_symlink() must have been called
1043  * previously to compute @disk_link->len.  If the filesystem did not allocate a
1044  * buffer for @disk_link->name after calling fscrypt_prepare_link(), then one
1047  * Return: 0 on success, -errno on failure