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 */ 29 struct 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 127 static 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 140 int fsverity_ioctl_enable(struct file *filp, const void __user *arg); 141 142 /* measure.c */ 143 144 int fsverity_ioctl_measure(struct file *filp, void __user *arg); 145 int fsverity_get_digest(struct inode *inode, 146 u8 digest[FS_VERITY_MAX_DIGEST_SIZE], 147 enum hash_algo *alg); 148 149 /* open.c */ 150 151 int fsverity_file_open(struct inode *inode, struct file *filp); 152 int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr); 153 void fsverity_cleanup_inode(struct inode *inode); 154 155 /* read_metadata.c */ 156 157 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg); 158 159 /* verify.c */ 160 161 bool fsverity_verify_page(struct page *page); 162 void fsverity_verify_bio(struct bio *bio); 163 void fsverity_enqueue_verify_work(struct work_struct *work); 164 165 #else /* !CONFIG_FS_VERITY */ 166 167 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode) 168 { 169 return NULL; 170 } 171 172 /* enable.c */ 173 174 static inline int fsverity_ioctl_enable(struct file *filp, 175 const void __user *arg) 176 { 177 return -EOPNOTSUPP; 178 } 179 180 /* measure.c */ 181 182 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg) 183 { 184 return -EOPNOTSUPP; 185 } 186 187 static 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 196 static inline int fsverity_file_open(struct inode *inode, struct file *filp) 197 { 198 return IS_VERITY(inode) ? -EOPNOTSUPP : 0; 199 } 200 201 static inline int fsverity_prepare_setattr(struct dentry *dentry, 202 struct iattr *attr) 203 { 204 return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0; 205 } 206 207 static inline void fsverity_cleanup_inode(struct inode *inode) 208 { 209 } 210 211 /* read_metadata.c */ 212 213 static inline int fsverity_ioctl_read_metadata(struct file *filp, 214 const void __user *uarg) 215 { 216 return -EOPNOTSUPP; 217 } 218 219 /* verify.c */ 220 221 static inline bool fsverity_verify_page(struct page *page) 222 { 223 WARN_ON(1); 224 return false; 225 } 226 227 static inline void fsverity_verify_bio(struct bio *bio) 228 { 229 WARN_ON(1); 230 } 231 232 static 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 */ 252 static inline bool fsverity_active(const struct inode *inode) 253 { 254 return fsverity_get_info(inode) != NULL; 255 } 256 257 #endif /* _LINUX_FSVERITY_H */ 258