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