Release 1.2.3.

[checkpath] / checkpath.3

.\" -*-nroff-*-
.TH checkpath 3 "25 January 2003" "Local tools"
.SH NAME
checkpath \- library for examining path security
.SH SYNOPSIS
.nf
.B "#include <checkpath.h>"

.BI "int checkpath(const char *" path ,
.BI "              const struct checkpath *" cp ");"
.BI "int checkpath_addgid(struct checkpath *" cp ", gid_t " g ");"
.BI "void checkpath_setuid(struct checkpath *" cp ");"
.BI "int checkpath_setgid(struct checkpath *" cp ");"
.BI "int checkpath_setgroups(struct checkpath *" cp ");"
.BI "void checkpath_setids(struct checkpath *" cp ");"
.fi
.SH DESCRIPTION
The
.B checkpath
function checks a path for security.  It ensures that only acceptble
users and groups can change the files or file contents accessible
through the path.
.PP
The function is given a
.I path
to be checked, and a pointer
.I cp
to a parameter block of type
.BR "struct checkpath" .
It scans the path and returns a bitmask of problems that it found.  It
may also have invoked a caller-provided reporting function with details
of the problems.
.SS "The parameter structure"
This structure contains the following members:
.TP
.B "uid_t cp_uid"
The user running the check.  Files and directories owned by
.B root
(uid 0) and by
.B cp_uid
are considered safe.
.TP
.B "gid_t cp_gid[NGROUPS_MAX + 1]"
The groups of which the user is a member.  Files whose groups are in
this set may be considered safe, depending on the
.B cp_what
configuration.  See below.
.TP
.B "int cp_gids"
The number of gids in the
.B cp_gid
array.
.TP
.B "int cp_verbose"
The verbosity level.  Messages are only given to the reporting function
if their verbosity level is less than or equal to this setting.  As a
guide, unexpected errors (e.g., nonexistent files) have level 0,
security concerns about the path have level 1, and other details have
levels 2 and above.  The recommended value is 1.
.TP
.B "unsigned cp_what"
A bitmask of flags determining what conditions are considered problems,
and other behaviour.  See below.
.TP
.B "void (*cp_report)(...)"
The reporting function.  See below.
.TP
.B "void *cp_arg"
An argument to be passed to the reporting function
.BR cp_report .
.PP
The members
.BR cp_uid ,
.B cp_gid
and
.B cp_gids
can be set up to reflect the current user and group memberships by
calling
.B checkpath_setids
passing the address of the structure to fill in; this overwrites the
previous contents of the
.BR cp_uid ,
.BR cp_gid ,
and
.BR cp_gids
members.  Alternatively, the functions
.BR checkpath_setuid ,
.BR checkpath_setgid ,
and
.B checkpath_setgroups
can be called to do the job in stages.  The
.B checkpath_setuid
function simply stores the process's real uid in
.BR cp_uid .
The
.B checkpath_setgid
and
.B checkpath_setgroups
functions store respectively the process's real gid and supplementary
gids in the
.B cp_gid
array; they avoid inserting duplicate entries; they return 0 on success
or \-1 if the table would overflow; they assume that the table is
properly set up (minimally, just set
.BR "cp_gids = 0" ).
They use a utility function
.B checkpath_addgid
to do their work; it takes a pointer to a
.B struct checkpath
and a gid, and again returns 0 on success or \-1 if overflow would
occur.
.SS "The cp_what flags"
The
.B cp_what
flags are as follows.
.TP
.B CP_ERROR
Some kind of operating system error occurred while checking the path.
.TP
.B CP_WRWORLD
A path element is world writable.
.TP
.B CP_WRGRP
A path element is group-writable.
.TP
.B CP_WROTHGRP
A path element is group-writable, and its group is not listed in
.BR cp_gid .
.TP
.B CP_WROTHUSR
A path element is owned by another user.
.TP
.B CP_SYMLINK
Report traversal of a symbolic link while checking the path.
.TP
.B CP_REPORT
Format a user-readable message string when reporting problems.
.TP
.B CP_STICKYOK
Don't complain if the object designated by the path is a sticky
directory, as long as the owner is trustworthy (i.e., either
.B root
or
.BR cp_uid ).
This is useful when testing candidate temporary directories for
suitability.
.PP
The flags
.BR CP_ERROR ,
.BR CP_WRWORLD ,
.BR CP_WRGRP ,
.BR CP_WROTHGRP ,
and
.B CP_WROTHUSR
are collectively the
.I problem
flags.  The mask
.B CP_PROBLEMS
has only these bits set.  A problem is reported (and returned) only if
its bit is set in the
.B cp_what
structure member.  Note that it's possible that a problem might fit into
multiple categories, e.g., a group-writable directory might be reported
as
.B CP_WRGRP
or
.BR CP_WROTHGRP ;
in this case, the most specific problem is used (in this case
.BR CP_WROTHGRP ).
.SS "The reporting function"
The reporting function is passed the following arguments:
.TP
.BI "unsigned " what
A flag inidicating the kind of notification this is.  It will be a
problem flag or
.BR CP_SYMLINK .
.TP
.BI "int " verb
The verbosity level of this message.
.TP
.BI "const char *" path
The full pathname of the object which caused this report to be issued.
The pathname will not contain symbolic links (except as the last
element, and then only if this is a
.B CP_SYMLINK
notification).
.TP
.BI "const char *" msg
A human-readable message describing this notification in detail.  This
is only generated if
.B CP_REPORT
is set in the
.B cp_what
flags.
.TP
.BI "void *" p
The
.B cp_arg
member of the parameter structure, provided as a context pointer for the
reporting function.
.SH BUGS
None known.
.SH SEE ALSO
.BR chkpath (1),
.BR tmpdir (1).
.SH AUTHOR
Mark Wooding (mdw@nsict.org).