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, len: folio_size(folio), offset: 0); |
259 | } |
260 | |
261 | static inline bool fsverity_verify_page(struct page *page) |
262 | { |
263 | return fsverity_verify_blocks(page_folio(page), PAGE_SIZE, offset: 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 | |