share/man/man5/veriexec.5

   1 .\" $NetBSD: veriexecctl.8,v 1.33 2008/02/15 15:33:56 elad Exp $
   2 .\"
   3 .\" Copyright (c) 1999
   4 .\"     Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au
   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. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     $Id: veriexec.5,v 1.1 2008/02/18 10:37:19 elad Exp $
  33 .\"
  34 .Dd February 18, 2008
  35 .Dt VERIEXEC 5
  36 .Os
  37 .Sh NAME
  38 .Nm veriexec
  39 .Nd format for the
  40 .Em Veriexec
  41 signatures file
  42 .Sh DESCRIPTION
  43 .Em Veriexec
  44 loads entries to the in-kernel database from a file describing files to be
  45 monitored and the type of monitoring.
  46 This file is often referred to as the
  47 .Sq signatures database
  48 or
  49 .Sq signatures file .
  50 .Pp
  51 The signatures file can be easily created using
  52 .Xr veriexecgen 8 .
  53 .Sh SIGNATURES DATABASE FORMAT
  54 The signatures database has a line based structure, where each line has several
  55 fields separated by white-space (space, tabs, etc.) taking the following form:
  56 .Pp
  57 .Dl path        type    fingerprint     flags
  58 .Pp
  59 The description for each field is as follows:
  60 .Bl -tag -width XXXX
  61 .It path
  62 The full path to the file.
  63 White-space characters can be escaped if prefixed with a
  64 .Sq \e .
  65 .It type
  66 Type of fingerprinting algorithm used for the file.
  67 .Pp
  68 Requires kernel support for the specified algorithm.
  69 List of fingerprinting algorithms supported by the kernel can be obtained by
  70 using the following command:
  71 .Bd -literal -offset indent
  72 # sysctl kern.veriexec.algorithms
  73 .Ed
  74 .It fingerprint
  75 The fingerprint for the file.
  76 Can (usually) be generated using the following command:
  77 .Bd -literal -offset indent
  78 % cksum -a \*[Lt]algorithm\*[Gt] \*[Lt]file\*[Gt]
  79 .Ed
  80 .It flags
  81 Optional listing of entry flags, separated by a comma.
  82 These may include:
  83 .Bl -tag -width XXXX
  84 .It direct
  85 Allow direct execution only.
  86 .Pp
  87 Execution of a program is said to be
  88 .Dq direct
  89 when the program is invoked by the user (either in a script, manually typing it,
  90 etc.) via the
  91 .Xr execve 2
  92 syscall.
  93 .It indirect
  94 Allow indirect execution only.
  95 .Pp
  96 Execution of a program is said to be
  97 .Dq indirect
  98 if it is invoked by the kernel to interpret a script
  99 .Pq Dq hash-bang .
 100 .It file
 101 Allow opening the file only, via the
 102 .Xr open 2
 103 syscall (no execution is allowed).
 104 .It untrusted
 105 Indicate that the file is located on untrusted storage and its fingerprint
 106 evaluation status should not be cached, but rather re-calculated each time
 107 it is accessed.
 108 .\"It also enabled per-page fingerprints for the file, causing pages it as
 109 .\"backing store to be verified for their integrity as well.
 110 .Pp
 111 Fingerprints for untrusted files will always be evaluated on load.
 112 .El
 113 .Pp
 114 To improve readaibility of the signatures file, the following aliases are
 115 provided:
 116 .Bl -tag -width XXXX
 117 .It program
 118 An alias for
 119 .Dq direct .
 120 .It interpreter
 121 An alias for
 122 .Dq indirect
 123 .It script
 124 An alias for both
 125 .Dq direct
 126 and
 127 .Dq file .
 128 .It library
 129 An alias for both
 130 .Dq file
 131 and
 132 .Dq indirect .
 133 .El
 134 .Pp
 135 If no flags are specified,
 136 .Dq direct
 137 is assumed.
 138 .El
 139 .Pp
 140 Comments begin with a
 141 .Sq \&#
 142 character and span to the end of the line.
 143 .Sh SEE ALSO
 144 .Xr veriexec 4 ,
 145 .Xr security 8 ,
 146 .Xr veriexec 8 ,
 147 .Xr veriexecctl 8 ,
 148 .Xr veriexecgen 8
 149 .Sh HISTORY
 150 .Nm
 151 first appeared in
 152 .Nx 2.0 .
 153 .Sh AUTHORS
 154 .An Brett Lymn Aq blymn@NetBSD.org
 155 .An Elad Efrat Aq elad@NetBSD.org