Release 1.2.4.

[checkpath] / checkpath.3

diff --git a/checkpath.3 b/checkpath.3
index 8bc8faf..921dec7 100644 (file)
--- a/checkpath.3
+++ b/checkpath.3
@@ -8,6 +8,10 @@ checkpath \- library for examining path security
 
 .BI "int checkpath(const char *" path ,
 .BI "              const struct checkpath *" cp ");"
 
 .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
 .BI "void checkpath_setids(struct checkpath *" cp ");"
 .fi
 .SH DESCRIPTION


@@ -17,7 +21,7 @@ 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
 users and groups can change the files or file contents accessible
 through the path.
 .PP

-The function is given a 
+The function is given a

 .I path
 to be checked, and a pointer
 .I cp
 .I path
 to be checked, and a pointer
 .I cp


@@ -30,7 +34,7 @@ of the problems.
 This structure contains the following members:
 .TP
 .B "uid_t cp_uid"
 This structure contains the following members:
 .TP
 .B "uid_t cp_uid"

-The user running the check.  Files and directories owned by 
+The user running the check.  Files and directories owned by

 .B root
 (uid 0) and by
 .B cp_uid
 .B root
 (uid 0) and by
 .B cp_uid


@@ -38,7 +42,7 @@ 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
 .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 
+this set may be considered safe, depending on the

 .B cp_what
 configuration.  See below.
 .TP
 .B cp_what
 configuration.  See below.
 .TP


@@ -46,7 +50,7 @@ configuration.  See below.
 The number of gids in the
 .B cp_gid
 array.
 The number of gids in the
 .B cp_gid
 array.

-.TP 
+.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
 .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


@@ -57,7 +61,7 @@ levels 2 and above.  The recommended value is 1.
 .B "unsigned cp_what"
 A bitmask of flags determining what conditions are considered problems,
 and other behaviour.  See below.
 .B "unsigned cp_what"
 A bitmask of flags determining what conditions are considered problems,
 and other behaviour.  See below.

-.TP 
+.TP

 .B "void (*cp_report)(...)"
 The reporting function.  See below.
 .TP
 .B "void (*cp_report)(...)"
 The reporting function.  See below.
 .TP


@@ -73,7 +77,38 @@ and
 can be set up to reflect the current user and group memberships by
 calling
 .B checkpath_setids
 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.
+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
 .SS "The cp_what flags"
 The
 .B cp_what