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 ");" |
11 | .BI "void checkpath_setids(struct checkpath *" cp ");" |
12 | .fi |
13 | .SH DESCRIPTION |
14 | The |
15 | .B checkpath |
16 | function checks a path for security. It ensures that only acceptble |
17 | users and groups can change the files or file contents accessible |
18 | through the path. |
19 | .PP |
20 | The function is given a |
21 | .I path |
22 | to be checked, and a pointer |
23 | .I cp |
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 |
28 | of the problems. |
29 | .SS "The parameter structure" |
30 | This structure contains the following members: |
31 | .TP |
32 | .B "uid_t cp_uid" |
33 | The user running the check. Files and directories owned by |
34 | .B root |
35 | (uid 0) and by |
36 | .B cp_uid |
37 | are considered safe. |
38 | .TP |
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 |
42 | .B cp_what |
43 | configuration. See below. |
44 | .TP |
45 | .B "int cp_gids" |
46 | The number of gids in the |
47 | .B cp_gid |
48 | array. |
49 | .TP |
50 | .B "int cp_verbose" |
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. |
56 | .TP |
57 | .B "unsigned cp_what" |
58 | A bitmask of flags determining what conditions are considered problems, |
59 | and other behaviour. See below. |
60 | .TP |
61 | .B "void (*cp_report)(...)" |
62 | The reporting function. See below. |
63 | .TP |
64 | .B "void *cp_arg" |
65 | An argument to be passed to the reporting function |
66 | .BR cp_report . |
67 | .PP |
68 | The members |
69 | .BR cp_uid , |
70 | .B cp_gid |
71 | and |
72 | .B cp_gids |
73 | can be set up to reflect the current user and group memberships by |
74 | calling |
75 | .B checkpath_setids |
76 | passing the address of the structure to fill in. |
77 | .SS "The cp_what flags" |
78 | The |
79 | .B cp_what |
80 | flags are as follows. |
81 | .TP |
82 | .B CP_ERROR |
83 | Some kind of operating system error occurred while checking the path. |
84 | .TP |
85 | .B CP_WRWORLD |
86 | A path element is world writable. |
87 | .TP |
88 | .B CP_WRGRP |
89 | A path element is group-writable. |
90 | .TP |
91 | .B CP_WROTHGRP |
92 | A path element is group-writable, and its group is not listed in |
93 | .BR cp_gid . |
94 | .TP |
95 | .B CP_WROTHUSR |
96 | A path element is owned by another user. |
97 | .TP |
98 | .B CP_SYMLINK |
99 | Report traversal of a symbolic link while checking the path. |
100 | .TP |
101 | .B CP_REPORT |
102 | Format a user-readable message string when reporting problems. |
103 | .TP |
104 | .B CP_STICKYOK |
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 |
107 | .B root |
108 | or |
109 | .BR cp_uid ). |
110 | This is useful when testing candidate temporary directories for |
111 | suitability. |
112 | .PP |
113 | The flags |
114 | .BR CP_ERROR , |
115 | .BR CP_WRWORLD , |
116 | .BR CP_WRGRP , |
117 | .BR CP_WROTHGRP , |
118 | and |
119 | .B CP_WROTHUSR |
120 | are collectively the |
121 | .I problem |
122 | flags. The mask |
123 | .B CP_PROBLEMS |
124 | has only these bits set. A problem is reported (and returned) only if |
125 | its bit is set in the |
126 | .B cp_what |
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 |
129 | as |
130 | .B CP_WRGRP |
131 | or |
132 | .BR CP_WROTHGRP ; |
133 | in this case, the most specific problem is used (in this case |
134 | .BR CP_WROTHGRP ). |
135 | .SS "The reporting function" |
136 | The reporting function is passed the following arguments: |
137 | .TP |
138 | .BI "unsigned " what |
139 | A flag inidicating the kind of notification this is. It will be a |
140 | problem flag or |
141 | .BR CP_SYMLINK . |
142 | .TP |
143 | .BI "int " verb |
144 | The verbosity level of this message. |
145 | .TP |
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 |
150 | .B CP_SYMLINK |
151 | notification). |
152 | .TP |
153 | .BI "const char *" msg |
154 | A human-readable message describing this notification in detail. This |
155 | is only generated if |
156 | .B CP_REPORT |
157 | is set in the |
158 | .B cp_what |
159 | flags. |
160 | .TP |
161 | .BI "void *" p |
162 | The |
163 | .B cp_arg |
164 | member of the parameter structure, provided as a context pointer for the |
165 | reporting function. |
166 | .SH BUGS |
167 | None known. |
168 | .SH SEE ALSO |
169 | .BR chkpath (1), |
170 | .BR tmpdir (1). |
171 | .SH AUTHOR |
172 | Mark Wooding (mdw@nsict.org). |