NetBSD/share/man/man9/kauth.9

.\" $NetBSD: kauth.9,v 1.12 2006/09/17 13:11:54 elad Exp $
.\"
.\" Copyright (c) 2005, 2006 Elad Efrat <elad@NetBSD.org>
.\" All rights reserved.
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Elad Efrat.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
.\"
.Dd September 17, 2006
.Dt KAUTH 9
.Os
.Sh NAME
.Nm kauth
.Nd kernel authorization framework
.Sh SYNOPSIS
.In sys/kauth.h
.Sh DESCRIPTION
.Nm ,
or kernel authorization, is the subsystem managing all authorization requests
inside the kernel.
It manages user credentials and rights, and can be used
to implement a system-wide security policy.
It allows external modules to plug-in the authorization process.
.Pp
.Nm
introduces some new concepts, namely
.Dq scopes
and
.Dq listeners ,
which will be detailed together with other useful information for kernel
developers in this document.
.Ss Types
Some
.Nm
types include the following:
.Bl -tag -width "123456"
.It kauth_cred_t
Representing credentials that can be associated with an object.
Includes user- and group-ids (real, effective, and save) as well as group
membership information.
.It kauth_scope_t
Describes a scope.
.It kauth_listener_t
Describes a listener.
.El
.Ss Terminology
.Nm
operates in various
.Dq scopes ,
each scope holding a group of
.Dq listeners .
.Pp
Each listener works as a callback for when an authorization request within the
scope is made.
When such a request is made, all listeners on the scope are passed common
information such as the credentials of the request context, an identifier for
the requested operation, and possibly other information as well.
.Pp
Every listener examines the passed information and returns its decision
regarding the requested operation.
It can either allow, deny, or defer the operation -- in which case, the
decision is left to the other listeners.
.Pp
For an operation to be allowed, all listeners must not return any deny
or defer decisions.
.Pp
Scopes manage listeners that operate in the same aspect of the system.
.Ss Kernel Programming Interface
.Nm
exports a KPI that allows developers both of
.Nx
and third-party products to authorize requests, access and modify credentials,
create and remove scopes and listeners, and perform other miscellaneous operations on
credentials.
.Ss Authorization Requests
.Nm
provides a single authorization request routine, which all authorization
requests go through.
This routine dispatches the request to the listeners of the appropriate scope,
together with four optional user-data variables, and returns the augmented
result.
.Pp
It is declared as
.Pp
.Ft int Fn kauth_authorize_action "kauth_scope_t scope" "kauth_cred_t cred" \
"kauth_action_t op" "void *arg0" "void *arg1" "void *arg2" "void *arg3"
.Pp
An authorization request can return one of two possible values.
Zero indicates success -- the operation is allowed;
.Er EPERM
(see
.Xr errno 2 )
indicates failure -- the operation is denied.
.Pp
Each scope has its own authorization wrapper, to make it easy to call from various
places by eliminating the need to specify the scope and/or cast values.
The authorization wrappers are detailed in each scope's section.
.Ss Generic Scope
The generic scope,
.Dq org.netbsd.kauth.generic ,
manages generic authorization requests in the kernel.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_generic "kauth_cred_t cred" "kauth_action_t op" \
"void *arg0"
.Pp
The following operations are available for this scope:
.Bl -tag -width "123456"
.It Dv KAUTH_GENERIC_ISSUSER
Checks whether the credentials belong to the super-user.
.Pp
Using this request is strongly discouraged and should only be done as a
temporary place-holder, as it is breaking the separation between the
interface for authorization requests from the back-end implementation.
.It Dv KAUTH_GENERIC_CANSEE
Checks whether an object with one set of credentials can access
information about another object, possibly with a different set of
credentials.
.Pp
.Ar arg0
contains the credentials of the object looked at.
.Pp
This request should be issued only in cases where generic credentials
check is required; otherwise it is recommended to use the object-specific
routines.
.El
.Ss System Scope
The system scope,
.Dq org.netbsd.kauth.system ,
manages authorization requests affecting the entire system.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_system "kauth_cred_t cred" \
"kauth_action_t op" "enum kauth_system_req req" "void *arg1" "void *arg2" \
"void *arg3"
.Pp
The following requests are available for this scope:
.Bl -tag -width "123456"
.It Dv KAUTH_SYSTEM_ACCOUNTING
Check if enabling/disabling accounting allowed.
.It Dv KAUTH_SYSTEM_CHROOT
.Ar arg0
can be any of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_CHROOT_CHROOT
Check if calling
.Xr chroot 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_CHROOT_FCHROOT
Check if calling
.Xr fchroot 2
is allowed.
.El
.It Dv KAUTH_SYSTEM_DEBUG
This request concentrates several debugging-related operations.
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_DEBUG_IPKDB
Check if using
.Xr ipkdb 4
is allowed.
.El
.It Dv KAUTH_SYSTEM_FILEHANDLE
Check if filehandle operations allowed.
.It Dv KAUTH_SYSTEM_LKM
Check if an LKM request is allowed.
.Pp
.Ar arg2
is the command.
.It Dv KAUTH_SYSTEM_MKNOD
Check if creating devices is allowed.
.It Dv KAUTH_SYSTEM_RAWIO
This request groups raw access to system resources.
.Pp
.Ar arg0
indicates what is the underlying resource being access, and can be one of the
following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_RAWIO_DISK
The underlying resource is a disk.
.It Dv KAUTH_REQ_SYSTEM_RAWIO_MEMORY
The underlying resource is the machine memory.
.El
.Pp
.Ar arg1
indicates the access requested, and can be one of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_RAWIO_READ
Read access is requested.
.It Dv KAUTH_REQ_SYSTEM_RAWIO_RW
Both read and write access is requested.
.It Dv KAUTH_REQ_SYSTEM_RAWIO_WRITE
Write access is requsted.
.El
.Pp
If the request is for a disk device,
.Ar arg2
should contain a
.Ft struct vnode *
for the vnode in question, and
.Ar arg3
should contain the device number.
.Pp
The behavior if any of the above is not provided is policy-dependent.
.It Dv KAUTH_SYSTEM_REBOOT
Check if rebooting is allowed.
.It Dv KAUTH_SYSTEM_SETIDCORE
Check if changing coredump settings for set-id processes is allowed.
.It Dv KAUTH_SYSTEM_SWAPCTL
Check if privileged
.Xr swapctl 2
requests are allowed.
.It Dv KAUTH_SYSTEM_SYSCTL
This requests operations related to
.Xr sysctl 9 .
.Ar arg1
indicates the specific request and can be one of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD
Check if adding a
.Xr sysctl 9
node is allowed.
.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE
Check if deleting a
.Xr sysctl 9
node is allowed.
.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC
Check if adding description to a
.Xr sysctl 9
node is allowed.
.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT
Check if accessing private
.Xr sysctl 9
nodes is allowed.
.El
.It Dv KAUTH_SYSTEM_TIME
This request groups time-related operations.
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME
Check if changing the time using
.Xr adjtime 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_TIME_BACKWARDS
Check if setting the time backwards is allowed.
.It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME
Check if setting the time using
.Xr ntp_adjtime 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM
Check if changing the time (usually via
.Xr settimeofday 2 )
is allowed.
.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET
Check if changing the RTC offset is allowed.
.El
.El
.Ss Process Scope
The process scope,
.Dq org.netbsd.kauth.process ,
manages authorization requests related to processes in the system.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_process "kauth_cred_t cred" \
"kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \
"void *arg3"
.Pp
The following operations are available for this scope:
.Bl -tag -width "123456"
.It Dv KAUTH_PROCESS_CANSIGNAL
Checks whether an object with one set of credentials can post signals
to another process.
.Pp
.Ar arg1
and
.Ar arg2
contain the credentials
.Ft ( kauth_cred_t )
and the process data
.Ft ( struct proc * )
of the process the signal is posted to, respectively.
.Ar arg3
is the signal to be posted.
.It Dv KAUTH_PROCESS_CANSEE
Checks whether an object with one set of credentials can access
information about another process, possibly with a different set of
credentials.
.It Dv KAUTH_PROCESS_CORENAME
Checks whether the coredump name for the process
.Ar p
can be changed.
.It Dv KAUTH_PROCESS_RESOURCE
Groups authorization requests related to resource management.
.Ar arg0
indicates the sub-action, and can be one of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_PROCESS_RESOURCE_NICE
Checks whether the
.Em nice
value of
.Ar p
can be changed to
.Ar arg2 .
.It Dv KAUTH_REQ_PROCESS_RESOURCE_RLIMIT
Checks whether the
.Em rlimit
value for
.Ar arg3
in
.Ar p
can be set to
.Ar arg2 .
.El
.It Dv KAUTH_PROCESS_SETID
Check if changing the user- or group-ids, groups, or login-name for
.Ar p
is allowed.
.El
.Ss Network Scope
The network scope,
.Dq org.netbsd.kauth.network ,
manages networking-related authorization requests in the kernel.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \
"void *arg0" "void *arg1" "void *arg2" "void *arg3"
.Pp
The following operations are available for this scope:
.Bl -tag -width "123456"
.It Dv KAUTH_NETWORK_ALTQ
Checks if an ALTQ operation is allowed.
.Pp
.Ar arg0
indicates the ALTQ subsystem in question, and can be one of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP
.It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE
.It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ
.It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR
.It Dv KAUTH_REQ_NETWORK_ALTQ_CONF
.It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ
.It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC
.It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ
.It Dv KAUTH_REQ_NETWORK_ALTQ_RED
.It Dv KAUTH_REQ_NETWORK_ALTQ_RIO
.It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ
.El
.It Dv KAUTH_NETWORK_BIND
Checks if a
.Xr bind 2
request is allowed.
.Pp
.Ar arg0
allows to indicate the type of the request to structure listeners and callers
easier.
Supported request types:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT
Checks if binding to a privileged/reserved port is allowed.
.El
.It Dv KAUTH_NETWORK_FIREWALL
Checks if firewall-related operations is allowed.
.Pp
.Ar arg0
indicates the sub-action, and can be one of the following:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_NETWORK_FIREWALL_FW
Modification of packet filtering rules.
.It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT
Modification of NAT rules.
.El
.It Dv KAUTH_NETWORK_FORWSRCRT
Checks whether status of forwarding of source-routed packets can be modified
or not.
.It Dv KAUTH_NETWORK_ROUTE
Checks if a routing-related request is allowed.
.Pp
.Ar arg0
is the
.Ft struct rt_msghdr *
for the request.
.It Dv KAUTH_NETWORK_SOCKET
Checks if a
.Xr socket 2
request is allowed.
.Pp
.Ar arg0
allows to indicate the type of the request to structure listeners and callers
easier.
Supported request types:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK
Checks if opening a raw socket is allowed.
.El
.El
.Ss Machine-dependent Scope
The machine-dependent (machdep) scope,
.Dq org.netbsd.kauth.machdep ,
manages machine-dependent authorization requests in the kernel.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \
"void *arg0" "void *arg1" "void *arg2" "void *arg3"
.Pp
In this scope,
.Ar arg0
always indicates the machine for the request.
Below is the list of available request hierarchy.
.Bl -tag -width "123456"
.It Dv KAUTH_MACHDEP_X86
The request is x86 specific.
.Pp
Available requests as
.Ar arg1
are:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_MACHDEP_X86_IOPL
Checks if IOPL is allowed to be modified.
.It Dv KAUTH_REQ_MACHDEP_X86_IOPERM
Checks if IOPERM is allowed to be modified.
.It Dv KAUTH_REQ_MACHDEP_X86_MTRR_SET
Checks if the MTRR can be set.
.El
.It Dv KAUTH_MACHDEP_X86_64
The request is x86-64 specific.
.Pp
Available requests as
.Ar arg1
are:
.Bl -tag -width "123456"
.It Dv KAUTH_REQ_MACHDEP_X86_64_MTRR_GET
Check if MTRR values can be retrieved.
.El
.El
.Ss Credentials Accessors and Mutators
.Nm
has a variety of accessor and mutator routines to handle
.Ft kauth_cred_t
objects.
.Pp
The following routines can be used to access and modify the user- and
group-ids in a
.Ft kauth_cred_t :
.Bl -tag -width "123456"
.It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred"
Returns the real user-id from
.Ar cred .
.It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred"
Returns the effective user-id from
.Ar cred .
.It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred"
Returns the saved user-id from
.Ar cred .
.It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid"
Sets the real user-id in
.Ar cred
to
.Ar uid .
.It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid"
Sets the effective user-id in
.Ar cred
to
.Ar uid .
.It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid"
Sets the saved user-id in
.Ar cred
to
.Ar uid .
.It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred"
Returns the real group-id from
.Ar cred .
.It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred"
Returns the effective group-id from
.Ar cred .
.It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred"
Returns the saved group-id from
.Ar cred .
.It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid"
Sets the real group-id in
.Ar cred
to
.Ar gid .
.It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid"
Sets the effective group-id in
.Ar cred
to
.Ar gid .
.It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid"
Sets the saved group-id in
.Ar cred
to
.Ar gid .
.It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred"
Return the reference count for
.Ar cred .
.El
.Pp
The following routines can be used to access and modify the group
list in a
.Ft kauth_cred_t :
.Bl -tag -width "123456"
.It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \
"int *resultp"
Checks if the group-id
.Ar gid
is a member in the group list of
.Ar cred .
.Pp
If it is,
.Ar resultp
will be set to one, otherwise, to zero.
.Pp
The return value is an error code, or zero for success.
.It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred"
Return the number of groups in the group list of
.Ar cred .
.It Ft int Fn kauth_cred_group "kauth_cred_t cred" "u_int idx"
Return the group-id of the group at index
.Ar idx
in the group list of
.Ar cred .
.It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "gid_t *groups" \
"size_t ngroups" "uid_t gmuid"
Copy
.Ar ngroups
groups from array pointed to by
.Ar groups
to the group list in
.Ar cred ,
adjusting the number of groups in
.Ar cred
appropriately.
.Pp
Any groups remaining will be set to an invalid value.
.Pp
.Ar gmuid
is unused for now, and to maintain interface compatibility with the Darwin
KPI.
.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \
"size_t ngroups"
Copy
.Ar ngroups
groups from the group list in
.Ar cred
to the buffer pointed to by
.Ar groups .
.Pp
The number of groups in
.Ar cred
will be returned.
.El
.Ss Credentials Inheritance and Reference Counting
.Nm
provides a KPI for handling a
.Ft kauth_cred_t
in shared credentials situations and credential inheritance.
.Pp
When a
.Ft kauth_cred_t
is first allocated, its reference count is set to 1.
However, with time, its reference count can grow as more objects (processes,
LWPs, files, etc.) reference it.
One such case is during a
.Xr fork 2
where the child process and its LWPs inherit the credentials of the parent.
.Pp
To prevent freeing a
.Ft kauth_cred_t
while it is still referenced, the following routines are available to maintain
its reference count:
.Bl -tag -width "123456"
.It Ft void Fn kauth_cred_hold "kauth_cred_t cred"
Increases reference count to
.Ar cred
by one.
.It Ft void Fn kauth_cred_free "kauth_cred_t cred"
Decreases the reference count to
.Ar cred
by one.
.Pp
If the reference count dropped to zero, the memory used by
.Ar cred
will be returned back to the memory pool.
.El
.Ss Credentials Memory Management
Data-structures for credentials, listeners, and scopes are allocated from
memory pools managed by the
.Xr pool 9
subsystem.
.Pp
The
.Ft kauth_cred_t
objects have their own memory management routines:
.Bl -tag -width "123456"
.It Ft kauth_cred_t Fn kauth_cred_alloc "void"
Allocates a new
.Ft kauth_cred_t ,
initializes its lock, and sets its reference count to one.
.El
.Ss Conversion Routines
Sometimes it might be necessary to convert a
.Ft kauth_cred_t
to a predecessing type, such as
.Ft struct pcred
or
.Ft struct ucred ,
or convert credentials passed from userland as a
.Ft struct uucred
to a
.Ft kauth_cred_t .
.Pp
The following routines are available for these cases:
.Bl -tag -width "123456"
.It Ft void Fn kauth_cred_topcred "kauth_cred_t cred" "struct pcred *pcred"
Convert a
.Ft kauth_cred_t
to a
.Ft struct pcred .
.Pp
This includes real and saved user- and group-ids and reference count, copied
from
.Ar cred .
The
.Ar pc_ucred
field in the destination is set to
.Dv NULL .
.It Ft void Fn kauth_cred_toucred "kauth_cred_t cred" "struct ucred *ucred"
Convert a
.Ft kauth_cred_t
to a
.Ft struct ucred .
.Pp
This includes effective user- and group-ids, number of groups, and the group
list from
.Ar cred .
.Pp
Note that
.Nm
will try to copy as many groups as
.Ar ucred
can hold.
.It Ft void Fn kauth_cred_uucvt "kauth_cred_t cred" "const struct uucred *uucred"
Convert userland's view of credentials to a
.Ft kauth_cred_t .
.Pp
This includes effective user- and group-ids, a number of groups, and a group
list.
The reference count is set to one.
.Pp
Note that
.Nm
will try to copy as many groups as can be held inside a
.Ft kauth_cred_t .
The addition of groups will also guarantee order and no duplicates.
.It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred"
Compares
.Ar cred
with the userland credentials in
.Ar uucred .
.Pp
Common values that will be compared are effective user- and group-ids, and
the group list.
.El
.Ss Miscellaneous Routines
Other routines provided by
.Nm
are:
.Bl -tag -width "123456"
.It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2"
Clone credentials from
.Ar cred1
to
.Ar cred2 ,
except for the lock and reference count.
.Pp
.It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred"
Duplicate
.Ar cred .
.Pp
What this routine does is call
.Fn kauth_cred_alloc
followed by a call to
.Fn kauth_cred_clone .
.It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred"
Works like
.Fn kauth_cred_dup ,
except for a few differences.
.Pp
If
.Ar cred
already has a reference count of one, it will be returned.
Otherwise, a new
.Ft kauth_cred_t
will be allocated and the credentials from
.Ar cred
will be cloned to it.
Last, a call to
.Fn kauth_cred_free
for
.Ar cred
will be done.
.It Ft kauth_cred_t Fn kauth_cred_get "void"
Return the credentials associated with the current LWP.
.El
.Ss Scope Management
.Nm
provides routines to manage the creation and deletion of scopes on the
system.
.Pp
Note that the built-in scopes, the
.Dq generic
scope and the
.Dq process
scope, can't be deleted.
.Bl -tag -width "123456"
.It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \
"kauth_scope_callback_t cb" "void *cookie"
Register a new scope on the system.
.Ar id
is the name of the scope, usually in reverse DNS-like notation.
For example,
.Dq org.netbsd.kauth.myscope .
.Ar cb
is the default listener, to which authorization requests for this scope
will be dispatched to.
.Ar cookie
is optional user-data that will be passed to all listeners
during authorization on the scope.
.It Ft void Fn kauth_deregister_scope "kauth_scope_t scope"
Deregister
.Ar scope
from the scopes available on the system.
.El
.Ss Listener Management
Listeners in
.Nm
are authorization callbacks that are called during an authorization
request in the scope which they belong to.
.Pp
When an authorization request is made, all listeners associated with
a scope are called to allow, deny, or defer the request.
.Pp
It is enough for one listener to deny the request in order for the
request to be denied; but all listeners are called during an authorization
process none-the-less.
All listeners are required to allow the request for it to be granted,
and in a case where all listeners defer the request -- leaving the decision
for other listeners -- the request is denied.
.Pp
The following KPI is provided for the management of listeners:
.Bl -tag -width "123456"
.It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \
"kauth_scope_callback_t cb" "void *cookie"
Create a new listener on the scope with the id
.Ar id ,
setting the default listener to
.Ar cb .
.\".Ar cookie
.\"is optional user-data that will be passed to the listener when called
.\"during an authorization request.
.It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener"
Remove
.Ar listener
from the scope which it belongs to.
.Pp
Effectively what this does is is remove the callback from the chain of
functions to be called when an authorization request is made, preventing
from the listener from being entered in the future.
.El
.Pp
.Nm
provides no means for synchronization within listeners.
It is the the programmer's responsibility to make sure data used by the
listener is properly locked during its use, as it can be accessed
simultaneously from the same listener called multiple times.
It is also the programmer's responsibility to do garbage collection after
the listener, possibly freeing any allocated data it used.
.Pp
The common method to do the above is by having a reference count to
each listener.
On entry to the listener, this reference count should be raised, and
on exit -- lowered.
.Pp
During the removal of a listener, first
.Fn kauth_scope_unlisten
should be called to make sure the listener code will not be entered in
the future.
Then, the code should wait (possibly sleeping) until the reference count
drops to zero.
When that happens, it is safe to do the final cleanup.
.Pp
Listeners might sleep, so no locks can be held when calling an authorization
wrapper.
.\".Sh EXAMPLES
.\" .Sh SEE ALSO
.Sh HISTORY
The kernel authorization framework first appeared in Mac OS X 10.4.
.Pp
The kernel authorization framework in
.Nx
first appeared in
.Nx 4.0 ,
and is a clean-room implementation based on Apple TN2127, available at
http://developer.apple.com/technotes/tn2005/tn2127.html
.Sh AUTHORS
.An Elad Efrat Aq elad@NetBSD.org
implemented the kernel authorization framework in
.Nx .
.Pp
.An Jason R. Thorpe Aq thorpej@NetBSD.org
provided guidance and answered questions about the Darwin implementation.
.Sh ONE MORE THING
The
.Nm
framework is dedicated to Brian Mitchell, one of the most talented people
I know.
Thanks for everything.