1 /*-
2 * SPDX-License-Identifier: BSD-3-Clause
3 *
4 * Copyright (c) 2007-2009 Google Inc. and Amit Singh
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are
9 * met:
10 *
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above
14 * copyright notice, this list of conditions and the following disclaimer
15 * in the documentation and/or other materials provided with the
16 * distribution.
17 * * Neither the name of Google Inc. nor the names of its
18 * contributors may be used to endorse or promote products derived from
19 * this software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * Copyright (C) 2005 Csaba Henk.
34 * All rights reserved.
35 *
36 * Copyright (c) 2019 The FreeBSD Foundation
37 *
38 * Portions of this software were developed by BFF Storage Systems, LLC under
39 * sponsorship from the FreeBSD Foundation.
40 *
41 * Redistribution and use in source and binary forms, with or without
42 * modification, are permitted provided that the following conditions
43 * are met:
44 * 1. Redistributions of source code must retain the above copyright
45 * notice, this list of conditions and the following disclaimer.
46 * 2. Redistributions in binary form must reproduce the above copyright
47 * notice, this list of conditions and the following disclaimer in the
48 * documentation and/or other materials provided with the distribution.
49 *
50 * THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
51 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
52 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
53 * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
54 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
55 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
56 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
57 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
58 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
59 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
60 * SUCH DAMAGE.
61 */
62
63 #ifndef _FUSE_FILE_H_
64 #define _FUSE_FILE_H_
65
66 #include <sys/types.h>
67 #include <sys/fcntl.h>
68 #include <sys/stat.h>
69 #include <sys/mman.h>
70 #include <sys/vnode.h>
71
72 /*
73 * The fufh type is the access mode of the fuse file handle. It's the portion
74 * of the open(2) flags related to permission.
75 */
76 typedef enum fufh_type {
77 FUFH_INVALID = -1,
78 FUFH_RDONLY = O_RDONLY,
79 FUFH_WRONLY = O_WRONLY,
80 FUFH_RDWR = O_RDWR,
81 FUFH_EXEC = O_EXEC,
82 } fufh_type_t;
83
84 /*
85 * FUSE File Handles
86 *
87 * The FUSE protocol says that a server may assign a unique 64-bit file handle
88 * every time that a file is opened. Effectively, that's once for each file
89 * descriptor.
90 *
91 * Unfortunately, the VFS doesn't help us here. VOPs don't have a
92 * struct file* argument. fileops do, but many syscalls bypass the fileops
93 * layer and go straight to a vnode. Some, like writing from cache, can't
94 * track a file handle even in theory. The entire concept of the file handle
95 * is a product of FUSE's Linux origins; Linux lacks vnodes and almost every
96 * file system operation takes a struct file* argument.
97 *
98 * Since FreeBSD's VFS is more file descriptor-agnostic, we must store FUSE
99 * filehandles in the vnode. One option would be to only store a single file
100 * handle and never open FUSE files concurrently. That's what NetBSD does.
101 * But that violates FUSE's security model. FUSE expects the server to do all
102 * authorization (except when mounted with -o default_permissions). In order
103 * to do that, the server needs us to send FUSE_OPEN every time somebody opens
104 * a new file descriptor.
105 *
106 * Another option would be to never open FUSE files concurrently, but send a
107 * FUSE_ACCESS prior to every open after the first. That would give the server
108 * the opportunity to authorize the access. Unfortunately, the FUSE protocol
109 * makes ACCESS optional. File systems that don't implement it are assumed to
110 * authorize everything. A survey of 32 fuse file systems showed that only 14
111 * implemented access. Among the laggards were a few that really ought to be
112 * doing server-side authorization.
113 *
114 * So we do something hacky, similar to what OpenBSD, Illumos, and OSXFuse do.
115 * we store a list of file handles, one for each combination of vnode, uid,
116 * gid, pid, and access mode. When opening a file, we first check whether
117 * there's already a matching file handle. If so, we reuse it. If not, we
118 * send FUSE_OPEN and create a new file handle. That minimizes the number of
119 * open file handles while still allowing the server to authorize stuff.
120 *
121 * VOPs that need a file handle search through the list for a close match.
122 * They can't be guaranteed of finding an exact match because, for example, a
123 * process may have changed its UID since opening the file. Also, most VOPs
124 * don't know exactly what permission they need. Is O_RDWR required or is
125 * O_RDONLY good enough? So the file handle we end up using may not be exactly
126 * the one we're supposed to use with that file descriptor. But if the FUSE
127 * file system isn't too picky, it will work. (FWIW even Linux sometimes
128 * guesses the file handle, during writes from cache or most SETATTR
129 * operations).
130 *
131 * I suspect this mess is part of the reason why neither NFS nor 9P have an
132 * equivalent of FUSE file handles.
133 */
134 struct fuse_filehandle {
135 LIST_ENTRY(fuse_filehandle) next;
136
137 /* The filehandle returned by FUSE_OPEN */
138 uint64_t fh_id;
139
140 /*
141 * flags returned by FUSE_OPEN
142 * Supported flags: FOPEN_DIRECT_IO, FOPEN_KEEP_CACHE
143 * Unsupported:
144 * FOPEN_NONSEEKABLE: Adding support would require a new per-file
145 * or per-vnode attribute, which would have to be checked by
146 * kern_lseek (and others) for every file system. The benefit is
147 * dubious, since I'm unaware of any file systems in ports that use
148 * this flag.
149 */
150 uint32_t fuse_open_flags;
151
152 /* The access mode of the file handle */
153 fufh_type_t fufh_type;
154
155 /* Credentials used to open the file */
156 gid_t gid;
157 pid_t pid;
158 uid_t uid;
159 };
160
161 #define FUFH_IS_VALID(f) ((f)->fufh_type != FUFH_INVALID)
162
163 /*
164 * Get the flags to use for FUSE_CREATE, FUSE_OPEN and FUSE_RELEASE
165 *
166 * These are supposed to be the same as the flags argument to open(2).
167 * However, since we can't reliably associate a fuse_filehandle with a specific
168 * file descriptor it would would be dangerous to include anything more than
169 * the access mode flags. For example, suppose we open a file twice, once with
170 * O_APPEND and once without. Then the user pwrite(2)s to offset using the
171 * second file descriptor. If fusefs uses the first file handle, then the
172 * server may append the write to the end of the file rather than at offset 0.
173 * To prevent problems like this, we only ever send the portion of flags
174 * related to access mode.
175 *
176 * It's essential to send that portion, because FUSE uses it for server-side
177 * authorization.
178 */
179 static inline int
fufh_type_2_fflags(fufh_type_t type)180 fufh_type_2_fflags(fufh_type_t type)
181 {
182 int oflags = -1;
183
184 switch (type) {
185 case FUFH_RDONLY:
186 case FUFH_WRONLY:
187 case FUFH_RDWR:
188 case FUFH_EXEC:
189 oflags = type;
190 break;
191 default:
192 break;
193 }
194
195 return oflags;
196 }
197
198 bool fuse_filehandle_validrw(struct vnode *vp, int mode,
199 struct ucred *cred, pid_t pid);
200 int fuse_filehandle_get(struct vnode *vp, int fflag,
201 struct fuse_filehandle **fufhp, struct ucred *cred,
202 pid_t pid);
203 int fuse_filehandle_get_anyflags(struct vnode *vp,
204 struct fuse_filehandle **fufhp, struct ucred *cred,
205 pid_t pid);
206 int fuse_filehandle_getrw(struct vnode *vp, int fflag,
207 struct fuse_filehandle **fufhp, struct ucred *cred,
208 pid_t pid);
209
210 void fuse_filehandle_init(struct vnode *vp, fufh_type_t fufh_type,
211 struct fuse_filehandle **fufhp, struct thread *td,
212 const struct ucred *cred,
213 const struct fuse_open_out *foo);
214 int fuse_filehandle_open(struct vnode *vp, int mode,
215 struct fuse_filehandle **fufhp, struct thread *td,
216 struct ucred *cred);
217 int fuse_filehandle_close(struct vnode *vp, struct fuse_filehandle *fufh,
218 struct thread *td, struct ucred *cred);
219
220 void fuse_file_init(void);
221 void fuse_file_destroy(void);
222
223 #endif /* _FUSE_FILE_H_ */
224