1 /* SPDX-License-Identifier: GPL-2.0 */
3 * fs-verity: read-only file-based authenticity protection
5 * This header declares the interface between the fs/verity/ support layer and
6 * filesystems that support fs-verity.
8 * Copyright 2019 Google LLC
11 #ifndef _LINUX_FSVERITY_H
12 #define _LINUX_FSVERITY_H
15 #include <crypto/hash_info.h>
16 #include <crypto/sha2.h>
17 #include <uapi/linux/fsverity.h>
20 * Largest digest size among all hash algorithms supported by fs-verity.
21 * Currently assumed to be <= size of fsverity_descriptor::root_hash.
23 #define FS_VERITY_MAX_DIGEST_SIZE SHA512_DIGEST_SIZE
25 /* Verity operations for filesystems */
26 struct fsverity_operations {
29 * Begin enabling verity on the given file.
31 * @filp: a readonly file descriptor for the file
33 * The filesystem must do any needed filesystem-specific preparations
34 * for enabling verity, e.g. evicting inline data. It also must return
35 * -EBUSY if verity is already being enabled on the given file.
37 * i_rwsem is held for write.
39 * Return: 0 on success, -errno on failure
41 int (*begin_enable_verity)(struct file *filp);
44 * End enabling verity on the given file.
46 * @filp: a readonly file descriptor for the file
47 * @desc: the verity descriptor to write, or NULL on failure
48 * @desc_size: size of verity descriptor, or 0 on failure
49 * @merkle_tree_size: total bytes the Merkle tree took up
51 * If desc == NULL, then enabling verity failed and the filesystem only
52 * must do any necessary cleanups. Else, it must also store the given
53 * verity descriptor to a fs-specific location associated with the inode
54 * and do any fs-specific actions needed to mark the inode as a verity
55 * inode, e.g. setting a bit in the on-disk inode. The filesystem is
56 * also responsible for setting the S_VERITY flag in the VFS inode.
58 * i_rwsem is held for write, but it may have been dropped between
59 * ->begin_enable_verity() and ->end_enable_verity().
61 * Return: 0 on success, -errno on failure
63 int (*end_enable_verity)(struct file *filp, const void *desc,
64 size_t desc_size, u64 merkle_tree_size);
67 * Get the verity descriptor of the given inode.
69 * @inode: an inode with the S_VERITY flag set
70 * @buf: buffer in which to place the verity descriptor
71 * @bufsize: size of @buf, or 0 to retrieve the size only
73 * If bufsize == 0, then the size of the verity descriptor is returned.
74 * Otherwise the verity descriptor is written to 'buf' and its actual
75 * size is returned; -ERANGE is returned if it's too large. This may be
76 * called by multiple processes concurrently on the same inode.
78 * Return: the size on success, -errno on failure
80 int (*get_verity_descriptor)(struct inode *inode, void *buf,
84 * Read a Merkle tree page of the given inode.
87 * @index: 0-based index of the page within the Merkle tree
88 * @num_ra_pages: The number of Merkle tree pages that should be
89 * prefetched starting at @index if the page at @index
90 * isn't already cached. Implementations may ignore this
91 * argument; it's only a performance optimization.
93 * This can be called at any time on an open verity file, as well as
94 * between ->begin_enable_verity() and ->end_enable_verity(). It may be
95 * called by multiple processes concurrently, even with the same page.
97 * Note that this must retrieve a *page*, not necessarily a *block*.
99 * Return: the page on success, ERR_PTR() on failure
101 struct page *(*read_merkle_tree_page)(struct inode *inode,
103 unsigned long num_ra_pages);
106 * Write a Merkle tree block to the given inode.
108 * @inode: the inode for which the Merkle tree is being built
109 * @buf: block to write
110 * @index: 0-based index of the block within the Merkle tree
111 * @log_blocksize: log base 2 of the Merkle tree block size
113 * This is only called between ->begin_enable_verity() and
114 * ->end_enable_verity().
116 * Return: 0 on success, -errno on failure
118 int (*write_merkle_tree_block)(struct inode *inode, const void *buf,
119 u64 index, int log_blocksize);
122 #ifdef CONFIG_FS_VERITY
124 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
127 * Pairs with the cmpxchg_release() in fsverity_set_info().
128 * I.e., another task may publish ->i_verity_info concurrently,
129 * executing a RELEASE barrier. We need to use smp_load_acquire() here
130 * to safely ACQUIRE the memory the other task published.
132 return smp_load_acquire(&inode->i_verity_info);
137 int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
141 int fsverity_ioctl_measure(struct file *filp, void __user *arg);
142 int fsverity_get_digest(struct inode *inode,
143 u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
144 enum hash_algo *alg);
148 int fsverity_file_open(struct inode *inode, struct file *filp);
149 int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
150 void fsverity_cleanup_inode(struct inode *inode);
152 /* read_metadata.c */
154 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
158 bool fsverity_verify_page(struct page *page);
159 void fsverity_verify_bio(struct bio *bio);
160 void fsverity_enqueue_verify_work(struct work_struct *work);
162 #else /* !CONFIG_FS_VERITY */
164 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
171 static inline int fsverity_ioctl_enable(struct file *filp,
172 const void __user *arg)
179 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
184 static inline int fsverity_get_digest(struct inode *inode,
185 u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
193 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
195 return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
198 static inline int fsverity_prepare_setattr(struct dentry *dentry,
201 return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
204 static inline void fsverity_cleanup_inode(struct inode *inode)
208 /* read_metadata.c */
210 static inline int fsverity_ioctl_read_metadata(struct file *filp,
211 const void __user *uarg)
218 static inline bool fsverity_verify_page(struct page *page)
224 static inline void fsverity_verify_bio(struct bio *bio)
229 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
234 #endif /* !CONFIG_FS_VERITY */
237 * fsverity_active() - do reads from the inode need to go through fs-verity?
238 * @inode: inode to check
240 * This checks whether ->i_verity_info has been set.
242 * Filesystems call this from ->readahead() to check whether the pages need to
243 * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to
244 * a race condition where the file is being read concurrently with
245 * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.)
247 * Return: true if reads need to go through fs-verity, otherwise false
249 static inline bool fsverity_active(const struct inode *inode)
251 return fsverity_get_info(inode) != NULL;
254 #endif /* _LINUX_FSVERITY_H */