share/man/man4/veriexec.4

   1 .\" $NetBSD: veriexec.4,v 1.19 2008/02/10 19:32:23 elad Exp $
   2 .\"
   3 .\" Copyright 2005 Elad Efrat <elad@bsd.org.il>
   4 .\" Copyright 2005 Brett Lymn <blymn@netbsd.org>
   5 .\"
   6 .\" This code is donated to The NetBSD Foundation by the author.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. The name of the Author may not be used to endorse or promote
  14 .\"    products derived from this software without specific prior written
  15 .\"    permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .Dd February 10, 2008
  30 .Dt VERIEXEC 4
  31 .Os
  32 .Sh NAME
  33 .Nm veriexec
  34 .Nd Veriexec pseudo-device
  35 .Sh SYNOPSIS
  36 .Cd pseudo-device veriexec
  37 .Sh DESCRIPTION
  38 .Em Veriexec
  39 verifies the integrity of specified executables and files before they are
  40 run or read.
  41 This makes it much more difficult to insert a trojan horse into the system
  42 and also makes it more difficult to run binaries that are not supposed to
  43 be running, for example, packet sniffers, DDoS clients and so on.
  44 .Pp
  45 The
  46 .Nm
  47 pseudo-device is used to load and delete entries to and from the in-kernel
  48 .Em Veriexec
  49 databases, as well as query information about them.
  50 It can also be used to dump the entire database.
  51 .Ss Kernel-userland interaction
  52 .Em Veriexec
  53 uses
  54 .Xr proplib 3
  55 for communication between the kernel and userland.
  56 .Bl -tag -width XXXX
  57 .It Dv VERIEXEC_LOAD
  58 Load an entry for a file to be monitored by
  59 .Em Veriexec .
  60 .Pp
  61 The dictionary passed contains the following elements:
  62 .Bl -column entryxtype string
  63 .It Sy Name     Type    Purpose
  64 .It file        string  filename for this entry
  65 .It entry-type  uint8   entry type ( see below )
  66 .It fp-type     string  fingerprint hashing algorithm
  67 .It fp  data    the fingerprint
  68 .El
  69 .Pp
  70 .Dq entry-type
  71 can be one or more (binary-OR'd) of the following:
  72 .Bl -column veriexecxuntrusted effect
  73 .It Sy Type     Effect
  74 .It Dv VERIEXEC_DIRECT  can execute directly
  75 .It Dv VERIEXEC_INDIRECT        can execute indirectly (interpreter, Xr mmap 2 )
  76 .It Dv VERIEXEC_FILE    can be opened
  77 .It Dv VERIEXEC_UNTRUSTED       located on untrusted storage
  78 .El
  79 .It Dv VERIEXEC_DELETE
  80 Removes either an entry for a single file or entries for an entire mount from
  81 .Em Veriexec .
  82 .Pp
  83 The dictionary passed contains the following elements:
  84 .Bl -column file string
  85 .It Sy Name     Type    Purpose
  86 .It file        string  filename or mount-point
  87 .El
  88 .It Dv VERIEXEC_DUMP
  89 Dump the
  90 .Em Veriexec
  91 monitored files database from the kernel.
  92 .Pp
  93 Only files that the filename is kept for them will be dumped.
  94 The returned array contains dictionaries with the following elements:
  95 .Bl -column entryxtype string
  96 .It Sy Name     Type    Purpose
  97 .It file        string  filename
  98 .It fp-type     string  fingerprint hashing algorithm
  99 .It fp  data    the fingerprint
 100 .It entry-type  uint8   entry type ( see above )
 101 .El
 102 .It Dv VERIEXEC_FLUSH
 103 Flush the
 104 .Em Veriexec
 105 database, removing all entries.
 106 .Pp
 107 This command has no parameters.
 108 .It Dv VERIEXEC_QUERY
 109 Queries
 110 .Em Veriexec
 111 about a file, returning information that may be useful about it.
 112 .Pp
 113 The dictionary passed contains the following elements:
 114 .Bl -column file string
 115 .It Sy Name     Type    Purpose
 116 .It file        string  filename
 117 .El
 118 .Pp
 119 The dictionary returned contains the following elements:
 120 .Bl -column entryxtype string
 121 .It Sy Name     Type    Purpose
 122 .It entry-type  uint8   entry type ( see above )
 123 .It status      uint8   entry status
 124 .It fp-type     string  fingerprint hashing algorithm
 125 .It fp  data    the fingerprint
 126 .El
 127 .Pp
 128 .Dq status
 129 can be one of the following:
 130 .Bl -column fingerprintxmismatch effect
 131 .It Sy Status   Meaning
 132 .It Dv FINGERPRINT_NOTEVAL      not evaluated
 133 .It Dv FINGERPRINT_VALID        fingerprint match
 134 .It Dv FINGERPRINT_MISMATCH     fingerprint mismatch
 135 .El
 136 .El
 137 .Pp
 138 Note that the requests
 139 .Dv VERIEXEC_LOAD ,
 140 .Dv VERIEXEC_DELETE ,
 141 and
 142 .Dv VERIEXEC_FLUSH
 143 are not permitted once the strict level has been raised past 0.
 144 .Sh SEE ALSO
 145 .Xr proplib 3 ,
 146 .Xr sysctl 3 ,
 147 .Xr security 8 ,
 148 .Xr sysctl 8 ,
 149 .Xr veriexecctl 8 ,
 150 .Xr veriexecgen 8 ,
 151 .Xr veriexec 9
 152 .Sh NOTES
 153 .Nm
 154 is part of the default configuration on the following architectures: amd64,
 155 i386, prep, sparc64.
 156 .Sh AUTHORS
 157 .An Brett Lymn Aq blymn@NetBSD.org
 158 .An Elad Efrat Aq elad@NetBSD.org