1# Additional background on Capabilities 2 3## Unforgeable references 4 5One of the key words that describes capabilities is *unforgeable*. 6 7A pointer in C is forgeable, because untrusted code could cast an integer 8to a pointer, thus *forging* access to whatever that pointer value points 9to. 10 11MVP WebAssembly doesn't have unforgeable references, but what we can do instead 12is just use integer values which are indices into a table that's held outside 13the reach of untrusted code. The indices themselves are forgeable, but 14ultimately the table is the thing which holds the actual capabilities, and 15its elements are unforgeable. There's no way to gain access to a new resource 16by making up a new index. 17 18When the reference-types proposal lands, references will be unforgeable, and 19will likely subsume the current integer-based APIs, at the WASI API layer. 20 21## Static vs dynamic capabilities 22 23There are two levels of capabilities that we can describe: static and dynamic. 24 25The static capabilities of a wasm module are its imports. These essentially 26declare the set of "rights" the module itself will be able to request. 27An important caveat though is that this doesn't consider capabilities which 28may be passed into an instance at runtime. 29 30The dynamic capabilities of a wasm module are a set of boolean values 31associated with a file descriptor, indicating individual "rights". This 32includes things like the right to read, or to write, using a given file 33descriptor. 34 35## Filesystem rules 36 37It happens that integer indices representing capabilities is same thing that 38POSIX does, except that POSIX calls these indices *file descriptors*. 39 40One difference though is that POSIX normally allows processes to request 41a file descriptor for any file in the entire filesystem hierarchy, which is 42granted based on whatever security policies are in place. This doesn't 43violate the capability model, but it doesn't take full advantage of it. 44 45CloudABI, Fuchsia, and other capability-oriented systems prefer to take 46advantage of the hierarchical nature of the filesystem and require untrusted 47code to have a capability for a directory in order to access things inside 48that directory. 49 50This way, you can launch untrusted code, and at runtime give it access to 51specific directories, without having to set permissions in the filesystem or 52in per-application or per-user configuration settings. 53 54See [this tutorial](WASI-tutorial.md) for an example of how this can look 55in practice. 56 57## Berkeley socket rules 58 59Sockets aren't naturally hierarchical though, so we'll need to decide what 60capabilities look like. This is an area that isn't yet implemented. 61 62In CloudABI, users launch programs with the sockets they need already 63created. That's potentially a starting point, which might be enough for 64simple cases. 65 66We also anticipate an eventual extension to that, where we create a capability 67that represents a set of possible sockets that can be created. A set 68might be described by ranges of permitted ports, ranges of permitted 69addresses, or sets of permitted protocols. In this case the actual socket 70wouldn't be created until the application actually requests it. 71 72## Other info 73 74CloudABI's intro to capability-based OS security provides additional background info: 75 76https://github.com/NuxiNL/cloudabi#capability-based-security 77 78 79The Fuchsia project has a blog post on the topic of capability-based OS security: 80 81https://fuchsia.dev/fuchsia-src/concepts/filesystems/dotdot 82