Manuál NetBSD

KAUTH(9) NetBSD 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 membership 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 allow, deny, or defer the operation -- in which case, the decision is left to the other listeners.

For an operation to be allowed, all listeners must not return any deny or defer decisions.

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. Zero indicates success -- the operation is allowed; EPERM (see errno(2)) indicates failure -- the operation is denied.

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.

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

KAUTH_GENERIC_CANSEE

Checks whether an object with one set of credentials can access information about another object, possibly with a different set of credentials.

arg0 contains the credentials of the object looked at.

This request should be issued only in cases where generic credentials check is required; otherwise it is recommended to use the object-specific routines.

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

Check if an LKM request is allowed.

arg1 is the command.

KAUTH_SYSTEM_MKNOD

Check if creating devices is allowed.

KAUTH_SYSTEM_RAWIO

This request groups raw access to system resources.

req indicates what is the underlying resource being access, and can be one of the following:

KAUTH_REQ_SYSTEM_RAWIO_DISK

The underlying resource is a disk.

KAUTH_REQ_SYSTEM_RAWIO_MEMORY

The underlying resource is the machine memory.

arg1 indicates the access requested, and can be one of the following:

KAUTH_REQ_SYSTEM_RAWIO_READ

Read access is requested.

KAUTH_REQ_SYSTEM_RAWIO_RW

Both read and write access are requested.

KAUTH_REQ_SYSTEM_RAWIO_WRITE

Write access is requested.

If the request is for a disk device, arg2 should contain a struct vnode * for the vnode in question, and arg3 should contain the device number.

The behavior if any of the above is not provided is policy-dependent.

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

Check if setting the time backwards 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.

KAUTH_REQ_SYSTEM_TIME_RTCOFFSET

Check if changing the RTC offset 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_CANSIGNAL

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

arg1 and arg2 contain the credentials (kauth_cred_t) and the process data (struct proc *) of the process the signal is posted to, respectively. arg3 is the signal to be posted.

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.

KAUTH_PROCESS_CORENAME

Checks whether the coredump name for the process p can be changed.

KAUTH_PROCESS_RESOURCE

Groups authorization requests related to resource management. arg0 indicates the sub-action, and can be one of the following:

KAUTH_REQ_PROCESS_RESOURCE_NICE

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

KAUTH_REQ_PROCESS_RESOURCE_RLIMIT

Checks whether the rlimit value for arg3 in p can be set to arg2.

KAUTH_PROCESS_SETID

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

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

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

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(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_SOCKET_RAWSOCK

Checks if opening a raw socket is allowed.

KAUTH_REQ_NETWORK_SOCKET_CANSEE

Checks if looking at the socket passed is allowed.

arg1 is a struct socket * describing the socket.

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, enum kauth_machdep_req req, void *arg1, void *arg2, void *arg3)

In this scope, req always indicates the machine for the request. Below is the list of available request hierarchy.

KAUTH_MACHDEP_X86

The request is x86 specific.

Available requests as arg1 are:

KAUTH_REQ_MACHDEP_X86_IOPL

Checks if IOPL is allowed to be modified.

KAUTH_REQ_MACHDEP_X86_IOPERM

Checks if IOPERM is allowed to be modified.

KAUTH_REQ_MACHDEP_X86_MTRR_SET

Checks if the MTRR can be set.

KAUTH_MACHDEP_X86_64

The request is x86-64 specific.

Available requests as arg1 are:

KAUTH_REQ_MACHDEP_X86_64_MTRR_GET

Check if MTRR values can be retrieved.

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, and any other hardware. Network devices specifically are handled by the network scope.

This scope has an authorization routine per device class on the system.

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. The second argument is 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.

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.

int 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, gid_t *groups, size_t ngroups, uid_t gmuid)

Copy ngroups groups from array pointed to by groups to the group list in cred, adjusting the number of groups in cred appropriately.

Any groups remaining will be set to an invalid value.

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

int kauth_cred_getgroups(kauth_cred_t cred, gid_t *groups, size_t ngroups)

Copy ngroups groups from the group list in cred to the buffer pointed to by groups.

The number of groups in cred will be returned.

Credentials Inheritance and Reference Counting
kauth provides a KPI for handling a kauth_cred_t in shared credentials situations and credential inheritance.

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. One such case is during a fork(2) where the child process and its LWPs inherit the credentials of the parent.

To prevent freeing a kauth_cred_t while it is still referenced, the following routines are available to maintain its reference count:

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 returned back to the memory pool.

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:

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 a predecessing type, such as struct pcred or struct ucred, or convert credentials passed from userland as a struct uucred to a kauth_cred_t.

The following routines are available for these cases:

void kauth_cred_topcred(kauth_cred_t cred, struct pcred *pcred)

Convert a kauth_cred_t to a struct pcred.

This includes real and saved user- and group-ids and reference count, copied from cred. The pc_ucred field in the destination is set to NULL.

void kauth_cred_toucred(kauth_cred_t cred, struct ucred *ucred)

Convert a kauth_cred_t to a struct ucred.

This includes effective user- and group-ids, number of groups, and the group list from cred.

Note that kauth will try to copy as many groups as ucred can hold.

void kauth_cred_uucvt(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. The addition of groups will also guarantee order and no duplicates.

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.

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.

void kauth_unlisten_scope(kauth_listener_t listener)

Remove listener from the scope which it belongs to.

Effectively what this does is is remove the callback from the chain of functions to be called when an authorization request is made, preventing from the listener from being entered in the future.

kauth provides no means for synchronization within listeners. It is the the programmer’s responsibility to make sure data used by the listener is properly locked during its use, as it can be accessed simultaneously from the same listener called multiple times. It is also the programmer’s responsibility to do garbage collection after the listener, possibly freeing any allocated data it used.

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.

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

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.

NetBSD 4.0 October 13, 2006 NetBSD 4.0