Crate pathrs 

libpathrs provides a series of primitives for Linux programs to safely handle path operations inside an untrusted directory tree. There are countless examples of security vulnerabilities caused by bad handling of paths; this library provides an easy-to-use set of VFS APIs to avoid those kinds of issues.

The idea is that a Root handle is like a handle for resolution inside a chroot(2), with Handle being an O_PATH descriptor which you can “upgrade” to a proper File. However this library acts far more efficiently than spawning a new process and doing a full chroot(2) for every operation.

Example

The recommended usage of libpathrs looks something like this:

let (root_path, unsafe_path) = ("/path/to/root", "/etc/passwd");
// Get a root handle for resolution.
let root = Root::open(root_path)?;
// Resolve the path.
let handle = root.resolve(unsafe_path)?;
// Upgrade the handle to a full std::fs::File.
let file = handle.reopen(OpenFlags::O_RDONLY)?;

// Or, in one line:
let file = root.resolve(unsafe_path)?
               .reopen(OpenFlags::O_RDONLY)?;

Kernel Support

At the moment, libpathrs only works on Linux as it was designed around Linux-only APIs that are necessary to provide safe path operations. In future, we plan to expand support for other Unix-like operating systems.

Please consult the markdown documentation for the latest information about what kernel features are supported and recommended minimum kernel versions.

Modules

error

Error types for libpathrs.

flags

Bit-flags for modifying the behaviour of libpathrs.

procfs

Helpers to operate on procfs safely.

Structs

Handle

A handle to an existing inode within a Root.

HandleRef

Borrowed version of Handle.

Root

A handle to the root of a directory tree.

RootRef

Borrowed version of Root.

Enums

InodeType

An inode type to be created with Root::create.