.\" $NetBSD: veriexec.9,v 1.29 2015/12/09 18:25:32 maxv Exp $ .\" .\" Copyright 2006 Elad Efrat .\" Copyright 2006 Brett Lymn .\" .\" 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.