.\" $NetBSD: secmodel_securelevel.9,v 1.19 2019/05/18 10:21:03 alnsn Exp $
.\"
.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
.\" Copyright (c) 2000 Hugh Graham
.\" 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 18, 2019
.Dt SECMODEL_SECURELEVEL 9
.Os
.Sh NAME
.Nm secmodel_securelevel
.Nd securelevel security model
.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
.Em super-user ,
by providing convenient means of
.Dq locking down
a system to a degree suited to its environment.
.Pp
The
.Em super-user
can raise the
.Em securelevel
using
.Xr sysctl 8 ,
but only
.Xr init 8
can lower it.
.Pp
Four security levels are provided:
.Bl -tag -width flag
.It \&-1 Em Permanently insecure mode
.Bl -bullet
.It
Do not raise the
.Em securelevel
on boot.
.El
.It \ 0 Em Insecure mode
.Bl -bullet
.It
The init process (PID 1) may not be traced or accessed by
.Xr ptrace 2
or procfs.
.It
Immutable and append-only file flags may be changed by
.Xr chflags 1
or by other means.
.It
All devices may be read or written subject to their permissions.
.It
All
.Xr gpio 4
pins can be set and device drivers can be attached to them.
.It
On architectures that support
.Xr module 7 ,
kernel modules can be loaded and unloaded.
.El
.It \ 1 Em Secure mode
.Bl -bullet
.It
All effects of
.Em securelevel
0.
.It
The
.Xr x86/kmem 4
memory files
.Pa /dev/mem
and
.Pa /dev/kmem
may not be written to.
.It
Raw disk devices of mounted file systems are read-only.
.It
Immutable and append-only file flags may not be removed.
.It
Kernel modules may not be loaded or unloaded.
.It
Neither the
.Va net.inet.ip.sourceroute
nor the
.Va vm.user_va0_disable
.Xr sysctl 8
variables may be changed.
.It
Adding or removing
.Xr sysctl 9
nodes is denied.
.It
The RTC offset may not be changed.
.It
Set-id coredump settings may not be altered.
.It
Device
.Dq pass-thru
requests that may be used to perform raw disk and/or memory access are denied.
.It
The
.Em iopl
and
.Em ioperm
calls are denied.
.It
Access to unmanaged memory is denied.
.It
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
.Em securelevel
1.
.It
Raw disk devices are always read-only whether mounted or not.
.It
New disks may not be mounted, and existing mounts may only be downgraded
from read-write to read-only.
.It
The system clock may not be set backwards or close to overflow.
.It
Per-process coredump name may not be changed.
.It
Packet filtering and NAT rules may not be altered.
.It
CPU ucode loading is denied on platforms that support it.
.El
.El
.Pp
Highly secure mode may seem Draconian, but is intended as a last line of
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
.Xr newfs 8 .
Further, it can limit the potential damage of a compromised
.Dq firewall
by prohibiting the modification of packet filter rules.
Preventing
the system clock from being set backwards aids in post-mortem analysis
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
.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
.Xr rc.conf 5
for details.
Lower securelevels require the kernel to be compiled with
.Sy options INSECURE ,
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
is 0 or lower, nor any data or configuration file used by any such
program, can be modified while the security level is greater than
0.
This may be achieved through the careful use of the
.Dq immutable
file flag to define and protect a Trusted Computing Base (TCB)
consisting of all such programs and data, or by ensuring that all
such programs and data are on filesystems that are mounted read-only
and running at security level 2 or higher.
.Em Particular care must be taken to ensure, if relying upon
.Em security level 1 and the use of file flags, that the integrity of the
.Em TCB cannot be compromised through the use of modifications to the
.Em disklabel or access to overlapping disk partitions, including the
.Em raw partition .
.Pp
Do not overlook the fact that shell scripts (or anything else fed to an
interpreter, through any mechanism) and the kernel itself are "programs
that run while the security level is 0" and must be considered part of
the TCB.
.Pp
The following
.Xr sysctl 3
variables are exported:
.Bl -tag -width compact
.It security.models.securelevel.securelevel
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_eval 9
.Sh AUTHORS
.An Elad Efrat Aq Mt elad@NetBSD.org
.Sh BUGS
Systems without
.Xr sysctl 8
behave as though they have security level \-1.
.Pp
The security level 2 restrictions relating to TCB integrity protection
should be enforced at security level 1.
Restrictions dependent upon security level but not relating to TCB
integrity protection should be selected by
.Xr sysctl 8
settings available only at security level 0 or lower.