jimzah/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src.git synced 2024-11-26 20:12:44 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Add examples to veriexec(8)

Browse Source 
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 2024-08-01 14:59:52 -07:00
parent 46ea2ffc3f
commit b77f618568
3 changed files with 172 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
sbin/veriexec/veriexec.8
View File

@ -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.

1
share/man/man4/Makefile
View File

@ -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
View 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 .