KAUTH(9)

🦋 KAUTH(9) — kernel authorization framework 🦋

Kernel Developer's Manual

🌸 NAME 🌸

• kauth — kernel authorization framework

✨ SYNOPSIS ✨

#include <sys/kauth.h>

💖 DESCRIPTION 💖

Okay bestie, so kauth — kernel authorization, iconic name — is the subsystem that runs all authorization requests inside the kernel. It manages user credentials and rights, and it can be used to implement a system-wide security policy. It also lets external modules plug into the authorization process. No cap.

kauth introduces some new concepts, namely “scopes” and “listeners”, which get detailed together with other useful information for kernel developers in this document. Periodt.

🧸 Types 🧸

Some kauth types include the following:

• kauth_cred_t — represents credentials that can be associated with an object. Includes user- and group-ids (real, effective, and save) as well as group membership information.
• kauth_scope_t — describes a scope.
• kauth_listener_t — describes a listener.

🎀 Terminology 🎀

kauth operates in various “scopes”, each scope holding a group of “listeners”.

Each listener works as a callback for when an authorization request within the scope is made. When such a request is made, all listeners on the scope are passed common information such as the credentials of the request context, an identifier for the requested operation, and possibly other information as well.

Every listener examines the passed information and returns its decision regarding the requested operation. It can either return:

• KAUTH_RESULT_ALLOW — the listener allows the operation.
• KAUTH_RESULT_DENY — the listener denies the operation.
• KAUTH_RESULT_DEFER — the listener defers the decision to other listeners.

For an operation to be allowed, at least one listener has to return KAUTH_RESULT_ALLOW while no other listener returned KAUTH_RESULT_DENY.

Scopes manage listeners that operate in the same aspect of the system.

🌈 Kernel Programming Interface 🌈

kauth exports a KPI that allows developers both of NetBSD and third-party products to authorize requests, access and modify credentials, create and remove scopes and listeners, and perform other miscellaneous operations on credentials. Slay.

🔥 Authorization Requests 🔥

kauth provides a single authorization request routine, which all authorization requests go through. This routine dispatches the request to the listeners of the appropriate scope, together with four optional user-data variables, and returns the augmented result.

It is declared as:

int kauth_authorize_action(kauth_scope_t scope, kauth_cred_t cred, kauth_action_t op, void *arg0, void *arg1, void *arg2, void *arg3)

An authorization request can return one of two possible values:

• 0 (zero) — indicates success; operation is allowed.
• EPERM — indicates failure; operation is denied. See errno(2).

Each scope has its own authorization wrapper, to make it easy to call from various places by eliminating the need to specify the scope and/or cast values. The authorization wrappers are detailed in each scope's section.

kauth_authorize_action() has several special cases, when it will always allow the request. These are for when the request is issued by the kernel itself (indicated by the credentials being either NOCRED or FSCRED), or when there was no definitive decision from any of the listeners (i.e., it was not explicitly allowed or denied) and no security model was loaded.

🫶 Generic Scope 🫶

The generic scope, org.netbsd.kauth.generic, manages generic authorization requests in the kernel.

The authorization wrapper for this scope is declared as:

int kauth_authorize_generic(kauth_cred_t cred, kauth_action_t op, void *arg0)

The following operations are available for this scope:

• KAUTH_GENERIC_ISSUSER — checks whether the credentials belong to the super-user.

Using this request is strongly discouraged and should only be done as a temporary place-holder, as it is breaking the separation between the interface for authorization requests from the back-end implementation. Like, don't make it your whole personality, bestie.

👑 System Scope 👑

The system scope, org.netbsd.kauth.system, manages authorization requests affecting the entire system.

The authorization wrapper for this scope is declared as:

int kauth_authorize_system(kauth_cred_t cred, kauth_action_t op, enum kauth_system_req req, void *arg1, void *arg2, void *arg3)

The following requests are available for this scope:

• KAUTH_SYSTEM_ACCOUNTING — check if enabling/disabling accounting allowed.
• KAUTH_SYSTEM_CHROOT — req can be any of the following:
  • KAUTH_REQ_SYSTEM_CHROOT_CHROOT — check if calling chroot(2) is allowed.
  • KAUTH_REQ_SYSTEM_CHROOT_FCHROOT — check if calling fchroot(2) is allowed.
• KAUTH_SYSTEM_CPU — check CPU-manipulation access. req can be any of the following:
  • KAUTH_REQ_SYSTEM_CPU_SETSTATE — set CPU state, including setting it online or offline.
• KAUTH_SYSTEM_DEBUG — this request concentrates several debugging-related operations.
• KAUTH_SYSTEM_DEVMAPPER — check if operations on the device mapper dm(4) device are allowed.
• KAUTH_SYSTEM_FILEHANDLE — check if file handle operations allowed.
• KAUTH_SYSTEM_FS_EXTATTR — check if starting, stopping, enabling, or disabling extended attributes is allowed. arg1 is a struct mount * of the mount-point on which the operation is performed.
• KAUTH_SYSTEM_FS_SNAPSHOT — check if setting up a file system snapshot is allowed. arg1 is a struct mount * of the mount-point of which the snapshot is taken, and arg2 is a struct vnode * of the vnode where the snapshot is expected to be.
• KAUTH_SYSTEM_FS_QUOTA — check if file system quota operations are allowed.

arg1 is a struct mount * describing the file system mount in question. req can be one of the following:

• KAUTH_REQ_SYSTEM_FS_QUOTA_GET — check if retrieving quota information is allowed. arg2 is a uid_t with the user-id of the user whose quota information is to be retrieved.
• KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFF — check if turning quota on/off is allowed.
• KAUTH_REQ_SYSTEM_FS_QUOTA_MANAGE — check if managing the quota by setting the quota/quota use is allowed. arg2 is a uid_t with the user-id of the user whose quota/quota use is to be set.
• KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMIT — check if bypassing the quota (not enforcing it) is allowed.

• KAUTH_SYSTEM_FS_RESERVEDSPACE — check if using the file system reserved space is allowed.
• KAUTH_SYSTEM_LFS — check if LFS-related operations are allowed. req can be one of the following:
  • KAUTH_REQ_SYSTEM_LFS_MARKV — check if calling lfs_markv(2) is allowed.
  • KAUTH_REQ_SYSTEM_LFS_BMAPV — check if calling lfs_bmapv(2) is allowed.
  • KAUTH_REQ_SYSTEM_LFS_SEGCLEAN — check if calling lfs_segclean(2) is allowed.
  • KAUTH_REQ_SYSTEM_LFS_SEGWAIT — check if calling lfs_segwait(2) is allowed.
  • KAUTH_REQ_SYSTEM_LFS_FCNTL — check if operations on LFS through fcntl(2) are allowed.
