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$ 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 44The 45.Nm 46interfaces check to see if specific system privileges are granted to the 47passed thread, 48.Fa td , 49or credential, 50.Fa cred . 51This interface replaces the now removed 52.Xr suser 9 53privilege checking interface. 54Privileges typically represent rights in one of two categories: the right to 55manage a particular component of the system, or an exemption to a specific 56policy or access control list. 57The caller identifies the desired privilege via the 58.Fa priv 59argument. 60The optional flags argument, 61.Fa flags , 62is currently unused. 63.Ss Privilege Policies 64Privileges are typically granted based on one of two base system policies: 65the superuser policy, which grants privilege based on the effective (or 66sometimes real) UID having a value of 0, and the 67.Xr jail 2 68policy, which permits only certain privileges to be granted to processes in a 69jail. 70The set of available privileges may also be influenced by the TrustedBSD MAC 71Framework, described in 72.Xr mac 9 . 73.Sh IMPLEMENTATION NOTES 74When adding a new privilege check to a code path, first check the complete 75list of current privileges in 76.Pa sys/priv.h 77to see if one already exists for the class of privilege required. 78Only if there is not an exact match should a new privilege be added to the 79privilege list. 80As privilege numbers becomes encoded in the kernel module ABI, privilege 81constants must not be changed as any kernel modules depending on privileges 82will then need to be recompiled. 83When adding a new privilege, be certain to also determine whether it should 84be listed in 85.Fn prison_priv_check , 86which includes a complete list of privileges granted to the root user in 87.Xr jail 2 . 88.Pp 89Certain catch-all privileges exist, such as 90.Dv PRIV_DRIVER , 91intended to be used by device drivers, rather than adding a new 92driver-specific privilege. 93.Sh RETURN VALUES 94Typically, 0 will be returned for success, and 95.Er EPERM 96will be returned on failure. 97Most consumers of 98.Nm 99will wish to directly return the error code from a failed privilege check to 100user space; a small number will wish to translate it to another error code 101appropriate to a specific context. 102.Pp 103When designing new APIs, it is preferable to return explicit errors from a 104call if privilege is not granted rather than changing the semantics of the 105call but returning success. 106For example, the behavior exhibited by 107.Xr stat 2 , 108in which the generation field is optionally zero'd out when there is 109insufficient privilege is highly undesirable, as it results in frequent 110privilege checks, and the caller is unable to tell if an access control 111failure occurred. 112.Sh SEE ALSO 113.Xr jail 2 , 114.Xr mac 9 , 115.Xr ucred 9 116.Sh AUTHORS 117The 118.Nm 119API and implementation were created by 120.An Robert Watson 121under contract to 122nCircle Network Security, Inc. 123