[src/uebayasi-xip]: src/share/man/man9 Bump date for previous.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a451f4bb1a70
branches:  uebayasi-xip
changeset: 751656:a451f4bb1a70
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Apr 13 07:16:32 2010 +0000

description:
Bump date for previous.

diffstat:

 share/man/man9/veriexec.9 |  346 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 346 insertions(+), 0 deletions(-)

diffs (truncated from 350 to 300 lines):

diff -r eb431817ecc6 -r a451f4bb1a70 share/man/man9/veriexec.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/veriexec.9 Tue Apr 13 07:16:32 2010 +0000
@@ -0,0 +1,346 @@
+.\" $NetBSD: veriexec.9,v 1.24.2.2 2010/04/13 07:16:32 jruoho Exp $
+.\"
+.\" Copyright 2006 Elad Efrat <elad%NetBSD.org@localhost>
+.\" Copyright 2006 Brett Lymn <blymn%NetBSD.org@localhost>
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Brett Lymn and Elad Efrat
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 13, 2010
+.Dt VERIEXEC 9
+.Os
+.Sh NAME
+.Nm veriexec
+.Nd in-kernel file integrity subsystem KPI
+.Sh SYNOPSIS
+.In sys/verified_exec.h
+.Ft void
+.Fn veriexec_init "void"
+.Ft bool
+.Fn veriexec_lookup "struct vnode *vp"
+.Ft int
+.Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \
+"const u_char *name" "int flag" "bool *found"
+.Ft void
+.Fn veriexec_purge "struct vnode *vp"
+.Ft int
+.Fn 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"
+.Ft int
+.Fn veriexec_file_add "struct lwp *l" "prop_dictionary_t dict"
+.Ft int
+.Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp"
+.Ft int
+.Fn veriexec_table_delete "struct lwp *l" "struct mount *mp"
+.Ft int
+.Fn veriexec_flush "struct lwp *l"
+.Ft int
+.Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \
+"const char *path" "int fmode"
+.Ft int
+.Fn veriexec_renamechk "struct lwp *l" "struct vnode *fromvp" \
+"const char *fromname" "struct vnode *tovp" "const char *toname"
+.Ft int
+.Fn veriexec_removechk "struct lwp *l" "struct vnode *vp" \
+"const char *name"
+.Ft int
+.Fn veriexec_unmountchk "struct mount *mp"
+.Ft int
+.Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict"
+.Ft int
+.Fn veriexec_dump "struct lwp *l" "prop_array_t rarray"
+.Sh DESCRIPTION
+.Nm
+is the
+.Tn KPI
+for
+.Em Veriexec ,
+the
+.Nx
+in-kernel file integrity subsystem.
+It is responsible for managing the supported hashing algorithms, fingerprint
+calculation and comparison, file monitoring tables, and relevant hooks to
+enforce the
+.Em Veriexec
+policy.
+.Sh FUNCTIONS
+.Ss Core Routines
+.Bl -tag -width compact
+.It Fn veriexec_init "void"
+Initialize the
+.Em Veriexec
+subsystem.
+Called only once during system startup.
+.It Fn veriexec_lookup "vp"
+Check if
+.Ar vp
+is monitored by
+.Em Veriexec .
+Returns
+.Dv true
+if it is, or
+.Dv false
+otherwise.
+.It Fn veriexec_verify "l" "vp" "name" "flag" "found"
+Verifies the digital fingerprint of
+.Ar vp .
+.Ar name
+is the filename, and
+.Ar flag
+is the access flag.
+The access flag can be one of:
+.Bl -tag -width VERIEXEC_INDIRECT
+.It Dv VERIEXEC_DIRECT
+The file was executed directly via
+.Xr execve 2 .
+.It Dv VERIEXEC_INDIRECT
+The file was executed indirectly, either as an interpreter for a script or
+mapped to an executable memory region.
+.It Dv VERIEXEC_FILE
+The file was opened for reading/writing.
+.El
+.Pp
+.Ar l
+is the LWP for the request context.
+.Pp
+An optional argument,
+.Ar found ,
+is a pointer to a boolean indicating whether an entry for the file was found
+in the
+.Em Veriexec
+tables.
+.It Fn veriexec_purge "vp"
+Purge the file entry for
+.Ar vp .
+This invalidates the fingerprint so it will be evaluated next time the file
+is accessed.
+.\" veriexec_page_verify() intentionally not documented.
+.El
+.Ss Fingerprint Related Routines
+.Bl -tag -width compact
+.It Fn veriexec_fpops_add "fp_type" "hash_len" "ctx_size" \
+"init" "update" "final"
+Add support for fingerprinting algorithm
+.Ar fp_type
+with binary hash length
+.Ar hash_len
+and calculation context size
+.Ar ctx_size
+to
+.Em Veriexec .
+.Ar init ,
+.Ar update ,
+and
+.Ar final
+are the routines used to initialize, update, and finalize a calculation
+context.
+.El
+.Ss Table Management Routines
+.Bl -tag -width compact
+.It Fn veriexec_file_add "l" "dict"
+Add a
+.Em Veriexec
+entry for the file described by
+.Ar dict .
+.Pp
+.Ar dict
+is expected to have the following:
+.Bl -column entry-type string "entry type flags (see veriexec(4))"
+.It Sy Name    Type    Purpose
+.It file       string  filename
+.It entry-type uint8   entry type flags ( see Xr veriexec 4 )
+.It fp-type    string  fingerprint hashing algorithm
+.It fp data    the fingerprint
+.El
+.It Fn veriexec_file_delete "l" "vp"
+Remove
+.Em Veriexec
+entry for
+.Ar vp .
+.It Fn veriexec_table_delete "l" "mp"
+Remove
+.Em Veriexec
+table for mount-point
+.Ar mp .
+.It Fn veriexec_flush "l"
+Delete all
+.Em Veriexec
+tables.
+.El
+.Ss Hook Handlers
+.Bl -tag -width compact
+.It Fn veriexec_openchk "l" "vp" "path" "fmode"
+Called when a file is opened.
+.Pp
+.Ar l
+is the LWP opening the file,
+.Ar vp
+is a vnode for the file being opened as returned from
+.Xr namei 9 .
+If
+.Dv NULL ,
+the file is being created.
+.Ar path
+is the pathname for the file (not necessarily a full path), and
+.Ar fmode
+are the mode bits with which the file was opened.
+.It Fn veriexec_renamechk "l" "fromvp" "fromname" "tovp" "toname"
+Called when a file is renamed.
+.Pp
+.Ar fromvp
+and
+.Ar fromname
+are the vnode and filename of the file being renamed.
+.Ar tovp
+and
+.Ar toname
+are the vnode and filename of the target file.
+.Ar l
+is the LWP renaming the file.
+.Pp
+Depending on the strict level,
+.Nm
+will either track changes appropriately or prevent the rename.
+.It Fn veriexec_removechk "l" "vp" "name"
+Called when a file is removed.
+.Pp
+.Ar vp
+is the vnode of the file being removed, and
+.Ar name
+is the filename.
+.Ar l
+is the LWP removing the file,
+.Pp
+Depending on the strict level,
+.Nm
+will either clean-up after the file or prevent its removal.
+.It Fn veriexec_unmountchk "mp"
+Checks if the current strict level allows
+.Ar mp
+to be unmounted.
+.El
+.Ss Miscellaneous Routines
+.Bl -tag -width compact
+.It Fn veriexec_convert "vp" "rdict"
+Convert
+.Em Veriexec
+entry for
+.Ar vp
+to human-readable
+.Xr proplib 3
+dictionary,
+.Ar rdict ,
+with the following elements:
+.Bl -column entryxtype string
+.It Sy Name    Type    Purpose
+.It entry-type uint8   entry type flags ( see Xr veriexec 4 )
+.It status     uint8   entry status ( see below )
+.It fp-type    string  fingerprint hashing algorithm
+.It fp data    the fingerprint
+.El
+.Pp
+The
+.Dq status
+can be one of the following:
+.Bl -column fingerprintxmismatch effect
+.It Sy Status  Meaning
+.It FINGERPRINT_NOTEVAL        not evaluated
+.It FINGERPRINT_VALID  fingerprint match
+.It FINGERPRINT_MISMATCH       fingerprint mismatch
+.El
+.Pp
+If no entry was found,
+.Er ENOENT
+is returned.
+Otherwise, zero.
+.It Fn veriexec_dump "l" "rarray"
+Fill
+.Ar rarray
+with entries for all files monitored by
+.Em Veriexec
+that have a filename associated with them.
+.Pp
+Each element in
+.Ar rarray
+is a dictionary with the same elements as filled by
+.Fn veriexec_convert ,
+with an additional field,
+.Dq file ,
+containing the filename.
+.El
+.Sh FILES
+.Bl -column srcxsysxkernxkernxverifiedexecxc foo
+.It Sy Path    Purpose
+.It src/sys/dev/verified_exec.c        driver for userland communication