• KAUTH_SYSTEM_MAP_VA_ZERO — check if changing the status of memory mapping of virtual address zero is allowed.
• KAUTH_SYSTEM_MODULE — check if a module request is allowed. arg1 is the command.
• KAUTH_SYSTEM_MKNOD — check if creating devices is allowed.
• KAUTH_SYSTEM_MOUNT — check if mount-related operations are allowed. req can be any of the following:
  • KAUTH_REQ_SYSTEM_MOUNT_DEVICE — check if mounting a device is allowed. arg1 is a vnode_t * of the device, arg2 is a struct mount * with the mount-point, and arg3 is a mode_t with the desired access mode.
  • KAUTH_REQ_SYSTEM_MOUNT_GET — check if retrieving information about a mount is allowed. arg1 is a struct mount * with the mount structure in question, arg2 is a void * with file system specific data, if any.
  • KAUTH_REQ_SYSTEM_MOUNT_NEW — check if mounting a new file system is allowed. arg1 is the struct vnode * on which the file system is to be mounted, arg2 is an int with the mount flags, and arg3 is a void * with file system specific data, if any.
  • KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT — checks if unmounting a file system is allowed. arg1 is a struct mount * with the mount in question.
  • KAUTH_REQ_SYSTEM_MOUNT_UPDATE — checks if updating an existing mount is allowed. arg1 is the struct mount * of the existing mount, arg2 is an int with the new mount flags, and arg3 is a void * with file system specific data, if any.
  • KAUTH_REQ_SYSTEM_MOUNT_UMAP — check if mounting the user and group id remapping file system. See mount_umap(8).
• KAUTH_SYSTEM_MQUEUE — check if bypassing permissions on a message queue object are allowed. arg1 is a mqueue_t * describing the message queue.
• KAUTH_SYSTEM_PSET — check processor-set manipulation. req can be any of the following:
  • KAUTH_REQ_SYSTEM_PSET_ASSIGN — change processor-set processor assignment.
  • KAUTH_REQ_SYSTEM_PSET_BIND — bind an LWP to a processor-set.
  • KAUTH_REQ_SYSTEM_PSET_CREATE — create a processor-set.
  • KAUTH_REQ_SYSTEM_PSET_DESTROY — destroy a processor-set.
• KAUTH_SYSTEM_REBOOT — check if rebooting is allowed.
• KAUTH_SYSTEM_SETIDCORE — check if changing coredump settings for set-id processes is allowed.
• KAUTH_SYSTEM_SEMAPHORE — check if access to a kernel semaphore is allowed. arg1 is a ksem_t * describing the semaphore.
• KAUTH_SYSTEM_SWAPCTL — check if privileged swapctl(2) requests are allowed.

KAUTH_SYSTEM_SYSCTL

okay so this one handles everything sysctl(9)-flavored 🍓 — req tells you which specific request it is, and it's one of these:

• KAUTH_REQ_SYSTEM_SYSCTL_ADD — vibe check on whether adding a sysctl(9) node is allowed ✨
• KAUTH_REQ_SYSTEM_SYSCTL_DELETE — can we delete a sysctl(9) node? that's the question 💅
• KAUTH_REQ_SYSTEM_SYSCTL_DESC — is adding a description to a sysctl(9) node allowed? 🎀
• KAUTH_REQ_SYSTEM_SYSCTL_MODIFY — checks if modifying a sysctl(9) node variable is allowed when that node doesn't have a custom sysctl helper function. no helper? then this gatekeeper steps in 🫶
• KAUTH_REQ_SYSTEM_SYSCTL_PRVT — is accessing private sysctl(9) nodes allowed? 🙈

heads up bestie: KAUTH_REQ_SYSTEM_SYSCTL_MODIFY might be deprecated in the future 😭

KAUTH_SYSTEM_SYSVIPC

this one checks SysV IPC related operations. req = the specific request, and it's one of:

• KAUTH_REQ_SYSTEM_SYSVIPC_BYPASS — checks if bypassing a SysV IPC object's permissions is allowed. arg1 is a struct ipc_perm * holding the object's permissions, and arg2 is a mode_t indicating the requested access mode 👑
• KAUTH_REQ_SYSTEM_SYSVIPC_SHM_LOCK — is shared memory locking allowed? 🔒
• KAUTH_REQ_SYSTEM_SYSVIPC_SHM_UNLOCK — is shared memory unlocking allowed? 🔓
• KAUTH_REQ_SYSTEM_SYSVIPC_MSGQ_OVERSIZE — is oversizing a message queue allowed? arg1 is a msglen_t indicating the size of the message buffer, and arg2 is a msglen_t indicating the size of the message queue 📬

KAUTH_SYSTEM_TIME

the time-ops group chat ⏰ — req can be any of:

• KAUTH_REQ_SYSTEM_TIME_ADJTIME — checks if changing the time using adjtime(2) is allowed.
• KAUTH_REQ_SYSTEM_TIME_NTPADJTIME — checks if setting the time using ntp_adjtime(2) is allowed.
• KAUTH_REQ_SYSTEM_TIME_SYSTEM — checks if changing the time (usually via settimeofday(2)) is allowed. arg1 is a struct timespec * with the new time, arg2 is a struct timeval * with the delta from the current time, and arg3 is a bool indicating whether the caller is a device context (e.g. /dev/clockctl) or not. literally all the deets 💖
• KAUTH_REQ_SYSTEM_TIME_RTCOFFSET — checks if changing the RTC offset is allowed.
• KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS — checks if manipulating timecounters is allowed.

KAUTH_SYSTEM_VERIEXEC

checks whether operations on the veriexec(8) subsystem are allowed. req can be one of:

• KAUTH_REQ_SYSTEM_VERIEXEC_ACCESS — is access to the veriexec(8) subsystem allowed? 🦋
• KAUTH_REQ_SYSTEM_VERIEXEC_MODIFY — are modifications to the state of veriexec(8) allowed? ✨

---

🌈 Process Scope 🌈

the process scope, “org.netbsd.kauth.process”, manages all the authorization requests related to processes in the system. it's giving main character energy ngl 💅

the authorization wrapper for this scope is declared as:

int kauth_authorize_process(kauth_cred_t cred, kauth_action_t op, struct proc *p, void *arg1, void *arg2, void *arg3)

and here are all the operations available for this scope 👑

KAUTH_PROCESS_KTRACE

checks whether an object with one set of credentials can ktrace(1) another process p, possibly with a different set of credentials 👀

if arg1 is KAUTH_REQ_PROCESS_KTRACE_PERSISTENT, this checks if persistent tracing can be done. persistent tracing maintains the trace across a set-user-id/set-group-id exec(3), and normally requires privileged credentials. so yeah, fancy tracing = fancy creds 🔥

