347 lines
9.5 KiB
Groff
347 lines
9.5 KiB
Groff
.\" $NetBSD: veriexec.9,v 1.29 2015/12/09 18:25:32 maxv 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 December 9, 2015
|
|
.Dt VERIEXEC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm veriexec
|
|
.Nd in-kernel file integrity subsystem KPI
|
|
.Sh SYNOPSIS
|
|
.In sys/verified_exec.h
|
|
.Ft void
|
|
.Fn veriexec_init "void"
|
|
.Ft bool
|
|
.Fn veriexec_lookup "struct vnode *vp"
|
|
.Ft int
|
|
.Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \
|
|
"const u_char *name" "int flag" "bool *found"
|
|
.Ft void
|
|
.Fn veriexec_purge "struct vnode *vp"
|
|
.Ft int
|
|
.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"
|
|
.Ft int
|
|
.Fn veriexec_file_add "struct lwp *l" "prop_dictionary_t dict"
|
|
.Ft int
|
|
.Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp"
|
|
.Ft int
|
|
.Fn veriexec_table_delete "struct lwp *l" "struct mount *mp"
|
|
.Ft int
|
|
.Fn veriexec_flush "struct lwp *l"
|
|
.Ft int
|
|
.Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \
|
|
"const char *path" "int fmode"
|
|
.Ft int
|
|
.Fn veriexec_renamechk "struct lwp *l" "struct vnode *fromvp" \
|
|
"const char *fromname" "struct vnode *tovp" "const char *toname"
|
|
.Ft int
|
|
.Fn veriexec_removechk "struct lwp *l" "struct vnode *vp" \
|
|
"const char *name"
|
|
.Ft int
|
|
.Fn veriexec_unmountchk "struct mount *mp"
|
|
.Ft int
|
|
.Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict"
|
|
.Ft int
|
|
.Fn veriexec_dump "struct lwp *l" "prop_array_t rarray"
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the
|
|
.Tn KPI
|
|
for
|
|
.Em 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
|
|
.Em Veriexec
|
|
policy.
|
|
.Sh FUNCTIONS
|
|
.Ss Core Routines
|
|
.Bl -tag -width compact
|
|
.It Fn veriexec_init "void"
|
|
Initialize the
|
|
.Em Veriexec
|
|
subsystem.
|
|
Called only once during system startup.
|
|
.It Fn veriexec_lookup "vp"
|
|
Check if
|
|
.Ar vp
|
|
is monitored by
|
|
.Em Veriexec .
|
|
Returns
|
|
.Dv true
|
|
if it is, or
|
|
.Dv false
|
|
otherwise.
|
|
.It Fn veriexec_verify "l" "vp" "name" "flag" "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 -width VERIEXEC_INDIRECT
|
|
.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 Fn veriexec_purge "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.
|
|
.El
|
|
.Ss Fingerprint Related Routines
|
|
.Bl -tag -width compact
|
|
.It Fn veriexec_fpops_add "fp_type" "hash_len" "ctx_size" \
|
|
"init" "update" "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 -width compact
|
|
.It Fn veriexec_file_add "l" "dict"
|
|
Add a
|
|
.Em Veriexec
|
|
entry for the file described by
|
|
.Ar dict .
|
|
.Pp
|
|
.Ar dict
|
|
is expected to have the following:
|
|
.Bl -column entry-type string "entry type flags (see veriexec(4))"
|
|
.It Sy Name Type Purpose
|
|
.It file string filename
|
|
.It entry-type uint8 entry type flags ( see Xr veriexec 4 )
|
|
.It fp-type string fingerprint hashing algorithm
|
|
.It fp data the fingerprint
|
|
.El
|
|
.It Fn veriexec_file_delete "l" "vp"
|
|
Remove
|
|
.Em Veriexec
|
|
entry for
|
|
.Ar vp .
|
|
.It Fn veriexec_table_delete "l" "mp"
|
|
Remove
|
|
.Em Veriexec
|
|
table for mount-point
|
|
.Ar mp .
|
|
.It Fn veriexec_flush "l"
|
|
Delete all
|
|
.Em Veriexec
|
|
tables.
|
|
.El
|
|
.Ss Hook Handlers
|
|
.Bl -tag -width compact
|
|
.It Fn veriexec_openchk "l" "vp" "path" "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 Fn veriexec_renamechk "l" "fromvp" "fromname" "tovp" "toname"
|
|
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 Fn veriexec_removechk "l" "vp" "name"
|
|
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 Fn veriexec_unmountchk "mp"
|
|
Checks if the current strict level allows
|
|
.Ar mp
|
|
to be unmounted.
|
|
.El
|
|
.Ss Miscellaneous Routines
|
|
.Bl -tag -width compact
|
|
.It Fn veriexec_convert "vp" "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
|
|
.It Sy Name Type Purpose
|
|
.It entry-type uint8 entry type flags ( see Xr veriexec 4 )
|
|
.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.
|
|
.It Fn veriexec_dump "l" "rarray"
|
|
Fill
|
|
.Ar rarray
|
|
with entries for all files monitored by
|
|
.Em Veriexec
|
|
that have a filename associated with them.
|
|
.Pp
|
|
Each element in
|
|
.Ar rarray
|
|
is a dictionary with the same elements as filled by
|
|
.Fn veriexec_convert ,
|
|
with an additional field,
|
|
.Dq file ,
|
|
containing the filename.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -column srcxsysxkernxkernxverifiedexecxc foo
|
|
.It Sy Path Purpose
|
|
.It src/sys/dev/veriexec.c driver for userland communication
|
|
.It src/sys/sys/verified_exec.h shared (userland/kernel) header file
|
|
.It src/sys/kern/kern_veriexec.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 security 7 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr veriexecctl 8 ,
|
|
.Xr veriexecgen 8 ,
|
|
.Xr fileassoc 9
|
|
.Sh AUTHORS
|
|
.An Brett Lymn Aq Mt blymn@NetBSD.org
|
|
.An Elad Efrat Aq Mt elad@NetBSD.org
|
|
.Sh CAVEATS
|
|
There are two known issues with
|
|
.Em 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 committed 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.
|