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 struct fsverity_info; 30 31 /* Verity operations for filesystems */ 32 struct 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 */ 147 static 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 161 struct 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 */ 170 static 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 179 int fsverity_ioctl_enable(struct file *filp, const void __user *arg); 180 181 /* measure.c */ 182 183 int fsverity_ioctl_measure(struct file *filp, void __user *arg); 184 int 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 190 int __fsverity_file_open(struct inode *inode, struct file *filp); 191 192 /* read_metadata.c */ 193 194 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg); 195 196 /* verify.c */ 197 198 void fsverity_readahead(struct fsverity_info *vi, pgoff_t index, 199 unsigned long nr_pages); 200 bool fsverity_verify_blocks(struct fsverity_info *vi, struct folio *folio, 201 size_t len, size_t offset); 202 void fsverity_verify_bio(struct fsverity_info *vi, struct bio *bio); 203 void fsverity_enqueue_verify_work(struct work_struct *work); 204 void fsverity_fill_zerohash(struct folio *folio, size_t offset, size_t len, 205 struct fsverity_info *vi); 206 207 #else /* !CONFIG_FS_VERITY */ 208 209 static inline bool fsverity_active(const struct inode *inode) 210 { 211 return false; 212 } 213 214 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode) 215 { 216 return NULL; 217 } 218 219 /* enable.c */ 220 221 static inline int fsverity_ioctl_enable(struct file *filp, 222 const void __user *arg) 223 { 224 return -EOPNOTSUPP; 225 } 226 227 /* measure.c */ 228 229 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg) 230 { 231 return -EOPNOTSUPP; 232 } 233 234 static inline int fsverity_get_digest(struct inode *inode, 235 u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE], 236 u8 *alg, enum hash_algo *halg) 237 { 238 /* 239 * fsverity is not enabled in the kernel configuration, so always report 240 * that the file doesn't have fsverity enabled (digest size 0). 241 */ 242 return 0; 243 } 244 245 /* open.c */ 246 247 static inline int __fsverity_file_open(struct inode *inode, struct file *filp) 248 { 249 return -EOPNOTSUPP; 250 } 251 252 /* read_metadata.c */ 253 254 static inline int fsverity_ioctl_read_metadata(struct file *filp, 255 const void __user *uarg) 256 { 257 return -EOPNOTSUPP; 258 } 259 260 /* verify.c */ 261 262 static inline void fsverity_readahead(struct fsverity_info *vi, pgoff_t index, 263 unsigned long nr_pages) 264 { 265 } 266 267 static inline bool fsverity_verify_blocks(struct fsverity_info *vi, 268 struct folio *folio, size_t len, 269 size_t offset) 270 { 271 WARN_ON_ONCE(1); 272 return false; 273 } 274 275 static inline void fsverity_verify_bio(struct fsverity_info *vi, 276 struct bio *bio) 277 { 278 WARN_ON_ONCE(1); 279 } 280 281 static inline void fsverity_enqueue_verify_work(struct work_struct *work) 282 { 283 WARN_ON_ONCE(1); 284 } 285 286 static inline void fsverity_fill_zerohash(struct folio *folio, size_t offset, 287 size_t len, struct fsverity_info *vi) 288 { 289 WARN_ON_ONCE(1); 290 } 291 292 #endif /* !CONFIG_FS_VERITY */ 293 294 static inline bool fsverity_verify_folio(struct fsverity_info *vi, 295 struct folio *folio) 296 { 297 return fsverity_verify_blocks(vi, folio, folio_size(folio), 0); 298 } 299 300 /** 301 * fsverity_file_open() - prepare to open a verity file 302 * @inode: the inode being opened 303 * @filp: the struct file being set up 304 * 305 * When opening a verity file, deny the open if it is for writing. Otherwise, 306 * set up the inode's verity info if not already done. 307 * 308 * When combined with fscrypt, this must be called after fscrypt_file_open(). 309 * Otherwise, we won't have the key set up to decrypt the verity metadata. 310 * 311 * Return: 0 on success, -errno on failure 312 */ 313 static inline int fsverity_file_open(struct inode *inode, struct file *filp) 314 { 315 if (IS_VERITY(inode)) 316 return __fsverity_file_open(inode, filp); 317 return 0; 318 } 319 320 void fsverity_cleanup_inode(struct inode *inode); 321 322 struct page *generic_read_merkle_tree_page(struct inode *inode, pgoff_t index); 323 void generic_readahead_merkle_tree(struct inode *inode, pgoff_t index, 324 unsigned long nr_pages); 325 326 #endif /* _LINUX_FSVERITY_H */ 327