mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-21 18:50:50 +01:00
Add examples to veriexec(8)
Add missing flags to veriexec(8) as well as some examples to help explain usage. Also add veriexec.4 Sponsored by: Juniper Networks, Inc. Reviewed by: imp Differential Revision: https://reviews.freebsd.org/D46207
This commit is contained in:
Simon J. Gerraty
parent
46ea2ffc3f
commit
b77f618568
@ -1,7 +1,7 @@
|
||||
.\"-
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2018-2023, Juniper Networks, Inc.
|
||||
.\" Copyright (c) 2018-2024, Juniper Networks, Inc.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
@ -24,7 +24,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 August 8, 2023
|
||||
.Dd August 1, 2024
|
||||
.Dt VERIEXEC 8
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -97,7 +97,7 @@ The possible states
|
||||
are:
|
||||
.Bl -tag -width enforce
|
||||
.It Ar loaded
|
||||
set automatically when first
|
||||
set automatically when the first
|
||||
.Pa manifest
|
||||
has been loaded.
|
||||
.It Ar active
|
||||
@ -137,10 +137,11 @@ The manifest contains a mapping of relative pathnames to fingerprints
|
||||
with optional flags.
|
||||
For example:
|
||||
.Bd -literal -offset indent
|
||||
sbin/veriexec sha256=f22136...c0ff71 no_ptrace
|
||||
sbin/veriexec sha256=f22136...c0ff71 no_ptrace trusted
|
||||
usr/bin/python sha256=5944d9...876525 indirect
|
||||
sbin/somedaemon sha256=77fc2f...63f5687 label=mod1/val1,mod2/val2
|
||||
.Ed
|
||||
.Pp
|
||||
The supported flags are:
|
||||
.Bl -tag -width indirect
|
||||
.It Ql indirect
|
||||
@ -149,16 +150,31 @@ but can be used as an interpreter for example via:
|
||||
.Bd -literal -offset indent
|
||||
#!/usr/bin/python
|
||||
.Ed
|
||||
.It Ql no_fips
|
||||
If the system has a notion of running in FIPS mode,
|
||||
a file marked with this flag will not be allowed to
|
||||
exec.
|
||||
.It Ql no_ptrace
|
||||
do not allow running executable under a debugger.
|
||||
Useful for any application critical to the security state of system.
|
||||
.It Ql trusted
|
||||
this flag is required for a process to use
|
||||
.Xr veriexec 4
|
||||
to interact with
|
||||
.Xr mac_veriexec 4 .
|
||||
Generally only
|
||||
.Nm
|
||||
should need this flag.
|
||||
Implies
|
||||
.Ql no_ptrace .
|
||||
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Ql label
|
||||
argument allows associating a
|
||||
.Xr maclabel 7
|
||||
with the executable.
|
||||
with a file.
|
||||
Neither
|
||||
.Nm
|
||||
nor
|
||||
@ -167,10 +183,60 @@ nor
|
||||
pay any attention to the content of the label
|
||||
they are provided for the use of other
|
||||
.Xr mac 4
|
||||
modules.
|
||||
modules or indeed other applications.
|
||||
.Sh EXAMPLES
|
||||
Load the manifest for a
|
||||
.Xr tarfs 5
|
||||
package mounted on
|
||||
.Pa /mnt
|
||||
and be strict about enforcing certificate validity:
|
||||
.Bd -literal -offset indent
|
||||
# veriexec -S -C /mnt /mnt/manifest
|
||||
|
||||
.Ed
|
||||
.Nm
|
||||
will look for a detatched signature that it recognizes, such as
|
||||
.Pa manifest.asc
|
||||
(OpenPGP) or
|
||||
.Pa manifest.*sig
|
||||
(X.509).
|
||||
In the case of an X.509 signature we also need a matching certificate chain
|
||||
.Pa manifest.*certs .
|
||||
In either case there needs to be a suitable trust anchor in the trust store.
|
||||
.Pp
|
||||
We can now activate:
|
||||
.Bd -literal -offset indent
|
||||
# veriexec -z active
|
||||
|
||||
.Ed
|
||||
Any user can check if
|
||||
.Xr mac_veriexec 4
|
||||
is
|
||||
.Ql active :
|
||||
.Bd -literal -offset indent
|
||||
$ veriexec -i active
|
||||
|
||||
.Ed
|
||||
Any user can check that
|
||||
.Pa /mnt/bin/app
|
||||
is verified:
|
||||
.Bd -literal -offset indent
|
||||
$ veriexec -x /mnt/bin/app
|
||||
|
||||
.Ed
|
||||
If it is not, we will get an Authentiaction error,
|
||||
but unless
|
||||
.Xr mac_veriexec 4
|
||||
is enforcing we would still be able to run it.
|
||||
.Sh NOTES
|
||||
It is only safe to set
|
||||
.Xr mac_veriexec 4
|
||||
to
|
||||
.Ql enforce
|
||||
state, if sufficient manifests have been loaded
|
||||
to cover all the applications that might need to be run.
|
||||
.Sh HISTORY
|
||||
The Verified Exec system first appeared in
|
||||
.Nx .
|
||||
This utility derives from the one found in Junos.
|
||||
The key difference is the requirement that manifest files
|
||||
be digitally signed.
|
||||
This utility derives from the one found in Junos,
|
||||
which requires that manifest files be digitally signed.
|
||||
|
||||
@ -1054,6 +1054,7 @@ MAN+= \
|
||||
uslcom.4 \
|
||||
uvisor.4 \
|
||||
uvscom.4 \
|
||||
veriexec.4 \
|
||||
zyd.4
|
||||
|
||||
MLINKS+=otus.4 if_otus.4
|
||||
|
||||
96
share/man/man4/veriexec.4
Normal file
96
share/man/man4/veriexec.4
Normal file
@ -0,0 +1,96 @@
|
||||
.\"-
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2024, Juniper Networks, Inc.
|
||||
.\"
|
||||
.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT
|
||||
.\" OWNER 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 August 1, 2024
|
||||
.Dt VERIEXEC 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm veriexec
|
||||
.Nd the veriexec device
|
||||
.Sh SYNOPSIS
|
||||
.In dev/veriexec/veriexec_ioctl.h
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
device is used by
|
||||
.Xr veriexec 8
|
||||
to query and modify the state of
|
||||
.Xr mac_veriexec 4 .
|
||||
.Pp
|
||||
Once
|
||||
.Xr mac_veriexec 4
|
||||
is active, only a process which is marked as
|
||||
.Ql trusted
|
||||
(normally only
|
||||
.Xr veriexec 8 )
|
||||
is able to more than the
|
||||
.Dv VERIEXEC_GETSTATE
|
||||
ioctl.
|
||||
.Sh IOCTLS
|
||||
The supported ioctls are described below.
|
||||
.Bl -tag
|
||||
.It Dv VERIEXEC_SIGNED_LOAD Vt struct verified_exec_params
|
||||
Pass file information to
|
||||
.Xr mac_veriexec 4 .
|
||||
.Bd -literal
|
||||
struct verified_exec_params {
|
||||
unsigned char flags;
|
||||
char fp_type[VERIEXEC_FPTYPELEN]; /* type of fingerprint */
|
||||
char file[MAXPATHLEN];
|
||||
unsigned char fingerprint[MAXFINGERPRINTLEN];
|
||||
};
|
||||
.Ed
|
||||
.It Dv VERIEXEC_LABEL_LOAD Vt struct verified_exec_label_params
|
||||
Pass file information and a label to
|
||||
.Xr mac_veriexec 4 .
|
||||
.Bd -literal
|
||||
struct verified_exec_label_params {
|
||||
struct verified_exec_params params;
|
||||
char label[MAXLABELLEN];
|
||||
};
|
||||
.Ed
|
||||
.It Dv VERIEXEC_ACTIVE
|
||||
.It Dv VERIEXEC_DEBUG_OFF
|
||||
.It Dv VERIEXEC_DEBUG_ON Vt int level
|
||||
.It Dv VERIEXEC_ENFORCE
|
||||
.It Dv VERIEXEC_GETSTATE
|
||||
.It Dv VERIEXEC_GETVERSION
|
||||
.It Dv VERIEXEC_LOCK
|
||||
.It Dv VERIEXEC_VERIFIED_FILE Vt int fd
|
||||
Rarely needed.
|
||||
Tells
|
||||
.Xr mac_veriexec 4
|
||||
that the file associated with
|
||||
.Va fd
|
||||
is verified.
|
||||
.El
|
||||
.Sh HISTORY
|
||||
A
|
||||
.Nm
|
||||
device first appeared in
|
||||
.Nx .
|
||||
It was added to
|
||||
.Fx 13.1 .
|
||||
Loading…
Reference in New Issue
Block a user