.\" $NetBSD: secmodel.9,v 1.17 2010/12/02 12:54:13 wiz Exp $
.\"
.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 10, 2009
.Dt SECMODEL 9
.Os
.Sh NAME
.Nm secmodel
.Nd security model development guidelines
.Sh SYNOPSIS
.In secmodel/secmodel.h
.Sh DESCRIPTION
.Nx
provides a complete abstraction of the underlying security model used with
the operating system to a set of
.Xr kauth 9
scopes and actions.
.Pp
It is possible to modify the security model -- either slightly or using an
entirely different model -- by attaching/detaching
.Xr kauth 9
listeners.
This document describes this process.
.Ss Background
In
.Nx 4.0 ,
Kernel Authorization --
.Xr kauth 9
-- was introduced as the subsystem responsible for authorization and
credential management.
Before its introduction, there were several ways for providing resource access
control:
.Bl -dash -offset indent -compact
.It
Checking if the user in question is the superuser via
.Fn suser .
.It
Comparing the user-id against hard-coded values, often zero,
.It
Checking the system securelevel.
.El
.Pp
The problem with the above is that the interface ("can X do Y?") was
tightly coupled with the implementation ("is X Z?").
.Xr kauth 9
allowed us to separate them, dispatching requests with highly detailed
context using
a consistent and clear KPI.
.Pp
The result is a pluggable framework for attaching "listeners" that can
modify the behavior of the system, security-wise.
It allows us to maintain the existing security model (based on a single
superuser and above-superuser restrictions known as securelevel) but easily
decouple it from the system, given we want to use a different one.
.Pp
The different security model can be implemented in the kernel or loaded as a
module, base its decisions on available information, dispatch the decision to a
userspace daemon, or even to a centralized network authorization server.
.Ss The kauth(9) KPI
Before writing a new security model, one should be familiar with the
.Xr kauth 9
KPI, its limitations, requirements, and so on.
.Pp
First, some terminology.
According to
.Xr kauth 9 ,
the system is logically divided to scopes, where each scope denotes a
different area of interest in the system -- something like a namespace.
For example,
.Nx
has the process, network, and machdep scopes, representing process-related,
network-related, and machdep-related actions.
.Pp
Each scope has a collection of actions -- or requests -- forming the high
level indication of the request type.
Each request is automatically associated with credentials and between zero
to four arguments providing the request context.
.Pp
For example, in the process scope there are requests such as "can signal",
"can change rlimits", and "can change corename".
.Pp
Each scope in the system is associated with listeners, which are actually
callback routines, that get called when an authorization request on the
relevant scope takes place.
.Pp
Every listener receives the request and its context, and can make a decision
of either "allow", "deny", or "defer" (if it doesn't want to be the one
deciding).
.Pp
It is important to note that a single "deny" is enough to fail a request,
and at least a single "allow" is required to allow it.
In other words, it is impossible to attach listeners that weaken the security
of the system or override decisions made by other listeners.
.Pp
At last, there are several things you should remember about
.Xr kauth 9 :
.Bl -dash -offset indent
.It
Authorization requests can not be issued when the kernel is holding any
locks.
This is a requirement from kernel code, to allow designing security models
where the request should be dispatched to userspace or a different host.
.It
Private listener data -- such as internal data-structures -- is entirely
under the responsibility of the developer.
Locking, synchronization, and garbage collection are all things that
.Xr kauth 9
does
.Em not
take care of for you!
.El
.Ss Writing a new security model
A security model is composed of (code-wise) the following components:
.Bl -enum -offset indent
.It
Entry routines, named
.Fn secmodel_\*[Lt]model\*[Gt]_init
and
.Fn secmodel_\*[Lt]model\*[Gt]_start ,
used to initialize and start the security model.
.Pp
If the security model is to be started automatically by the kernel and is
compiled in it, a function called
.Fn secmodel_start
can be added to call the model's start routine.
.Pp
If the security model is to be built and used as a module, another function
called
.Fn secmodel_\*[Lt]model\*[Gt]_stop ,
to stop the security model in case the module is to be unloaded.
.It
A sysctl(9) setup routine for the model.
This should create an entry for the model in the
.Xr sysctl 9
namespace, under the "security.models.\*[Lt]model\*[Gt]" hierarchy.
.Pp
All "knobs" for the model should be located under the new node, as well
as a mandatory "name" variable, indicating a descriptive human-readable
name for the model.
.Pp
If the module is to be used as a module, explicit calls to the setup
routine and
.Fn sysctl_teardown
are to be used to create and destroy the
.Xr sysctl 9
tree.
.It
If the model uses any private data inside credentials, listening on
the credentials scope,
.Dv KAUTH_SCOPE_CRED ,
is required.
.It
Optionally, internal data-structures used by the model.
These must all be prefixed with "secmodel_\*[Lt]model\*[Gt]_".
.It
A set of listeners, attached to various scopes, used to enforce the policy
the model intends to implement.
.It
Finally, a security model should register itself when loaded using
.Fn secmodel_register
and deregister it when unloaded (if used as a module) using
.Fn secmodel_deregister .
.El
.Pp
Below is sample code for a
.Xr kauth 9
network scope listener for the
.Em jenna
security model.
It is used to allow users with a user-id below 1000 bind to reserved ports
(for example, 22/TCP):
.Bd -literal -offset indent
int
secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action,
    void *cookie, void *arg0, void *arg1, void *arg2, void *arg3)
{
	int result;

	/* Default defer. */
	result = KAUTH_RESULT_DEFER;

	switch (action) {
	case KAUTH_NETWORK_BIND:
		/*
		 * We only care about bind(2) requests to privileged
		 * ports.
		 */
		if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) {
			/*
			 * If the user-id is below 1000, which may
			 * indicate a "reserved" user-id, allow the
			 * request.
			 */
			if (kauth_cred_geteuid(cred) \*[Lt] 1000)
				result = KAUTH_RESULT_ALLOW;
		}
		break;
	}

	return (result);
}
.Ed
.Pp
There are two main issues, however, with that listener, that you should be
aware of when approaching to write your own security model:
.Bl -enum -offset indent
.It
As mentioned,
.Xr kauth 9
uses restrictive decisions: if you attach this listener on-top of an existing
security model, even if it would allow the request, it could still be failed.
.It
If you attach this listener as the only listener for the network scope,
there are many other requests that will be deferred and, eventually,
denied -- which may not be desired.
.El
.Pp
That's why before implementing listeners, it should be clear whether they
implement an entirely new from scratch security model, or add on-top of an
existing one.
.Ss Adding on-top of an existing security model
One of the shortcomings of
.Xr kauth 9
is that it does not provide any stacking mechanism, similar to Linux Security
Modules (LSM).
This, however, is considered a feature in reducing dependency on other people's
code.
.Pp
To properly "stack" minor adjustments on-top of an existing security model,
one could use one of two approaches:
.Bl -dash
.It
Registering an internal scope for the security model to be used as a
fall-back when requests are deferred.
.Pp
This requires the security model developer to add an internal scope for
every scope the model partly covers, and registering the fall-back
listeners to it.
In the model's listener(s) for the scope, when a defer decision is made, the
request is passed to be authorized on the internal scope, effectively using
the fall-back security model.
.Pp
Here's example code that implements the above:
.Bd -literal -offset indent
#include \*[Lt]secmodel/bsd44/bsd44.h\*[Gt]

