👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for kauth (netbsd section 9)

KAUTH(9)			  BSD Kernel Developer's Manual 			 KAUTH(9)

NAME
     kauth -- kernel authorization framework

SYNOPSIS
     #include <sys/kauth.h>

DESCRIPTION
     kauth, 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.

     kauth introduces some new concepts, namely ``scopes'' and ``listeners'', which will be
     detailed together with other useful information for kernel developers in this document.

   Types
     Some kauth types include the following:

     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 member-
		       ship information.

     kauth_scope_t     Describes a scope.

     kauth_listener_t  Describes a listener.

   Terminology
     kauth operates in various ``scopes'', each scope holding a group of ``listeners''.

     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.

     Every listener examines the passed information and returns its decision regarding the
     requested operation.  It can either return:

     KAUTH_RESULT_ALLOW  The listener allows the operation.
     KAUTH_RESULT_DENY	 The listener denies the operation.
     KAUTH_RESULT_DEFER  The listener defers the decision to other listeners.

     For an operation to be allowed, at least one listener has to return KAUTH_RESULT_ALLOW while
     no other listener returned KAUTH_RESULT_DENY.

     Scopes manage listeners that operate in the same aspect of the system.

   Kernel Programming Interface
     kauth exports a KPI that allows developers both of NetBSD and third-party products to autho-
     rize requests, access and modify credentials, create and remove scopes and listeners, and
     perform other miscellaneous operations on credentials.

   Authorization Requests
     kauth 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.

     It is declared as

     int kauth_authorize_action(kauth_scope_t scope, kauth_cred_t cred, kauth_action_t op, void
     *arg0, void *arg1, void *arg2, void *arg3)

     An authorization request can return one of two possible values:
     0 (zero)  indicates success; operation is allowed.
     EPERM     indicates failure; operation is denied.	See errno(2).

     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.

     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 NOCRED or 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.

   Generic Scope
     The generic scope, ``org.netbsd.kauth.generic'', manages generic authorization requests in
     the kernel.

     The authorization wrapper for this scope is declared as

     int kauth_authorize_generic(kauth_cred_t cred, kauth_action_t op, void *arg0)

     The following operations are available for this scope:

     KAUTH_GENERIC_ISSUSER
	      Checks whether the credentials belong to the super-user.

	      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 authoriza-
	      tion requests from the back-end implementation.

   System Scope
     The system scope, ``org.netbsd.kauth.system'', manages authorization requests affecting the
     entire system.

     The authorization wrapper for this scope is declared as

     int kauth_authorize_system(kauth_cred_t cred, kauth_action_t op, enum kauth_system_req req,
     void *arg1, void *arg2, void *arg3)

     The following requests are available for this scope:

     KAUTH_SYSTEM_ACCOUNTING
	      Check if enabling/disabling accounting allowed.

     KAUTH_SYSTEM_CHROOT
	      req can be any of the following:

	      KAUTH_REQ_SYSTEM_CHROOT_CHROOT
		       Check if calling chroot(2) is allowed.

	      KAUTH_REQ_SYSTEM_CHROOT_FCHROOT
		       Check if calling fchroot(2) is allowed.

     KAUTH_SYSTEM_CPU
	      Check CPU-manipulation access.

	      req can be any of the following:

	      KAUTH_REQ_SYSTEM_CPU_SETSTATE
		       Set CPU state, including setting it online or offline.

     KAUTH_SYSTEM_DEBUG
	      This request concentrates several debugging-related operations.  req can be any of
	      the following:

	      KAUTH_REQ_SYSTEM_DEBUG_IPKDB
		       Check if using ipkdb(4) is allowed.

     KAUTH_SYSTEM_FILEHANDLE
	      Check if filehandle operations allowed.

     KAUTH_SYSTEM_FS_QUOTA
	      Check if file-system quota operations are allowed.

	      arg1 is a struct mount * describing the file-system mount in question.  req can be
	      one of the following:

	      KAUTH_REQ_SYSTEM_FS_QUOTA_GET
		       Check if retrieving quota information is allowed.

		       arg2 is a uid_t with the user-id of the user whose quota information is to
		       be retrieved.

	      KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFF
		       Check if turning quota on/off is allowed.

	      KAUTH_REQ_SYSTEM_FS_QUOTA_MANAGE
		       Check if managing the quota by setting the quota/quota use is allowed.

		       arg2 is a uid_t with the user-id of the user whose quota/quota use is to
		       be set.

	      KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMIT
		       Check if bypassing the quota (not enforcing it) is allowed.

     KAUTH_SYSTEM_FS_RESERVEDSPACE
	      Check if using the file-system reserved space is allowed.

     KAUTH_SYSTEM_MODULE
	      Check if a module request is allowed.

	      arg1 is the command.

     KAUTH_SYSTEM_MKNOD
	      Check if creating devices is allowed.

     KAUTH_SYSTEM_MOUNT
	      Check if mount-related operations are allowed.

	      req can be any of the following:

	      KAUTH_REQ_SYSTEM_MOUNT_GET
		       Check if retrieving information about a mount is allowed.  arg1 is a
		       struct mount * with the mount structure in question, arg2 is a void * with
		       file-system specific data, if any.

	      KAUTH_REQ_SYSTEM_MOUNT_NEW
		       Check if mounting a new file-system is allowed.

		       arg1 is the struct vnode * on which the file-system is to be mounted, arg2
		       is an int with the mount flags, and arg3 is a void * with file-system spe-
		       cific data, if any.

	      KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT
		       Checks if unmounting a file-system is allowed.

		       arg1 is a struct mount * with the mount in question.

	      KAUTH_REQ_SYSTEM_MOUNT_UPDATE
		       Checks if updating an existing mount is allowed.

		       arg1 is the struct mount * of the existing mount, arg2 is an int with the
		       new mount flags, and arg3 is a void * with file-system specific data, if
		       any.

     KAUTH_SYSTEM_PSET
	      Check processor-set manipulation.

	      req can be any of the following:

	      KAUTH_REQ_SYSTEM_PSET_ASSIGN
		       Change processor-set processor assignment.

	      KAUTH_REQ_SYSTEM_PSET_BIND
		       Bind an LWP to a processor-set.

	      KAUTH_REQ_SYSTEM_PSET_CREATE
		       Create a processor-set.

	      KAUTH_REQ_SYSTEM_PSET_DESTROY
		       Destroy a processor-set.

     KAUTH_SYSTEM_REBOOT
	      Check if rebooting is allowed.

     KAUTH_SYSTEM_SETIDCORE
	      Check if changing coredump settings for set-id processes is allowed.

     KAUTH_SYSTEM_SWAPCTL
	      Check if privileged swapctl(2) requests are allowed.

     KAUTH_SYSTEM_SYSCTL
	      This requests operations related to sysctl(9).  req indicates the specific request
	      and can be one of the following:

	      KAUTH_REQ_SYSTEM_SYSCTL_ADD
		       Check if adding a sysctl(9) node is allowed.

	      KAUTH_REQ_SYSTEM_SYSCTL_DELETE
		       Check if deleting a sysctl(9) node is allowed.

	      KAUTH_REQ_SYSTEM_SYSCTL_DESC
		       Check if adding description to a sysctl(9) node is allowed.

	      KAUTH_REQ_SYSTEM_SYSCTL_MODIFY
		       Check if modifying a sysctl(9) node variable that doesn't have a custom
		       sysctl helper function is allowed.

		       This request might be deprecated in the future.

	      KAUTH_REQ_SYSTEM_SYSCTL_PRVT
		       Check if accessing private sysctl(9) nodes is allowed.

     KAUTH_SYSTEM_TIME
	      This request groups time-related operations.  req can be any of the following:

	      KAUTH_REQ_SYSTEM_TIME_ADJTIME
		       Check if changing the time using adjtime(2) is allowed.

	      KAUTH_REQ_SYSTEM_TIME_NTPADJTIME
		       Check if setting the time using ntp_adjtime(2) is allowed.

	      KAUTH_REQ_SYSTEM_TIME_SYSTEM
		       Check if changing the time (usually via settimeofday(2)) is allowed.

		       arg1 is a struct timespec * with the new time, arg2 is a struct timeval *
		       with the delta from the current time, arg3 is a bool indicating whether
		       the caller is a device context (e.g.  /dev/clockctl) or not.

	      KAUTH_REQ_SYSTEM_TIME_RTCOFFSET
		       Check if changing the RTC offset is allowed.

	      KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS
		       Check if manipulating timecounters is allowed.

   Process Scope
     The process scope, ``org.netbsd.kauth.process'', manages authorization requests related to
     processes in the system.

     The authorization wrapper for this scope is declared as

     int kauth_authorize_process(kauth_cred_t cred, kauth_action_t op, struct proc *p, void
     *arg1, void *arg2, void *arg3)

     The following operations are available for this scope:

     KAUTH_PROCESS_KTRACE
	      Checks whether an object with one set of credentials can ktrace(1) another process
	      p, possibly with a different set of credentials.

	      If arg1 is 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 exec(3), and normally requires privileged credentials.

     KAUTH_PROCESS_PROCFS
	      Checks whether object with passed credentials can use procfs to access process p.

	      arg1 is the struct pfsnode * for the target element in the target process, and arg2
	      is the access type, which can be either KAUTH_REQ_PROCESS_PROCFS_CTL,
	      KAUTH_REQ_PROCESS_PROCFS_READ, KAUTH_REQ_PROCESS_PROCFS_RW, or
	      KAUTH_REQ_PROCESS_PROCFS_WRITE, indicating control, read, read-write, or write
	      access respectively.

     KAUTH_PROCESS_PTRACE
	      Checks whether object with passed credentials can use ptrace(2) to access process
	      p.

	      arg1 is the ptrace(2) command.

     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.

	      arg1 indicates the class of information being viewed, and can be either of
	      KAUTH_REQ_PROCESS_CANSEE_ARGS, KAUTH_REQ_PROCESS_CANSEE_ENTRY,
	      KAUTH_REQ_PROCESS_CANSEE_ENV, or KAUTH_REQ_PROCESS_CANSEE_OPENFILES.

     KAUTH_PROCESS_SCHEDULER_GETAFFINITY
	      Checks whether viewing the scheduler affinity is allowed.

     KAUTH_PROCESS_SCHEDULER_SETAFFINITY
	      Checks whether setting the scheduler affinity is allowed.

     KAUTH_PROCESS_SCHEDULER_GETPARAM
	      Checks whether viewing the scheduler policy and parameters is allowed.

     KAUTH_PROCESS_SCHEDULER_SETPARAM
	      Checks whether modifying the scheduler policy and parameters is allowed.

     KAUTH_PROCESS_SIGNAL
	      Checks whether an object with one set of credentials can post signals to another
	      process.

	      p is the process the signal is being posted to, and arg1 is the signal number.

     KAUTH_PROCESS_CORENAME
	      Controls access to process corename.

	      arg1 can be KAUTH_REQ_PROCESS_CORENAME_GET or KAUTH_REQ_PROCESS_CORENAME_SET, indi-
	      cating access to read or write the process' corename, respectively.

	      When modifying the corename, arg2 holds the new corename to be used.

     KAUTH_PROCESS_FORK
	      Checks if the process can fork.  arg1 is an int indicating how many processes exist
	      on the system at the time of the check.

     KAUTH_PROCESS_KEVENT_FILTER
	      Checks whether setting a process kevent(2) filter is allowed.

     KAUTH_PROCESS_NICE
	      Checks whether the nice value of p can be changed to arg1.

     KAUTH_PROCESS_RLIMIT
	      Controls access to process resource limits.

	      arg1 can be KAUTH_REQ_PROCESS_RLIMIT_GET or KAUTH_REQ_PROCESS_RLIMIT_SET, indicat-
	      ing access to read or write the process' resource limits, respectively.

	      When modifying resource limits, arg2 is the new value to be used and arg3 indicates
	      which resource limit is to be modified.

     KAUTH_PROCESS_SETID
	      Check if changing the user- or group-ids, groups, or login-name for p is allowed.

     KAUTH_PROCESS_STOPFLAG
	      Check if setting the stop flags for exec(3), exit(3), and fork(2) is allowed.

	      arg1 indicates the flag, and can be either P_STOPEXEC, P_STOPEXIT, or P_STOPFORK
	      respectively.

   Network Scope
     The network scope, ``org.netbsd.kauth.network'', manages networking-related authorization
     requests in the kernel.

     The authorization wrapper for this scope is declared as

     int kauth_authorize_network(kauth_cred_t cred, kauth_action_t op, enum kauth_network_req
     req, void *arg1, void *arg2, void *arg3)

     The following operations are available for this scope:

     KAUTH_NETWORK_ALTQ
	      Checks if an ALTQ operation is allowed.

	      req indicates the ALTQ subsystem in question, and can be one of the following:

	      KAUTH_REQ_NETWORK_ALTQ_AFMAP
	      KAUTH_REQ_NETWORK_ALTQ_BLUE
	      KAUTH_REQ_NETWORK_ALTQ_CBQ
	      KAUTH_REQ_NETWORK_ALTQ_CDNR
	      KAUTH_REQ_NETWORK_ALTQ_CONF
	      KAUTH_REQ_NETWORK_ALTQ_FIFOQ
	      KAUTH_REQ_NETWORK_ALTQ_HFSC
	      KAUTH_REQ_NETWORK_ALTQ_JOBS
	      KAUTH_REQ_NETWORK_ALTQ_PRIQ
	      KAUTH_REQ_NETWORK_ALTQ_RED
	      KAUTH_REQ_NETWORK_ALTQ_RIO
	      KAUTH_REQ_NETWORK_ALTQ_WFQ

     KAUTH_NETWORK_BIND
	      Checks if a bind(2) request is allowed.

	      req allows to indicate the type of the request to structure listeners and callers
	      easier.  Supported request types:

	      KAUTH_REQ_NETWORK_BIND_PORT
		       Checks if binding to a non-privileged/reserved port is allowed.

	      KAUTH_REQ_NETWORK_BIND_PRIVPORT
		       Checks if binding to a privileged/reserved port is allowed.

     KAUTH_NETWORK_FIREWALL
	      Checks if firewall-related operations are allowed.

	      req indicates the sub-action, and can be one of the following:

	      KAUTH_REQ_NETWORK_FIREWALL_FW
		       Modification of packet filtering rules.

	      KAUTH_REQ_NETWORK_FIREWALL_NAT
		       Modification of NAT rules.

     KAUTH_NETWORK_INTERFACE
	      Checks if network interface-related operations are allowed.

	      arg1 is (optionally) the struct ifnet * associated with the interface.  arg2 is
	      (optionally) an int describing the interface-specific operation.	arg3 is (option-
	      ally) a pointer to the interface-specific request structure.  req indicates the
	      sub-action, and can be one of the following:

	      KAUTH_REQ_NETWORK_INTERFACE_GET
		       Check if retrieving information from the device is allowed.

	      KAUTH_REQ_NETWORK_INTERFACE_GETPRIV
		       Check if retrieving privileged information from the device is allowed.

	      KAUTH_REQ_NETWORK_INTERFACE_SET
		       Check if setting parameters on the device is allowed.

	      KAUTH_REQ_NETWORK_INTERFACE_SETPRIV
		       Check if setting privileged parameters on the device is allowed.

	      Note that unless the struct ifnet * for the interface was passed in arg1, there's
	      no way to tell what structure arg3 is.

     KAUTH_NETWORK_INTERFACE_PPP
	      Checks if operations performed on the ppp(4) network interface are allowed.

	      req can be one of the following:

	      KAUTH_REQ_NETWORK_INTERFACE_PPP_ADD
		       Checks if adding and enabling a ppp(4) interface to the system is allowed.

     KAUTH_NETWORK_INTERFACE_SLIP
	      Checks if operations performed on the sl(4) network interface are allowed.

	      req can be one of the following:

	      KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADD
		       Checks if adding and enabling a sl(4) interface to the system is allowed.

     KAUTH_NETWORK_INTERFACE_STRIP
	      Checks if operations performed on the strip(4) network interface are allowed.

	      req can be one of the following:

	      KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADD
		       Check if adding and enabling a strip(4) interface to the system is
		       allowed.

     KAUTH_NETWORK_INTERFACE_TUN
	      Checks if operations performed on the tun(4) network interface are allowed.

	      req can be one of the following:

	      KAUTH_REQ_NETWORK_INTERFACE_TUN_ADD
		       Checks if adding and enabling a tun(4) interface to the system is allowed.

     KAUTH_NETWORK_FORWSRCRT
	      Checks whether status of forwarding of source-routed packets can be modified or
	      not.

     KAUTH_NETWORK_NFS
	      Check if an NFS related operation is allowed.

	      req can be any of the following:

	      KAUTH_REQ_NETWORK_NFS_EXPORT
		       Check if modifying the NFS export table is allowed.

	      KAUTH_REQ_NETWORK_NFS_SVC
		       Check if access to the NFS nfssvc(2) syscall is allowed.

     KAUTH_NETWORK_ROUTE
	      Checks if a routing-related request is allowed.

	      arg1 is the struct rt_msghdr * for the request.

     KAUTH_NETWORK_SOCKET
	      Checks if a socket related operation is allowed.

	      req allows to indicate the type of the request to structure listeners and callers
	      easier.  Supported request types:

	      KAUTH_REQ_NETWORK_SOCKET_RAWSOCK
		       Checks if opening a raw socket is allowed.

	      KAUTH_REQ_NETWORK_SOCKET_OPEN
		       Checks if opening a socket is allowed.  arg1, arg2, and arg3 are all int
		       parameters describing the domain, socket type, and protocol, respectively.

	      KAUTH_REQ_NETWORK_SOCKET_CANSEE
		       Checks if looking at the socket passed is allowed.

		       arg1 is a struct socket * describing the socket.

	      KAUTH_REQ_NETWORK_SOCKET_DROP
		       Checks if a connection can be dropped.

		       arg1 is a struct socket * describing the socket.

	      KAUTH_REQ_NETWORK_SOCKET_SETPRIV
		       Checks if setting privileged socket options is allowed.

		       arg1 is a struct socket * describing the socket, arg2 is a u_long describ-
		       ing the socket option.

   Machine-dependent Scope
     The machine-dependent (machdep) scope, ``org.netbsd.kauth.machdep'', manages machine-depen-
     dent authorization requests in the kernel.

     The authorization wrapper for this scope is declared as

     int kauth_authorize_machdep(kauth_cred_t cred, kauth_action_t op, void *arg0, void *arg1,
     void *arg2, void *arg3)

     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.

     KAUTH_MACHDEP_CPU_UCODE_APPLY
	      Request to apply a CPU microcode to a CPU.  This is related to the CPU_UCODE kernel
	      config options(4).

     KAUTH_MACHDEP_CACHEFLUSH
	      Request to flush the whole CPU cache.  Affects m68k Linux emulation.

     KAUTH_MACHDEP_IOPERM_GET
	      Request to get the I/O permission level.	Affects amd64, i386, xen.

     KAUTH_MACHDEP_IOPERM_SET
	      Request to set the I/O permission level.	Affects amd64, i386, xen.

     KAUTH_MACHDEP_IOPL
	      Request to set the I/O privilege level.  Affects amd64, i386, xen.

     KAUTH_MACHDEP_LDT_GET
	      Request to get the LDT (local descriptor table).	Affects amd64, i386, xen.

     KAUTH_MACHDEP_LDT_SET
	      Request to set the LDT (local descriptor table).	Affects amd64, i386, xen.

     KAUTH_MACHDEP_MTRR_GET
	      Request to get the MTRR (memory type range registers).  Affects amd64, i386, xen.

     KAUTH_MACHDEP_MTRR_SET
	      Request to set the MTRR (memory type range registers).  Affects amd64, i386, xen.

     KAUTH_MACHDEP_NVRAM
	      Request to access (read/write) the NVRAM.  Affects i386.

     KAUTH_MACHDEP_UNMANAGEDMEM
	      Request to access unmanaged memory.  Affects alpha, amd64, arm, i386, powerpc, sh3,
	      vax, xen.

   Device Scope
     The device scope, ``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
     network scope.

     In addition to the standard authorization wrapper:

     int kauth_authorize_device(kauth_cred_t cred, kauth_action_t op, void *arg0, void *arg1,
     void *arg2, void *arg3)

     this scope provides authorization wrappers for various device types.

     int kauth_authorize_device_tty(kauth_cred_t cred, kauth_action_t op, struct tty *tty)

     Authorizes requests for terminal devices on the system.  The third argument, tty, is the
     terminal device in question.  It is passed to the listener as arg0.  The second argument,
     op, is the action and can be one of the following:

     KAUTH_DEVICE_TTY_OPEN
	      Open the terminal device pointed to by tty.

     KAUTH_DEVICE_TTY_PRIVSET
	      Set privileged settings on the terminal device pointed to by tty.

     KAUTH_DEVICE_TTY_STI
	      Use the ``TIOCSTI'' device ioctl(2), allowing to inject characters into the termi-
	      nal buffer, simulating terminal input.

     int kauth_authorize_device_spec(kauth_cred_t cred, enum kauth_device_req req, struct vnode
     *vp)

     Authorizes requests for special files, usually disk devices, but also direct memory access,
     on the system.

     It passes KAUTH_DEVICE_RAWIO_SPEC as the action to the listener, and accepts two arguments.
     req, passed to the listener as arg0, is access requested, and can be one of
     KAUTH_REQ_DEVICE_RAWIO_SPEC_READ, KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE, or
     KAUTH_REQ_DEVICE_RAWIO_SPEC_RW, representing read, write, or both read/write access respec-
     tively.  vp is the vnode of the special file in question, and is passed to the listener as
     arg1.

     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 iskmemdev():

	   if ((vp->v_type == VCHR) &&
	       iskmemdev(vp->v_un.vu_specinfo->si_rdev))
		   /* system memory access */

     int kauth_authorize_device_passthru(kauth_cred_t cred, dev_t dev, u_long mode, void *data)

     Authorizes hardware passthru requests, or user commands passed directly to the hardware.
     These have the potential of resulting in direct disk and/or memory access.

     It passes KAUTH_DEVICE_RAWIO_PASSTHRU as the action to the listener, and accepts three argu-
     ments.  dev, passed as arg1 to the listener, is the device for which the request is made.
     mode, passed as 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:

	   KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ
	   KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF
	   KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE
	   KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF

     data, passed as arg2 to the listener, is device-specific data that may be associated with
     the request.

   Bluetooth Devices
     Authorizing actions relevant to Bluetooth devices is done using the standard authorization
     wrapper, with the following actions:

     KAUTH_DEVICE_BLUETOOTH_BCSP
	      Check if operations on a bcsp(4) device are allowed.

	      arg0 is an enum kauth_device_req with one of the following values:

	      KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADD
		       Check if adding and enabling a bcsp(4) device is allowed.

     KAUTH_DEVICE_BLUETOOTH_BTUART
	      Check if operations on a btuart(4) device are allowed.

	      arg0 is an enum kauth_device_req with one of the following values:

	      KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADD
		       Check if adding and enabling a btuart(4) device is allowed.

     KAUTH_DEVICE_BLUETOOTH_RECV
	      Check if a packet can be received from the device.

	      arg0 is the packet type.	For HCI_CMD_PKT packets, arg1 is the opcode, for
	      HCI_EVENT_PKT packets, arg1 is the event ID, and for HCI_ACLDATA_PKT or
	      HCI_SCODATA_PKT packets, arg1 is the connection handle.

     KAUTH_DEVICE_BLUETOOTH_SEND
	      Check if a packet can be sent to the device.

	      arg0 is a struct hci_unit * describing the HCI unit, arg1 is a hci_cmd_hdr_t *
	      describing the packet header.

     KAUTH_DEVICE_BLUETOOTH_SETPRIV
	      Check if privileged settings can be changed.

	      arg0 is a struct hci_unit * describing the HCI unit, arg1 is a struct btreq *
	      describing the request, and arg2 is a u_long describing the command.

   Kernel random device
     Authorization actions relevant to the kernel random device, rnd(4), is done using the stan-
     dard authorization wrapper, with the following actions:

     KAUTH_DEVICE_RND_ADDDATA
	      Check if adding data to the entropy pool is allowed.

     KAUTH_DEVICE_RND_GETPRIV
	      Check if privileged settings and information can be retrieved.

     KAUTH_DEVICE_RND_SETPRIV
	      Check if privileged settings can be changed.

   Credentials Scope
     The credentials scope, ``org.netbsd.kauth.cred'', is a special scope used internally by the
     kauth framework to provide hooking to credential-related operations.

     It is a ``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 aforemen-
     tioned operations, especially in cases where the credentials hold security model-private
     data.

     Notifications are made using the following function, which is internal to kauth:

     int kauth_cred_hook(kauth_cred_t cred, kauth_action_t action, void *arg0, void *arg1)

     With the following actions:

     KAUTH_CRED_COPY
	      The credentials are being copied.  cred are the credentials of the lwp context
	      doing the copy, and arg0 and arg1 are both kauth_cred_t representing the ``from''
	      and ``to'' credentials, respectively.

     KAUTH_CRED_FORK
	      The credentials are being inherited from a parent to a child process during a fork.

	      cred are the credentials of the lwp context doing the fork, and arg0 and arg1 are
	      both struct proc * of the parent and child processes, respectively.

     KAUTH_CRED_FREE
	      The credentials in cred are being freed.

     KAUTH_CRED_INIT
	      The credentials in cred are being initialized.

     Since this is a notify-only scope, all listeners are required to return KAUTH_RESULT_ALLOW.

   Credentials Accessors and Mutators
     kauth has a variety of accessor and mutator routines to handle kauth_cred_t objects.

     The following routines can be used to access and modify the user- and group-ids in a
     kauth_cred_t:

     uid_t kauth_cred_getuid(kauth_cred_t cred)
	      Returns the real user-id from cred.

     uid_t kauth_cred_geteuid(kauth_cred_t cred)
	      Returns the effective user-id from cred.

     uid_t kauth_cred_getsvuid(kauth_cred_t cred)
	      Returns the saved user-id from cred.

     void kauth_cred_setuid(kauth_cred_t cred, uid_t uid)
	      Sets the real user-id in cred to uid.

     void kauth_cred_seteuid(kauth_cred_t cred, uid_t uid)
	      Sets the effective user-id in cred to uid.

     void kauth_cred_setsvuid(kauth_cred_t cred, uid_t uid)
	      Sets the saved user-id in cred to uid.

     gid_t kauth_cred_getgid(kauth_cred_t cred)
	      Returns the real group-id from cred.

     gid_t kauth_cred_getegid(kauth_cred_t cred)
	      Returns the effective group-id from cred.

     gid_t kauth_cred_getsvgid(kauth_cred_t cred)
	      Returns the saved group-id from cred.

     void kauth_cred_setgid(kauth_cred_t cred, gid_t gid)
	      Sets the real group-id in cred to gid.

     void kauth_cred_setegid(kauth_cred_t cred, gid_t gid)
	      Sets the effective group-id in cred to gid.

     void kauth_cred_setsvgid(kauth_cred_t cred, gid_t gid)
	      Sets the saved group-id in cred to gid.

     u_int kauth_cred_getrefcnt(kauth_cred_t cred)
	      Return the reference count for cred.

     The following routines can be used to access and modify the group list in a kauth_cred_t:

     int kauth_cred_ismember_gid(kauth_cred_t cred, gid_t gid, int *resultp)
	      Checks if the group-id gid is a member in the group list of cred.

	      If it is, resultp will be set to one, otherwise, to zero.

	      The return value is an error code, or zero for success.

     u_int kauth_cred_ngroups(kauth_cred_t cred)
	      Return the number of groups in the group list of cred.

     gid_t kauth_cred_group(kauth_cred_t cred, u_int idx)
	      Return the group-id of the group at index idx in the group list of cred.

     int kauth_cred_setgroups(kauth_cred_t cred, const gid_t *groups, size_t ngroups, uid_t
	      gmuid, enum uio_seg seg)
	      Copy ngroups groups from array pointed to by groups to the group list in cred,
	      adjusting the number of groups in cred appropriately.  seg should be either
	      UIO_USERSPACE or UIO_SYSSPACE indicating whether groups is a user or kernel space
	      address.

	      Any groups remaining will be set to an invalid value.

	      gmuid is unused for now, and to maintain interface compatibility with the Darwin
	      KPI.

	      The return value is an error code, or zero for success.

     int kauth_cred_getgroups(kauth_cred_t cred, gid_t *groups, size_t ngroups, enum uio_seg seg)
	      Copy ngroups groups from the group list in cred to the buffer pointed to by groups.
	      seg should be either UIO_USERSPACE or UIO_SYSSPACE indicating whether groups is a
	      user or kernel space address.

	      The return value is an error code, or zero for success.

   Credential Private Data
     kauth provides an interface to allow attaching security-model private data to credentials.

     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 rou-
     tines, while the indirect control is often dictated by events such as process fork, and is
     handled by listening on the credentials scope (see above).

     Attaching private data to credentials works by registering a key to serve as a unique iden-
     tifier, distinguishing various sets of private data that may be associated with the creden-
     tials.  Registering, and deregistering, a key is done by using these routines:

     int kauth_register_key(const char *name, kauth_key_t *keyp)
	      Register new key for private data for name (usually, the security model name).
	      keyp will be used to return the key to be used in further calls.

	      The function returns 0 on success and an error code (see errno(2)) on failure.

     int kauth_deregister_key(kauth_key_t key)
	      Deregister private data key key.

     Once registered, private data may be manipulated by the following routines:

     void kauth_cred_setdata(kauth_cred_t cred, kauth_key_t key, void *data)
	      Set private data for key in cred to be data.

     void * kauth_cred_getdata(kauth_cred_t cred, kauth_key_t key)
	      Retrieve private data for key in cred.

     Note that it is required to use the above routines every time the private data is changed,
     i.e., using kauth_cred_getdata() and later modifying the private data should be accompanied
     by a call to kauth_cred_setdata() with the ``new'' private data.

   Credential Inheritance and Reference Counting
     kauth provides an interface for handling shared credentials.

     When a 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.

     The following routines are available for managing credentials reference counting:

     void kauth_cred_hold(kauth_cred_t cred)
	      Increases reference count to cred by one.

     void kauth_cred_free(kauth_cred_t cred)
	      Decreases the reference count to cred by one.

	      If the reference count dropped to zero, the memory used by cred will be freed.

     Credential inheritance happens during a fork(2), and is handled by the following function:

     void kauth_proc_fork(struct proc *parent, struct proc *child)

     When called, it references the parent's credentials from the child, and calls the creden-
     tials scope's hook with the KAUTH_CRED_FORK action to allow security model-specific handling
     of the inheritance to take place.

   Credentials Memory Management
     Data-structures for credentials, listeners, and scopes are allocated from memory pools man-
     aged by the pool(9) subsystem.

     The kauth_cred_t objects have their own memory management routines:

     kauth_cred_t kauth_cred_alloc(void)
	      Allocates a new kauth_cred_t, initializes its lock, and sets its reference count to
	      one.

   Conversion Routines
     Sometimes it might be necessary to convert a kauth_cred_t to userland's view of credentials,
     a struct uucred, or vice versa.

     The following routines are available for these cases:

     void kauth_uucred_to_cred(kauth_cred_t cred, const struct uucred *uucred)
	      Convert userland's view of credentials to a kauth_cred_t.

	      This includes effective user- and group-ids, a number of groups, and a group list.
	      The reference count is set to one.

	      Note that kauth will try to copy as many groups as can be held inside a
	      kauth_cred_t.

     void kauth_cred_to_uucred(struct uucred *uucred, const kauth_cred_t cred)
	      Convert kauth_cred_t to userland's view of credentials.

	      This includes effective user- and group-ids, a number of groups, and a group list.

	      Note that kauth will try to copy as many groups as can be held inside a struct
	      uucred.

     int kauth_cred_uucmp(kauth_cred_t cred, struct uucred *uucred)
	      Compares cred with the userland credentials in uucred.

	      Common values that will be compared are effective user- and group-ids, and the
	      group list.

   Miscellaneous Routines
     Other routines provided by kauth are:

     void kauth_cred_clone(kauth_cred_t cred1, kauth_cred_t cred2)
	      Clone credentials from cred1 to cred2, except for the lock and reference count.

     kauth_cred_t kauth_cred_dup(kauth_cred_t cred)
	      Duplicate cred.

	      What this routine does is call kauth_cred_alloc() followed by a call to
	      kauth_cred_clone().

     kauth_cred_t kauth_cred_copy(kauth_cred_t cred)
	      Works like kauth_cred_dup(), except for a few differences.

	      If cred already has a reference count of one, it will be returned.  Otherwise, a
	      new kauth_cred_t will be allocated and the credentials from cred will be cloned to
	      it.  Last, a call to kauth_cred_free() for cred will be done.

     kauth_cred_t kauth_cred_get(void)
	      Return the credentials associated with the current LWP.

   Scope Management
     kauth provides routines to manage the creation and deletion of scopes on the system.

     Note that the built-in scopes, the ``generic'' scope and the ``process'' scope, can't be
     deleted.

     kauth_scope_t kauth_register_scope(const char *id, kauth_scope_callback_t cb, void *cookie)
	      Register a new scope on the system.  id is the name of the scope, usually in
	      reverse DNS-like notation.  For example, ``org.netbsd.kauth.myscope''.  cb is the
	      default listener, to which authorization requests for this scope will be dispatched
	      to.  cookie is optional user-data that will be passed to all listeners during
	      authorization on the scope.

     void kauth_deregister_scope(kauth_scope_t scope)
	      Deregister scope from the scopes available on the system, and free the
	      kauth_scope_t object scope.

   Listener Management
     Listeners in kauth are authorization callbacks that are called during an authorization
     request in the scope which they belong to.

     When an authorization request is made, all listeners associated with a scope are called to
     allow, deny, or defer the request.

     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.

     The following KPI is provided for the management of listeners:

     kauth_listener_t kauth_listen_scope(const char *id, kauth_scope_callback_t cb, void *cookie)
	      Create a new listener on the scope with the id id, setting the default listener to
	      cb.  cookie is optional user-data that will be passed to the listener when called
	      during an authorization request.

     void kauth_unlisten_scope(kauth_listener_t listener)
	      Removes listener from the scope which it belongs to, ensuring it won't be called
	      again, and frees the kauth_listener_t object listener.

     kauth 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 free-
     ing any allocated data it used.

     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.

     During the removal of a listener, first 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.

     Listeners might sleep, so no locks can be held when calling an authorization wrapper.

