.\" -*-nroff-*- .TH checkpath 3 "25 January 2003" "Local tools" .SH NAME checkpath \- library for examining path security .SH SYNOPSIS .nf .B "#include " .BI "int checkpath(const char *" path , .BI " const struct checkpath *" cp ");" .BI "int checkpath_addgid(struct checkpath *" cp ", gid_t " g ");" .BI "void checkpath_setuid(struct checkpath *" cp ");" .BI "int checkpath_setgid(struct checkpath *" cp ");" .BI "int checkpath_setgroups(struct checkpath *" cp ");" .BI "void checkpath_setids(struct checkpath *" cp ");" .fi .SH DESCRIPTION The .B checkpath function checks a path for security. It ensures that only acceptble users and groups can change the files or file contents accessible through the path. .PP The function is given a .I path to be checked, and a pointer .I cp to a parameter block of type .BR "struct checkpath" . It scans the path and returns a bitmask of problems that it found. It may also have invoked a caller-provided reporting function with details of the problems. .SS "The parameter structure" This structure contains the following members: .TP .B "uid_t cp_uid" The user running the check. Files and directories owned by .B root (uid 0) and by .B cp_uid are considered safe. .TP .B "gid_t cp_gid[NGROUPS_MAX + 1]" The groups of which the user is a member. Files whose groups are in this set may be considered safe, depending on the .B cp_what configuration. See below. .TP .B "int cp_gids" The number of gids in the .B cp_gid array. .TP .B "int cp_verbose" The verbosity level. Messages are only given to the reporting function if their verbosity level is less than or equal to this setting. As a guide, unexpected errors (e.g., nonexistent files) have level 0, security concerns about the path have level 1, and other details have levels 2 and above. The recommended value is 1. .TP .B "unsigned cp_what" A bitmask of flags determining what conditions are considered problems, and other behaviour. See below. .TP .B "void (*cp_report)(...)" The reporting function. See below. .TP .B "void *cp_arg" An argument to be passed to the reporting function .BR cp_report . .PP The members .BR cp_uid , .B cp_gid and .B cp_gids can be set up to reflect the current user and group memberships by calling .B checkpath_setids passing the address of the structure to fill in; this overwrites the previous contents of the .BR cp_uid , .BR cp_gid , and .BR cp_gids members. Alternatively, the functions .BR checkpath_setuid , .BR checkpath_setgid , and .B checkpath_setgroups can be called to do the job in stages. The .B checkpath_setuid function simply stores the process's real uid in .BR cp_uid . The .B checkpath_setgid and .B checkpath_setgroups functions store respectively the process's real gid and supplementary gids in the .B cp_gid array; they avoid inserting duplicate entries; they return 0 on success or \-1 if the table would overflow; they assume that the table is properly set up (minimally, just set .BR "cp_gids = 0" ). They use a utility function .B checkpath_addgid to do their work; it takes a pointer to a .B struct checkpath and a gid, and again returns 0 on success or \-1 if overflow would occur. .SS "The cp_what flags" The .B cp_what flags are as follows. .TP .B CP_ERROR Some kind of operating system error occurred while checking the path. .TP .B CP_WRWORLD A path element is world writable. .TP .B CP_WRGRP A path element is group-writable. .TP .B CP_WROTHGRP A path element is group-writable, and its group is not listed in .BR cp_gid . .TP .B CP_WROTHUSR A path element is owned by another user. .TP .B CP_SYMLINK Report traversal of a symbolic link while checking the path. .TP .B CP_REPORT Format a user-readable message string when reporting problems. .TP .B CP_STICKYOK Don't complain if the object designated by the path is a sticky directory, as long as the owner is trustworthy (i.e., either .B root or .BR cp_uid ). This is useful when testing candidate temporary directories for suitability. .PP The flags .BR CP_ERROR , .BR CP_WRWORLD , .BR CP_WRGRP , .BR CP_WROTHGRP , and .B CP_WROTHUSR are collectively the .I problem flags. The mask .B CP_PROBLEMS has only these bits set. A problem is reported (and returned) only if its bit is set in the .B cp_what structure member. Note that it's possible that a problem might fit into multiple categories, e.g., a group-writable directory might be reported as .B CP_WRGRP or .BR CP_WROTHGRP ; in this case, the most specific problem is used (in this case .BR CP_WROTHGRP ). .SS "The reporting function" The reporting function is passed the following arguments: .TP .BI "unsigned " what A flag inidicating the kind of notification this is. It will be a problem flag or .BR CP_SYMLINK . .TP .BI "int " verb The verbosity level of this message. .TP .BI "const char *" path The full pathname of the object which caused this report to be issued. The pathname will not contain symbolic links (except as the last element, and then only if this is a .B CP_SYMLINK notification). .TP .BI "const char *" msg A human-readable message describing this notification in detail. This is only generated if .B CP_REPORT is set in the .B cp_what flags. .TP .BI "void *" p The .B cp_arg member of the parameter structure, provided as a context pointer for the reporting function. .SH BUGS None known. .SH SEE ALSO .BR chkpath (1), .BR tmpdir (1). .SH AUTHOR Mark Wooding (mdw@nsict.org).