Skip to content

Commit

Permalink
Update Wasmtime's WASI documentation. (#9471)
Browse files Browse the repository at this point in the history 
* Update Wasmtime's WASI documentation.

Replace most of Wasmtime's original WASI documentation with links to
other resources that are now available.

This documentation was written when WASI was first released, and while
many of the big ideas are still present in WASI, many of the details have
changed. For example, [Jco] is now a much better way to run WASI programs
in Browsers than the original Web polyfill, and WASI is now goverened by
the WASI Subgroup rather than by Wasmtime itself, and so on.

[Jco]: https://github.com/bytecodealliance/jco

Fixes #9107.

* Fix documentation link.

* Fix another doc link.
  • Loading branch information
@sunfishcode
sunfishcode authored Oct 16, 2024
1 parent 93d8bd9 commit 3f2febf
Show file tree
Hide file tree
Showing 9 changed files with 20 additions and 826 deletions.
179 changes: 0 additions & 179 deletions docs/WASI-background.md
View file

This file was deleted.

81 changes: 3 additions & 78 deletions docs/WASI-capabilities.md
View file
Original file line number Diff line number Diff line change
@@ -1,81 +1,6 @@
# Additional background on Capabilities

## Unforgeable references
For more information about capabilities in WASI, see the WASI Subgroup's
[capabilities documentation].

One of the key words that describes capabilities is *unforgeable*.

A pointer in C is forgeable, because untrusted code could cast an integer
to a pointer, thus *forging* access to whatever that pointer value points
to.

MVP WebAssembly doesn't have unforgeable references, but what we can do instead
is just use integer values which are indices into a table that's held outside
the reach of untrusted code. The indices themselves are forgeable, but
ultimately the table is the thing which holds the actual capabilities, and
its elements are unforgeable. There's no way to gain access to a new resource
by making up a new index.

When the reference-types proposal lands, references will be unforgeable, and
will likely subsume the current integer-based APIs, at the WASI API layer.

## Static vs dynamic capabilities

There are two levels of capabilities that we can describe: static and dynamic.

The static capabilities of a wasm module are its imports. These essentially
declare the set of "rights" the module itself will be able to request.
An important caveat though is that this doesn't consider capabilities which
may be passed into an instance at runtime.

The dynamic capabilities of a wasm module are a set of boolean values
associated with a file descriptor, indicating individual "rights". This
includes things like the right to read, or to write, using a given file
descriptor.

## Filesystem rules

It happens that integer indices representing capabilities is same thing that
POSIX does, except that POSIX calls these indices *file descriptors*.

One difference though is that POSIX normally allows processes to request
a file descriptor for any file in the entire filesystem hierarchy, which is
granted based on whatever security policies are in place. This doesn't
violate the capability model, but it doesn't take full advantage of it.

CloudABI, Fuchsia, and other capability-oriented systems prefer to take
advantage of the hierarchical nature of the filesystem and require untrusted
code to have a capability for a directory in order to access things inside
that directory.

This way, you can launch untrusted code, and at runtime give it access to
specific directories, without having to set permissions in the filesystem or
in per-application or per-user configuration settings.

See [this tutorial](WASI-tutorial.md) for an example of how this can look
in practice.

## Berkeley socket rules

Sockets aren't naturally hierarchical though, so we'll need to decide what
capabilities look like. This is an area that isn't yet implemented.

In CloudABI, users launch programs with the sockets they need already
created. That's potentially a starting point, which might be enough for
simple cases.

We also anticipate an eventual extension to that, where we create a capability
that represents a set of possible sockets that can be created. A set
might be described by ranges of permitted ports, ranges of permitted
addresses, or sets of permitted protocols. In this case the actual socket
wouldn't be created until the application actually requests it.

## Other info

CloudABI's intro to capability-based OS security provides additional background info:

https://github.com/NuxiNL/cloudabi#capability-based-security


The Fuchsia project has a blog post on the topic of capability-based OS security:

https://fuchsia.dev/fuchsia-src/concepts/filesystems/dotdot
[capabilities documentation]: https://github.com/WebAssembly/WASI/blob/main/docs/Capabilities.md
27 changes: 2 additions & 25 deletions docs/WASI-documents.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,5 @@
# WASI Document Guide

