cap-std

cap-std crate provides a capability-oriented version of [std]. It provides capability-oriented versions of interfaces you are used to.

The filesystem module, [cap_std::fs], is known to work on Linux, macOS, and FreeBSD, and probably can be easily ported to other modern Unix-family platforms. Ports to Windows and WASI platforms are in development, though not yet usable.

Capability-oriented security

Operating systems have a concept of resource handles, or file descriptors, which are values that can be passed around within and sometimes between programs, and which represent access to external resources. Programs typically have the ambient authority to request any file or network handle simply by providing its name or address:

let file = File::open("/anything/you/want.txt")?;

There may be access-control lists, namespaces, firewalls, or virtualization mechanisms governing which resources can actually be accessed, but those are typically coarse-grained and configured outside of the application.

Capability-oriented security seeks to avoid ambient authority, to make sandboxing finer-grained and composable. To open a file, one needs a [Dir], representing an open directory it's in:

let file = dir.open("the/thing.txt")?;

Attempts to access paths not contained within the directory:

``` let hidden = dir.open("../hidden.txt")?;

dir.symlink("/hidden.txt", "misdirection.txt")?;
let secret = dir.open("misdirection.txt")?;

```

return PermissionDenied errors.

This allows application logic to configure its own access, without changing the behavior of the whole host process, setting up a separate host process, or requiring external configuration.

How do I obtain a [Dir]?

If every resource requires some other resource to obtain, how does one obtain the first resource?

There are three main ways: - Use the [cap-directories] crate to create Dirs for config, cache and other data directories. - Use the [cap-tempfile] crate to create Dirs for temporary directories. - Use the unsafe [Dir::open_ambient_dir] to open a plain path. This function is not sandboxed, and may open any file the host process has access to.

See the [kv-cli example] for a simple example of a program using cap-directories and cap-std APIs.

What can I use cap-std for?

cap-std is not a sandbox for untrusted Rust code. Among other things, untrusted Rust code could use unsafe or the unsandboxed APIs in std::fs.

cap-std allows code to declare its intent and to opt in to protection from malicious path names. Code which takes a [Dir] from which to open files, rather than taking bare filenames, declares its intent to only open files underneath that Dir. And, Dir automatically protects against paths which might include .., symlinks, or absolute paths that might lead outside of that Dir.

cap-std also has another role, within WASI, because cap-std's filesystem APIs closely follow WASI's sandboxing APIs. In WASI, cap-std becomes a very thin layer, thinner than libstd's filesystem APIs because it doesn't need extra code to handle absolute paths.

How fast is it?

On Linux 5.6 and newer, cap-std uses [openat2] to implement open and with a single system call in common cases. Several other operations internally utilize openat2 for fast path resolution as well.

Otherwise, cap-std opens each component of a path individually, in order to specially handle .. and symlinks. The algorithm is carefully designed to minimize system calls, so opening red/green/blue performs just 5 system calls—it opens red, green, and then blue, and closes the handles for red and green.

Async support

Async APIs are available in the [cap-async-std] crate.

What about networking?

This library contains a few sketches of how to apply similar ideas to networking, but it's very incomplete at this time. If you're interested in this area, let's talk about what this might become!

What is cap_std::fs_utf8?

It's an experiment in what an API with UTF-8 filesystem paths (but which still allow you to access any file with any byte-sequence name) might look like. For more information on the technique, see the [arf-strings package]. To try it, opt in by enabling the fs_utf8 feature and using std::fs_utf8 in place of std::fs.