In https://github.com/myfreeweb/rusty-sandbox there is support for defining a Directory containing a path under which all associated operations can be permitted (e.g. allow read of everything under /zdata/files). This functionality would be a nice addition to this crate.

Use case: combine with CAP_CONNECT to create a file downloader which can only write to specific directories (thinking of things like freebsd-update here :smirk:), or only permit an Iron/Nickel web server to read data from one location.

    It would be nice to have a `rustfmt` task as well, but we can do this in a follow up since it requires a `cargo fmt` run.

Originally posted by @dlrobertson in https://github.com/dlrobertson/capsicum-rs/pull/12#discussion_r1020256852

• clippy cleanup
• enter and get_mode now return a io::Result
• Fix a stack overflow in IoctlRights::from_file
• Fix FFI bindings
• Add a test for unlimited ioctl rights
• Fix doc tests
• Fix definitions of fork() and wait()

It's best practice to put FFI bindings in a separate crate, named *-sys. We should do something like that for capsicum. https://doc.rust-lang.org/cargo/reference/build-scripts.html#-sys-packages

Futhermore, since Capsicum is part of FreeBSD's system C library, the correct place for these declarations is in the libc crate. That crate has the added advantage of a very good test suite to verify that the FFI functions are defined correctly. Therefore we should rely on libc's bindings. It already has bindings for most of Capsicum's functions.

• Must check the child process's exit status
• Must switch the panic handler to SIGABRT, since stack unwinding isn't safe after fork() (requires nightly).

We could use tempdir to create a directory which we wouldn't have access to, or do something like a lookup in "./tests". We probably should avoid using "./src" and "./tests" which I think wouldn't work in some cases if the tests binary was run manually outside of the root crate directory.

Originally posted by @dlrobertson in https://github.com/dlrobertson/capsicum-rs/pull/7#discussion_r1016017038

Also see https://github.com/dlrobertson/capsicum-rs/pull/7/files#r1016042775

• Use the tempfile crate instead of hard-coding temporary file names
• Must use _exit(0) at the end of child processes, so we don't run the Rust destructors in both children and parents.
• Minimize use of unsafe
• Always run cap_enter in a child process.

If no limits have been placed on a file with cap_ioctls_limit, then cap_ioctls_get will return the special value CAP_IOCTLS_ALL, which means "unlimited". But IoctlRights has no way to represent that, since it's defined a as a vec of allowed commands.

On FreeBSD 14.0-CURRENT with a recent nightly rust, the ioctl test triggers an assertion within jemalloc

> rustc --version
rustc 1.67.0-nightly (215e3cd21 2022-11-03)
> cargo test --test lib base::test_ioctl
warning: use of deprecated macro `try`: use the `?` operator instead
  --> src/util.rs:47:20
   |
47 |         let file = try!(File::open(path));
   |                    ^^^
   |
   = note: `#[warn(deprecated)]` on by default

warning: `capsicum` (lib) generated 1 warning
    Finished test [unoptimized + debuginfo] target(s) in 0.06s
     Running tests/lib.rs (target/debug/deps/lib-23b06746adb64d7f)

running 1 test
<jemalloc>: /usr/home/somers/src/freebsd.org/src/contrib/jemalloc/include/jemalloc/internal/extent_inlines.h:65: Failed assertion: "szind < SC_NSIZES"
error: test failed, to rerun pass `--test lib`

Caused by:
  process didn't exit successfully: `/usr/home/somers/src/rust/capsicum-rs/target/debug/deps/lib-23b06746adb64d7f 'base::test_ioctl'` (signal: 6, SIGABRT: process abort signal)

CapErr simply served to wrap an io::Error around an enum that mainly just served to tell the user what function he had just called. But the user already knew that. Simpler just to return io::Error directly. The only complication was Directory::open_file, which needs to handle a NulError. I mapped that to io::Error with an ErrorKind of Other.

Fixes #25

Rust 1.63.0 introduces I/O safety. RawFd (just a wrapper around i32) gets replaced by OwnedFd to track file ownership. It's a very nice improvement, and I think capscium should take advantage. https://blog.rust-lang.org/2022/08/11/Rust-1.63.0.html#rust-ownership-for-raw-file-descriptorshandles-io-safety

Capsicum's model is to block access to global namespaces. But important operations like gethostbynbame and sysctlbyname operate on global namespaces only. So to sandbox that, Capsicum uses the technique of privilege separation. Through libcasper(3) it forks child processes to deal with stuff like that. We should provide bindings for libcasper and the most important casper services. I've already got a start on this.

I find CapErr to be confusing. Every type wraps either io::Error or ffi::NulError. The variants mainly serve to tell the user which function returned the error. But the user already knows that. I propose that we use plain io::Result for all functions whose inner error type is an io::Error. And for the few functions with more complicated error types we'll make an enum for each one. That's essentially the approach we take in the Nix crate.

• [ ] the purpose of the crate and use cases should be highlighted
• [ ] documentation should contain less code and more descriptions
• [ ] add docs to all the things
• [ ] add #![deny(missing_docs)] to src/lib.rs