1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
<table class="head">
<tr>
<td class="head-ltitle">PRIV(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">PRIV(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">priv</code> — <span class="Nd">kernel
privilege checking API</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/priv.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">priv_check</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *td</var>, <var class="Fa" style="white-space: nowrap;">int
priv</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">priv_check_cred</code>(<var class="Fa" style="white-space: nowrap;">struct
ucred *cred</var>, <var class="Fa" style="white-space: nowrap;">int
priv</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">priv</code> interfaces check to see if
specific system privileges are granted to the passed thread,
<var class="Fa">td</var>, or credential, <var class="Fa">cred</var>. This
interface replaces the now removed <a class="Xr">suser(9)</a> 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 <var class="Fa">priv</var> argument.</p>
<section class="Ss">
<h2 class="Ss" id="Privilege_Policies"><a class="permalink" href="#Privilege_Policies">Privilege
Policies</a></h2>
<p class="Pp">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
<a class="Xr">jail(2)</a> 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
<a class="Xr">mac(9)</a>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION
NOTES</a></h1>
<p class="Pp">When adding a new privilege check to a code path, first check the
complete list of current privileges in <span class="Pa">sys/priv.h</span> 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
<code class="Fn">prison_priv_check</code>(), which includes a complete list
of privileges granted to the root user in <a class="Xr">jail(2)</a>.</p>
<p class="Pp">Certain catch-all privileges exist, such as
<code class="Dv">PRIV_DRIVER</code>, intended to be used by device drivers,
rather than adding a new driver-specific privilege.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">Typically, 0 will be returned for success, and
<code class="Er">EPERM</code> will be returned on failure. Most consumers of
<code class="Nm">priv</code> 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.</p>
<p class="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 <a class="Xr">stat(2)</a>, 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.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">jail(2)</a>, <a class="Xr">dtrace_priv(4)</a>,
<a class="Xr">mac(9)</a>, <a class="Xr">ucred(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">priv</code> API and implementation were
created by <span class="An">Robert Watson</span> under contract to nCircle
Network Security, Inc.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">November 12, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
