Branch data     Line data    Source code

       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                 :            :          *
      81                 :            :          * This can be called at any time on an open verity file, as well as
      82                 :            :          * between ->begin_enable_verity() and ->end_enable_verity().  It may be
      83                 :            :          * called by multiple processes concurrently, even with the same page.
      84                 :            :          *
      85                 :            :          * Note that this must retrieve a *page*, not necessarily a *block*.
      86                 :            :          *
      87                 :            :          * Return: the page on success, ERR_PTR() on failure
      88                 :            :          */
      89                 :            :         struct page *(*read_merkle_tree_page)(struct inode *inode,
      90                 :            :                                               pgoff_t index);
      91                 :            : 
      92                 :            :         /**
      93                 :            :          * Write a Merkle tree block to the given inode.
      94                 :            :          *
      95                 :            :          * @inode: the inode for which the Merkle tree is being built
      96                 :            :          * @buf: block to write
      97                 :            :          * @index: 0-based index of the block within the Merkle tree
      98                 :            :          * @log_blocksize: log base 2 of the Merkle tree block size
      99                 :            :          *
     100                 :            :          * This is only called between ->begin_enable_verity() and
     101                 :            :          * ->end_enable_verity().
     102                 :            :          *
     103                 :            :          * Return: 0 on success, -errno on failure
     104                 :            :          */
     105                 :            :         int (*write_merkle_tree_block)(struct inode *inode, const void *buf,
     106                 :            :                                        u64 index, int log_blocksize);
     107                 :            : };
     108                 :            : 
     109                 :            : #ifdef CONFIG_FS_VERITY
     110                 :            : 
     111                 :            : static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
     112                 :            : {
     113                 :            :         /* pairs with the cmpxchg() in fsverity_set_info() */
     114                 :            :         return READ_ONCE(inode->i_verity_info);
     115                 :            : }
     116                 :            : 
     117                 :            : /* enable.c */
     118                 :            : 
     119                 :            : extern int fsverity_ioctl_enable(struct file *filp, const void __user *arg);
     120                 :            : 
     121                 :            : /* measure.c */
     122                 :            : 
     123                 :            : extern int fsverity_ioctl_measure(struct file *filp, void __user *arg);
     124                 :            : 
     125                 :            : /* open.c */
     126                 :            : 
     127                 :            : extern int fsverity_file_open(struct inode *inode, struct file *filp);
     128                 :            : extern int fsverity_prepare_setattr(struct dentry *dentry, struct iattr *attr);
     129                 :            : extern void fsverity_cleanup_inode(struct inode *inode);
     130                 :            : 
     131                 :            : /* verify.c */
     132                 :            : 
     133                 :            : extern bool fsverity_verify_page(struct page *page);
     134                 :            : extern void fsverity_verify_bio(struct bio *bio);
     135                 :            : extern void fsverity_enqueue_verify_work(struct work_struct *work);
     136                 :            : 
     137                 :            : #else /* !CONFIG_FS_VERITY */
     138                 :            : 
     139                 :            : static inline struct fsverity_info *fsverity_get_info(const struct inode *inode)
     140                 :            : {
     141                 :            :         return NULL;
     142                 :            : }
     143                 :            : 
     144                 :            : /* enable.c */
     145                 :            : 
     146                 :            : static inline int fsverity_ioctl_enable(struct file *filp,
     147                 :            :                                         const void __user *arg)
     148                 :            : {
     149                 :            :         return -EOPNOTSUPP;
     150                 :            : }
     151                 :            : 
     152                 :            : /* measure.c */
     153                 :            : 
     154                 :            : static inline int fsverity_ioctl_measure(struct file *filp, void __user *arg)
     155                 :            : {
     156                 :            :         return -EOPNOTSUPP;
     157                 :            : }
     158                 :            : 
     159                 :            : /* open.c */
     160                 :            : 
     161                 :            : static inline int fsverity_file_open(struct inode *inode, struct file *filp)
     162                 :            : {
     163                 :          3 :         return IS_VERITY(inode) ? -EOPNOTSUPP : 0;
     164                 :            : }
     165                 :            : 
     166                 :            : static inline int fsverity_prepare_setattr(struct dentry *dentry,
     167                 :            :                                            struct iattr *attr)
     168                 :            : {
     169                 :          3 :         return IS_VERITY(d_inode(dentry)) ? -EOPNOTSUPP : 0;
     170                 :            : }
     171                 :            : 
     172                 :            : static inline void fsverity_cleanup_inode(struct inode *inode)
     173                 :            : {
     174                 :            : }
     175                 :            : 
     176                 :            : /* verify.c */
     177                 :            : 
     178                 :            : static inline bool fsverity_verify_page(struct page *page)
     179                 :            : {
     180                 :            :         WARN_ON(1);
     181                 :            :         return false;
     182                 :            : }
     183                 :            : 
     184                 :            : static inline void fsverity_verify_bio(struct bio *bio)
     185                 :            : {
     186                 :          0 :         WARN_ON(1);
     187                 :            : }
     188                 :            : 
     189                 :            : static inline void fsverity_enqueue_verify_work(struct work_struct *work)
     190                 :            : {
     191                 :          0 :         WARN_ON(1);
     192                 :            : }
     193                 :            : 
     194                 :            : #endif  /* !CONFIG_FS_VERITY */
     195                 :            : 
     196                 :            : /**
     197                 :            :  * fsverity_active() - do reads from the inode need to go through fs-verity?
     198                 :            :  *
     199                 :            :  * This checks whether ->i_verity_info has been set.
     200                 :            :  *
     201                 :            :  * Filesystems call this from ->readpages() to check whether the pages need to
     202                 :            :  * be verified or not.  Don't use IS_VERITY() for this purpose; it's subject to
     203                 :            :  * a race condition where the file is being read concurrently with
     204                 :            :  * FS_IOC_ENABLE_VERITY completing.  (S_VERITY is set before ->i_verity_info.)
     205                 :            :  */
     206                 :            : static inline bool fsverity_active(const struct inode *inode)
     207                 :            : {
     208                 :            :         return fsverity_get_info(inode) != NULL;
     209                 :            : }
     210                 :            : 
     211                 :            : #endif  /* _LINUX_FSVERITY_H */