share/man/man9/suser.9

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