share/man/man9/suser.9

   1 .\"
   2 .\" Copyright (c) 2004 Hiten Pandya <hmp@dragonflybsd.org>
   3 .\" Copyright (c) 1996 Julian R Elischer
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed by Kenneth Stailey.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed for the FreeBSD Project
  19 .\"     by Julian R Elischer
  20 .\" 4. The name of the author may not be used to endorse or promote products
  21 .\"    derived from this software without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  24 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  25 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  26 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  27 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  30 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  31 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\" $FreeBSD: src/share/man/man9/suser.9,v 1.9.2.5 2001/12/17 11:30:19 ru Exp $
  36 .\" $DragonFly: src/share/man/man9/suser.9,v 1.3 2004/05/10 13:00:37 hmp Exp $
  37 .\"
  38 .Dd May 10, 2004
  39 .Dt SUSER 9
  40 .Os
  41 .Sh NAME
  42 .Nm suser ,
  43 .Nm suser_cred ,
  44 .Nm suser_proc
  45 .Nd check for credentials for superuser privilege
  46 .Sh SYNOPSIS
  47 .In sys/param.h
  48 .In sys/proc.h
  49 .In sys/ucred.h
  50 .Ft int
  51 .Fn suser "struct thread *td"
  52 .Ft int
  53 .Fn suser_cred "struct ucred *cred" "int flags"
  54 .Ft int
  55 .Fn suser_proc "struct proc *p"
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 family of functions check if the credentials given include superuser privilege.
  60 .Pp
  61 The
  62 .Fn suser
  63 function is the most common, and should be used unless special
  64 circumstances dictate otherwise.
  65 The credential check is only necessary if the thread
  66 .Fa td
  67 is attached to a process.
  68 .Pp
  69 The
  70 .Nm suser_cred
  71 function should be used when the credentials to be checked are
  72 not the process' own, when there is no process or when superuser
  73 privilege should be extended to imprisoned roots.
  74 .Pp
  75 The
  76 .Fn suser_proc
  77 function is used when the credentials to be checked are of a
  78 different process.
  79 .Pp
  80 By default a process does not command superuser privilege if it has
  81 been imprisoned by the
  82 .Xr jail 2
  83 system call.
  84 There are cases however where this is appropriate and can be done by
  85 setting the
  86 .Dv PRISON_ROOT
  87 bit in the flags argument to the
  88 .Nm suser_cred
  89 function.
  90 It is important to review carefully in each case that
  91 this does not weaken the prison.
  92 Generally only where the action is protected by the
  93 .Xr chroot 2
  94 implicit in
  95 .Xr jail 2
  96 call should such privilege be granted.
  97 .Pp
  98 The
  99 .Fn suser ,
 100 .Fn suser_cred
 101 and
 102 .Fn suser_proc
 103 functions note the fact that superuser powers have been used in the
 104 process structure of the process specified.
 105 Because part of their function is to notice
 106 whether superuser privilege have been used,
 107 the functions should only be called after other permission
 108 possibilities have been exhausted.
 109 .Sh RETURN VALUES
 110 The
 111 .Fn suser ,
 112 .Fn suser_cred
 113 and
 114 .Fn suser_proc
 115 functions return
 116 .Li 0
 117 if the user has superuser privilege and
 118 .Er EPERM
 119 otherwise.
 120 This is the
 121 .Em reverse logic
 122 of some other implementations of
 123 .Nm
 124 in which a TRUE response indicates superuser powers.