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