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 <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 /* Verity operations for filesystems */
  30 struct fsverity_operations {
  31
  32         /**
  33          * Begin enabling verity on the given file.
  34          *
  35          * @filp: a readonly file descriptor for the file
  36          *
  37          * The filesystem must do any needed filesystem-specific preparations
  38          * for enabling verity, e.g. evicting inline data.  It also must return
  39          * -EBUSY if verity is already being enabled on the given file.
  40          *
  41          * i_rwsem is held for write.
  42          *
  43          * Return: 0 on success, -errno on failure
  44          */
  45         int (*begin_enable_verity)(struct file *filp);
  46
  47         /**
  48          * End enabling verity on the given file.
  49          *
  50          * @filp: a readonly file descriptor for the file
  51          * @desc: the verity descriptor to write, or NULL on failure
  52          * @desc_size: size of verity descriptor, or 0 on failure
  53          * @merkle_tree_size: total bytes the Merkle tree took up
  54          *
  55          * If desc == NULL, then enabling verity failed and the filesystem only
  56          * must do any necessary cleanups.  Else, it must also store the given
  57          * verity descriptor to a fs-specific location associated with the inode
  58          * and do any fs-specific actions needed to mark the inode as a verity
  59          * inode, e.g. setting a bit in the on-disk inode.  The filesystem is
  60          * also responsible for setting the S_VERITY flag in the VFS inode.
  61          *
  62          * i_rwsem is held for write, but it may have been dropped between
  63          * ->begin_enable_verity() and ->end_enable_verity().
  64          *
  65          * Return: 0 on success, -errno on failure
  66          */
  67         int (*end_enable_verity)(struct file *filp, const void *desc,
  68                                  size_t desc_size, u64 merkle_tree_size);
  69
  70         /**
  71          * Get the verity descriptor of the given inode.
  72          *
  73          * @inode: an inode with the S_VERITY flag set
  74          * @buf: buffer in which to place the verity descriptor
  75          * @bufsize: size of @buf, or 0 to retrieve the size only
  76          *
  77          * If bufsize == 0, then the size of the verity descriptor is returned.
  78          * Otherwise the verity descriptor is written to 'buf' and its actual
  79          * size is returned; -ERANGE is returned if it's too large.  This may be
  80          * called by multiple processes concurrently on the same inode.
  81          *
  82          * Return: the size on success, -errno on failure
  83          */
  84         int (*get_verity_descriptor)(struct inode *inode, void *buf,
  85                                      size_t bufsize);
  86
  87         /**
  88          * Read a Merkle tree page of the given inode.
  89          *
  90          * @inode: the inode
  91          * @index: 0-based index of the page within the Merkle tree
  92          * @num_ra_pages: The number of Merkle tree pages that should be
  93          *                prefetched starting at @index if the page at @index
  94          *                isn't already cached.  Implementations may ignore this
  95          *                argument; it's only a performance optimization.
  96          *
  97          * This can be called at any time on an open verity file.  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: the Merkle tree block to write
 113          * @pos: the position of the block in the Merkle tree (in bytes)
 114          * @size: the Merkle tree block size (in bytes)
 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 pos, unsigned int size);
 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 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
 147                         u8 *alg, enum hash_algo *halg);
 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 /**
 156  * fsverity_cleanup_inode() - free the inode's verity info, if present
 157  * @inode: an inode being evicted
 158  *
 159  * Filesystems must call this on inode eviction to free ->i_verity_info.
 160  */
 161 static inline void fsverity_cleanup_inode(struct inode *inode)
 162 {
 163         if (inode->i_verity_info)
 164                 __fsverity_cleanup_inode(inode);
 165 }
 166
 167 /* read_metadata.c */
 168
 169 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
 170
 171 /* verify.c */
 172
 173 bool fsverity_verify_blocks(struct folio *folio, size_t len, size_t offset);
 174 void fsverity_verify_bio(struct bio *bio);
 175 void fsverity_enqueue_verify_work(struct work_struct *work);
 176
 177 #else /* !CONFIG_FS_VERITY */
 178
 179 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
 180 {
 181         return NULL;
 182 }
 183
 184 /* enable.c */
 185
 186 static inline int fsverity_ioctl_enable(struct file *filp,
 187                                         const void __user *arg)
 188 {
 189         return -EOPNOTSUPP;
 190 }
 191
 192 /* measure.c */
 193
 194 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
 195 {
 196         return -EOPNOTSUPP;
 197 }
 198
 199 static inline int fsverity_get_digest(struct inode *inode,
 200                                       u8 raw_digest[FS_VERITY_MAX_DIGEST_SIZE],
 201                                       u8 *alg, enum hash_algo *halg)
 202 {
 203         /*
 204          * fsverity is not enabled in the kernel configuration, so always report
 205          * that the file doesn't have fsverity enabled (digest size 0).
 206          */
 207         return 0;
 208 }
 209
 210 /* open.c */
 211
 212 static inline int __fsverity_file_open(struct inode *inode, struct file *filp)
 213 {
 214         return -EOPNOTSUPP;
 215 }
 216
 217 static inline int __fsverity_prepare_setattr(struct dentry *dentry,
 218                                              struct iattr *attr)
 219 {
 220         return -EOPNOTSUPP;
 221 }
 222
 223 static inline void fsverity_cleanup_inode(struct inode *inode)
 224 {
 225 }
 226
 227 /* read_metadata.c */
 228
 229 static inline int fsverity_ioctl_read_metadata(struct file *filp,
 230                                                const void __user *uarg)
 231 {
 232         return -EOPNOTSUPP;
 233 }
 234
 235 /* verify.c */
 236
 237 static inline bool fsverity_verify_blocks(struct folio *folio, size_t len,
 238                                           size_t offset)
 239 {
 240         WARN_ON_ONCE(1);
 241         return false;
 242 }
 243
 244 static inline void fsverity_verify_bio(struct bio *bio)
 245 {
 246         WARN_ON_ONCE(1);
 247 }
 248
 249 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
 250 {
 251         WARN_ON_ONCE(1);
 252 }
 253
 254 #endif  /* !CONFIG_FS_VERITY */
 255
 256 static inline bool fsverity_verify_folio(struct folio *folio)
 257 {
 258         return fsverity_verify_blocks(folio, folio_size(folio), 0);
 259 }
 260
 261 static inline bool fsverity_verify_page(struct page *page)
 262 {
 263         return fsverity_verify_blocks(page_folio(page), PAGE_SIZE, 0);
 264 }
 265
 266 /**
 267  * fsverity_active() - do reads from the inode need to go through fs-verity?
 268  * @inode: inode to check
 269  *
 270  * This checks whether ->i_verity_info has been set.
 271  *
 272  * Filesystems call this from ->readahead() to check whether the pages need to
 273  * be verified or not.  Don't use IS_VERITY() for this purpose; it's subject to
 274  * a race condition where the file is being read concurrently with
 275  * FS_IOC_ENABLE_VERITY completing.  (S_VERITY is set before ->i_verity_info.)
 276  *
 277  * Return: true if reads need to go through fs-verity, otherwise false
 278  */
 279 static inline bool fsverity_active(const struct inode *inode)
 280 {
 281         return fsverity_get_info(inode) != NULL;
 282 }
 283
 284 /**
 285  * fsverity_file_open() - prepare to open a verity file
 286  * @inode: the inode being opened
 287  * @filp: the struct file being set up
 288  *
 289  * When opening a verity file, deny the open if it is for writing.  Otherwise,
 290  * set up the inode's ->i_verity_info if not already done.
 291  *
 292  * When combined with fscrypt, this must be called after fscrypt_file_open().
 293  * Otherwise, we won't have the key set up to decrypt the verity metadata.
 294  *
 295  * Return: 0 on success, -errno on failure
 296  */
 297 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
 298 {
 299         if (IS_VERITY(inode))
 300                 return __fsverity_file_open(inode, filp);
 301         return 0;
 302 }
 303
 304 /**
 305  * fsverity_prepare_setattr() - prepare to change a verity inode's attributes
 306  * @dentry: dentry through which the inode is being changed
 307  * @attr: attributes to change
 308  *
 309  * Verity files are immutable, so deny truncates.  This isn't covered by the
 310  * open-time check because sys_truncate() takes a path, not a file descriptor.
 311  *
 312  * Return: 0 on success, -errno on failure
 313  */
 314 static inline int fsverity_prepare_setattr(struct dentry *dentry,
 315                                            struct iattr *attr)
 316 {
 317         if (IS_VERITY(d_inode(dentry)))
 318                 return __fsverity_prepare_setattr(dentry, attr);
 319         return 0;
 320 }
 321
 322 #endif  /* _LINUX_FSVERITY_H */