man/man9/kauth.9

.\" $NetBSD: kauth.9,v 1.114 2023/10/04 22:17:10 ad 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 October 4, 2023
.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 kauth_listener_t
.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 return:
.Pp
.Bl -tag -width KAUTH_RESULT_ALLOW -compact
.It Dv KAUTH_RESULT_ALLOW
The listener allows the operation.
.It Dv KAUTH_RESULT_DENY
The listener denies the operation.
.It Dv KAUTH_RESULT_DEFER
The listener defers the decision to other listeners.
.El
.Pp
For an operation to be allowed, at least one listener has to return
.Dv KAUTH_RESULT_ALLOW
while no other listener returned
.Dv KAUTH_RESULT_DENY .
.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:
.Bl -tag -width ".It Dv 0 Po zero Pc" -compact
.It Dv 0 Po zero Pc
indicates success; operation is allowed.
.It Dv EPERM
indicates failure; operation is denied.
See
.Xr errno 2 .
.El
.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 -width compact
.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.
.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 compact
.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 -width compact
.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 -width compact
.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.
.It Dv KAUTH_SYSTEM_DEVMAPPER
Check if operations on the device mapper
.Xr dm 4
device are allowed.
.It Dv KAUTH_SYSTEM_FILEHANDLE
Check if file handle operations allowed.
.It Dv KAUTH_SYSTEM_FS_EXTATTR
Check if starting, stopping, enabling, or disabling extended attributes
is allowed.
.Ar arg1
is a
.Ft struct mount *
of the mount-point on which the operation is performed.
.It Dv KAUTH_SYSTEM_FS_SNAPSHOT
Check if setting up a file system snapshot is allowed.
.Ar arg1
is a
.Ft struct mount *
of the mount-point of which the snapshot is taken, and
.Ar arg2
is a
.Ft struct vnode *
of the vnode where the snapshot is expected to be.
.It Dv KAUTH_SYSTEM_FS_QUOTA
Check if file system quota operations are allowed.
.Pp
.Ar arg1
is a
.Ft struct mount *
describing the file system mount in question.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_GET
Check if retrieving quota information is allowed.
.Pp
.Ar arg2
is a
.Ft uid_t
with the user-id of the user whose quota information is to be retrieved.
.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFF
Check if turning quota on/off is allowed.
.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_MANAGE
Check if managing the quota by setting the quota/quota use is allowed.
.Pp
.Ar arg2
is a
.Ft uid_t
with the user-id of the user whose quota/quota use is to be set.
.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMIT
Check if bypassing the quota (not enforcing it) is allowed.
.El
.It Dv KAUTH_SYSTEM_FS_RESERVEDSPACE
Check if using the file system reserved space is allowed.
.It Dv KAUTH_SYSTEM_LFS
Check if LFS-related operations are allowed.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_SYSTEM_LFS_MARKV
Check if calling
.Xr lfs_markv 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_LFS_BMAPV
Check if calling
.Xr lfs_bmapv 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_LFS_SEGCLEAN
Check if calling
.Xr lfs_segclean 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_LFS_SEGWAIT
Check if calling
.Xr lfs_segwait 2
is allowed.
.It Dv KAUTH_REQ_SYSTEM_LFS_FCNTL
Check if operations on LFS through
.Xr fcntl 2
are allowed.
.El
.It Dv KAUTH_SYSTEM_MAP_VA_ZERO
Check if changing the status of memory mapping of virtual address zero
is allowed.
.It Dv KAUTH_SYSTEM_MODULE
Check if a module 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 -width compact
.It Dv KAUTH_REQ_SYSTEM_MOUNT_DEVICE
Check if mounting a device is allowed.
.Ar arg1
is a
.Ft vnode_t *
of the device,
.Ar arg2
is a
.Ft struct mount *
with the mount-point, and
.Ar arg3
is a
.Ft mode_t
with the desired access mode.
.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.
.It Dv KAUTH_REQ_SYSTEM_MOUNT_UMAP
Check if mounting the user and group id remapping file system.
See
.Xr mount_umap 8 .
.El
.It Dv KAUTH_SYSTEM_MQUEUE
Check if bypassing permissions on a message queue object are allowed.
.Ar arg1
is a
.Ft mqueue_t *
describing the message queue.
.It Dv KAUTH_SYSTEM_PSET
Check processor-set manipulation.
.Pp
.Ar req
can be any of the following:
.Bl -tag -width compact
.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_SEMAPHORE
Check if access to a kernel semaphore is allowed.
.Ar arg1
is a
.Ft ksem_t *
describing the semaphore.
.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 -width compact
.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_MODIFY
Check if modifying a
.Xr sysctl 9
node variable that doesn't have a custom sysctl helper function is allowed.
.Pp
This request might be deprecated in the future.
.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT
Check if accessing private
.Xr sysctl 9
nodes is allowed.
.El
.It Dv KAUTH_SYSTEM_SYSVIPC
Check SysV IPC related operations.
.Ar req
indicates the specific request and can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_BYPASS
Check if bypassing a SysV IPC object's permissions is allowed.
.Ar arg1
is a
.Ft struct ipc_perm *
with the object's permissions and
.Ar arg2
is a
.Ft mode_t
indicating the requested access mode.
.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_SHM_LOCK
Check if shared memory locking is allowed.
.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_SHM_UNLOCK
Check if shared memory unlocking is allowed.
.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_MSGQ_OVERSIZE
Check if oversizing a message queue is allowed.
.Ar arg1
is a
.Ft msglen_t
indicating the size of the message buffer, and
.Ar arg2
is a
.Ft msglen_t
indicating the size of the message queue.
.El
.It Dv KAUTH_SYSTEM_TIME
This request groups time-related operations.
.Ar req
can be any of the following:
.Bl -tag -width compact
.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 (e.g.
.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
.It Dv KAUTH_SYSTEM_VERIEXEC
Check if operations on the
.Xr veriexec 8
subsystem are allowed.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_SYSTEM_VERIEXEC_ACCESS
Check if access to the
.Xr veriexec 8
subsystem is allowed.
.It Dv KAUTH_REQ_SYSTEM_VERIEXEC_MODIFY
Check if modifications to the state of
.Xr veriexec 8
are 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 compact
.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 3 ,
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_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 be 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_GETPARAM
Checks whether viewing the scheduler policy and parameters is allowed.
.It Dv KAUTH_PROCESS_SCHEDULER_SETPARAM
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.
.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, or
.Dv KAUTH_REQ_PROCESS_RLIMIT_BYPASS
to check if the limit enforcement can be bypassed.
.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 -width compact
.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 -width 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 -width compact
.It Dv KAUTH_REQ_NETWORK_BIND_PORT
Checks if binding to a non-privileged/reserved port is allowed.
.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 -width compact
.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 -width compact
.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.
.It Dv KAUTH_REQ_NETWORK_INTERFACE_FIRMWARE
Check if manipulating the firmware on a network interface 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_INTERFACE_BRIDGE
Check if operations performed on the
.Xr bridge 4
network interface are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_GETPRIV
Check if getting privileges parameters is allowed.
.It Dv KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_SETPRIV
Check if setting privileges parameters is allowed.
.El
.It Dv KAUTH_NETWORK_INTERFACE_PPP
Checks if operations performed on the
.Xr ppp 4
network interface are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_PPP_ADD
Checks if adding and enabling a
.Xr ppp 4
interface to the system is allowed.
.El
.It Dv KAUTH_NETWORK_INTERFACE_PVC
Check if operations performed on a PVC device (e.g.
.Xr en 4 )
are allowed.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_PVC_ADD
Check if adding a PVC device is allowed.
.El
.It Dv KAUTH_NETWORK_INTERFACE_SLIP
Checks if operations performed on the
.Xr sl 4
network interface are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADD
Checks if adding and enabling a
.Xr sl 4
interface to the system is allowed.
.El
.It Dv KAUTH_NETWORK_INTERFACE_STRIP
Checks if operations performed on the
.Xr strip 4
network interface are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADD
Check if adding and enabling a
.Xr strip 4
interface to the system is allowed.
.El
.It Dv KAUTH_NETWORK_INTERFACE_TUN
Checks if operations performed on the
.Xr tun 4
network interface are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_INTERFACE_TUN_ADD
Checks if adding and enabling a
.Xr tun 4
interface to the system is allowed.
.El
.It Dv KAUTH_NETWORK_IPSEC
Check if operations related to
.Xr ipsec 4
connections are allowed.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_IPSEC_BYPASS
Check if bypassing
.Xr ipsec 4
policy is allowed.
.El
.It Dv KAUTH_NETWORK_IPV6
Check if IPv6-specific operations are allowed.
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_IPV6_HOPBYHOP
Check if setting hop-by-hop packet options is allowed.
.It Dv KAUTH_REQ_NETWORK_IPV6_JOIN_MULTICAST
Check if joining a multicast network is allowed.
.El
.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 if an NFS related operation is allowed.
.Pp
.Ar req
can be any of the following:
.Bl -tag -width compact
.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_SMB
Check if operations related to SMB are allowed.
.Pp
.Ar req
can be one of the following:
.Bl -tag -width compact
.It Dv KAUTH_REQ_NETWORK_SMB_SHARE_ACCESS
Check if accessing an SMB share is allowed.
.Pp
.Ar arg1
is a
.Ft struct smb_share *
describing the SMB share, and
.Ar arg2
is a
.Ft mode_t
with the desired access mode.
.It Dv KAUTH_REQ_NETWORK_SMB_SHARE_CREATE
Check if creating an SMB share is allowed.
.Pp
.Ar arg1
is a
.Ft struct smb_sharespec *
describing the share to be created.
.It Dv KAUTH_REQ_NETWORK_SMB_VC_ACCESS
Check if accessing an SMB VC is allowed.
.Pp
.Ar arg1
is a
.Ft struct smb_vc *
describing the SMB VC, and
.Ar arg2
is a
.Ft mode_t
with the desired access mode.
.It Dv KAUTH_REQ_NETWORK_SMB_VC_CREATE
Check if creating an SMB VC is allowed.
.Pp
.Ar arg1
is a
.Ft struct smb_vcspec *
describing the VC to be created.
.El
.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 -width compact
.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.
.It Dv KAUTH_REQ_NETWORK_SOCKET_DROP
Checks if a connection can be dropped.
.Pp
.Ar arg1
is a
.Ft struct socket *
describing the socket.
.It Dv KAUTH_REQ_NETWORK_SOCKET_SETPRIV
Checks if setting privileged socket options is allowed.
.Pp
.Ar arg1
is a
.Ft struct socket *
describing the socket,
.Ar arg2
is a
.Ft u_long
describing the socket option.
.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 -width compact
.It Dv KAUTH_MACHDEP_CACHEFLUSH
Request to flush the whole CPU cache.
Affects
.Em m68k
Linux emulation.
.It Dv KAUTH_MACHDEP_CPU_UCODE_APPLY
Request to apply a CPU microcode to a CPU.
This is related to
.Em CPU_UCODE ,
see
.Xr options 4 .
Affects
.Em i386
and
.Em xen .
.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_NVRAM
Request to access (read/write) the NVRAM.
Affects
.Em i386 .
.It Dv KAUTH_MACHDEP_PXG
Request to start or stop the
.Xr pxg 4
CPU.
.Ar arg0
is
.Ft true
or
.Ft false ,
respectively.
Affects
.Em pmax .
.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 x68k ,
.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, Bluetooth accessories, 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 -width compact
.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.
.It Dv KAUTH_DEVICE_TTY_VIRTUAL
Control the virtual console.
.Ar tty
is the current console
.Xr tty 4 .
.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->v_type == VCHR) &&
    iskmemdev(vp->v_un.vu_specinfo->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 -width compact -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 Bluetooth Devices
Authorizing actions relevant to Bluetooth devices is done using the standard
authorization wrapper, with the following actions:
.Bl -tag -width compact
.It KAUTH_DEVICE_BLUETOOTH_BCSP
Check if operations on a
.Xr bcsp 4
device are allowed.
.Pp
.Ar arg0
is an
.Ft enum kauth_device_req
with one of the following values:
.Bl -tag -width compact
.It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADD
Check if adding and enabling a
.Xr bcsp 4
device is allowed.
.El
.It KAUTH_DEVICE_BLUETOOTH_BTUART
Check if operations on a
.Xr btuart 4
device are allowed.
.Pp
.Ar arg0
is an
.Ft enum kauth_device_req
with one of the following values:
.Bl -tag -width compact
.It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADD
Check if adding and enabling a
.Xr btuart 4
device is allowed.
.El
.It KAUTH_DEVICE_BLUETOOTH_RECV
Check if a packet can be received from the device.
.Pp
.Ar arg0
is the packet type.
For
.Dv HCI_CMD_PKT
packets,
.Ar arg1
is the opcode, for
.Dv HCI_EVENT_PKT
packets,
.Ar arg1
is the event ID, and for
.Dv HCI_ACLDATA_PKT
or
.Dv HCI_SCODATA_PKT
packets,
.Ar arg1
is the connection handle.
.It KAUTH_DEVICE_BLUETOOTH_SEND
Check if a packet can be sent to the device.
.Pp
.Ar arg0
is a
.Ft struct hci_unit *
describing the HCI unit,
.Ar arg1
is a
.Ft hci_cmd_hdr_t *
describing the packet header.
.It KAUTH_DEVICE_BLUETOOTH_SETPRIV
Check if privileged settings can be changed.
.Pp
.Ar arg0
is a
.Ft struct hci_unit *
describing the HCI unit,
.Ar arg1
is a
.Ft struct btreq *
describing the request, and
.Ar arg2
is a
.Ft u_long
describing the command.
.El
.Ss Kernel random device
Authorization actions relevant to the kernel random device,
.Xr rnd 4 ,
is done using the standard authorization wrapper, with the following actions:
.Bl -tag -width compact
.It KAUTH_DEVICE_RND_ADDDATA
Check if adding data to the entropy pool is allowed.
.It KAUTH_DEVICE_RND_GETPRIV
Check if privileged settings and information can be retrieved.
.It KAUTH_DEVICE_RND_SETPRIV
Check if privileged settings can be changed.
.El
.Ss Wscons devices
Authorization actions relevant to
.Xr wscons 4
are done using the standard authorization wrapper, with the following actions:
.Bl -tag -width compact
.It KAUTH_DEVICE_WSCONS_KEYBOARD_BELL
Check if setting the default bell is allowed.
.It KAUTH_DEVICE_WSCONS_KEYBOARD_KEYREPEAT
Check if setting the default key-repeat is allowed.
.El
.Ss Vnode Scope
The vnode scope,
.Dq org.netbsd.kauth.vnode ,
authorizes operations made on vnodes representing file system objects.
.Pp
The authorization wrapper for this scope is declared as
.Pp
.Ft int Fn kauth_authorize_vnode "kauth_cred_t cred" "kauth_action_t action" \
"vnode_t *vp" "vnode_t *dvp" "int fs_decision"
.Pp
This scope is heavily used in file system code and can potentially affect
system-wide performance.
Therefore, there are several things developers should know when using it.
.Pp
First, the
.Ar action
parameter is a bit-mask and multiple actions can be binary-OR'd and authorized
in a single call.
Two helper functions help generate the
.Ar action
value for a couple of common cases: translating file system access to a
.Nm
action and checking access to a vnode.
.Pp
The first,
.Fn kauth_mode_to_action "mode_t access_mode" ,
and returns a
.Ft kauth_action_t
representing the desired access modes.
Another function,
.Fn kauth_access_action "mode_t access_mode" "enum vtype v_type" \
"mode_t file_mode" ,
returns a
.Ft kauth_action_t
suitable for use in many file system
.Xr access 2
implementations.
It calls the aforementioned
.Fn kauth_mode_to_action ,
but before returning also adds the
.Dv KAUTH_VNODE_IS_EXEC
flag if needed.
See below for the meaning of this flag and how its necessity is
determined.
.Pp
Second, it is recommended to be very careful with adding listeners on this
scope.
A special parameter,
.Ar fs_decision ,
allows different file systems to instrument different policies without adding
their own listener.
This parameter is special because it also serves as a fall-back decision when
no
.Xr secmodel 9
is present to prevent a fail-open scenario.
It can take either an
.Xr errno 2
value or
.Dq KAUTH_VNODE_REMOTEFS ,
indicating that the file system on which the authorization is made is remote
and cannot provide us with a fall-back decision.
In this case,
.Nm
can only short-circuit the request but the file system will have the last
word if there is no definitive allow or deny decision.
.Pp
The value of
.Ar fs_decision
can be hard-coded or determined by calling an internal function implementing a
policy.
For the latter case,
.Xr genfs 9
provides a set of helper functions that implement common policies that
file systems can use.
The calling convention is as follows:
.Bd -literal -offset indent
int error;

error = kauth_authorize_vnode(..., genfs_can_foo(...));
.Ed
.Pp
Actions on the vnode scope are of two types: operations and flags.
An operation is similar in concept to actions on other scopes in the sense
that it represents an operation desired by the caller.
A flag is an indicator of additional information about the vnode that
a file system can set in order to allow the listener to make a more
informed decision.
.Pp
Actions include the following:
.Bl -tag -width compact -offset indent
.It KAUTH_VNODE_READ_DATA
Read file data.
.It KAUTH_VNODE_LIST_DIRECTORY
Read directory listing.
Identical to the above.
.It KAUTH_VNODE_WRITE_DATA
Write file data.
.It KAUTH_VNODE_ADD_FILE
Add a file to a directory.
Identical to the above.
.It KAUTH_VNODE_EXECUTE
Execute a file.
.It KAUTH_VNODE_SEARCH
Search (enter) a directory.
Identical to the above.
.It KAUTH_VNODE_DELETE
Delete a file.
.It KAUTH_VNODE_APPEND_DATA
Append data to a file.
.It KAUTH_VNODE_ADD_SUBDIRECTORY
Add a subdirectory to a directory.
Identical to the above.
.It KAUTH_VNODE_READ_TIMES
Read the created, last accessed, and last modified times of a file.
.It KAUTH_VNODE_WRITE_TIMES
Modify the created, last accessed, or last modified times of a file.
.It KAUTH_VNODE_READ_FLAGS
Read file flags.
.It KAUTH_VNODE_WRITE_FLAGS
Modify file flags.
.It KAUTH_VNODE_READ_SYSFLAGS
Read file system flags.
.It KAUTH_VNODE_WRITE_SYSFLAGS
Modify file system flags.
.It KAUTH_VNODE_RENAME
Rename a file.
.It KAUTH_VNODE_CHANGE_OWNERSHIP
Change ownership of a file.
.It KAUTH_VNODE_READ_SECURITY
Read the permissions of a file.
.It KAUTH_VNODE_WRITE_SECURITY
Change the permissions of a file, for example by using
.Xr chmod 2 .
.It KAUTH_VNODE_READ_ATTRIBUTES
Read attributes of a file.
.It KAUTH_VNODE_WRITE_ATTRIBUTES
Modify attributes of a file.
.It KAUTH_VNODE_READ_EXTATTRIBUTES
Read extended attributes of a file.
.It KAUTH_VNODE_WRITE_EXTATTRIBUTES
Modify extended attributes of a file.
.It KAUTH_VNODE_RETAIN_SUID
Check if retaining the set-user-id bit on files after
.Xr chown 2
is allowed.
.It KAUTH_VNODE_RETAIN_SGID
Check if retaining the set-group-id bit on files after
.Xr chown 2
is allowed.
.It KAUTH_VNODE_REVOKE
Revoke a file.
.El
.Pp
Flags include the following:
.Bl -tag -width compact -offset indent
.It KAUTH_VNODE_IS_EXEC
The vnode is executable.
.Pp
The macro
.Fn FS_OBJECT_CAN_EXEC
can be used to help determine if this flag should be set.
This macro determines a file system object to be executable if it is a
directory (in which case we say it is searchable) or if it has at least one
executable bit set in its mode.
.Pp
Setting this flag helps a listener know that a vnode is executable and is used
in implementing privileged access to files and directories while maintaining
semantics that prevent execution until a file is marked as an executable.
An example for using this in listener code is:
.Bd -literal -offset indent
if (privileged) {
	/* Always allow read/write; execute only if executable. */
	if ((action & KAUTH_VNODE_EXECUTE) == 0 ||
	    (action & KAUTH_VNODE_IS_EXEC))
		result = KAUTH_RESULT_ALLOW;
}
.Ed
.Pp
Finally, the vnode scope authorization wrapper returns
.Er EACCES
in case of an error, to maintain file system semantics.
File systems can override this value if needed.
.It KAUTH_VNODE_HAS_SYSFLAGS
The file system object represented by the vnode has system flags set.
.It KAUTH_VNODE_ACCESS
The authorization is advisory only and no actual operation is to be
performed.
This is not implemented.
.El
.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 -width compact
.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_CHROOT
The credentials in cred belong to a process whose root directory is
changed through
.Fn change_root
(see
.Xr vfs 9 ).
.Pp
.Ar Arg0
is the new
.Ft struct cwdinfo *
of the process.
.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 -width compact
.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 compact
.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:
.Bl -tag -width compact
.It Ft int Fn kauth_register_key "secmodel_t sm" "kauth_key_t *keyp"
Register new key for private data for security model
.Ar sm .
.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 -width compact
.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 -width compact
.It Ft kauth_cred_t Fn kauth_cred_hold "kauth_cred_t cred"
Increases reference count to
.Ar cred
by one and returns
.Ar cred
verbatim.
.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 -width compact
.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 -width compact
.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 -width compact
.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.
.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.
This does not change the reference count of the resulting
.Ft kauth_cred_t
object.
.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 compact
.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 \(em leaving the
decision for other listeners \(em the request is denied.
.Pp
The following KPI is provided for the management of listeners:
.Bl -tag -width compact
.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 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; 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, &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
of 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
.Lk 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 Mt elad@NetBSD.org
implemented the kernel authorization framework in
.Nx .
.Pp
.An Jason R. Thorpe Aq Mt thorpej@NetBSD.org
provided guidance and answered questions about the Darwin implementation.