KAUTH_PROCESS_PROCFS

checks whether the object with the passed credentials can use procfs to access process p 🫶

arg1 is the struct pfsnode * for the target element in the target process, and arg2 is the access type, which can be either KAUTH_REQ_PROCESS_PROCFS_READ, KAUTH_REQ_PROCESS_PROCFS_RW, or KAUTH_REQ_PROCESS_PROCFS_WRITE, indicating control, read, read-write, or write access respectively. yes bestie, the order in that sentence is exactly how it's written, don't come for me 😭

KAUTH_PROCESS_PTRACE

checks whether the object with the passed credentials can use ptrace(2) to access process p. arg1 is the ptrace(2) command 🐛

KAUTH_PROCESS_CANSEE

checks whether an object with one set of credentials can access information about another process, possibly with a different set of credentials 🙈

arg1 indicates the class of information being viewed, and can be either of KAUTH_REQ_PROCESS_CANSEE_ARGS, KAUTH_REQ_PROCESS_CANSEE_ENTRY, KAUTH_REQ_PROCESS_CANSEE_ENV, or KAUTH_REQ_PROCESS_CANSEE_OPENFILES.

KAUTH_PROCESS_SCHEDULER_GETAFFINITY

checks whether viewing the scheduler affinity is allowed 👑

KAUTH_PROCESS_SCHEDULER_SETAFFINITY

checks whether setting the scheduler affinity is allowed ✨

KAUTH_PROCESS_SCHEDULER_GETPARAM

checks whether viewing the scheduler policy and parameters is allowed 🌸

KAUTH_PROCESS_SCHEDULER_SETPARAM

checks whether modifying the scheduler policy and parameters is allowed 💅

KAUTH_PROCESS_SIGNAL

checks whether an object with one set of credentials can post signals to another process 📣

p is the process the signal is being posted to, and arg1 is the signal number.

KAUTH_PROCESS_CORENAME

controls access to process corename 🎀

arg1 can be KAUTH_REQ_PROCESS_CORENAME_GET or KAUTH_REQ_PROCESS_CORENAME_SET, indicating access to read or write the process' corename, respectively.

when modifying the corename, arg2 holds the new corename to be used 🦋

KAUTH_PROCESS_FORK

checks if the process can fork. arg1 is an int indicating how many processes exist on the system at the time of the check 🍴

KAUTH_PROCESS_KEVENT_FILTER

checks whether setting a process kevent(2) filter is allowed 🧚

KAUTH_PROCESS_NICE

checks whether the nice value of p can be changed to arg1 😇

KAUTH_PROCESS_RLIMIT

controls access to process resource limits 📏

arg1 can be KAUTH_REQ_PROCESS_RLIMIT_GET or KAUTH_REQ_PROCESS_RLIMIT_SET, indicating access to read or write the process' resource limits, respectively, or KAUTH_REQ_PROCESS_RLIMIT_BYPASS to check if the limit enforcement can be bypassed 👀

when modifying resource limits, arg2 is the new value to be used and arg3 indicates which resource limit is to be modified.

KAUTH_PROCESS_SETID

check if changing the user- or group-ids, groups, or login-name for p is allowed 🪪

KAUTH_PROCESS_STOPFLAG

check if setting the stop flags for exec(3), exit(3), and fork(2) is allowed 🛑

arg1 indicates the flag, and can be either P_STOPEXEC, P_STOPEXIT, or P_STOPFORK respectively.

---

🦋 Network Scope 🦋

the network scope, “org.netbsd.kauth.network”, manages networking-related authorization requests in the kernel 🌐

the authorization wrapper for this scope is declared as:

int kauth_authorize_network(kauth_cred_t cred, kauth_action_t op, enum kauth_network_req req, void *arg1, void *arg2, void *arg3)

the following operations are available for this scope ⭐

KAUTH_NETWORK_ALTQ

checks if an ALTQ operation is allowed 🚦

req indicates the ALTQ subsystem in question, and can be one of the following:

KAUTH_REQ_NETWORK_ALTQ_AFMAP
KAUTH_REQ_NETWORK_ALTQ_BLUE
KAUTH_REQ_NETWORK_ALTQ_CBQ
KAUTH_REQ_NETWORK_ALTQ_CDNR
KAUTH_REQ_NETWORK_ALTQ_CONF
KAUTH_REQ_NETWORK_ALTQ_FIFOQ
KAUTH_REQ_NETWORK_ALTQ_HFSC
KAUTH_REQ_NETWORK_ALTQ_JOBS
KAUTH_REQ_NETWORK_ALTQ_PRIQ
KAUTH_REQ_NETWORK_ALTQ_RED
KAUTH_REQ_NETWORK_ALTQ_RIO
KAUTH_REQ_NETWORK_ALTQ_WFQ

KAUTH_NETWORK_BIND

checks if a bind(2) request is allowed 🪢

req lets you indicate the type of the request so structuring listeners and callers is easier. supported request types:

• KAUTH_REQ_NETWORK_BIND_PORT — checks if binding to a non-privileged/reserved port is allowed.
• KAUTH_REQ_NETWORK_BIND_PRIVPORT — checks if binding to a privileged/reserved port is allowed. fancy port, fancy permission 💅

KAUTH_NETWORK_FIREWALL

checks if firewall-related operations are allowed 🔥

req indicates the sub-action, and can be one of the following:

• KAUTH_REQ_NETWORK_FIREWALL_FW — modification of packet filtering rules.
• KAUTH_REQ_NETWORK_FIREWALL_NAT — modification of NAT rules.

KAUTH_NETWORK_INTERFACE

checks if network interface-related operations are allowed 🧚

arg1 is (optionally) the struct ifnet * associated with the interface. arg2 is (optionally) an int describing the interface-specific operation. arg3 is (optionally) a pointer to the interface-specific request structure. req indicates the sub-action, and can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_GET — check if retrieving information from the device is allowed.
• KAUTH_REQ_NETWORK_INTERFACE_GETPRIV — check if retrieving privileged information from the device is allowed. 👑
• KAUTH_REQ_NETWORK_INTERFACE_SET — check if setting parameters on the device is allowed.
• KAUTH_REQ_NETWORK_INTERFACE_SETPRIV — check if setting privileged parameters on the device is allowed. 🔥
• KAUTH_REQ_NETWORK_INTERFACE_FIRMWARE — check if manipulating the firmware on a network interface device is allowed. 🧚

ngl this one's important: unless the struct ifnet * for the interface was passed in arg1, there's no way to tell what structure arg3 is. so like… pass arg1, bestie 😭💀

💅 KAUTH_NETWORK_INTERFACE_BRIDGE

Okay so this one checks if operations on the bridge(4) network interface are allowed. Slay.

