903 lines
26 KiB
Groff
903 lines
26 KiB
Groff
.\" $NetBSD: kauth.9,v 1.31 2006/10/30 21:36:36 wiz 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 October 30, 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
|
|
.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
|
|
.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
|
|
.It Dv KAUTH_SYSTEM_ACCOUNTING
|
|
Check if enabling/disabling accounting allowed.
|
|
.It Dv KAUTH_SYSTEM_CHROOT
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.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.
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.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 arg1
|
|
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 req
|
|
indicates what is the underlying resource being access, and can be one of the
|
|
following:
|
|
.Bl -tag
|
|
.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
|
|
.It Dv KAUTH_REQ_SYSTEM_RAWIO_READ
|
|
Read access is requested.
|
|
.It Dv KAUTH_REQ_SYSTEM_RAWIO_RW
|
|
Both read and write access are requested.
|
|
.It Dv KAUTH_REQ_SYSTEM_RAWIO_WRITE
|
|
Write access is requested.
|
|
.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 req
|
|
indicates the specific request and can be one of the following:
|
|
.Bl -tag
|
|
.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.
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.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
|
|
.It Dv KAUTH_PROCESS_CANSIGNAL
|
|
Checks whether an object with one set of credentials can post signals
|
|
to another process.
|
|
.Pp
|
|
.Ar p
|
|
is the process the signal is being posted to, and
|
|
.Ar arg1
|
|
is the signal number.
|
|
.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
|
|
.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" \
|
|
"enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3"
|
|
.Pp
|
|
The following operations are available for this scope:
|
|
.Bl -tag
|
|
.It Dv KAUTH_NETWORK_ALTQ
|
|
Checks if an ALTQ operation is allowed.
|
|
.Pp
|
|
.Ar req
|
|
indicates the ALTQ subsystem in question, and can be one of the following:
|
|
.Pp
|
|
.Bl -tag -compact
|
|
.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_JOBS
|
|
.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 req
|
|
allows to indicate the type of the request to structure listeners and callers
|
|
easier.
|
|
Supported request types:
|
|
.Bl -tag
|
|
.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 are allowed.
|
|
.Pp
|
|
.Ar req
|
|
indicates the sub-action, and can be one of the following:
|
|
.Bl -tag
|
|
.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_INTERFACE
|
|
Checks if network interface-related operations are allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
is (optionally) the
|
|
.Ft struct ifnet *
|
|
associated with the interface.
|
|
.Ar arg2
|
|
is (optionally) an
|
|
.Ft int
|
|
describing the interface-specific operation.
|
|
.Ar arg3
|
|
is (optionally) a pointer to the interface-specific request structure.
|
|
.Ar req
|
|
indicates the sub-action, and can be one of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_NETWORK_INTERFACE_GET
|
|
Check if retrieving information from the device is allowed.
|
|
.It Dv KAUTH_REQ_NETWORK_INTERFACE_GETPRIV
|
|
Check if retrieving privileged information from the device is allowed.
|
|
.It Dv KAUTH_REQ_NETWORK_INTERFACE_SET
|
|
Check if setting parameters on the device is allowed.
|
|
.It Dv KAUTH_REQ_NETWORK_INTERFACE_SETPRIV
|
|
Check if setting privileged parameters on the device is allowed.
|
|
.El
|
|
.Pp
|
|
Note that unless the
|
|
.Ft struct ifnet *
|
|
for the interface was passed in
|
|
.Ar arg1 ,
|
|
there's no way to tell what structure
|
|
.Ar arg3
|
|
is.
|
|
.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 arg1
|
|
is the
|
|
.Ft struct rt_msghdr *
|
|
for the request.
|
|
.It Dv KAUTH_NETWORK_SOCKET
|
|
Checks if a socket related operation is allowed.
|
|
.Pp
|
|
.Ar req
|
|
allows to indicate the type of the request to structure listeners and callers
|
|
easier.
|
|
Supported request types:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK
|
|
Checks if opening a raw socket is allowed.
|
|
.It Dv KAUTH_REQ_NETWORK_SOCKET_OPEN
|
|
Checks if opening a socket is allowed.
|
|
.Ar arg1 , arg2 ,
|
|
and
|
|
.Ar arg3
|
|
are all
|
|
.Ft int
|
|
parameters describing the domain, socket type, and protocol,
|
|
respectively.
|
|
.It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE
|
|
Checks if looking at the socket passed is allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
is a
|
|
.Ft struct socket *
|
|
describing the socket.
|
|
.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" \
|
|
"enum kauth_machdep_req req" "void *arg1" "void *arg2" "void *arg3"
|
|
.Pp
|
|
In this scope,
|
|
.Ar req
|
|
always indicates the machine for the request.
|
|
Below is the list of available request hierarchy.
|
|
.Bl -tag
|
|
.It Dv KAUTH_MACHDEP_X86
|
|
The request is x86 specific.
|
|
.Pp
|
|
Available requests as
|
|
.Ar arg1
|
|
are:
|
|
.Bl -tag
|
|
.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
|
|
.It Dv KAUTH_REQ_MACHDEP_X86_64_MTRR_GET
|
|
Check if MTRR values can be retrieved.
|
|
.El
|
|
.El
|
|
.Ss Device Scope
|
|
The device scope,
|
|
.Dq org.netbsd.kauth.device ,
|
|
manages authorization requests related to devices on the system.
|
|
Devices can be, for example, terminals, tape drives, and any other hardware.
|
|
Network devices specifically are handled by the
|
|
.Em network
|
|
scope.
|
|
.Pp
|
|
This scope has an authorization routine per device class on the system.
|
|
.Pp
|
|
.Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \
|
|
"struct tty *tty"
|
|
.Pp
|
|
Authorizes requests for
|
|
.Em terminal devices
|
|
on the system.
|
|
The third argument,
|
|
.Ar tty ,
|
|
is the terminal device in question.
|
|
The second argument is one of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_DEVICE_TTY_OPEN
|
|
Open the terminal device pointed to by
|
|
.Ar tty .
|
|
.It Dv KAUTH_DEVICE_TTY_PRIVSET
|
|
Set privileged settings on the terminal device pointed to by
|
|
.Ar tty .
|
|
.It Dv KAUTH_DEVICE_PASSTHRU
|
|
Pass a user command directly to a hardware device.
|
|
.Pp
|
|
.Em NOTE :
|
|
Depending on the device, this can result in direct memory and/or disk access.
|
|
.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
|
|
.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
|
|
.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
|
|
.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
|
|
.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 userland's view of credentials, a
|
|
.Ft struct uucred ,
|
|
or vice versa.
|
|
.Pp
|
|
The following routines are available for these cases:
|
|
.Bl -tag
|
|
.It Ft void Fn kauth_uucred_to_cred "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 .
|
|
.It Ft void Fn kauth_cred_to_uucred "struct uucred *uucred" "const kauth_cred_t cred"
|
|
Convert
|
|
.Ft kauth_cred_t
|
|
to userland's view of credentials.
|
|
.Pp
|
|
This includes effective user- and group-ids, a number of groups, and a group
|
|
list.
|
|
.Pp
|
|
Note that
|
|
.Nm
|
|
will try to copy as many groups as can be held inside a
|
|
.Ft struct uucred .
|
|
.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
|
|
.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
|
|
.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
|
|
.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
|
|
.Xr secmodel 9
|
|
.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.
|