1.\" $NetBSD: veriexec.4,v 1.7 2005/08/02 18:54:53 elad Exp $ 2.\" 3.\" Copyright 2005 Elad Efrat <elad@bsd.org.il> 4.\" Copyright 2005 Brett Lymn <blymn@netbsd.org> 5.\" 6.\" This code is donated to The NetBSD Foundation by the author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. The name of the Author may not be used to endorse or promote 14.\" products derived from this software without specific prior written 15.\" permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $Id: veriexec.4,v 1.7 2005/08/02 18:54:53 elad Exp $ 30.\" 31.Dd August 2, 2005 32.Dt VERIEXEC 4 33.Sh NAME 34.Nm veriexec 35.Nd Veriexec pseudo-device 36.Sh SYNOPSIS 37.Cd pseudo-device veriexec 38.Sh DESCRIPTION 39The 40.Nm 41pseudo-device is used to interface the kernel's Veriexec data-structures. 42It is used to size the kernel data structures and load the Veriexec 43fingerprints into kernel memory. 44.Ss Veriexec file operations 45All the following operations are invoked using the 46.Xr ioctl 2 47system call. 48Refer to that man page for the description of the 49.Em request 50and 51.Em argp 52parameters. 53The following section lists the requests that can be made via 54.Xr ioctl 2 . 55.Ss Veriexec file request descriptions 56.Bl -tag -width VERIEXEC_TABLESIZE 57.It Dv VERIEXEC_TABLESIZE Fa struct veriexec_sizing_params 58Sizes the in kernel hash tables to accommodate the fingerprint entries. 59This request must be made prior to loading the fingerprints into the 60kernel. 61The argument structure contains the device to which the hash table relates 62and the number of fingerprint entries that will be loaded into the 63kernel for the device. 64.It Dv VERIEXEC_LOAD Fa struct veriexec_params 65Inserts a fingerprint into the in-kernel tables. 66These tables must have been previously sized using the 67.Dv VERIEXEC_TABLESIZE 68request. 69The argument structure is, as defined in 70.Pa /usr/include/sys/verified_exec.h : 71.Bd -literal 72struct veriexec_params { 73 unsigned char type; 74 unsigned char fp_type[VERIEXEC_TYPE_MAXLEN]; 75 char file[MAXPATHLEN]; 76 unsigned int size; 77 unsigned char *fingerprint; 78}; 79.Ed 80.Pp 81Where type is a bitfield that can be binary-OR'd with one or more of: 82.Bl -tag -width VERIEXEC_INDIRECT 83.It Dv VERIEXEC_DIRECT 84Allow execution of the file if fingerprint matches. 85.It Dv VERIEXEC_INDIRECT 86Allow execution of the file as a script interpreter only, direct command 87line invocation is disallowed. 88.It Dv VERIEXEC_FILE 89The file is a plain file, not an executable. 90.El 91.Pp 92Followed by fp_type, which is the fingerprint type. 93This is a case-insensitive character string that must match one of 94the fingerprint types supported by the running kernel. 95Next the path to the file to which the fingerprint applies. 96The field size is the number of bytes contained in the 97fingerprint, this is used by the kernel to provide a simple sanity check 98on the fingerprint passed. 99Lastly, the fingerprint is a pointer to an 100array of characters that comprise the fingerprint for the file. 101.El 102.Pp 103Note that the requests 104.Dv VERIEXEC_TABLESIZE 105and 106.Dv VERIEXEC_LOAD 107are not permitted once the veriexec strict level has been raised past 0 108by setting 109.Dv kern.veriexec.strict 110using 111.Xr sysctl 8 . 112.Sh SEE ALSO 113.Xr sysctl 3 , 114.Xr sysctl 8 , 115.Xr veriexecctl 8 116.Sh NOTES 117The size field in the 118.Dv VERIEXEC_LOAD 119structure is only used to validate that the size of the fingerprint being 120passed is the expected size for that fingerprint hash type; it is not used 121for any other purpose. 122A malicious person could deliberately mismatch the size of the fingerprint 123array and, possibly, cause a kernel page fault panic when the kernel 124reads the input fingerprint array memory. 125Due to this, it is recommended only the root user be allowed to access 126this device. 127