util.subproj/rcmd.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)rcmd.3        8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/net/rcmd.3,v 1.12.2.7 2001/08/17 15:42:38 ru Exp $
  34 .\"
  35 .Dd March 3, 2000
  36 .Dt RCMD 3
  37 .Os
  38 .Sh NAME
  39 .Nm rcmd ,
  40 .Nm rresvport ,
  41 .Nm iruserok ,
  42 .Nm ruserok ,
  43 .Nm rcmd_af ,
  44 .Nm rresvport_af ,
  45 .Nm iruserok_sa
  46 .Nd routines for returning a stream to a remote command
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .Fd #include <unistd.h>
  51 .Ft int
  52 .Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
  53 .Ft int
  54 .Fn rresvport "int *port"
  55 .Ft int
  56 .Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser"
  57 .Ft int
  58 .Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser"
  59 .Ft int
  60 .Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
  61 .Ft int
  62 .Fn rresvport_af "int *port" "int af"
  63 .Ft int
  64 .Fn iruserok_sa "const void *addr" "int addrlen" "int superuser" "const char *ruser" "const char *luser"
  65 .Sh DESCRIPTION
  66 The
  67 .Fn rcmd
  68 function
  69 is used by the super-user to execute a command on
  70 a remote machine using an authentication scheme based
  71 on reserved port numbers.
  72 The
  73 .Fn rresvport
  74 function
  75 returns a descriptor to a socket
  76 with an address in the privileged port space.
  77 The
  78 .Fn ruserok
  79 function
  80 is used by servers
  81 to authenticate clients requesting service with
  82 .Fn rcmd .
  83 All three functions are present in the same file and are used
  84 by the
  85 .Xr rshd 8
  86 server (among others).
  87 .Pp
  88 The
  89 .Fn rcmd
  90 function
  91 looks up the host
  92 .Fa *ahost
  93 using
  94 .Xr gethostbyname 3 ,
  95 returning -1 if the host does not exist.
  96 Otherwise
  97 .Fa *ahost
  98 is set to the standard name of the host
  99 and a connection is established to a server
 100 residing at the well-known Internet port
 101 .Fa inport .
 102 .Pp
 103 If the connection succeeds,
 104 a socket in the Internet domain of type
 105 .Dv SOCK_STREAM
 106 is returned to the caller, and given to the remote
 107 command as
 108 .Em stdin
 109 and
 110 .Em stdout .
 111 If
 112 .Fa fd2p
 113 is non-zero, then an auxiliary channel to a control
 114 process will be set up, and a descriptor for it will be placed
 115 in
 116 .Fa *fd2p .
 117 The control process will return diagnostic
 118 output from the command (unit 2) on this channel, and will also
 119 accept bytes on this channel as being
 120 .Tn UNIX
 121 signal numbers, to be
 122 forwarded to the process group of the command.
 123 If
 124 .Fa fd2p
 125 is 0, then the
 126 .Em stderr
 127 (unit 2 of the remote
 128 command) will be made the same as the
 129 .Em stdout
 130 and no
 131 provision is made for sending arbitrary signals to the remote process,
 132 although you may be able to get its attention by using out-of-band data.
 133 .Pp
 134 The protocol is described in detail in
 135 .Xr rshd 8 .
 136 .Pp
 137 The
 138 .Fn rresvport
 139 function is used to obtain a socket to which an address with a Privileged
 140 Internet port is bound.
 141 This socket is suitable for use by
 142 .Fn rcmd
 143 and several other functions.
 144 Privileged Internet ports are those in the range 0 to 1023.
 145 Only the super-user is allowed to bind an address of this sort
 146 to a socket.
 147 .Pp
 148 The
 149 .Fn iruserok
 150 and
 151 .Fn ruserok
 152 functions take a remote host's IP address or name, as returned by the
 153 .Xr gethostbyname 3
 154 routines, two user names and a flag indicating whether the local user's
 155 name is that of the super-user.
 156 Then, if the user is
 157 .Em NOT
 158 the super-user, it checks the
 159 .Pa /etc/hosts.equiv
 160 file.
 161 If that lookup is not done, or is unsuccessful, the
 162 .Pa .rhosts
 163 in the local user's home directory is checked to see if the request for
 164 service is allowed.
 165 .Pp
 166 If this file does not exist, is not a regular file, is owned by anyone
 167 other than the user or the super-user, or is writable by anyone other
 168 than the owner, the check automatically fails.
 169 Zero is returned if the machine name is listed in the
 170 .Dq Pa hosts.equiv
 171 file, or the host and remote user name are found in the
 172 .Dq Pa .rhosts
 173 file; otherwise
 174 .Fn iruserok
 175 and
 176 .Fn ruserok
 177 return -1.
 178 If the local domain (as obtained from
 179 .Xr gethostname 3 )
 180 is the same as the remote domain, only the machine name need be specified.
 181 .Pp
 182 The
 183 .Fn iruserok
 184 function is strongly preferred for security reasons.
 185 It requires trusting the local DNS at most, while the
 186 .Fn ruserok
 187 function requires trusting the entire DNS, which can be spoofed.
 188 .Pp
 189 The functions with an
 190 .Dq Li _af
 191 or
 192 .Dq Li _sa
 193 suffix, i.e.,
 194 .Fn rcmd_af ,
 195 .Fn rresvport_af
 196 and
 197 .Fn iruserok_sa ,
 198 work the same as the corresponding functions without a
 199 suffix, except that they are capable of handling both IPv6 and IPv4 ports.
 200 .Pp
 201 The
 202 .Dq Li _af
 203 suffix means that the function has an additional
 204 .Fa af
 205 argument which is used to specify the address family,
 206 (see below).
 207 The
 208 .Fa af
 209 argument extension is implemented for functions
 210 that have no binary address argument.
 211 Instead, the
 212 .Fa af
 213 argument specifies which address family is desired.
 214 .Pp
 215 The
 216 .Dq Li _sa
 217 suffix means that the function has general socket address and
 218 length arguments.
 219 As the socket address is a protocol independent data structure,
 220 IPv4 and IPv6 socket address can be passed as desired.
 221 The
 222 .Fa sa
 223 argument extension is implemented for functions
 224 that pass a protocol dependent binary address argument.
 225 The argument needs to be replaced with a more general address structure
 226 to support multiple address families in a general way.
 227 .Pp
 228 The functions with neither an
 229 .Dq Li _af
 230 suffix nor an
 231 .Dq Li _sa
 232 suffix work for IPv4 only, except for
 233 .Fn ruserok
 234 which can handle both IPv6 and IPv4.
 235 To switch the address family, the
 236 .Fa af
 237 argument must be filled with
 238 .Dv AF_INET ,
 239 or
 240 .Dv AF_INET6 .
 241 For
 242 .Fn rcmd_af ,
 243 .Dv PF_UNSPEC
 244 is also allowed.
 245 .Sh DIAGNOSTICS
 246 The
 247 .Fn rcmd
 248 function
 249 returns a valid socket descriptor on success.
 250 It returns -1 on error and prints a diagnostic message
 251 on the standard error.
 252 .Pp
 253 The
 254 .Fn rresvport
 255 function
 256 returns a valid, bound socket descriptor on success.
 257 It returns -1 on error with the global value
 258 .Va errno
 259 set according to the reason for failure.
 260 The error code
 261 .Er EAGAIN
 262 is overloaded to mean ``All network ports in use.''
 263 .Sh SEE ALSO
 264 .Xr rlogin 1 ,
 265 .Xr rsh 1 ,
 266 .Xr intro 2 ,
 267 .Xr rexec 3 ,
 268 .Xr rexecd 8 ,
 269 .Xr rlogind 8 ,
 270 .Xr rshd 8
 271 .Pp
 272 .Rs
 273 .%A W. Stevens
 274 .%A M. Thomas
 275 .%T "Advanced Socket API for IPv6"
 276 .%O RFC2292
 277 .Re
 278 .Rs
 279 .%A W. Stevens
 280 .%A M. Thomas
 281 .%A E. Nordmark
 282 .%T "Advanced Socket API for IPv6"
 283 .%O draft-ietf-ipngwg-rfc2292bis-01.txt
 284 .Re
 285 .Sh HISTORY
 286 Most of these
 287 functions appeared in
 288 .Bx 4.2 .
 289 .Fn rresvport_af
 290 appeared in RFC2292, and was implemented by the WIDE project
 291 for the Hydrangea IPv6 protocol stack kit.
 292 .Fn rcmd_af
 293 appeared in draft-ietf-ipngwg-rfc2292bis-01.txt,
 294 and was implemented in the WIDE/KAME IPv6 protocol stack kit.
 295 .Fn iruserok_sa
 296 appeared in discussion on the IETF ipngwg mailing list,
 297 and was implemented in
 298 .Fx 4.0 .