PRIV(9)

💖 PRIV(9) — kernel privilege checking API 💖

okay bestie, welcome to the priv(9) page from the Kernel Developer's Manual ✨ this is the whole tea on how the kernel decides who's allowed to do what, and honestly? it's giving gatekeeper (affectionate). let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <sys/priv.h>

int
priv_check(struct thread *td, int priv);

int
priv_check_cred(struct ucred *cred, int priv, int flags);

---

🌸 DESCRIPTION 🌸

so the priv interfaces are the vibe check for privileges 💅 they look at the thread you passed in, td, or the credential you passed in, cred, and they're like "hmm, are you allowed to do this?" This interface replaced the now-removed suser(9) privilege checking interface — rip bozo, we don't do that anymore 😌

Privileges typically represent rights in one of two categories, no cap:

• the right to manage a particular component of the system, or
• an exemption to a specific policy or access control list.

The caller tells the kernel which privilege it wants via the priv argument. The optional flags argument, flags, is currently unused — it's just... there. sitting pretty. iconic but unemployed 🎀

👑 Privilege Policies 👑

Privileges are typically granted based on one of two base system policies:

• the superuser policy, which grants privilege based on the effective (or sometimes real) UID having a value of 0, and
• the jail(2) policy, which permits only certain privileges to be granted to processes in a jail.

The set of available privileges may also be influenced by the TrustedBSD MAC Framework, which is described over in mac(9) 🦋

---

🛠️ IMPLEMENTATION NOTES 🛠️

listen up, this part is important and I need you to actually read it, bestie 😭

When you're adding a new privilege check to a code path, first go check the complete list of current privileges in sys/priv.h and see if one already exists for the class of privilege you need. Only if there is not an exact match should a new privilege be added to the privilege list. 🔍

As privilege numbers become encoded in the kernel module ABI, privilege constants must not be changed — because any kernel modules depending on privileges will then need to be recompiled. Not it. 🙈

When you do add a new privilege, be certain to also determine whether it should be listed in prison_priv_check(), which includes a complete list of privileges granted to the root user in jail(2) 👑

Certain catch-all privileges exist, such as PRIV_DRIVER, which is intended to be used by device drivers, rather than adding a new driver-specific privilege. main character energy for a catch-all ngl 💀

---

🌈 RETURN VALUES 🌈

Typically, 0 will be returned for success, and EPERM will be returned on failure ✨ Most consumers of priv will wish to directly return the error code from a failed privilege check to user space; a small number will wish to translate it to another error code appropriate to a specific context.

When designing new APIs, it is preferable to return explicit errors from a call if privilege is not granted rather than changing the semantics of the call but returning success 🫶

For example, the behavior exhibited by stat(2), in which the generation field is optionally zero'd out when there is insufficient privilege, is highly undesirable, as it results in frequent privilege checks, and the caller is unable to tell if an access control failure occurred. do not do this. I'm literally begging. 😭

---

👀 SEE ALSO 👀

• jail(2)
• mac(9)
• ucred(9)

---

💜 AUTHORS 💜

The priv API and implementation were created by Robert Watson under contract to nCircle Network Security, Inc. — shoutout to the legend, we stan 💖

---

and that's the whole page bestie!! this one came from Debian, dated August 30, 2006 — vintage, retro, lowkey a classic 🎀 go check your privileges, stay unproblematic, and don't change those constants fr fr 💅✨