| 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 "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 ");" |
| 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 |
| 24 | The function is given a |
| 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" |
| 37 | The user running the check. Files and directories owned by |
| 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 |
| 45 | this set may be considered safe, depending on the |
| 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. |
| 53 | .TP |
| 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. |
| 64 | .TP |
| 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 |
| 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. |
| 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). |