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