req can be one of these besties:

• KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_GETPRIV — checks if getting privileges parameters is allowed.
• KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_SETPRIV — checks if setting privileges parameters is allowed.

🧚 KAUTH_NETWORK_INTERFACE_PPP

Checks if operations performed on the ppp(4) network interface are allowed.

req can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_PPP_ADD — checks if adding and enabling a ppp(4) interface to the system is allowed.

🌸 KAUTH_NETWORK_INTERFACE_PVC

Check if operations performed on a PVC device (e.g. en(4)) are allowed. req can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_PVC_ADD — check if adding a PVC device is allowed.

🦋 KAUTH_NETWORK_INTERFACE_SLIP

Checks if operations performed on the sl(4) network interface are allowed.

req can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADD — checks if adding and enabling a sl(4) interface to the system is allowed.

🎀 KAUTH_NETWORK_INTERFACE_STRIP

Checks if operations performed on the strip(4) network interface are allowed.

req can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADD — check if adding and enabling a strip(4) interface to the system is allowed.

⭐ KAUTH_NETWORK_INTERFACE_TUN

Checks if operations performed on the tun(4) network interface are allowed.

req can be one of the following:

• KAUTH_REQ_NETWORK_INTERFACE_TUN_ADD — checks if adding and enabling a tun(4) interface to the system is allowed.

🌈 KAUTH_NETWORK_IPSEC

Check if operations related to ipsec(4) connections are allowed. req can be one of the following:

• KAUTH_REQ_NETWORK_IPSEC_BYPASS — check if bypassing ipsec(4) policy is allowed.

💜 KAUTH_NETWORK_IPV6

Check if IPv6-specific operations are allowed. req can be one of the following:

• KAUTH_REQ_NETWORK_IPV6_HOPBYHOP — check if setting hop-by-hop packet options is allowed.
• KAUTH_REQ_NETWORK_IPV6_JOIN_MULTICAST — check if joining a multicast network is allowed.

💀 KAUTH_NETWORK_FORWSRCRT

Checks whether status of forwarding of source-routed packets can be modified or not. (And yes bestie, the constant really is spelled FORWSRCRT — we do not fix it, we respect it. 🫶)

🍓 KAUTH_NETWORK_NFS

Check if an NFS related operation is allowed.

req can be any of the following:

• KAUTH_REQ_NETWORK_NFS_EXPORT — check if modifying the NFS export table is allowed.
• KAUTH_REQ_NETWORK_NFS_SVC — check if access to the NFS nfssvc(2) syscall is allowed.

👑 KAUTH_NETWORK_ROUTE

Checks if a routing-related request is allowed.

arg1 is the struct rt_msghdr * for the request.

🧚 KAUTH_NETWORK_SMB

Check if operations related to SMB are allowed.

req can be one of the following:

• KAUTH_REQ_NETWORK_SMB_SHARE_ACCESS — check if accessing an SMB share is allowed. arg1 is a struct smb_share * describing the SMB share, and arg2 is a mode_t with the desired access mode.
• KAUTH_REQ_NETWORK_SMB_SHARE_CREATE — check if creating an SMB share is allowed. arg1 is a struct smb_sharespec * describing the share to be created.
• KAUTH_REQ_NETWORK_SMB_VC_ACCESS — check if accessing an SMB VC is allowed. arg1 is a struct smb_vc * describing the SMB VC, and arg2 is a mode_t with the desired access mode.
• KAUTH_REQ_NETWORK_SMB_VC_CREATE — check if creating an SMB VC is allowed. arg1 is a struct smb_vcspec * describing the VC to be created.

🔥 KAUTH_NETWORK_SOCKET

Checks if a socket related operation is allowed.

req allows to indicate the type of the request to structure listeners and callers easier. Supported request types are giving:

• KAUTH_REQ_NETWORK_SOCKET_RAWSOCK — checks if opening a raw socket is allowed.
• KAUTH_REQ_NETWORK_SOCKET_OPEN — checks if opening a socket is allowed. arg1, arg2, and arg3 are all int parameters describing the domain, socket type, and protocol, respectively.
• KAUTH_REQ_NETWORK_SOCKET_CANSEE — checks if looking at the socket passed is allowed. arg1 is a struct socket * describing the socket.
• KAUTH_REQ_NETWORK_SOCKET_DROP — checks if a connection can be dropped. arg1 is a struct socket * describing the socket.
• KAUTH_REQ_NETWORK_SOCKET_SETPRIV — checks if setting privileged socket options is allowed. arg1 is a struct socket * describing the socket, arg2 is a u_long describing the socket option.

---

🖥️ Machine-dependent Scope ✨

The machine-dependent (machdep) scope, “org.netbsd.kauth.machdep”, manages machine-dependent authorization requests in the kernel. Very demure, very platform-specific.

The authorization wrapper for this scope is declared as:

int kauth_authorize_machdep(kauth_cred_t cred, kauth_action_t op, void
*arg0, void *arg1, void *arg2, void *arg3)

The actions on this scope provide a set that may or may not affect all platforms. Below is a list of available actions, along with which platforms are affected by each — iykyk, don't assume your arch has your back. 💅

• KAUTH_MACHDEP_CACHEFLUSH — request to flush the whole CPU cache. Affects m68k Linux emulation.
• KAUTH_MACHDEP_CPU_UCODE_APPLY — request to apply a CPU microcode to a CPU. This is related to CPU_UCODE, see options(4). Affects i386 and xen.
• KAUTH_MACHDEP_IOPERM_GET — request to get the I/O permission level. Affects amd64, i386, xen.
• KAUTH_MACHDEP_IOPERM_SET — request to set the I/O permission level. Affects amd64, i386, xen.
• KAUTH_MACHDEP_IOPL — request to set the I/O privilege level. Affects amd64, i386, xen.
• KAUTH_MACHDEP_LDT_GET — request to get the LDT (local descriptor table). Affects amd64, i386, xen.
• KAUTH_MACHDEP_LDT_SET — request to set the LDT (local descriptor table). Affects amd64, i386, xen.
• KAUTH_MACHDEP_MTRR_GET — request to get the MTRR (memory type range registers). Affects amd64, i386, xen.
• KAUTH_MACHDEP_MTRR_SET — request to set the MTRR (memory type range registers). Affects amd64, i386, xen.
• KAUTH_MACHDEP_NVRAM — request to access (read/write) the NVRAM. Affects i386.
• KAUTH_MACHDEP_PXG — request to start or stop the pxg(4) CPU. arg0 is true or false, respectively. Affects pmax.
• KAUTH_MACHDEP_UNMANAGEDMEM — request to access unmanaged memory. Affects alpha, amd64, arm, i386, powerpc, sh3, vax, x68k, xen.

