Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
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 <crypto/hash_info.h>
16#include <crypto/sha2.h>
17#include <uapi/linux/fsverity.h>
18
19/*
20 * Largest digest size among all hash algorithms supported by fs-verity.
21 * Currently assumed to be <= size of fsverity_descriptor::root_hash.
22 */
23#define FS_VERITY_MAX_DIGEST_SIZE SHA512_DIGEST_SIZE
24
25/* Arbitrary limit to bound the kmalloc() size. Can be changed. */
26#define FS_VERITY_MAX_DESCRIPTOR_SIZE 16384
27
28/* Verity operations for filesystems */
29struct fsverity_operations {
30
31 /**
32 * Begin enabling verity on the given file.
33 *
34 * @filp: a readonly file descriptor for the file
35 *
36 * The filesystem must do any needed filesystem-specific preparations
37 * for enabling verity, e.g. evicting inline data. It also must return
38 * -EBUSY if verity is already being enabled on the given file.
39 *
40 * i_rwsem is held for write.
41 *
42 * Return: 0 on success, -errno on failure
43 */
44 int (*begin_enable_verity)(struct file *filp);
45
46 /**
47 * End enabling verity on the given file.
48 *
49 * @filp: a readonly file descriptor for the file
50 * @desc: the verity descriptor to write, or NULL on failure
51 * @desc_size: size of verity descriptor, or 0 on failure
52 * @merkle_tree_size: total bytes the Merkle tree took up
53 *
54 * If desc == NULL, then enabling verity failed and the filesystem only
55 * must do any necessary cleanups. Else, it must also store the given
56 * verity descriptor to a fs-specific location associated with the inode
57 * and do any fs-specific actions needed to mark the inode as a verity
58 * inode, e.g. setting a bit in the on-disk inode. The filesystem is
59 * also responsible for setting the S_VERITY flag in the VFS inode.
60 *
61 * i_rwsem is held for write, but it may have been dropped between
62 * ->begin_enable_verity() and ->end_enable_verity().
63 *
64 * Return: 0 on success, -errno on failure
65 */
66 int (*end_enable_verity)(struct file *filp, const void *desc,
67 size_t desc_size, u64 merkle_tree_size);
68
69 /**
70 * Get the verity descriptor of the given inode.
71 *
72 * @inode: an inode with the S_VERITY flag set
73 * @buf: buffer in which to place the verity descriptor
74 * @bufsize: size of @buf, or 0 to retrieve the size only
75 *
76 * If bufsize == 0, then the size of the verity descriptor is returned.
77 * Otherwise the verity descriptor is written to 'buf' and its actual
78 * size is returned; -ERANGE is returned if it's too large. This may be
79 * called by multiple processes concurrently on the same inode.
80 *
81 * Return: the size on success, -errno on failure
82 */
83 int (*get_verity_descriptor)(struct inode *inode, void *buf,
84 size_t bufsize);
85
86 /**
87 * Read a Merkle tree page of the given inode.
88 *
89 * @inode: the inode
90 * @index: 0-based index of the page within the Merkle tree
91 * @num_ra_pages: The number of Merkle tree pages that should be
92 * prefetched starting at @index if the page at @index
93 * isn't already cached. Implementations may ignore this
94 * argument; it's only a performance optimization.
95 *
96 * This can be called at any time on an open verity file, as well as
97 * between ->begin_enable_verity() and ->end_enable_verity(). 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: block to write
113 * @index: 0-based index of the block within the Merkle tree
114 * @log_blocksize: log base 2 of the Merkle tree block size
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 index, int log_blocksize);
123};
124
125#ifdef CONFIG_FS_VERITY
126
127static 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
140int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
141
142/* measure.c */
143
144int fsverity_ioctl_measure(struct file *filp, void __user *arg);
145int fsverity_get_digest(struct inode *inode,
146 u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
147 enum hash_algo *alg);
148
149/* open.c */
150
151int fsverity_file_open(struct inode *inode, struct file *filp);
152int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
153void fsverity_cleanup_inode(struct inode *inode);
154
155/* read_metadata.c */
156
157int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
158
159/* verify.c */
160
161bool fsverity_verify_page(struct page *page);
162void fsverity_verify_bio(struct bio *bio);
163void fsverity_enqueue_verify_work(struct work_struct *work);
164
165#else /* !CONFIG_FS_VERITY */
166
167static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
168{
169 return NULL;
170}
171
172/* enable.c */
173
174static inline int fsverity_ioctl_enable(struct file *filp,
175 const void __user *arg)
176{
177 return -EOPNOTSUPP;
178}
179
180/* measure.c */
181
182static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
183{
184 return -EOPNOTSUPP;
185}
186
187static inline int fsverity_get_digest(struct inode *inode,
188 u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
189 enum hash_algo *alg)
190{
191 return -EOPNOTSUPP;
192}
193
194/* open.c */
195
196static inline int fsverity_file_open(struct inode *inode, struct file *filp)
197{
198 return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
199}
200
201static inline int fsverity_prepare_setattr(struct dentry *dentry,
202 struct iattr *attr)
203{
204 return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
205}
206
207static inline void fsverity_cleanup_inode(struct inode *inode)
208{
209}
210
211/* read_metadata.c */
212
213static inline int fsverity_ioctl_read_metadata(struct file *filp,
214 const void __user *uarg)
215{
216 return -EOPNOTSUPP;
217}
218
219/* verify.c */
220
221static inline bool fsverity_verify_page(struct page *page)
222{
223 WARN_ON(1);
224 return false;
225}
226
227static inline void fsverity_verify_bio(struct bio *bio)
228{
229 WARN_ON(1);
230}
231
232static inline void fsverity_enqueue_verify_work(struct work_struct *work)
233{
234 WARN_ON(1);
235}
236
237#endif /* !CONFIG_FS_VERITY */
238
239/**
240 * fsverity_active() - do reads from the inode need to go through fs-verity?
241 * @inode: inode to check
242 *
243 * This checks whether ->i_verity_info has been set.
244 *
245 * Filesystems call this from ->readahead() to check whether the pages need to
246 * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to
247 * a race condition where the file is being read concurrently with
248 * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.)
249 *
250 * Return: true if reads need to go through fs-verity, otherwise false
251 */
252static inline bool fsverity_active(const struct inode *inode)
253{
254 return fsverity_get_info(inode) != NULL;
255}
256
257#endif /* _LINUX_FSVERITY_H */