feat: Added NetBSD man pages

1 files changed, 538 insertions, 0 deletions

diff --git a/static/netbsd/man9/secmodel.9 b/static/netbsd/man9/secmodel.9
new file mode 100644
index 00000000..3dcb1cc6
--- /dev/null
+++ b/static/netbsd/man9/secmodel.9
@@ -0,0 +1,538 @@
+.\" $NetBSD: secmodel.9,v 1.23 2022/01/26 11:48:53 andvar 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 December 4, 2011
+.Dt SECMODEL 9
+.Os
+.Sh NAME
+.Nm secmodel
+.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_<model>_eval "const char *what" "void *arg" \
+    "void *ret"
+.Sh DESCRIPTION
+.Nx
+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 \(em either slightly or
+using an entirely different model \(em by attaching/detaching
+.Xr kauth 9
+listeners.
+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_<model>_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_<model>_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 targeted security model.
+The value is then implementation-defined.
+.El
+.Pp
+.Bl -tag -width what
+.It Fa id
+The unique identifier of the targeted
+.Nm .
+.It Fa what
+The query that will be passed down to the targeted
+.Nm .
+.It Fa arg
+The arguments passed to the evaluation routine of the targeted
+.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 targeted
+.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.
+See
+.Xr kauth 9
+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_<model>_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_<model>_init
+and
+.Fn secmodel_<model>_start ,
+used to initialize and start the security model, and another
+function called
+.Fn secmodel_<model>_stop ,
+to stop the security model in case the module is to be unloaded.
+.It
+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.<model>" hierarchy.
+.Pp
+All "knobs" for the model should be located under the new node, as well
+as a mandatory
+.Fa name
+variable, indicating a descriptive human-readable
+name for the model.
+.It
+A
+.Xr sysctl 9
+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,
+.Dv KAUTH_SCOPE_CRED ,
+is required.
+.It
+Optionally, internal data-structures used by the model.
+These must all be prefixed with "secmodel_<model>_".
+.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 after being
+initialized using
+.Fn secmodel_register ,
+and deregister itself before being stopped using
+.Fn secmodel_deregister .
+.El
+.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 to bind to reserved ports
+(for example, 22/TCP):
+.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)
+{
+	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) < 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
+.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 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,
+denied \(em 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.
+.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 \(em such as internal data structures \(em 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
+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 -enum
+.It
+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 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 is example code that implements the above:
+.Bd -literal
+#include <secmodel/bsd44/bsd44.h>
+
+/*
+ * 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) < 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
+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) < 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
+.Sh AVAILABLE SECURITY MODELS
+The following is a list of security models available in the default
+.Nx
+distribution.
+.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 Xr secmodel_overlay 9
+Sample overlay security model, sitting on-top of
+.Xr secmodel_bsd44 9 .
+.El
+.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_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 Mt elad@NetBSD.org