cap-std 3.4.2

Capability-based version of the Rust standard library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

<div align="center">
  <h1><code>cap-std</code></h1>

  <p>
    <strong>Capability-based version of the Rust standard library</strong>
  </p>

  <p>
    <a href="https://github.com/bytecodealliance/cap-std/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/cap-std/workflows/CI/badge.svg" alt="Github Actions CI Status" /></a>
    <a href="https://crates.io/crates/cap-std"><img src="https://img.shields.io/crates/v/cap-std.svg" alt="crates.io page" /></a>
    <a href="https://docs.rs/cap-std"><img src="https://docs.rs/cap-std/badge.svg" alt="docs.rs docs" /></a>
  </p>
</div>

This crate provides a capability-based version of [`std`], providing
sandboxed filesystem, networking, and clock APIs. See the [toplevel README.md]
for more information about sandboxing using capability-based security.

The filesystem module [`cap_std::fs`], the networking module [`cap_std::net`],
and the time module [`cap_std::time`] currently support Linux, macOS, FreeBSD,
and Windows. WASI support is in development, though not yet usable.

Example usage of [`Dir`] for filesystem access:

```rust
use std::io;
use cap_std::fs::Dir;

/// Open files relative to `dir`.
fn dir_example(dir: &Dir) -> io::Result<()> {
    // This works (assuming symlinks don't lead outside of `dir`).
    let file = dir.open("the/thing.txt")?;

    // This fails, since `..` leads outside of `dir`.
    let hidden = dir.open("../hidden.txt")?;

    // This fails, as creating symlinks to absolute paths is not permitted.
    dir.symlink("/hidden.txt", "misdirection.txt")?;

    // However, even if the symlink had succeeded, or, if there is a
    // pre-existing symlink to an absolute directory, following a
    // symlink which would lead outside the sandbox also fails.
    let secret = dir.open("misdirection.txt")?;

    Ok(())
}
```

Example usage of [`Pool`] for network access:

```rust
use std::io;
use cap_std::net::Pool;

/// Open network addresses within `pool`.
fn pool_example(pool: &Pool) -> io::Result<()> {
    // Connect to an address. This succeeds only if the given address and
    // port are present in `pool`.
    let stream = pool.connect_tcp_stream("localhost:3333")?;

    Ok(())
}
```

[`std`]: https://doc.rust-lang.org/std/
[toplevel README.md]: https://github.com/bytecodealliance/cap-std/blob/main/README.md
[`cap_std::fs`]: https://docs.rs/cap-std/latest/cap_std/fs/index.html
[`cap_std::net`]: https://docs.rs/cap-std/latest/cap_std/net/index.html
[`cap_std::time`]: https://docs.rs/cap-std/latest/cap_std/time/index.html
[`Pool`]: https://docs.rs/cap-std/latest/cap_std/net/struct.Pool.html
[`Dir`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html