lib/libutil/_secure_path.3

   1 .\" Copyright (c) 1997 David Nugent <davidn@blaze.net.au>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, is permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice immediately at the beginning of the file, without modification,
   9 .\"    this list of conditions, and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
  14 .\"    is permitted provided this notation is included.
  15 .\" 4. Absolutely no warranty of function or purpose is made by the author
  16 .\"    David Nugent.
  17 .\" 5. Modifications may be freely made to this file providing the above
  18 .\"    conditions are met.
  19 .\"
  20 .\" $FreeBSD: src/lib/libutil/_secure_path.3,v 1.7.2.4 2002/03/19 01:49:54 dd Exp $
  21 .\" $DragonFly: src/lib/libutil/_secure_path.3,v 1.3 2006/02/17 19:35:07 swildner Exp $
  22 .\"
  23 .Dd May 2, 1997
  24 .Os
  25 .Dt _SECURE_PATH 3
  26 .Sh NAME
  27 .Nm _secure_path
  28 .Nd determine if a file appears to be secure
  29 .Sh LIBRARY
  30 .Lb libutil
  31 .Sh SYNOPSIS
  32 .In sys/types.h
  33 .In libutil.h
  34 .Ft int
  35 .Fn _secure_path "const char *path" "uid_t uid" "gid_t gid"
  36 .Sh DESCRIPTION
  37 This function does some basic security checking on a given path.
  38 It is intended to be used by processes running with root privileges
  39 in order to decide whether or not to trust the contents of a given
  40 file.
  41 It uses a method often used to detect system compromise.
  42 .Pp
  43 A file is considered
  44 .Sq secure
  45 if it meets the following conditions:
  46 .Bl -enum
  47 .It
  48 The file exists, and is a regular file (not a symlink, device
  49 special or named pipe, etc.),
  50 .It
  51 Is not world writable.
  52 .It
  53 Is owned by the given uid or uid 0, if uid is not -1,
  54 .It
  55 Is not group writable or it has group ownership by the given
  56 gid, if gid is not -1.
  57 .El
  58 .Sh RETURN VALUES
  59 This function returns zero if the file exists and may be
  60 considered secure, -2 if the file does not exist, and
  61 -1 otherwise to indicate a security failure.
  62 .Xr syslog 3
  63 is used to log any failure of this function, including the
  64 reason, at LOG_ERR priority.
  65 .Sh SEE ALSO
  66 .Xr lstat 2 ,
  67 .Xr syslog 3
  68 .Sh HISTORY
  69 Code from which this function was derived was contributed to the
  70 .Fx
  71 project by Berkeley Software Design, Inc.
  72 .Sh BUGS
  73 The checks carried out are rudimentary and no attempt is made
  74 to eliminate race conditions between use of this function and
  75 access to the file referenced.