include/linux/fsverity.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * fs-verity: read-only file-based authenticity protection
0004  *
0005  * This header declares the interface between the fs/verity/ support layer and
0006  * filesystems that support fs-verity.
0007  *
0008  * Copyright 2019 Google LLC
0009  */
0010
0011 #ifndef _LINUX_FSVERITY_H
0012 #define _LINUX_FSVERITY_H
0013
0014 #include <linux/fs.h>
0015 #include <crypto/hash_info.h>
0016 #include <crypto/sha2.h>
0017 #include <uapi/linux/fsverity.h>
0018
0019 /*
0020  * Largest digest size among all hash algorithms supported by fs-verity.
0021  * Currently assumed to be <= size of fsverity_descriptor::root_hash.
0022  */
0023 #define FS_VERITY_MAX_DIGEST_SIZE   SHA512_DIGEST_SIZE
0024
0025 /* Verity operations for filesystems */
0026 struct fsverity_operations {
0027
0028     /**
0029      * Begin enabling verity on the given file.
0030      *
0031      * @filp: a readonly file descriptor for the file
0032      *
0033      * The filesystem must do any needed filesystem-specific preparations
0034      * for enabling verity, e.g. evicting inline data.  It also must return
0035      * -EBUSY if verity is already being enabled on the given file.
0036      *
0037      * i_rwsem is held for write.
0038      *
0039      * Return: 0 on success, -errno on failure
0040      */
0041     int (*begin_enable_verity)(struct file *filp);
0042
0043     /**
0044      * End enabling verity on the given file.
0045      *
0046      * @filp: a readonly file descriptor for the file
0047      * @desc: the verity descriptor to write, or NULL on failure
0048      * @desc_size: size of verity descriptor, or 0 on failure
0049      * @merkle_tree_size: total bytes the Merkle tree took up
0050      *
0051      * If desc == NULL, then enabling verity failed and the filesystem only
0052      * must do any necessary cleanups.  Else, it must also store the given
0053      * verity descriptor to a fs-specific location associated with the inode
0054      * and do any fs-specific actions needed to mark the inode as a verity
0055      * inode, e.g. setting a bit in the on-disk inode.  The filesystem is
0056      * also responsible for setting the S_VERITY flag in the VFS inode.
0057      *
0058      * i_rwsem is held for write, but it may have been dropped between
0059      * ->begin_enable_verity() and ->end_enable_verity().
0060      *
0061      * Return: 0 on success, -errno on failure
0062      */
0063     int (*end_enable_verity)(struct file *filp, const void *desc,
0064                  size_t desc_size, u64 merkle_tree_size);
0065
0066     /**
0067      * Get the verity descriptor of the given inode.
0068      *
0069      * @inode: an inode with the S_VERITY flag set
0070      * @buf: buffer in which to place the verity descriptor
0071      * @bufsize: size of @buf, or 0 to retrieve the size only
0072      *
0073      * If bufsize == 0, then the size of the verity descriptor is returned.
0074      * Otherwise the verity descriptor is written to 'buf' and its actual
0075      * size is returned; -ERANGE is returned if it's too large.  This may be
0076      * called by multiple processes concurrently on the same inode.
0077      *
0078      * Return: the size on success, -errno on failure
0079      */
0080     int (*get_verity_descriptor)(struct inode *inode, void *buf,
0081                      size_t bufsize);
0082
0083     /**
0084      * Read a Merkle tree page of the given inode.
0085      *
0086      * @inode: the inode
0087      * @index: 0-based index of the page within the Merkle tree
0088      * @num_ra_pages: The number of Merkle tree pages that should be
0089      *        prefetched starting at @index if the page at @index
0090      *        isn't already cached.  Implementations may ignore this
0091      *        argument; it's only a performance optimization.
0092      *
0093      * This can be called at any time on an open verity file, as well as
0094      * between ->begin_enable_verity() and ->end_enable_verity().  It may be
0095      * called by multiple processes concurrently, even with the same page.
0096      *
0097      * Note that this must retrieve a *page*, not necessarily a *block*.
0098      *
0099      * Return: the page on success, ERR_PTR() on failure
0100      */
0101     struct page *(*read_merkle_tree_page)(struct inode *inode,
0102                           pgoff_t index,
0103                           unsigned long num_ra_pages);
0104
0105     /**
0106      * Write a Merkle tree block to the given inode.
0107      *
0108      * @inode: the inode for which the Merkle tree is being built
0109      * @buf: block to write
0110      * @index: 0-based index of the block within the Merkle tree
0111      * @log_blocksize: log base 2 of the Merkle tree block size
0112      *
0113      * This is only called between ->begin_enable_verity() and
0114      * ->end_enable_verity().
0115      *
0116      * Return: 0 on success, -errno on failure
0117      */
0118     int (*write_merkle_tree_block)(struct inode *inode, const void *buf,
0119                        u64 index, int log_blocksize);
0120 };
0121
0122 #ifdef CONFIG_FS_VERITY
0123
0124 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
0125 {
0126     /*
0127      * Pairs with the cmpxchg_release() in fsverity_set_info().
0128      * I.e., another task may publish ->i_verity_info concurrently,
0129      * executing a RELEASE barrier.  We need to use smp_load_acquire() here
0130      * to safely ACQUIRE the memory the other task published.
0131      */
0132     return smp_load_acquire(&inode->i_verity_info);
0133 }
0134
0135 /* enable.c */
0136
0137 int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
0138
0139 /* measure.c */
0140
0141 int fsverity_ioctl_measure(struct file *filp, void __user *arg);
0142 int fsverity_get_digest(struct inode *inode,
0143             u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
0144             enum hash_algo *alg);
0145
0146 /* open.c */
0147
0148 int fsverity_file_open(struct inode *inode, struct file *filp);
0149 int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
0150 void fsverity_cleanup_inode(struct inode *inode);
0151
0152 /* read_metadata.c */
0153
0154 int fsverity_ioctl_read_metadata(struct file *filp, const void __user *uarg);
0155
0156 /* verify.c */
0157
0158 bool fsverity_verify_page(struct page *page);
0159 void fsverity_verify_bio(struct bio *bio);
0160 void fsverity_enqueue_verify_work(struct work_struct *work);
0161
0162 #else /* !CONFIG_FS_VERITY */
0163
0164 static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
0165 {
0166     return NULL;
0167 }
0168
0169 /* enable.c */
0170
0171 static inline int fsverity_ioctl_enable(struct file *filp,
0172                     const void __user *arg)
0173 {
0174     return -EOPNOTSUPP;
0175 }
0176
0177 /* measure.c */
0178
0179 static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
0180 {
0181     return -EOPNOTSUPP;
0182 }
0183
0184 static inline int fsverity_get_digest(struct inode *inode,
0185                       u8 digest[FS_VERITY_MAX_DIGEST_SIZE],
0186                       enum hash_algo *alg)
0187 {
0188     return -EOPNOTSUPP;
0189 }
0190
0191 /* open.c */
0192
0193 static inline int fsverity_file_open(struct inode *inode, struct file *filp)
0194 {
0195     return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
0196 }
0197
0198 static inline int fsverity_prepare_setattr(struct dentry *dentry,
0199                        struct iattr *attr)
0200 {
0201     return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
0202 }
0203
0204 static inline void fsverity_cleanup_inode(struct inode *inode)
0205 {
0206 }
0207
0208 /* read_metadata.c */
0209
0210 static inline int fsverity_ioctl_read_metadata(struct file *filp,
0211                            const void __user *uarg)
0212 {
0213     return -EOPNOTSUPP;
0214 }
0215
0216 /* verify.c */
0217
0218 static inline bool fsverity_verify_page(struct page *page)
0219 {
0220     WARN_ON(1);
0221     return false;
0222 }
0223
0224 static inline void fsverity_verify_bio(struct bio *bio)
0225 {
0226     WARN_ON(1);
0227 }
0228
0229 static inline void fsverity_enqueue_verify_work(struct work_struct *work)
0230 {
0231     WARN_ON(1);
0232 }
0233
0234 #endif  /* !CONFIG_FS_VERITY */
0235
0236 /**
0237  * fsverity_active() - do reads from the inode need to go through fs-verity?
0238  * @inode: inode to check
0239  *
0240  * This checks whether ->i_verity_info has been set.
0241  *
0242  * Filesystems call this from ->readahead() to check whether the pages need to
0243  * be verified or not.  Don't use IS_VERITY() for this purpose; it's subject to
0244  * a race condition where the file is being read concurrently with
0245  * FS_IOC_ENABLE_VERITY completing.  (S_VERITY is set before ->i_verity_info.)
0246  *
0247  * Return: true if reads need to go through fs-verity, otherwise false
0248  */
0249 static inline bool fsverity_active(const struct inode *inode)
0250 {
0251     return fsverity_get_info(inode) != NULL;
0252 }
0253
0254 #endif  /* _LINUX_FSVERITY_H */