1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2018-2024, Juniper Networks, Inc. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 18.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 19.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 21.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 25.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd August 1, 2024 28.Dt VERIEXEC 8 29.Os 30.Sh NAME 31.Nm veriexec 32.Nd manipulate state of mac_veriexec 33.Sh SYNOPSIS 34.Nm 35.Op Fl v 36.Op Fl C Ar directory 37.Op Fl S 38.Pa manifest 39.Nm 40.Fl z Ar state 41.Nm 42.Fl i Ar state 43.Nm 44.Fl l 45.Ar file ... 46.Nm 47.Fl x 48.Ar file ... 49.Sh DESCRIPTION 50.Nm 51is a utility to query or manipulate the state of 52.Xr mac_veriexec 4 . 53.Pp 54The first form is for loading a 55.Pa manifest . 56.Nm 57first verifies a digital signature of the 58.Ar manifest 59and if successful, parses it and feeds its content to kernel. 60The 61.Fl S 62flag indicates that certificate validity should be checked. 63Without this, a valid signature with an expired certificate 64will still be accepted. 65.Pp 66The second form with 67.Fl z 68is used to modify the 69.Ar state , 70and with 71.Fl i 72to query the current 73.Ar state . 74.Pp 75With 76.Fl l 77.Nm 78will report any labels associated with the remaining arguments 79assumed to be files. 80If only a single file argument is given, the bare label (if any) 81will be reported, otherwise the pathname followed by label. 82.Pp 83The final form with 84.Fl x 85is used to test whether 86.Ar file 87is verified or not. 88This requires 89.Xr mac_veriexec 4 90to be in the 91.Ql active 92or 93.Ql enforce 94state. 95.Pp 96The possible states 97are: 98.Bl -tag -width enforce 99.It Ar loaded 100set automatically when the first 101.Pa manifest 102has been loaded. 103.It Ar active 104.Xr mac_veriexec 4 105will begin checking files. 106This state can only be entered from the 107.Ar loaded 108state. 109.It Ar enforce 110.Xr mac_veriexec 4 111will fail attempts to 112.Xr exec 2 113or 114.Xr open 2 115files with 116.Dv O_VERIFY 117unless verified. 118.It Ar locked 119prevent loading of any more manifests. 120.El 121.Pp 122When setting or querying the state, it is sufficient to provide 123a unique prefix of the desired state. 124So 125.Fl i 126.Ar a 127or 128.Fl z 129.Ar e 130are sufficient, but 131.Fl i 132.Ar loc 133is the minimum required to avoid confusion with 134.Ar loaded . 135.Sh MANIFESTS 136The manifest contains a mapping of relative pathnames to fingerprints 137with optional flags. 138For example: 139.Bd -literal -offset indent 140sbin/veriexec sha256=f22136...c0ff71 no_ptrace trusted 141usr/bin/python sha256=5944d9...876525 indirect 142sbin/somedaemon sha256=77fc2f...63f5687 label=mod1/val1,mod2/val2 143.Ed 144.Pp 145The supported flags are: 146.Bl -tag -width indirect 147.It Ql indirect 148the executable cannot be run directly, 149but can be used as an interpreter for example via: 150.Bd -literal -offset indent 151#!/usr/bin/python 152.Ed 153.It Ql no_fips 154If the system has a notion of running in FIPS mode, 155a file marked with this flag will not be allowed to 156exec. 157.It Ql no_ptrace 158do not allow running executable under a debugger. 159Useful for any application critical to the security state of system. 160.It Ql trusted 161this flag is required for a process to use 162.Xr veriexec 4 163to interact with 164.Xr mac_veriexec 4 . 165Generally only 166.Nm 167should need this flag. 168Implies 169.Ql no_ptrace . 170 171.El 172.Pp 173The 174.Ql label 175argument allows associating a 176.Xr maclabel 7 177with a file. 178Neither 179.Nm 180nor 181.Xr mac_veriexec 4 182(if it supports labels) 183pay any attention to the content of the label 184they are provided for the use of other 185.Xr mac 4 186modules or indeed other applications. 187.Sh EXAMPLES 188Load the manifest for a 189.Xr tarfs 5 190package mounted on 191.Pa /mnt 192and be strict about enforcing certificate validity: 193.Bd -literal -offset indent 194# veriexec -S -C /mnt /mnt/manifest 195 196.Ed 197.Nm 198will look for a detatched signature that it recognizes, such as 199.Pa manifest.asc 200(OpenPGP) or 201.Pa manifest.*sig 202(X.509). 203In the case of an X.509 signature we also need a matching certificate chain 204.Pa manifest.*certs . 205In either case there needs to be a suitable trust anchor in the trust store. 206.Pp 207We can now activate: 208.Bd -literal -offset indent 209# veriexec -z active 210 211.Ed 212Any user can check if 213.Xr mac_veriexec 4 214is 215.Ql active : 216.Bd -literal -offset indent 217$ veriexec -i active 218 219.Ed 220Any user can check that 221.Pa /mnt/bin/app 222is verified: 223.Bd -literal -offset indent 224$ veriexec -x /mnt/bin/app 225 226.Ed 227If it is not, we will get an Authentiaction error, 228but unless 229.Xr mac_veriexec 4 230is enforcing we would still be able to run it. 231.Sh NOTES 232It is only safe to set 233.Xr mac_veriexec 4 234to 235.Ql enforce 236state, if sufficient manifests have been loaded 237to cover all the applications that might need to be run. 238.Sh HISTORY 239The Verified Exec system first appeared in 240.Nx . 241This utility derives from the one found in Junos, 242which requires that manifest files be digitally signed. 243