---

🎮 Device Scope 💖

The device scope, “org.netbsd.kauth.device”, manages authorization requests related to devices on the system. Devices can be, for example, terminals, tape drives, Bluetooth accessories, and any other hardware. Network devices specifically are handled by the network scope — different scope, different vibe.

In addition to the standard authorization wrapper:

int kauth_authorize_device(kauth_cred_t cred, kauth_action_t op, void
*arg0, void *arg1, void *arg2, void *arg3)

this scope provides authorization wrappers for various device types. Obsessed, honestly.

int kauth_authorize_device_tty(kauth_cred_t cred, kauth_action_t op,
struct tty *tty)

Authorizes requests for terminal devices on the system. The third argument, tty, is the terminal device in question. It is passed to the listener as arg0. The second argument, op, is the action and can be one of the following:

• KAUTH_DEVICE_TTY_OPEN — open the terminal device pointed to by tty.
• KAUTH_DEVICE_TTY_PRIVSET — set privileged settings on the terminal device pointed to by tty.
• KAUTH_DEVICE_TTY_STI — use the “TIOCSTI” device ioctl(2), allowing to inject characters into the terminal buffer, simulating terminal input. (Yes, that one. It's giving "typing for you while you're not looking". 💀)
• KAUTH_DEVICE_TTY_VIRTUAL — control the virtual console. tty is the current console tty(4).

int kauth_authorize_device_spec(kauth_cred_t cred, enum kauth_device_req
req, struct vnode *vp)

Authorizes requests for special files, usually disk devices, but also direct memory access, on the system.

It passes KAUTH_DEVICE_RAWIO_SPEC as the action to the listener, and accepts two arguments. req, passed to the listener as arg0, is access requested, and can be one of KAUTH_REQ_DEVICE_RAWIO_SPEC_READ, KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE, or KAUTH_REQ_DEVICE_RAWIO_SPEC_RW, representing read, write, or both read/write access respectively. vp is the vnode of the special file in question, and is passed to the listener as arg1.

⚠️ Bestie, keep in mind that it is the responsibility of the security model developer to check whether the underlying device is a disk or the system memory, using iskmemdev(). Do NOT skip this, fr fr:

if ((vp->v_type == VCHR) &&
    iskmemdev(vp->v_un.vu_specinfo->si_rdev))
        /* system memory access */

int kauth_authorize_device_passthru(kauth_cred_t cred, dev_t dev, u_long
mode, void *data)

Authorizes hardware passthru requests, or user commands passed directly to the hardware. These have the potential of resulting in direct disk and/or memory access. 🚨 Highkey important, no cap.

It passes KAUTH_DEVICE_RAWIO_PASSTHRU as the action to the listener, and accepts three arguments. dev, passed as arg1 to the listener, is the device for which the request is made. mode, passed as arg0 to the listener, is a generic representation of the access mode requested. It can be one or more (binary-OR'd) of the following:

KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ
KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF
KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE
KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF

data, passed as arg2 to the listener, is device-specific data that may be associated with the request.

🦋 Bluetooth Devices 🦋

okay so authorizing stuff for Bluetooth devices? same standard authorization wrapper as always, just with these actions 💖

• KAUTH_DEVICE_BLUETOOTH_BCSP — check if operations on a bcsp(4) device are even allowed, bestie.

arg0 is an enum kauth_device_req and it's one of these:

• KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADD — checks if adding and enabling a bcsp(4) device is allowed ✨

• KAUTH_DEVICE_BLUETOOTH_BTUART — check if operations on a btuart(4) device are allowed.

arg0 is an enum kauth_device_req, one of:

• KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADD — checks if adding and enabling a btuart(4) device is allowed 🎀

• KAUTH_DEVICE_BLUETOOTH_RECV — can we even receive a packet from the device? 👀

arg0 is the packet type. For HCI_CMD_PKT packets, arg1 is the opcode; for HCI_EVENT_PKT packets, arg1 is the event ID; and for HCI_ACLDATA_PKT or HCI_SCODATA_PKT packets, arg1 is the connection handle. iykyk 💅

• KAUTH_DEVICE_BLUETOOTH_SEND — can we send a packet to the device?

arg0 is a struct hci_unit * describing the HCI unit, and arg1 is a hci_cmd_hdr_t * describing the packet header.

• KAUTH_DEVICE_BLUETOOTH_SETPRIV — can privileged settings be changed? 🔥

arg0 is a struct hci_unit * describing the HCI unit, arg1 is a struct btreq * describing the request, and arg2 is a u_long describing the command.

---

🎲 Kernel random device 🎲

authorization actions for the kernel random device, rnd(4) — again, standard authorization wrapper, with these actions:

• KAUTH_DEVICE_RND_ADDDATA — check if adding data to the entropy pool is allowed 🌸
• KAUTH_DEVICE_RND_GETPRIV — check if privileged settings and information can be retrieved
• KAUTH_DEVICE_RND_SETPRIV — check if privileged settings can be changed

---

⌨️ Wscons devices ⌨️

authorization actions relevant to wscons(4), standard wrapper, these actions:

• KAUTH_DEVICE_WSCONS_KEYBOARD_BELL — check if setting the default bell is allowed 🔔
• KAUTH_DEVICE_WSCONS_KEYBOARD_KEYREPEAT — check if setting the default key-repeat is allowed

---

🗂️ Vnode Scope 🗂️

The vnode scope, "org.netbsd.kauth.vnode", authorizes operations made on vnodes representing file system objects. literally its whole personality 💜

The authorization wrapper for this scope is declared as:

int kauth_authorize_vnode(kauth_cred_t cred, kauth_action_t action,
vnode_t *vp, vnode_t *dvp, int fs_decision)

okay so warning time 🚨 this scope is heavily used in file system code, which means it can potentially affect system-wide performance. so there are a few things developers should know before using it, no cap.

First: the action parameter is a bit-mask, and multiple actions can be binary-OR'd and authorized in a single call ✨ two helper functions help generate the action value for a couple of common cases: translating file system access to a kauth action, and checking access to a vnode.

The first one, kauth_mode_to_action(mode_t access_mode), returns a kauth_action_t representing the desired access modes. The other one, kauth_access_action(mode_t access_mode, enum vtype v_type, mode_t file_mode), returns a kauth_action_t suitable for use in many file system access(2) implementations. It calls the aforementioned kauth_mode_to_action(), but before returning it also adds the KAUTH_VNODE_IS_EXEC flag if needed. (Scroll down for what this flag means and how its necessity is determined 👇)

Second: be very careful with adding listeners on this scope, fr fr. A special parameter, fs_decision, lets different file systems instrument different policies without adding their own listener. It's special because it also serves as a fall-back decision when no secmodel(9) is present — which is what prevents a fail-open scenario 😭 It can take either an errno(2) value or "KAUTH_VNODE_REMOTEFS", which means the file system on which the authorization is made is remote and can't give us a fall-back decision. In that case, kauth can only short-circuit the request — but the file system gets the last word if there's no definitive allow or deny decision. main character energy tbh 👑

The value of fs_decision can be hard-coded, or determined by calling an internal function implementing a policy. For the latter case, genfs(9) provides a set of helper functions implementing common policies that file systems can use. Calling convention goes like this:

int error;

error = kauth_authorize_vnode(..., genfs_can_foo(...));

Actions on the vnode scope come in two types: operations and flags 🫶 An operation is similar in concept to actions on other scopes — it represents an operation desired by the caller. A flag is an indicator of additional information about the vnode that a file system can set, so the listener can make a more informed decision.

Actions include the following:

• KAUTH_VNODE_READ_DATA — read file data
• KAUTH_VNODE_LIST_DIRECTORY — read directory listing. identical to the above 👯
• KAUTH_VNODE_WRITE_DATA — write file data
• KAUTH_VNODE_ADD_FILE — add a file to a directory. identical to the above
• KAUTH_VNODE_EXECUTE — execute a file
• KAUTH_VNODE_SEARCH — search (enter) a directory. identical to the above
• KAUTH_VNODE_DELETE — delete a file 💀
• KAUTH_VNODE_APPEND_DATA — append data to a file
• KAUTH_VNODE_ADD_SUBDIRECTORY — add a subdirectory to a directory. identical to the above
• KAUTH_VNODE_READ_TIMES — read the created, last accessed, and last modified times of a file
• KAUTH_VNODE_WRITE_TIMES — modify the created, last accessed, or last modified times of a file
• KAUTH_VNODE_READ_FLAGS — read file flags
• KAUTH_VNODE_WRITE_FLAGS — modify file flags
• KAUTH_VNODE_READ_SYSFLAGS — read file system flags
• KAUTH_VNODE_WRITE_SYSFLAGS — modify file system flags
• KAUTH_VNODE_RENAME — rename a file
• KAUTH_VNODE_CHANGE_OWNERSHIP — change ownership of a file
• KAUTH_VNODE_READ_SECURITY — read the permissions of a file
• KAUTH_VNODE_WRITE_SECURITY — change the permissions of a file, for example by using chmod(2)
• KAUTH_VNODE_READ_ATTRIBUTES — read attributes of a file
• KAUTH_VNODE_WRITE_ATTRIBUTES — modify attributes of a file
• KAUTH_VNODE_READ_EXTATTRIBUTES — read extended attributes of a file
• KAUTH_VNODE_WRITE_EXTATTRIBUTES — modify extended attributes of a file
• KAUTH_VNODE_RETAIN_SUID — check if retaining the set-user-id bit on files after chown(2) is allowed
• KAUTH_VNODE_RETAIN_SGID — check if retaining the set-group-id bit on files after chown(2) is allowed
• KAUTH_VNODE_REVOKE — revoke a file

Flags include the following:

• KAUTH_VNODE_IS_EXEC — the vnode is executable.

The macro FS_OBJECT_CAN_EXEC() can be used to help determine if this flag should be set. This macro determines a file system object to be executable if it's a directory (in which case we say it's searchable) or if it has at least one executable bit set in its mode.

Setting this flag helps a listener know that a vnode is executable, and it's used in implementing privileged access to files and directories while maintaining semantics that prevent execution until a file is marked as an executable. An example of using this in listener code is:

if (privileged) {
        /* Always allow read/write; execute only if executable. */
        if ((action & KAUTH_VNODE_EXECUTE) == 0 ||
            (action & KAUTH_VNODE_IS_EXEC))
                result = KAUTH_RESULT_ALLOW;
}

Finally, the vnode scope authorization wrapper returns EACCES in case of an error, to maintain file system semantics. File systems can override this value if needed 💅

• KAUTH_VNODE_HAS_SYSFLAGS — the file system object represented by the vnode has system flags set
• KAUTH_VNODE_ACCESS — the authorization is advisory only and no actual operation is to be performed. this is not implemented 🚩

---

🔐 Credentials Scope 🔐

The credentials scope, "org.netbsd.kauth.cred", is a special scope used internally by the kauth framework to provide hooking to credential-related operations 👑

It's a "notify-only" scope — it allows hooking operations such as initialization of new credentials, credential inheritance during a fork, and copying and freeing of credentials. The main purpose for this scope is to give a security model a way to control those aforementioned operations, especially when the credentials hold security model-private data 🫶

Notifications are made using the following function, which is internal to kauth:

int kauth_cred_hook(kauth_cred_t cred, kauth_action_t action, void
*arg0, void *arg1)

with the following actions:

• KAUTH_CRED_COPY — cred are the credentials that are being copied. arg0 is a kauth_cred_t representing the destination credentials. That is, the credentials are copied from cred to arg0.
• KAUTH_CRED_FORK — the credentials are being inherited from a parent to a child process during a fork.

cred are the credentials of the lwp context doing the fork, and arg0 and arg1 are both struct proc * of the parent and child processes, respectively.

• KAUTH_CRED_CHROOT — the credentials in cred belong to a process whose root directory is changed through change_root() (see vfs(9)).

Arg0 is the new struct cwdinfo * of the process.

• KAUTH_CRED_FREE — the credentials in cred are being freed. Bye bestie, we hardly knew ye 😭
• KAUTH_CRED_INIT — the credentials in cred are being initialized. Fresh start energy ✨

Since this is a notify-only scope, every single listener is required to return KAUTH_RESULT_ALLOW. No cap, no exceptions — it’s giving mandatory group-chat agreement 💅

🌸 Credentials Accessors and Mutators 🌸

Okay so kauth has a whole little toolkit of accessor and mutator routines to handle kauth_cred_t objects. Iconic, honestly.

The following routines can be used to access and modify the user- and group-ids in a kauth_cred_t:

• uid_t kauth_cred_getuid(kauth_cred_t cred) — returns the real user-id from cred. The actual real one, not the fake one 🫶
• uid_t kauth_cred_geteuid(kauth_cred_t cred) — returns the effective user-id from cred. Effective as in “what you’re actually acting as” 💖
• uid_t kauth_cred_getsvuid(kauth_cred_t cred) — returns the saved user-id from cred. The little backup copy, iykyk 🎀
• void kauth_cred_setuid(kauth_cred_t cred, uid_t uid) — sets the real user-id in cred to uid.
• void kauth_cred_seteuid(kauth_cred_t cred, uid_t uid) — sets the effective user-id in cred to uid.
• void kauth_cred_setsvuid(kauth_cred_t cred, uid_t uid) — sets the saved user-id in cred to uid.
• gid_t kauth_cred_getgid(kauth_cred_t cred) — returns the real group-id from cred.
• gid_t kauth_cred_getegid(kauth_cred_t cred) — returns the effective group-id from cred.
• gid_t kauth_cred_getsvgid(kauth_cred_t cred) — returns the saved group-id from cred.
• void kauth_cred_setgid(kauth_cred_t cred, gid_t gid) — sets the real group-id in cred to gid.
• void kauth_cred_setegid(kauth_cred_t cred, gid_t gid) — sets the effective group-id in cred to gid.
• void kauth_cred_setsvgid(kauth_cred_t cred, gid_t gid) — sets the saved group-id in cred to gid.
• u_int kauth_cred_getrefcnt(kauth_cred_t cred) — returns the reference count for cred. The “how many besties are holding onto this” number 🔥

The following routines can be used to access and modify the group list in a kauth_cred_t:

• int kauth_cred_ismember_gid(kauth_cred_t cred, gid_t gid, int *resultp) — checks if the group-id gid is a member in the group list of cred.

If it is, resultp will be set to one, otherwise, to zero.

The return value is an error code, or zero for success. Very “vibe check: are you in the group chat?” energy 💀

• u_int kauth_cred_ngroups(kauth_cred_t cred) — returns the number of groups in the group list of cred.
• gid_t kauth_cred_group(kauth_cred_t cred, u_int idx) — returns the group-id of the group at index idx in the group list of cred.
• int kauth_cred_setgroups(kauth_cred_t cred, const gid_t *groups, size_t ngroups, uid_t gmuid, enum uio_seg seg) — copies ngroups groups from the array pointed to by groups to the group list in cred, adjusting the number of groups in cred appropriately. seg should be either UIO_USERSPACE or UIO_SYSSPACE, indicating whether groups is a user or kernel space address.

Any groups remaining will be set to an invalid value.

gmuid is unused for now, and to maintain interface compatibility with the Darwin KPI.

The return value is an error code, or zero for success.

• int kauth_cred_getgroups(kauth_cred_t cred, gid_t *groups, size_t ngroups, enum uio_seg seg) — copies ngroups groups from the group list in cred to the buffer pointed to by groups. seg should be either UIO_USERSPACE or UIO_SYSSPACE, indicating whether groups is a user or kernel space address.

The return value is an error code, or zero for success. Slay, but check your error codes 💅

🦋 Credential Private Data 🦋

kauth provides an interface to allow attaching security-model private data to credentials. It’s giving “your creds can have little secrets” ✨

The use of this interface has two parts that can be divided into direct and indirect control of the private-data. Directly controlling the private data is done by using the below routines, while the indirect control is often dictated by events such as process fork, and is handled by listening on the credentials scope (see above).

Attaching private data to credentials works by registering a key to serve as a unique identifier, distinguishing various sets of private data that may be associated with the credentials. Registering, and deregistering, a key is done by using these routines:

• int kauth_register_key(secmodel_t sm, kauth_key_t *keyp) — registers a new key for private data for security model sm. keyp will be used to return the key to be used in further calls.

The function returns 0 on success and an error code (see errno(2)) on failure. Periodt, check your return value 💖

• int kauth_deregister_key(kauth_key_t key) — deregisters private data key key. Bye key, thanks for your service 🎀

Once registered, private data may be manipulated by the following routines:

• void kauth_cred_setdata(kauth_cred_t cred, kauth_key_t key, void *data) — sets private data for key in cred to be data.
• void * kauth_cred_getdata(kauth_cred_t cred, kauth_key_t key) — retrieves private data for key in cred.

Note that it is required to use the above routines every time the private data is changed, i.e., using kauth_cred_getdata() and later modifying the private data should be accompanied by a call to kauth_cred_setdata() with the “new” private data. Fr fr, don’t skip the setter — that’s the whole plot twist 😭

💜 Credential Inheritance and Reference Counting 💜

kauth provides an interface for handling shared credentials. Sharing is caring, but the refcount has to stay correct 🫶

When a kauth_cred_t is first allocated, its reference count is set to 1. However, with time, its reference count can grow as more objects (processes, LWPs, files, etc.) reference it. Main character cred energy: everyone wants a piece 👑

The following routines are available for managing credentials reference counting:

• kauth_cred_t kauth_cred_hold(kauth_cred_t cred) — increases the reference count to cred by one and returns cred verbatim. Same cred, extra hold, no copies 💅
• void kauth_cred_free(kauth_cred_t cred) — decreases the reference count to cred by one.

If the reference count dropped to zero, the memory used by cred will be freed. Last one out turns off the lights 💀

Credential inheritance happens during a fork(2), and is handled by the following function:

void kauth_proc_fork(struct proc *parent, struct proc *child)

When called, it references the parent's credentials from the child, and calls the credentials scope's hook with the KAUTH_CRED_FORK action to allow security model-specific handling of the inheritance to take place. It’s giving “pass the aux, but make it secure” 🔥

🌈 Credentials Memory Management 🌈

Data-structures for credentials, listeners, and scopes are allocated from memory pools managed by the pool(9) subsystem. Pool party, but make it kernel-safe 🧚

The kauth_cred_t objects have their own memory management routines:

• kauth_cred_t kauth_cred_alloc(void) — allocates a new kauth_cred_t, initializes its lock, and sets its reference count to one. Fresh cred, fresh lock, refcount 1 — iconic starter pack ✨

⭐ Conversion Routines ⭐

Sometimes it might be necessary to convert a kauth_cred_t to userland's view of credentials, a struct uucred, or vice versa. Translating between kernel and userland, the bilingual bestie moment 🦋

The following routines are available for these cases:

• void kauth_uucred_to_cred(kauth_cred_t cred, const struct uucred *uucred) — converts userland's view of credentials to a kauth_cred_t.

This includes effective user- and group-ids, a number of groups, and a group list. The reference count is set to one.

Note that kauth will try to copy as many groups as can be held inside a kauth_cred_t. It’s giving “we’ll fit what we can, bestie” 🫶

• void kauth_cred_to_uucred(struct uucred *uucred, const kauth_cred_t cred) — converts kauth_cred_t to userland's view of credentials.

This includes effective user- and group-ids, a number of groups, and a group list.

Note that kauth will try to copy as many groups as can be held inside a struct uucred. Same energy, opposite direction 💖

• int kauth_cred_uucmp(kauth_cred_t cred, struct uucred *uucred) — compares cred with the userland credentials in uucred.

Common values that will be compared are effective user- and group-ids, and the group list. It’s a vibe check, but for credentials 🌸

🎀 Miscellaneous Routines 🎀

Other routines provided by kauth are:

• void kauth_cred_clone(kauth_cred_t cred1, kauth_cred_t cred2) — clones credentials from cred1 to cred2, except for the lock and reference count. Copy the fit, not the lock 🔥
• kauth_cred_t kauth_cred_dup(kauth_cred_t cred) — duplicates cred.

What this routine does is call kauth_cred_alloc() followed by a call to kauth_cred_clone(). Alloc then clone, the classic duo 💅

• kauth_cred_t kauth_cred_copy(kauth_cred_t cred) — works like kauth_cred_dup(), except for a few differences.

If cred already has a reference count of one, it will be returned. Otherwise, a new kauth_cred_t will be allocated and the credentials from cred will be cloned to it. Last, a call to kauth_cred_free() for cred will be done. It’s giving “if you’re solo, stay solo; otherwise make a copy and free the old one” 😭

• kauth_cred_t kauth_cred_get(void) — returns the credentials associated with the current LWP. This does not change the reference count of the resulting kauth_cred_t object. Look, don’t touch the refcount — just vibes 👑

💖 Scope Management 💖

kauth provides routines to manage the creation and deletion of scopes on the system. Scope admin, but make it cute 🎀

Note that the built-in scopes, the “generic” scope and the “process” scope, can't be deleted. They’re permanent residents, no eviction 💀

• kauth_scope_t kauth_register_scope(const char *id, kauth_scope_callback_t cb, void *cookie) — registers a new scope on the system. id is the name of the scope, usually in reverse DNS-like notation. For example, “org.netbsd.kauth.myscope”. cb is the default listener, to which authorization requests for this scope will be dispatched to. cookie is optional user-data that will be passed to all listeners during authorization on the scope. Very “new group chat, here’s the invite link” energy ✨
• void kauth_deregister_scope(kauth_scope_t scope) — deregisters scope from the scopes available on the system, and frees the kauth_scope_t object scope. Archive the chat and free the object, periodt 💅

🧚 Listener Management 🧚

Listeners in kauth are authorization callbacks that are called during an authorization request in the scope which they belong to. They’re the group-chat members who get a vote on every request 🗳️

When an authorization request is made, all listeners associated with a scope are called to allow, deny, or defer the request. It’s giving full council, no skipping anyone.

It is enough for one listener to deny the request in order for the request to be denied; but all listeners are called during an authorization process none-the-less. All listeners are required to allow the request for it to be granted, and in a case where all listeners defer the request — leaving the decision for other listeners — the request is denied. So: one deny = denied, everyone allow = granted, all defer = denied. No cap, that’s the rule 😭

The following KPI is provided for the management of listeners:

• kauth_listener_t kauth_listen_scope(const char *id, kauth_scope_callback_t cb, void *cookie) — creates a new listener on the scope with the id id, setting the default listener to cb. cookie is optional user-data that will be passed to the listener when called during an authorization request. New listener just dropped, and yes she brought snacks 🍓
• void kauth_unlisten_scope(kauth_listener_t listener) — bestie this one removes listener from its scope, guarantees it will not be called ever again, and frees the kauth_listener_t object listener. it's giving closure, periodt 🫶

okay so here's the tea on synchronization 😭 kauth literally provides no means for synchronization within listeners. it is the programmer's responsibility to make sure data used by the listener is properly locked during its use, because it can be accessed simultaneously from the same listener called multiple times. also on you: garbage collection after the listener, possibly freeing any allocated data it used. no cap, that's your job 💅

the common method to do the above is by having a reference count to each listener. on entry to the listener, this reference count should be raised; on exit, lowered. iconic little pattern ngl ✨

during the removal of a listener, first kauth_scope_unlisten() should be called to make sure the listener code will not be entered in the future. then, the code should wait (possibly sleeping) until the reference count drops to zero. when that happens, it is safe to do the final cleanup. slay 🌸

⚠️ listen up: listeners might sleep, so no locks can be held when calling an authorization wrapper. literally do not do it 🙈

---

💖 EXAMPLES 💖

older code had no abstraction of the security model, so most privilege checks looked like this:

if (suser(cred, &acflag) == 0)
        /* allow privileged operation */

using the new interface, you must ask for a specific privilege explicitly. for example, checking whether it's possible to open a socket would look something like this:

if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET,
    KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM,
    IPPROTO_TCP) == 0)
        /* allow opening the socket */

