1395 lines
38 KiB
Groff
1395 lines
38 KiB
Groff
.\" $NetBSD: kauth.9,v 1.71 2008/09/23 22:40:46 pooka 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. 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 24, 2008
|
|
.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.
|
|
.Pp
|
|
.Fn kauth_authorize_action
|
|
has several special cases, when it will always allow the request.
|
|
These are for when the request is issued by the kernel itself (indicated by the
|
|
credentials being either
|
|
.Dv NOCRED
|
|
or
|
|
.Dv FSCRED ) ,
|
|
or when there was no definitive decision from any of the listeners (i.e., it
|
|
was not explicitly allowed or denied) and no security model was loaded.
|
|
.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_CPU
|
|
Check CPU-manipulation access.
|
|
.Pp
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_SYSTEM_CPU_SETSTATE
|
|
Set CPU state, including setting it online or offline.
|
|
.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_MOUNT
|
|
Check if mount-related operations are allowed.
|
|
.Pp
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_SYSTEM_MOUNT_GET
|
|
Check if retrieving information about a mount is allowed.
|
|
.Ar arg1
|
|
is a
|
|
.Ft struct mount *
|
|
with the mount structure in question,
|
|
.Ar arg2
|
|
is a
|
|
.Ft void *
|
|
with file-system specific data, if any.
|
|
.It Dv KAUTH_REQ_SYSTEM_MOUNT_NEW
|
|
Check if mounting a new file-system is allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
is the
|
|
.Ft struct vnode *
|
|
on which the file-system is to be mounted,
|
|
.Ar arg2
|
|
is an
|
|
.Ft int
|
|
with the mount flags, and
|
|
.Ar arg3
|
|
is a
|
|
.Ft void *
|
|
with file-system specific data, if any.
|
|
.It Dv KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT
|
|
Checks if unmounting a file-system is allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
is a
|
|
.Ft struct mount *
|
|
with the mount in question.
|
|
.It Dv KAUTH_REQ_SYSTEM_MOUNT_UPDATE
|
|
Checks if updating an existing mount is allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
is the
|
|
.Ft struct mount *
|
|
of the existing mount,
|
|
.Ar arg2
|
|
is an
|
|
.Ft int
|
|
with the new mount flags, and
|
|
.Ar arg3
|
|
is a
|
|
.Ft void *
|
|
with file-system specific data, if any.
|
|
.El
|
|
.It Dv KAUTH_SYSTEM_PSET
|
|
Check processor-set manipulation.
|
|
.Pp
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_SYSTEM_PSET_ASSIGN
|
|
Change processor-set processor assignment.
|
|
.It Dv KAUTH_REQ_SYSTEM_PSET_BIND
|
|
Bind an LWP to a processor-set.
|
|
.It Dv KAUTH_REQ_SYSTEM_PSET_CREATE
|
|
Create a processor-set.
|
|
.It Dv KAUTH_REQ_SYSTEM_PSET_DESTROY
|
|
Destroy a processor-set.
|
|
.El
|
|
.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_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.
|
|
.Pp
|
|
.Ar arg1
|
|
is a
|
|
.Ft struct timespec *
|
|
with the new time,
|
|
.Ar arg2
|
|
is a
|
|
.Ft struct timeval *
|
|
with the delta from the current time,
|
|
.Ar arg3
|
|
is a
|
|
.Ft bool
|
|
indicating whether the caller is a device context (eg.
|
|
.Pa /dev/clockctl )
|
|
or not.
|
|
.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET
|
|
Check if changing the RTC offset is allowed.
|
|
.It Dv KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS
|
|
Check if manipulating timecounters 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_KTRACE
|
|
Checks whether an object with one set of credentials can
|
|
.Xr ktrace 1
|
|
another process
|
|
.Ar p ,
|
|
possibly with a different set of credentials.
|
|
.Pp
|
|
If
|
|
.Ar arg1
|
|
is
|
|
.Dv KAUTH_REQ_PROCESS_KTRACE_PERSISTENT ,
|
|
this checks if persistent tracing can be done.
|
|
Persistent tracing maintains the trace across a set-user-id/set-group-id
|
|
.Xr exec 2 ,
|
|
and normally requires privileged credentials.
|
|
.It Dv KAUTH_PROCESS_PROCFS
|
|
Checks whether object with passed credentials can use
|
|
.Em procfs
|
|
to access process
|
|
.Ar p .
|
|
.Pp
|
|
.Ar arg1
|
|
is the
|
|
.Ft struct pfsnode *
|
|
for the target element in the target process, and
|
|
.Ar arg2
|
|
is the access type, which can be either
|
|
.Dv KAUTH_REQ_PROCESS_PROCFS_CTL ,
|
|
.Dv KAUTH_REQ_PROCESS_PROCFS_READ ,
|
|
.Dv KAUTH_REQ_PROCESS_PROCFS_RW ,
|
|
or
|
|
.Dv KAUTH_REQ_PROCESS_PROCFS_WRITE ,
|
|
indicating
|
|
.Em control ,
|
|
.Em read ,
|
|
.Em read-write ,
|
|
or
|
|
.Em write
|
|
access respectively.
|
|
.It Dv KAUTH_PROCESS_PTRACE
|
|
Checks whether object with passed credentials can use
|
|
.Xr ptrace 2
|
|
to access process
|
|
.Ar p .
|
|
.Pp
|
|
.Ar arg1
|
|
is the
|
|
.Xr ptrace 2
|
|
command.
|
|
.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.
|
|
.Pp
|
|
.Ar arg1
|
|
indicates the class of information being viewed, and can either of
|
|
.Dv KAUTH_REQ_PROCESS_CANSEE_ARGS ,
|
|
.Dv KAUTH_REQ_PROCESS_CANSEE_ENTRY ,
|
|
.Dv KAUTH_REQ_PROCESS_CANSEE_ENV ,
|
|
or
|
|
.Dv KAUTH_REQ_PROCESS_CANSEE_OPENFILES .
|
|
.It Dv KAUTH_PROCESS_SCHEDULER_GETAFFINITY
|
|
Checks whether viewing the scheduler affinity is allowed.
|
|
.It Dv KAUTH_PROCESS_SCHEDULER_SETAFFINITY
|
|
Checks whether setting the scheduler affinity is allowed.
|
|
.It Dv KAUTH_PROCESS_SCHEDULER_GETPARAMS
|
|
Checks whether viewing the scheduler policy and parameters is allowed.
|
|
.It Dv KAUTH_PROCESS_SCHEDULER_SETPARAMS
|
|
Checks whether modifying the scheduler policy and parameters is allowed.
|
|
.It Dv KAUTH_PROCESS_SIGNAL
|
|
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_CORENAME
|
|
Controls access to process corename.
|
|
.Pp
|
|
.Ar arg1
|
|
can be
|
|
.Dv KAUTH_REQ_PROCESS_CORENAME_GET
|
|
or
|
|
.Dv KAUTH_REQ_PROCESS_CORENAME_SET ,
|
|
indicating access to read or write the process' corename, respectively.
|
|
.Pp
|
|
When modifying the corename,
|
|
.Ar arg2
|
|
holds the new corename to be used.
|
|
.It Dv KAUTH_PROCESS_FORK
|
|
Checks if the process can fork.
|
|
.Ar arg1
|
|
is an
|
|
.Ft int
|
|
indicating how many processes exist on the system at the time of the check.
|
|
.It Dv KAUTH_PROCESS_KEVENT_FILTER
|
|
Checks whether setting a process
|
|
.Xr kevent 2
|
|
filter is allowed.
|
|
.Pp
|
|
.It Dv KAUTH_PROCESS_NICE
|
|
Checks whether the
|
|
.Em nice
|
|
value of
|
|
.Ar p
|
|
can be changed to
|
|
.Ar arg1 .
|
|
.It Dv KAUTH_PROCESS_RLIMIT
|
|
Controls access to process resource limits.
|
|
.Pp
|
|
.Ar arg1
|
|
can be
|
|
.Dv KAUTH_REQ_PROCESS_RLIMIT_GET
|
|
or
|
|
.Dv KAUTH_REQ_PROCESS_RLIMIT_SET ,
|
|
indicating access to read or write the process' resource limits, respectively.
|
|
.Pp
|
|
When modifying resource limits,
|
|
.Ar arg2
|
|
is the new value to be used and
|
|
.Ar arg3
|
|
indicates which resource limit is to be modified.
|
|
.It Dv KAUTH_PROCESS_SETID
|
|
Check if changing the user- or group-ids, groups, or login-name for
|
|
.Ar p
|
|
is allowed.
|
|
.It Dv KAUTH_PROCESS_STOPFLAG
|
|
Check if setting the stop flags for
|
|
.Xr exec 3 ,
|
|
.Xr exit 3 ,
|
|
and
|
|
.Xr fork 2
|
|
is allowed.
|
|
.Pp
|
|
.Ar arg1
|
|
indicates the flag, and can be either
|
|
.Dv P_STOPEXEC ,
|
|
.Dv P_STOPEXIT ,
|
|
or
|
|
.Dv P_STOPFORK
|
|
respectively.
|
|
.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_NFS
|
|
Check is an NFS related operation is allowed.
|
|
.Pp
|
|
.Ar req
|
|
can be any of the following:
|
|
.Bl -tag
|
|
.It Dv KAUTH_REQ_NETWORK_NFS_EXPORT
|
|
Check if modifying the NFS export table is allowed.
|
|
.It Dv KAUTH_REQ_NETWORK_NFS_SVC
|
|
Check if access to the NFS
|
|
.Xr nfssvc 2
|
|
syscall is allowed.
|
|
.El
|
|
.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" \
|
|
"void *arg0" "void *arg1" "void *arg2" "void *arg3"
|
|
.Pp
|
|
The actions on this scope provide a set that may or may not affect all
|
|
platforms.
|
|
Below is a list of available actions, along with which platforms are affected
|
|
by each.
|
|
.Bl -tag
|
|
.It Dv KAUTH_MACHDEP_IOPERM_GET
|
|
Request to get the I/O permission level.
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_IOPERM_SET
|
|
Request to set the I/O permission level.
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_IOPL
|
|
Request to set the I/O privilege level.
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_LDT_GET
|
|
Request to get the LDT (local descriptor table).
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_LDT_SET
|
|
Request to set the LDT (local descriptor table).
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_MTRR_GET
|
|
Request to get the MTRR (memory type range registers).
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_MTRR_SET
|
|
Request to set the MTRR (memory type range registers).
|
|
Affects
|
|
.Em amd64 ,
|
|
.Em i386 ,
|
|
.Em xen .
|
|
.It Dv KAUTH_MACHDEP_UNMANAGEDMEM
|
|
Request to access unmanaged memory.
|
|
Affects
|
|
.Em alpha ,
|
|
.Em amd64 ,
|
|
.Em arm ,
|
|
.Em i386 ,
|
|
.Em powerpc ,
|
|
.Em sh3 ,
|
|
.Em vax ,
|
|
.Em xen .
|
|
.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
|
|
In addition to the standard authorization wrapper:
|
|
.Pp
|
|
.Ft int Fn kauth_authorize_device "kauth_cred_t cred" "kauth_action_t op" \
|
|
"void *arg0" "void *arg1" "void *arg2" "void *arg3"
|
|
.Pp
|
|
this scope provides authorization wrappers for various device types.
|
|
.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.
|
|
It is passed to the listener as
|
|
.Ar arg0 .
|
|
The second argument,
|
|
.Ar op ,
|
|
is the action and can be 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_TTY_STI
|
|
Use the
|
|
.Dq TIOCSTI
|
|
device
|
|
.Xr ioctl 2 ,
|
|
allowing to inject characters into the terminal buffer, simulating terminal
|
|
input.
|
|
.El
|
|
.Pp
|
|
.Ft int Fn kauth_authorize_device_spec "kauth_cred_t cred" \
|
|
"enum kauth_device_req req" "struct vnode *vp"
|
|
.Pp
|
|
Authorizes requests for
|
|
.Em special files ,
|
|
usually disk devices, but also direct memory access, on the system.
|
|
.Pp
|
|
It passes
|
|
.Dv KAUTH_DEVICE_RAWIO_SPEC
|
|
as the action to the listener, and accepts two arguments.
|
|
.Ar req ,
|
|
passed to the listener as
|
|
.Ar arg0 ,
|
|
is access requested, and can be one of
|
|
.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_READ ,
|
|
.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE ,
|
|
or
|
|
.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_RW ,
|
|
representing read, write, or both read/write access respectively.
|
|
.Ar vp
|
|
is the vnode of the special file in question, and is passed to the listener as
|
|
.Ar arg1 .
|
|
.Pp
|
|
Keep in mind that it is the responsibility of the security model developer to
|
|
check whether the underlying device is a disk or the system memory, using
|
|
.Fn iskmemdev :
|
|
.Bd -literal -offset indent
|
|
if ((vp-\*[Gt]v_type == VCHR) \*[Am]\*[Am]
|
|
iskmemdev(vp-\*[Gt]v_un.vu_specinfo-\*[Gt]si_rdev))
|
|
/* system memory access */
|
|
.Ed
|
|
.Pp
|
|
.Ft int Fn kauth_authorize_device_passthru "kauth_cred_t cred" "dev_t dev" \
|
|
"u_long mode" "void *data"
|
|
.Pp
|
|
Authorizes hardware
|
|
.Em passthru
|
|
requests, or user commands passed directly to the hardware.
|
|
These have the potential of resulting in direct disk and/or memory access.
|
|
.Pp
|
|
It passes
|
|
.Dv KAUTH_DEVICE_RAWIO_PASSTHRU
|
|
as the action to the listener, and accepts three arguments.
|
|
.Ar dev ,
|
|
passed as
|
|
.Ar arg1
|
|
to the listener, is the device for which the request is made.
|
|
.Ar mode ,
|
|
passed as
|
|
.Ar arg0
|
|
to the listener, is a generic representation of the access mode requested.
|
|
It can be one or more (binary-OR'd) of the following:
|
|
.Pp
|
|
.Bl -tag -offset indent -compact
|
|
.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ
|
|
.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF
|
|
.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE
|
|
.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF
|
|
.El
|
|
.Pp
|
|
.Ar data ,
|
|
passed as
|
|
.Ar arg2
|
|
to the listener, is device-specific data that may be associated with the
|
|
request.
|
|
.Ss Credentials Scope
|
|
The credentials scope,
|
|
.Dq org.netbsd.kauth.cred ,
|
|
is a special scope used internally by the
|
|
.Nm
|
|
framework to provide hooking to credential-related operations.
|
|
.Pp
|
|
It is a
|
|
.Dq notify-only
|
|
scope, allowing hooking operations such as initialization of new credentials,
|
|
credential inheritance during a fork, and copying and freeing of credentials.
|
|
The main purpose for this scope is to give a security model a way to control
|
|
the aforementioned operations, especially in cases where the credentials
|
|
hold security model-private data.
|
|
.Pp
|
|
Notifications are made using the following function, which is internal to
|
|
.Nm :
|
|
.Pp
|
|
.Ft int Fn kauth_cred_hook "kauth_cred_t cred" "kauth_action_t action" \
|
|
"void *arg0" "void *arg1"
|
|
.Pp
|
|
With the following actions:
|
|
.Bl -tag
|
|
.It Dv KAUTH_CRED_COPY
|
|
The credentials are being copied.
|
|
.Ar cred
|
|
are the credentials of the lwp context doing the copy, and
|
|
.Ar arg0
|
|
and
|
|
.Ar arg1
|
|
are both
|
|
.Ft kauth_cred_t
|
|
representing the
|
|
.Dq from
|
|
and
|
|
.Dq to
|
|
credentials, respectively.
|
|
.It Dv KAUTH_CRED_FORK
|
|
The credentials are being inherited from a parent to a child process during a
|
|
fork.
|
|
.Pp
|
|
.Ar cred
|
|
are the credentials of the lwp context doing the fork, and
|
|
.Ar arg0
|
|
and
|
|
.Ar arg1
|
|
are both
|
|
.Ft struct proc *
|
|
of the parent and child processes, respectively.
|
|
.It Dv KAUTH_CRED_FREE
|
|
The credentials in
|
|
.Ar cred
|
|
are being freed.
|
|
.It Dv KAUTH_CRED_INIT
|
|
The credentials in
|
|
.Ar cred
|
|
are being initialized.
|
|
.El
|
|
.Pp
|
|
Since this is a notify-only scope, all listeners are required to return
|
|
.Dv KAUTH_RESULT_ALLOW .
|
|
.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 gid_t 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" "const gid_t *groups" \
|
|
"size_t ngroups" "uid_t gmuid" "enum uio_seg seg"
|
|
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.
|
|
.Ar seg
|
|
should be either
|
|
.Dv UIO_USERSPACE
|
|
or
|
|
.Dv UIO_SYSSPACE
|
|
indicating whether
|
|
.Ar groups
|
|
is a user or kernel space address.
|
|
.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.
|
|
.Pp
|
|
The return value is an error code, or zero for success.
|
|
.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \
|
|
"size_t ngroups" "enum uio_seg seg"
|
|
Copy
|
|
.Ar ngroups
|
|
groups from the group list in
|
|
.Ar cred
|
|
to the buffer pointed to by
|
|
.Ar groups .
|
|
.Ar seg
|
|
should be either
|
|
.Dv UIO_USERSPACE
|
|
or
|
|
.Dv UIO_SYSSPACE
|
|
indicating whether
|
|
.Ar groups
|
|
is a user or kernel space address.
|
|
.Pp
|
|
The return value is an error code, or zero for success.
|
|
.El
|
|
.Ss Credential Private Data
|
|
.Nm
|
|
provides an interface to allow attaching security-model private data to
|
|
credentials.
|
|
.Pp
|
|
The use of this interface has two parts that can be divided to direct and
|
|
indirect control of the private-data.
|
|
Directly controlling the private data is done by using the below routines,
|
|
while the indirect control is often dictated by events such as process
|
|
fork, and is handled by listening on the credentials scope (see above).
|
|
.Pp
|
|
Attaching private data to credentials works by registering a key to serve
|
|
as a unique identifier, distinguishing various sets of private data that
|
|
may be associated with the credentials.
|
|
Registering, and deregistering, a key is done by using these routines:
|
|
.Pp
|
|
.Bl -tag
|
|
.It Ft int Fn kauth_register_key "const char *name" "kauth_key_t *keyp"
|
|
Register new key for private data for
|
|
.Ar name
|
|
(usually, the security model name).
|
|
.Ar keyp
|
|
will be used to return the key to be used in further calls.
|
|
.Pp
|
|
The function returns 0 on success and an error code (see
|
|
.Xr errno 2 )
|
|
on failure.
|
|
.It Ft int Fn kauth_deregister_key "kauth_key_t key"
|
|
Deregister private data key
|
|
.Ar key .
|
|
.El
|
|
.Pp
|
|
Once registered, private data may be manipulated by the following routines:
|
|
.Bl -tag
|
|
.It Ft void Fn kauth_cred_setdata "kauth_cred_t cred" "kauth_key_t key" \
|
|
"void *data"
|
|
Set private data for
|
|
.Ar key
|
|
in
|
|
.Ar cred
|
|
to be
|
|
.Ar data .
|
|
.It Ft void * Fn kauth_cred_getdata "kauth_cred_t cred" "kauth_key_t key"
|
|
Retrieve private data for
|
|
.Ar key
|
|
in
|
|
.Ar cred .
|
|
.El
|
|
.Pp
|
|
Note that it is required to use the above routines every time the private
|
|
data is changed, i.e., using
|
|
.Fn kauth_cred_getdata
|
|
and later modifying the private data should be accompanied by a call to
|
|
.Fn kauth_cred_setdata
|
|
with the
|
|
.Dq new
|
|
private data.
|
|
.Ss Credential Inheritance and Reference Counting
|
|
.Nm
|
|
provides an interface for handling shared credentials.
|
|
.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.
|
|
.Pp
|
|
The following routines are available for managing credentials reference
|
|
counting:
|
|
.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 freed.
|
|
.El
|
|
.Pp
|
|
Credential inheritance happens during a
|
|
.Xr fork 2 ,
|
|
and is handled by the following function:
|
|
.Pp
|
|
.Ft void Fn kauth_proc_fork "struct proc *parent" "struct proc *child"
|
|
.Pp
|
|
When called, it references the parent's credentials from the child,
|
|
and calls the credentials scope's hook with the
|
|
.Dv KAUTH_CRED_FORK
|
|
action to allow security model-specific handling of the inheritance
|
|
to take place.
|
|
.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, and free the
|
|
.Ft kauth_scope_t
|
|
object
|
|
.Ar scope .
|
|
.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"
|
|
Removes
|
|
.Ar listener
|
|
from the scope which it belongs to, ensuring it won't be called again,
|
|
and frees the
|
|
.Ft kauth_listener_t
|
|
object
|
|
.Ar listener .
|
|
.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
|
|
Older code had no abstraction of the security model, so most privilege
|
|
checks looked like this:
|
|
.Bd -literal -offset indent
|
|
if (suser(cred, \*[Am]acflag) == 0)
|
|
/* allow privileged operation */
|
|
.Ed
|
|
.Pp
|
|
Using the new interface, you must ask for a specific privilege explicitly.
|
|
For example, checking whether it is possible to open a socket would look
|
|
something like this:
|
|
.Bd -literal -offset indent
|
|
if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET,
|
|
KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM,
|
|
IPPROTO_TCP) == 0)
|
|
/* allow opening the socket */
|
|
.Ed
|
|
.Pp
|
|
Note that the
|
|
.Em securelevel
|
|
implications were also integrated into the
|
|
.Nm
|
|
framework so you don't have to note anything special in the call to the
|
|
authorization wrapper, but rather just have to make sure the security
|
|
model handles the request as you expect it to.
|
|
.Pp
|
|
To do that you can just
|
|
.Xr grep 1
|
|
in the relevant security model directory and have a look at the code.
|
|
.Sh EXTENDING KAUTH
|
|
Although
|
|
.Nm
|
|
provides a large set of both detailed and more or less generic requests,
|
|
it might be needed eventually to introduce more scopes, actions, or
|
|
requests.
|
|
.Pp
|
|
Adding a new scope should happen only when an entire subsystem is
|
|
introduced and it is assumed other parts of the kernel may want to
|
|
interfere with its inner-workings.
|
|
When a subsystem that has the potential of impacting the security
|
|
if the system is introduced, existing security modules must be updated
|
|
to also handle actions on the newly added scope.
|
|
.Pp
|
|
New actions should be added when sets of operations not covered at all
|
|
belong in an already existing scope.
|
|
.Pp
|
|
Requests (or sub-actions) can be added as subsets of existing actions
|
|
when an operation that belongs in an already covered area is introduced.
|
|
.Pp
|
|
Note that all additions should include updates to this manual, the
|
|
security models shipped with
|
|
.Nx ,
|
|
and the example skeleton security model.
|
|
.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 NOTES
|
|
As
|
|
.Nm
|
|
in
|
|
.Nx
|
|
is still under active development, it is likely that the ABI, and possibly the
|
|
API, will differ between
|
|
.Nx
|
|
versions.
|
|
Developers are to take notice of this fact in order to avoid building code
|
|
that expects one version of the ABI and running it in a system with a different
|
|
one.
|
|
.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.
|