include/linux/fsverity.h

   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         /* pairs with the cmpxchg() in fsverity_set_info() */
 119         return READ_ONCE(inode->i_verity_info);
 120 }
 121
 122 /* enable.c */
 123
 124 extern int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
 125
 126 /* measure.c */
 127
 128 extern int fsverity_ioctl_measure(struct file *filp, void __user *arg);
 129
 130 /* open.c */
 131
 132 extern int fsverity_file_open(struct inode *inode, struct file *filp);
 133 extern int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
 134 extern void fsverity_cleanup_inode(struct inode *inode);
 135
 136 /* verify.c */
 137
 138 extern bool fsverity_verify_page(struct page *page);
 139 extern void fsverity_verify_bio(struct bio *bio);
 140 extern void fsverity_enqueue_verify_work(struct work_struct *work);
 141
 142 #else /* !CONFIG_FS_VERITY */
 143
 144 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
 145 {
 146         return NULL;
 147 }
 148
 149 /* enable.c */
 150
 151 static inline int fsverity_ioctl_enable(struct file *filp,
 152                                         const void __user *arg)
 153 {
 154         return -EOPNOTSUPP;
 155 }
 156
 157 /* measure.c */
 158
 159 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
 160 {
 161         return -EOPNOTSUPP;
 162 }
 163
 164 /* open.c */
 165
 166 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
 167 {
 168         return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
 169 }
 170
 171 static inline int fsverity_prepare_setattr(struct dentry *dentry,
 172                                            struct iattr *attr)
 173 {
 174         return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
 175 }
 176
 177 static inline void fsverity_cleanup_inode(struct inode *inode)
 178 {
 179 }
 180
 181 /* verify.c */
 182
 183 static inline bool fsverity_verify_page(struct page *page)
 184 {
 185         WARN_ON(1);
 186         return false;
 187 }
 188
 189 static inline void fsverity_verify_bio(struct bio *bio)
 190 {
 191         WARN_ON(1);
 192 }
 193
 194 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
 195 {
 196         WARN_ON(1);
 197 }
 198
 199 #endif  /* !CONFIG_FS_VERITY */
 200
 201 /**
 202  * fsverity_active() - do reads from the inode need to go through fs-verity?
 203  *
 204  * This checks whether ->i_verity_info has been set.
 205  *
 206  * Filesystems call this from ->readpages() to check whether the pages need to
 207  * be verified or not.  Don't use IS_VERITY() for this purpose; it's subject to
 208  * a race condition where the file is being read concurrently with
 209  * FS_IOC_ENABLE_VERITY completing.  (S_VERITY is set before ->i_verity_info.)
 210  */
 211 static inline bool fsverity_active(const struct inode *inode)
 212 {
 213         return fsverity_get_info(inode) != NULL;
 214 }
 215
 216 #endif  /* _LINUX_FSVERITY_H */