143 lines
5.4 KiB
Groff
143 lines
5.4 KiB
Groff
.\" $NetBSD: veriexec.4,v 1.12 2006/08/28 20:55:16 hubertf Exp $
|
|
.\"
|
|
.\" Copyright 2005 Elad Efrat <elad@bsd.org.il>
|
|
.\" Copyright 2005 Brett Lymn <blymn@netbsd.org>
|
|
.\"
|
|
.\" 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 August 28, 2006
|
|
.Dt VERIEXEC 4
|
|
.Sh NAME
|
|
.Nm veriexec
|
|
.Nd Veriexec pseudo-device
|
|
.Sh SYNOPSIS
|
|
.Cd pseudo-device veriexec
|
|
.Sh DESCRIPTION
|
|
.Dq Veriexec
|
|
verifies the integrity of specified executables and files before they are
|
|
run or read.
|
|
This makes it much more difficult to insert a trojan horse into the system
|
|
and also makes it more difficult to run binaries that are not supposed to
|
|
be running, for example, packet sniffers, DDoS clients and so on.
|
|
.Pp
|
|
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.
|