vfs/
protocols.rs

1// Copyright 2023 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::common::CreationMode;
6use crate::directory::DirectoryOptions;
7use crate::file::FileOptions;
8use crate::node::NodeOptions;
9use crate::service::ServiceOptions;
10use crate::symlink::SymlinkOptions;
11use fidl_fuchsia_io as fio;
12use zx_status::Status;
13
14/// Extends fio::Flags and fio::OpenFlags
15pub trait ProtocolsExt: ToFileOptions + ToNodeOptions + Send + Sync + 'static {
16    /// True if the directory protocol is allowed.
17    fn is_dir_allowed(&self) -> bool;
18
19    /// True if the file protocol is allowed.
20    fn is_file_allowed(&self) -> bool;
21
22    /// True if the symlink protocol is allowed.
23    fn is_symlink_allowed(&self) -> bool;
24
25    /// The creation mode for the connection.
26    fn creation_mode(&self) -> CreationMode;
27
28    /// The rights for the connection.  If None, it means the connection is not for a node based
29    /// protocol.  If the connection is supposed to use the same rights as the parent connection,
30    /// the rights should have been populated.
31    fn rights(&self) -> Option<fio::Operations>;
32
33    /// Convert to directory options.  Returns an error if the request does not permit a directory.
34    fn to_directory_options(&self) -> Result<DirectoryOptions, Status>;
35
36    /// Convert to symlink options.  Returns an error if the request does not permit a symlink.
37    fn to_symlink_options(&self) -> Result<SymlinkOptions, Status>;
38
39    /// Convert to service options.  Returns an error if the request is not valid for a service.
40    fn to_service_options(&self) -> Result<ServiceOptions, Status>;
41
42    /// True if the file should be in append mode.
43    fn is_append(&self) -> bool;
44
45    /// True if the file should be truncated.
46    fn is_truncate(&self) -> bool;
47
48    /// If creating an object, Whether to create a directory.
49    fn create_directory(&self) -> bool;
50
51    /// True if the protocol should be a limited node connection.
52    fn is_node(&self) -> bool;
53
54    /// True if creating as an unnamed temporary object.
55    fn create_unnamed_temporary_in_directory_path(&self) -> bool;
56}
57
58impl ProtocolsExt for fio::OpenFlags {
59    fn is_dir_allowed(&self) -> bool {
60        !self.contains(fio::OpenFlags::NOT_DIRECTORY)
61    }
62
63    fn is_file_allowed(&self) -> bool {
64        !self.contains(fio::OpenFlags::DIRECTORY)
65    }
66
67    fn is_symlink_allowed(&self) -> bool {
68        !self.contains(fio::OpenFlags::DIRECTORY)
69    }
70
71    fn creation_mode(&self) -> CreationMode {
72        if self.contains(fio::OpenFlags::CREATE) {
73            if self.contains(fio::OpenFlags::CREATE_IF_ABSENT) {
74                CreationMode::Always
75            } else {
76                CreationMode::AllowExisting
77            }
78        } else {
79            CreationMode::Never
80        }
81    }
82
83    fn rights(&self) -> Option<fio::Operations> {
84        if self.contains(fio::OpenFlags::CLONE_SAME_RIGHTS) {
85            None
86        } else {
87            let mut rights = fio::Operations::GET_ATTRIBUTES | fio::Operations::CONNECT;
88            if self.contains(fio::OpenFlags::RIGHT_READABLE) {
89                rights |= fio::R_STAR_DIR;
90            }
91            if self.contains(fio::OpenFlags::RIGHT_WRITABLE) {
92                rights |= fio::W_STAR_DIR;
93            }
94            if self.contains(fio::OpenFlags::RIGHT_EXECUTABLE) {
95                rights |= fio::X_STAR_DIR;
96            }
97            Some(rights)
98        }
99    }
100
101    /// Checks flags provided for a new directory connection.  Returns directory options (cleaning
102    /// up some ambiguities) or an error, in case new new connection flags are not permitting the
103    /// connection to be opened.
104    ///
105    /// Changing this function can be dangerous!  Flags operations may have security implications.
106    fn to_directory_options(&self) -> Result<DirectoryOptions, Status> {
107        assert!(!self.intersects(fio::OpenFlags::NODE_REFERENCE));
108
109        let mut flags = *self;
110
111        if flags.intersects(fio::OpenFlags::DIRECTORY) {
112            flags &= !fio::OpenFlags::DIRECTORY;
113        }
114
115        if flags.intersects(fio::OpenFlags::NOT_DIRECTORY) {
116            return Err(Status::NOT_FILE);
117        }
118
119        // Parent connection must check the POSIX flags in `check_child_connection_flags`, so if any
120        // are still present, we expand their respective rights and remove any remaining flags.
121        if flags.intersects(fio::OpenFlags::POSIX_EXECUTABLE) {
122            flags |= fio::OpenFlags::RIGHT_EXECUTABLE;
123        }
124        if flags.intersects(fio::OpenFlags::POSIX_WRITABLE) {
125            flags |= fio::OpenFlags::RIGHT_WRITABLE;
126        }
127        flags &= !(fio::OpenFlags::POSIX_WRITABLE | fio::OpenFlags::POSIX_EXECUTABLE);
128
129        let allowed_flags = fio::OpenFlags::DESCRIBE
130            | fio::OpenFlags::CREATE
131            | fio::OpenFlags::CREATE_IF_ABSENT
132            | fio::OpenFlags::DIRECTORY
133            | fio::OpenFlags::RIGHT_READABLE
134            | fio::OpenFlags::RIGHT_WRITABLE
135            | fio::OpenFlags::RIGHT_EXECUTABLE;
136
137        let prohibited_flags = fio::OpenFlags::APPEND | fio::OpenFlags::TRUNCATE;
138
139        if flags.intersects(prohibited_flags) {
140            return Err(Status::INVALID_ARGS);
141        }
142
143        if flags.intersects(!allowed_flags) {
144            return Err(Status::NOT_SUPPORTED);
145        }
146
147        // Map io1 OpenFlags::RIGHT_* flags to the corresponding set of io2 rights. Using Open1
148        // requires GET_ATTRIBUTES, as this was previously an privileged operation.
149        let mut rights = fio::Rights::GET_ATTRIBUTES;
150        if flags.contains(fio::OpenFlags::RIGHT_READABLE) {
151            rights |= fio::R_STAR_DIR;
152        }
153        if flags.contains(fio::OpenFlags::RIGHT_WRITABLE) {
154            rights |= fio::W_STAR_DIR;
155        }
156        if flags.contains(fio::OpenFlags::RIGHT_EXECUTABLE) {
157            rights |= fio::X_STAR_DIR;
158        }
159
160        Ok(DirectoryOptions { rights })
161    }
162
163    fn to_symlink_options(&self) -> Result<SymlinkOptions, Status> {
164        if self.intersects(fio::OpenFlags::DIRECTORY) {
165            return Err(Status::NOT_DIR);
166        }
167
168        // We allow write and executable access because the client might not know this is a symbolic
169        // link and they want to open the target of the link with write or executable rights.
170        let optional = fio::OpenFlags::NOT_DIRECTORY
171            | fio::OpenFlags::DESCRIBE
172            | fio::OpenFlags::RIGHT_WRITABLE
173            | fio::OpenFlags::RIGHT_EXECUTABLE;
174
175        if *self & !optional != fio::OpenFlags::RIGHT_READABLE {
176            return Err(Status::INVALID_ARGS);
177        }
178
179        Ok(SymlinkOptions)
180    }
181
182    fn to_service_options(&self) -> Result<ServiceOptions, Status> {
183        if self.intersects(fio::OpenFlags::DIRECTORY) {
184            return Err(Status::NOT_DIR);
185        }
186
187        if self.intersects(!fio::OpenFlags::DESCRIBE.union(fio::OpenFlags::NOT_DIRECTORY)) {
188            return Err(Status::INVALID_ARGS);
189        }
190
191        Ok(ServiceOptions)
192    }
193
194    fn is_append(&self) -> bool {
195        self.contains(fio::OpenFlags::APPEND)
196    }
197
198    fn is_truncate(&self) -> bool {
199        self.contains(fio::OpenFlags::TRUNCATE)
200    }
201
202    fn create_directory(&self) -> bool {
203        self.contains(fio::OpenFlags::DIRECTORY)
204    }
205
206    fn is_node(&self) -> bool {
207        self.contains(fio::OpenFlags::NODE_REFERENCE)
208    }
209
210    fn create_unnamed_temporary_in_directory_path(&self) -> bool {
211        false
212    }
213}
214
215impl ProtocolsExt for fio::Flags {
216    fn is_dir_allowed(&self) -> bool {
217        self.contains(fio::Flags::PROTOCOL_DIRECTORY)
218            || self.intersection(fio::MASK_KNOWN_PROTOCOLS).is_empty()
219    }
220
221    fn is_file_allowed(&self) -> bool {
222        self.contains(fio::Flags::PROTOCOL_FILE)
223            || self.intersection(fio::MASK_KNOWN_PROTOCOLS).is_empty()
224    }
225
226    fn is_symlink_allowed(&self) -> bool {
227        self.contains(fio::Flags::PROTOCOL_SYMLINK)
228            || self.intersection(fio::MASK_KNOWN_PROTOCOLS).is_empty()
229    }
230
231    fn creation_mode(&self) -> CreationMode {
232        #[cfg(fuchsia_api_level_at_least = "HEAD")]
233        {
234            if self.contains(fio::Flags::FLAG_CREATE_AS_UNNAMED_TEMPORARY) {
235                if self.contains(fio::Flags::FLAG_MUST_CREATE) {
236                    return CreationMode::UnlinkableUnnamedTemporary;
237                }
238                return CreationMode::UnnamedTemporary;
239            }
240        }
241        if self.contains(fio::Flags::FLAG_MUST_CREATE) {
242            CreationMode::Always
243        } else if self.contains(fio::Flags::FLAG_MAYBE_CREATE) {
244            CreationMode::AllowExisting
245        } else {
246            CreationMode::Never
247        }
248    }
249
250    fn rights(&self) -> Option<fio::Operations> {
251        Some(flags_to_rights(self))
252    }
253
254    fn to_directory_options(&self) -> Result<DirectoryOptions, Status> {
255        // Verify protocols.
256        if !self.is_dir_allowed() {
257            return Err(if self.is_file_allowed() { Status::NOT_FILE } else { Status::WRONG_TYPE });
258        }
259
260        // Expand the POSIX flags to their respective rights. This is done with the assumption that
261        // the POSIX flags would have been validated prior to calling this. E.g. in the vfs
262        // connection later.
263        let mut updated_flags = *self;
264        if updated_flags.contains(fio::Flags::PERM_INHERIT_WRITE) {
265            updated_flags |=
266                fio::Flags::from_bits_truncate(fio::INHERITED_WRITE_PERMISSIONS.bits());
267        }
268        if updated_flags.contains(fio::Flags::PERM_INHERIT_EXECUTE) {
269            updated_flags |= fio::Flags::PERM_EXECUTE;
270        }
271
272        // Verify that there are no file-related flags.
273        if updated_flags.intersects(fio::Flags::FILE_APPEND | fio::Flags::FILE_TRUNCATE) {
274            return Err(Status::INVALID_ARGS);
275        }
276
277        Ok(DirectoryOptions { rights: flags_to_rights(&updated_flags) })
278    }
279
280    fn to_symlink_options(&self) -> Result<SymlinkOptions, Status> {
281        if !self.is_symlink_allowed() {
282            return Err(Status::WRONG_TYPE);
283        }
284
285        // If is_symlink_allowed() returned true, there must be rights.
286        if !self.rights().unwrap().contains(fio::Operations::GET_ATTRIBUTES) {
287            return Err(Status::INVALID_ARGS);
288        }
289        Ok(SymlinkOptions)
290    }
291
292    fn to_service_options(&self) -> Result<ServiceOptions, Status> {
293        // This should not be called if fio::Flags::PROTOCOL_NODE was set (`to_node_options` would
294        // be called instead).
295        assert!(!self.contains(fio::Flags::PROTOCOL_NODE));
296        if !self
297            .intersection(fio::MASK_KNOWN_PROTOCOLS)
298            .difference(fio::Flags::PROTOCOL_SERVICE)
299            .is_empty()
300        {
301            return if self.is_dir_allowed() {
302                Err(Status::NOT_DIR)
303            } else if self.is_file_allowed() {
304                Err(Status::NOT_FILE)
305            } else {
306                Err(Status::WRONG_TYPE)
307            };
308        }
309
310        if !self.difference(fio::Flags::PROTOCOL_SERVICE).is_empty() {
311            return Err(Status::INVALID_ARGS);
312        }
313
314        Ok(ServiceOptions)
315    }
316
317    fn is_append(&self) -> bool {
318        self.contains(fio::Flags::FILE_APPEND)
319    }
320
321    fn is_truncate(&self) -> bool {
322        self.contains(fio::Flags::FILE_TRUNCATE)
323    }
324
325    fn create_directory(&self) -> bool {
326        self.contains(fio::Flags::PROTOCOL_DIRECTORY)
327    }
328
329    fn is_node(&self) -> bool {
330        self.contains(fio::Flags::PROTOCOL_NODE)
331    }
332
333    fn create_unnamed_temporary_in_directory_path(&self) -> bool {
334        self.creation_mode() == CreationMode::UnnamedTemporary
335            || self.creation_mode() == CreationMode::UnlinkableUnnamedTemporary
336    }
337}
338
339pub trait ToFileOptions: Send + 'static {
340    fn to_file_options(&self) -> Result<FileOptions, Status>;
341}
342
343impl ToFileOptions for fio::OpenFlags {
344    fn to_file_options(&self) -> Result<FileOptions, Status> {
345        assert!(!self.intersects(fio::OpenFlags::NODE_REFERENCE));
346
347        if self.contains(fio::OpenFlags::DIRECTORY) {
348            return Err(Status::NOT_DIR);
349        }
350
351        // Verify allowed operations/flags this node supports.
352        let flags_without_rights = self.difference(
353            fio::OpenFlags::RIGHT_READABLE
354                | fio::OpenFlags::RIGHT_WRITABLE
355                | fio::OpenFlags::RIGHT_EXECUTABLE,
356        );
357        const ALLOWED_FLAGS: fio::OpenFlags = fio::OpenFlags::DESCRIBE
358            .union(fio::OpenFlags::CREATE)
359            .union(fio::OpenFlags::CREATE_IF_ABSENT)
360            .union(fio::OpenFlags::APPEND)
361            .union(fio::OpenFlags::TRUNCATE)
362            .union(fio::OpenFlags::POSIX_WRITABLE)
363            .union(fio::OpenFlags::POSIX_EXECUTABLE)
364            .union(fio::OpenFlags::NOT_DIRECTORY);
365        if flags_without_rights.intersects(!ALLOWED_FLAGS) {
366            return Err(Status::NOT_SUPPORTED);
367        }
368
369        // Disallow invalid flag combinations.
370        let mut prohibited_flags = fio::OpenFlags::empty();
371        if !self.intersects(fio::OpenFlags::RIGHT_WRITABLE) {
372            prohibited_flags |= fio::OpenFlags::TRUNCATE
373        }
374        if self.intersects(prohibited_flags) {
375            return Err(Status::INVALID_ARGS);
376        }
377
378        Ok(FileOptions {
379            rights: {
380                let mut rights = fio::Operations::GET_ATTRIBUTES;
381                if self.contains(fio::OpenFlags::RIGHT_READABLE) {
382                    rights |= fio::Operations::READ_BYTES;
383                }
384                if self.contains(fio::OpenFlags::RIGHT_WRITABLE) {
385                    rights |= fio::Operations::WRITE_BYTES | fio::Operations::UPDATE_ATTRIBUTES;
386                }
387                if self.contains(fio::OpenFlags::RIGHT_EXECUTABLE) {
388                    rights |= fio::Operations::EXECUTE;
389                }
390                rights
391            },
392            is_append: self.contains(fio::OpenFlags::APPEND),
393            #[cfg(fuchsia_api_level_at_least = "HEAD")]
394            is_linkable: true,
395        })
396    }
397}
398
399impl ToFileOptions for fio::Flags {
400    fn to_file_options(&self) -> Result<FileOptions, Status> {
401        // Verify protocols.
402        if !self.is_file_allowed() {
403            if self.is_dir_allowed() && !self.is_symlink_allowed() {
404                return Err(Status::NOT_DIR);
405            } else {
406                return Err(Status::WRONG_TYPE);
407            }
408        }
409
410        // Verify prohibited flags and disallow invalid flag combinations.
411        if self.contains(fio::Flags::FILE_TRUNCATE) && !self.contains(fio::Flags::PERM_WRITE) {
412            return Err(Status::INVALID_ARGS);
413        }
414
415        // Used to remove any non-file flags.
416        const ALLOWED_RIGHTS: fio::Operations = fio::Operations::empty()
417            .union(fio::Operations::GET_ATTRIBUTES)
418            .union(fio::Operations::READ_BYTES)
419            .union(fio::Operations::WRITE_BYTES)
420            .union(fio::Operations::UPDATE_ATTRIBUTES)
421            .union(fio::Operations::EXECUTE);
422
423        Ok(FileOptions {
424            rights: flags_to_rights(self).intersection(ALLOWED_RIGHTS),
425            is_append: self.contains(fio::Flags::FILE_APPEND),
426            #[cfg(fuchsia_api_level_at_least = "HEAD")]
427            is_linkable: !self.contains(
428                fio::Flags::FLAG_CREATE_AS_UNNAMED_TEMPORARY | fio::FLAG_TEMPORARY_AS_NOT_LINKABLE,
429            ),
430        })
431    }
432}
433
434impl ToFileOptions for FileOptions {
435    fn to_file_options(&self) -> Result<FileOptions, Status> {
436        Ok(*self)
437    }
438}
439
440pub trait ToNodeOptions: Send + 'static {
441    fn to_node_options(&self, dirent_type: fio::DirentType) -> Result<NodeOptions, Status>;
442}
443
444impl ToNodeOptions for fio::OpenFlags {
445    fn to_node_options(&self, dirent_type: fio::DirentType) -> Result<NodeOptions, Status> {
446        // Strictly, we shouldn't allow rights to be specified with NODE_REFERENCE, but there's a
447        // CTS pkgdir test that asserts these flags work and fixing that is painful so we preserve
448        // old behaviour (which permitted these flags).
449        let allowed_rights =
450            fio::OPEN_RIGHTS | fio::OpenFlags::POSIX_WRITABLE | fio::OpenFlags::POSIX_EXECUTABLE;
451        if self.intersects(!(fio::OPEN_FLAGS_ALLOWED_WITH_NODE_REFERENCE | allowed_rights)) {
452            Err(Status::INVALID_ARGS)
453        } else if self.contains(fio::OpenFlags::DIRECTORY)
454            && dirent_type != fio::DirentType::Directory
455        {
456            Err(Status::NOT_DIR)
457        } else {
458            Ok(NodeOptions { rights: fio::Operations::GET_ATTRIBUTES })
459        }
460    }
461}
462
463impl ToNodeOptions for fio::Flags {
464    fn to_node_options(&self, dirent_type: fio::DirentType) -> Result<NodeOptions, Status> {
465        // Strictly, we shouldn't allow rights to be specified with PROTOCOL_NODE, but there's a
466        // CTS pkgdir test that asserts these flags work and fixing that is painful so we preserve
467        // old behaviour (which permitted these flags).
468        const ALLOWED_FLAGS: fio::Flags = fio::Flags::FLAG_SEND_REPRESENTATION
469            .union(fio::MASK_KNOWN_PERMISSIONS)
470            .union(fio::MASK_KNOWN_PROTOCOLS);
471
472        if self.intersects(!ALLOWED_FLAGS) {
473            return Err(Status::INVALID_ARGS);
474        }
475
476        // If other `PROTOCOL_*` were were specified along with `PROTOCOL_NODE`, verify that the
477        // target node supports it.
478        if self.intersects(fio::MASK_KNOWN_PROTOCOLS.difference(fio::Flags::PROTOCOL_NODE)) {
479            if dirent_type == fio::DirentType::Directory {
480                if !self.intersects(fio::Flags::PROTOCOL_DIRECTORY) {
481                    if self.intersects(fio::Flags::PROTOCOL_FILE) {
482                        return Err(Status::NOT_FILE);
483                    } else {
484                        return Err(Status::WRONG_TYPE);
485                    }
486                }
487            } else if dirent_type == fio::DirentType::File {
488                if !self.intersects(fio::Flags::PROTOCOL_FILE) {
489                    if self.intersects(fio::Flags::PROTOCOL_DIRECTORY) {
490                        return Err(Status::NOT_DIR);
491                    } else {
492                        return Err(Status::WRONG_TYPE);
493                    }
494                }
495            } else if dirent_type == fio::DirentType::Symlink {
496                if !self.intersects(fio::Flags::PROTOCOL_SYMLINK) {
497                    return Err(Status::WRONG_TYPE);
498                }
499            }
500        }
501
502        Ok(NodeOptions {
503            rights: flags_to_rights(self).intersection(fio::Operations::GET_ATTRIBUTES),
504        })
505    }
506}
507
508impl ToNodeOptions for NodeOptions {
509    fn to_node_options(&self, _dirent_type: fio::DirentType) -> Result<NodeOptions, Status> {
510        Ok(*self)
511    }
512}
513
514fn flags_to_rights(flags: &fio::Flags) -> fio::Rights {
515    fio::Rights::from_bits_truncate(flags.bits())
516}
vfs/protocols.rs

vfs/
protocols.rs
