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 digest[FS_VERITY_MAX_DIGEST_SIZE],
147 : enum hash_algo *alg);
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 digest[FS_VERITY_MAX_DIGEST_SIZE],
201 : enum hash_algo *alg)
202 : {
203 : return -EOPNOTSUPP;
204 : }
205 :
206 : /* open.c */
207 :
208 : static inline int __fsverity_file_open(struct inode *inode, struct file *filp)
209 : {
210 : return -EOPNOTSUPP;
211 : }
212 :
213 : static inline int __fsverity_prepare_setattr(struct dentry *dentry,
214 : struct iattr *attr)
215 : {
216 : return -EOPNOTSUPP;
217 : }
218 :
219 : static inline void fsverity_cleanup_inode(struct inode *inode)
220 : {
221 : }
222 :
223 : /* read_metadata.c */
224 :
225 : static inline int fsverity_ioctl_read_metadata(struct file *filp,
226 : const void __user *uarg)
227 : {
228 : return -EOPNOTSUPP;
229 : }
230 :
231 : /* verify.c */
232 :
233 : static inline bool fsverity_verify_blocks(struct folio *folio, size_t len,
234 : size_t offset)
235 : {
236 : WARN_ON(1);
237 : return false;
238 : }
239 :
240 : static inline void fsverity_verify_bio(struct bio *bio)
241 : {
242 : WARN_ON(1);
243 : }
244 :
245 : static inline void fsverity_enqueue_verify_work(struct work_struct *work)
246 : {
247 : WARN_ON(1);
248 : }
249 :
250 : #endif /* !CONFIG_FS_VERITY */
251 :
252 : static inline bool fsverity_verify_folio(struct folio *folio)
253 : {
254 : return fsverity_verify_blocks(folio, folio_size(folio), 0);
255 : }
256 :
257 : static inline bool fsverity_verify_page(struct page *page)
258 : {
259 : return fsverity_verify_blocks(page_folio(page), PAGE_SIZE, 0);
260 : }
261 :
262 : /**
263 : * fsverity_active() - do reads from the inode need to go through fs-verity?
264 : * @inode: inode to check
265 : *
266 : * This checks whether ->i_verity_info has been set.
267 : *
268 : * Filesystems call this from ->readahead() to check whether the pages need to
269 : * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to
270 : * a race condition where the file is being read concurrently with
271 : * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.)
272 : *
273 : * Return: true if reads need to go through fs-verity, otherwise false
274 : */
275 : static inline bool fsverity_active(const struct inode *inode)
276 : {
277 0 : return fsverity_get_info(inode) != NULL;
278 : }
279 :
280 : /**
281 : * fsverity_file_open() - prepare to open a verity file
282 : * @inode: the inode being opened
283 : * @filp: the struct file being set up
284 : *
285 : * When opening a verity file, deny the open if it is for writing. Otherwise,
286 : * set up the inode's ->i_verity_info if not already done.
287 : *
288 : * When combined with fscrypt, this must be called after fscrypt_file_open().
289 : * Otherwise, we won't have the key set up to decrypt the verity metadata.
290 : *
291 : * Return: 0 on success, -errno on failure
292 : */
293 : static inline int fsverity_file_open(struct inode *inode, struct file *filp)
294 : {
295 : if (IS_VERITY(inode))
296 : return __fsverity_file_open(inode, filp);
297 : return 0;
298 : }
299 :
300 : /**
301 : * fsverity_prepare_setattr() - prepare to change a verity inode's attributes
302 : * @dentry: dentry through which the inode is being changed
303 : * @attr: attributes to change
304 : *
305 : * Verity files are immutable, so deny truncates. This isn't covered by the
306 : * open-time check because sys_truncate() takes a path, not a file descriptor.
307 : *
308 : * Return: 0 on success, -errno on failure
309 : */
310 : static inline int fsverity_prepare_setattr(struct dentry *dentry,
311 : struct iattr *attr)
312 : {
313 : if (IS_VERITY(d_inode(dentry)))
314 : return __fsverity_prepare_setattr(dentry, attr);
315 : return 0;
316 : }
317 :
318 : #endif /* _LINUX_FSVERITY_H */
|
