mirror of
https://github.com/RGBCube/serenity
synced 2025-05-16 04:44:58 +00:00
93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
## Name
|
|
|
|
unveil - restrict filesystem access
|
|
|
|
## Synopsis
|
|
|
|
```**c++
|
|
#include <unistd.h>
|
|
|
|
int unveil(const char* path, const char* permissions);
|
|
```
|
|
|
|
## Description
|
|
|
|
`unveil()` manipulates the process veil. The veil is a whitelist of paths on
|
|
the file system the calling process is allowed to access.
|
|
|
|
A process that has not made any `unveil()` calls is allowed to access the whole
|
|
filesystem (subject to the regular permission checks). A process that has made
|
|
one or more `unveil()` calls cannot access any paths except those that were
|
|
explicitly unveiled.
|
|
|
|
Calling `unveil()` allows the process to access the given `path`, which must be
|
|
an absolute path, according to the given `permissions` string, which may
|
|
include the following characters:
|
|
|
|
* `r`: May read a file at this path
|
|
* `w`: May write to a file at this path
|
|
* `x`: May execute a program image at this path
|
|
* `c`: May create or remove a file at this path
|
|
* `b`: May browse directories at this path
|
|
|
|
A single `unveil()` call may specify multiple permission characters at once.
|
|
Subsequent `unveil()` calls may take away permissions from the ones allowed
|
|
earlier for the same file. Note that unveiling a path with any set of
|
|
permissions does not turn off the regular permission checks: access to a file
|
|
which the process has unveiled for itself, but has otherwise no appropriate
|
|
permissions for, will still be rejected. Unveiling a directory allows the
|
|
process to access any files inside the directory.
|
|
|
|
Calling `unveil()` with both `path` and `permissions` set to null locks the
|
|
veil; no further `unveil()` calls are allowed after that.
|
|
|
|
The veil state is reset after the program successfully performs an `execve()`
|
|
call.
|
|
|
|
`unveil()` is intended to be used in programs that want to sandbox themselves,
|
|
either to limit the impact of a possible vulnerability exploitation, or before
|
|
intentionally executing untrusted code.
|
|
|
|
## Return value
|
|
|
|
If successful, returns 0. Otherwise, returns -1 and sets `errno` to describe
|
|
the error.
|
|
|
|
## Errors
|
|
|
|
* `EFAULT`: `path` and/or `permissions` are not null and not in readable
|
|
memory.
|
|
* `EPERM`: The veil is locked, or an attempt to add more permissions for an
|
|
already unveiled path was rejected.
|
|
* `EINVAL`: `path` is not an absolute path, or `permissions` are malformed.
|
|
|
|
All of the usual path resolution errors may also occur.
|
|
|
|
## History
|
|
|
|
The `unveil()` system call was first introduced by OpenBSD.
|
|
|
|
## Examples
|
|
|
|
```c++
|
|
// Allow the process to read from /res:
|
|
unveil("/res", "r");
|
|
|
|
// Allow the process to read, write, and create the config file:
|
|
unveil("/etc/WindowServer.ini", "rwc");
|
|
|
|
// Allow the process to execute Calendar:
|
|
unveil("/bin/Calendar", "x");
|
|
|
|
// Allow the process to browse files from /usr/share:
|
|
unveil("/usr/share", "b");
|
|
|
|
// Disallow any further veil manipulation:
|
|
unveil(nullptr, nullptr);
|
|
```
|
|
|
|
## See also
|
|
|
|
* [`pledge`(2)](pledge.md)
|
|
* [`chroot`(2)](chroot.md)
|
|
* [`Mitigations`(7)](../man7/Mitigations.md)
|