EXAMPLES
     Older code had no abstraction of the security model, so most privilege checks looked like
     this:

	   if (suser(cred, &acflag) == 0)
		   /* allow privileged operation */

     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:

	   if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET,
	       KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM,
	       IPPROTO_TCP) == 0)
		   /* allow opening the socket */

     Note that the securelevel implications were also integrated into the kauth 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.

     To do that you can just grep(1) in the relevant security model directory and have a look at
     the code.

EXTENDING KAUTH
     Although kauth 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.

     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.

     New actions should be added when sets of operations not covered at all belong in an already
     existing scope.

     Requests (or sub-actions) can be added as subsets of existing actions when an operation that
     belongs in an already covered area is introduced.

     Note that all additions should include updates to this manual, the security models shipped
     with NetBSD, and the example skeleton security model.

SEE ALSO
     secmodel(9)

HISTORY
     The kernel authorization framework first appeared in Mac OS X 10.4.

     The kernel authorization framework in NetBSD first appeared in NetBSD 4.0, and is a clean-
     room implementation based on Apple TN2127, available at http://developer.apple.com/tech-
     notes/tn2005/tn2127.html

NOTES
     As kauth in NetBSD is still under active development, it is likely that the ABI, and possi-
     bly the API, will differ between NetBSD 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.

AUTHORS
     Elad Efrat <elad@NetBSD.org> implemented the kernel authorization framework in NetBSD.

     Jason R. Thorpe <thorpej@NetBSD.org> provided guidance and answered questions about the Dar-
     win implementation.

ONE MORE THING
     The kauth framework is dedicated to Brian Mitchell, one of the most talented people I know.
     Thanks for everything.

BSD					 January 16, 2012				      BSD


All times are GMT -4. The time now is 09:53 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password