Provided by: freebsd-manpages_8.0-1_all
priv - kernel privilege checking API
priv_check(struct thread *td, int priv);
priv_check_cred(struct ucred *cred, int priv, int flags);
The priv interfaces check to see if specific system privileges are
granted to the passed thread, td, or credential, cred. This interface
replaces the now removed suser(9) privilege checking interface.
Privileges typically represent rights in one of two categories: the right
to manage a particular component of the system, or an exemption to a
specific policy or access control list. The caller identifies the
desired privilege via the priv argument. The optional flags argument,
flags, is currently unused.
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, described in mac(9).
When adding a new privilege check to a code path, first check the
complete list of current privileges in sys/priv.h to see if one already
exists for the class of privilege required. Only if there is not an
exact match should a new privilege be added to the privilege list. As
privilege numbers becomes encoded in the kernel module ABI, privilege
constants must not be changed as any kernel modules depending on
privileges will then need to be recompiled. When adding 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, intended to be
used by device drivers, rather than adding a new driver-specific
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
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.
jail(2), mac(9), ucred(9)
The priv API and implementation were created by Robert Watson under
contract to nCircle Network Security, Inc.