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 struct fsverity_info;
30
31 /* Verity operations for filesystems */
32 struct fsverity_operations {
33 /**
34 * Begin enabling verity on the given file.
35 *
36 * @filp: a readonly file descriptor for the file
37 *
38 * The filesystem must do any needed filesystem-specific preparations
39 * for enabling verity, e.g. evicting inline data. It also must return
40 * -EBUSY if verity is already being enabled on the given file.
41 *
42 * i_rwsem is held for write.
43 *
44 * Return: 0 on success, -errno on failure
45 */
46 int (*begin_enable_verity)(struct file *filp);
47
48 /**
49 * End enabling verity on the given file.
50 *
51 * @filp: a readonly file descriptor for the file
52 * @desc: the verity descriptor to write, or NULL on failure
53 * @desc_size: size of verity descriptor, or 0 on failure
54 * @merkle_tree_size: total bytes the Merkle tree took up
55 *
56 * If desc == NULL, then enabling verity failed and the filesystem only
57 * must do any necessary cleanups. Else, it must also store the given
58 * verity descriptor to a fs-specific location associated with the inode
59 * and do any fs-specific actions needed to mark the inode as a verity
60 * inode, e.g. setting a bit in the on-disk inode. The filesystem is
61 * also responsible for setting the S_VERITY flag in the VFS inode.
62 *
63 * i_rwsem is held for write, but it may have been dropped between
64 * ->begin_enable_verity() and ->end_enable_verity().
65 *
66 * Return: 0 on success, -errno on failure
67 */
68 int (*end_enable_verity)(struct file *filp, const void *desc,
69 size_t desc_size, u64 merkle_tree_size);
70
71 /**
72 * Get the verity descriptor of the given inode.
73 *
74 * @inode: an inode with the S_VERITY flag set
75 * @buf: buffer in which to place the verity descriptor
76 * @bufsize: size of @buf, or 0 to retrieve the size only
77 *
78 * If bufsize == 0, then the size of the verity descriptor is returned.
79 * Otherwise the verity descriptor is written to 'buf' and its actual
80 * size is returned; -ERANGE is returned if it's too large. This may be
81 * called by multiple processes concurrently on the same inode.
82 *
83 * Return: the size on success, -errno on failure
84 */
85 int (*get_verity_descriptor)(struct inode *inode, void *buf,
86 size_t bufsize);
87
88 /**
89 * Read a Merkle tree page of the given inode.
90 *
91 * @inode: the inode
92 * @index: 0-based index of the page within the Merkle tree
93 *
94 * This can be called at any time on an open verity file. It may be
95 * called by multiple processes concurrently, even with the same page.
96 *
97 * Note that this must retrieve a *page*, not necessarily a *block*.
98 *
99 * Return: the page on success, ERR_PTR() on failure
100 */
101 struct page *(*read_merkle_tree_page)(struct inode *inode,
102 pgoff_t index);
103
104 /**
105 * Perform readahead of a Merkle tree for the given inode.
106 *
107 * @inode: the inode
108 * @index: 0-based index of the first page within the Merkle tree
109 * @nr_pages: number of pages to be read ahead.
110 *
111 * This can be called at any time on an open verity file. It may be
112 * called by multiple processes concurrently, even with the same range.
113 *
114 * Optional method so that ->read_merkle_tree_page preferably finds
115 * cached data instead of issuing dependent I/O.
116 */
117 void (*readahead_merkle_tree)(struct inode *inode, pgoff_t index,
118 unsigned long nr_pages);
119
120 /**
121 * Write a Merkle tree block to the given file.
122 *
123 * @file: the file for which the Merkle tree is being built
124 * @buf: the Merkle tree block to write
125 * @pos: the position of the block in the Merkle tree (in bytes)
126 * @size: the Merkle tree block size (in bytes)
127 *
128 * This is only called between ->begin_enable_verity() and
129 * ->end_enable_verity().
130 *
131 * Return: 0 on success, -errno on failure
132 */
133 int (*write_merkle_tree_block)(struct file *file, const void *buf,
134 u64 pos, unsigned int size);
135 };
136
137 #ifdef CONFIG_FS_VERITY
138 /**
139 * fsverity_active() - do reads from the inode need to go through fs-verity?
140 * @inode: inode to check
141 *
142 * This checks whether the inode's verity info has been set, and reads need
143 * to verify the file data.
144 *
145 * Return: true if reads need to go through fs-verity, otherwise false
146 */
fsverity_active(const struct inode * inode)147 static inline bool fsverity_active(const struct inode *inode)
148 {
149 if (IS_VERITY(inode)) {
150 /*
151 * This pairs with the try_cmpxchg in set_mask_bits()
152 * used to set the S_VERITY bit in i_flags.
153 */
154 smp_mb();
155 return true;
156 }
157
158 return false;
159 }
160
161 struct fsverity_info *__fsverity_get_info(const struct inode *inode);
162 /**
163 * fsverity_get_info - get fsverity information for an inode
164 * @inode: inode to operate on.
165 *
166 * This gets the fsverity_info for @inode if it exists. Safe to call without
167 * knowin that a fsverity_info exist for @inode, including on file systems that
168 * do not support fsverity.
169 */
fsverity_get_info(const struct inode * inode)170 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
171 {
172 if (!fsverity_active(inode))
173 return NULL;
174 return __fsverity_get_info(inode);
175 }
176
177 /* enable.c */
178
179 int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
180
181 /* measure.c */
182
183 int fsverity_ioctl_measure(struct file *filp, void __user *arg);
184 int fsverity_get_digest(struct inode *inode,
185 u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
186 u8 *alg, enum hash_algo *halg);
187
188 /* open.c */
189
190 int __fsverity_file_open(struct inode *inode, struct file *filp);
191
192 /* read_metadata.c */
193
194 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
195
196 /* verify.c */
197
198 void fsverity_readahead(struct fsverity_info *vi, pgoff_t index,
199 unsigned long nr_pages);
200 bool fsverity_verify_blocks(struct fsverity_info *vi, struct folio *folio,
201 size_t len, size_t offset);
202 void fsverity_verify_bio(struct fsverity_info *vi, struct bio *bio);
203 void fsverity_enqueue_verify_work(struct work_struct *work);
204
205 #else /* !CONFIG_FS_VERITY */
206
fsverity_active(const struct inode * inode)207 static inline bool fsverity_active(const struct inode *inode)
208 {
209 return false;
210 }
211
fsverity_get_info(const struct inode * inode)212 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
213 {
214 return NULL;
215 }
216
217 /* enable.c */
218
fsverity_ioctl_enable(struct file * filp,const void __user * arg)219 static inline int fsverity_ioctl_enable(struct file *filp,
220 const void __user *arg)
221 {
222 return -EOPNOTSUPP;
223 }
224
225 /* measure.c */
226
fsverity_ioctl_measure(struct file * filp,void __user * arg)227 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
228 {
229 return -EOPNOTSUPP;
230 }
231
fsverity_get_digest(struct inode * inode,u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],u8 * alg,enum hash_algo * halg)232 static inline int fsverity_get_digest(struct inode *inode,
233 u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
234 u8 *alg, enum hash_algo *halg)
235 {
236 /*
237 * fsverity is not enabled in the kernel configuration, so always report
238 * that the file doesn't have fsverity enabled (digest size 0).
239 */
240 return 0;
241 }
242
243 /* open.c */
244
__fsverity_file_open(struct inode * inode,struct file * filp)245 static inline int __fsverity_file_open(struct inode *inode, struct file *filp)
246 {
247 return -EOPNOTSUPP;
248 }
249
250 /* read_metadata.c */
251
fsverity_ioctl_read_metadata(struct file * filp,const void __user * uarg)252 static inline int fsverity_ioctl_read_metadata(struct file *filp,
253 const void __user *uarg)
254 {
255 return -EOPNOTSUPP;
256 }
257
258 /* verify.c */
259
fsverity_readahead(struct fsverity_info * vi,pgoff_t index,unsigned long nr_pages)260 static inline void fsverity_readahead(struct fsverity_info *vi, pgoff_t index,
261 unsigned long nr_pages)
262 {
263 }
264
fsverity_verify_blocks(struct fsverity_info * vi,struct folio * folio,size_t len,size_t offset)265 static inline bool fsverity_verify_blocks(struct fsverity_info *vi,
266 struct folio *folio, size_t len,
267 size_t offset)
268 {
269 WARN_ON_ONCE(1);
270 return false;
271 }
272
fsverity_verify_bio(struct fsverity_info * vi,struct bio * bio)273 static inline void fsverity_verify_bio(struct fsverity_info *vi,
274 struct bio *bio)
275 {
276 WARN_ON_ONCE(1);
277 }
278
fsverity_enqueue_verify_work(struct work_struct * work)279 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
280 {
281 WARN_ON_ONCE(1);
282 }
283
284 #endif /* !CONFIG_FS_VERITY */
285
fsverity_verify_folio(struct fsverity_info * vi,struct folio * folio)286 static inline bool fsverity_verify_folio(struct fsverity_info *vi,
287 struct folio *folio)
288 {
289 return fsverity_verify_blocks(vi, folio, folio_size(folio), 0);
290 }
291
292 /**
293 * fsverity_file_open() - prepare to open a verity file
294 * @inode: the inode being opened
295 * @filp: the struct file being set up
296 *
297 * When opening a verity file, deny the open if it is for writing. Otherwise,
298 * set up the inode's verity info if not already done.
299 *
300 * When combined with fscrypt, this must be called after fscrypt_file_open().
301 * Otherwise, we won't have the key set up to decrypt the verity metadata.
302 *
303 * Return: 0 on success, -errno on failure
304 */
fsverity_file_open(struct inode * inode,struct file * filp)305 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
306 {
307 if (IS_VERITY(inode))
308 return __fsverity_file_open(inode, filp);
309 return 0;
310 }
311
312 void fsverity_cleanup_inode(struct inode *inode);
313
314 struct page *generic_read_merkle_tree_page(struct inode *inode, pgoff_t index);
315 void generic_readahead_merkle_tree(struct inode *inode, pgoff_t index,
316 unsigned long nr_pages);
317
318 #endif /* _LINUX_FSVERITY_H */
319