/*
 * Internal fall-back scope for the network scope.
 */
#define	JENNA_ISCOPE_NETWORK "jenna.iscope.network"
static kauth_scope_t secmodel_jenna_iscope_network;

/*
 * Jenna's entry point. Register internal scope for the network scope
 * which we partly cover for fall-back authorization.
 */
void
secmodel_jenna_start(void)
{
	secmodel_jenna_iscope_network = kauth_register_scope(
	    JENNA_ISCOPE_NETWORK, NULL, NULL);

	kauth_listen_scope(JENNA_ISCOPE_NETWORK,
	    secmodel_bsd44_suser_network_cb, NULL);
	kauth_listen_scope(JENNA_ISCOPE_NETWORK,
	    secmodel_securelevel_network_cb, NULL);
}

/*
 * Jenna sits on top of another model, effectively filtering requests.
 * If it has nothing to say, it discards the request. This is a good
 * example for fine-tuning a security model for a special need.
 */
int
secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action,
    void *cookie, void *arg0, void *arg1, void *arg2, void *arg3)
{
	int result;

	/* Default defer. */
	result = KAUTH_RESULT_DEFER;

	switch (action) {
	case KAUTH_NETWORK_BIND:
		/*
		 * We only care about bind(2) requests to privileged
		 * ports.
		 */
		if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) {
			if (kauth_cred_geteuid(cred) \*[Lt] 1000)
				result = KAUTH_RESULT_ALLOW;
		}
		break;
	}

	/*
	 * If we have don't have a decision, fall-back to the bsd44
	 * security model.
	 */
	if (result == KAUTH_RESULT_DEFER)
		result = kauth_authorize_action(
		    secmodel_jenna_iscope_network, cred, action,
		    arg0, arg1, arg2, arg3);

	return (result);
}
.Ed
.It
If the above is not desired, or cannot be used for any reason, there is
always the ability to manually call the fall-back routine:
.Bd -literal -offset indent
int
secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action,
    void *cookie, void *arg0, void *arg1, void *arg2, void *arg3)
{
	int result;

	/* Default defer. */
	result = KAUTH_RESULT_DEFER;

	switch (action) {
	case KAUTH_NETWORK_BIND:
		/*
		 * We only care about bind(2) requests to privileged
		 * ports.
		 */
		if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) {
			if (kauth_cred_geteuid(cred) \*[Lt] 1000)
				result = KAUTH_RESULT_ALLOW;
		}
		break;
	}

	/*
	 * If we have don't have a decision, fall-back to the bsd44
	 * security model's suser behavior.
	 */
	if (result == KAUTH_RESULT_DEFER)
		result = secmodel_bsd44_suser_network_cb(cred, action,
		    cookie, arg0, arg1, arg2, arg3);

	return (result);
}
.Ed
.El
.Ss Writing a new security model from scratch
When writing a security model from scratch, aside from the obvious issues of
carefully following the desired policy to be implemented and paying attention
to all of the issues outlined above, one must also remember that any unhandled
requests will be denied by default.
.Pp
To make it easier on developers to write new security models from scratch,
.Nx
maintains skeleton listeners that contain every possible request and
arguments.
.Ss Available security models
The following is a list of security models available in the default
.Nx
distribution.
To choose, one should edit
.Pa sys/conf/std .
.Bl -tag -width secmodel_overlay
.It secmodel_bsd44
Traditional
.Nx
security model, derived from
.Bx 4.4 .
.It secmodel_overlay
Sample overlay security model, sitting on-top of
.Xr secmodel_bsd44 9 .
.El
.Sh FILES
.Pa /usr/share/examples/secmodel
.Sh SEE ALSO
.Xr kauth 9 ,
.Xr secmodel_bsd44 9 ,
.Xr secmodel_overlay 9
.Sh AUTHORS
.An Elad Efrat Aq elad@NetBSD.org