diff options
Diffstat (limited to 'share/man')
-rw-r--r-- | share/man/man9/Makefile | 1 | ||||
-rw-r--r-- | share/man/man9/priv.9 | 115 | ||||
-rw-r--r-- | share/man/man9/suser.9 | 9 |
3 files changed, 124 insertions, 1 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 7c56c97..2b8b5bb 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -188,6 +188,7 @@ MAN= accept_filter.9 \ pmap_zero_page.9 \ printf.9 \ prison_check.9 \ + priv.9 \ pseudofs.9 \ psignal.9 \ random.9 \ diff --git a/share/man/man9/priv.9 b/share/man/man9/priv.9 new file mode 100644 index 0000000..4693769 --- /dev/null +++ b/share/man/man9/priv.9 @@ -0,0 +1,115 @@ +.\"- +.\" Copyright (c) 2006 nCircle Network Security, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert N. M. Watson for the TrustedBSD +.\" Project under contract to nCircle Network Security, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, NCIRCLE NETWORK SECURITY, +.\" INC., OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 30, 2006 +.Dt priv 9 +.Os +.Sh NAME +.Nm priv +.Nd kernel privilege checking API +.Sh SYNOPSIS +.In sys/priv.h +.Ft int +.Fn priv_check "struct thread *td" "int priv" +.Ft int +.Fn priv_check_cred "struct ucred *cred" "int priv" "int flags" +.Sh DESCRIPTION +The +.Xr priv 9 +interfaces check to see if specific system privileges are granted to the +passed thread, +.Va td , +or credential, +.Va cred. +This interface replaces the +.Xr 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 +.Fa priv +argument. +Additional access control context may also be passed using the +.Va flags . +.Ss 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 +.Xr 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 +.Xr mac 9 . +.Sh IMPLEMENTATION NOTES +When adding a new privilege check to a code path, first check the complete +list of current privileges in +.Pa 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 the privilege number becomes encoded in the kernel module ABI, privileges +should only be appended to the list, not inserted in the list, and the list +sort order should not be changed. +.Pp +Certain catch-all privileges exist, such as +.Dv PRIV_DRIVER , +intended to be used by device drivers, rather than adding a new +driver-specific privilege. +.Sh RETURN VALUES +Typically, 0 will be returned for success, and +.Dv EPERM +will be returned on failure. +Most consumers of +.Xr priv 9 +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. +.Pp +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 +.Xr stat 2 , +in which the generation field is optionally zero'd out when insufficient +privilege is not present is highly undesirable, as it results in frequent +privilege checks, and the caller is unable to tell if an access control +failure occured. +.Sh SEE ALSO +.Xr jail 2 , +.Xr mac 9 , +.Xr suser 9 , +.Xr ucred 9 +.Sh AUTHORS +The +.Xr priv 9 +API and implementation were created by Robert Watson under contract to +nCircle Network Security, Inc. diff --git a/share/man/man9/suser.9 b/share/man/man9/suser.9 index fc1d89f..eb05454 100644 --- a/share/man/man9/suser.9 +++ b/share/man/man9/suser.9 @@ -54,6 +54,12 @@ and .Fn suser_cred functions check if the credentials given include superuser powers. .Pp +These interfaces have now been obsoleted by +.Xr priv 9 , +and are provided only for compatibility with third party kernel modules that +have not yet been updated to the new interface. +They should not be used in any new kernel code. +.Pp The .Fn suser function is the most common, and should be used unless special @@ -123,7 +129,8 @@ of some other implementations of in which a TRUE response indicates superuser powers. .Sh SEE ALSO .Xr chroot 2 , -.Xr jail 2 +.Xr jail 2 , +.Xr priv 9 .Sh BUGS The .Fn suser |