.\" $NetBSD: veriexec.4,v 1.26 2018/01/17 12:41:48 sevan 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 January 17, 2018
.Dt VERIEXEC 4
.Os
.Sh NAME
.Nm veriexec
.Nd Veriexec pseudo-device
.Sh SYNOPSIS
.Cd pseudo-device veriexec
.Sh DESCRIPTION
.Em 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 load and delete entries to and from the in-kernel
.Em Veriexec
databases, as well as query information about them.
It can also be used to dump the entire database.
.Ss Kernel-userland interaction
.Em Veriexec
uses
.Xr proplib 3
for communication between the kernel and userland.
.Bl -tag -width XXXX
.It Dv VERIEXEC_LOAD
Load an entry for a file to be monitored by
.Em Veriexec .
.Pp
The dictionary passed contains the following elements:
.Bl -column keepxfilename string
.It Sy Name Ta Sy Type Ta Sy Purpose
.It file	string	filename for this entry
.It entry-type	uint8	entry type ( see below )
.It fp-type	string	fingerprint hashing algorithm
.It fp	data	the fingerprint
.It keep-filename	bool	whether or not to retain the entry's filename
.El
.Pp
.Dq entry-type
can be one or more (binary-OR'd) of the following:
.Bl -column veriexecxuntrusted effect
.It Sy Type Ta Sy Effect
.It Dv VERIEXEC_DIRECT	can execute directly
.It Dv VERIEXEC_INDIRECT	can execute indirectly (interpreter, Xr mmap 2 )
.It Dv VERIEXEC_FILE	can be opened
.It Dv VERIEXEC_UNTRUSTED	located on untrusted storage
.El
.It Dv VERIEXEC_DELETE
Removes either an entry for a single file or entries for an entire mount from
.Em Veriexec .
.Pp
The dictionary passed contains the following elements:
.Bl -column file string
.It Sy Name Ta Sy Type Ta Sy Purpose
.It file	string	filename or mount-point
.El
.It Dv VERIEXEC_DUMP
Dump the
.Em Veriexec
monitored files database from the kernel.
.Pp
Only files for which the filename was kept will be dumped.
The returned array contains dictionaries with the following elements:
.Bl -column entryxtype string
.It Sy Name Ta Sy Type Ta Sy Purpose
.It file	string	filename
.It fp-type	string	fingerprint hashing algorithm
.It fp	data	the fingerprint
.It entry-type	uint8	entry type ( see above )
.El
.It Dv VERIEXEC_FLUSH
Flush the
.Em Veriexec
database, removing all entries.
.Pp
This command has no parameters.
.It Dv VERIEXEC_QUERY
Queries
.Em Veriexec
about a file, returning information that may be useful about it.
.Pp
The dictionary passed contains the following elements:
.Bl -column file string
.It Sy Name Ta Sy Type Ta Sy Purpose
.It file	string	filename
.El
.Pp
The dictionary returned contains the following elements:
.Bl -column entryxtype string
.It Sy Name Ta Sy Type Ta Sy Purpose
.It entry-type	uint8	entry type ( see above )
.It status	uint8	entry status
.It fp-type	string	fingerprint hashing algorithm
.It fp	data	the fingerprint
.El
.Pp
.Dq status
can be one of the following:
.Bl -column fingerprintxmismatch effect
.It Sy Status Ta Sy Meaning
.It Dv FINGERPRINT_NOTEVAL	not evaluated
.It Dv FINGERPRINT_VALID	fingerprint match
.It Dv FINGERPRINT_MISMATCH	fingerprint mismatch
.El
.El
.Pp
Note that the requests
.Dv VERIEXEC_LOAD ,
.Dv VERIEXEC_DELETE ,
and
.Dv VERIEXEC_FLUSH
are not permitted once the strict level has been raised past 0.
.Sh SEE ALSO
.Xr proplib 3 ,
.Xr sysctl 3 ,
.Xr security 7 ,
.Xr sysctl 8 ,
.Xr veriexecctl 8 ,
.Xr veriexecgen 8 ,
.Xr veriexec 9
.Sh NOTES
.Nm
is part of the default configuration on the following architectures: amd64,
i386, macppc, prep, sparc64.
.Sh AUTHORS
.An Brett Lymn Aq Mt blymn@NetBSD.org
.An Elad Efrat Aq Mt elad@NetBSD.org