KAUTH(9)

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:

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:

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 authorize 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:

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:

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_SYSTEM_CPU

Check CPU-manipulation access.

req can be any of the following:

KAUTH_SYSTEM_DEBUG

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

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_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_SYSTEM_PSET

Check processor-set manipulation.

req can be any of the following:

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_SYSTEM_TIME

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

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, indicating 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, indicating 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_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_NETWORK_FIREWALL

Checks if firewall-related operations are allowed.

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

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 (optionally) a pointer to the interface-specific request structure. req indicates the sub-action, and can be one of the following:

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_NETWORK_INTERFACE_SLIP

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

req can be one of the following:

KAUTH_NETWORK_INTERFACE_STRIP

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

req can be one of the following:

KAUTH_NETWORK_INTERFACE_TUN

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

req can be one of the following:

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_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:

Machine-dependent Scope

The machine-dependent (machdep) scope, “org.netbsd.kauth.machdep”, manages machine-dependent 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.

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:

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 respectively. 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 arguments. 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:

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:

Kernel random device

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

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 aforementioned 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:

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:

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

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 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).

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:

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

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:

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 credentials 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 managed by the pool(9) subsystem.

The kauth_cred_t objects have their own memory management routines:

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:

Miscellaneous Routines

Other routines provided by kauth are:

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.

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

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.

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/technotes/tn2005/tn2127.html

NOTES

As kauth in NetBSD is still under active development, it is likely that the ABI, and possibly 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 Darwin implementation.

ONE MORE THING

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

January 16, 2012

NetBSD 6.1

NAME

SYNOPSIS

DESCRIPTION

Types

Terminology

Kernel Programming Interface

Authorization Requests

Generic Scope

System Scope

Process Scope

Network Scope

Machine-dependent Scope

Device Scope

Bluetooth Devices

Kernel random device

Credentials Scope

Credentials Accessors and Mutators

Credential Private Data

Credential Inheritance and Reference Counting

Credentials Memory Management

Conversion Routines

Miscellaneous Routines

Scope Management

Listener Management

EXAMPLES

EXTENDING KAUTH

SEE ALSO

HISTORY

NOTES

AUTHORS

ONE MORE THING