Module Name: src
Committed By: jym
Date: Sun Dec 4 21:08:46 UTC 2011
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/libpthread: affinity.3
src/lib/librt: sched.3
src/share/man/man9: Makefile secmodel.9 secmodel_bsd44.9
secmodel_securelevel.9 secmodel_suser.9
Added Files:
src/share/man/man9: secmodel_extensions.9
Log Message:
Improvements in secmodel(9). Document secmodel_register(9), _deregister(9)
and _eval(9).
Add secmodel_extensions(9), and indicate the new sysctl(7) to let
ordinary users control the CPU affinity (user_set_cpu_affinity).
To generate a diff of this commit:
cvs rdiff -u -r1.1715 -r1.1716 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.6 -r1.7 src/lib/libpthread/affinity.3
cvs rdiff -u -r1.10 -r1.11 src/lib/librt/sched.3
cvs rdiff -u -r1.361 -r1.362 src/share/man/man9/Makefile
cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/secmodel.9
cvs rdiff -u -r1.13 -r1.14 src/share/man/man9/secmodel_bsd44.9
cvs rdiff -u -r0 -r1.1 src/share/man/man9/secmodel_extensions.9
cvs rdiff -u -r1.10 -r1.11 src/share/man/man9/secmodel_securelevel.9
cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/secmodel_suser.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1715 src/distrib/sets/lists/comp/mi:1.1716
--- src/distrib/sets/lists/comp/mi:1.1715 Tue Nov 29 03:40:42 2011
+++ src/distrib/sets/lists/comp/mi Sun Dec 4 21:08:37 2011
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1715 2011/11/29 03:40:42 tls Exp $
+# $NetBSD: mi,v 1.1716 2011/12/04 21:08:37 jym Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -10510,7 +10510,11 @@
./usr/share/man/cat9/scsipi.0 comp-sys-catman .cat
./usr/share/man/cat9/secmodel.0 comp-sys-catman .cat
./usr/share/man/cat9/secmodel_bsd44.0 comp-sys-catman .cat
+./usr/share/man/cat9/secmodel_deregister.0 comp-sys-catman .cat
+./usr/share/man/cat9/secmodel_eval.0 comp-sys-catman .cat
+./usr/share/man/cat9/secmodel_extensions.0 comp-sys-catman .cat
./usr/share/man/cat9/secmodel_overlay.0 comp-sys-catman .cat
+./usr/share/man/cat9/secmodel_register.0 comp-sys-catman .cat
./usr/share/man/cat9/secmodel_securelevel.0 comp-sys-catman .cat
./usr/share/man/cat9/secmodel_suser.0 comp-sys-catman .cat
./usr/share/man/cat9/seldestroy.0 comp-sys-catman .cat
@@ -16612,7 +16616,11 @@
./usr/share/man/html9/scsipi.html comp-sys-htmlman html
./usr/share/man/html9/secmodel.html comp-sys-htmlman html
./usr/share/man/html9/secmodel_bsd44.html comp-sys-htmlman html
+./usr/share/man/html9/secmodel_deregister.html comp-sys-htmlman html
+./usr/share/man/html9/secmodel_eval.html comp-sys-htmlman html
+./usr/share/man/html9/secmodel_extensions.html comp-sys-htmlman html
./usr/share/man/html9/secmodel_overlay.html comp-sys-htmlman html
+./usr/share/man/html9/secmodel_register.html comp-sys-htmlman html
./usr/share/man/html9/secmodel_securelevel.html comp-sys-htmlman html
./usr/share/man/html9/secmodel_suser.html comp-sys-htmlman html
./usr/share/man/html9/seldestroy.html comp-sys-htmlman html
@@ -22909,7 +22917,11 @@
./usr/share/man/man9/scsipi.9 comp-sys-man .man
./usr/share/man/man9/secmodel.9 comp-sys-man .man
./usr/share/man/man9/secmodel_bsd44.9 comp-sys-man .man
+./usr/share/man/man9/secmodel_deregister.9 comp-sys-man .man
+./usr/share/man/man9/secmodel_eval.9 comp-sys-man .man
+./usr/share/man/man9/secmodel_extensions.9 comp-sys-man .man
./usr/share/man/man9/secmodel_overlay.9 comp-sys-man .man
+./usr/share/man/man9/secmodel_register.9 comp-sys-man .man
./usr/share/man/man9/secmodel_securelevel.9 comp-sys-man .man
./usr/share/man/man9/secmodel_suser.9 comp-sys-man .man
./usr/share/man/man9/seldestroy.9 comp-sys-man .man
Index: src/lib/libpthread/affinity.3
diff -u src/lib/libpthread/affinity.3:1.6 src/lib/libpthread/affinity.3:1.7
--- src/lib/libpthread/affinity.3:1.6 Fri Jul 9 20:58:38 2010
+++ src/lib/libpthread/affinity.3 Sun Dec 4 21:08:44 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: affinity.3,v 1.6 2010/07/09 20:58:38 wiz Exp $
+.\" $NetBSD: affinity.3,v 1.7 2011/12/04 21:08:44 jym Exp $
.\"
.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd July 9, 2010
+.Dd December 4, 2011
.Dt AFFINITY 3
.Os
.Sh NAME
@@ -65,6 +65,22 @@ Note that
must be created and initialized using the
.Xr cpuset 3
functions.
+.Sh IMPLEMENTATION NOTES
+Setting CPU
+.Xr affinity 3
+requires super-user privileges.
+Ordinary users can be allowed to control CPU affinity
+of their threads via the
+.Pa security.models.extensions.user_set_cpu_affinity
+.Xr sysctl 7 .
+See
+.Xr secmodel_extensions 9 .
+.Pp
+Portable applications should not use the
+.Fn pthread_setaffinity_np
+and
+.Fn pthread_getaffinity_np
+functions.
.Sh RETURN VALUES
The
.Fn pthread_setaffinity_np
Index: src/lib/librt/sched.3
diff -u src/lib/librt/sched.3:1.10 src/lib/librt/sched.3:1.11
--- src/lib/librt/sched.3:1.10 Mon Apr 25 23:14:33 2011
+++ src/lib/librt/sched.3 Sun Dec 4 21:08:44 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: sched.3,v 1.10 2011/04/25 23:14:33 wiz Exp $
+.\" $NetBSD: sched.3,v 1.11 2011/12/04 21:08:44 jym Exp $
.\"
.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 6, 2010
+.Dd December 4, 2011
.Dt SCHED 3
.Os
.Sh NAME
@@ -148,6 +148,16 @@ into the
.Fa cpuset .
.El
.Sh IMPLEMENTATION NOTES
+Setting CPU
+.Xr affinity 3
+requires super-user privileges.
+Ordinary users can be allowed to control CPU affinity
+of their threads via the
+.Pa security.models.extensions.user_set_cpu_affinity
+.Xr sysctl 7 .
+See
+.Xr secmodel_extensions 9 .
+.Pp
Portable applications should not use the
.Fn sched_setaffinity_np
and
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.361 src/share/man/man9/Makefile:1.362
--- src/share/man/man9/Makefile:1.361 Tue Nov 29 03:40:41 2011
+++ src/share/man/man9/Makefile Sun Dec 4 21:08:45 2011
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.361 2011/11/29 03:40:41 tls Exp $
+# $NetBSD: Makefile,v 1.362 2011/12/04 21:08:45 jym Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -45,8 +45,9 @@ MAN= accept_filter.9 accf_data.9 accf_ht
rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \
scanc.9 \
sched_4bsd.9 sched_m2.9 scsipi.9 \
- secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \
- secmodel_suser.9 SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
+ secmodel_bsd44.9 secmodel_extensions.9 \
+ secmodel_overlay.9 secmodel_securelevel.9 secmodel_suser.9 \
+ SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
signal.9 skpc.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \
store.9 suspendsched.9 \
sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
@@ -691,6 +692,10 @@ MLINKS+=STACK.9 STACK_ALLOC.9 \
STACK.9 STACK_ALIGN.9 \
STACK.9 STACK_GROW.9 \
STACK.9 STACK_SHRINK.9
+MAN+= secmodel.9
+MLINKS+=secmodel.9 secmodel_register.9 \
+ secmodel.9 secmodel_eval.9 \
+ secmodel.9 secmodel_deregister.9
MAN+= select.9
MLINKS+=select.9 selinit.9 \
select.9 seldestroy.9 \
Index: src/share/man/man9/secmodel.9
diff -u src/share/man/man9/secmodel.9:1.17 src/share/man/man9/secmodel.9:1.18
--- src/share/man/man9/secmodel.9:1.17 Thu Dec 2 12:54:13 2010
+++ src/share/man/man9/secmodel.9 Sun Dec 4 21:08:45 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: secmodel.9,v 1.17 2010/12/02 12:54:13 wiz Exp $
+.\" $NetBSD: secmodel.9,v 1.18 2011/12/04 21:08:45 jym Exp $
.\"
.\" Copyright (c) 2006 Elad Efrat <e...@netbsd.org>
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\" (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
+.Dd December 4, 2011
.Dt SECMODEL 9
.Os
.Sh NAME
@@ -33,141 +33,201 @@
.Nd security model development guidelines
.Sh SYNOPSIS
.In secmodel/secmodel.h
+.Ft int
+.Fn secmodel_register "secmodel_t *sm" "const char *id" "const char *name" \
+ "prop_dictionary_t behavior" "secmodel_eval_t sm_eval" \
+ "secmodel_setinfo_t sm_setinfo"
+.Ft int
+.Fn secmodel_deregister "secmodel_t sm"
+.Ft int
+.Fn secmodel_eval "const char *id" "const char *what" "void *arg" "void *ret"
+.Ft static int
+.Fn secmodel_\*[Lt]model\*[Gt]_eval "const char *what" "void *arg" \
+ "void *ret"
.Sh DESCRIPTION
.Nx
-provides a complete abstraction of the underlying security model used with
-the operating system to a set of
+provides a complete abstraction of the underlying security model used within
+the operating system through a set of
.Xr kauth 9
scopes and actions.
+It allows maintaining the traditional security model (based on a single
+.Em super-user
+and above-super-user restrictions known as
+.Em securelevel )
+while decoupling it easily from the system.
.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.
+This can be done via the
+.Nm
+pluggable framework.
+.Pp
+A
+.Nm
+is typically implemented as a kernel
+.Xr module 9 ,
+and can be either built-in statically or loaded dynamically at run-time.
+They base their decisions on available information, either directly from
+kernel, from a userspace daemon or even from a centralized network
+authorization server.
+.Sh DATA TYPES
+The
+.Nm
+framework offers the following data types:
+.Bl -tag -width secmodel_t
+.It Fa secmodel_t
+An opaque type that describes a
+.Nm .
+.El
+.Sh FUNCTIONS
+.Bl -tag -width xxxxxxx
+.It Fn secmodel_register "sm" "id" "name" "behavior" "sm_eval" "sm_setinfo"
+Register a security model to the
+.Nm
+framework and stores its description inside
+.Fa sm .
+.Bl -tag -width sm_setinfo
+.It Fa sm
+The
+.Nm
+description.
+.It Fa id
+The unique identifier of the
+.Nm .
+.It Fa name
+The descriptive human-readable name of the
+.Nm .
+.It Fa behavior
+(optional) a
+.Xr prop_dictionary 3
+that declares the behavior of this security model, like
+.Do copy credentials on fork . Dc
+.It Fa sm_eval
+(optional) the
+.Fn secmodel_\*[Lt]model\*[Gt]_eval
+callback used by a
+.Nm
+to register an evaluation routine that can be queried later
+by another security model.
+.It Fa sm_setinfo
+(optional) the
+.Fn secmodel_\*[Lt]model\*[Gt]_setinfo
+callback used by a
+.Nm
+to register a routine that permits other security models to
+alter the
+.Nm
+internals.
+Currently not implemented.
+.El
+.It Fn secmodel_deregister "sm"
+Deregister the
+.Nm
+described by
+.Fa sm .
+.It Fn secmodel_eval "id" "what" "arg" "ret"
+Call the evaluation callback implemented by a security model.
+The return value can be either:
+.Bl -dash -compact -offset xxxxxx
+.It
+zero (0), when the call succeeded.
+.It
+positive, when the error comes directly from the
+.Nm
+framework.
+.It
+negative, when the error comes from the evaluation callback
+implemented in the targetted security model.
+The value is then implementation-defined.
.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
+.Bl -tag -width what
+.It Fa id
+The unique identifier of the targetted
+.Nm .
+.It Fa what
+The query that will be passed down to the targetted
+.Nm .
+.It Fa arg
+The arguments passed to the evaluation routine of the targetted
+.Nm .
+.It Fa ret
+The answer of the evaluation routine.
+.El
+.El
+.Sh RETURN VALUES
+If successful, functions return 0.
+Otherwise, the following error values are returned:
+.Bl -tag -width [EINVAL]
+.It Bq Er EEXIST
+The
+.Nm
+is already registered.
+.It Bq Er EFAULT
+An invalid address or reference was passed as parameter.
+.It Bq Er EINVAL
+An invalid value was passed as parameter.
+.It Bq Er ENOENT
+The targetted
+.Nm
+does not exist, or it does not implement an evaluation callback.
+.El
+.Sh WRITING A SECURITY MODEL
+Before writing a 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
+See
.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:
+for details.
+.Pp
+A security model is based on the kernel
+.Xr module 9
+framework, and can be built-in statically inside kernel or
+loaded dynamically at run-time.
+It is composed of (code-wise) the following components:
.Bl -enum -offset indent
.It
+.Xr module 9
+routines, especially a
+.Fn MODULE
+declaration and a
+.Fn secmodel_\*[Lt]model\*[Gt]_modcmd
+function used to start
+.Po through Dv MODULE_CMD_INIT Pc
+and stop
+.Po through Dv MODULE_CMD_FINI Pc
+the
+.Nm .
+.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
+used to initialize and start the security model, and 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
+A
.Xr sysctl 9
+setup routine for the model.
+This should create an entry for the model in the
+.Xr sysctl 7
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
+as a mandatory
+.Fa 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
+.It
+A
.Xr sysctl 9
-tree.
+teardown routine used to destroy the
+.Xr sysctl 7
+tree associated with the model.
.It
If the model uses any private data inside credentials, listening on
the credentials scope,
@@ -180,20 +240,21 @@ These must all be prefixed with "secmode
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
+Finally, a security model should register itself after being
+initialized using
+.Fn secmodel_register ,
+and deregister itself before being stopped using
.Fn secmodel_deregister .
.El
-.Pp
+.Sh EXAMPLES
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
+It is used to allow users with a user-id below 1000 to bind to reserved ports
(for example, 22/TCP):
-.Bd -literal -offset indent
+.Bd -literal
int
secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action,
void *cookie, void *arg0, void *arg1, void *arg2, void *arg3)
@@ -229,10 +290,9 @@ There are two main issues, however, with
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.
+security model, even if it would allow the request, it could still be denied.
.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,
@@ -242,7 +302,34 @@ denied -- which may not be desired.
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
+.Sh PROGRAMMING CONSIDERATIONS
+There are several things you should remember when writing a security model:
+.Bl -dash -offset indent
+.It
+Pay attention to the correctness of your
+.Nm
+implementation of the desired policy.
+Certain rights can grant more privileges on the system than others,
+like allowing calls to
+.Xr chroot 2
+or mounting a file-system.
+.It
+All unhandled requests are denied by default.
+.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 STACKING ON 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
@@ -252,20 +339,20 @@ code.
.Pp
To properly "stack" minor adjustments on-top of an existing security model,
one could use one of two approaches:
-.Bl -dash
+.Bl -enum
.It
-Registering an internal scope for the security model to be used as a
+Register 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
+every scope the model partly covers, and register 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
+Here is example code that implements the above:
+.Bd -literal
#include \*[Lt]secmodel/bsd44/bsd44.h\*[Gt]
/*
@@ -332,7 +419,7 @@ secmodel_jenna_network_cb(kauth_cred_t c
.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
+.Bd -literal
int
secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action,
void *cookie, void *arg0, void *arg1, void *arg2, void *arg3)
@@ -367,37 +454,85 @@ secmodel_jenna_network_cb(kauth_cred_t c
}
.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
+.Sh 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
+.Bl -tag -width xxxxxxxx
+.It Xr secmodel_suser 9
+Implements the
+.Em super-user
+(root) security policy.
+.It Xr secmodel_securelevel 9
+Implements the
+.Em securelevel
+security model.
+.It Xr secmodel_extensions 9
+Implements extensions to the traditional
+.Bx 4.4
+security model, like usermounts.
+.It Xr secmodel_bsd44 9
Traditional
.Nx
security model, derived from
.Bx 4.4 .
-.It secmodel_overlay
+.It Xr secmodel_overlay 9
Sample overlay security model, sitting on-top of
.Xr secmodel_bsd44 9 .
.El
-.Sh FILES
-.Pa /usr/share/examples/secmodel
+.Sh CODE REFERENCES
+The core of the
+.Nm
+implementation is in
+.Pa sys/secmodel/secmodel.c .
+.Pp
+The header file
+.In secmodel/secmodel.h
+describes the public interface.
+.Pp
+To make it easier on developers to write new security models from scratch,
+.Nx
+maintains an example
+.Nm
+under
+.Pa share/examples/secmodel/ .
.Sh SEE ALSO
.Xr kauth 9 ,
+.Xr module 9 ,
.Xr secmodel_bsd44 9 ,
-.Xr secmodel_overlay 9
+.Xr secmodel_extensions 9 ,
+.Xr secmodel_overlay 9 ,
+.Xr secmodel_securelevel 9 ,
+.Xr secmodel_suser 9
+.Sh HISTORY
+Kernel Authorization was introduced in
+.Nx 4.0
+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 super-user 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
+allows separating them, dispatching requests with highly detailed
+context using a consistent and clear KPI.
+.Pp
+The
+.Nm
+framework was extended in
+.Nx 6.0
+to implement
+.Nm
+registration and evaluation procedure calls.
.Sh AUTHORS
.An Elad Efrat Aq e...@netbsd.org
Index: src/share/man/man9/secmodel_bsd44.9
diff -u src/share/man/man9/secmodel_bsd44.9:1.13 src/share/man/man9/secmodel_bsd44.9:1.14
--- src/share/man/man9/secmodel_bsd44.9:1.13 Fri Oct 2 19:50:37 2009
+++ src/share/man/man9/secmodel_bsd44.9 Sun Dec 4 21:08:45 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: secmodel_bsd44.9,v 1.13 2009/10/02 19:50:37 elad Exp $
+.\" $NetBSD: secmodel_bsd44.9,v 1.14 2011/12/04 21:08:45 jym Exp $
.\"
.\" Copyright (c) 2006 Elad Efrat <e...@netbsd.org>
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\" (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 October 2, 2009
+.Dd December 4, 2011
.Dt SECMODEL_BSD44 9
.Os
.Sh NAME
@@ -40,13 +40,15 @@ is the default security model in
.Nx .
It is the traditional security model based on
.Bx 4.4
-and is composed of two separate security models,
-.Xr secmodel_suser 9
+and is composed of three separate security models:
+.Xr secmodel_extensions 9 ,
+.Xr secmodel_securelevel 9
and
-.Xr secmodel_securelevel 9 .
+.Xr secmodel_suser 9 .
.Sh SEE ALSO
.Xr kauth 9 ,
.Xr secmodel 9 ,
+.Xr secmodel_extensions 9 ,
.Xr secmodel_securelevel 9 ,
.Xr secmodel_suser 9
.Sh AUTHORS
Index: src/share/man/man9/secmodel_securelevel.9
diff -u src/share/man/man9/secmodel_securelevel.9:1.10 src/share/man/man9/secmodel_securelevel.9:1.11
--- src/share/man/man9/secmodel_securelevel.9:1.10 Wed Dec 22 09:08:09 2010
+++ src/share/man/man9/secmodel_securelevel.9 Sun Dec 4 21:08:45 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: secmodel_securelevel.9,v 1.10 2010/12/22 09:08:09 wiz Exp $
+.\" $NetBSD: secmodel_securelevel.9,v 1.11 2011/12/04 21:08:45 jym Exp $
.\"
.\" Copyright (c) 2006 Elad Efrat <e...@netbsd.org>
.\" Copyright (c) 2000 Hugh Graham
@@ -26,7 +26,7 @@
.\" (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 December 21, 2010
+.Dd December 4, 2011
.Dt SECMODEL_SECURELEVEL 9
.Os
.Sh NAME
@@ -35,11 +35,17 @@
.Sh DESCRIPTION
The securelevel mechanism is intended to allow protecting the persistence
of code and data on the system, or a subset thereof, from modification, even
-by the super-user, by providing convenient means of
+by the
+.Em super-user
+by providing convenient means of
.Dq locking down
a system to a degree suited to its environment.
.Pp
-The super-user can raise the securelevel using
+The
+.Em super-user
+can raise the
+.Em securelevel
+using
.Xr sysctl 8 ,
but only
.Xr init 8
@@ -50,7 +56,9 @@ Four security levels are provided.
.It \&-1 Em Permanently insecure mode
.Bl -bullet
.It
-Don't raise the securelevel on boot
+Do not raise the
+.Em securelevel
+on boot
.El
.It \ 0 Em Insecure mode
.Bl -bullet
@@ -76,7 +84,9 @@ kernel modules can be loaded and unloade
.It \ 1 Em Secure mode
.Bl -bullet
.It
-All effects of securelevel 0.
+All effects of
+.Em securelevel
+0.
.It
The
.Xr kmem 4
@@ -123,12 +133,16 @@ calls are denied.
.It
Access to unmanaged memory is denied.
.It
-Only GPIO pins that have been set at securelevel 0 can be accessed.
+Only GPIO pins that have been set at
+.Em securelevel
+0 can be accessed.
.El
.It \ 2 Em Highly secure mode
.Bl -bullet
.It
-All effects of securelevel 1.
+All effects of
+.Em securelevel
+1.
.It
Raw disk devices are always read-only whether mounted or not.
.It
@@ -144,7 +158,9 @@ Packet filtering and NAT rules may not b
.El
.Pp
Highly secure mode may seem Draconian, but is intended as a last line of
-defence should the superuser account be compromised.
+defence should the
+.Em super-user
+account be compromised.
Its effects preclude
circumvention of file flags by direct modification of a raw disk device,
or erasure of a file system by means of
@@ -158,11 +174,16 @@ and helps ensure the integrity of logs.
Precision timekeeping is not
affected because the clock may still be slowed.
.Pp
-Normally, the system runs in securelevel 0 while single-user and in
-securelevel 1 while multi-user.
-If a higher securelevel is desired while running multi-user,
-it can be set using the
+Normally, the system runs in
.Em securelevel
+0 while single-user and in
+.Em securelevel
+1 while multi-user.
+If a higher
+.Em securelevel
+is desired while running multi-user,
+it can be set using the
+.Sy securelevel
keyword in the startup script
.Pa /etc/rc.conf ,
see
@@ -170,7 +191,9 @@ see
for details.
Lower securelevels require the kernel to be compiled with
.Sy options INSECURE ,
-causing it to always default to securelevel \-1.
+causing it to always default to
+.Em securelevel
+\-1.
.Pp
In order for this protection to be effective, the administrator
must ensure that no program that is run while the security level
@@ -203,10 +226,54 @@ The system security level.
This level may be raised by processes with appropriate privilege.
It may only be lowered by process 1 (init).
.El
+.Sh FUNCTIONS
+.Nm
+exposes a
+.Xr secmodel_eval 9
+evaluation routine
+to test whether the current
+.Em securelevel
+is above a certain threshold level or not.
+.Pp
+The parameters to
+.Xr secmodel_eval 9
+are:
+.Bl -tag -compact -width xxxxx
+.It id
+the unique identifier of
+.Nm :
+.Qo Dv org.netbsd.secmodel.securelevel Qc .
+.It what
+a string,
+.Qo Dv is-securelevel-above Qc
+.It arg
+a reference to an
+.Dv int
+representing the threshold level.
+.It ret
+a boolean, set by
+.Nm
+to
+.Dv true
+when the
+.Em securelevel
+is strictly above
+the threshold level,
+.Dv false
+otherwise.
+.El
+.Sh RETURN TYPES
+If successful, the evaluation returns 0 with the
+.Fa ret
+argument being either
+.Dv true
+or
+.Dv false .
.Sh SEE ALSO
.Xr kauth 9 ,
.Xr secmodel 9 ,
-.Xr secmodel_bsd44 9
+.Xr secmodel_bsd44 9 ,
+.Xr secmodel_eval 9
.Sh AUTHORS
.An Elad Efrat Aq e...@netbsd.org
.Sh BUGS
Index: src/share/man/man9/secmodel_suser.9
diff -u src/share/man/man9/secmodel_suser.9:1.4 src/share/man/man9/secmodel_suser.9:1.5
--- src/share/man/man9/secmodel_suser.9:1.4 Sat Oct 3 07:37:01 2009
+++ src/share/man/man9/secmodel_suser.9 Sun Dec 4 21:08:45 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: secmodel_suser.9,v 1.4 2009/10/03 07:37:01 wiz Exp $
+.\" $NetBSD: secmodel_suser.9,v 1.5 2011/12/04 21:08:45 jym Exp $
.\"
.\" Copyright (c) 2009 Elad Efrat <e...@netbsd.org>
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\" (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 October 2, 2009
+.Dd December 4, 2011
.Dt SECMODEL_SUSER 9
.Os
.Sh NAME
@@ -40,46 +40,53 @@ The
.Em super-user
is the host administrator, considered to have higher privileges than other
users.
+.Sh FUNCTIONS
+.Nm
+exposes a
+.Xr secmodel_eval 9
+evaluation routine
+to test whether a set of credentials can be assimilated to
+.Em super-user
+credentials or not.
.Pp
-The following
-.Xr sysctl 3
-variables are exported:
-.Bl -tag -width compact
-.It security.models.suser.curtain
-If non-zero, will filter returned objects according to the user-id
-requesting information about them, preventing from users any access to
-objects they don't own.
-.Pp
-At the moment, it affects
-.Xr ps 1 ,
-.Xr netstat 1
-(for
-.Dv PF_INET ,
-.Dv PF_INET6 ,
-and
-.Dv PF_UNIX
-PCBs), and
-.Xr w 1 .
-.It security.models.suser.usermount
-Allow non-superuser mounts.
-.Pp
-If non-zero, file-systems are allowed to be mounted by an ordinary user who
-owns the point
-.Ar node
-and has at least read access to the
-.Ar special
-device
-.Xr mount 8
-arguments.
-Finally, the flags
-.Cm nosuid
-and
-.Cm nodev
-must be given for non-superuser mounts.
+The parameters to
+.Xr secmodel_eval 9
+are:
+.Bl -tag -compact -width xxxxx
+.It id
+the unique identifier of
+.Nm :
+.Qo Dv org.netbsd.secmodel.suser Qc
+.It what
+a string,
+.Qo Dv is-root Qc .
+.It arg
+the
+.Xr kauth 9
+credentials
+.Po Fa kauth_cred_t Pc
+of the caller.
+.It ret
+a boolean, set by
+.Nm
+to
+.Dv true
+when the credentials are equivalent to
+.Em super-user ,
+.Dv false
+otherwise.
.El
+.Sh RETURN TYPES
+If successful, the evaluation returns 0 with the
+.Fa ret
+argument being either
+.Dv true
+or
+.Dv false .
.Sh SEE ALSO
.Xr kauth 9 ,
.Xr secmodel 9 ,
-.Xr secmodel_bsd44 9
+.Xr secmodel_bsd44 9 ,
+.Xr secmodel_eval 9
.Sh AUTHORS
.An Elad Efrat Aq e...@netbsd.org
Added files:
Index: src/share/man/man9/secmodel_extensions.9
diff -u /dev/null src/share/man/man9/secmodel_extensions.9:1.1
--- /dev/null Sun Dec 4 21:08:46 2011
+++ src/share/man/man9/secmodel_extensions.9 Sun Dec 4 21:08:45 2011
@@ -0,0 +1,120 @@
+.\" $NetBSD: secmodel_extensions.9,v 1.1 2011/12/04 21:08:45 jym Exp $
+.\"
+.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jean-Yves Migeon <j...@netbsd.org>
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 December 3, 2011
+.Dt SECMODEL_EXTENSIONS 9
+.Os
+.Sh NAME
+.Nm secmodel_extensions
+.Nd Extensions security model
+.Sh DESCRIPTION
+.Nm
+implements extensions to the traditional security model based on
+the original
+.Bx 4.4 .
+They can be used to grant additional privileges to ordinary users, or
+enable specific security measures like curtain mode.
+.Pp
+The extensions are described below.
+.Sh Curtain mode
+When enabled, all returned objects will be filtered according to
+the user-id requesting information about them, preventing users from
+accessing objects they do not own.
+.Pp
+It affects the output of many commands, including
+.Xr fstat 1 ,
+.Xr netstat 1 ,
+.Xr ps 1 ,
+.Xr sockstat 1 ,
+and
+.Xr w 1 .
+.Pp
+This extension is enabled by setting
+.Pa security.models.extensions.curtain
+or
+.Pa security.curtain
+.Xr sysctl 7
+to a non-zero value.
+.Pp
+It can be enabled at any time, but cannot be disabled
+anymore when the
+.Em securelevel
+of the system is above 0.
+.Sh Non-superuser mounts
+When enabled, it allows file-systems to be mounted by an ordinary user
+who owns the point
+.Ar node
+and has at least read access to the
+.Ar special
+device
+.Xr mount 8
+arguments.
+Note that the
+.Cm nosuid
+and
+.Cm nodev
+flags must be given for non-superuser mounts.
+.Pp
+This extension is enabled by setting
+.Pa security.models.extensions.usermount
+or
+.Pa vfs.generic.usermount
+.Xr sysctl 7
+to a non-zero value.
+.Pp
+It can be disabled at any time, but cannot be enabled
+anymore when the
+.Em securelevel
+of the system is above 0.
+.Sh Non-superuser control of CPU sets
+When enabled, an ordinary user is allowed to control the CPU
+.Xr affinity 3
+of the processes and threads he owns.
+.Pp
+This extension is enabled by setting
+.Pa security.models.extensions.user_set_cpu_affinity
+.Xr sysctl 7
+to a non-zero value.
+.Pp
+It can be disabled at any time, but cannot be enabled
+anymore when the
+.Em securelevel
+of the system is above 0.
+.El
+.Sh SEE ALSO
+.Xr affinity 3 ,
+.Xr sched 3 ,
+.Xr sysctl 7 ,
+.Xr kauth 9 ,
+.Xr secmodel 9 ,
+.Xr secmodel_bsd44 9 ,
+.Xr secmodel_securelevel 9 ,
+.Xr secmodel_suser 9
+.Sh AUTHORS
+.An Elad Efrat Aq e...@netbsd.org