not me being obsessed with how clean that is 😭✨

note that the securelevel implications were also integrated into the kauth framework so you don't have to note anything special in the call to the authorization wrapper — you just have to make sure the security model handles the request as you expect it to. the framework ate and left no crumbs 👑

to do that you can just grep(1) in the relevant security model directory and have a look at the code. iykyk 🔍

---

🦋 EXTENDING KAUTH 🦋

although kauth provides a large set of both detailed and more or less generic requests, it might be needed eventually to introduce more scopes, actions, or requests. growth era fr fr 🌱

• adding a new scope should happen only when an entire subsystem is introduced and it is assumed other parts of the kernel may want to interfere with its inner-workings. when a subsystem that has the potential of impacting the security of the system is introduced, existing security modules must be updated to also handle actions on the newly added scope. no skipping that step bestie 💅
• new actions should be added when sets of operations not covered at all belong in an already existing scope. fills the gap, main character energy ✨
• requests (or sub-actions) can be added as subsets of existing actions when an operation that belongs in an already covered area is introduced. nesting dolls but make it kernel 🎀

📌 note that all additions should include updates to this manual, the security models shipped with NetBSD, and the example skeleton security model. don't leave the docs hanging, that's so not slay 😤

---

🔗 SEE ALSO 🔗

• secmodel(9)

---

🌈 HISTORY 🌈

the kernel authorization framework first appeared in Mac OS X 10.4. a legend was born 💫

the kernel authorization framework in NetBSD first appeared in NetBSD 4.0, and is a clean-room implementation based on Apple TN2127, available at http://developer.apple.com/technotes/tn2005/tn2127.html — go read it, it's giving lore 📖✨

---

💀 NOTES 💀

as kauth in NetBSD is still under active development, it is likely that the ABI, and possibly the API, will differ between NetBSD versions. 🚨

developers are to take notice of this fact in order to avoid building code that expects one version of the ABI and running it in a system with a different one. fr fr do not do this, it will not end well 😭🙈

---

👑 AUTHORS 👑

• Elad Efrat <elad@NetBSD.org> implemented the kernel authorization framework in NetBSD. the blueprint herself 💖
• Jason R. Thorpe <thorpej@NetBSD.org> provided guidance and answered questions about the Darwin implementation. the supportive bestie we all need 🫶

---

and that's the whole page babes!! 🎀✨ this one's from the Debian fam, dated Jul 1, 2025 — go forth and authorize securely, mwah 💅💜