6700cfccd6
Bug fixes:
- Fix crash reported by Scott Ellis on current-users@.
- Fix race conditions in enforcing the Veriexec rename and remove
policies. These are NOT security issues.
- Fix memory leak in rename handling when overwriting a monitored
file.
- Fix table deletion logic.
- Don't prevent query requests if not in learning mode.
KPI updates:
- fileassoc_table_run() now takes a cookie to pass to the callback.
- veriexec_table_add() was removed, it is now done internally. As a
result, there's no longer a need for VERIEXEC_TABLESIZE.
- veriexec_report() was removed, it is now internal.
- Perform sanity checks on the entry type, and enforce default type
in veriexec_file_add() rather than in veriexecctl.
- Add veriexec_flush(), used to delete all Veriexec tables, and
veriexec_dump(), used to fill an array with all Veriexec entries.
New features:
- Add a '-k' flag to veriexecctl, to keep the filenames in the kernel
database. This allows Veriexec to produce slightly more accurate
logs under certain circumstances. In the future, this can be either
replaced by vnode->pathname translation, or combined with it.
- Add a VERIEXEC_DUMP ioctl, to dump the entire Veriexec database.
This can be used to recover a database if the file was lost.
Example usage:
# veriexecctl dump > /etc/signatures
Note that only entries with the filename kept (that is, were loaded
with the '-k' flag) will be dumped.
Idea from Brett Lymn.
- Add a VERIEXEC_FLUSH ioctl, to delete all Veriexec entries. Sample
usage:
# veriexecctl flush
- Add a 'veriexec_flags' rc(8) variable, and make its default have
the '-k' flag. On systems using the default signatures file
(generaetd from running 'veriexecgen' with no arguments), this will
use additional 32kb of kernel memory on average.
- Add a '-e' flag to veriexecctl, to evaluate the fingerprint during
load. This is done automatically for files marked as 'untrusted'.
Misc. stuff:
- The code for veriexecctl was massively simplified as a result of
eliminating the need for VERIEXEC_TABLESIZE, and now uses a single
pass of the signatures file, making the loading somewhat faster.
- Lots of minor fixes found using the (still under development)
Veriexec regression testsuite.
- Some of the messages Veriexec prints were improved.
- Various documentation fixes.
All relevant man-pages were updated to reflect the above changes.
Binary compatibility with existing veriexecctl binaries is maintained.
324 lines
8.5 KiB
Groff
324 lines
8.5 KiB
Groff
.\" $NetBSD: fileassoc.9,v 1.20 2007/05/15 19:47:43 elad Exp $
|
|
.\"
|
|
.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 May 15, 2007
|
|
.Dt FILEASSOC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fileassoc
|
|
.Nd in-kernel, file-system independent, file-meta data association
|
|
.Sh SYNOPSIS
|
|
.In sys/fileassoc.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
KPI allows association of meta-data with files independent of file-system
|
|
support for such elaborate meta-data.
|
|
.Pp
|
|
When plugging a new fileassoc to the system, a developer can specify private
|
|
data to be associated with every file, as well as (potentially different)
|
|
private data to be associated with every file-system mount.
|
|
.Pp
|
|
For example, a developer might choose to associate a custom ACL with every
|
|
file, and a count of total files with ACLs with the mount.
|
|
.Ss Kernel Programming Interface
|
|
Designed with simplicity in mind, the
|
|
.Nm
|
|
KPI usually accepts four different types of parameters to the most commonly
|
|
used routines:
|
|
.Bl -tag -width "123456"
|
|
.It Ft struct mount * Ar mp
|
|
Describing a mount on which to take action.
|
|
.It Ft struct vnode * Ar vp
|
|
Describing a file on which to take action.
|
|
.It Ft fileassoc_t Ar id
|
|
Describing an id, as returned from a successful call to
|
|
.Fn fileassoc_register .
|
|
.It Ft void * Ar data
|
|
Describing a custom private data block, attached to either a file or a mount.
|
|
.El
|
|
.Pp
|
|
Before using the
|
|
.Nm
|
|
KPI it is important to keep in mind that the interface provides memory
|
|
management only for
|
|
.Nm
|
|
internal memory.
|
|
Any additional memory stored in the tables (such as private data-structures
|
|
used by custom fileassocs) should be allocated and freed by the developer.
|
|
.Pp
|
|
.Nm
|
|
provides the ability to specify a
|
|
.Dq cleanup
|
|
routine to
|
|
.Fn fileassoc_register
|
|
(see below)
|
|
to be called whenever an entry for a file or a mount is deleted.
|
|
.Ss Fileassoc Registration and Deregistration Routines
|
|
These routines allow a developer to allocate a
|
|
.Nm
|
|
slot to be used for private data.
|
|
.Bl -tag -width "123456"
|
|
.It Ft int Fn fileassoc_register "const char *name" \
|
|
"fileassoc_cleanup_cb_t cleanup_cb" "fileassoc_t *result"
|
|
Registers a new fileassoc as
|
|
.Ar name ,
|
|
and returns a
|
|
.Ft fileassoc_t
|
|
via
|
|
.Fa result
|
|
to be used as identifier in subsequent calls to the
|
|
.Nm
|
|
subsystem.
|
|
.Pp
|
|
.Fn fileassoc_register
|
|
returns zero on success.
|
|
Otherwise, an error number will be returned.
|
|
.Pp
|
|
If
|
|
.Ar cleanup_cb
|
|
is not
|
|
.Dv NULL ,
|
|
it will be called during delete/clear operations (see routines below) with
|
|
indication whether the passed data is file- or mount-specific.
|
|
.Pp
|
|
.Ar cleanup_cb
|
|
should be a function receiving a
|
|
.Ft void *
|
|
and returning
|
|
.Ft void .
|
|
See the
|
|
.Sx EXAMPLES
|
|
section for illustration.
|
|
.Pp
|
|
.It Ft int Fn fileassoc_deregister "fileassoc_t id"
|
|
Deregisters a
|
|
.Nm fileassoc
|
|
whose id is
|
|
.Ar id .
|
|
.Pp
|
|
Note that calling
|
|
.Fn fileassoc_deregister
|
|
only frees the associated slot in the
|
|
.Nm
|
|
subsystem.
|
|
It is up to the developer to take care of garbage collection.
|
|
.El
|
|
.Ss Lookup Routines
|
|
These routines allow lookup of
|
|
.Nm
|
|
mounts, files, and private data attached to them.
|
|
.Bl -tag -width "123456"
|
|
.It Ft void * Fn fileassoc_lookup "struct vnode *vp" "fileassoc_t id"
|
|
Returns the private data for the file/id combination
|
|
or
|
|
.Dv NULL
|
|
if not found.
|
|
.El
|
|
.Ss Mount-wide Routines
|
|
.Bl -tag -width "123456"
|
|
.It Ft int Fn fileassoc_table_delete "struct mount *mp"
|
|
Deletes a fileassoc table for
|
|
.Ar mp .
|
|
.Pp
|
|
.It Ft int Fn fileassoc_table_clear "struct mount *mp" "fileassoc_t id"
|
|
Clear all table entries for
|
|
.Ar fileassoc
|
|
from
|
|
.Ar mp .
|
|
.Pp
|
|
If specified, the fileassoc's
|
|
.Dq cleanup routine
|
|
will be called with a pointer to the private data-structure.
|
|
.Pp
|
|
.It Ft int Fn fileassoc_table_run "struct mount *mp" "fileassoc_t id" \
|
|
"fileassoc_cb_t cb" "void *cookie"
|
|
For each entry for
|
|
.Ar id ,
|
|
call
|
|
.Ar cb
|
|
with the entry being the first argument, and
|
|
.Ar cookie
|
|
being the second argument.
|
|
.Pp
|
|
.Ar cb
|
|
is a function returning
|
|
.Ft void
|
|
and receiving one
|
|
.Ft "void *"
|
|
parameter.
|
|
.El
|
|
.Ss File-specific Routines
|
|
.Bl -tag -width "123456"
|
|
.It Ft int Fn fileassoc_file_delete "struct vnode *vp"
|
|
Delete the fileassoc entries for
|
|
.Ar vp .
|
|
.Pp
|
|
If specified, the
|
|
.Dq cleanup routines
|
|
of all fileassoc types added will be called with a pointer to the corresponding
|
|
private data structure and indication of
|
|
.Dv FILEASSOC_CLEANUP_FILE .
|
|
.El
|
|
.Ss Fileassoc-specific Routines
|
|
.Bl -tag -width "123456"
|
|
.It Ft int Fn fileassoc_add "struct vnode *vp" "fileassoc_t id" "void *data"
|
|
Add private data in
|
|
.Ar data
|
|
for
|
|
.Ar vp ,
|
|
for the fileassoc specified by
|
|
.Ar id .
|
|
.Pp
|
|
If a table for the mount-point
|
|
.Ar vp
|
|
is on doesn't exist, one will be created automatically.
|
|
.Nm
|
|
manages internally the optimal table sizes as tables are modified.
|
|
.It Ft int Fn fileassoc_clear "struct vnode *vp" "fileassoc_t id"
|
|
Clear the private data for
|
|
.Ar vp ,
|
|
for the fileassoc specified by
|
|
.Ar id .
|
|
.Pp
|
|
If specified, the fileassoc's
|
|
.Dq cleanup routine
|
|
will be called with a pointer to the private data-structure and indication of
|
|
.Dv FILEASSOC_CLEANUP_FILE .
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following code examples should give you a clue on using
|
|
.Nm
|
|
for your purposes.
|
|
.Pp
|
|
First, we'll begin with registering a new id.
|
|
We need to do that to save a slot for private data storage with each mount
|
|
and/or file:
|
|
.Bd -literal -offset indent
|
|
fileassoc_t myhook_id;
|
|
int error;
|
|
|
|
error = fileassoc_register("my_hook", myhook_cleanup, \*[Am]myhook_id);
|
|
if (error != 0)
|
|
...handle error...
|
|
.Ed
|
|
.Pp
|
|
In the above example we pass a
|
|
.Fn myhook_cleanup
|
|
routine.
|
|
It could look something like this:
|
|
.Bd -literal -offset indent
|
|
void
|
|
myhook_cleanup(void *data)
|
|
{
|
|
|
|
printf("Myhook: Removing entry for file.\n");
|
|
...handle file entry removal...
|
|
free(data, M_TEMP);
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Another useful thing would be to add our private data to a file.
|
|
For example, let's assume we keep a custom ACL with each file:
|
|
.Bd -literal -offset indent
|
|
int
|
|
myhook_acl_add(struct vnode *vp, struct myhook_acl *acl)
|
|
{
|
|
int error;
|
|
|
|
error = fileassoc_add(vp, myhook_id, acl);
|
|
if (error) {
|
|
printf("Myhook: Could not add ACL.\n");
|
|
...handle error...
|
|
}
|
|
|
|
printf("Myhook: Added ACL.\n");
|
|
|
|
return (0);
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Adding an entry will override any entry that previously exists.
|
|
.Pp
|
|
Whatever your plug is, eventually you'll want to access the private data you
|
|
store with each file.
|
|
To do that you can use the following:
|
|
.Bd -literal -offset indent
|
|
int
|
|
myhook_acl_access(struct vnode *vp, int access_flags)
|
|
{
|
|
struct myhook_acl *acl;
|
|
|
|
acl = fileassoc_lookup(vp, myhook_id);
|
|
if (acl == NULL)
|
|
return (0);
|
|
|
|
error = myhook_acl_eval(acl, access_flags);
|
|
if (error) {
|
|
printf("Myhook: Denying access based on ACL decision.\n");
|
|
return (error);
|
|
}
|
|
|
|
return (0);
|
|
}
|
|
.Ed
|
|
.Pp
|
|
And, in some cases, it may be desired to remove private data associated with
|
|
an file:
|
|
.Bd -literal -offset indent
|
|
int error;
|
|
|
|
error = fileassoc_clear(vp, myhook_id);
|
|
if (error) {
|
|
printf("Myhook: Error occured during fileassoc removal.\n");
|
|
...handle error...
|
|
}
|
|
.Ed
|
|
.Pp
|
|
As mentioned previously, the call to
|
|
.Fn fileassoc_clear
|
|
will result in a call to the
|
|
.Dq cleanup routine
|
|
specified in the initial call to
|
|
.Fn fileassoc_register .
|
|
.Pp
|
|
The above should be enough to get you started.
|
|
.Pp
|
|
For example usage of
|
|
.Nm ,
|
|
see the Veriexec code.
|
|
.Sh CODE REFERENCES
|
|
.Pa src/sys/kern/kern_fileassoc.c
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
KPI first appeared in
|
|
.Nx 4.0 .
|
|
.Sh AUTHORS
|
|
.An Elad Efrat Aq elad@NetBSD.org
|
|
.An Brett Lymn Aq blymn@NetBSD.org
|