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