daniel/MontaukOS
1
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement kernel capability model

Browse Source
This commit is contained in:
daniel
2026-08-29 16:53:04 +02:00
parent 9051b8a16e
commit e7646bbbdb
47 changed files with 1507 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files
programs/man/syscalls.2
+147 -35
View File
@@ -3,7 +3,7 @@
syscalls - overview of MontaukOS system calls
.SH DESCRIPTION
MontaukOS provides 176 system calls (numbers 0-184, with numbers
MontaukOS provides 178 system calls (numbers 0-186, with numbers
140-148 reserved) for userspace programs. Syscalls use the x86-64
SYSCALL instruction with the following register convention:
@@ -20,6 +20,66 @@
montauk:: namespace. This page groups syscalls the same way the
kernel source does (one subsystem header per group).
.SH CAPABILITY SECURITY
Privileged authority is stored in kernel-owned process credentials, not
inferred from a process name, PID, executable path, or merely from the
owner name returned by SYS_GETUSER. The owner identity may namespace
per-user resources such as the clipboard, but no owner name implies
administrative authority. The kernel-created init process is
the root of the delegation tree. Login authenticates a user and delegates
the appropriate session capabilities; there is no special "system" user
shortcut in the kernel.
Each process has three uint64_t masks, exposed in ProcInfo:
permitted capabilities owned by the process
effective permitted capabilities accepted by syscall checks
delegable permitted capabilities that may be given to children
Effective and delegable must be subsets of permitted. SYS_SPAWN and the
other ordinary spawn variants give the child no capabilities. A parent
uses SYS_SPAWN_CAPS to make an explicit delegation. Every requested
permitted or delegable bit must be present in the parent's delegable mask,
so a non-delegable grant cannot be propagated through another generation.
Invalid or unauthorized requests return SYS_ERR_PERMISSION (-13).
Capability bits and protected operations are:
CAP_PROCESS_ADMIN kill unrelated processes or whole sessions
CAP_POWER_REQUEST post a graceful shutdown/reboot request
CAP_POWER_CONTROL consume power requests; reset or power off
CAP_SUSPEND enter ACPI sleep
CAP_STORAGE_ADMIN change partitions, mounts, or filesystems
CAP_RAW_STORAGE raw disk reads and writes
CAP_NETWORK_ADMIN change network/Wi-Fi configuration
CAP_SET_TIME set wall-clock time or timezone
CAP_USER_ADMIN manage users/trusted config; override owner at spawn
CAP_DISPLAY_ADMIN set display mode or brightness
CAP_DEVICE_ADMIN claim USB interfaces or change Bluetooth state
CAP_LOG_READ read the kernel log
CAP_SYSTEM_IMAGE write the program images in 0:/os and 0:/apps
CAP_STANDARD_SESSION contains CAP_POWER_REQUEST and CAP_SUSPEND.
CAP_ADMIN_SESSION adds the administrative capabilities above except
CAP_POWER_CONTROL and CAP_SYSTEM_IMAGE. Final shutdown/reset authority is
deliberately retained by login, the trusted session supervisor.
SYS_POWERINFO remains readable without a capability, so the powermgr GUI
and power command are monitors, not privileged power daemons.
CAP_SYSTEM_IMAGE is likewise excluded from every session and from the
"all" wildcard in 0:/config/capabilities.toml, and must be named
explicitly to be granted. Capability grants are keyed on binary path, so
write access to 0:/os or 0:/apps is equivalent to holding whatever those
images are granted the next time a launcher runs them. Partitioning or
formatting a volume is CAP_STORAGE_ADMIN and does not carry it.
The authentication and trusted-service configuration files users.toml,
setup.toml, init.toml, and ssh.toml are readable by ordinary processes but
require CAP_USER_ADMIN to create, replace, delete, or write. The kernel
also protects the 0:/config directory entry against replacement. This
prevents changing a userspace role string from becoming a route to new
kernel authority at the next login or boot.
.SH PROCESS MANAGEMENT
.B SYS_EXIT (0)
Terminate the calling process.
@@ -39,9 +99,18 @@
.B SYS_SPAWN (20)
Spawn a new process from an ELF binary on the VFS. The child inherits
a snapshot of the caller's environment.
a snapshot of the caller's environment but no capabilities.
int montauk::spawn(const char* path, const char* args = nullptr);
.B SYS_SPAWN_CAPS (185)
Spawn a child with explicit permitted, effective, and delegable masks.
The child masks must satisfy the subset rules described under CAPABILITY
SECURITY. Passing a non-null user override additionally requires the
caller to have effective CAP_USER_ADMIN; null inherits the parent owner.
int montauk::spawn_with_caps(
const char* path, const char* args, const char* user,
const montauk::abi::SpawnCapabilities& capabilities);
.B SYS_WAITPID (23)
Block until the given process has exited. Returns 0-255 for a normal
exit, 256 plus the signal number if it was killed or crashed, or 0 if
@@ -64,11 +133,13 @@
.B SYS_PROCLIST (61)
List running processes (pid, parent, state, name, heap usage,
accumulated CPU time).
accumulated CPU time, and permitted/effective/delegable capability masks).
int montauk::proclist(montauk::abi::ProcInfo* buf, int max);
.B SYS_KILL (62)
Terminate another process by PID.
Terminate a process by PID. Any process may terminate one of its own
descendants. Terminating an unrelated process requires
CAP_PROCESS_ADMIN.
int montauk::kill(int pid);
.B SYS_SETSESSION (174)
@@ -79,6 +150,7 @@
.B SYS_KILLSESSION (175)
Terminate all live processes in a process session. Returns the number of
members signalled; repeat until zero to wait for complete teardown.
Requires CAP_PROCESS_ADMIN.
int montauk::killsession(int sessionId);
.B SYS_CHDIR (96)
@@ -93,7 +165,8 @@
.B SYS_SETUSER (92)
Associate a process with a logged-in user name (used by login/session
management).
management and per-user resource isolation). Requires CAP_USER_ADMIN.
The name never grants capabilities or implies administrator status.
int montauk::setuser(int pid, const char* name);
.B SYS_GETUSER (93)
@@ -256,12 +329,14 @@
.B SYS_SETUNIXTIME (153)
Set the system wall clock from a UTC Unix timestamp. Returns 0 on
success or -1 if the timestamp is outside the supported range.
success or -1 if the timestamp is outside the supported range. Requires
CAP_SET_TIME.
int montauk::set_unix_time(int64_t unixSeconds);
.B SYS_SETTZ (90)
Set the system-wide timezone offset, in minutes from UTC.
void montauk::settz(int offset_minutes);
Set the system-wide timezone offset, in minutes from UTC. Requires
CAP_SET_TIME.
int montauk::settz(int offset_minutes);
.B SYS_GETTZ (91)
Get the current timezone offset, in minutes from UTC.
@@ -328,7 +403,8 @@
void montauk::get_netcfg(montauk::abi::NetCfg* out);
.B SYS_SETNETCFG (38)
Set the network configuration (IP, mask, gateway, DNS server).
Set the network configuration (IP, mask, gateway, DNS server). Requires
CAP_NETWORK_ADMIN.
int montauk::set_netcfg(const montauk::abi::NetCfg* cfg);
.B SYS_NETSTATUS (125)
@@ -346,6 +422,7 @@
.B SYS_WIFI_SCAN (158)
Perform a channel scan and block until it finishes or timeoutMs
elapses. Returns the number of results, or -1 if no adapter is ready.
Requires CAP_NETWORK_ADMIN because it changes radio state.
int montauk::wifi_scan(montauk::abi::WifiNetwork* buf,
int maxCount, uint32_t timeoutMs);
@@ -355,16 +432,18 @@
.B SYS_WIFI_CONNECT (160)
Join a network and block until the link is up or the attempt fails.
Requires CAP_NETWORK_ADMIN.
int montauk::wifi_connect(const char* ssid,
const char* password);
.B SYS_WIFI_DISCONNECT (161)
Disconnect from the current Wi-Fi network.
Disconnect from the current Wi-Fi network. Requires CAP_NETWORK_ADMIN.
int montauk::wifi_disconnect();
.B SYS_WIFI_SCAN_START (162)
Start a non-blocking channel scan. Returns 0 if started, 1 if a scan
is already running, or -1 if no adapter is ready.
is already running, or -1 if no adapter is ready. Requires
CAP_NETWORK_ADMIN.
int montauk::wifi_scan_start(uint32_t timeoutMs);
.B SYS_WIFI_RESULTS (163)
@@ -374,7 +453,7 @@
.B SYS_WIFI_CONNECT_ASYNC (164)
Start a non-blocking network join. Observe SYS_WIFI_INFO for progress
and the final result.
and the final result. Requires CAP_NETWORK_ADMIN.
int montauk::wifi_connect_async(const char* ssid,
const char* password);
@@ -450,11 +529,13 @@
int maxCount);
.B SYS_DISPLAYSETMODE (156)
Switch to a mode returned by SYS_DISPLAYMODES.
Switch to a mode returned by SYS_DISPLAYMODES. Requires
CAP_DISPLAY_ADMIN.
int montauk::display_set_mode(int modeIndex);
.B SYS_DISPLAYBRIGHTNESS (157)
Set brightness to 0-100 percent, or pass -1 to query it.
Set brightness to 0-100 percent, or pass -1 to query it. Setting requires
CAP_DISPLAY_ADMIN; querying does not.
int montauk::display_brightness(int percent = -1);
.SH TERMINAL
@@ -478,15 +559,18 @@
.SH POWER MANAGEMENT
.B SYS_RESET (26)
Reboot the system.
[[noreturn]] void montauk::reset();
Reboot the system. Requires CAP_POWER_CONTROL. A successful call does not
return; an unauthorized call returns SYS_ERR_PERMISSION.
int montauk::reset();
.B SYS_SHUTDOWN (27)
Shut down the system.
[[noreturn]] void montauk::shutdown();
Shut down the system. Requires CAP_POWER_CONTROL. A successful call does
not return; an unauthorized call returns SYS_ERR_PERMISSION.
int montauk::shutdown();
.B SYS_SUSPEND (89)
Enter ACPI S3 sleep. Returns after wake, 0 on success.
Enter ACPI S3 sleep. Returns after wake, 0 on success. Requires
CAP_SUSPEND.
int montauk::suspend();
.B SYS_POWER_REQUEST (135)
@@ -494,8 +578,16 @@
posts a pending action (POWER_REQ_SHUTDOWN / POWER_REQ_REBOOT)
then exits; login.elf reads it with POWER_REQ_QUERY
(read-and-clear), runs the shutdown stages, and finally calls
shutdown()/reset(). See montauk::abi::PowerRequestAction.
shutdown()/reset(). Posting requires CAP_POWER_REQUEST; querying and
consuming the request requires CAP_POWER_CONTROL. See
montauk::abi::PowerRequestAction.
A request may also come from inside a session -- the shell's shutdown
builtin posts one. Since login only reads the request after the session
leader exits, the leader polls POWER_REQ_PEEK, a non-destructive read
requiring only CAP_POWER_REQUEST, and exits when one is pending.
int montauk::power_request(int action);
int montauk::power_request_pending();
.B SYS_POWERINFO (149)
Get the CPU power/thermal snapshot (HWP state, throttling,
@@ -507,7 +599,7 @@
.SH KERNEL LOG
.B SYS_LOG (46)
Read from the kernel ring log buffer.
Read from the kernel ring log buffer. Requires CAP_LOG_READ.
int64_t montauk::read_log(char* buf, uint64_t size);
.B SYS_LOG_WRITE (176)
@@ -520,9 +612,20 @@
to the framebuffer console.
.B SYS_SPAWN_REDIR (49)
Spawn a process with its console I/O redirected to the caller.
Spawn a process with its console I/O redirected to the caller. The child
receives no capabilities.
int montauk::spawn_redir(const char* path, const char* args = nullptr);
.B SYS_SPAWN_REDIR_CAPS (186)
Spawn a redirected child with explicit capability masks. It applies the
same subset and parent-delegable checks as SYS_SPAWN_CAPS. An
administrative console explicitly lets its shell delegate selected
capabilities; the shell's executable policy gives each trusted tool a
delegable mask of zero, preventing further propagation.
int montauk::spawn_redir_with_caps(
const char* path, const char* args,
const montauk::abi::SpawnCapabilities& capabilities);
.B SYS_CHILDIO_READ (50)
Read buffered output produced by a redirected child.
int montauk::childio_read(int childPid, char* buf, int maxLen);
@@ -625,37 +728,41 @@
int montauk::partlist(montauk::abi::PartInfo* buf, int max);
.B SYS_DISKREAD (71)
Raw, driver-agnostic sector read from a block device.
Raw, driver-agnostic sector read from a block device. Requires
CAP_RAW_STORAGE.
int64_t montauk::disk_read(int blockDev, uint64_t lba,
uint32_t sectorCount, void* buf);
.B SYS_DISKWRITE (72)
Raw, driver-agnostic sector write to a block device.
Raw, driver-agnostic sector write to a block device. Requires
CAP_RAW_STORAGE.
int64_t montauk::disk_write(int blockDev, uint64_t lba,
uint32_t sectorCount, const void* buf);
.B SYS_GPTINIT (73)
Initialize a fresh GPT partition table on a block device.
Initialize a fresh GPT partition table on a block device. Requires
CAP_STORAGE_ADMIN.
int montauk::gpt_init(int blockDev);
.B SYS_GPTADD (74)
Add a partition to an existing GPT table.
Add a partition to an existing GPT table. Requires CAP_STORAGE_ADMIN.
int montauk::gpt_add(const montauk::abi::GptAddParams* params);
.B SYS_FSMOUNT (75)
Mount a partition's filesystem onto a drive number.
Mount a partition's filesystem onto a drive number. Requires
CAP_STORAGE_ADMIN.
int montauk::fs_mount(int partIndex, int driveNum);
.B SYS_FSFORMAT (76)
Format a partition with a filesystem (FS_TYPE_FAT32 or
FS_TYPE_EXT2).
FS_TYPE_EXT2). Requires CAP_STORAGE_ADMIN.
int montauk::fs_format(const montauk::abi::FsFormatParams* params);
.B SYS_FS_SYNC (134)
Flush all block-device write caches and cleanly unmount
disk-backed volumes ahead of power-off. Returns the number of
volumes unmounted. Part of the graceful shutdown sequence
(see SYS_POWER_REQUEST).
(see SYS_POWER_REQUEST). Requires CAP_STORAGE_ADMIN.
int montauk::fs_sync();
.SH AUDIO
@@ -708,16 +815,18 @@
.SH BLUETOOTH
.B SYS_BTSCAN (84)
Scan for discoverable Bluetooth devices for up to timeoutMs.
Scan for discoverable Bluetooth devices for up to timeoutMs. Requires
CAP_DEVICE_ADMIN because it changes radio state.
int montauk::bt_scan(montauk::abi::BtScanResult* buf, int maxCount,
uint32_t timeoutMs);
.B SYS_BTCONNECT (85)
Connect (and pair/bond if needed) to a device by BD_ADDR.
Connect (and pair/bond if needed) to a device by BD_ADDR. Requires
CAP_DEVICE_ADMIN.
int montauk::bt_connect(const uint8_t* bdAddr);
.B SYS_BTDISCONNECT (86)
Disconnect from a device by BD_ADDR.
Disconnect from a device by BD_ADDR. Requires CAP_DEVICE_ADMIN.
int montauk::bt_disconnect(const uint8_t* bdAddr);
.B SYS_BTLIST (87)
@@ -731,7 +840,8 @@
.B SYS_BTSETADDR (137)
Change the adapter's BD_ADDR (6-byte buffer, byte 0 is the
least-significant octet). Volatile -- apply after the last
controller reset and persist separately to bluetooth.toml.
controller reset and persist separately to bluetooth.toml. Requires
CAP_DEVICE_ADMIN.
int montauk::bt_set_addr(const uint8_t* bdAddr);
.B SYS_BTBONDS (138)
@@ -739,7 +849,8 @@
int montauk::bt_bonds(montauk::abi::BtBondInfo* buf, int maxCount);
.B SYS_BTFORGET (139)
Forget a paired device; it must re-pair next time.
Forget a paired device; it must re-pair next time. Requires
CAP_DEVICE_ADMIN.
int montauk::bt_forget(const uint8_t* bdAddr);
.SH GENERIC USB INTERFACES
@@ -759,7 +870,8 @@
.B SYS_USB_CLAIM (179)
Exclusively claim an unbound interface. Returns a generation-checked handle
owned by the calling process.
owned by the calling process. Requires CAP_DEVICE_ADMIN; subsequent
operations are authorized by ownership of that handle.
int montauk::usb_claim(uint8_t slotId, uint8_t interfaceNumber);
.B SYS_USB_CLOSE (180)