Tue Apr 13 07:14:45 2010 UTC ()
Provide prototypes in SYNOPSIS; use only parameter names in FUNCTIONS.


(jruoho)
diff -r1.22 -r1.23 src/share/man/man9/veriexec.9
cvs diff -r1.22 -r1.23 src/share/man/man9/veriexec.9 (expand / switch to unified diff)

--- src/share/man/man9/veriexec.9 2009/05/13 22:43:58 1.22
+++ src/share/man/man9/veriexec.9 2010/04/13 07:14:45 1.23
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: veriexec.9,v 1.22 2009/05/13 22:43:58 wiz Exp $ 1.\" $NetBSD: veriexec.9,v 1.23 2010/04/13 07:14:45 jruoho Exp $
2.\" 2.\"
3.\" Copyright 2006 Elad Efrat <elad@NetBSD.org> 3.\" Copyright 2006 Elad Efrat <elad@NetBSD.org>
4.\" Copyright 2006 Brett Lymn <blymn@NetBSD.org> 4.\" Copyright 2006 Brett Lymn <blymn@NetBSD.org>
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Brett Lymn and Elad Efrat 7.\" by Brett Lymn and Elad Efrat
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Neither the name of The NetBSD Foundation nor the names of its 14.\" 2. Neither the name of The NetBSD Foundation nor the names of its
@@ -25,58 +25,95 @@ @@ -25,58 +25,95 @@
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 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 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd February 10, 2008 30.Dd February 10, 2008
31.Dt VERIEXEC 9 31.Dt VERIEXEC 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm veriexec 34.Nm veriexec
35.Nd in-kernel file integrity subsystem KPI 35.Nd in-kernel file integrity subsystem KPI
36.Sh SYNOPSIS 36.Sh SYNOPSIS
37.In sys/verified_exec.h 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"
38.Sh DESCRIPTION 74.Sh DESCRIPTION
39.Nm 75.Nm
40is the KPI for 76is the
 77.Tn KPI
 78for
41.Em Veriexec , 79.Em Veriexec ,
42the 80the
43.Nx 81.Nx
44in-kernel file integrity subsystem. 82in-kernel file integrity subsystem.
45It is responsible for managing the supported hashing algorithms, fingerprint 83It is responsible for managing the supported hashing algorithms, fingerprint
46calculation and comparison, file monitoring tables, and relevant hooks to 84calculation and comparison, file monitoring tables, and relevant hooks to
47enforce the 85enforce the
48.Em Veriexec 86.Em Veriexec
49policy. 87policy.
 88.Sh FUNCTIONS
