.\" $NetBSD: veriexec.4,v 1.11 2006/04/06 00:19:06 simonb Exp $ .\" .\" Copyright 2005 Elad Efrat .\" Copyright 2005 Brett Lymn .\" .\" This code is donated to The NetBSD Foundation by the author. .\" .\" 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. The name of the Author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 December 12, 2005 .Dt VERIEXEC 4 .Sh NAME .Nm veriexec .Nd Veriexec pseudo-device .Sh SYNOPSIS .Cd pseudo-device veriexec .Sh DESCRIPTION The .Nm pseudo-device is used to interface the kernel's Veriexec data-structures. It is used to size the kernel data structures and load the Veriexec fingerprints into kernel memory. .Ss Veriexec file operations All the following operations are invoked using the .Xr ioctl 2 system call. Refer to that man page for the description of the .Em request and .Em argp parameters. The following section lists the requests that can be made via .Xr ioctl 2 . .Ss Veriexec file request descriptions .Bl -tag -width VERIEXEC_TABLESIZE .It Dv VERIEXEC_TABLESIZE Fa struct veriexec_sizing_params Sizes the in kernel hash tables to accommodate the fingerprint entries. This request must be made prior to loading the fingerprints into the kernel. The argument structure contains the device to which the hash table relates and the number of fingerprint entries that will be loaded into the kernel for the device. .It Dv VERIEXEC_LOAD Fa struct veriexec_params Inserts a fingerprint into the in-kernel tables. These tables must have been previously sized using the .Dv VERIEXEC_TABLESIZE request. The argument structure is, as defined in .Pa /usr/include/sys/verified_exec.h : .Bd -literal struct veriexec_params { unsigned char type; unsigned char fp_type[VERIEXEC_TYPE_MAXLEN]; char file[MAXPATHLEN]; unsigned int size; unsigned char *fingerprint; }; .Ed .Pp Where type is a bitfield that can be binary-OR'd with one or more of: .Bl -tag -width VERIEXEC_INDIRECT .It Dv VERIEXEC_DIRECT Allow execution of the file if fingerprint matches. .It Dv VERIEXEC_INDIRECT Allow execution of the file as a script interpreter only, direct command line invocation is disallowed. .It Dv VERIEXEC_FILE The file is a plain file, not an executable. .It Dv VERIEXEC_UNTRUSTED The file is located on untrusted storage. .El .Pp Followed by fp_type, which is the fingerprint type. This is a case-insensitive character string that must match one of the fingerprint types supported by the running kernel. Next the path to the file to which the fingerprint applies. The field size is the number of bytes contained in the fingerprint, this is used by the kernel to provide a simple sanity check on the fingerprint passed. Lastly, the fingerprint is a pointer to an array of characters that comprise the fingerprint for the file. .It Dv VERIEXEC_DELETE Fa struct veriexec_delete_params Removes either an entry or an entire table from Veriexec. To remove a single entry, both device id and inode number must be provided. If only a device id is provided and inode is zero, the entire table for the specified device will be removed. .It Dv VERIEXEC_QUERY Fa struct veriexec_query_params Queries a Veriexec table entry and returns the fingerprint and the algorithm used to calculate it, evaluation status, and entry type. .El .Pp Note that the requests .Dv VERIEXEC_TABLESIZE , .Dv VERIEXEC_LOAD , and .Dv VERIEXEC_DELETE are not permitted once the veriexec strict level has been raised past 0 by setting .Dv kern.veriexec.strict using .Xr sysctl 8 . .Sh SEE ALSO .Xr sysctl 3 , .Xr sysctl 8 , .Xr veriexecctl 8 .Sh NOTES The size field in the .Dv VERIEXEC_LOAD structure is only used to validate that the size of the fingerprint being passed is the expected size for that fingerprint hash type; it is not used for any other purpose. A malicious person could deliberately mismatch the size of the fingerprint array and, possibly, cause a kernel page fault panic when the kernel reads the input fingerprint array memory. Due to this, it is recommended only the root user be allowed to access this device.