1.\" $NetBSD: veriexec.9,v 1.24 2010/04/13 07:16:31 jruoho Exp $ 2.\" 3.\" Copyright 2006 Elad Efrat <elad@NetBSD.org> 4.\" Copyright 2006 Brett Lymn <blymn@NetBSD.org> 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Brett Lymn and Elad Efrat 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Neither the name of The NetBSD Foundation nor the names of its 15.\" contributors may be used to endorse or promote products derived 16.\" from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 13, 2010 31.Dt VERIEXEC 9 32.Os 33.Sh NAME 34.Nm veriexec 35.Nd in-kernel file integrity subsystem KPI 36.Sh SYNOPSIS 37.In sys/verified_exec.h 38.Ft void 39.Fn veriexec_init "void" 40.Ft bool 41.Fn veriexec_lookup "struct vnode *vp" 42.Ft int 43.Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \ 44"const u_char *name" "int flag" "bool *found" 45.Ft void 46.Fn veriexec_purge "struct vnode *vp" 47.Ft int 48.Fn veriexec_fpops_add "const char *fp_type" "size_t hash_len" \ 49"size_t ctx_size" "veriexec_fpop_init_t init" "veriexec_fpop_update_t update" \ 50"veriexec_fpop_final_t final" 51.Ft int 52.Fn veriexec_file_add "struct lwp *l" "prop_dictionary_t dict" 53.Ft int 54.Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp" 55.Ft int 56.Fn veriexec_table_delete "struct lwp *l" "struct mount *mp" 57.Ft int 58.Fn veriexec_flush "struct lwp *l" 59.Ft int 60.Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \ 61"const char *path" "int fmode" 62.Ft int 63.Fn veriexec_renamechk "struct lwp *l" "struct vnode *fromvp" \ 64"const char *fromname" "struct vnode *tovp" "const char *toname" 65.Ft int 66.Fn veriexec_removechk "struct lwp *l" "struct vnode *vp" \ 67"const char *name" 68.Ft int 69.Fn veriexec_unmountchk "struct mount *mp" 70.Ft int 71.Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict" 72.Ft int 73.Fn veriexec_dump "struct lwp *l" "prop_array_t rarray" 74.Sh DESCRIPTION 75.Nm 76is the 77.Tn KPI 78for 79.Em Veriexec , 80the 81.Nx 82in-kernel file integrity subsystem. 83It is responsible for managing the supported hashing algorithms, fingerprint 84calculation and comparison, file monitoring tables, and relevant hooks to 85enforce the 86.Em Veriexec 87policy. 88.Sh FUNCTIONS 89.Ss Core Routines 90.Bl -tag -width compact 91.It Fn veriexec_init "void" 92Initialize the 93.Em Veriexec 94subsystem. 95Called only once during system startup. 96.It Fn veriexec_lookup "vp" 97Check if 98.Ar vp 99is monitored by 100.Em Veriexec . 101Returns 102.Dv true 103if it is, or 104.Dv false 105otherwise. 106.It Fn veriexec_verify "l" "vp" "name" "flag" "found" 107Verifies the digital fingerprint of 108.Ar vp . 109.Ar name 110is the filename, and 111.Ar flag 112is the access flag. 113The access flag can be one of: 114.Bl -tag -width VERIEXEC_INDIRECT 115.It Dv VERIEXEC_DIRECT 116The file was executed directly via 117.Xr execve 2 . 118.It Dv VERIEXEC_INDIRECT 119The file was executed indirectly, either as an interpreter for a script or 120mapped to an executable memory region. 121.It Dv VERIEXEC_FILE 122The file was opened for reading/writing. 123.El 124.Pp 125.Ar l 126is the LWP for the request context. 127.Pp 128An optional argument, 129.Ar found , 130is a pointer to a boolean indicating whether an entry for the file was found 131in the 132.Em Veriexec 133tables. 134.It Fn veriexec_purge "vp" 135Purge the file entry for 136.Ar vp . 137This invalidates the fingerprint so it will be evaluated next time the file 138is accessed. 139.\" veriexec_page_verify() intentionally not documented. 140.El 141.Ss Fingerprint Related Routines 142.Bl -tag -width compact 143.It Fn veriexec_fpops_add "fp_type" "hash_len" "ctx_size" \ 144"init" "update" "final" 145Add support for fingerprinting algorithm 146.Ar fp_type 147with binary hash length 148.Ar hash_len 149and calculation context size 150.Ar ctx_size 151to 152.Em Veriexec . 153.Ar init , 154.Ar update , 155and 156.Ar final 157are the routines used to initialize, update, and finalize a calculation 158context. 159.El 160.Ss Table Management Routines 161.Bl -tag -width compact 162.It Fn veriexec_file_add "l" "dict" 163Add a 164.Em Veriexec 165entry for the file described by 166.Ar dict . 167.Pp 168.Ar dict 169is expected to have the following: 170.Bl -column entry-type string "entry type flags (see veriexec(4))" 171.It Sy Name Type Purpose 172.It file string filename 173.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) 174.It fp-type string fingerprint hashing algorithm 175.It fp data the fingerprint 176.El 177.It Fn veriexec_file_delete "l" "vp" 178Remove 179.Em Veriexec 180entry for 181.Ar vp . 182.It Fn veriexec_table_delete "l" "mp" 183Remove 184.Em Veriexec 185table for mount-point 186.Ar mp . 187.It Fn veriexec_flush "l" 188Delete all 189.Em Veriexec 190tables. 191.El 192.Ss Hook Handlers 193.Bl -tag -width compact 194.It Fn veriexec_openchk "l" "vp" "path" "fmode" 195Called when a file is opened. 196.Pp 197.Ar l 198is the LWP opening the file, 199.Ar vp 200is a vnode for the file being opened as returned from 201.Xr namei 9 . 202If 203.Dv NULL , 204the file is being created. 205.Ar path 206is the pathname for the file (not necessarily a full path), and 207.Ar fmode 208are the mode bits with which the file was opened. 209.It Fn veriexec_renamechk "l" "fromvp" "fromname" "tovp" "toname" 210Called when a file is renamed. 211.Pp 212.Ar fromvp 213and 214.Ar fromname 215are the vnode and filename of the file being renamed. 216.Ar tovp 217and 218.Ar toname 219are the vnode and filename of the target file. 220.Ar l 221is the LWP renaming the file. 222.Pp 223Depending on the strict level, 224.Nm 225will either track changes appropriately or prevent the rename. 226.It Fn veriexec_removechk "l" "vp" "name" 227Called when a file is removed. 228.Pp 229.Ar vp 230is the vnode of the file being removed, and 231.Ar name 232is the filename. 233.Ar l 234is the LWP removing the file, 235.Pp 236Depending on the strict level, 237.Nm 238will either clean-up after the file or prevent its removal. 239.It Fn veriexec_unmountchk "mp" 240Checks if the current strict level allows 241.Ar mp 242to be unmounted. 243.El 244.Ss Miscellaneous Routines 245.Bl -tag -width compact 246.It Fn veriexec_convert "vp" "rdict" 247Convert 248.Em Veriexec 249entry for 250.Ar vp 251to human-readable 252.Xr proplib 3 253dictionary, 254.Ar rdict , 255with the following elements: 256.Bl -column entryxtype string 257.It Sy Name Type Purpose 258.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) 259.It status uint8 entry status ( see below ) 260.It fp-type string fingerprint hashing algorithm 261.It fp data the fingerprint 262.El 263.Pp 264The 265.Dq status 266can be one of the following: 267.Bl -column fingerprintxmismatch effect 268.It Sy Status Meaning 269.It FINGERPRINT_NOTEVAL not evaluated 270.It FINGERPRINT_VALID fingerprint match 271.It FINGERPRINT_MISMATCH fingerprint mismatch 272.El 273.Pp 274If no entry was found, 275.Er ENOENT 276is returned. 277Otherwise, zero. 278.It Fn veriexec_dump "l" "rarray" 279Fill 280.Ar rarray 281with entries for all files monitored by 282.Em Veriexec 283that have a filename associated with them. 284.Pp 285Each element in 286.Ar rarray 287is a dictionary with the same elements as filled by 288.Fn veriexec_convert , 289with an additional field, 290.Dq file , 291containing the filename. 292.El 293.Sh FILES 294.Bl -column srcxsysxkernxkernxverifiedexecxc foo 295.It Sy Path Purpose 296.It src/sys/dev/verified_exec.c driver for userland communication 297.It src/sys/sys/verified_exec.h shared (userland/kernel) header file 298.It src/sys/kern/kern_verifiedexec.c subsystem code 299.It src/sys/kern/vfs_syscalls.c rename, remove, and unmount policies 300.It src/sys/kern/vfs_vnops.c regular file access policy 301.El 302.Sh SEE ALSO 303.Xr proplib 3 , 304.Xr sysctl 3 , 305.Xr veriexec 4 , 306.Xr security 8 , 307.Xr sysctl 8 , 308.Xr veriexecctl 8 , 309.Xr veriexecgen 8 , 310.Xr fileassoc 9 311.Sh AUTHORS 312.An Brett Lymn Aq blymn@NetBSD.org 313.An Elad Efrat Aq elad@NetBSD.org 314.Sh CAVEATS 315There are two known issues with 316.Em Veriexec 317that should be considered when using it. 318.Ss Remote File-systems 319There is an issue providing protection for files residing on mounts from 320remote hosts. 321Because access to the file-system does not necessarily go through 322.Nm , 323there is no way to track on-disk changes. 324While it is possible to minimize the effect by evaluating the file's 325fingerprint on each access without caching the result, a problem arises when 326a file is overwritten after its fingerprint has been evaluated and it is 327running on the local host. 328.Pp 329An attacker could potentially overwrite the file contents in the remote host 330at that point, and force a flush on the local host, resulting in paging in 331of the files from the disk, introducing malicious code into a supposedly 332safe address space. 333.Pp 334There is a fix for this issue, however due to dependencies on other work 335that is still in progress it has not been committed yet. 336.Ss Layered File-systems 337Due to VFS limitations, 338.Nm 339cannot track the same on-disk file across multiple layers of overlay 340file-systems. 341Therefore, you cannot expect changes to files on overlay mounts will be 342detected simply because the underlying mount is monitored by 343.Nm . 344.Pp 345A workaround for this issue is listing all files, under all mounts, you want 346monitored in the signature file. 347