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.4 2006/10/26 12:58:30 swildner Exp $
  37 .\"
  38 .Dd October 26, 2006
  39 .Dt SUSER 9
  40 .Os
  41 .Sh NAME
  42 .Nm suser ,
  43 .Nm suser_cred
  44 .Nd check for credentials for superuser privilege
  45 .Sh SYNOPSIS
  46 .In sys/param.h
  47 .In sys/proc.h
  48 .In sys/ucred.h
  49 .Ft int
  50 .Fn suser "struct thread *td"
  51 .Ft int
  52 .Fn suser_cred "struct ucred *cred" "int flags"
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 family of functions check if the credentials given include superuser privilege.
  57 .Pp
  58 The
  59 .Fn suser
  60 function is the most common, and should be used unless special
  61 circumstances dictate otherwise.
  62 The credential check is only necessary if the thread
  63 .Fa td
  64 is attached to a process.
  65 .Pp
  66 The
  67 .Nm suser_cred
  68 function should be used when the credentials to be checked are
  69 not the process' own, when there is no process or when superuser
  70 privilege should be extended to imprisoned roots.
  71 .Pp
  72 By default a process does not command superuser privilege if it has
  73 been imprisoned by the
  74 .Xr jail 2
  75 system call.
  76 There are cases however where this is appropriate and can be done by
  77 setting the
  78 .Dv PRISON_ROOT
  79 bit in the flags argument to the
  80 .Nm suser_cred
  81 function.
  82 It is important to review carefully in each case that
  83 this does not weaken the prison.
  84 Generally only where the action is protected by the
  85 .Xr chroot 2
  86 implicit in
  87 .Xr jail 2
  88 call should such privilege be granted.
  89 .Pp
  90 The
  91 .Fn suser
  92 and
  93 .Fn suser_cred
  94 functions note the fact that superuser powers have been used in the
  95 process structure of the process specified.
  96 Because part of their function is to notice
  97 whether superuser privilege have been used,
  98 the functions should only be called after other permission
  99 possibilities have been exhausted.
 100 .Sh RETURN VALUES
 101 The
 102 .Fn suser
 103 and
 104 .Fn suser_cred
 105 functions return
 106 .Li 0
 107 if the user has superuser privilege and
 108 .Er EPERM
 109 otherwise.
 110 This is the
 111 .Em reverse logic
 112 of some other implementations of
 113 .Nm
 114 in which a TRUE response indicates superuser powers.