1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * fs-verity: read-only file-based authenticity protection
4 *
5 * This header declares the interface between the fs/verity/ support layer and
6 * filesystems that support fs-verity.
7 *
8 * Copyright 2019 Google LLC
9 */
10
11 #ifndef _LINUX_FSVERITY_H
12 #define _LINUX_FSVERITY_H
13
14 #include <linux/fs.h>
15 #include <uapi/linux/fsverity.h>
16
17 /* Verity operations for filesystems */
18 struct fsverity_operations {
19
20 /**
21 * Begin enabling verity on the given file.
22 *
23 * @filp: a readonly file descriptor for the file
24 *
25 * The filesystem must do any needed filesystem-specific preparations
26 * for enabling verity, e.g. evicting inline data. It also must return
27 * -EBUSY if verity is already being enabled on the given file.
28 *
29 * i_rwsem is held for write.
30 *
31 * Return: 0 on success, -errno on failure
32 */
33 int (*begin_enable_verity)(struct file *filp);
34
35 /**
36 * End enabling verity on the given file.
37 *
38 * @filp: a readonly file descriptor for the file
39 * @desc: the verity descriptor to write, or NULL on failure
40 * @desc_size: size of verity descriptor, or 0 on failure
41 * @merkle_tree_size: total bytes the Merkle tree took up
42 *
43 * If desc == NULL, then enabling verity failed and the filesystem only
44 * must do any necessary cleanups. Else, it must also store the given
45 * verity descriptor to a fs-specific location associated with the inode
46 * and do any fs-specific actions needed to mark the inode as a verity
47 * inode, e.g. setting a bit in the on-disk inode. The filesystem is
48 * also responsible for setting the S_VERITY flag in the VFS inode.
49 *
50 * i_rwsem is held for write, but it may have been dropped between
51 * ->begin_enable_verity() and ->end_enable_verity().
52 *
53 * Return: 0 on success, -errno on failure
54 */
55 int (*end_enable_verity)(struct file *filp, const void *desc,
56 size_t desc_size, u64 merkle_tree_size);
57
58 /**
59 * Get the verity descriptor of the given inode.
60 *
61 * @inode: an inode with the S_VERITY flag set
62 * @buf: buffer in which to place the verity descriptor
63 * @bufsize: size of @buf, or 0 to retrieve the size only
64 *
65 * If bufsize == 0, then the size of the verity descriptor is returned.
66 * Otherwise the verity descriptor is written to 'buf' and its actual
67 * size is returned; -ERANGE is returned if it's too large. This may be
68 * called by multiple processes concurrently on the same inode.
69 *
70 * Return: the size on success, -errno on failure
71 */
72 int (*get_verity_descriptor)(struct inode *inode, void *buf,
73 size_t bufsize);
74
75 /**
76 * Read a Merkle tree page of the given inode.
77 *
78 * @inode: the inode
79 * @index: 0-based index of the page within the Merkle tree
80 * @num_ra_pages: The number of Merkle tree pages that should be
81 * prefetched starting at @index if the page at @index
82 * isn't already cached. Implementations may ignore this
83 * argument; it's only a performance optimization.
84 *
85 * This can be called at any time on an open verity file, as well as
86 * between ->begin_enable_verity() and ->end_enable_verity(). It may be
87 * called by multiple processes concurrently, even with the same page.
88 *
89 * Note that this must retrieve a *page*, not necessarily a *block*.
90 *
91 * Return: the page on success, ERR_PTR() on failure
92 */
93 struct page *(*read_merkle_tree_page)(struct inode *inode,
94 pgoff_t index,
95 unsigned long num_ra_pages);
96
97 /**
98 * Write a Merkle tree block to the given inode.
99 *
100 * @inode: the inode for which the Merkle tree is being built
101 * @buf: block to write
102 * @index: 0-based index of the block within the Merkle tree
103 * @log_blocksize: log base 2 of the Merkle tree block size
104 *
105 * This is only called between ->begin_enable_verity() and
106 * ->end_enable_verity().
107 *
108 * Return: 0 on success, -errno on failure
109 */
110 int (*write_merkle_tree_block)(struct inode *inode, const void *buf,
111 u64 index, int log_blocksize);
112 };
113
114 #ifdef CONFIG_FS_VERITY
115
fsverity_get_info(const struct inode * inode)116 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
117 {
118 /*
119 * Pairs with the cmpxchg_release() in fsverity_set_info().
120 * I.e., another task may publish ->i_verity_info concurrently,
121 * executing a RELEASE barrier. We need to use smp_load_acquire() here
122 * to safely ACQUIRE the memory the other task published.
123 */
124 return smp_load_acquire(&inode->i_verity_info);
125 }
126
127 /* enable.c */
128
129 int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
130
131 /* measure.c */
132
133 int fsverity_ioctl_measure(struct file *filp, void __user *arg);
134
135 /* open.c */
136
137 int fsverity_file_open(struct inode *inode, struct file *filp);
138 int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
139 void fsverity_cleanup_inode(struct inode *inode);
140
141 /* read_metadata.c */
142
143 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
144
145 /* verify.c */
146
147 bool fsverity_verify_page(struct page *page);
148 void fsverity_verify_bio(struct bio *bio);
149 void fsverity_enqueue_verify_work(struct work_struct *work);
150
151 #else /* !CONFIG_FS_VERITY */
152
fsverity_get_info(const struct inode * inode)153 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
154 {
155 return NULL;
156 }
157
158 /* enable.c */
159
fsverity_ioctl_enable(struct file * filp,const void __user * arg)160 static inline int fsverity_ioctl_enable(struct file *filp,
161 const void __user *arg)
162 {
163 return -EOPNOTSUPP;
164 }
165
166 /* measure.c */
167
fsverity_ioctl_measure(struct file * filp,void __user * arg)168 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
169 {
170 return -EOPNOTSUPP;
171 }
172
173 /* open.c */
174
fsverity_file_open(struct inode * inode,struct file * filp)175 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
176 {
177 return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
178 }
179
fsverity_prepare_setattr(struct dentry * dentry,struct iattr * attr)180 static inline int fsverity_prepare_setattr(struct dentry *dentry,
181 struct iattr *attr)
182 {
183 return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
184 }
185
fsverity_cleanup_inode(struct inode * inode)186 static inline void fsverity_cleanup_inode(struct inode *inode)
187 {
188 }
189
190 /* read_metadata.c */
191
fsverity_ioctl_read_metadata(struct file * filp,const void __user * uarg)192 static inline int fsverity_ioctl_read_metadata(struct file *filp,
193 const void __user *uarg)
194 {
195 return -EOPNOTSUPP;
196 }
197
198 /* verify.c */
199
fsverity_verify_page(struct page * page)200 static inline bool fsverity_verify_page(struct page *page)
201 {
202 WARN_ON(1);
203 return false;
204 }
205
fsverity_verify_bio(struct bio * bio)206 static inline void fsverity_verify_bio(struct bio *bio)
207 {
208 WARN_ON(1);
209 }
210
fsverity_enqueue_verify_work(struct work_struct * work)211 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
212 {
213 WARN_ON(1);
214 }
215
216 #endif /* !CONFIG_FS_VERITY */
217
218 /**
219 * fsverity_active() - do reads from the inode need to go through fs-verity?
220 * @inode: inode to check
221 *
222 * This checks whether ->i_verity_info has been set.
223 *
224 * Filesystems call this from ->readpages() to check whether the pages need to
225 * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to
226 * a race condition where the file is being read concurrently with
227 * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.)
228 *
229 * Return: true if reads need to go through fs-verity, otherwise false
230 */
fsverity_active(const struct inode * inode)231 static inline bool fsverity_active(const struct inode *inode)
232 {
233 return fsverity_get_info(inode) != NULL;
234 }
235
236 #endif /* _LINUX_FSVERITY_H */
237