NAME

     priv — kernel privilege checking API

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

     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.

   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, described in mac(9).

IMPLEMENTATION NOTES

     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 privilege.

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.

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.