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 <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 */