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.

Debian                                           August 30, 2006                                         PRIV(9)