50.Ss Core Routines 89.Ss Core Routines
51.Bl -tag -width compact 90.Bl -tag -width compact
52.It Ft void Fn veriexec_init "void" 91.It Fn veriexec_init "void"
53Initialize the 92Initialize the
54.Em Veriexec 93.Em Veriexec
55subsystem. 94subsystem.
56Called only once during system startup. 95Called only once during system startup.
57.It Ft "bool" Fn veriexec_lookup "struct vnode *vp" 96.It Fn veriexec_lookup "vp"
58Check if 97Check if
59.Ar vp 98.Ar vp
60is monitored by 99is monitored by
61.Em Veriexec 100.Em Veriexec .
62or not. 
63Returns 101Returns
64.Dv true 102.Dv true
65if it is, or 103if it is, or
66.Dv false 104.Dv false
67otherwise. 105otherwise.
68.It Ft int Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \ 106.It Fn veriexec_verify "l" "vp" "name" "flag" "found"
69"const u_char *name" "int flag" "bool *found" 
70Verifies the digital fingerprint of 107Verifies the digital fingerprint of
71.Ar vp . 108.Ar vp .
72.Ar name 109.Ar name
73is the filename, and 110is the filename, and
74.Ar flag 111.Ar flag
75is the access flag. 112is the access flag.
76The access flag can be one of: 113The access flag can be one of:
77.Bl -tag -width VERIEXEC_INDIRECT 114.Bl -tag -width VERIEXEC_INDIRECT
78.It Dv VERIEXEC_DIRECT 115.It Dv VERIEXEC_DIRECT
79The file was executed directly via 116The file was executed directly via
80.Xr execve 2 . 117.Xr execve 2 .
81.It Dv VERIEXEC_INDIRECT 118.It Dv VERIEXEC_INDIRECT
82The file was executed indirectly, either as an interpreter for a script or 119The file was executed indirectly, either as an interpreter for a script or
@@ -84,144 +121,139 @@ mapped to an executable memory region. @@ -84,144 +121,139 @@ mapped to an executable memory region.
84.It Dv VERIEXEC_FILE 121.It Dv VERIEXEC_FILE
85The file was opened for reading/writing. 122The file was opened for reading/writing.
86.El 123.El
87.Pp 124.Pp
88.Ar l 125.Ar l
89is the LWP for the request context. 126is the LWP for the request context.
90.Pp 127.Pp
91An optional argument, 128An optional argument,
92.Ar found , 129.Ar found ,
93is a pointer to a boolean indicating whether an entry for the file was found 130is a pointer to a boolean indicating whether an entry for the file was found
94in the 131in the
95.Em Veriexec 132.Em Veriexec
96tables. 133tables.
97.It Ft void Fn veriexec_purge "struct vnode *vp" 134.It Fn veriexec_purge "vp"
98Purge the file entry for 135Purge the file entry for
99.Ar vp . 136.Ar vp .
100This invalidates the fingerprint so it will be evaluated next time the file 137This invalidates the fingerprint so it will be evaluated next time the file
101is accessed. 138is accessed.
102.\" veriexec_page_verify() intentionally not documented. 139.\" veriexec_page_verify() intentionally not documented.
103.El 140.El
104.Ss Fingerprint Related Routines 141.Ss Fingerprint Related Routines
105.Bl -tag -width compact 142.Bl -tag -width compact
106.It Ft int Fn veriexec_fpops_add "const char *fp_type" "size_t hash_len" \ 143.It Fn veriexec_fpops_add "fp_type" "hash_len" "ctx_size" \
107"size_t ctx_size" "veriexec_fpop_init_t init" "veriexec_fpop_update_t update" \ 144"init" "update" "final"
108"veriexec_fpop_final_t final" 
109Add support for fingerprinting algorithm 145Add support for fingerprinting algorithm
110.Ar fp_type 146.Ar fp_type
111with binary hash length 147with binary hash length
112.Ar hash_len 148.Ar hash_len
113and calculation context size 149and calculation context size
114.Ar ctx_size 150.Ar ctx_size
115to 151to
116.Em Veriexec . 152.Em Veriexec .
117.Ar init , 153.Ar init ,
118.Ar update , 154.Ar update ,
119and 155and
120.Ar final 156.Ar final
121are the routines used to initialize, update, and finalize a calculation 157are the routines used to initialize, update, and finalize a calculation
122context. 158context.
123.El 159.El
124.Ss Table Management Routines 160.Ss Table Management Routines
125.Bl -tag -width compact 161.Bl -tag -width compact
126.It Ft int Fn veriexec_file_add "struct lwp *l" \ 162.It Fn veriexec_file_add "l" "dict"
127"prop_dictionary_t dict" 
128Add a 163Add a
129.Em Veriexec 164.Em Veriexec
130entry for the file described by 165entry for the file described by
131.Ar dict . 166.Ar dict .
132.Pp 167.Pp
133.Ar dict 168.Ar dict
134is expected to have the following: 169is expected to have the following:
135.Bl -column entry-type string "entry type flags (see veriexec(4))" 170.Bl -column entry-type string "entry type flags (see veriexec(4))"
136.It Sy Name Type Purpose 171.It Sy Name Type Purpose
137.It file string filename 172.It file string filename
138.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) 173.It entry-type uint8 entry type flags ( see Xr veriexec 4 )
139.It fp-type string fingerprint hashing algorithm 174.It fp-type string fingerprint hashing algorithm
140.It fp data the fingerprint 175.It fp data the fingerprint
141.El 176.El
142.It Ft int Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp" 177.It Fn veriexec_file_delete "l" "vp"
143Remove 178Remove
144.Em Veriexec 179.Em Veriexec
145entry for 180entry for
146.Ar vp . 181.Ar vp .
147.It Ft int Fn veriexec_table_delete "struct lwp *l" "struct mount *mp" 182.It Fn veriexec_table_delete "l" "mp"
148Remove 183Remove
149.Em Veriexec 184.Em Veriexec
150table for mount-point 185table for mount-point
151.Ar mp . 186.Ar mp .
152.It Ft int Fn veriexec_flush "struct lwp *l" 187.It Fn veriexec_flush "l"
153Delete all 188Delete all
154.Em Veriexec 189.Em Veriexec
155tables. 190tables.
156.El 191.El
157.Ss Hook Handlers 192.Ss Hook Handlers
158.Bl -tag -width compact 193.Bl -tag -width compact
159.It Ft int Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \ 194.It Fn veriexec_openchk "l" "vp" "path" "fmode"
160"const char *path" "int fmode" 
161Called when a file is opened. 195Called when a file is opened.
162.Pp 196.Pp
163.Ar l 197.Ar l
164is the LWP opening the file, 198is the LWP opening the file,
165.Ar vp 199.Ar vp
166is a vnode for the file being opened as returned from 200is a vnode for the file being opened as returned from
167.Xr namei 9 . 201.Xr namei 9 .
168If 202If
169.Dv NULL , 203.Dv NULL ,
170the file is being created. 204the file is being created.
171.Ar path 205.Ar path
172is the pathname for the file (not necessarily a full path), and 206is the pathname for the file (not necessarily a full path), and
173.Ar fmode 207.Ar fmode
174are the mode bits with which the file was opened. 208are the mode bits with which the file was opened.
175.It Ft int Fn veriexec_renamechk "struct lwp *l" "struct vnode *fromvp" \ 209.It Fn veriexec_renamechk "l" "fromvp" "fromname" "tovp" "toname"
176"const char *fromname" "struct vnode *tovp" "const char *toname" 
177Called when a file is renamed. 210Called when a file is renamed.
178.Pp 211.Pp
179.Ar fromvp 212.Ar fromvp
180and 213and
181.Ar fromname 214.Ar fromname
182are the vnode and filename of the file being renamed. 215are the vnode and filename of the file being renamed.
183.Ar tovp 216.Ar tovp
184and 217and
185.Ar toname 218.Ar toname
186are the vnode and filename of the target file. 219are the vnode and filename of the target file.
187.Ar l 220.Ar l
188is the LWP renaming the file. 221is the LWP renaming the file.
189.Pp 222.Pp
190Depending on the strict level, 223Depending on the strict level,
191.Nm 224.Nm
192will either track changes appropriately or prevent the rename. 225will either track changes appropriately or prevent the rename.
193.It Ft int Fn veriexec_removechk "struct lwp *l" "struct vnode *vp" \ 226.It Fn veriexec_removechk "l" "vp" "name"
194"const char *name" 
195Called when a file is removed. 227Called when a file is removed.
196.Pp 228.Pp
197.Ar vp 229.Ar vp
198is the vnode of the file being removed, and 230is the vnode of the file being removed, and
199.Ar name 231.Ar name
200is the filename. 232is the filename.
201.Ar l 233.Ar l
202is the LWP removing the file, 234is the LWP removing the file,
203.Pp 235.Pp
204Depending on the strict level, 236Depending on the strict level,
205.Nm 237.Nm
206will either clean-up after the file or prevent its removal. 238will either clean-up after the file or prevent its removal.
207.It Ft int Fn veriexec_unmountchk "struct mount *mp" 239.It Fn veriexec_unmountchk "mp"
208Checks if the current strict level allows 240Checks if the current strict level allows
209.Ar mp 241.Ar mp
210to be unmounted. 242to be unmounted.
211.El 243.El
212.Ss Miscellaneous Routines 244.Ss Miscellaneous Routines
213.Bl -tag -width compact 245.Bl -tag -width compact
214.It Ft int Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict" 246.It Fn veriexec_convert "vp" "rdict"
215Convert 247Convert
216.Em Veriexec 248.Em Veriexec
217entry for 249entry for
218.Ar vp 250.Ar vp
219to human-readable 251to human-readable
220.Xr proplib 3 252.Xr proplib 3
221dictionary, 253dictionary,
222.Ar rdict , 254.Ar rdict ,
223with the following elements: 255with the following elements:
224.Bl -column entryxtype string 256.Bl -column entryxtype string
225.It Sy Name Type Purpose 257.It Sy Name Type Purpose
226.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) 258.It entry-type uint8 entry type flags ( see Xr veriexec 4 )
227.It status uint8 entry status ( see below ) 259.It status uint8 entry status ( see below )
@@ -233,27 +265,27 @@ The @@ -233,27 +265,27 @@ The
233.Dq status 265.Dq status
234can be one of the following: 266can be one of the following:
235.Bl -column fingerprintxmismatch effect 267.Bl -column fingerprintxmismatch effect
236.It Sy Status Meaning 268.It Sy Status Meaning
237.It FINGERPRINT_NOTEVAL not evaluated 269.It FINGERPRINT_NOTEVAL not evaluated
238.It FINGERPRINT_VALID fingerprint match 270.It FINGERPRINT_VALID fingerprint match
239.It FINGERPRINT_MISMATCH fingerprint mismatch 271.It FINGERPRINT_MISMATCH fingerprint mismatch
240.El 272.El
241.Pp 273.Pp
242If no entry was found, 274If no entry was found,
243.Er ENOENT 275.Er ENOENT
244is returned. 276is returned.
245Otherwise, zero. 277Otherwise, zero.
246.It Ft int Fn veriexec_dump "struct lwp *l" "prop_array_t rarray" 278.It Fn veriexec_dump "l" "rarray"
247Fill 279Fill
248.Ar rarray 280.Ar rarray
249with entries for all files monitored by 281with entries for all files monitored by
250.Em Veriexec 282.Em Veriexec
251that have a filename associated with them. 283that have a filename associated with them.
252.Pp 284.Pp
253Each element in 285Each element in
254.Ar rarray 286.Ar rarray
255is a dictionary with the same elements as filled by 287is a dictionary with the same elements as filled by
256.Fn veriexec_convert , 288.Fn veriexec_convert ,
257with an additional field, 289with an additional field,
258.Dq file , 290.Dq file ,
259containing the filename. 291containing the filename.