VERIEXEC(9)            NetBSD Kernel Developer's Manual            VERIEXEC(9)

     veriexec -- in-kernel file integrity subsystem KPI

     #include <sys/verified_exec.h>

     veriexec is the KPI for Veriexec, the NetBSD in-kernel file integrity
     subsystem.  It is responsible for managing the supported hashing algo-
     rithms, fingerprint calculation and comparison, file monitoring tables,
     and relevant hooks to enforce the Veriexec policy.

   Core Routines
     void veriexec_init(void)
               Initialize the Veriexec subsystem.  Should be called only once
               during system startup.

     struct veriexec_file_entry *vfe veriexec_lookup(struct vnode *vp)
               Lookup private Veriexec data associated with vp.  Returns NULL
               if file is not monitored by Veriexec.

     int veriexec_verify(struct lwp *l, struct vnode *vp, const u_char *name,
               int flag, boolean_t *found)
               Verifies the digital fingerprint of vp.  name is the filename,
               and flag is the access flag.  The access flag can be one of:

                             The file was executed directly via execve(2).

                             The file was executed indirectly, either as an
                             interpreter for a script or mapped to an exe-
                             cutable memory region.

                             The file was opened for reading/writing.

               l is the LWP for the request context.

               An optional argument, found, is a pointer to a boolean indicat-
               ing whether an entry for the file was found in the Veriexec

     void veriexec_purge(struct vnode *vp)
               Purge the file entry for vp.  This invalidates the fingerprint
               so it will be evaluated next time the file is accessed.

     void veriexec_report(const u_char *msg, u_char *name, struct lwp *l, int
               Log a Veriexec message in msg for file name.  l is optionally
               the LWP context in question.

               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

                             The message should always be printed.  This is a
                             synonym for 0.

                             The message should be printed only if Veriexec is
                             in verbose mode.

               REPORT_DEBUG  The message should be printed only if Veriexec is
                             in debug verbosity.

               REPORT_ALARM  The message is an alarm.  If l is not NULL, user
                             and process ids will be printed.  The log will be
                             sent to the LOG_ALERT syslog facility.

               REPORT_PANIC  The system should panic(9) after posting the mes-

   Fingerprint Related Routines
     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 fp_type with binary
               hash length hash_len and calculation context size ctx_size to
               Veriexec.  init, update, and final are the routines used to
               initialize, update, and finalize a calculation context.

   Table Management Routines
     int veriexec_table_add(struct lwp *l, prop_dictionary_t dict)
               Prepare storage for a Veriexec table, to optimize the lookup

               dict holds the following elements:

               Name     TypePurpose
               mount    stringmount-point
               count    uint64estimated number of entries

     int veriexec_file_add(struct lwp *l, prop_dictionary_t dict)
               Add a Veriexec entry for the file described by dict.

               dict is expected to have the following:

               Name          Type      Purpose
               file          string    filename
               entry-type    uint8     entry type flags (see access flags
               fp-type       string    fingerprint hashing algorithm
               fp            data      the fingerprint

     int veriexec_table_delete(struct mount *mp)
               Remove Veriexec table for mount-point mp.

     int veriexec_file_delete(struct vnode *vp)
               Remove Veriexec entry for vp.

   Hook Handlers
     int veriexec_renamechk(struct vnode *fromvp, const char *fromname, struct
               vnode *tovp, const char *toname, struct lwp *l)
               Called when a file is renamed.

               fromvp and fromname are the vnode and filename of the file
               being renamed.  tovp and toname are the vnode and filename of
               the target file.  l is the LWP renaming the file.

               Depending on the strict level, veriexec will either track
               changes appropriately or prevent the rename.

     int veriexec_removechk(struct vnode *vp, const char *name, struct lwp *l)
               Called when a file is removed.

               vp is the vnode of the file being removed, and name is the
               filename.  l is the LWP removing the file,

               Depending on the strict level, veriexec will either clean-up
               after the file or prevent its removal.

     int veriexec_unmountchk(struct mount *mp)
               Checks if the current strict level allows mp to be unmounted.

   Misc. Routines
     int veriexec_convert(struct vnode *vp, prop_dictionary_t rdict)
               Convert Veriexec entry for vp to human-readable proplib(3) dic-
               tionary, rdict, with the following elements:

               Name          Type      Purpose
               entry-type    uint8     entry type (see above)
               status        uint8     entry status (see below)
               fp-type       string    fingerprint hashing algorithm
               fp            data      the fingerprint

               The ``status'' can be one of the following:

               Status                  Meaning
               FINGERPRINT_NOTEVAL     not evaluated
               FINGERPRINT_VALID       fingerprint match
               FINGERPRINT_MISMATCH    fingerprint mismatch

               If no entry was found, ENOENT is returned.  Otherwise, zero.

     Path                                Purpose
     src/sys/dev/verified_exec.c         driver for userland communication
     src/sys/sys/verified_exec.h         shared (userland/kernel) header file
     src/sys/kern/kern_verifiedexec.c    subsystem code
     src/sys/kern/vfs_syscalls.c         rename, remove, and unmount policies
     src/sys/kern/vfs_vnops.c            regular file access policy

     proplib(3), sysctl(3), veriexec(4), sysctl(8), veriexecctl(8),
     veriexecgen(8), fileassoc(9)

     Brett Lymn <>
     Elad Efrat <>

     There are two known issues with Veriexec that should be considered when
     using it.

   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 veriexec, 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.

     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.

     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.

   Layered File-systems
     Due to VFS limitations, veriexec 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 veriexec.

     A workaround for this issue is listing all files, under all mounts, you
     want monitored in the signature file.

NetBSD 4.0                     December 1, 2006                     NetBSD 4.0