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 <uapi/linux/fsverity.h> 16 17 /* Verity operations for filesystems */ 18 struct fsverity_operations { 19 20 /** 21 * Begin enabling verity on the given file. 22 * 23 * @filp: a readonly file descriptor for the file 24 * 25 * The filesystem must do any needed filesystem-specific preparations 26 * for enabling verity, e.g. evicting inline data. It also must return 27 * -EBUSY if verity is already being enabled on the given file. 28 * 29 * i_rwsem is held for write. 30 * 31 * Return: 0 on success, -errno on failure 32 */ 33 int (*begin_enable_verity)(struct file *filp); 34 35 /** 36 * End enabling verity on the given file. 37 * 38 * @filp: a readonly file descriptor for the file 39 * @desc: the verity descriptor to write, or NULL on failure 40 * @desc_size: size of verity descriptor, or 0 on failure 41 * @merkle_tree_size: total bytes the Merkle tree took up 42 * 43 * If desc == NULL, then enabling verity failed and the filesystem only 44 * must do any necessary cleanups. Else, it must also store the given 45 * verity descriptor to a fs-specific location associated with the inode 46 * and do any fs-specific actions needed to mark the inode as a verity 47 * inode, e.g. setting a bit in the on-disk inode. The filesystem is 48 * also responsible for setting the S_VERITY flag in the VFS inode. 49 * 50 * i_rwsem is held for write, but it may have been dropped between 51 * ->begin_enable_verity() and ->end_enable_verity(). 52 * 53 * Return: 0 on success, -errno on failure 54 */ 55 int (*end_enable_verity)(struct file *filp, const void *desc, 56 size_t desc_size, u64 merkle_tree_size); 57 58 /** 59 * Get the verity descriptor of the given inode. 60 * 61 * @inode: an inode with the S_VERITY flag set 62 * @buf: buffer in which to place the verity descriptor 63 * @bufsize: size of @buf, or 0 to retrieve the size only 64 * 65 * If bufsize == 0, then the size of the verity descriptor is returned. 66 * Otherwise the verity descriptor is written to 'buf' and its actual 67 * size is returned; -ERANGE is returned if it's too large. This may be 68 * called by multiple processes concurrently on the same inode. 69 * 70 * Return: the size on success, -errno on failure 71 */ 72 int (*get_verity_descriptor)(struct inode *inode, void *buf, 73 size_t bufsize); 74 75 /** 76 * Read a Merkle tree page of the given inode. 77 * 78 * @inode: the inode 79 * @index: 0-based index of the page within the Merkle tree 80 * @num_ra_pages: The number of Merkle tree pages that should be 81 * prefetched starting at @index if the page at @index 82 * isn't already cached. Implementations may ignore this 83 * argument; it's only a performance optimization. 84 * 85 * This can be called at any time on an open verity file, as well as 86 * between ->begin_enable_verity() and ->end_enable_verity(). It may be 87 * called by multiple processes concurrently, even with the same page. 88 * 89 * Note that this must retrieve a *page*, not necessarily a *block*. 90 * 91 * Return: the page on success, ERR_PTR() on failure 92 */ 93 struct page *(*read_merkle_tree_page)(struct inode *inode, 94 pgoff_t index, 95 unsigned long num_ra_pages); 96 97 /** 98 * Write a Merkle tree block to the given inode. 99 * 100 * @inode: the inode for which the Merkle tree is being built 101 * @buf: block to write 102 * @index: 0-based index of the block within the Merkle tree 103 * @log_blocksize: log base 2 of the Merkle tree block size 104 * 105 * This is only called between ->begin_enable_verity() and 106 * ->end_enable_verity(). 107 * 108 * Return: 0 on success, -errno on failure 109 */ 110 int (*write_merkle_tree_block)(struct inode *inode, const void *buf, 111 u64 index, int log_blocksize); 112 }; 113 114 #ifdef CONFIG_FS_VERITY 115 116 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode) 117 { 118 /* 119 * Pairs with the cmpxchg_release() in fsverity_set_info(). 120 * I.e., another task may publish ->i_verity_info concurrently, 121 * executing a RELEASE barrier. We need to use smp_load_acquire() here 122 * to safely ACQUIRE the memory the other task published. 123 */ 124 return smp_load_acquire(&inode->i_verity_info); 125 } 126 127 /* enable.c */ 128 129 int fsverity_ioctl_enable(struct file *filp, const void __user *arg); 130 131 /* measure.c */ 132 133 int fsverity_ioctl_measure(struct file *filp, void __user *arg); 134 135 /* open.c */ 136 137 int fsverity_file_open(struct inode *inode, struct file *filp); 138 int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr); 139 void fsverity_cleanup_inode(struct inode *inode); 140 141 /* read_metadata.c */ 142 143 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg); 144 145 /* verify.c */ 146 147 bool fsverity_verify_page(struct page *page); 148 void fsverity_verify_bio(struct bio *bio); 149 void fsverity_enqueue_verify_work(struct work_struct *work); 150 151 #else /* !CONFIG_FS_VERITY */ 152 153 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode) 154 { 155 return NULL; 156 } 157 158 /* enable.c */ 159 160 static inline int fsverity_ioctl_enable(struct file *filp, 161 const void __user *arg) 162 { 163 return -EOPNOTSUPP; 164 } 165 166 /* measure.c */ 167 168 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg) 169 { 170 return -EOPNOTSUPP; 171 } 172 173 /* open.c */ 174 175 static inline int fsverity_file_open(struct inode *inode, struct file *filp) 176 { 177 return IS_VERITY(inode) ? -EOPNOTSUPP : 0; 178 } 179 180 static inline int fsverity_prepare_setattr(struct dentry *dentry, 181 struct iattr *attr) 182 { 183 return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0; 184 } 185 186 static inline void fsverity_cleanup_inode(struct inode *inode) 187 { 188 } 189 190 /* read_metadata.c */ 191 192 static inline int fsverity_ioctl_read_metadata(struct file *filp, 193 const void __user *uarg) 194 { 195 return -EOPNOTSUPP; 196 } 197 198 /* verify.c */ 199 200 static inline bool fsverity_verify_page(struct page *page) 201 { 202 WARN_ON(1); 203 return false; 204 } 205 206 static inline void fsverity_verify_bio(struct bio *bio) 207 { 208 WARN_ON(1); 209 } 210 211 static inline void fsverity_enqueue_verify_work(struct work_struct *work) 212 { 213 WARN_ON(1); 214 } 215 216 #endif /* !CONFIG_FS_VERITY */ 217 218 /** 219 * fsverity_active() - do reads from the inode need to go through fs-verity? 220 * @inode: inode to check 221 * 222 * This checks whether ->i_verity_info has been set. 223 * 224 * Filesystems call this from ->readpages() to check whether the pages need to 225 * be verified or not. Don't use IS_VERITY() for this purpose; it's subject to 226 * a race condition where the file is being read concurrently with 227 * FS_IOC_ENABLE_VERITY completing. (S_VERITY is set before ->i_verity_info.) 228 * 229 * Return: true if reads need to go through fs-verity, otherwise false 230 */ 231 static inline bool fsverity_active(const struct inode *inode) 232 { 233 return fsverity_get_info(inode) != NULL; 234 } 235 236 #endif /* _LINUX_FSVERITY_H */ 237