diff options
Diffstat (limited to 'static/netbsd/man9/veriexec.9')
| -rw-r--r-- | static/netbsd/man9/veriexec.9 | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/static/netbsd/man9/veriexec.9 b/static/netbsd/man9/veriexec.9 new file mode 100644 index 00000000..15ebddbd --- /dev/null +++ b/static/netbsd/man9/veriexec.9 @@ -0,0 +1,346 @@ +.\" $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. |