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 <linux/mm.h>
16 #include <crypto/hash_info.h>
17 #include <crypto/sha2.h>
18 #include <uapi/linux/fsverity.h>
19
20 /*
21 * Largest digest size among all hash algorithms supported by fs-verity.
22 * Currently assumed to be <= size of fsverity_descriptor::root_hash.
23 */
24 #define FS_VERITY_MAX_DIGEST_SIZE SHA512_DIGEST_SIZE
25
26 /* Arbitrary limit to bound the kmalloc() size. Can be changed. */
27 #define FS_VERITY_MAX_DESCRIPTOR_SIZE 16384
28
29 /* Verity operations for filesystems */
30 struct fsverity_operations {
31
32 /**
33 * Begin enabling verity on the given file.
34 *
35 * @filp: a readonly file descriptor for the file
36 *
37 * The filesystem must do any needed filesystem-specific preparations
38 * for enabling verity, e.g. evicting inline data. It also must return
39 * -EBUSY if verity is already being enabled on the given file.
40 *
41 * i_rwsem is held for write.
42 *
43 * Return: 0 on success, -errno on failure
44 */
45 int (*begin_enable_verity)(struct file *filp);
46
47 /**
48 * End enabling verity on the given file.
49 *
50 * @filp: a readonly file descriptor for the file
51 * @desc: the verity descriptor to write, or NULL on failure
52 * @desc_size: size of verity descriptor, or 0 on failure
53 * @merkle_tree_size: total bytes the Merkle tree took up
54 *
55 * If desc == NULL, then enabling verity failed and the filesystem only
56 * must do any necessary cleanups. Else, it must also store the given
57 * verity descriptor to a fs-specific location associated with the inode
58 * and do any fs-specific actions needed to mark the inode as a verity
59 * inode, e.g. setting a bit in the on-disk inode. The filesystem is
60 * also responsible for setting the S_VERITY flag in the VFS inode.
61 *
62 * i_rwsem is held for write, but it may have been dropped between
63 * ->begin_enable_verity() and ->end_enable_verity().
64 *
65 * Return: 0 on success, -errno on failure
66 */
67 int (*end_enable_verity)(struct file *filp, const void *desc,
68 size_t desc_size, u64 merkle_tree_size);
69
70 /**
71 * Get the verity descriptor of the given inode.
72 *
73 * @inode: an inode with the S_VERITY flag set
74 * @buf: buffer in which to place the verity descriptor
75 * @bufsize: size of @buf, or 0 to retrieve the size only
76 *
77 * If bufsize == 0, then the size of the verity descriptor is returned.
78 * Otherwise the verity descriptor is written to 'buf' and its actual
79 * size is returned; -ERANGE is returned if it's too large. This may be
80 * called by multiple processes concurrently on the same inode.
81 *
82 * Return: the size on success, -errno on failure
83 */
84 int (*get_verity_descriptor)(struct inode *inode, void *buf,
85 size_t bufsize);
86
87 /**
88 * Read a Merkle tree page of the given inode.
89 *
90 * @inode: the inode
91 * @index: 0-based index of the page within the Merkle tree
92 * @num_ra_pages: The number of Merkle tree pages that should be
93 * prefetched starting at @index if the page at @index
94 * isn't already cached. Implementations may ignore this
95 * argument; it's only a performance optimization.
96 *
97 * This can be called at any time on an open verity file. It may be
98 * called by multiple processes concurrently, even with the same page.
99 *
100 * Note that this must retrieve a *page*, not necessarily a *block*.
101 *
102 * Return: the page on success, ERR_PTR() on failure
103 */
104 struct page *(*read_merkle_tree_page)(struct inode *inode,
105 pgoff_t index,
106 unsigned long num_ra_pages);
107
108 /**
109 * Write a Merkle tree block to the given inode.
110 *
111 * @inode: the inode for which the Merkle tree is being built
112 * @buf: the Merkle tree block to write
113 * @pos: the position of the block in the Merkle tree (in bytes)
114 * @size: the Merkle tree block size (in bytes)
115 *
116 * This is only called between ->begin_enable_verity() and
117 * ->end_enable_verity().
118 *
119 * Return: 0 on success, -errno on failure
120 */
121 int (*write_merkle_tree_block)(struct inode *inode, const void *buf,
122 u64 pos, unsigned int size);
123 };
124
125 #ifdef CONFIG_FS_VERITY
126
127 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
128 {
129 /*
130 * Pairs with the cmpxchg_release() in fsverity_set_info().
131 * I.e., another task may publish ->i_verity_info concurrently,
132 * executing a RELEASE barrier. We need to use smp_load_acquire() here
133 * to safely ACQUIRE the memory the other task published.
134 */
135 return smp_load_acquire(&inode->i_verity_info);
136 }
137
138 /* enable.c */
139
140 int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
141
142 /* measure.c */
143
144 int fsverity_ioctl_measure(struct file *filp, void __user *arg);
145 int fsverity_get_digest(struct inode *inode,
146 u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
147 u8 *alg, enum hash_algo *halg);
148
149 /* open.c */
150
151 int __fsverity_file_open(struct inode *inode, struct file *filp);
152 int __fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
153 void __fsverity_cleanup_inode(struct inode *inode);
154
155 /**
156 * fsverity_cleanup_inode() - free the inode's verity info, if present
157 * @inode: an inode being evicted
158 *
159 * Filesystems must call this on inode eviction to free ->i_verity_info.
160 */
161 static inline void fsverity_cleanup_inode(struct inode *inode)
162 {
163 if (inode->i_verity_info)
164 __fsverity_cleanup_inode(inode);
165 }
166
167 /* read_metadata.c */
168
169 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
170
171 /* verify.c */
172
173 bool fsverity_verify_blocks(struct folio *folio, size_t len, size_t offset);
174 void fsverity_verify_bio(struct bio *bio);
175 void fsverity_enqueue_verify_work(struct work_struct *work);
176
177 #else /* !CONFIG_FS_VERITY */
178
179 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
180 {
181 return NULL;
182 }
183
184 /* enable.c */
185
186 static inline int fsverity_ioctl_enable(struct file *filp,
187 const void __user *arg)
188 {
189 return -EOPNOTSUPP;
190 }
191
192 /* measure.c */
193
194 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
195 {
196 return -EOPNOTSUPP;
197 }
198
199 static inline int fsverity_get_digest(struct inode *inode,
200 u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
201 u8 *alg, enum hash_algo *halg)
202 {
203 /*
204 * fsverity is not enabled in the kernel configuration, so always report
205 * that the file doesn't have fsverity enabled (digest size 0).
206 */
207 return 0;
208 }
209
210 /* open.c */
211
212 static inline int __fsverity_file_open(struct inode *inode, struct file *filp)
213 {
214 return -EOPNOTSUPP;
215 }
216
217 static inline int __fsverity_prepare_setattr(struct dentry *dentry,
218 struct iattr *attr)
219 {
220 return -EOPNOTSUPP;
221 }
222
223 static inline void fsverity_cleanup_inode(struct inode *inode)
224 {
225 }
226
227 /* read_metadata.c */
228
229 static inline int fsverity_ioctl_read_metadata(struct file *filp,
230 const void __user *uarg)
231 {
232 return -EOPNOTSUPP;
233 }
234
235 /* verify.c */
236
237 static inline bool fsverity_verify_blocks(struct folio *folio, size_t len,
238 size_t offset)
239 {
240 WARN_ON_ONCE(1);
241 return false;
242 }
243
244 static inline void fsverity_verify_bio(struct bio *bio)
245 {
246 WARN_ON_ONCE(1);
247 }
248
249 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
250 {
251 WARN_ON_ONCE(1);
252 }
253
254 #endif /* !CONFIG_FS_VERITY */
255
256 static inline bool fsverity_verify_folio(struct folio *folio)
257 {
258 return fsverity_verify_blocks(folio, folio_size(folio), 0);
259 }
260
261 static inline bool fsverity_verify_page(struct page *page)
262 {
263 return fsverity_verify_blocks(page_folio(page), PAGE_SIZE, 0);
264 }
265
266 /**
267 * fsverity_active() - do reads from the inode need to go through fs-verity?
268 * @inode: inode to check
269 *
270 * This checks whether ->i_verity_info has been set.
271 *
272 * Filesystems call this from ->readahead() to check whether the pages need to
273 * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to
274 * a race condition where the file is being read concurrently with
275 * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.)
276 *
277 * Return: true if reads need to go through fs-verity, otherwise false
278 */
279 static inline bool fsverity_active(const struct inode *inode)
280 {
281 return fsverity_get_info(inode) != NULL;
282 }
283
284 /**
285 * fsverity_file_open() - prepare to open a verity file
286 * @inode: the inode being opened
287 * @filp: the struct file being set up
288 *
289 * When opening a verity file, deny the open if it is for writing. Otherwise,
290 * set up the inode's ->i_verity_info if not already done.
291 *
292 * When combined with fscrypt, this must be called after fscrypt_file_open().
293 * Otherwise, we won't have the key set up to decrypt the verity metadata.
294 *
295 * Return: 0 on success, -errno on failure
296 */
297 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
298 {
299 if (IS_VERITY(inode))
300 return __fsverity_file_open(inode, filp);
301 return 0;
302 }
303
304 /**
305 * fsverity_prepare_setattr() - prepare to change a verity inode's attributes
306 * @dentry: dentry through which the inode is being changed
307 * @attr: attributes to change
308 *
309 * Verity files are immutable, so deny truncates. This isn't covered by the
310 * open-time check because sys_truncate() takes a path, not a file descriptor.
311 *
312 * Return: 0 on success, -errno on failure
313 */
314 static inline int fsverity_prepare_setattr(struct dentry *dentry,
315 struct iattr *attr)
316 {
317 if (IS_VERITY(d_inode(dentry)))
318 return __fsverity_prepare_setattr(dentry, attr);
319 return 0;
320 }
321
322 #endif /* _LINUX_FSVERITY_H */
323
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.