share/man/man9/priv.9

   1 .\"-
   2 .\" Copyright (c) 2006 nCircle Network Security, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by Robert N. M. Watson for the TrustedBSD
   6 .\" Project under contract to nCircle Network Security, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR, NCIRCLE NETWORK SECURITY,
  21 .\" INC., OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  23 .\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  24 .\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  25 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  26 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  27 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/share/man/man9/priv.9,v 1.7 2008/09/17 15:49:44 attilio Exp $
  30 .\"
  31 .Dd August 30, 2006
  32 .Dt PRIV 9
  33 .Os
  34 .Sh NAME
  35 .Nm priv
  36 .Nd kernel privilege checking API
  37 .Sh SYNOPSIS
  38 .In sys/priv.h
  39 .Ft int
  40 .Fn priv_check "struct thread *td" "int priv"
  41 .Ft int
  42 .Fn priv_check_cred "struct ucred *cred" "int priv" "int flags"
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 interfaces check to see if specific system privileges are granted to the
  47 passed thread,
  48 .Fa td ,
  49 or credential,
  50 .Fa cred .
  51 This interface replaces the now removed
  52 .Xr suser 9
  53 privilege checking interface.
  54 Privileges typically represent rights in one of two categories: the right to
  55 manage a particular component of the system, or an exemption to a specific
  56 policy or access control list.
  57 The caller identifies the desired privilege via the
  58 .Fa priv
  59 argument.
  60 The optional flags argument,
  61 .Fa flags ,
  62 is currently unused.
  63 .Ss Privilege Policies
  64 Privileges are typically granted based on one of two base system policies:
  65 the superuser policy, which grants privilege based on the effective (or
  66 sometimes real) UID having a value of 0, and the
  67 .Xr jail 2
  68 policy, which permits only certain privileges to be granted to processes in a
  69 jail.
  70 The set of available privileges may also be influenced by the TrustedBSD MAC
  71 Framework, described in
  72 .Xr mac 9 .
  73 .Sh IMPLEMENTATION NOTES
  74 When adding a new privilege check to a code path, first check the complete
  75 list of current privileges in
  76 .Pa sys/priv.h
  77 to see if one already exists for the class of privilege required.
  78 Only if there is not an exact match should a new privilege be added to the
  79 privilege list.
  80 As privilege numbers becomes encoded in the kernel module ABI, privilege
  81 constants must not be changed as any kernel modules depending on privileges
  82 will then need to be recompiled.
  83 When adding a new privilege, be certain to also determine whether it should
  84 be listed in
  85 .Fn prison_priv_check ,
  86 which includes a complete list of privileges granted to the root user in
  87 .Xr jail 2 .
  88 .Pp
  89 Certain catch-all privileges exist, such as
  90 .Dv PRIV_DRIVER ,
  91 intended to be used by device drivers, rather than adding a new
  92 driver-specific privilege.
  93 .Sh RETURN VALUES
  94 Typically, 0 will be returned for success, and
  95 .Er EPERM
  96 will be returned on failure.
  97 Most consumers of
  98 .Nm
  99 will wish to directly return the error code from a failed privilege check to
 100 user space; a small number will wish to translate it to another error code
 101 appropriate to a specific context.
 102 .Pp
 103 When designing new APIs, it is preferable to return explicit errors from a
 104 call if privilege is not granted rather than changing the semantics of the
 105 call but returning success.
 106 For example, the behavior exhibited by
 107 .Xr stat 2 ,
 108 in which the generation field is optionally zero'd out when there is
 109 insufficient privilege is highly undesirable, as it results in frequent
 110 privilege checks, and the caller is unable to tell if an access control
 111 failure occurred.
 112 .Sh SEE ALSO
 113 .Xr jail 2 ,
 114 .Xr mac 9 ,
 115 .Xr ucred 9
 116 .Sh AUTHORS
 117 The
 118 .Nm
 119 API and implementation were created by
 120 .An Robert Watson
 121 under contract to
 122 nCircle Network Security, Inc.