Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 * 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 */
147static 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
161struct 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 */
170static 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
179int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
180
181/* measure.c */
182
183int fsverity_ioctl_measure(struct file *filp, void __user *arg);
184int 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
190int __fsverity_file_open(struct inode *inode, struct file *filp);
191
192/* read_metadata.c */
193
194int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
195
196/* verify.c */
197
198void fsverity_readahead(struct fsverity_info *vi, pgoff_t index,
199 unsigned long nr_pages);
200bool fsverity_verify_blocks(struct fsverity_info *vi, struct folio *folio,
201 size_t len, size_t offset);
202void fsverity_verify_bio(struct fsverity_info *vi, struct bio *bio);
203void fsverity_enqueue_verify_work(struct work_struct *work);
204
205#else /* !CONFIG_FS_VERITY */
206
207static inline bool fsverity_active(const struct inode *inode)
208{
209 return false;
210}
211
212static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
213{
214 return NULL;
215}
216
217/* enable.c */
218
219static inline int fsverity_ioctl_enable(struct file *filp,
220 const void __user *arg)
221{
222 return -EOPNOTSUPP;
223}
224
225/* measure.c */
226
227static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
228{
229 return -EOPNOTSUPP;
230}
231
232static 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
245static inline int __fsverity_file_open(struct inode *inode, struct file *filp)
246{
247 return -EOPNOTSUPP;
248}
249
250/* read_metadata.c */
251
252static inline int fsverity_ioctl_read_metadata(struct file *filp,
253 const void __user *uarg)
254{
255 return -EOPNOTSUPP;
256}
257
258/* verify.c */
259
260static inline void fsverity_readahead(struct fsverity_info *vi, pgoff_t index,
261 unsigned long nr_pages)
262{
263}
264
265static 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
273static inline void fsverity_verify_bio(struct fsverity_info *vi,
274 struct bio *bio)
275{
276 WARN_ON_ONCE(1);
277}
278
279static inline void fsverity_enqueue_verify_work(struct work_struct *work)
280{
281 WARN_ON_ONCE(1);
282}
283
284#endif /* !CONFIG_FS_VERITY */
285
286static 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 */
305static 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
312void fsverity_cleanup_inode(struct inode *inode);
313
314struct page *generic_read_merkle_tree_page(struct inode *inode, pgoff_t index);
315void generic_readahead_merkle_tree(struct inode *inode, pgoff_t index,
316 unsigned long nr_pages);
317
318#endif /* _LINUX_FSVERITY_H */