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