NetBSD/share/man/man9/veriexec.9

.\" $NetBSD: veriexec.9,v 1.13 2007/01/11 16:24:47 elad Exp $
.\"
.\" Copyright 2006 Elad Efrat <elad@NetBSD.org>
.\" Copyright 2006 Brett Lymn <blymn@NetBSD.org>
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Brett Lymn and Elad Efrat
.\"
.\" 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. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``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 FOUNDATION OR CONTRIBUTORS
.\" 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 11, 2007
.Dt VERIEXEC 9
.Os
.Sh NAME
.Nm veriexec
.Nd in-kernel file integrity subsystem KPI
.Sh SYNOPSIS
.In sys/verified_exec.h
.Sh DESCRIPTION
.Nm
is the KPI for Veriexec,
the
.Nx
in-kernel file integrity subsystem.
It is responsible for managing the supported hashing algorithms, fingerprint
calculation and comparison, file monitoring tables, and relevant hooks to
enforce the Veriexec policy.
.Ss Core Routines
.Bl -tag
.It Ft void Fn veriexec_init "void"
Initialize the Veriexec subsystem.
Should be called only once during system startup.
.It Ft "boolean_t" Fn veriexec_lookup "struct vnode *vp"
Check if
.Ar vp
is monitored by
.Em Veriexec
or not.
Returns
.Dv TRUE
if it is, or
.Dv FALSE
otherwise.
.It Ft int Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \
"const u_char *name" "int flag" "boolean_t *found"
Verifies the digital fingerprint of
.Ar vp .
.Ar name
is the filename, and
.Ar flag
is the access flag.
The access flag can be one of:
.Bl -tag
.It Dv VERIEXEC_DIRECT
The file was executed directly via
.Xr execve 2 .
.It Dv VERIEXEC_INDIRECT
The file was executed indirectly, either as an interpreter for a script or
mapped to an executable memory region.
.It Dv VERIEXEC_FILE
The file was opened for reading/writing.
.El
.Pp
.Ar l
is the LWP for the request context.
.Pp
An optional argument,
.Ar found ,
is a pointer to a boolean indicating whether an entry for the file was found
in the
.Em Veriexec
tables.
.It Ft void Fn veriexec_purge "struct vnode *vp"
Purge the file entry for
.Ar vp .
This invalidates the fingerprint so it will be evaluated next time the file
is accessed.
.\" veriexec_page_verify() intentionally not documented.
.It Ft void Fn veriexec_report "const u_char *msg" "u_char *name" \
"struct lwp *l" "int flags"
Log a Veriexec message in
.Ar msg
for file
.Ar name .
.Ar l
is optionally the LWP context in question.
.Pp
.Ar flags
control how the message will be formatted, where will it be logged to, and
whether the system should panic after posting it.
Flags can be binary-OR'd together.
Available flags include:
.Bl -tag
.It Dv REPORT_ALWAYS
The message should always be printed.
This is a synonym for 0.
.It Dv REPORT_VERBOSE
The message should be printed only if Veriexec is in verbose mode.
.It Dv REPORT_DEBUG
The message should be printed only if Veriexec is in debug verbosity.
.It Dv REPORT_ALARM
The message is an alarm.
If
.Ar l
is not
.Dv NULL ,
user and process ids will be printed.
The log will be sent to the
.Em LOG_ALERT
syslog facility.
.It Dv REPORT_PANIC
The system should
.Xr panic 9
after posting the message.
.El
.El
.Ss Fingerprint Related Routines
.Bl -tag
.It Ft Fn veriexec_fpops_add "const char *fp_type" "size_t hash_len" \
"size_t ctx_size" "veriexec_fpop_init_t init" "veriexec_fpop_update_t update" \
"veriexec_fpop_final_t final"
Add support for fingerprinting algorithm
.Ar fp_type
with binary hash length
.Ar hash_len
and calculation context size
.Ar ctx_size
to
.Em Veriexec .
.Ar init ,
.Ar update ,
and
.Ar final
are the routines used to initialize, update, and finalize a calculation
context.
.El
.Ss Table Management Routines
.Bl -tag
.It Ft int Fn veriexec_table_add "struct lwp *l" "prop_dictionary_t dict"
Prepare storage for a
.Em Veriexec
table, to optimize the lookup time.
.Pp
.Ar dict
holds the following elements:
.Bl -column mount
.Sy Name	Type	Purpose
.It mount	string	mount-point
.It count	uint64	estimated number of entries
.El
.It Ft int Fn veriexec_file_add "struct lwp *l" \
"prop_dictionary_t dict"
Add a Veriexec entry for the file described by
.Ar dict .
.Pp
.Ar dict
is expected to have the following:
.Bl -column entryxtype string
.Sy Name	Type	Purpose
.It file	string	filename
.It entry-type	uint8	entry type flags ( see access flags above )
.It fp-type	string	fingerprint hashing algorithm
.It fp	data	the fingerprint
.El
.It Ft int Fn veriexec_table_delete "struct lwp *l" "struct mount *mp"
Remove
.Em Veriexec
table for mount-point
.Ar mp .
.It Ft int Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp"
Remove
.Em Veriexec
entry for
.Ar vp .
.El
.Ss Hook Handlers
.Bl -tag
.It Ft int Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \
"const char *path" "int fmode"
Called when a file is opened.
.Pp
.Ar l
is the LWP opening the file,
.Ar vp
is a vnode for the file being opened as returned from
.Xr namei 9 .
If
.Dv NULL ,
the file is being created.
.Ar path
is the pathname for the file (not necessarily a full path), and
.Ar fmode
are the mode bits with which the file was opened.
.It Ft int Fn veriexec_renamechk "struct vnode *fromvp" \
"const char *fromname" "struct vnode *tovp" "const char *toname" \
"struct lwp *l"
Called when a file is renamed.
.Pp
.Ar fromvp
and
.Ar fromname
are the vnode and filename of the file being renamed.
.Ar tovp
and
.Ar toname
are the vnode and filename of the target file.
.Ar l
is the LWP renaming the file.
.Pp
Depending on the strict level,
.Nm
will either track changes appropriately or prevent the rename.
.It Ft int Fn veriexec_removechk "struct vnode *vp" "const char *name" \
"struct lwp *l"
Called when a file is removed.
.Pp
.Ar vp
is the vnode of the file being removed, and
.Ar name
is the filename.
.Ar l
is the LWP removing the file,
.Pp
Depending on the strict level,
.Nm
will either clean-up after the file or prevent its removal.
.It Ft int Fn veriexec_unmountchk "struct mount *mp"
Checks if the current strict level allows
.Ar mp
to be unmounted.
.El
.Ss Misc. Routines
.Bl -tag
.It Ft int Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict"
Convert
.Em Veriexec
entry for
.Ar vp
to human-readable
.Xr proplib 3
dictionary,
.Ar rdict ,
with the following elements:
.Bl -column entryxtype string
.Sy Name	Type	Purpose
.It entry-type	uint8	entry type ( see above )
.It status	uint8	entry status ( see below )
.It fp-type	string	fingerprint hashing algorithm
.It fp	data	the fingerprint
.El
.Pp
The
.Dq status
can be one of the following:
.Bl -column fingerprintxmismatch effect
.It Sy Status	Meaning
.It FINGERPRINT_NOTEVAL	not evaluated
.It FINGERPRINT_VALID	fingerprint match
.It FINGERPRINT_MISMATCH	fingerprint mismatch
.El
.Pp
If no entry was found,
.Er ENOENT
is returned.
Otherwise, zero.
.El
.Sh FILES
.Bl -column srcxsysxkernxkernxverifiedexecxc foo
.Sy Path	Purpose
.It src/sys/dev/verified_exec.c	driver for userland communication
.It src/sys/sys/verified_exec.h	shared (userland/kernel) header file
.It src/sys/kern/kern_verifiedexec.c	subsystem code
.It src/sys/kern/vfs_syscalls.c	rename, remove, and unmount policies
.It src/sys/kern/vfs_vnops.c	regular file access policy
.El
.Sh SEE ALSO
.Xr proplib 3 ,
.Xr sysctl 3 ,
.Xr veriexec 4 ,
.Xr sysctl 8 ,
.Xr veriexecctl 8 ,
.Xr veriexecgen 8 ,
.Xr fileassoc 9
.Sh AUTHORS
.An Brett Lymn Aq blymn@NetBSD.org
.An Elad Efrat Aq elad@NetBSD.org
.Sh CAVEATS
There are two known issues with Veriexec that should be considered when
using it.
.Ss Remote File-systems
There is an issue providing protection for files residing on mounts from
remote hosts.
Because access to the file-system does not necessarily go through
.Nm ,
there is no way to track on-disk changes.
While it is possible to minimize the effect by evaluating the file's
fingerprint on each access without caching the result, a problem arises when
a file is overwritten after its fingerprint has been evaluated and it is
running on the local host.
.Pp
An attacker could potentially overwrite the file contents in the remote host
at that point, and force a flush on the local host, resulting in paging in
of the files from the disk, introducing malicious code into a supposedly
safe address space.
.Pp
There is a fix for this issue, however due to dependencies on other work
that is still in progress it has not been commited yet.
.Ss Layered File-systems
Due to VFS limitations,
.Nm
cannot track the same on-disk file across multiple layers of overlay
file-systems.
Therefore, you cannot expect changes to files on overlay mounts will be
detected simply because the underlying mount is monitored by
.Nm .
.Pp
A workaround for this issue is listing all files, under all mounts, you want
monitored in the signature file.