mdw@git.distorted.org.uk Git - 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 "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).