2 .TH checkpath 3 "25 January 2003" "Local tools"
4 checkpath \- library for examining path security
7 .B "#include <checkpath.h>"
9 .BI "int checkpath(const char *" path ,
10 .BI " const struct checkpath *" cp ");"
11 .BI "void checkpath_setids(struct checkpath *" cp ");"
16 function checks a path for security. It ensures that only acceptble
17 users and groups can change the files or file contents accessible
20 The function is given a
22 to be checked, and a pointer
24 to a parameter block of type
25 .BR "struct checkpath" .
26 It scans the path and returns a bitmask of problems that it found. It
27 may also have invoked a caller-provided reporting function with details
29 .SS "The parameter structure"
30 This structure contains the following members:
33 The user running the check. Files and directories owned by
39 .B "gid_t cp_gid[NGROUPS_MAX + 1]"
40 The groups of which the user is a member. Files whose groups are in
41 this set may be considered safe, depending on the
43 configuration. See below.
46 The number of gids in the
51 The verbosity level. Messages are only given to the reporting function
52 if their verbosity level is less than or equal to this setting. As a
53 guide, unexpected errors (e.g., nonexistent files) have level 0,
54 security concerns about the path have level 1, and other details have
55 levels 2 and above. The recommended value is 1.
58 A bitmask of flags determining what conditions are considered problems,
59 and other behaviour. See below.
61 .B "void (*cp_report)(...)"
62 The reporting function. See below.
65 An argument to be passed to the reporting function
73 can be set up to reflect the current user and group memberships by
76 passing the address of the structure to fill in.
77 .SS "The cp_what flags"
83 Some kind of operating system error occurred while checking the path.
86 A path element is world writable.
89 A path element is group-writable.
92 A path element is group-writable, and its group is not listed in
96 A path element is owned by another user.
99 Report traversal of a symbolic link while checking the path.
102 Format a user-readable message string when reporting problems.
105 Don't complain if the object designated by the path is a sticky
106 directory, as long as the owner is trustworthy (i.e., either
110 This is useful when testing candidate temporary directories for
124 has only these bits set. A problem is reported (and returned) only if
125 its bit is set in the
127 structure member. Note that it's possible that a problem might fit into
128 multiple categories, e.g., a group-writable directory might be reported
133 in this case, the most specific problem is used (in this case
135 .SS "The reporting function"
136 The reporting function is passed the following arguments:
139 A flag inidicating the kind of notification this is. It will be a
144 The verbosity level of this message.
146 .BI "const char *" path
147 The full pathname of the object which caused this report to be issued.
148 The pathname will not contain symbolic links (except as the last
149 element, and then only if this is a
153 .BI "const char *" msg
154 A human-readable message describing this notification in detail. This
164 member of the parameter structure, provided as a context pointer for the
172 Mark Wooding (mdw@nsict.org).