To get started using WASI, see [the intro document](WASI-intro.md) and
[the tutorial](WASI-tutorial.md).
For documentation about WASI, see the [Resources page on wasi.dev].

For more detail on what WASI is, see [the overview](WASI-overview.md).

For specifics on the API, see the [API documentation](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md).
Additionally, a C header file describing the WASI API is
[here](https://github.com/WebAssembly/wasi-libc/blob/master/libc-bottom-half/headers/public/wasi/api.h).

The WASI C/C++ SDK repository is [wasi-sdk](https://github.com/WebAssembly/wasi-sdk/).

The WASI libc repository, used by wasi-sdk, is [wasi-libc](https://github.com/WebAssembly/wasi-libc/).

For some discussion of capability-based design, see the [Capabilities document](WASI-capabilities.md).

For some discussion of WASI's design inspiration, see the [Background document](WASI-background.md).

For background on some of the design decisions in WASI, see [the rationale](WASI-rationale.md).

For documentation of the exports required of programs using, see
[the application ABI](https://github.com/WebAssembly/WASI/blob/main/legacy/application-abi.md).

For some ideas of things that we may want to change about WASI in the
short term, see the [possible changes](WASI-some-possible-changes.md) document.
For longer-term ideas, see the [possible future features](WASI-possible-future-features.md)
document.
[Resources page on wasi.dev]: https://wasi.dev/resources
61 changes: 5 additions & 56 deletions docs/WASI-intro.md
View file
Original file line number Diff line number Diff line change
@@ -1,60 +1,9 @@
# Welcome to WASI!

WASI stands for WebAssembly System Interface. It's an API designed by
the [Wasmtime] project that provides access to several operating-system-like
features, including files and filesystems, Berkeley sockets, clocks, and
random numbers, that we'll be proposing for standardization.
WebAssembly System Interface, or WASI, is a family of APIs being designed
by the [WASI Subgroup] of the Wasm Community Group of the W3C.

It's designed to be independent of browsers, so it doesn't depend on
Web APIs or JS, and isn't limited by the need to be compatible with JS.
And it has integrated capability-based security, so it extends
WebAssembly's characteristic sandboxing to include I/O.
To learn more about WASI, see [wasi.dev].

See the [WASI Overview](WASI-overview.md) for more detailed background
information, and the [WASI Tutorial](WASI-tutorial.md) for a walkthrough
showing how various pieces fit together.

Note that everything here is a prototype, and while a lot of stuff works,
there are numerous missing features and some rough edges. For example,
networking support is incomplete.

## How can I write programs that use WASI?

The two toolchains that currently work well are the Rust toolchain and
a specially packaged C and C++ toolchain. Of course, we hope other
toolchains will be able to implement WASI as well!

### Rust

To install a WASI-enabled Rust toolchain, see the [online section of the
guide](https://bytecodealliance.github.io/wasmtime/examples-rust-embed.html)

### C/C++

To install a WASI-enabled C/C++ toolchain, see the [online section of the
guide](https://bytecodealliance.github.io/wasmtime/lang-c.html)

## How can I run programs that use WASI?

Currently the options are [Wasmtime] and the [browser polyfill], though we
intend WASI to be implementable in many wasm VMs.

[Wasmtime]: https://github.com/bytecodealliance/wasmtime
[browser polyfill]: https://github.com/bjorn3/browser_wasi_shim

### Wasmtime

[Wasmtime] is a non-Web WebAssembly engine which is part of the
[Bytecode Alliance project](https://bytecodealliance.org). To build
it, download the code and build with `cargo build --release`. It can
run WASI-using wasm programs by simply running `wasmtime foo.wasm`,
or `cargo run --bin wasmtime foo.wasm`.

### The browser polyfill

The source is [here](https://github.com/bjorn3/browser_wasi_shim).

## Where can I learn more?

Beyond the [WASI Overview](WASI-overview.md), take a look at the
various [WASI documents](WASI-documents.md).
[WASI Subgroup]: https://github.com/WebAssembly/wasi
[wasi.dev]: https://wasi.dev/
Loading

0 comments on commit 3f2febf

Please sign in to comment.