kauth introduces some new concepts, namely ``scopes'' and ``listeners'', which will be detailed together with other useful information for kernel developers in this document.
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.
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.
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.
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
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
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.
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
KAUTH_SYSTEM_CHROOT
KAUTH_REQ_SYSTEM_CHROOT_CHROOT
KAUTH_REQ_SYSTEM_CHROOT_FCHROOT
KAUTH_SYSTEM_CPU
req can be any of the following:
KAUTH_REQ_SYSTEM_CPU_SETSTATE
KAUTH_SYSTEM_DEBUG
KAUTH_REQ_SYSTEM_DEBUG_IPKDB
KAUTH_SYSTEM_FILEHANDLE
KAUTH_SYSTEM_LKM
arg1 is the command.
KAUTH_SYSTEM_MKNOD
KAUTH_SYSTEM_MOUNT
req can be any of the following:
KAUTH_REQ_SYSTEM_MOUNT_GET
struct
mount
*
with the mount structure in question,
arg2
is a
void
*
with file-system specific data, if any.
KAUTH_REQ_SYSTEM_MOUNT_NEW
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 specific data, if any.
KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT
arg1
is a
struct
mount
*
with the mount in question.
KAUTH_REQ_SYSTEM_MOUNT_UPDATE
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
req can be any of the following:
KAUTH_REQ_SYSTEM_PSET_ASSIGN
KAUTH_REQ_SYSTEM_PSET_BIND
KAUTH_REQ_SYSTEM_PSET_CREATE
KAUTH_REQ_SYSTEM_PSET_DESTROY
KAUTH_SYSTEM_REBOOT
KAUTH_SYSTEM_SETIDCORE
KAUTH_SYSTEM_SWAPCTL
KAUTH_SYSTEM_SYSCTL
KAUTH_REQ_SYSTEM_SYSCTL_ADD
KAUTH_REQ_SYSTEM_SYSCTL_DELETE
KAUTH_REQ_SYSTEM_SYSCTL_DESC
KAUTH_REQ_SYSTEM_SYSCTL_PRVT
KAUTH_SYSTEM_TIME
KAUTH_REQ_SYSTEM_TIME_ADJTIME
KAUTH_REQ_SYSTEM_TIME_NTPADJTIME
KAUTH_REQ_SYSTEM_TIME_SYSTEM
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 (eg.
/dev/clockctl
)
or not.
KAUTH_REQ_SYSTEM_TIME_RTCOFFSET
KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS
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
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(2),
and normally requires privileged credentials.
KAUTH_PROCESS_PROCFS
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
arg1 is the ptrace(2) command.
KAUTH_PROCESS_CANSEE
arg1
indicates the class of information being viewed, and can 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
KAUTH_PROCESS_SCHEDULER_SETAFFINITY
KAUTH_PROCESS_SCHEDULER_GETPARAMS
KAUTH_PROCESS_SCHEDULER_SETPARAMS
KAUTH_PROCESS_SIGNAL
p is the process the signal is being posted to, and arg1 is the signal number.
KAUTH_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
int
indicating how many processes exist on the system at the time of the check.
KAUTH_PROCESS_KEVENT_FILTER
KAUTH_PROCESS_NICE
KAUTH_PROCESS_RLIMIT
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
KAUTH_PROCESS_STOPFLAG
arg1
indicates the flag, and can be either
P_STOPEXEC
,
P_STOPEXIT
,
or
P_STOPFORK
respectively.
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
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
req allows to indicate the type of the request to structure listeners and callers easier. Supported request types:
KAUTH_REQ_NETWORK_BIND_PRIVPORT
KAUTH_NETWORK_FIREWALL
req indicates the sub-action, and can be one of the following:
KAUTH_REQ_NETWORK_FIREWALL_FW
KAUTH_REQ_NETWORK_FIREWALL_NAT
KAUTH_NETWORK_INTERFACE
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:
KAUTH_REQ_NETWORK_INTERFACE_GET
KAUTH_REQ_NETWORK_INTERFACE_GETPRIV
KAUTH_REQ_NETWORK_INTERFACE_SET
KAUTH_REQ_NETWORK_INTERFACE_SETPRIV
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_FORWSRCRT
KAUTH_NETWORK_NFS
req can be any of the following:
KAUTH_REQ_NETWORK_NFS_EXPORT
KAUTH_REQ_NETWORK_NFS_SVC
KAUTH_NETWORK_ROUTE
arg1
is the
struct
rt_msghdr
*
for the request.
KAUTH_NETWORK_SOCKET
req allows to indicate the type of the request to structure listeners and callers easier. Supported request types:
KAUTH_REQ_NETWORK_SOCKET_RAWSOCK
KAUTH_REQ_NETWORK_SOCKET_OPEN
int
parameters describing the domain, socket type, and protocol,
respectively.
KAUTH_REQ_NETWORK_SOCKET_CANSEE
arg1
is a
struct
socket
*
describing the socket.
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_IOPERM_GET
KAUTH_MACHDEP_IOPERM_SET
KAUTH_MACHDEP_IOPL
KAUTH_MACHDEP_LDT_GET
KAUTH_MACHDEP_LDT_SET
KAUTH_MACHDEP_MTRR_GET
KAUTH_MACHDEP_MTRR_SET
KAUTH_MACHDEP_UNMANAGEDMEM
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
KAUTH_DEVICE_TTY_PRIVSET
KAUTH_DEVICE_TTY_STI
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.
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 :
int
kauth_cred_hook(, kauth_cred_t cred
, kauth_action_t action
, void *arg0
, void *arg1
)
With the following actions:
KAUTH_CRED_COPY
kauth_cred_t
representing the
``from''
and
``to''
credentials, respectively.
KAUTH_CRED_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
KAUTH_CRED_INIT
Since this is a notify-only scope, all listeners are required to return
KAUTH_RESULT_ALLOW
.
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
)
uid_t
kauth_cred_geteuid(
, kauth_cred_t cred
)
uid_t
kauth_cred_getsvuid(
, kauth_cred_t cred
)
void
kauth_cred_setuid(
, kauth_cred_t cred
, uid_t uid
)
void
kauth_cred_seteuid(
, kauth_cred_t cred
, uid_t uid
)
void
kauth_cred_setsvuid(
, kauth_cred_t cred
, uid_t uid
)
gid_t
kauth_cred_getgid(
, kauth_cred_t cred
)
gid_t
kauth_cred_getegid(
, kauth_cred_t cred
)
gid_t
kauth_cred_getsvgid(
, kauth_cred_t cred
)
void
kauth_cred_setgid(
, kauth_cred_t cred
, gid_t gid
)
void
kauth_cred_setegid(
, kauth_cred_t cred
, gid_t gid
)
void
kauth_cred_setsvgid(
, kauth_cred_t cred
, gid_t gid
)
u_int
kauth_cred_getrefcnt(
, kauth_cred_t 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
)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
)
gid_t
kauth_cred_group(
, kauth_cred_t cred
, u_int idx
)
int
kauth_cred_setgroups(
, kauth_cred_t cred
, const gid_t *groups
, size_t ngroups
, uid_t gmuid
, enum uio_seg seg
)
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
)
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.
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:
int
kauth_register_key(
, const char *name
, kauth_key_t *keyp
)The function returns 0 on success and an error code (see errno(2)) on failure.
int
kauth_deregister_key(
, kauth_key_t 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
)
void
*
kauth_cred_getdata(
, kauth_cred_t cred
, kauth_key_t key
)
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.
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
)
void
kauth_cred_free(
, kauth_cred_t cred
)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 credentials scope's hook with the
KAUTH_CRED_FORK
action to allow security model-specific handling of the inheritance
to take place.
The
kauth_cred_t
objects have their own memory management routines:
kauth_cred_t
kauth_cred_alloc(
, void
)
kauth_cred_t
,
initializes its lock, and sets its reference count to one.
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
)
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
)
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
)Common values that will be compared are effective user- and group-ids, and the group list.
void
kauth_cred_clone(
, kauth_cred_t cred1
, kauth_cred_t cred2
)
kauth_cred_t
kauth_cred_dup(
, kauth_cred_t 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
)
),
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
)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
)
void
kauth_deregister_scope(
, kauth_scope_t scope
)
kauth_scope_t
object
scope.
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
)
void
kauth_unlisten_scope(
, kauth_listener_t listener
)
kauth_listener_t
object
listener.
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.
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.
Adding a new scope should happen only when an entire subsystem is introduced and it is assumed other parts of the kernel may want to interfere with its inner-workings. When a subsystem that has the potential of impacting the security if the system is introduced, existing security modules must be updated to also handle actions on the newly added scope.
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.
The kernel authorization framework in NetBSD first appeared in NetBSD4.0, and is a clean-room implementation based on Apple TN2127, available at http://developer.apple.com/technotes/tn2005/tn2127.html
Jason R. Thorpe <thorpej@NetBSD.org>
provided guidance and answered questions about the Darwin implementation.