From b77f618568f252da3a6c69e8aff25f6b1bada1fd Mon Sep 17 00:00:00 2001 From: "Simon J. Gerraty" Date: Thu, 1 Aug 2024 14:59:52 -0700 Subject: [PATCH] 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 --- sbin/veriexec/veriexec.8 | 84 ++++++++++++++++++++++++++++++---- share/man/man4/Makefile | 1 + share/man/man4/veriexec.4 | 96 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 9 deletions(-) create mode 100644 share/man/man4/veriexec.4 diff --git a/sbin/veriexec/veriexec.8 b/sbin/veriexec/veriexec.8 index 2e476f327b14..3c85957357f5 100644 --- a/sbin/veriexec/veriexec.8 +++ b/sbin/veriexec/veriexec.8 @@ -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. diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index b4a8e484b137..4e685cac3ecf 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1054,6 +1054,7 @@ MAN+= \ uslcom.4 \ uvisor.4 \ uvscom.4 \ + veriexec.4 \ zyd.4 MLINKS+=otus.4 if_otus.4 diff --git a/share/man/man4/veriexec.4 b/share/man/man4/veriexec.4 new file mode 100644 index 000000000000..14e4aeae0d10 --- /dev/null +++ b/share/man/man4/veriexec.4 @@ -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 .