| 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). |