CAP_ENTER(2)

💖 CAP_ENTER(2) 💖

okay so bestie, we're in the System Calls Manual today and this one is actually iconic. no cap. this is the cap_enter, cap_getmode page — Capability mode system calls ✨

---

📚 LIBRARY

Standard C Library (libc, -lc) 🫶

---

🎀 SYNOPSIS

#include <sys/capsicum.h>

int
cap_enter(void);

int
cap_getmode(u_int *modep);

---

✨ DESCRIPTION ✨

so cap_enter() is the main character here. it places the current process into capability mode, which is a whole mode of execution where processes may only issue system calls that operate on file descriptors, or that read limited global system state. like, that's it. that's the vibe. 💅

access to global name spaces — think file system or IPC name spaces — is prevented. blocked. not invited to the party. 🙈

and if the process is already in a capability mode sandbox? the system call is just a no-op. nothing happens, we move on, periodt.

future process descendants created with fork(2) or pdfork(2) will be placed in capability mode from inception. so the babies are born sandboxed, iykyk 👑

when you combine it with cap_rights_limit(2), cap_ioctls_limit(2), and cap_fcntls_limit(2), cap_enter() may be used to create kernel-enforced sandboxes in which appropriately-crafted applications or application components may be run. that's the dream setup fr fr 🌈

then cap_getmode() — she's the vibes checker. she returns a flag indicating whether or not the process is in a capability mode sandbox. 🦋

---

🌸 RUN-TIME SETTINGS 🌸

if the kern.trap_enotcap sysctl MIB is set to a non-zero value, then for any process executing in a capability mode sandbox, any syscall which results in either an ENOTCAPABLE or ECAPMODE error also generates the synchronous SIGTRAP signal to the thread on the syscall return. 😭

on signal delivery, the si_errno member of the siginfo signal handler parameter is set to the syscall error value, and the si_code member is set to TRAP_CAP.

also go peek at the PROC_TRAPCAP_CTL and PROC_TRAPCAP_STATUS operations of the procctl(2) function for similar per-process functionality. 👀

---

⚠️ CAVEAT ⚠️

ngl, creating effective process sandboxes is a tricky process. it involves identifying the least possible rights required by the process and then passing those rights into the process in a safe manner.

consumers of cap_enter() should also be aware of other inherited rights, such as access to VM resources, memory contents, and other process properties that should be considered. don't sleep on those. 💀

it is advisable to use fexecve(2) to create a runtime environment inside the sandbox that has as few implicitly acquired rights as possible. do that. for me. 🫶

---

💜 RETURN VALUES 💜

the cap_enter() and cap_getmode() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

when the process is in capability mode, cap_getmode() sets the flag to a non-zero value. a zero value means the process is not in capability mode. simple as that bestie ✨

---

🔥 ERRORS 🔥

the cap_enter() and cap_getmode() system calls will fail if:

• [ENOSYS] — The kernel is compiled without:

options CAPABILITY_MODE

the cap_getmode() system call may also return the following error:

• [EFAULT] — Pointer modep points outside the process's allocated address space.

---

👀 SEE ALSO 👀

cap_fcntls_limit(2), cap_ioctls_limit(2), cap_rights_limit(2), fexecve(2), procctl(2), cap_sandboxed(3), capsicum(4), sysctl(9)

---

🦋 HISTORY 🦋

the cap_getmode() system call first appeared in FreeBSD 8.3. support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. we love a legacy 💖

---

👑 AUTHORS 👑

these functions and the capability facility were created by Robert N. M. Watson at the University of Cambridge Computer Laboratory, with support from a grant from Google, Inc. absolute legend behavior, honestly 🌟

---

and that's the whole page bestie!! this was shipped as part of Debian, dated May 5, 2020, and it lives in the CAP_ENTER(2) slot of the manual. go forth and sandbox responsibly 💅✨🎀