Commit | Line | Data |
---|---|---|
d7b5ee0c | 1 | .\" -*-nroff-*- |
2 | .TH checkpath 3 "25 January 2003" "Local tools" | |
3 | .SH NAME | |
4 | checkpath \- library for examining path security | |
5 | .SH SYNOPSIS | |
6 | .nf | |
7 | .B "#include <checkpath.h>" | |
8 | ||
9 | .BI "int checkpath(const char *" path , | |
10 | .BI " const struct checkpath *" cp ");" | |
a2965015 MW |
11 | .BI "int checkpath_addgid(struct checkpath *" cp ", gid_t " g ");" |
12 | .BI "void checkpath_setuid(struct checkpath *" cp ");" | |
13 | .BI "int checkpath_setgid(struct checkpath *" cp ");" | |
14 | .BI "int checkpath_setgroups(struct checkpath *" cp ");" | |
d7b5ee0c | 15 | .BI "void checkpath_setids(struct checkpath *" cp ");" |
16 | .fi | |
17 | .SH DESCRIPTION | |
18 | The | |
19 | .B checkpath | |
20 | function checks a path for security. It ensures that only acceptble | |
21 | users and groups can change the files or file contents accessible | |
22 | through the path. | |
23 | .PP | |
263d6e0d | 24 | The function is given a |
d7b5ee0c | 25 | .I path |
26 | to be checked, and a pointer | |
27 | .I cp | |
28 | to a parameter block of type | |
29 | .BR "struct checkpath" . | |
30 | It scans the path and returns a bitmask of problems that it found. It | |
31 | may also have invoked a caller-provided reporting function with details | |
32 | of the problems. | |
33 | .SS "The parameter structure" | |
34 | This structure contains the following members: | |
35 | .TP | |
36 | .B "uid_t cp_uid" | |
263d6e0d | 37 | The user running the check. Files and directories owned by |
d7b5ee0c | 38 | .B root |
39 | (uid 0) and by | |
40 | .B cp_uid | |
41 | are considered safe. | |
42 | .TP | |
43 | .B "gid_t cp_gid[NGROUPS_MAX + 1]" | |
44 | The groups of which the user is a member. Files whose groups are in | |
263d6e0d | 45 | this set may be considered safe, depending on the |
d7b5ee0c | 46 | .B cp_what |
47 | configuration. See below. | |
48 | .TP | |
49 | .B "int cp_gids" | |
50 | The number of gids in the | |
51 | .B cp_gid | |
52 | array. | |
263d6e0d | 53 | .TP |
d7b5ee0c | 54 | .B "int cp_verbose" |
55 | The verbosity level. Messages are only given to the reporting function | |
56 | if their verbosity level is less than or equal to this setting. As a | |
57 | guide, unexpected errors (e.g., nonexistent files) have level 0, | |
58 | security concerns about the path have level 1, and other details have | |
59 | levels 2 and above. The recommended value is 1. | |
60 | .TP | |
61 | .B "unsigned cp_what" | |
62 | A bitmask of flags determining what conditions are considered problems, | |
63 | and other behaviour. See below. | |
263d6e0d | 64 | .TP |
d7b5ee0c | 65 | .B "void (*cp_report)(...)" |
66 | The reporting function. See below. | |
67 | .TP | |
68 | .B "void *cp_arg" | |
69 | An argument to be passed to the reporting function | |
70 | .BR cp_report . | |
71 | .PP | |
72 | The members | |
73 | .BR cp_uid , | |
74 | .B cp_gid | |
75 | and | |
76 | .B cp_gids | |
77 | can be set up to reflect the current user and group memberships by | |
78 | calling | |
79 | .B checkpath_setids | |
a2965015 MW |
80 | passing the address of the structure to fill in; this overwrites the |
81 | previous contents of the | |
82 | .BR cp_uid , | |
83 | .BR cp_gid , | |
84 | and | |
85 | .BR cp_gids | |
86 | members. Alternatively, the functions | |
87 | .BR checkpath_setuid , | |
88 | .BR checkpath_setgid , | |
89 | and | |
90 | .B checkpath_setgroups | |
91 | can be called to do the job in stages. The | |
92 | .B checkpath_setuid | |
93 | function simply stores the process's real uid in | |
94 | .BR cp_uid . | |
95 | The | |
96 | .B checkpath_setgid | |
97 | and | |
98 | .B checkpath_setgroups | |
99 | functions store respectively the process's real gid and supplementary | |
100 | gids in the | |
101 | .B cp_gid | |
102 | array; they avoid inserting duplicate entries; they return 0 on success | |
103 | or \-1 if the table would overflow; they assume that the table is | |
104 | properly set up (minimally, just set | |
105 | .BR "cp_gids = 0" ). | |
106 | They use a utility function | |
107 | .B checkpath_addgid | |
108 | to do their work; it takes a pointer to a | |
109 | .B struct checkpath | |
110 | and a gid, and again returns 0 on success or \-1 if overflow would | |
111 | occur. | |
d7b5ee0c | 112 | .SS "The cp_what flags" |
113 | The | |
114 | .B cp_what | |
115 | flags are as follows. | |
116 | .TP | |
117 | .B CP_ERROR | |
118 | Some kind of operating system error occurred while checking the path. | |
119 | .TP | |
120 | .B CP_WRWORLD | |
121 | A path element is world writable. | |
122 | .TP | |
123 | .B CP_WRGRP | |
124 | A path element is group-writable. | |
125 | .TP | |
126 | .B CP_WROTHGRP | |
127 | A path element is group-writable, and its group is not listed in | |
128 | .BR cp_gid . | |
129 | .TP | |
130 | .B CP_WROTHUSR | |
131 | A path element is owned by another user. | |
132 | .TP | |
133 | .B CP_SYMLINK | |
134 | Report traversal of a symbolic link while checking the path. | |
135 | .TP | |
136 | .B CP_REPORT | |
137 | Format a user-readable message string when reporting problems. | |
138 | .TP | |
139 | .B CP_STICKYOK | |
140 | Don't complain if the object designated by the path is a sticky | |
141 | directory, as long as the owner is trustworthy (i.e., either | |
142 | .B root | |
143 | or | |
144 | .BR cp_uid ). | |
145 | This is useful when testing candidate temporary directories for | |
146 | suitability. | |
147 | .PP | |
148 | The flags | |
149 | .BR CP_ERROR , | |
150 | .BR CP_WRWORLD , | |
151 | .BR CP_WRGRP , | |
152 | .BR CP_WROTHGRP , | |
153 | and | |
154 | .B CP_WROTHUSR | |
155 | are collectively the | |
156 | .I problem | |
157 | flags. The mask | |
158 | .B CP_PROBLEMS | |
159 | has only these bits set. A problem is reported (and returned) only if | |
160 | its bit is set in the | |
161 | .B cp_what | |
162 | structure member. Note that it's possible that a problem might fit into | |
163 | multiple categories, e.g., a group-writable directory might be reported | |
164 | as | |
165 | .B CP_WRGRP | |
166 | or | |
167 | .BR CP_WROTHGRP ; | |
168 | in this case, the most specific problem is used (in this case | |
169 | .BR CP_WROTHGRP ). | |
170 | .SS "The reporting function" | |
171 | The reporting function is passed the following arguments: | |
172 | .TP | |
173 | .BI "unsigned " what | |
174 | A flag inidicating the kind of notification this is. It will be a | |
175 | problem flag or | |
176 | .BR CP_SYMLINK . | |
177 | .TP | |
178 | .BI "int " verb | |
179 | The verbosity level of this message. | |
180 | .TP | |
181 | .BI "const char *" path | |
182 | The full pathname of the object which caused this report to be issued. | |
183 | The pathname will not contain symbolic links (except as the last | |
184 | element, and then only if this is a | |
185 | .B CP_SYMLINK | |
186 | notification). | |
187 | .TP | |
188 | .BI "const char *" msg | |
189 | A human-readable message describing this notification in detail. This | |
190 | is only generated if | |
191 | .B CP_REPORT | |
192 | is set in the | |
193 | .B cp_what | |
194 | flags. | |
195 | .TP | |
196 | .BI "void *" p | |
197 | The | |
198 | .B cp_arg | |
199 | member of the parameter structure, provided as a context pointer for the | |
200 | reporting function. | |
201 | .SH BUGS | |
202 | None known. | |
203 | .SH SEE ALSO | |
204 | .BR chkpath (1), | |
205 | .BR tmpdir (1). | |
206 | .SH AUTHOR | |
207 | Mark Wooding (mdw@nsict.org). |