Line data Source code
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 0 : 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 */
|
