chiark - git - mdw - checkpath/blob - checkpath.3

   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@distorted.org.uk).